30 May 14
Aequitas

So you want to make a linux build with Unity

So maybe you’re like me, you’ve used Linux before, but it just wasn’t for you. That’s fine, everyone has their own tastes. But now you’ve got a game made in Unity, and some portion of your community is asking you to “Please port to Linux! It’s easy! Unity will do it for you!”

Well … yes and no. Getting Unity to output 32 and 64-bit executables for Linux is easy enough, but there’s a fair amount of work you’re going to have to do to get things running for your Linux users.

Now, to those very knowledgeable Linux humans reading this, please don’t take offense. This is the view of a Windows user trying to make the life of other game devs easier AND help put more games on the OS you love. If any of the info I present is wrong, feel free to correct me, but please make sure you do it in a way that is useful to someone who is not used to working in Linux.

1) You’re going to need to test in Linux
Luckily, this doesn’t mean you need to wipe an entire machine and start from scratch. Linux allows for a Live Disk to be created on a USB stick, meaning you can run it straight off the USB drive.

I used Universal USB Installer, and a 32-bit version of Ubuntu, one of the most popular Linux builds. Other Linux builds can be made into Live Disks too, you might need to download the ones people seem to be having the most problems with.

2) Executable file permissions
Once you’re in Linux, you should try running your game, either by navigating to it and double clicking on the .x86 (or .x86_64) file that Unity created for you, or opening a terminal, navigating to your game directory and running it with:

./YourGame.x86

This will probably fail.

The reason for this is that the files need execution permission. Just right click on them, select properties, go to the permissions tab, and tick the “allow execution” box, or navigate to them in the terminal, and use:

chmod +x YourGame.x86

You can save yourself some time in the future by keeping these executables somewhere when you make new builds, and just copy them over. This works because Unity doesn’t actually build a unique executable for each game, that’s all handled by the files in the YourGame_data directory.

3) Shell Script
Now you may be lucky, and your game runs from this point onwards with no hitches … or maybe not. There’s a good chance that you’re going to run into some of the problems I’ve laid out below, and to get around most of them, you’re going to need a shell script.

A shell script is a bit of code that you can easily run in Linux to do stuff for you.

So here’s a basic script that will launch your executable. Call it YourGame.sh

#!/bin/sh

cd "$(dirname "$0")"

exec ./YourGame.x86 "$@"

that cd on line 3 is in case someone runs the script from a different directory to where your game is located.

4) 32-bit vs 64-bit
You’re going to find that some people are using a 32-bit version of Linux, and some are using 64-bit. Now, 64-bit *can* run 32-bit executables (though not the other way around), but you’re likely to find that it doesn’t come with the 32-bit libraries it may need.

If you’re not using external libraries, or your external libraries come in both 32 and 64-bit flavours, you can make life a little easier by including an OS bit check in your shell script.

if [ `getconf LONG_BIT` = "64" ]
then
    exec ./YourGame.x86_64 "$@"
else
    exec ./YourGame.x86 "$@"
fi

5) Including libs
But what if you are using external libraries? What if those libraries only come in 32-bit?

Both problems can be solved by using the LD_LIBRARY_PATH environment variable. This lets you specify a path to check for libraries before the system checks it’s standard libraries.

export LD_LIBRARY_PATH="./YourGame_Data/lib:$LD_LIBRARY_PATH"

Now just add your external libraries to a new lib folder in your game’s data folder, and they will be picked up. Though if you only got the 32-bit version, you may still have the problem of 64-bit systems not having some standard libs.

You can include those in this folder too, you just need to figure out which ones you need. Luckily, someone has done this for us! So you can copy these files from a 32-bit Linux install, and the 32-bit executable should run on 64-bit systems (though you’ll probably want to take out the OS bit check since you only want to call the 32-bit executable)

6) Language
A week or so after launching, some users were having errors show up when trying to handle files or file paths. After some investigation, one of them figured out that it had to do with the OS language setting. While this might not affect your game, it probably won’t hurt to include this in your shell script. Just make sure you test it.

export LANG=en

7) Install script
If you’re distributing your game via a store that just pops it into a zip file and ships it out there, you’ll probably want a way that makes it easy for your users to play it. One of our users suggested this script which you can ship alongside you game. It will make a desktop icon for your game, and link it up to run your shell script.

8) Putting it all together
Just in case this was all a bit confusing, here’s a look at what a shell script might look like at the end:

#!/bin/sh

cd "$(dirname "$0")"

export LANG=en

if [ `getconf LONG_BIT` = "64" ]
then
    export LD_LIBRARY_PATH="./YourGame_Data/lib64:$LD_LIBRARY_PATH"
    exec ./YourGame.x86_64 "$@"
else
    export LD_LIBRARY_PATH="./YourGame_Data/lib32:$LD_LIBRARY_PATH"
    exec ./YourGame.x86 "$@"
fi

9) Support
Once you release your game on Linux, people will have problems. In fact, you’ll probably see a disproportionate number of problems compared to releasing for other OSes. The important part here is not to panic: Linux is very much OS Hard Mode and almost every Linux user has their own unique setup that will break things in fantastically non-reproducible ways. Thankfully Linux users are mostly okay with this and will often put in a lot of work to solve issues, they’ll also tend to post the solutions they come up with, so make sure you’ve given them somewhere to do that!

Most of your problems will be caused by missing libraries or driver problems due to unique hardware configurations. For instance: We discovered that the latest NVIDIA drivers available for SuSe systems had simply turned off OpenGL support on some people’s machines, there’s literally nothing you as a developer can do about that. The trick is to stay calm and try to give your Linux players as much accurate information as possible – because they’re usually quite used to troubleshooting, they’ll tend to jump to wrong conclusions because they don’t know how your game is structured or what it might be doing under the hood.

10) Good Luck!
Hopefully this helps other Unity developers who’re looking at porting to Linux but have no idea where to start. If anyone has other common solutions to similar problems with the porting process, let us know in the forum comments!


  11 comments 

Copyright © 2014 QCF Design
Powered by WordPress, theme based on one from Themelab.com