Created Jun 17, 2016

A week ago I was CC'd in on a thread about Linux packaging, and how to avoid doing it the wrong way (i.e. RPM, Deb, etc.). I've always used MojoSetup and I've never forced distributions to do any additional work, but this is still a new concept to a lot of people. Additionally, Amos suggested that I expand on Itch's FNA appendix, so here's a guide on how I package my games.

This is a bit of an expansion on my MAGFest 2016 presentation, which you can find here:

On any operating system you should always assume one thing: Absolutely none of your game's dependencies will be on the system except for the C runtime and a graphics driver (hopefully it's a new one, but that's another story). For whatever reason this surprises a lot of people, particularly Windows developers that already do this on Windows! This may be the result of people discovering things like apt and dnf, where Linux users can grab software via repositories and not have to pull in a giant blob of things from the web whenever they do clean installs, or what have you.

The first mistake you can make is thinking that you need to integrate the package manager into your game.

The software you grab from a repository is NOT the same thing as what you grab from a website! These repositories fulfill a very important role, and it actually has very little to do with convenience. They're actually doing something much more important: ensuring compatibility across the entire system and everything that might run on it. The way this is done is by self-compiling everything:

... they're not grabbing a blob from the Mono project website, they're pulling the source in and building against Fedora's system libraries, which were also self-built, and then building everything that depends on Mono against the new version, all with an ungodly amount of checks, tests, and all sorts of things that make build engineers sweat with joy.

Your game is not doing any of that, and it's certainly not doing it for every single distribution. This is likely because A: your game is proprietary, B: you probably just want to type make once and be done with it like an Earth-dwelling being, and C: you don't even have a grasp of just how many distributions are out there, and that's just limiting it to the ones that exist today that will be running your game.

Sounds like an insane ecosystem to support, but guess what: Just treat Linux deps like you do Windows deps and all of this goes away! With this in mind, let's look at an example.

-lGL and -lGLU are pretty self-explanatory; obviously you don't need to ship OpenGL drivers, so you can skip those outright. But SDL2, GLEW, OpenAL, and Vorbisfile are definitely DLLs you would ship on Windows (well, maybe you statically link GLEW, but you get the idea).

But what's all that other crap up there? Even after trimming down our stuff, we're left with this:

So along with Vorbisfile we need to ship Ogg and Vorbis too. Big surprise, right? Basically anything that's not a standard runtime lib and not something that was needed by the driver needs to go into your game. There are very few exceptions to this rule - for example, I'm pretty sure a Linux machine without zlib is a work of fiction at this point. But libpng, which uses zlib, should probably be included with your game due to the various versions of that lib (1.2, 1.5, etc.).

At the end of the day, that giant ldd we started with actually looks like this in the official shipping version of Super Hexagon:

This all might seem complicated, but keep in mind that this is only as complicated as your dependency tree is. If you use libraries that are also conscious of this you'll be fine, but not everyone is like this. So unfortunately, all of you using stuff like SFML or even Chromium are in for a real treat:

