compilation.txt

Solarus is an open-source Zelda-like 2D game engine written in C++ and licensed
under GPL v3.
It can run quests scripted in Lua.

This file explains how to compile Solarus.


--------
Contents
--------

1  Overview
2  External dependencies
  2.1  Linux users
  2.2  Windows users
  2.3  Mac OS X users
3  Compilation instructions
  3.1  Configure
  3.2  Build
  3.3  Run
  3.4  Install
4  Platform-specific information
  4.1  Mac OS X
  4.2  OpenPandora
  4.3  GCW-Zero


-----------
1  Overview
-----------

Solarus can run quests scripted in Lua.
A quest is a game, represented as a directory called "data"
or a zip archive called "data.solarus" or
"data.solarus.zip" and containing all the data files of the quest:
(graphics, musics, sounds, scripts, dialogs, etc.).
A short sample quest is provided in the directory "sample_quest".

Our quests can be found on the website: http://www.solarus-games.org.

The project is separated in two parts: Solarus and the Solarus GUI.
- Compiling the core part (Solarus) generates:
  - A dynamic library called "solarus".
  - An executable file called "solarus-run" that directly runs a quest.
- Compiling the GUI part (Solarus GUI) is optional and generates:
  - A dynamic library called "solarus-gui"
  - An executable file called "solarus", providing a GUI window
    to run quests.

It is possible to play Solarus games without the GUI part:
the "solarus-run" execute will directly run the quest in the current
directory if any.
The GUI part adds a user-friendly interface with menus that allow users to
select quests and change some settings.

The GUI mode is probably the preferred way for desktop systems,
while the solarus-run mode may be better on mobile systems.
If you don't want the GUI part, it is possible to disable it
at configuration time, and then you don't need Qt.


------------------------
2  External dependencies
------------------------

The build process of Solarus uses CMake.

To compile Solarus, 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,
and probably with other recent compilers (please let us know).


The following libraries are required to compile and execute Solarus:

