magnum/doc/cmake.dox

/*
    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` -- @ref Audio library
-   `%DebugTools` -- @ref DebugTools library (depends on `%MeshTools`,
    `%Primitives`, `%SceneGraph`, `%Shaders` and `%Shapes` components)
-   `%MeshTools` -- @ref MeshTools library
-   `%Primitives` -- @ref Primitives library
-   `%SceneGraph` -- @ref SceneGraph library
-   `%Shaders` -- @ref Shaders library
-   `%Shapes` -- @ref Shapes library (depends on `%SceneGraph` component)
-   `%Text` -- @ref Text library (depends on `%TextureTools` component)
-   `%TextureTools` -- @ref 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"

For manual context creation (without application wrappers) there are also
platform-specific context libraries (see @ref platform-custom for more
information):

-   `CglContext` -- CGL 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 (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. Similarly,
if exactly one `*Context` component is requested and found, its libraries and
include dirs are available in convenience aliases `MAGNUM_CONTEXT_LIBRARIES`
and `MAGNUM_CONTEXT_INCLUDE_DIRS`.

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.

*/
}