magnum/doc/building.dox

/** @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
@ref building-win "crosscompile for Windows" 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)
- **OpenGL** headers, on Linux most probably shipped with Mesa or
  **OpenGL ES 2** headers, if targetting OpenGL ES 2.
- **GLEW** - OpenGL extension wrangler
- **Corrade** - Plugin management and utility library. You can get it at
  http://github.com/mosra/corrade or at http://mosra.cz/blog/corrade.php.

@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 can be built and installed using these four commands:

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

By default the engine is built for desktop OpenGL. If you want to target
OpenGL ES 2, pass `-DTARGET_GLES=True` to CMake.

If you want to build with another compiler (e.g. Clang), pass
`-DCMAKE_CXX_COMPILER=clang++` to CMake.

@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=True` to CMake. Unit tests use QtTest framework (you need at
least **Qt 4.6**) and can be run using

    ctest -V

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.

@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 (OpenGL
headers, 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:

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

You may need to modify the `basic-mingw32.cmake` file and
`CMAKE_INSTALL_PREFIX` to suit your distribution filesystem hierarchy. If
everything goes well, in `build-win/` subdirectories will be the DLLs.
*/