- SDL2 (2.0.4 or greater)
- SDL2main
- SDL2_image
- SDL2_ttf
- Openal
- Vorbisfile
- Ogg
- Modplug (0.8.8.4 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.

- About SDL2:

SDL 2.0.2 is buggy (you will get broken graphics or even a black screen).
You need at least SDL 2.0.4.

- About Qt5:

You only need Qt if you want to build the Solarus GUI.
If you want to disable the build of the Solarus GUI,
set the CMake variable SOLARUS_GUI to OFF at the configuration step
and then you don't need Qt.

- About Lua:

Solarus uses the Lua scripting language.
LuaJIT, a just-in-time implementation of Lua, is used by default for optimal
performance.
But if you want to use vanilla Lua rather than LuaJIT,
set the CMake variable SOLARUS_USE_LUAJIT to OFF at the configuration step.

- About ModPlug:

We maintain a fork of libmodplug 0.8.8.4 here:
https://github.com/christopho/libmodplug
Previous versions of libmodplug cause compilation problems as well as issues
like .it musics that do not correctly loop.


2.1  Linux users:
-----------------

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

build-essential cmake
libsdl2-dev libsdl2-image-dev libsdl2-ttf-dev libluajit-5.1-dev
libphysfs-dev libopenal-dev libvorbis-dev libmodplug-dev
qtbase5-dev qttools5-dev qttools5-dev-tools

2.2  Windows users:
-------------------

Install a C++ compiler if you don't have one.
Solarus compiles fine with the MinGW compiler: http://www.mingw.org/
and probably with other compilers too.

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.
With the MinGW compiler for example, this may be something like
C:\MinGW\include.
Similarly, install the static library files (the .lib or .a files)
in your compiler's lib directory.
This may be something like C:\MinGW\lib.
Install the dynamic library files (the .dll files) in your compiler's bin
directory
This may be something like C:\MinGW\bin.

The directory libraries/win32 of Solarus contains some required static and
dynamic libraries that might be hard to find as binaries on websites
(especially ModPlug). They all work at least with the MinGW compiler.


2.3  Mac OS X users:
--------------------

The directory libraries/macosx contains some required static and dynamic
libraries that are not provided as binaries by their authors, but I don't
guarantee that they are up-to-date.
The Lua readme recommends to link statically against Lua, so you shouldn't
embed it.
Also, the OpenAL framework is already part of the OSX system since 10.4, so you
don't have to embed this one either.
You can use both .dylib or .framework for the other ones, but just remember
that you have to check the version number, runpath search, architecture and
backward compatibility if you want to deploy your application.


---------------------------
3  Compilation instructions
---------------------------


3.1  Configure
--------------

Use CMake to generate Makefiles or a project for your favorite IDE,
from the CMake GUI of from the command line.

- Graphically:

Run the CMake GUI. Select the source directory of Solarus (like C:/solarus)
and choose a build directory of your choice (like C:/solarus/build).

Click "Configure" and choose what kind of project you want CMake to generate:
Makefiles, a Code::Blocks project, a Visual Studio project, etc.

If CMake does not automatically find a compiler, indicate its installation path
by creating a variable CMAKE_PREFIX_PATH with the appropriate value
(for example C:/MinGW). This prefix path should be a directory that contains
include, lib and bin directories with all dependencies in them.
After that, click "Configure" again. CMake should be able to find all
includes and libraries. If it does not, check that you have correctly
installed them.

Then click "Generate" to generate the project files.

- Or from the command-line:

Go to the solarus directory and type:

$ mkdir build
$ cd build
$ cmake ..

This generates appropriate Makefiles for your system in a build directory.
If you prefer, you can also generate other kinds of projects with the
appropriate -G option (see the documentation of CMake for more information).


3.2  Build
----------

Then, you can compile the Solarus project that was generated by CMake.

- Graphically:

If you chose to generate a project for an IDE (like Code::Blocks or Qt Creator),
open the generated project an compile it from your IDE.

- Or from the command-line:

If you chose to generate Makefiles, you can compile from the command-line:

$ make

The build error messages will tell you which headers
and libraries are missing (it is hard to get them right in one try!).

Once the compilation is finished, you obtain a dynamic library called "solarus"
and an executable called "solarus-run".
If you built the Solarus GUI too, you also have a "gui" directory
that contains a dynamic library called "solarus-gui"
and an executable called "solarus".


3.3.  Run the Solarus GUI
-------------------------

To open the Solarus user-friendly GUI, run the "solarus" executable located
in the "gui" directory.
You can then choose the quest to run and change some settings.


3.4.  Run a quest directly
--------------------------

To directly execute a quest without a GUI, run the "solarus-run"
executable.
The quest path must be specified on the command line.
If you don't specify it, it will be the current directory by default.

The quest path is a directory containing the "data" subdirectory of your
quest, or containing the "data.solarus" or "data.solarus.zip" archive of
your quest.

It means that if you run solarus-run without parameters, then a quest must
exist in the current directory.

- Graphically:

Make a shortcut that runs the solarus-run executable with your quest path as
parameter.
Or place the quest in the same directory as the solarus-run executable
and run it wihout parameter.

- Or from the command line:

Type from your build directory:

$ ./solarus-run path/to/your/quest


3.5.  Install
-------------

Installing Solarus is optional.

But this can be useful in some cases: if your want it in your PATH (on Unix),
if you want to remove the build directory, or if you want to use the Solarus
libraries in another project.

- Graphically:

Copy the solarus library, the solarus-run executable,
the solarus-gui library and the solarus executable
where you want them to be installed.

If you intend to use the Solarus libraries from another project, you need to
copy the whole include/solarus directory somewhere too
(and gui/include/solarus for the Solarus GUI library).
Important: also copy the build/include/solarus/config.h and put it with the
other installed headers, next to config.h.in.
(config.h is a header generated at configuration step, this is why it was in
the build directory and not with the rest of source files.)

- Or from the command line:

If you generated Makefiles with CMake, an appropriate install rule is
available:

$ make install

This will install all compiled Solarus libraries, executables
and headers (including the generated header config.h).
The default installation directory probably requires administrative
privileges.

To change the installation directory, change the CMake variable
CMAKE_INSTALL_PREFIX at the configuration step.
The executables, the libraries and the headers will be installed in
standard subdirectories of this install prefix, like
bin/, lib/ and include/.

If you need finer customization, the name of these three subdirectories
can also be changed in CMake: they are set in variables
SOLARUS_EXECUTABLE_INSTALL_DESTINATION, SOLARUS_LIBRARY_INSTALL_DESTINATION
and SOLARUS_HEADERS_INSTALL_DESTINATION.


--------------------------------
4  Platform-specific information
--------------------------------


4.1  Mac OS X
-------------

- Pre-requisites

To install the needed packages via the brew package manager:

brew install sdl2 libvorbis libmodplug cmake ninja luajit sdl2_image sdl2_ttf

You will also need a copy of OS X SDK, which is included with XCode. XCode is 
freely available on the App Store.


- Compile on OSX

You can follow the standard compilation instructions to build Solarus on OSX.
However here are some tips that may be useful depending on your developer environment :

You can build the XCode project using cmake
$ cmake -G Xcode ..

If you wish to build the solarus GUI, the cmake line will probably become
something like
$ cmake -DCMAKE_PREFIX_PATH="<path_to_Qt>/Qt/5.5/clang_64/lib/cmake" -Wno-dev  ..

If you want to deploy a quest on non-developer environment with a
standalone bundle, the better way is to use the Solarus package provided on
http://www.solarus-games.org/ and use a post-build script to replace 
Solarus.app/Contents/Resources/solarus-run and 
Solarus.app/Contents/Frameworks/libsolarus.dylib by ones just compiled.
The bundle is made to run the data/ or data.solarus quest located into
Solarus.app/Contents/Resources.


4.2  OpenPandora
----------------

First, you need a working OpenPandora cross-compiling environment.
See the OpenPandora website: www.openpandora.org

To compile Solarus, we provide a CMake toolchain file:
cmake/pandora/PandoraToolchain.cmake
The role of this toolchain file is essentially to indicate the compiler to
CMake.
You may want to modify some paths in this toolchain file to better fit your
configuration.
Then, compile Solarus normally with CMake, indicating the toolchain file like
this:

$ mkdir pandora-build
$ cd pandora-build
$ cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/pandora/PandoraToolchain.cmake ..
$ make


4.2 GCW-Zero
------------

First, you need a working GCW-Zero toolchain.  See the GCW-Zero development page at:
http://www.gcw-zero.com/develop to see how to set it up.

To compile Solarus, we provide a CMake toolchain file:
cmake/gcw-zero/gcw-zero.cmake
The role of this toolchain file is essentially to indicate the compiler to
CMake.
You may want to modify some paths in this toolchain file to better fit your
configuration.
Then, compile Solarus normally with CMake, indicating the toolchain file like
this:

$ mkdir gcw-zero-build
$ cd gcw-zero-build
$ cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/gcw-zero/.cmake ..
$ make