• Compilation instructions

    This page explains how to compile and install the engine from the source code. To download the code, see the source code page. The C++ source code is located in the src and include directories. It is licensed under GPL v3.

    When it is compiled, the engine is an executable file called solarus. When the solarus binary is run, it needs the path of the quest to launch. This can be done at runtime as an argument of solarus. Two forms of quest paths are possible:

    • a directory having a subdirectory named “data” with all data inside,
    • a directory having a zip archive “data.solarus” or “data.solarus.zip” with all data inside.

    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.

    The following libraries are required to compile and to execute Solarus: SDL, SDLmain, SDL_image, SDL_ttf, lua5.1, physfs, openal, vorbisfile and modplug.

    As of Solarus 1.2 (the current development version), the version of SDL changes: we use SDL2, SDL2main, SDL2_image and SDL2_ttf.

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

    Linux developers

    Just install the corresponding packages. For example, with Ubuntu or Debian:

    # apt-get install libsdl1.2-dev libsdl-image1.2-dev libsdl-ttf2.0-dev liblua5.1-0-dev libphysfs-dev libopenal-dev libmodplug-dev libvorbis-dev

    Compilation instructions

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

    $ cmake .

    This generates the appropriate Makefiles for your system.

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

    $ make -j4
    Then, to execute a quest, type
    $ ./solarus path/to/your/quest

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

    Optionally, to be able to run the engine from anywhere, install the engine with (as root):
    # 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:

    $ 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 SDL, SDL_image, SDL_ttf, lua5.1, 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, SDLmain, SDL, SDL_image, SDL_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.

    17 Responses to Compilation instructions

    1. kimsama
      April 6, 2013 at 5:55 pm

      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. April 6, 2013 at 6:05 pm

      Fixed in commit 79f23866. Thanks for the report!

    3. Biniou
      May 12, 2013 at 6:59 pm


      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 :-)

    4. Biniou
      May 12, 2013 at 7:07 pm

      … 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 (https://aur.archlinux.org/packages.php?ID=55051), 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?

    5. May 12, 2013 at 7:54 pm

      You need Lua 5.1. Lua 5.2 breaks compatibility: for example, lua_setfenv() no longer exists.

    6. Biniou
      May 12, 2013 at 8:50 pm

      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?

    7. May 12, 2013 at 9:43 pm

      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/liblua5.1.so . (Note this kind of manual cmake configuration allows people to use any library without even installing it.)

    8. Biniou
      May 13, 2013 at 6:39 am

      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!

    9. abombthecoder
      May 14, 2013 at 4:05 am

      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

    10. abombthecoder
      May 14, 2013 at 4:17 am

      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?

    11. abombthecoder
      May 14, 2013 at 4:39 am

      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!

    12. May 14, 2013 at 9:01 am

      @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: https://github.com/christopho/libmodplug

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

    13. abombthecoder
      May 15, 2013 at 1:06 am

      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.

    14. May 15, 2013 at 9:50 am

      @abombthecoder: Did you receive my email? We have an IRC channel on irc.solarus-games.org #solarus.

    15. red8
      July 29, 2013 at 1:51 am

      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. =)

    16. July 29, 2013 at 8:50 am

      @red8: I have just created an issue: https://github.com/christopho/solarus/issues/254
      Thanks for the report.
      I believe this crash in only in the development version, it might be due to the new dialog system.

    17. July 29, 2013 at 10:52 am

      @red8: The crash is now fixed in the Solarus git repository. Thanks again for the report!

    Leave a Reply

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