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.
239 lines
12 KiB
239 lines
12 KiB
/* |
|
This file is part of Magnum. |
|
|
|
Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016 |
|
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 cmake Usage with CMake |
|
@brief Guide how to find and use Magnum with CMake build system |
|
|
|
@tableofcontents |
|
|
|
Magnum uses CMake build system for both building and integration into your |
|
projects. The logic is in module `FindMagnum.cmake` distributed with the engine |
|
in `modules/` directory, you are encouraged to copy it along with |
|
`FindCorrade.cmake` into your project and add path to the files to |
|
`CMAKE_MODULE_PATH`. Otherwise, if CMake won't be able to find this file in |
|
predefined locations, it will error out even if Magnum might be installed on |
|
the system. If you plan to use Magnum on OpenGL ES, you may also need |
|
`FindOpenGLES2.cmake` or `FindOpenGLES3.cmake` and in some cases also |
|
`FindEGL.cmake`. |
|
|
|
Note that the module files are updated as the library evolves, you are |
|
encouraged to update your copies from time to time to avoid strange building |
|
issues. |
|
|
|
If you installed the library or its dependencies to non-standard location |
|
(other than `/usr`, e.g. `/home/xyz/projects`), set `CMAKE_PREFIX_PATH` to that |
|
directory to help CMake find it. You can enter more different dirs if you |
|
separate them with semicolons. |
|
|
|
Basic usage is: |
|
|
|
find_package(Magnum REQUIRED) |
|
|
|
This module tries to find base Magnum library and then defines: |
|
|
|
- `Magnum_FOUND` -- Whether the library was found |
|
- `Magnum::Magnum` -- Base library imported target |
|
- `MAGNUM_PLUGINS_DEBUG_DIR` -- Base directory with dynamic plugins for debug |
|
builds, defaults to `magnum-d/` subdirectory of dir where Magnum library |
|
was found |
|
- `MAGNUM_PLUGINS_RELEASE_DIR` -- Base directory with dynamic plugins for |
|
release builds, defaults to `magnum/` subdirectory of dir where Magnum |
|
library was found |
|
- `MAGNUM_PLUGINS_DIR` -- Base directory with dynamic plugins, defaults to |
|
`MAGNUM_PLUGINS_RELEASE_DIR` in release builds and multi-configuration |
|
builds or to `MAGNUM_PLUGINS_DEBUG_DIR` in debug builds. You can modify all |
|
three variable (e.g. set them to `.` when deploying on Windows with plugins |
|
stored relatively to the executable), the following `MAGNUM_PLUGINS_*_DIR` |
|
variables depend on it. |
|
- `MAGNUM_PLUGINS_FONT[|_DEBUG|_RELEASE]_DIR` -- Directory with dynamic font |
|
plugins |
|
- `MAGNUM_PLUGINS_FONTCONVERTER[|_DEBUG|_RELEASE]_DIR` -- Directory with |
|
dynamic font converter plugins |
|
- `MAGNUM_PLUGINS_IMAGECONVERTER[|_DEBUG|_RELEASE]_DIR` -- Directory with |
|
dynamic image converter plugins |
|
- `MAGNUM_PLUGINS_IMPORTER[|_DEBUG|_RELEASE]_DIR` -- Directory with dynamic |
|
importer plugins |
|
- `MAGNUM_PLUGINS_AUDIOIMPORTER[|_DEBUG|_RELEASE]_DIR` -- Directory with |
|
dynamic audio importer plugins |
|
|
|
However, this command will try to find only the base library, not the optional |
|
components. The base library depends on Corrade and OpenGL libraries (or |
|
OpenGL ES libraries). Additional dependencies are specified by the components. |
|
The optional components are: |
|
|
|
- `Audio` -- @ref Audio library |
|
- `DebugTools` -- @ref DebugTools library |
|
- `MeshTools` -- @ref MeshTools library |
|
- `Primitives` -- @ref Primitives library |
|
- `SceneGraph` -- @ref SceneGraph library |
|
- `Shaders` -- @ref Shaders library |
|
- `Shapes` -- @ref Shapes library |
|
- `Text` -- @ref Text library |
|
- `TextureTools` -- @ref TextureTools library |
|
|
|
Platform namespace is split into more components: |
|
|
|
- `GlfwApplication` -- @ref Platform::GlfwApplication "GlfwApplication" |
|
- `GlutApplication` -- @ref Platform::GlutApplication "GlutApplication" |
|
- `GlxApplication` -- @ref Platform::GlxApplication "GlxApplication" |
|
- `NaClApplication` -- @ref Platform::NaClApplication "NaClApplication" |
|
- `Sdl2Application` -- @ref Platform::Sdl2Application "Sdl2Application" |
|
- `XEglApplication` -- @ref Platform::XEglApplication "XEglApplication" |
|
- `WindowlessCglApplication` -- @ref Platform::WindowlessCglApplication "WindowlessCglApplication" |
|
- `WindowlessEglApplication` -- @ref Platform::WindowlessEglApplication "WindowlessEglApplication" |
|
- `WindowlessGlxApplication` -- @ref Platform::WindowlessGlxApplication "WindowlessGlxApplication" |
|
- `WindowlessIosApplication` -- @ref Platform::WindowlessIosApplication "WindowlessIosApplication" |
|
- `WindowlessNaClApplication` -- @ref Platform::WindowlessNaClApplication "WindowlessNaClApplication" |
|
- `WindowlessWglApplication` -- @ref Platform::WindowlessWglApplication "WindowlessWglApplication" |
|
- `WindowlessWindowsEglApplication` -- @ref Platform::WindowlessWindowsEglApplication "WindowlessWindowsEglApplication" |
|
|
|
For manual context creation (without application wrappers) there are also |
|
platform-specific context libraries (see @ref platform-custom for more |
|
information): |
|
|
|
- `CglContext` -- CGL context |
|
- `EglContext` -- EGL context |
|
- `GlxContext` -- GLX context |
|
- `WglContext` -- WGL context |
|
|
|
The library also contains a set of plugins for importing essential file |
|
formats. Additional plugins are provided in separate plugin repository, see |
|
@ref cmake-plugins for more information. If you are going to use dynamic |
|
plugins (the default) via plugin manager, they don't need to be handled via |
|
CMake. The manager will look for them at runtime at specified location and |
|
loads them dynamically. However, if they are built as static (see |
|
@ref building-plugins for more information), they need to be linked into the |
|
executable and then explicitly imported. Also if you are going to use them as |
|
dependencies, you need to find the dependency and then link to it. |
|
|
|
- `MagnumFont` -- @ref Text::MagnumFont "MagnumFont" plugin |
|
- `MagnumFontConverter` -- @ref Text::MagnumFontConverter "MagnumFontConverter" |
|
plugin |
|
- `ObjImporter` -- @ref Trade::ObjImporter "ObjImporter" plugin |
|
- `TgaImageConverter` -- @ref Trade::TgaImageConverter "TgaImageConverter" |
|
plugin |
|
- `TgaImporter` -- @ref Trade::TgaImporter "TgaImporter" plugin |
|
- `WavAudioImporter` -- @ref Audio::WavImporter "WavAudioImporter" plugin |
|
|
|
Lastly, a few utility executables are available: |
|
|
|
- `distancefieldconverter` -- @ref magnum-distancefieldconverter executable |
|
- `fontconverter` -- @ref magnum-fontconverter executable |
|
- `info` -- @ref magnum-info executable |
|
|
|
Note that [each namespace](namespaces.html), all @ref Platform libraries and |
|
each plugin class 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. |
|
|
|
Example usage with specifying additional components is: |
|
|
|
find_package(Magnum REQUIRED MeshTools Primitives Sdl2Application) |
|
|
|
For each component is then defined: |
|
|
|
- `Magnum_*_FOUND` -- Whether the component was found |
|
- `Magnum::*` -- Component imported target |
|
|
|
If exactly one `*Application` or exactly one `Windowless*Application` component |
|
is requested and found, its target is available in convenience alias |
|
`Magnum::Application` / `Magnum::WindowlessApplication` to simplify porting. |
|
Similarly, if exactly one `*Context` component is requested and found, its |
|
target is available in convenience alias `Magnum::Context`. |
|
|
|
The package is found if either debug or release version of each requested |
|
library (or plugin) is found. If both debug and release libraries (or plugins) |
|
are found, proper version is chosen based on actual build configuration of the |
|
project (i.e. `Debug` build is linked to debug libraries, `Release` build to |
|
release libraries). Note that this autodetection might fail for the |
|
`MAGNUM_PLUGINS_DIR` variable, especially on multi-configuration build systems. |
|
You can make use of @ref corrade-cmake "CORRADE_IS_DEBUG_BUILD" preprocessor |
|
variable along with `MAGNUM_PLUGINS_*_DEBUG_DIR` / `MAGNUM_PLUGINS_*_RELEASE_DIR` |
|
variables to decide in preprocessing step. |
|
|
|
Features of found Magnum library are exposed in these CMake variables, they |
|
are also available as preprocessor variables if including |
|
@ref Magnum/Magnum.h "Magnum/Magnum.h": |
|
|
|
- `MAGNUM_BUILD_DEPRECATED` -- Defined if compiled with deprecated APIs |
|
included |
|
- `MAGNUM_BUILD_STATIC` -- Defined if compiled as static libraries. Default |
|
are shared libraries. |
|
- `MAGNUM_BUILD_MULTITHREADED` -- Defined if compiled in a way that allows |
|
having multiple thread-local Magnum contexts. The default. |
|
- `MAGNUM_TARGET_GLES` -- Defined if compiled for OpenGL ES |
|
- `MAGNUM_TARGET_GLES2` -- Defined if compiled for OpenGL ES 2.0 |
|
- `MAGNUM_TARGET_GLES3` -- Defined if compiled for OpenGL ES 3.0 |
|
- `MAGNUM_TARGET_DESKTOP_GLES` -- Defined if compiled with OpenGL ES |
|
emulation on desktop OpenGL |
|
- `MAGNUM_TARGET_WEBGL` -- Defined if compiled for WebGL |
|
- `MAGNUM_TARGET_HEADLESS` -- Defined if compiled for headless machines. See |
|
@ref MAGNUM_TARGET_HEADLESS documentation for more information. |
|
|
|
Workflows without imported targets are deprecated and the following variables |
|
are included just for backwards compatibility and only if |
|
@ref MAGNUM_BUILD_DEPRECATED is enabled: |
|
|
|
- `MAGNUM_LIBRARIES` -- Expands to `Magnum::Magnum` target. Use `Magnum::Magnum` |
|
target directly instead. |
|
- `MAGNUM_*_LIBRARIES` -- Expands to `Magnum::*` target. Use `Magnum::*` |
|
target directly instead. |
|
- `MAGNUM_APPLICATION_LIBRARIES` / `MAGNUM_WINDOWLESSAPPLICATION_LIBRARIES` |
|
-- Expands to `Magnum::Application` / `Magnum::WindowlessApplication` |
|
target. Use `Magnum::Application` / `Magnum::WindowlessApplication` target |
|
directly instead. |
|
- `MAGNUM_CONTEXT_LIBRARIES` -- Expands to `Magnum::Context` target. Use |
|
`Magnum::Context` target directly instead. |
|
|
|
Corrade library provides also its own set of CMake macros and variables, see |
|
@ref corrade-cmake "its documentation" for more information. |
|
@ref cmake-plugins "Plugins repository", @ref cmake-integration "Integration repository" |
|
and @ref cmake-extras "Extras repository" have also their own CMake modules. |
|
|
|
@section cmake-modules Other CMake modules |
|
|
|
The `modules/` directory contains more useful CMake modules: |
|
|
|
- `FindGLFW.cmake` -- CMake module for finding GLFW. Copy this to your module |
|
directory if you want to use @ref Platform::GlfwApplication. |
|
- `FindEGL.cmake` -- CMake module for finding EGL. Copy this to your |
|
module directory if you want to target embedded platforms such as |
|
@ref CORRADE_TARGET_IOS "iOS", @ref CORRADE_TARGET_ANDROID "Android", |
|
@ref CORRADE_TARGET_WINDOWS_RT "Windows RT" or |
|
@ref CORRADE_TARGET_EMSCRIPTEN "Emscripten" or if you want to use EGL |
|
instead of GLX/WGL/CGL on a desktop platform. |
|
- `FindOpenGLES2.cmake`, `FindOpenGLES3.cmake` -- CMake module for finding |
|
OpenGL ES 2.0 / 3.0 library. Copy this to your module directory if you want |
|
to target @ref MAGNUM_TARGET_GLES "OpenGL ES". |
|
- `FindSDL2.cmake` -- CMake module for finding SDL 2. Copy this to your |
|
module directory if you want to use @ref Platform::Sdl2Application. |
|
|
|
See also relevant section for @ref corrade-cmake-modules "Corrade", |
|
@ref cmake-plugins-modules "Plugins", @ref cmake-integration-modules "Integration" |
|
and @ref cmake-extras-modules "Extras" projects. |
|
|
|
*/ |
|
}
|
|
|