This page explains how to compile and install the engine and the quests from the source code. To download the code, see the source code page.

When it is installed, the project is divided in two parts:

  • Solarus (the engine), which is an executable file written in C++ and called solarus.
  • One or several quests, each quest corresponding to a zip archive called data.solarus and containing all the data.

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 (more details below).

The engine source files are located in the src and include directories. The C++ code is under GPL.

The quests source files of are located in the quests directory. Each quest has a specific directory and its data files are in its data subdirectory.
For example, for the zsdx quest, the data files are in a directory called quests/zsdx/data. Those data files represent all resources used by both the engine and the quest, such as sounds, music, images, sprites, dialogs, maps and scripts. The scripts are written in Lua. When building the quest, a zip archive called data.solarus is created with all data files.

Two quests are currently available (zsdx and zsxd), and these quests are not under GPL since they use elements from Nintendo.

If you want to compile and install the engine without any quest, just remove the quests directory and follow the instructions normally.

External dependencies

The build process uses cmake for the engine and the quests. 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 above) and build a quest without CMake (by compiling the Lua scripts and building the zip archive yourself).

To compile Solarus (the engine), you need a C++ compiler.

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

Note that two other libraries are directly embedded in the source code: SimpleIni, an ini parsing library which consists in only two header files (no source files), and snes_spc, an SPC music decoding library.

Linux developers:

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

sudo 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 lua5.1 zip

Windows developers:

Download the binary version of each one of the development libraries listed above, on their official websites. Install the header files (the .h files) in your compiler’s include directory. This may be something like C:\Program Files\Microsoft Visual Studio 9.0\VC\include. Similarly, install the library files (the .lib files) in your compiler’s lib directory. This may be something like C:\Program Files\Microsoft Visual Studio 9.0\VC\lib. Install the dynamic library files (the .dll files) in your system32 directory (which may be C:\WINDOWS\system32). The directory libraries/win32 of the project contain some required static and dynamic libraries that are not provided as binaries by their authors.

To build a Solarus quest, you will also need zip.

Compilation instructions

To compile solarus and the quests provided (zsdx and zsxd for now) with cmake, go to the solarus directory and just type:

cmake .

This generates the appropriate Makefiles for your system. Then you can compile the engine and the quests with:

make

and install both of them with (as root):

make install

This installs the following three files (assuming that the install directory is /usr/local):
- the solarus binary (the engine) in /usr/local/bin/
- for each quest, the quest data archive in /usr/local/share/solarus/<quest_name>/
- for each quest, a script called <quest_name> in /usr/local/bin/

For example, the zsdx script runs the solarus binary with the appropriate command-line argument. This means that you can launch the zsdx game with the command:

zsdx

which is equivalent to:

solarus /usr/local/share/solarus/zsdx

If you want to compile the engine without quests (i.e. you have no quests directory), cmake detects it and only builds and installs the solarus binary.

Changing the install directory

You may want to install the engine and the quests 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 three files as described above except that the /usr/local prefix is replaced by the one you specified. The script generated launches the engine with the appropriate command-line argument.

More about the quest path

There are several ways to make the engine find the quest archive data.solarus. If the quest path is set as an command-line argument of solarus (see above), then the engine looks into the directory specified. Otherwise, if the DEFAULT_QUEST preprocessor constant exists, then this directory is used. The DEFAULT_QUEST constant can be set from your cmake command, by using:

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

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

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

Windows developers

I have managed to compile Solarus with Code::Blocks, without using CMake. It is necessary to additionally link with libz.

Mac OS X developers

I don’t have Mac OS X, so this section is very incomplete for now. Any help is welcome!