Compilation instructions

This page explains how to compile and install the engine from the source code.

Downloading the code

The engine and editor code is hosted on Gitlab. To download the code, clone the repository. See the source code page for more information.

# git clone

The C++ source code is located in the src/ and include/ directories. It is licensed under GPL v3.

Compiling and installing the engine

The build process uses CMake for the engine. CMake allows to compile the project on any OS. On Unix, it generates the appropriate makefiles; on Windows, it can generate a project for most environments, including Visual C++, Code::Blocks and MinGW. You can also compile the engine without CMake (by creating a project from the sources with your IDE and link with the libraries listed below).

To compile Solarus (the engine), you need a C++ compiler with support of C++11. Solarus compiles fine with gcc 4.8.1 or greater and clang 3.4 or greater.

The following libraries are required to compile and execute Solarus:

  • SDL2 (2.0.6 or greater)
  • SDL2main
  • SDL2_image
  • SDL2_ttf
  • OpenGL or OpenGL ES
  • OpenAL
  • Vorbisfile
  • Ogg
  • Modplug ( or greater)
  • Lua 5.1 or LuaJIT 2.0 (LuaJIT is recommended)
  • Physfs
  • Qt5 (only if you build the Solarus GUI too)

Note that another library is directly embedded in the source code: snes_spc, an SPC music decoding library.

Linux developers

Install the corresponding packages. With a recent Ubuntu or Debian, this might look like:

# apt-get install libsdl2-dev libsdl2-image-dev libsdl2-ttf-dev libluajit-5.1-dev libphysfs-dev libopenal-dev libmodplug-dev libvorbis-dev qtbase5-dev qttools5-dev qttools5-dev-tools libglm-dev

Compilation instructions

To compile solarus (the engine) with cmake, go to the solarus directory and type:

$ mkdir build
$ cd build
$ cmake ..

This generates the appropriate Makefiles for your system.

Then you can compile the engine, using 4 parallel threads in this example:

$ make

Executing a quest

Then, when you’re in the build directory, to execute a quest, type:

$ ./solarus_run path/to/your/quest

The argument must be a directory containing the “data” subdirectory of your quest, or containing the “data.solarus” or “” archive of your quest.


Optionally, to be able to run the engine from anywhere, install the engine with (as root):
# sudo make install

This installs the solarus binary in /usr/local/bin (assuming that the install directory is /usr/local).

Changing the installation directory

You may want to install solarus in another directory (e.g. so that no root access is necessary). You can specify this directory as a parameter of cmake:

$ mkdir build
$ cd build
$ cmake -DCMAKE_INSTALL_PREFIX=/home/your_directory ..
$ make
$ make install

This installs the solarus executable as described above, with the /usr/local prefix replaced by the one you specified.

More about the quest path

There are several ways to make the engine find the data of a quest. If the quest path command-line argument is set, then the engine looks into the directory specified (and expects a “data” subdirectory or a “data.solarus” zip archive).

If the command-line argument is not specified, the preprocessor constant SOLARUS_DEFAULT_QUEST is used. The SOLARUS_DEFAULT_QUEST constant can be configured from your cmake command by using:

$ cmake -DDEFAULT_QUEST=/path/to/your/quest .

Finally, if the SOLARUS_DEFAULT_QUEST constant is not set either, then the engine looks into the current directory.

This SOLARUS_DEFAULT_QUEST constant may be used if you want the engine to launch a default quest when it is called without command-line arguments. You can still launch another quest by using the command-line argument, which overwrites the SOLARUS_DEFAULT_QUEST constant.

Windows developers

You can use cmake and compile solarus with MinGW32. However, I usually compile it with Code::Blocks (and also MinGW32), without using CMake.

In both cases, the hardest part is to install the libraries because under Windows, you have to download all of them one by one (in their development version) and install the headers and the libraries. It’s a nightmare.

Here is my procedure with Code::Blocks and MinGW32:

First, the nightmare part: for each library in SDL2, SDL2_image, SDL2_ttf, lua5.1 or LuaJIT (recommended), OpenAL, physfs, modplug, ogg, vorbis, vorbisfile:

  • Download the development version of the library on its website.
  • Install the header files in C:\Program Files\CodeBlocks\mingw32\include
  • Install the compiled libraries (.a, .lib or even .dll) in C:\Program Files\CodeBlocks\MinGW\lib. If they don’t provide compiled libraries, compile it yourself or use the one I have already compiled (for Windows 32 bit) in the libraries/win32/ directory of the solarus git repository.

