/* This file is part of Magnum. Copyright © 2010, 2011, 2012, 2013 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 support everything needed: **GCC** >= 4.6 and **Clang** >= 3.1. On Windows you can use **MinGW**, Visual Studio compiler still lacks some needed features. - **CMake** >= 2.8.8 - **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 @section building-compilation Compilation, installation @subsection building-linux Via command-line (on Linux/Unix) On Unix-based OSs, the library (for example with support for GLUT applications) can be built and installed using these four commands: mkdir -p build && cd build cmake .. \ -DCMAKE_INSTALL_PREFIX=/usr \ -DWITH_GLUTAPPLICATION=ON make make install The library provides a lot of CMake options (described in sections later). They can be passed to CMake either as `-Dname=value` parameters on command-line (like above) or set conveniently using `cmake-gui`: cd build cmake-gui . @subsection building-windows Using QtCreator and CMake GUI (on Windows) On Windows, if you don't want to touch the command-line, the easiest way is to install QtCreator (just QtCreator, you don't need the full Qt SDK) and configure it to use MinGW and CMake. For most convenient usage it's best to install (or copy/paste) all library dependencies into directory where MinGW is installed (e.g. `C:/MinGW/`), following proper filesystem hierarchy, i.e. headers into `include/` and binaries into `bin/` or `lib/`. CMake will then have no problem finding them and you won't need to explicitly specify path to each one. Then just open project's root `CMakeLists.txt` file within QtCreator. It then asks you where to create build directory, allows you to specify initial CMake parameters and then you can just press Configure and everything should be ready to be built. You might need to set some CMake parameters before configuring, they can be set with `-Dname=value`. See below for more information. After the initial import you might want to reconfigure some CMake variables (more information below). Start CMake GUI, point it to the recently created build dir, modify the variables and press Generate. QtCreator will detect the changes and reparse the project accordingly. For most convenient usage it's best to set `CMAKE_INSTALL_PREFIX` to directory where MinGW is installed (e.g. `C:/MinGW/`) and add `C:/MinGW/bin` and `C:/MinGW/lib` to `PATH`. Installation to given prefix can be then done from within QtCreator by adding new `make install` build rule. @subsubsection building-windows-troubleshooting Windows troubleshooting If CMake isn't able to find dependencies (e.g. Corrade is not found) and you have installed them to MinGW directory, point to `CMAKE_FIND_ROOT_PATH` to MinGW installation prefix, e.g. specify `-DCMAKE_FIND_ROOT_PATH=C:/MinGW/` CMake parameter. See also Corrade's @ref building-corrade-windows-troubleshooting "troubleshooting section". @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. %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`. 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 src/Magnum.h for more information. See also @ref corrade-cmake and @ref src/Corrade.h for additional information. 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_AUDIO` - Audio library. Requires **OpenAL** library. - `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. - `WITH_MAGNUMINFO` - `magnum-info` executable, provides information about the engine and OpenGL capabilities. - `WITH_DISTANCEFIELDCONVERTER` - `magnum-distancefield` executable for converting black&white images to distance field textures. Enables also building of TextureTools library. 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". Available only if targetting desktop OpenGL or ES desktop emulation, not available on Google Chrome Native Client or Emscripten. Requires **X11** and **GLX** libraries. - `WITH_NACLAPPLICATION` - @ref Platform::NaClApplication "NaClApplication", available only if targeting Google Chrome Native Client. - `WITH_SDL2APPLICATION` - @ref Platform::Sdl2Application "Sdl2Application". Available also on Emscripten, but not on Google Chrome Native Client. Requires **SDL2** library. - `WITH_XEGLAPPLICATION` - @ref Platform::XEglApplication "XEglApplication", available only if targeting OpenGL ES (see above). Not available on Google Chrome Native Client or Emscripten. Requires **X11** and **EGL** libraries. - `WITH_WINDOWLESSGLXAPPLICATION` - @ref Platform::WindowlessGlxApplication "WindowlessGlxApplication". Available only if targetting desktop OpenGL or ES desktop emulation, not available on Google Chrome Native Client or Emscripten. Requires **X11** and **GLX** libraries. - `WITH_WINDOWLESSNACLAPPLICATION` - @ref Platform::WindowlessNaClApplication "WindowlessNaClApplication", available only if targeting Google Chrome Native Client. @subsection building-tests Building and running unit tests If you want to build also unit tests (which are not built by default), enable `BUILD_TEST` 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 above for more information. @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. @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 PKGBUILD for Git development build. The package is also in AUR under the same name. There are also a few development PKGBUILDs in project root, which allow you to build and install the package directly from source tree without downloading anything. The native PKGBUILD also contains `check()` function which will run all unit tests before packaging. If you want to build with another compiler (e.g. Clang), run makepkg this way: CXX=clang++ makepkg Development PKGBUILDs can detect when Clang is used and remove unsupported CXX flags. @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 root, named `PKGBUILD-mingw32`. 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 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. @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 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`. */ }