mirror of https://github.com/mosra/magnum.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
254 lines
11 KiB
254 lines
11 KiB
/* |
|
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, |
|
Physics, Primitives, SceneGraph and Shaders libraries. |
|
- `WITH_MESHTOOLS` - MeshTools library. Enabled automatically if `WITH_DEBUGTOOLS` |
|
is enabled. |
|
- `WITH_PHYSICS` - Physics library. Enables also building of SceneGraph |
|
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_PHYSICS` is enabled. |
|
- `WITH_SHADERS` - Shaders 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`. |
|
|
|
*/ |
|
}
|
|
|