magnum/doc/building.dox

/*
    This file is part of Magnum.

    Copyright © 2010, 2011, 2012, 2013 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.

%Magnum can be downloaded from GitHub and built either
@ref building-compilation "manually" or using already prepared packaging files,
currently only @ref building-arch "ArchLinux PKGBUILDs". Guide how to
crosscompile for @ref building-win "Windows" and
@ref building-nacl "Google Chrome Native Client" is also available.

@tableofcontents

Minimal set of tools and libraries required for building is:

- C++ compiler with good C++11 support. Currently there are two compilers
  which are tested to support everything needed: **GCC** >= 4.6 and **Clang**
  >= 3.1.
- **CMake** >= 2.8.8 (needed for `OBJECT` library target)
- **GLEW** - OpenGL extension wrangler (only if targeting desktop OpenGL)
- **Corrade** - Plugin management and utility library. See
  @ref building-corrade "Corrade download and installation guide" for more
  information.

@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 toolchains for crosscompiling, run also the following commands, or,
if you build from source archive, download snapshot of toolchains repository
from https://github.com/mosra/toolchains and put them in `toolchains/`
subdirectory.

    git submodule init
    git submodule update

@section building-compilation Compilation, installation

The library (for example with support for GLUT applications) can be built and
installed using these four commands. See below for more information about
optional features.

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

The libraries are build as shared by default, pass `-DBUILD_STATIC=ON` to build
them as static. If you plan them to use with shared libraries later, enable
also position-independent code with `-DBUILD_STATIC_PIC=ON`. If you want to
build with another compiler (e.g. Clang), pass `-DCMAKE_CXX_COMPILER=clang++`
to CMake.

@subsection building-optional Enabling or disabling features

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, as no customer OpenGL ES 3.0 platform exists yet.
 - `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.

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

 - `WITH_DEBUGTOOLS` - DebugTools library. Enables also building of MeshTools,
   Primitives, SceneGraph, Shaders and Shapes libraries.
 - `WITH_MESHTOOLS` - MeshTools library. Enabled automatically if `WITH_DEBUGTOOLS`
   is enabled.
 - `WITH_PRIMITIVES` - Primitives library. Enabled automatically if `WITH_DEBUGTOOLS`
   is enabled.
 - `WITH_SCENEGRAPH` - SceneGraph library. Enabled automatically if `WITH_DEBUGTOOLS`
   or `WITH_SHAPES` is enabled.
 - `WITH_SHADERS` - Shaders library. Enabled automatically if `WITH_DEBUGTOOLS`
   is enabled.
 - `WITH_SHAPES` - Shapes library. Enables also building of SceneGraph library.
   Enabled automatically if `WITH_DEBUGTOOLS` is enabled.
 - `WITH_TEXT` - Text library. Enables also building of TextureTools library.
 - `WITH_TEXTURETOOLS` - TextureTools library. Enabled automatically if `WITH_TEXT`
   is enabled.
 - `WITH_MAGNUMINFO` - `magnum-info` executable, provides information about the
   engine and OpenGL capabilities.

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_GLUTAPPLICATION` - @ref Platform::GlutApplication "GlutApplication",
  available only if targeting desktop OpenGL. Requires **GLUT** library.
- `WITH_GLXAPPLICATION` - @ref Platform::GlxApplication "GlxApplication".
  Requires **X11** and **GLX** libraries.
- `WITH_NACLAPPLICATION` - @ref Platform::NaClApplication "NaClApplication",
  available only if targeting Google Chrome Native Client (see below).
- `WITH_SDL2APPLICATION` - @ref Platform::Sdl2Application "Sdl2Application".
  Requires **SDL2** library.
- `WITH_XEGLAPPLICATION` - @ref Platform::XEglApplication "XEglApplication",
  available only if targeting OpenGL ES (see above). Requires **X11** and
  **EGL** libraries.
- `WITH_WINDOWLESSGLXAPPLICATION` - @ref Platform::WindowlessGlxApplication "WindowlessGlxApplication".
  Requires **X11** and **GLX** libraries.

@subsection building-tests Building and running unit tests

If you want to build also unit tests (which are not built by default), pass
`-DBUILD_TESTS=ON` to CMake. Unit tests use Corrade's @ref Corrade::TestSuite
"TestSuite" framework and can be run using

    ctest --output-on-failure

in build directory. Everything should pass ;-)

@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 **Graphviz** for class diagrams and  **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.

@section building-arch Building ArchLinux packages

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

There is also development PKGBUILD and MinGW development PKGBUILD in root,
which allows you to build and install the package directly from source tree
without downloading anything. The PKGBUILD also contains `check()` function
which will run all unit tests before packaging. Note that the unit tests
require Qt, as said above.

If you want to build with another compiler (e.g. Clang), run makepkg this way:

    CXX=clang++ makepkg

Both development PKGBUILDs can detect when Clang is used and remove
unsupported CXX flags.

@section building-win Crosscompiling for Windows using MinGW

@note This guide is tailored mainly for crosscompiling from ArchLinux. For
this system there is also prepared `mingw32-magnum` development package in
root, named `PKGBUILD-mingw32`.

You will need MinGW32 versions of the compiler and all libraries (GLEW,
Corrade), i.e. these ArchLinux packages:

- `mingw32-gcc`, which depends on `mingw32-w32api` containing OpenGL headers
- `mingw32-runtime`
- `mingw32-glew`
- `mingw32-corrade`

Make sure you have `toolchains` submodule updated, as
@ref building-download "explained above". Then create build directory and run
cmake and make. You may need to modify the `basic-mingw32.cmake` file and
`CMAKE_INSTALL_PREFIX` to suit your distribution filesystem hierarchy.

    mkdir build-win
    cd build-win
    cmake .. \
        -DCMAKE_TOOLCHAIN_FILE=../toolchains/archlinux/basic-mingw32.cmake \
        -DCMAKE_INSTALL_PREFIX=/usr/i486-mingw32
    make

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

@section building-nacl Compiling 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`.

Make sure you have `toolchains` submodule updated, as
@ref building-download "explained above". 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 make in
them. The toolchains need access to its platform file, so be sure to properly
set **absolute** path to `modules/` directory containing `Platform/NaCl.cmake`.
Also adapt `CMAKE_INSTALL_PREFIX` to the same value as in `NACL_PREFIX` in
toolchain file.

    mkdir -p build-nacl-x86-32
    cd build-nacl-x86-32
    cmake .. \
        -DCMAKE_MODULE_PATH="/absolute/path/to/toolchains/modules" \
        -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/NaCl-glibc-x86-32.cmake" \
        -DCMAKE_BUILD_TYPE=Release \
        -DCMAKE_INSTALL_PREFIX=/usr/nacl \
        -DWITH_NACLAPPLICATION=ON \
        -DLIB_SUFFIX=/32
    make

    mkdir -p build-nacl-x86-64
    cd build-nacl-x86-64
    cmake .. \
        -DCMAKE_MODULE_PATH="/absolute/path/to/toolchains/modules" \
        -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/NaCl-glibc-x86-64.cmake" \
        -DCMAKE_BUILD_TYPE=Release \
        -DCMAKE_INSTALL_PREFIX=/usr/nacl \
        -DWITH_NACLAPPLICATION=ON
    make

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

For ArchLinux there are also prepared package files in root, named
`PKGBUILD-nacl-glibc` and `PKGBUILD-nacl-newlib`.

*/
}