If you really hated reading this and want to avoid doing anything like this at all costs, your solution is to simply calm down on the dependency tree. Use OS portability libs like SDL which only depend on the C runtime (or in the case of Windows, not even that). Use SDL_GL_GetProcAddress instead of linking to libGL directly (for that matter, don't use GLU or GLEW). Use stb_image or LodePNG instead of linking to libjpeg, libpng, etc. Use something like stb_vorbis instead of libvorbisfile. Don't use GTK/Qt/wx at all. You can even find libs like miniz which can replace seemingly tiny dependencies like zlib! These are really tiny things you can do to get your dependency tree looking sparkling clean without having to do any real work at all, and it makes your game super portable as well.

Now that we know what files we need to ship, where do we put them? Is it just like throwing DLLs next to the EXE?

Linux library paths are a little bit strange, but this can work to our advantage. Odds are you're shipping both 32-bit and 64-bit, and you probably don't want to make 2 packages just for each architecture. RPM/Deb might force you to do this, but we're better than that. We can bundle 32/64-bit together at once simply by using an executable script instead of directly launching the executable binary. It'll look something like this:

And that's it! We move to the location of the game, determine which architecture to pick, and add the real executable folder to the library search path before launching the binary.

There is only one thing you must be careful about: If you're doing most of your deployment from Windows, BE SURE that you did not save this script with Windows line endings! Windows is fantastically stupid and uses '\r\n' as a new line instead of just '\n', and this will rightfully confuse the system when trying to read the script. Very often I get reports from FNA developers that miss this and as a result, none of their players can play the game.

From here you're totally done putting the game together; this would be exactly what goes into your SteamPipe build folder, and you could throw this into a .tar.gz or .tar.bz2 file and be done with it. But we want an installer, right?

Finally we can talk about MojoSetup, which is probably a MUCH smaller part of packaging than you thought. Here's how it works: Grab this archive here:

Extract it somewhere, navigate to the location in a terminal, and run this:

./build.sh examplegame

Congratulations, you just made a MojoSetup package. Seriously, that's it. Run ./examplegame-installer and check it out!

What you're looking at is a self-extracting zipfile (try it: unzip examplegame-installer) with both graphical and command-line interfaces, which allow users to install wherever they have permission to write while NEVER touching the system's package database, and it will automatically generate local desktop icons and an uninstaller that never leaves a footprint, while also prominently showing them the README right at the beginning of the install process.

And you probably wanted to ship a .deb file. Ha ha.

Getting this to work with your game is as trivial as just ripping off the examplegame/ folder. Simply edit the files for the needs of your game's title, description, etc. and copy your game folder into data/, and your packaging environment is complete.

The two files that are notably important are the example FEZ.bmp and Linux.README. For that particular bmp, you can use PNG if you want; it just needs to be large enough to work as a high-resolution desktop icon (which you should already have a VERY large version of if you ship for the Mac already). The Linux.README can have whatever you like inside, but that's the format that I've always used for my games.

From there, just upload the package and users can download your game, installing or unzipping as they please, and you'll never have to fight the distro's package manager to get users started. If you ship as often as I do, this matters a LOT. More importantly, being able to keep the build environment static is important too - having to do anything more than copying data and running ./build.sh becomes a HUGE pain when you have a large library of games to maintain over a period of many MANY years (and counting). Do whatever you can to keep your packaging process small!

MojoSetup's been a standard for myself and for many long-time Linux game developers - its roots go back to the late 1990s and Loki Software! I hope that it will be your standard as well.

(*) - At one point it was a tradition to ship with libstdc++ due to horrible ABI incompatibilities, but this appears to have gotten less horrible over the last few years, and some distributors like Valve will actually recommend NOT shipping with it.

This comment has been minimized.

At one point it was a tradition to ship with libstdc++ due to horrible ABI incompatibilities, but this appears to have gotten less horrible over the last few years, and some distributors like Valve will actually recommend NOT shipping with it.

Ummh... Valve actually ships libstdc++ in the steam runtime, and it's caused a bit of incompatibility (because the free graphics drivers use it, and you can't have two of those in the same process at the same time IIRC). See ValveSoftware/steam-runtime#13.

https://github.com/probonopd/linuxdeployqt (not just for Qt thanks to the -bundle-non-qt-libs switch - does much of the ldd magic you are talking about automatically, and removes the need for LD_LIBRARY_PATH by setting the rpath)

This comment has been minimized.

Thank you for writing this Ethan. I'm not a programmer , so I'm fairly inexperienced at this ... so ... I've flipped through mojosetup web pages and I wonder - is it possible to make an installer with it that would ask user for password (grant "sudoer" permissions) when trying to install to a folder that needs additional permissions? I'm thinking about packaging some assets for an app in a way that wouldn't require the user to hassle with command line, choosing the right folder , sudo-ing and so on (and sadly with default setup most people seem to have some files will need to go to /usr/share/appname/assets).