/* This file is part of Magnum. Copyright © 2010, 2011, 2012, 2013, 2014 Vladimír Vondruš 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. Currently there are two compilers which are tested to have everything needed: **GCC** >= 4.7 and **Clang** >= 3.1. On Windows you can use **MinGW**. 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.8 - **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. @subsection building-windows Building on Windows On Windows you can use either MinGW 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, the `C:/MinGW` directory is in most cases already prepared for exactly this. When running CMake, set `CMAKE_INSTALL_PREFIX` parameter to that directory so CMake knows where to look for installed libraries and where to install new ones. @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 and 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_FIND_ROOT_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. If you plan to use them 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. %Magnum by default does not install `FindMagnum.cmake`, as you should bundle the module with your code instead of depending on it being in system location. You can install it by enabling `WITH_FIND_MODULE`. 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, 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. 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 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` - Audio library. Depends on **OpenAL** library, not built by default. - `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` 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_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_WINDOWLESSGLXAPPLICATION` - @ref Platform::WindowlessGlxApplication "WindowlessGlxApplication" - `WITH_WINDOWLESSNACLAPPLICATION` - @ref Platform::WindowlessNaClApplication "WindowlessNaClApplication" - `WITH_WINDOWLESSWGLAPPLICATION` - @ref Platform::WindowlessWglApplication "WindowlessWglApplication" 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` - `magnum-info` executable, provides information about the engine and OpenGL capabilities. - `WITH_FONTCONVERTER` - `magnum-fontconverter` executable for converting fonts to raster ones. Enables also building of Text library. - `WITH_DISTANCEFIELDCONVERTER` - `magnum-distancefieldconverter` executable for converting black&white images to distance field textures. Enables also building of TextureTools 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. Platforms which have windowless context creation implemented (currently only desktop Linux) can build also tests for OpenGL functionality. You can enable them with `BUILD_GL_TESTS`. @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. You need to build them from project root: makepkg -p package/archlinux/ @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 packages installed and in addition also `dpkg-dev` package. Building is easy, just change directory to package root, copy `package/debian` directory there and run `dpkg-buildpackage`: cp -r 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`. @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 @subsection building-cross-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 `package/archlinux`, named `PKGBUILD-mingw32`. See @ref building-packages-arch "above" for more information. You will need MinGW32 versions of the compiler and all dependent libraries (Corrade), i.e. these ArchLinux packages: - `mingw32-gcc`, which depends on `mingw32-w32api` containing OpenGL headers - `mingw32-runtime` - `mingw32-corrade` Then create build directory and run cmake and build command in it. 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 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. The toolchains need access to the 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 build-nacl-x86-32 && cd build-nacl-x86-32 cmake .. \ -DCMAKE_MODULE_PATH="/absolute/path/to/toolchains/modules" \ -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/NaCl-newlib-x86-32.cmake" \ -DCMAKE_BUILD_TYPE=Release \ -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_MODULE_PATH="/absolute/path/to/toolchains/modules" \ -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/NaCl-newlib-x86-64.cmake" \ -DCMAKE_BUILD_TYPE=Release \ -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. @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/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. The toolchain needs access to its platform file, so be sure to properly set **absolute** path to `modules/` directory containing `Platform/Emscripten.cmake`. Also set `CMAKE_INSTALL_PREFIX` to path contained in `EMSCRIPTEN_TOOLCHAIN_PATH`. mkdir build-emscripten && cd build-emscripten cmake .. \ -DCMAKE_MODULE_PATH="/absolute/path/to/toolchains/modules" \ -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/Emscripten.cmake" \ -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_INSTALL_PREFIX=/usr/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. @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. The toolchain needs access to its platform file, so be sure to properly set **absolute** path to `modules/` directory containing `Platform/Android.cmake`. Also set `CMAKE_INSTALL_PREFIX` to `/usr` subdirectory of `ANDROID_SYSROOT`. Note that `BUILD_STATIC` is implicitly enabled, because manually loading all depending shared libraries using JNI would be too inconvenient. Decision between OpenGL ES 2.0 and ES 3.0 is left up to the user (i.e. you need to set `TARGET_GLES2` to `ON` or `OFF`). mkdir build-android-arm && cd build-android-arm cmake .. \ -DCMAKE_MODULE_PATH="/absolute/path/to/toolchains/modules" \ -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/Android-ARM.cmake" \ -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_INSTALL_PREFIX=/opt/android-ndk/platforms/android-19/arch-arm/usr \ -DTARGET_GLES=ON -DTARGET_GLES2=ON cmake --build . mkdir build-android-x86 && cd build-android-x86 cmake .. \ -DCMAKE_MODULE_PATH="/absolute/path/to/toolchains/modules" \ -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/Android-x86.cmake" \ -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_INSTALL_PREFIX=/opt/android-ndk/platforms/android-19/arch-x86/usr \ -DTARGET_GLES=ON -DTARGET_GLES2=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. @section building-ci-jenkins Jenkins Continuous Integration 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: http://your-jenkins-server/cli Then add new jobs or update existing ones (replace `` with `create-job` or `update-job`). java -jar jenkins-cli.jar -s http://your-jenkins-server Magnum < jenkins.xml java -jar jenkins-cli.jar -s http://your-jenkins-server Magnum-GLTests < jenkins-gltests.xml Build is done using **Ninja** build system and everything possible is enabled, thus you need also **SDL2**, **GLUT** and **OpenAL** libraries. It expects that **GCC** >= 4.8.1, 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. There is also MinGW32, MinGW-w64, Emscripten and NaCl 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://your-jenkins-server Magnum-MinGW32 < jenkins-mingw32.xml java -jar jenkins-cli.jar -s http://your-jenkins-server Magnum-MinGW-w64 < jenkins-mingw-w64.xml java -jar jenkins-cli.jar -s http://your-jenkins-server Magnum-Emscripten < jenkins-emscripten.xml java -jar jenkins-cli.jar -s http://your-jenkins-server Magnum-NaCl < jenkins-nacl.xml */ }