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: SDL2, SDL2_image, SDL2_ttf, lua5.1 (LuaJIT is recommended), physfs, openal, vorbisfile and modplug.
SDL 2.0.0 is buggy (you will get broken graphics or even a black screen). You need at least SDL 2.0.1. Ubuntu 14.04 provides SDL 2.0.2, so you will be okay, but Ubuntu 13.10 only provides SDL 2.0.0.
Note that another library is directly embedded in the source code: snes_spc, an SPC music decoding library.
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
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 -j4
Then, 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 “data.solarus.zip” archive of your quest.
# 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.
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.