compilation.txt

Solarus is an open-source Zelda-like 2D game engine written in C++ and licensed
under GPL v3.
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
-----------

When it is installed, the project is divided in two parts:
- Solarus (the engine), which is an executable file called solarus_run and
  a dynamic library called solarus.
- One (or several) quests, each quest corresponding to a game, represented as a
  directory called "data" or a zip archive called "data.solarus" or
  "data.solarus.zip" and containing all the data of the quest.
This readme is about compiling and installing solarus (the engine).
To execute it, you will also need a quest with all its game data files
(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.


------------------------
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 to execute Solarus:

SDL2 (2.0.1 or greater)
SDL2main
SDL2_image
SDL2_ttf
openal
vorbisfile
modplug (0.8.8.4 or greater)
lua5.1 (LuaJIT is recommended)
physfs

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

- About SDL2:

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.

- 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


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


3.3.  Run
---------

To execute a quest with the Solarus engine, execute 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, 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.4.  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
library in another project.

- Graphically:

Copy the solarus_run executable and the solarus library where you want them
to be installed.

If you intend to use the Solarus library from another project, you need to
copy the whole include/solarus directory somewhere too.
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 correctly install the solarus_run executable, the solarus library
and the solarus headers (including the generated one 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 executable, the library and the headers will be installed in
bin/, lib/ and include/ subdirectories of this install prefix.

If you need even 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
-------------

- Compile on OSX

You can compile solarus just by doing the default setting with cmake, or generate the XCode project. 
Note that you probably want to pass the SOLARUS_BUNDLE flag too, which build the entire bundle instead of 
just the binary.

By default, you will build a binary with the maximum of compatibility that your OSX version can provide. 
You may want to produce an optimized (or exotic) binary instead of a standard one.
To do so, pass SOLARUS_SYSROOT, SOLARUS_DEPLOYMENT or/and SOLARUS_ARCH constants to
cmake to overload default settings, just like the following example :

$ cmake -DSOLARUS_SYSROOT="/Developer/SDKs/MacOSX10.5.sdk" -DSOLARUS_ARCH="ppc;i386;x86_64" -DSOLARUS_DEPLOYMENT=10.5 .


- Deploy on OSX

You will only build the executable with the default command.
To build the entire bundle, pass the following flag to cmake

$ cmake -DSOLARUS_BUNDLE="your_bundle_name" .

Which will install the application into a bundle named "your_bundle_name"
and place it in the /Applications folder.
A bundle is a .app suffixed folder, which typically contains 
the executable and all resources it needs.
Pass SOLARUS_BUNDLE_INFOPLIST, SOLARUS_BUNDLE_ICON,
SOLARUS_BUNDLE_CODESIGN and/or SOLARUS_BUNDLE_VERSION flags
in addition to SOLARUS_BUNDLE to specify your own configuration.
See ./cmake/modules/addCFBundleTarget.cmake for more details.

All non-Mac-native frameworks are placed in ${your_bundle_name}.app/Contents/Frameworks/
You have to do a little verification on them : check if dependencies search
path are correctly integrated, just by doing

$ otool -L /dylib/or/binary/I/want/to/check

It show the search path for every dependencies. Just look on the one you embed.
If one of them has a wrong path, you can modify it with

$ install_name_tool -id new_path /dylib/or/binary/I/want/to/modify
or
$ install_name_tool -change old_path new_path /dylib/or/binary/I/want/to/modify

The new_path string usually looks like "@rpath/The_dylib.dylib" or 
"@rpath/The_framework.framework/Version/A/The_binary" on Mac 10.5+.
Replace "@rpath/" by "@executable_path/../Frameworks/" on older OSX versions.

Instead of using this command on embed libraries, you should directly do it on system libraries,
which they are copied from, and then just do this step once.

Finally, see https://developer.apple.com/library/mac/#releasenotes/General/SubmittingToMacAppStore/_index.html#//apple_ref/doc/uid/TP40010572
to make sure you have a fully 10.8+ and Mac App Store compatible application.


- Add a quest into the OSX Bundle

Just copy the quest file (data.solarus, data.solarus.zip or data/) into ${your_bundle_name}.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