magnum/doc/building.dox

/*
    This file is part of Magnum.

    Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016
              Vladimír Vondruš <mosra@centrum.cz>

    Permission is hereby granted, free of charge, to any person obtaining a
    copy of this software and associated documentation files (the "Software"),
    to deal in the Software without restriction, including without limitation
    the rights to use, copy, modify, merge, publish, distribute, sublicense,
    and/or sell copies of the Software, and to permit persons to whom the
    Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included
    in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
    DEALINGS IN THE SOFTWARE.
*/

namespace Magnum {

/** @page building Downloading and building
@brief Guide how to download and build Magnum on different platforms.

@tableofcontents

Minimal set of tools and libraries required for building is:

-   C++ compiler with good C++11 support. Compilers which are tested to have
    everything needed are **GCC** >= 4.7, **Clang** >= 3.1 and **MSVC** 2015.
    On Windows you can also use **MinGW-w64**. GCC 4.6, 4.5, 4.4 and MSVC 2013
    support involves some ugly workarounds and thus is available only in
    `compatibility` branch.
-   **CMake** >= 2.8.12
-   **Corrade** - Plugin management and utility library. See
    @ref building-corrade "Corrade download and installation guide" for more
    information.

Note that full feature set is available only on GCC 4.8.1 and Clang 3.1.

@section building-download Downloading the sources

The source is available on GitHub: https://github.com/mosra/magnum. Clone the
repository with your favorite IDE or Git GUI, download currrent snapshot as
compressed archive or use the command line:

    git clone git://github.com/mosra/magnum.git

If you need to use the `compatibility` branch, check it out as following from
the cloned repository or download the particular archive from
https://github.com/mosra/magnum/tree/compatibility.

    git checkout compatibility

@section building-compilation Compilation, installation

Relevant information about CMake usage was described in
@ref building-corrade "Corrade download and installation guide", this guide is
assuming you have at least basic knowledge of CMake.

@subsection building-linux Via command-line (on Linux/Unix)

On Unix-based OSs, the library (for example with support for SDL2 applications)
can be built and installed using these four commands:

    mkdir build && cd build
    cmake .. \
        -DCMAKE_INSTALL_PREFIX=/usr \
        -DWITH_SDL2APPLICATION=ON
    make
    make install

See @ref building-features "below" for additional configuration options.

If you have the dependencies installed in non-standard location (other than
`/usr`, e.g. `/home/xyz/projects`), set `CMAKE_PREFIX_PATH` to that directory
to help CMake find them. You can enter more different dirs if you separate them
with semicolons.

Also, if you plan to install the library to non-standard location, you might
want to set `CMAKE_INSTALL_RPATH` to `lib/` subdir of given prefix (e.g.
`/home/xyz/projects/lib`), so the dynamic libraries can be found at runtime.

@subsection building-windows Building on Windows

On Windows you can use either MinGW-w64 or MSVC 2013 compiler. It's then up to
you whether you will use QtCreator, Visual Studio or do the build from command-
line. Note that for most convenient usage it's best use some dedicated
directory (e.g. `C:/Sys`) for installing dependencies instead of putting each
dependency to its own directory in `C:/Program Files`. Then add its `bin/`
subdir (e.g. `C:/Sys/bin`) to PATH so all the DLLs are found when running the
executables. If you are using MinGW-w64, the `C:/MinGW` directory is in most
cases already prepared for exactly this.

Then, when running CMake, set `CMAKE_PREFIX_PATH` and `CMAKE_INSTALL_PREFIX`
value to that directory (e.g. `-DCMAKE_INSTALL_PREFIX=C:/Sys`).

@subsubsection building-windows-msvc Using Visual Studio

On Windows CMake by default creates Visual Studio project files. You need to
use `compatibility` branch to compile with MSVC 2013, as said above.

The most straightforward way to build and install the library is again via the
command-line. The bonus point is that you don't even need to wait for Visual
Studio to load:

    mkdir build && cd build
    cmake -DCMAKE_INSTALL_PREFIX="C:/Sys" ..
    cmake --build .
    cmake --build . --target install

If you want to build and install from Visual Studio, just open the `Magnum.sln`
project file generated by CMake in the build directory.

@subsubsection building-windows-qtcreator Using QtCreator

On Windows you can also use QtCreator (just QtCreator, you don't need the full
Qt SDK). Configure it to use CMake and either MSVC compiler or MinGW-w64 and
then just open project's root `CMakeLists.txt` file within it. QtCreator then
asks you where to create build directory, allows you to specify initial CMake
parameters (e.g. `CMAKE_PREFIX_PATH` and `CMAKE_INSTALL_PREFIX`) and then you
can just press *Configure* and everything is ready to be built.

After the initial import you might want to reconfigure some CMake variables,
see @ref building-features "below" for more information.

Installation to given prefix can be done from within QtCreator by adding new
`make install` build rule.

@subsection building-features Enabling or disabling features

The libraries are build as shared by default. If you are developing for
platform which doesn't support shared libraries or if you just want to link
them statically, enable `BUILD_STATIC` to build the libraries as static.
Building of static plugins is controlled with separate `BUILD_PLUGINS_STATIC`
variable. If you plan to use the static libraries and plugins with shared
libraries later, enable also position-independent code with `BUILD_STATIC_PIC`.
If you want to build with another compiler (e.g. Clang), pass
`-DCMAKE_CXX_COMPILER=clang++` to CMake.

Libraries and static plugins built in `Debug` configuration (e.g. with
`CMAKE_BUILD_TYPE` set to `Debug`) have `-d` suffix to make it possible to have
both debug and release libraries installed alongside each other. *Dynamic*
plugins in `Debug` configuration are installed to `magnum-d` subdirectory
instead of `magnum`. Headers and other files are the same for both. The library
and plugin distinction is handled semi-automatically when using Magnum in
depending projects, see @ref cmake for more information.

The library is constantly evolving and thus some APIs are deprecated and then
later removed in favor of better ones. To preserve backwards compatibility,
Magnum is by default built with all deprecated APIs. However, to make your
code more robust and future-proof, it's recommended to build the library with
`BUILD_DEPRECATED` disabled.

By default the engine is built for desktop OpenGL. Using `TARGET_*` CMake
parameters you can target other platforms. Note that some features are
available for desktop OpenGL only, see @ref requires-gl.

-   `TARGET_GLES` -- Target OpenGL ES.
-   `TARGET_GLES2` -- Target OpenGL ES 2.0. Currently enabled by default when
    `TARGET_GLES` is set.
-   `TARGET_DESKTOP_GLES` -- Target OpenGL ES on desktop, i.e. use OpenGL ES
    emulation in desktop OpenGL library. Might not be supported in all drivers.
-   `TARGET_HEADLESS` -- Build command-line utilities for use on a headless
    machine. Basically it means that EGL with no display attachment is being
    used everywhere instead of platform-specific toolkits like CGL, GLX or WGL.
    Supported mainly on OpenGL ES drivers, for desktop OpenGL the only driver
    that supports this configuration is NVidia >= 355.

By default the engine is built in a way that allows having multiple
thread-local Magnum contents. This might cause some performance penalties -- if
you are sure that you will never need such feature, you can disable it via the
`BUILD_MULTITHREADED` option.

The features used can be conveniently detected in depending projects both in
CMake and C++ sources, see @ref cmake and @ref Magnum/Magnum.h for more
information. See also @ref corrade-cmake and @ref Corrade/Corrade.h for
additional information.

By default the engine is built with nearly everything except @ref Audio
library, plugins and application libraries (see below). Using `WITH_*` CMake
parameters you can specify which parts will be built and which not:

-   `WITH_AUDIO` - @ref Audio library. Depends on **OpenAL** library, not built
    by default.
-   `WITH_DEBUGTOOLS` - @ref DebugTools library. Enables also building of
    MeshTools, Primitives, SceneGraph, Shaders and Shapes libraries.
-   `WITH_MESHTOOLS` - @ref MeshTools library. Enabled automatically if
    `WITH_DEBUGTOOLS` is enabled.
-   `WITH_PRIMITIVES` - @ref Primitives library. Enabled automatically if
    `WITH_DEBUGTOOLS` is enabled.
-   `WITH_SCENEGRAPH` - @ref SceneGraph library. Enabled automatically if
    `WITH_DEBUGTOOLS` or `WITH_SHAPES` is enabled.
-   `WITH_SHADERS` - @ref Shaders library. Enabled automatically if
    `WITH_DEBUGTOOLS` is enabled.
-   `WITH_SHAPES` - @ref Shapes library. Enables also building of SceneGraph
    library. Enabled automatically if `WITH_DEBUGTOOLS` is enabled.
-   `WITH_TEXT` - @ref Text library. Enables also building of TextureTools
    library.
-   `WITH_TEXTURETOOLS` - @ref TextureTools library. Enabled automatically if
    `WITH_TEXT` or `WITH_DISTANCEFIELDCONVERTER` is enabled.

None of the @ref Platform "application libraries" is built by default (and you
need at least one). Choose the one which suits your requirements and your
platform best:

-   `WITH_ANDROIDAPPLICATION` - @ref Platform::AndroidApplication "AndroidApplication"
-   `WITH_GLFWAPPLICATION` - @ref Platform::GlfwApplication "GlfwApplication"
-   `WITH_GLUTAPPLICATION` - @ref Platform::GlutApplication "GlutApplication"
-   `WITH_GLXAPPLICATION` - @ref Platform::GlxApplication "GlxApplication"
-   `WITH_NACLAPPLICATION` - @ref Platform::NaClApplication "NaClApplication"
-   `WITH_SDL2APPLICATION` - @ref Platform::Sdl2Application "Sdl2Application"
-   `WITH_XEGLAPPLICATION` - @ref Platform::XEglApplication "XEglApplication"
-   `WITH_WINDOWLESSCGLAPPLICATION` - @ref Platform::WindowlessCglApplication "WindowlessCglApplication"
-   `WITH_WINDOWLESSEGLAPPLICATION` - @ref Platform::WindowlessEglApplication "WindowlessEglApplication"
-   `WITH_WINDOWLESSGLXAPPLICATION` - @ref Platform::WindowlessGlxApplication "WindowlessGlxApplication"
-   `WITH_WINDOWLESSIOSAPPLICATION` - @ref Platform::WindowlessIosApplication "WindowlessIosApplication"
-   `WITH_WINDOWLESSNACLAPPLICATION` - @ref Platform::WindowlessNaClApplication "WindowlessNaClApplication"
-   `WITH_WINDOWLESSWGLAPPLICATION` - @ref Platform::WindowlessWglApplication "WindowlessWglApplication"
-   `WITH_WINDOWLESSWINDOWSEGLAPPLICATION` - @ref Platform::WindowlessWindowsEglApplication "WindowlessWindowsEglApplication"

None of the context libraries is built by default. You need them only if you
choose to not use any application library (see @ref platform-custom for more
information):

-   `WITH_CGLCONTEXT` -- CGL context
-   `WITH_EGLCONTEXT` -- EGL context
-   `WITH_GLXCONTEXT` -- GLX context
-   `WITH_WGLCONTEXT` -- WGL context

There are also a few command-line utilities. They are currently available only
on Linux, Mac OS X and Windows, also disabled by default:

-   `WITH_MAGNUMINFO` - @ref magnum-info "magnum-info" executable, provides
    information about the engine and OpenGL capabilities.
-   `WITH_DISTANCEFIELDCONVERTER` - @ref magnum-distancefieldconverter "magnum-distancefieldconverter"
    executable for converting black&white images to distance field textures.
    Enables also building of TextureTools library.
-   `WITH_FONTCONVERTER` - @ref magnum-fontconverter "magnum-fontconverter"
    executable for converting fonts to raster ones. Enables also building of
    Text library.

Magnum also contains a set of dependency-less plugins for importing essential
file formats. Additional plugins are provided in separate plugin repository,
see @ref building-plugins for more information. None of the plugins is built by
default.

-   `WITH_MAGNUMFONT` -- @ref Text::MagnumFont "MagnumFont" plugin. Available
    only if `WITH_TEXT` is enabled. Enables also building of
    @ref Trade::TgaImporter "TgaImporter" plugin.
-   `WITH_MAGNUMFONTCONVERTER` -- @ref Text::MagnumFontConverter "MagnumFontConverter"
    plugin. Available only if `WITH_TEXT` is enabled. Enables also building of
    @ref Trade::TgaImageConverter "TgaImageConverter" plugin.
-   `WITH_OBJIMPORTER` -- @ref Trade::ObjImporter "ObjImporter" plugin.
-   `WITH_TGAIMPORTER` -- @ref Trade::TgaImporter "TgaImporter" plugin.
-   `WITH_TGAIMAGECONVERTER` -- @ref Trade::TgaImageConverter "TgaImageConverter"
    plugin.
-   `WITH_WAVAUDIOIMPORTER` -- @ref Audio::WavImporter "WavAudioImporter"
    plugin. Available only if `WITH_AUDIO` is enabled.

Note that [each namespace](namespaces.html) and all @ref Platform libraries
contain more detailed information about dependencies, availability on
particular platform and also guide how to enable given library in build and use
it with CMake.

@subsection building-tests Building and running unit tests

If you want to build also unit tests (which are not built by default), enable
`BUILD_TESTS` in CMake. Unit tests use Corrade's @ref Corrade::TestSuite
"TestSuite" framework and can be run either manually (the binaries are located
in `Test/` subdirectories of build directory) or using

    ctest --output-on-failure

in build directory. On Windows the tests require the library to be installed
with DLLs accessible through `PATH`. See
@ref building-windows "above Windows documentation" for more information.

The @ref Audio library has tests which require OpenAL to be able to create a
context.  That is the case on most platforms, so they are enabled by default.
In case it's not possible to have OpenAL context (such as when running
@ref CORRADE_TARGET_EMSCRIPTEN "Emscripten" tests under Node.js), you can
disable building of them with `BUILD_AL_TESTS`. The tests are suffixed with
`ALTest` so they can be also selectively included/excluded when running CTest,
e.g.:

    ctest -E ALTest # run everything except tests requiring OpenAL context

Platforms which have windowless GL context creation implemented (currently all
platforms except @ref CORRADE_TARGET_EMSCRIPTEN "Emscripten",
@ref CORRADE_TARGET_NACL "NaCl", @ref CORRADE_TARGET_WINDOWS_RT "Windows RT"
and @ref CORRADE_TARGET_ANDROID "Android")  can build also tests for OpenGL
functionality. You can enable them with `BUILD_GL_TESTS`. All GL tests are
suffixed with `GLTest` so they can be also selectively included/excluded when
running CTest, e.g.:

    ctest -R GLTest # run only tests requiring OpenGL context

@subsection building-doc Building documentation

The documentation (which you are currently reading) is written in **Doxygen**
(version 1.8 with Markdown support is used, but older versions should do good
job too) and additionally uses **TeX** for math formulas. The documentation can
be build by running

    doxygen

in root directory (i.e. where `Doxyfile` is). Resulting HTML documentation
will be in `build/doc/` directory. You might need to create `build/` directory
if it doesn't exist yet. If Corrade with generated documentation is placed in
`corrade` directory next to `magnum`, the documentation will be crosslinked
with Corrade's one. If related projects (`magnum-plugins`, `magnum-integration`
and `magnum-examples`, see below) are places along these, their documentation
will be also included in generated output.

@section building-related Related projects

The engine itself is kept as small as possible with only little dependencies.
Additional functionality, often depending on external libraries, is provided in
separate repositories. Various importer plugins for image, audio and 3D model
formats are maintained in @ref building-plugins "Plugins repository",
Integration with various external math and physics libraries is provided by
@ref building-integration "Integration library".

@section building-packages Prepared packages

@subsection building-packages-arch ArchLinux packages

In `package/archlinux` directory is currently one package for Git development
build. The package is also in AUR under the same name.

There are also a few development PKGBUILDs in `package/archlinux`, which allow
you to build and install the package directly from source tree without
downloading anything. The native PKGBUILDs also contain `check()` function
which will run all unit tests before packaging.

@subsection building-packages-gentoo Gentoo ebuilds

Gentoo Git ebuild is available in `package/gentoo` directory.

@subsection building-packages-deb DEB packages

There is also `package/debian/` directory with all files needed for building
Debian packages. You need to have `corrade-dev` DEB package installed and in
addition also `dpkg-dev` and `debhelper` packages. Building is easy, just
change directory to package root, link or copy `package/debian` directory there
and run `dpkg-buildpackage`:

    ln -s package/debian .
    dpkg-buildpackage

This will compile binary and development packages, which will then appear in
parent directory. If you need to modify CMake flags (enabling/disabling some
features, for example), modify the last entry in `debian/rules`.

@subsection building-packages-brew Homebrew formulas

OS X Homebrew formulas are in `package/homebrew` directory. Either use the
`*.rb` files directly or use the tap at https://github.com/mosra/homebrew-magnum:

    brew install --HEAD mosra/magnum/magnum

@section building-windows-angle Building for ANGLE on Windows

Magnum is able to run on ANGLE OpenGL-to-D3D translator. Download the code from
https://github.com/MSOpenTech/angle and use provided Visual Studio solution to
build it. Put the resulting `libGLESv2`/`libEGL` libraries and
`GLES2`/`GLES3`/`EGL` includes to a location where CMake can find them or set
`CMAKE_PREFIX_PATH` accordingly. ANGLE supports only OpenGL ES, thus you need
to enable `TARGET_GLES`. The engine is built for OpenGL ES 2.0 by default,
switch to 3.0 by disabling `TARGET_GLES2`.

    mkdir build-angle && cd build-angle
    cmake .. \
        -DCMAKE_PREFIX_PATH=<path-to-ANGLE-installation> \
        -DTARGET_GLES=ON -DTARGEET_GLES2=OFF \
        -DWITH_SDL2APPLICATION=ON
    cmake --build .

@section building-crosscompiling Crosscompiling

For crosscompiling you need to have *both* target and native version of
Corrade installed, because Corrade needs to run `corrade-rc` utility on the
host system as part of the build process. If native version of `corrade-rc` is
not found on the system, crosscompilation will fail.

You also need to have the toolchains submodule updated. Either run the
following commands, or, if you build from source archive, download snapshot of
toolchains repository from https://github.com/mosra/toolchains and put the
contents in `toolchains/` subdirectory.

    git submodule init
    git submodule update

Note that CMake for some reason treats `CMAKE_PREFIX_PATH` and
`CMAKE_INSTALL_PREFIX` differently while crosscompiling and you may need to add
dependency paths to both `CMAKE_PREFIX_PATH` and `CMAKE_FIND_ROOT_PATH` to make
it able to find the dependencies.

@subsection building-cross-winrt Crosscompiling for Windows RT

As said above, you need native build of `corrade-rc` executable. The below
script assumes that native Corrade build is installed in `C:/Sys` and the
installation path for WinRT dependencies is in `C:/Sys-winrt`.

You need at least Windows 8.1, Visual Studio 2013 and Windows 8.1 Store/Phone
SDK installed. Windows RT applications support OpenGL only through ANGLE, which
is currently limited to OpenGL ES. Download and build ANGLE @ref building-windows-angle "according to instructions above",
but use project files from the `winrt/` directory instead. Version 2.0.4 of SDL
has support for WinRT applications, download the source from
https://www.libsdl.org/download-2.0.php and use project files from the
`VisualC-WinRT` directory. Because WinRT applications run in a sandbox, it's
recommended to build the library as static so you don't have to bundle all the
DLLs. Example:

    mkdir build-winrt
    cd build-winrt
    cmake .. ^
        -DCMAKE_SYSTEM_NAME=WindowsStore ^
        -DCMAKE_SYSTEM_VERSION=10 ^
        -DCORRADE_RC_EXECUTABLE="C:/Sys/bin/corrade-rc.exe" ^
        -DCMAKE_INSTALL_PREFIX="C:/Sys-winrt" ^
        -DBUILD_STATIC=ON ^
        -DWITH_SDL2APPLICATION=ON ^
        -G "Visual Studio 14 2015" ..
    cmake --build .

Change `WindowsStore` to `WindowsPhone` if you want to build for Windows Phone
instead. When done, you can install the package using `cmake --build . --target install`
to make it available for depending projects.

See @ref Platform::Sdl2Application documentation for more information about
building your projects for WinRT.

@subsection building-cross-win Crosscompiling for Windows using MinGW-w64

@note This guide is tailored mainly for crosscompiling from ArchLinux. For
    this system there is also prepared `mingw-w64-magnum` development package
    in `package/archlinux`, named `PKGBUILD-mingw-w64`. See
    @ref building-packages-arch "above" for more information.

You will need MinGW-w64 versions of the compiler and all dependent libraries
(Corrade), i.e. these ArchLinux packages:

- `mingw-w64-gcc`
- `mingw-w64-corrade`

Then create build directories for 32b/64b build and run cmake and build command
in them. You may need to modify the `basic-mingw-w64-32.cmake`/`basic-mingw-w64-64.cmake`
files and `CMAKE_INSTALL_PREFIX` to suit your distribution filesystem
hierarchy and specify path where Corrade is installed in `CMAKE_PREFIX_PATH`.

    mkdir build-mingw-w64-32 && cd build-mingw-w64-32
    cmake .. \
        -DCMAKE_TOOLCHAIN_FILE=../toolchains/archlinux/basic-mingw-w64-32.cmake \
        -DCMAKE_INSTALL_PREFIX=/usr/i686-w64-mingw32
    cmake --build .

    mkdir build-mingw-w64-64 && cd build-mingw-w64-64
    cmake .. \
        -DCMAKE_TOOLCHAIN_FILE=../toolchains/archlinux/basic-mingw-w64-64.cmake \
        -DCMAKE_INSTALL_PREFIX=/usr/x86_64-w64-mingw32
    cmake --build .

Then you can install the package using `cmake --build . --target install` to
make it available for depending projects.

@subsection building-cross-nacl Crosscompiling for Google Chrome Native Client

You will need [Native Client SDK](https://developers.google.com/native-client/beta/sdk/download).
Tested version is `pepper_22`.

You can choose from either `glibc` or `newlib` toolchain. `Newlib` supports
only static linking, thus `BUILD_STATIC` is always enabled. Don't forget to
adapt `NACL_PREFIX` variable in `generic/NaCl-*-x86-32.cmake` and
`generic/NaCl-*-x86-64.cmake` to path where your SDK is installed. Default is
`/usr/nacl`. You may need to adapt also `NACL_TOOLCHAIN_PATH` so CMake is able
to find the compiler. NaCl currently supports only OpenGL ES 2, thus
`TARGET_GLES` and `TARGET_GLES2` is always enabled.

Then create build directories for x86-32 and x86-64 and run cmake and build
command in them. Be sure to adapt `CMAKE_INSTALL_PREFIX` to the same value as
in `NACL_PREFIX` in toolchain file and specify path where Corrade is installed
in `CMAKE_PREFIX_PATH`.

    mkdir build-nacl-x86-32 && cd build-nacl-x86-32
    cmake .. \
        -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/NaCl-newlib-x86-32.cmake" \
        -DCMAKE_BUILD_TYPE=Release \
        -DCMAKE_PREFIX_PATH=/usr/nacl \
        -DCMAKE_INSTALL_PREFIX=/usr/nacl \
        -DWITH_NACLAPPLICATION=ON \
        -DLIB_SUFFIX=/32
    cmake --build .

    mkdir build-nacl-x86-64 && cd build-nacl-x86-64
    cmake .. \
        -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/NaCl-newlib-x86-64.cmake" \
        -DCMAKE_BUILD_TYPE=Release \
        -DCMAKE_PREFIX_PATH=/usr/nacl \
        -DCMAKE_INSTALL_PREFIX=/usr/nacl \
        -DWITH_NACLAPPLICATION=ON
    cmake --build .

Then you can install both versions using `cmake --build . --target install` to
make them available for depending projects. The headers are shared by both
versions.

For ArchLinux there are also prepared package files in `package/archlinux`,
named `PKGBUILD-nacl-glibc` and `PKGBUILD-nacl-newlib`, see
@ref building-packages-arch "above" for more information.

See @ref Platform::NaClApplication documentation for more information about
building your projects for Google Chrome Native Client.

@subsection building-cross-emscripten Crosscompiling for Emscripten

You will need [Emscripten](https://github.com/kripken/emscripten/wiki/Tutorial)
installed and configured.

Don't forget to adapt `EMSCRIPTEN_PREFIX` variable in `generic/Emscripten.cmake`
to path where Emscripten is installed. Default is `/usr/lib/emscripten`.
Emscripten supports dynamic libraries only to simplify porting and they are
generally slower, thus `BUILD_STATIC` is implicitly enabled.

Then create build directory and run cmake and build command in it. Be sure to
set `CMAKE_INSTALL_PREFIX` to path contained in `EMSCRIPTEN_TOOLCHAIN_PATH`.

WebGL 1.0 (GLES 2.0 equivalent) is enabled by default, switch to 2.0 (GLES 3.0
equivalent) by disabling `TARGET_GLES2`.

    mkdir build-emscripten && cd build-emscripten
    cmake .. \
        -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/Emscripten.cmake" \
        -DCMAKE_BUILD_TYPE=Release \
        -DCMAKE_PREFIX_PATH=/usr/lib/emscripten/system \
        -DCMAKE_INSTALL_PREFIX=/usr/lib/emscripten/system \
        -DWITH_SDL2APPLICATION=ON
    cmake --build .

Then you can install the library using `cmake --build . --target install` to
make it available for depending projects.

If you have Node.js installed, you can also build and run unit tests using
`ctest`. See `BUILD_TESTS` above.

For ArchLinux there is also prepared package file in `package/archlinux`,
named `PKGBUILD-emscripten`, see @ref building-packages-arch "above" for more
information.

See @ref Platform::Sdl2Application documentation for more information about
building your projects for Emscripten.

@subsection building-cross-ios Crosscompiling for iOS

You will need OSX and Xcode installed.

Set `CMAKE_OSX_ROOT` to SDK you want to target and enable all desired
architectures in `CMAKE_OSX_ARCHITECTURES`. Be sure to set `CMAKE_INSTALL_PREFIX`
to prefix where you store other iOS dependencies such as Corrade or SDL2.

As every application is in its own sandbox, it doesn't make sense to build
shared libraries (although it is supported). Enable `BUILD_STATIC` to build
static libraries. You might also have problems using dynamic plugins, enable
`BUILD_PLUGINS_STATIC` to build also plugins as static. OpenGL ES 2.0 is
enabled by default, switch to 3.0 by disabling `TARGET_GLES2`.

Please note that `BUILD_MULTITHREADED` is supported only since Xcode 7.3 and
doesn't work on `i386` iOS Simulator, you need to disable it in order to build
for older platforms.

    mkdir build-ios && cd build-ios
    cmake .. \
        -DCMAKE_TOOLCHAIN_FILE=../toolchains/generic/iOS.cmake \
        -DCMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk \
        -DCMAKE_OSX_ARCHITECTURES="arm64;armv7;armv7s" \
        -DCMAKE_INSTALL_PREFIX=~/ios-libs \
        -DBUILD_STATIC=ON -DBUILD_PLUGINS_STATIC=ON \
        -DTARGET_GLES2=OFF \
        -DWITH_SDL2APPLICATION=ON \
        -G Xcode
    cmake --build .

Then you can install the library using `cmake --build . --target install` to
make it available for depending projects.

See @ref Platform::Sdl2Application documentation for more information about
building your projects for iOS.

@subsection building-cross-android Crosscompiling for Android ARM and x86

You will need [Android NDK](https://developer.android.com/tools/sdk/ndk/index.html)
installed and configured.

Don't forget to adapt `ANDROID_NDK_ROOT` in `generic/Android-*.cmake` to path
where NDK is installed. Default is `/opt/android-ndk`. Adapt also
`ANDROID_SYSROOT` to your preferred API level. You might also need to update
`ANDROID_TOOLCHAIN_PREFIX` and `ANDROID_TOOLCHAIN_ROOT` to fit your system.

Then create build directory and run cmake and build command in it. Be sure to
set `CMAKE_INSTALL_PREFIX` to `/usr` subdirectory of `ANDROID_SYSROOT` and
specify path where Corrade is installed in `CMAKE_PREFIX_PATH`.

Note that `BUILD_STATIC` is implicitly enabled, because manually loading all
depending shared libraries using JNI would be too inconvenient. The engine is
built for OpenGL ES 2.0 by default, switch  to 3.0 by disabling `TARGET_GLES2`.

    mkdir build-android-arm && cd build-android-arm
    cmake .. \
        -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/Android-ARM.cmake" \
        -DCMAKE_BUILD_TYPE=Release \
        -DCMAKE_PREFIX_PATH=/opt/android-ndk/platforms/android-19/arch-arm/usr \
        -DCMAKE_INSTALL_PREFIX=/opt/android-ndk/platforms/android-19/arch-arm/usr \
        -DTARGET_GLES=ON -DTARGET_GLES2=OFF \
        -DWITH_ANDROIDAPPLICATION=ON
    cmake --build .

    mkdir build-android-x86 && cd build-android-x86
    cmake .. \
        -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/Android-x86.cmake" \
        -DCMAKE_BUILD_TYPE=Release \
        -DCMAKE_PREFIX_PATH=/opt/android-ndk/platforms/android-19/arch-x86/usr \
        -DCMAKE_INSTALL_PREFIX=/opt/android-ndk/platforms/android-19/arch-x86/usr \
        -DTARGET_GLES=ON -DTARGET_GLES2=OFF \
        -DWITH_ANDROIDAPPLICATION=ON
    cmake --build .

Then you can install the library using `cmake --build . --target install` to
make it available for depending projects.

For ArchLinux there are also prepared package files in `package/archlinux`,
named `PKGBUILD-android-arm` and `PKGBUILD-android-x86`, see
@ref building-packages-arch "above" for more information.

See @ref Platform::AndroidApplication documentation for more information about
building your projects for Android.

@section building-ci Continuous Integration

@subsection building-ci-travis Travis

In `package/ci/` there is `travis.yml` file with Linux GCC 4.7, OSX Clang, iOS
GLES2/GLES3 and Emscripten WebGL1/WebGL2 configuration. Online at
https://travis-ci.org/mosra/magnum. The Linux build has code coverage reports
available online at https://coveralls.io/github/mosra/magnum.

@subsection building-ci-appveyor AppVeyor

In `package/ci/` there is `appveyor.yml` file with Windows desktop MSVC, MinGW
and Windows RT GLES2/GLES3 configuration. Online at https://ci.appveyor.com/project/mosra/magnum.

@subsection building-ci-jenkins Jenkins

In `package/ci/` there are `jenkins.xml` and `jenkins-gltests.xml` files
containing job configuration, one for build and non-GL tests and the other for
GL tests only. Setup your Jenkins server, enable the **Git** and **Text-finder**
plugin and download the CLI application from here (replace `localhost:8080`
with your server name):

    http://localhost:8080/cli

Then add new jobs or update existing ones (update path to the `*.jar` file,
replace `localhost:8080` with your server name, replace `update-job` with
`create-job` if the job doesn't exist yet).

    java -jar ~/jenkins-cli.jar -s http://localhost:8080 update-job Magnum < package/ci/jenkins.xml
    java -jar ~/jenkins-cli.jar -s http://localhost:8080 update-job Magnum-GLTests < package/ci/jenkins-gltests.xml

Build is done using **Ninja** build system and everything possible is enabled,
thus you need also **SDL2**, **GLFW**, **GLUT** and **OpenAL** libraries. It
expects that **GCC** >= 4.9, 4.8, 4.7 and **Clang** are installed and there
are **OpenGL**, **OpenGL ES 2.0** and **OpenGL ES 3.0** librares as it tries to
compile the library with every combination of them. You can add/remove the axes
in `axes/hudson.matrix.TextAxis` or via the web interface later.

Magnum-GLTests depend on active X11 session, thus they should be run from
Jenkins instance running on graphical user session.

Clang Analyzer and *Sanitizer checks are also available. They both require **Clang**,
Analyzer job additionally requires **clang-analyzer** tool.

    java -jar ~/jenkins-cli.jar -s http://localhost:8080 update-job Magnum-ClangAnalyzer < package/ci/jenkins-clang-analyzer.xml
    java -jar ~/jenkins-cli.jar -s http://localhost:8080 update-job Magnum-ClangSanitizer < package/ci/jenkins-clang-sanitizer.xml
    java -jar ~/jenkins-cli.jar -s http://localhost:8080 update-job Magnum-ClangSanitizer-GLTests < package/ci/jenkins-clang-sanitizer-gltests.xml

There is also MinGW-w64, Emscripten, NaCl and Android configuration, add or
update them with the commands below. See @ref building-crosscompiling for more
information about setting up the crosscompilers and `toolchains/` submodule.
For Emscripten you need also **Node.js** installed to run the tests.

    java -jar ~/jenkins-cli.jar -s http://localhost:8080 update-job Magnum-MinGW-w64 < package/ci/jenkins-mingw-w64.xml
    java -jar ~/jenkins-cli.jar -s http://localhost:8080 update-job Magnum-Emscripten < package/ci/jenkins-emscripten.xml
    java -jar ~/jenkins-cli.jar -s http://localhost:8080 update-job Magnum-NaCl < package/ci/jenkins-nacl.xml
    java -jar ~/jenkins-cli.jar -s http://localhost:8080 update-job Magnum-Android < package/ci/jenkins-android.xml
*/

}