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.
184 lines
9.3 KiB
184 lines
9.3 KiB
/* |
|
This file is part of Magnum. |
|
|
|
Copyright © 2010, 2011, 2012, 2013, 2014 |
|
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 |
|
|
|
%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. |
|
|
|
Basic usage is: |
|
|
|
find_package(Magnum REQUIRED) |
|
|
|
This command tries to find base %Magnum library and then defines these |
|
variables: |
|
|
|
- `MAGNUM_FOUND` -- Whether the library was found |
|
- `MAGNUM_LIBRARIES` -- %Magnum library and dependent libraries |
|
- `MAGNUM_INCLUDE_DIRS` -- Root include dir and include dirs of dependencies |
|
- `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` -- Audio library |
|
- `%DebugTools` -- DebugTools library (depends on `%MeshTools`, |
|
`%Primitives`, `%SceneGraph`, `%Shaders` and `%Shapes` components) |
|
- `%MeshTools` -- MeshTools library |
|
- `%Primitives` -- Primitives library |
|
- `%SceneGraph` -- SceneGraph library |
|
- `%Shaders` -- Shaders library |
|
- `%Shapes` -- Shapes library (depends on `%SceneGraph` component) |
|
- `%Text` -- Text library (depends on `%TextureTools` component) |
|
- `%TextureTools` -- TextureTools library |
|
|
|
Platform namespace is split into more components: |
|
|
|
- `%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" |
|
- `%WindowlessGlxApplication` -- @ref Platform::WindowlessGlxApplication "WindowlessGlxApplication" |
|
- `%WindowlessNaClApplication` -- @ref Platform::WindowlessNaClApplication "WindowlessNaClApplication" |
|
- `%WindowlessWglApplication` -- @ref Platform::WindowlessWglApplication "WindowlessWglApplication" |
|
|
|
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 (depends on |
|
`%Text` component and `TgaImporter` plugin) |
|
- `MagnumFontConverter` -- @ref Text::MagnumFontConverter "MagnumFontConverter" |
|
plugin (depends on `%Text` component and `%TgaImageConverter` plugin) |
|
- `ObjImporter` -- @ref Trade::ObjImporter "ObjImporter" plugin (depends on |
|
`%MeshTools` component) |
|
- `TgaImageConverter` -- @ref Trade::TgaImageConverter "TgaImageConverter" |
|
plugin |
|
- `TgaImporter` -- @ref Trade::TgaImporter "TgaImporter" plugin |
|
- `WavAudioImporter` -- @ref Audio::WavImporter "WavAudioImporter" plugin |
|
(depends on `%Audio` component) |
|
|
|
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_*_LIBRARIES` -- Component library and dependent libraries |
|
- `MAGNUM_*_INCLUDE_DIRS` -- Include dirs of module dependencies |
|
|
|
If exactly one `*Application` or exactly one `Windowless*Application` component |
|
is requested and found, its libraries and include dirs are available in |
|
convenience aliases `MAGNUM_APPLICATION_LIBRARIES` / |
|
`MAGNUM_WINDOWLESSAPPLICATION_LIBRARIES` and `MAGNUM_APPLICATION_INCLUDE_DIRS` |
|
/ `MAGNUM_WINDOWLESSAPPLICATION_INCLUDE_DIRS` to simplify porting. |
|
|
|
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_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 |
|
|
|
If `MAGNUM_BUILD_DEPRECATED` is defined, the `MAGNUM_INCLUDE_DIR` variable also |
|
contains path directly to Magnum directory (i.e. for includes without `Magnum/` |
|
prefix) and `MAGNUM_PLUGINS_INCLUDE_DIR` contains include dir for plugins (i.e. |
|
for includes without `MagnumPlugins/` prefix). |
|
|
|
%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" and @ref cmake-integration "Integration library" |
|
have also their own CMake modules. |
|
|
|
*/ |
|
}
|
|
|