Table of Contents

Compiling the examples for Linux

This page will tell you how to get some examples compiling under Linux. I'm using the latest Ubuntu as of June 8th, 2023 for this test. The binaries should run both under the desktop, or from bash without the desktop environment running.

The examples may have weird window sizes and in non-desktop environments things like mouse cursor movement won't work.

Grabbing Proton SDK

First, let's install some tools and libraries we need in case you don't have them.

sudo apt install git build-essential libffi-dev zlib1g-dev libssl-dev

Now we'll grab the ProtonSDK source tree from git.

cd ~
git clone https://github.com/SethRobinson/proton.git

Projects you compile are put INTO the Proton directory. Sort of weird, but the end result is all paths and dependencies are relative when possible which make compiling for many platforms easier. Nothing to setup.

There is no lib/dll to make for Proton, the .cpp files are just used directly in the projects. There is however a tool called RTPack that is used to build fonts (.rtfont files), images (.rttex files, don't have to use them though), and general purpose compression. (one gotcha: compressed files use the .rtpack extension EXCEPT .rtfont/.rttex, those keep the same extension. Proton's file handling automatically decompresses things when needed)

Let's make the RTPack tool now.

cd proton/RTPack/linux
sh linux_compile.sh

Hopefully that worked.

Note: By default, RTPack is compiled with the RT_NO_PVR flag, so support for a weird texture format called PVRTC isn't included. If you really want that, you an go download the PVRTC libs. (more info here), but you probably don't need it unless you're trying to optimize an iOS game or something. It was a big thing in 2010, I don't know about now.

Compiling and running RTBareBones

This is the process I follow when compiling the examples. You may vary this to your needs if you want since cmake is quite flexible in what it can do. But it's a safe bet to follow these quidelines if you are not yet too familiar with cmake.

Generally with linux stuff, you make a “build” directory and do your stuff there. We do that too, but we do it from the <project name>/linux/build which is slightly different. This is a side effect of linux related things being relegated to the linux dir due to the originally window-centric approach of Proton.

Before building RTBareBones, your system will need some sdl2 libs, this helps with video and graphics, something RTPack didn't need. Do this:

sudo apt-get install libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev

Before we compile it, we need to build the media. This is where we build fonts, and convert jpg/pngs etc into more optimized formats. (this doesn't stop you from loading jpgs/pngs directly if you want, but that's just how these examples were built)

cd ~/proton/RTBareBones/media
sh update_media.sh

Now we need to compile RTBareBones, just do:

cd ~/proton/RTBareBones/linux
sh linux_compile.sh

(If you look at linux_compile.sh, it creates the build dir, does the cmake and make stuff, then copies the resulting binary to ../bin, which is where you should run it from. (../bin is the standard location to put binaries in Proton SDK and where resources like jpgs/sounds are put)

If the build finishes without errors you'll end up with a binary called RTBareBones in the ../bin directory.

To try it:

cd ../bin
./RTBareBones

You should see a spinning triangle and some font stretching effects.

Compiling and running the other examples

The compilation process for the other examples is exactly the same that what was explained for RTBareBones above.

But in addition the other examples than RTBareBones need resources to be built as explained here: Compiling RTSimpleApp.

To do this in linux using RTPack, you need to move into your projects media directory and run build_media.sh, which itself runs RTPack/linux/build_media.sh to do the work.

Let's build RTSimpleApp, then build its media:

cd RTSimpleApp/linux
sh linux_compile.sh
cd ../media
sh build_media.sh
cd ../bin
./RTSimpleApp

If that worked, the final stuff (.rtfont and .rttex and .rtpack files probably) will be copied into ../bin/interface, and you'll run the app.

How update_media.sh works

The resource building script goes to the subdirectories of the media directory and converts fonts and images to the Proton format. It uses a configuration file called texture_conversion_flags.txt that contains options for converting the images. The examples' media directories already contain these configuration files but if you'll build your own applications and want to use this system make sure you have these files in place.

Debug builds

The process described above for building the examples produces a binary that can be called a release build. We didn't give any special instructions for cmake so it chose the default settings. Especially the binary doesn't contain any debug symbols so it's not really suitable for a debugger. Luckily doing debug builds with cmake is quite easy.

Let's use the RTBareBones as an example. This is one place where the out-of-source builds used above come handy. You already have a release build made to a directory RTBareBones/linux/build. You can let the release build be there and do a debug build to another directory like this:

cd RTBareBones/linux
mkdir build-debug
cd build-debug
cmake -DCMAKE_BUILD_TYPE=Debug ..
make

Now you have the debug and release builds in separate subdirectories and they don't mess with each other. You can off course have more subdirectories to different kinds of builds as you desire.

Building

You basically only have to run cmake manually once per build directory. After that you can just run make. If the CMakeLists.txt file has been changed it is noticed by the build scripts and cmake is run automatically with the same parameters as it was run the first time.

IDEs

I've gotten things to work ok with VScode, I use it remotely on my Windows machine and ssh into the linux box. I set the project dir to “proton/RTBareBones” for example, and with the CMake Tools active I can specify the linux/CMakeLists.txt file to build and debug with.

The only problem is I can't get breakpoints in ../proton/shared files to hit, even though I've added the folder to the project and played with source mapping, hrmph.