Now, the easy part with to Code::Blocks (it is also possible with cmake):

  • Create a C++ project.
  • Add recursively the files from include and src to your project.
  • In Build options > Compiler settings > defines, for the Release mode, add NDEBUG (very important for performance).
  • Also in Build options, link to the following libraries in this order: mingw32, SDL2main, SDL2, SDL2_image, SDL2_ttf, lua5.1, physfs, OpenAL32, modplug, vorbis, vorbisfile. Some of them may be specified as relative file names of their DLL (in particular the ones I provide in the git repository). You are supposed to install the other ones in the compiler’s environment (see the “nightmare” part above).
  • Build the game with Code::Blocks. I recommend to compile in Release mode for performance (because NDEBUG is set) and for executable size, unless you are a developer.
  • The build error messages will tell you which headers and libraries are missing (it’s hard to get them right in one try!).

If you compile with Visual C++, it should also work. You may need to add the \Za flag to make Visual C++ respect the C++ standards: otherwise, you may have a linker error with Music.h.

Mac OS X developers

The install.txt file contains more information about the Mac OS X compilation.


  1. with the following:

    cmake -DCMAKE_BUILD_TYPE=Debug .

    I got the following error on my mac:

    solarus/include/DebugKeys.h:35:15: error: private field ‘main_loop’ is not used [-Werror,-Wunused-private-field]
    MainLoop& main_loop; /**< the Solarus main loop object */
    1 error generated.

    ps. Building latest solarus from github on mac machine is so tough.

  2. Hello,

    I have an issue when compiling, during the “make”:

    solarus-1.0.1/src/Savegame.cpp: In member function ‘void Savegame::load()’:
    solarus-1.0.1/src/Savegame.cpp:202:22: erreur: ‘lua_setfenv’ was not declared in this scope
    lua_setfenv(l, -2);

    Any hint to pass through this error maybe?
    Thanks a lot 🙂

  3. … and sorry to not have mentionned this on the previous post, but i’m on Manjaro (=Arch linux) and when trying to find a solution, i have found in the comments on the solarus arch repositories (, this entry… if it can help:
    pacman -Q lua sdl_image sdl_ttf physfs openal libvorbis libmodplug cmake zip
    gcc-multilib gcc-libs-multilib gcc gcc-libs

    lua 5.2.2-1
    sdl_image 1.2.12-3
    sdl_ttf 2.0.11-2
    physfs 2.0.3-1
    openal 1.15.1-1
    libvorbis 1.3.3-1
    zip 3.0-3
    Erreur: le paquet ‘gcc-multilib’ n’a pas été trouvé.
    Erreur: le paquet ‘gcc-libs-multilib’ n’a pas été trouvé.
    gcc 4.8.0-4
    gcc-libs 4.8.0-4

    …however if I try to install gcc-multilib, it is in conflict with gcc…. something wrong there maybe?

  4. Thanks for your reply, i understand the problem now.

    I’ve checked my packages, and in fact I have lua 5.2 and lua 5.1.5-3 installed (via the package lua51). However i cannot simply remove lua 5.2 as it is needed by some other programs.

    I’ve searched on the web without much success about a way to force cmake to use lua 5.1… do you know maybe a way to do it please?

  5. Solarus cmake file is correct, it clearly requires Lua 5.1. So the problem comes from CMake or from you distribution. Are 5.1 and 5.2 Lua headers in clearly separate directories? Like /usr/include/lua5.1 and /usr/include/lua5.2?

    If yes, what is your version of CMake? Can you try to upgrade it? Maybe the most recent versions find more correctly Lua 5.1 when 5.2 is also installed.

    If not, you can always tell CMake manually where Lua 5.1 is, with something like:
    cmake -DLUA_INCLUDE_DIR=/usr/include/lua5.1 -DLUA_LIBRARY=/usr/lib/ . (Note this kind of manual cmake configuration allows people to use any library without even installing it.)

  6. Thanks for your help, this time i’ve managed to compile Solarus!

    I understood the solarus cmake file was ok, but i was speaking to force the command cmake to use lua51. Concerning the files installed, I have found the headers in /usr/include/lua5.1 (but not in this place for 5.2…anyway this one was the one i wanted for compilation).
    My version of cmake was already the last ( in my repositories, so i tried to use the args you give, and voila, it works 🙂

    Thanks again for your dedication and your great work on solarus!

  7. I’ve done the nigh impossible and successfully compiled solarus on windows with visual studio 2012.

    When I run solarus with the Zelda Mystery of Solarus DX data file, it says:
    Opening quest: ‘.’
    Fatal: Data File languages/languages.dat does not exist

  8. Well i got it working with that actual github project data files, now I gotta debug what looks like a music problem.

    Where is the appropriate place to find the modplug source code for windows development?

  9. Ok I commented out one line and it appears to be working. the windows build seems to be a bit buggy in some areas. i tried running your downloaded client and it terminates itself abnormally. oh well. Ok, peace!

  10. @abombthecoder: if you compiled solarus from the master git branch, you need the ZSDX from git as well (and you will see that it is quite unstable because not fully tested yet with solarus 1.0).

    If have a fork of modplug if you want to try to compile it with visual studio:

    Which downloaded version did you use? Anyway, you need to have a data directory or a data.solarus archive so that it runs correctly.

  11. I downloaded ZSDX 1.5.2 with the windows installer, it crashes pretty quickly.

    I am running ZSDK from git and it’s all working great. I do notice a lot of bugs though, I’m trying to set up a linux VM to compare the two so I can verify it’s not just a windows problem.

    It’d be great if you can lurk at a IRC channel or set one up somewhere so we can talk about the development of this.

  12. On my Ubuntu system, I cloned the solarus and zsdx repos. Everything compiled (release version) and installed fine, but ZSDX crashes as soon as I pick up the heart container in the rupee shop (from the third mini-game). I get the error:

    Fatal: Cannot find item with name ”
    Aborted (core dumped)

    I ran the command: grep -R -n “Cannot find item with name” .*
    It found that this error is coming from line 426 of Equipment.cpp.

    I’ve never used lua before, but the file ‘2.dat’ does contain an entry for a heart container. I’m guessing something is causing the item to not bind correctly to the data.

    I’m going to try to create a debug build for solarus and run this through GDB. This will be a good excuse to teach myself lua. =)

  13. Just wondering since the Zelda game is available as an apk, is it possible to create an apk from here?

  14. I downloaded the source for Solarus and followed the instructions compile the source. The resulting executable runs the sample quest. I then attempted to ‘make install’. This put the solarus_run file in /usr/local/bin/ which is correct, but when I type solarus_run i get
    solarus_run: eror while loading shared libraries: cannot open shared object file: No such file or directory
    To get the program working I needed to copy the file from the build directrory to /usr/lib/

    I’m using Ubuntu 15.04 and would like to know how to fix the makefile so this file would be put in the corect place automatically.

  15. is also installed by make install. By default, it is installed in the “lib” subdirectory of the installation prefix.
    Your installation prefix seems to be /usr/local, so do you have a in /usr/local/lib?

  16. Everything appears to be working, except that when I run: solarus-quest-editor
    It says:
    solarus-quest-editor: error while loading shared libraries: cannot open shared object file: No such file or directory
    It is installed in /usr/local/bin and is in /usr/local/lib/x86_64-linux-gnu
    I am using Kubuntu 16.04 LTS.

  17. Try to install Solarus in /usr rather than /usr/local.
    To do that, re-run cmake in solarus build dir with:
    cmake -DCMAKE_INSTALL_PREFIX=/usr .
    and then recompile and install again.

  18. Note though that solarus-run works fine.
    Neither the solarus-quest-editor in usr/local/bin nor usr/bin work, they both give that same error.
    Tried installing the solarus engine with -DCMAKE_INSTALL_PREFIX=/usr and it didn’t install in usr/bin.
    This seems strange.

  19. $/usr/games/bin/solarus-run
    /usr/games/bin/solarus-run: error while loading shared libraries: cannot open shared object file: No such file or directory

    Debian standard path:
    $echo $PATH

    libsolarus is installed in /usr/games/lib/x86_64-linux-gnu/
    Why is it not seen by the system in $PATH ?

Leave a Reply

Your email address will not be published. Required fields are marked *