Solarus is an open-source Zelda-like 2D game engine written in C++ and licensed
under GPL v3.
This file explains how to compile and install Solarus.


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

1  Overview
2  External dependencies
3  Compilation instructions
  3.1  Default settings
  3.2  Change the install directory
  3.3  More about the datapath
  3.4  Windows developers
  3.5  Mac OS X developers


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

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 game, represented as a
  zip archive called data.solarus 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.). Our quests can be found on
the development blog: http://www.solarus-engine.org.


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

The build process of solarus uses cmake.
To compile Solarus, you obviously need a C++ compiler.
The following libraries are required to compile and to execute Solarus:

SDL
SDLmain
SDL_image
SDL_ttf
openal
vorbisfile
modplug
lua5.1
physfs


Note that two other libraries are directly embedded in the source code:
SimpleIni, an ini file 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:

libsdl1.2-dev libsdl-image1.2-dev libsdl-ttf2.0-dev liblua5.1-0-dev
libphysfs-dev libopenal-dev libvorbis-dev libmodplug-dev


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 contains some required static and dynamic
libraries that are not provided as binaries by their authors, but I don't
guarantee they are up-to-date.


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


3.1  Default settings
----------------------

To compile solarus 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
disable 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.


3.2  Change the install 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 -D CMAKE_INSTALL_PREFIX=/home/your_directory .
$ make
$ make install

This installs the solarus binary like above, with the /usr/local prefix
replaced by the one you specified.


3.3  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.


3.4  Windows developers
-----------------------

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


3.5  Mac OS X developers
---------------------

I don't have Mac OS X, so this readme is for now very incomplete in this section.
See the development blog for more information.

