compilation.md 14.3 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
![Solarus logo](/images/solarus_logo.png)

**COMPILATION GUIDE**

[![License](https://img.shields.io/badge/license-GPLv3-blue.svg)](https://www.gnu.org/copyleft/gpl.html)

---

# About Solarus

Solarus is an open-source adventure 2D game engine written in C++.
It can run games scripted in Lua.
This engine is used by our Zelda fangames.
Solarus is licensed under GPL v3.

This document explains how to compile Solarus.

# Contents

* [Overview](#overview)
* [External dependencies](#external-dependencies)
  - [Linux users](#linux-users)
  - [Windows users](#windows-users)
  - [macOS users](#macos-users)
* [Compilation instructions](#compilation-instructions)
  - [Configuring](#configuring)
  - [Building](#building)
  - [Running the Solarus GUI](#running-the-solarus-gui)
  - [Running a quest directly](#running-a-quest-directly)
  - [Installation](#installation)
* [Platform-specific information](#platform-specific-information)
  - [Mac OS X](#mac-os-x)
  - [OpenPandora](#openpandora)
  - [GCW-Zero](#gcw-zero)

# 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:

1. A dynamic library called `solarus`.
2. An executable file called `solarus-run` that directly runs a quest.

Compiling the GUI part (Solarus GUI) is *optional* and generates:

1. A dynamic library called `solarus-gui`.
2. 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`
executable 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 require the Qt dependencies.

# External dependencies

The build process of Solarus uses [CMake](https://cmake.org/).
72
You also will need the [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/) helper tool installed.
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131

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.6 or greater)
- SDL2main
- SDL2_image
- SDL2_ttf
- OpenGL or OpenGL ES
- 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 (Nintendo SNES) 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.6.

**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.
However, 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://gitlab.com/solarus-games/libmodplug
Previous versions of libmodplug cause compilation problems as well as issues
like `.it` files that do not correctly loop.

**About OpenGL ES**

If you wish to enable the OpenGL ES implementation, set the CMake
variable `SOLARUS_GL_ES` to `ON` at the configuration step.

## Linux users

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

132
    build-essential cmake pkg-config
133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412
    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 libglm-dev

## Windows users

Install a C++ compiler, Git and CMake.
Solarus compiles fine with the [MinGW compiler](http://www.mingw.org/) and
probably with other compilers too.

We recommend [QtCreator](https://www.qt.io/developers/), which includes the Qt
libraries, MinGW, as well as Git and CMake integration.

The directory `libraries/win32/mingw32` in the Solarus repository contains
headers and compiled binaries of all required libraries that Solarus needs
besides Qt, all of which working at least with the MinGW32 compiler.

If you want other versions of these dependencies of if you don't use the
MinGW32 toolchain, you can download the header files and the binaries of all
libraries listed above, on their official websites.
For some of them you have to compile the binary libraries yourself.

In any case, you will then need to tell CMake the location of these
dependencies.

## macOS users

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

# Compilation instructions

The following are the instructions for configuring and building Solarus.

## Configuring

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

**Using the CMake GUI**

Run the CMake GUI.
Select the source directory of Solarus (for example `C:\solarus`) and choose a
build directory of your choice (for example `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 the required dependencies in them.
After that, click *Configure* again. CMake should be now 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.

**Using the CMake command-line**

Go to the solarus directory and type the following:

    $ mkdir build
    $ cd build
    $ cmake ..

This generates appropriate Makefiles for your system in the `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).

## Building

After configuring the build, you can now compile the Solarus project using the
files generated by CMake.

**Using a GUI**

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.

**Using the command-line**

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

    $ make

Any 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 will obtain a dynamic library named
`solarus` and an executable named `solarus-run`.
If you built the Solarus GUI too, you will also have a `gui` directory that
contains a dynamic library named `solarus-gui` and an executable
named `solarus`.

## Running 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 its settings.

## Running 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,
or an archive containing your quest files (content of the `data` directory).

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

**Using a GUI**

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 any parameters.

**Using the command-line**

Type from your build directory:

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

## Installation

Installing Solarus is *optional*.

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

**Using a GUI**

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 as well, and
`gui/include/solarus` for the Solarus GUI library.

*Important:* also copy the `build/include/solarus/config.h` file and place it
with the other installed headers, next to `config.h.in`.
The `config.h` file is a header generated at the configuration step, this is
why it is in the build directory and not with the rest of source files.

**Using 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, i.e. `bin`, `lib` and `include`.

If you need finer-grained customization, the name of these three subdirectories
can also be changed in CMake.
For this, set the variables `SOLARUS_EXECUTABLE_INSTALL_DESTINATION`,
`SOLARUS_LIBRARY_INSTALL_DESTINATION` and `SOLARUS_HEADERS_INSTALL_DESTINATION`.

# Platform-specific information

## Mac OS X

**Pre-requisites**

To install the needed packages via the brew package manager, type:

    brew install cmake ninja \
        sdl2 sdl2_image sdl2_ttf luajit libvorbis libmodplug physfs

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

**Compile on macOS**

You can follow the standard compilation instructions to build Solarus on macOS.
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 invocation will probably become
something like this:

    $ cmake \
        -DCMAKE_PREFIX_PATH="<path_to_Qt>/Qt/<version>/clang_64/lib/cmake" \
        -Wno-dev  ..

**Deploy on macOS**

If you wish 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 the
`Solarus-run.app/Contents/Resources/solarus-run` and
`Solarus-run.app/Contents/Frameworks/libsolarus.dylib` files by the ones
just compiled.
The bundle is made to run the `data/` or `data.solarus` quest located in the
`Solarus-run.app/Contents/Resources` directory.

Once done, you eventually have to make sure that all new embedded binaries
are undependant from your developer environment.
Open a new command-line window and run the following on all of them:

    $ otool -L <binary_to_check>

Verify that all dependencies path related to an embedded binary are correct
and begin with the `@rpath/` string.
If not, run:

    $ install_name_tool -id <binary_path>

to update the first line returned by `otool -L` or:

    $ install_name_tool -change <old_path> <new_path>

to update one of the other.

*Note:* If you wish to deploy the Solarus GUI instead of a standalone quest,
steps are the same except that you will use the `Solarus.app` package instead
of the `Solarus-run.app` one, and will copy `libsolarus-gui.dylib` and
`solarus-launcher` binaries instead of the `solarus-run` one and the quest.

## OpenPandora

First, you need a working OpenPandora cross-compiling environment.
See the OpenPandora website: http://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
use 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

## GCW-Zero

First, you need a working GCW-Zero toolchain.
See the website in 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
use 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