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 of a game.
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.
Compiling and installing the engine
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:
# 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 (the engine) with cmake, go to the solarus directory and type:
$ cmake -DCMAKE_BUILD_TYPE=Release .
This generates the appropriate Makefiles for your system. The -DCMAKE_BUILD_TYPE=Release parameter optimizes the compilation and disables debugging assertions. Games will run significantly faster.
Then you can compile the engine with:
$ make
and install it with (as root):
# make install
This installs the solarus binary in /usr/local/bin (assuming that the install directory is /usr/local).
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.
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 three files 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 command-line argument is set (see above), 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 DEFAULT_QUEST is used. The DEFAULT_QUEST constant can be configured from your cmake command by using:
$ cmake -DEFAULT_QUEST=/path/to/your/quest .
Finally, if the DEFAULT_QUEST constant 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 command-line arguments. You can still launch another quest by using the command-line argument, which overwrites the 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.
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 thanks to Code::Blocks:
- 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!).
Mac OS X developers
The install.txt file contains more information about the Mac OS X compilation.
Playing a game with the engine
We have just seen how to compile and install Solarus (the engine). We now assume that Solarus is installed.
You need to specify to the solarus binary the path of the quest data files to use. Solarus accepts two forms of quest paths:
- a directory having a subdirectory named “data” with all data inside,
- a directory having an archive “data.solarus” with all data inside.
For instance, to run our quest zsdx, go to the quests/zsdx/ directory of your copy of the git repository. Since there is a “data” subdirectory, you can type
$ solarus .
or without arguments:
$ solarus
if solarus was compiled with the default quest set to “.”.
Also note that for our quests zsdx and zsxd, we provide installation scripts that build and install the zip archive data.solarus. See the readme.txt file of each quest for more details.
Comments