magnum/doc/cmake.dox

/*
    This file is part of Magnum.

    Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019,
                2020 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 the CMake buildsystem.

@m_keywords{CMake Subproject}
@m_keyword{CMake subproject,,}

@tableofcontents
@m_footernavigation

Magnum uses CMake as a primary build system for both building and integration
into your projects. The following guide explains how to use it. If you wish to
use a different buildsystem, see @ref custom-buildsystems instead.

@section cmake-installed Using Magnum that was externally built and installed

The main logic is in the [FindMagnum.cmake](https://github.com/mosra/magnum/blob/master/modules/FindMagnum.cmake)
module distributed with the engine in the `modules/` directory, you are
encouraged to copy it along with [FindCorrade.cmake](https://github.com/mosra/corrade/blob/master/modules/FindCorrade.cmake)
into your project and add path to the files to `CMAKE_MODULE_PATH`:

@code{.cmake}
# Path where FindCorrade.cmake & FindMagnum.cmake can be found, adapt as needed
set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/modules/" ${CMAKE_MODULE_PATH})

find_package(Magnum REQUIRED ...) # see below
@endcode

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. There are other
Find modules that you might need for particular features or platforms, see
the @ref cmake-modules "full list below". Each library that needs one of the
extra modules also mentions the requirement in its documentation. 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.

@section cmake-subproject Using Magnum as a CMake subproject

A self-contained alternative to a shared instance of the libraries, is to add
the repositories directly into your project (as Git submodules, bundling
downloaded archives etc.), and then to use CMake's @cb{.cmake} add_subdirectory() @ce
command to compile them on demand. With this approach, you don't need to care
about manually installing Magnum and Corrade, however the usual tradeoffs when
bundling code apply --- slower full rebuilds, IDEs having more to parse etc. In
this case, @ref building-features "build-time options" can be @cmake set() @ce
before calling @cmake add_subdirectory() @ce. Note that, unless you require
CMake 3.13 at least, it's necessary to use the `CACHE ... FORCE` arguments
[in order to have the options set properly](https://cmake.org/cmake/help/latest/policy/CMP0077.html).
For example:

@code{.cmake}
add_subdirectory(corrade EXCLUDE_FROM_ALL) # so only things you use are built

set(WITH_ANYIMAGEIMPORTER ON CACHE BOOL "" FORCE) # enable what you need
add_subdirectory(magnum EXCLUDE_FROM_ALL)

find_package(Magnum REQUIRED ...) # see below
@endcode

Note that the use of @cb{.cmake} add_subdirectory() @ce does not replace the
configuration necessary for an installed version of Magnum. The `modules/`
directory and calls to @cb{.cmake} find_package() @ce are needed in both the
installed and the subproject case for a properly configured environment.

To simplify your project setup, the subproject globally configures
@m_class{m-doc-external} [CMAKE_RUNTIME_OUTPUT_DIRECTORY](https://cmake.org/cmake/help/latest/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.html)
and friends to `<CONFIG>/bin` / `<CONFIG>/lib` directories inside your build
directory. This makes the subproject workflow easier when dynamically-loaded
plugins are involved; and on Windows it makes it possible to run built
executables without having to do a @cb{.sh} $PATH @ce setup for dependency
DLLs. If your project already configures `CMAKE_{RUNTIME,LIBRARY,ARCHIVE}_OUTPUT_DIRECTORY`,
those will get used instead (and you can also set your own output directories
* *after* the @cb{.cmake} add_subdirectory() @ce call, which will make Magnum
keep the above). If you want to disable this behavior altogether and keep
all executables and libraries in their implicit locations, set those variables
to an empty string (as opposed to nothing at all, which is the same as if the
variable is not set) --- Magnum will detect and respect that:

@code{.cmake}
# I'm happy with having binaries scattered around the build dir
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "")
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "")
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "")

add_subdirectory(corrade EXCLUDE_FROM_ALL)
add_subdirectory(magnum EXCLUDE_FROM_ALL)
@endcode

Please note that in case of the (by default) dynamic plugins, because these are
loaded at runtime, CMake doesn't know we need them to be built --- one option
is to list them explicitly like shown below, another (but uglier) is to not use
`EXCLUDE_FROM_ALL` on the `magnum` subdirectory, so everything is always built
implicitly.

@code{.cmake}
set(WITH_ANYIMAGEIMPORTER ON CACHE BOOL "" FORCE)
set(WITH_ANYSCENEIMPORTER ON CACHE BOOL "" FORCE)
add_subdirectory(magnum EXCLUDE_FROM_ALL)

# So the AnyImageImporter / AnySceneImporter gets built implicitly
add_dependencies(your-app
    Magnum::AnyImageImporter
    Magnum::AnySceneImporter)
@endcode

Each namespace, plugin and application class provides further information about
additional steps needed for a CMake subproject setup.

@section cmake-find-module Finding the package and its components

Basic usage is:

@code{.cmake}
find_package(Magnum REQUIRED)
@endcode

This module tries to find the base Magnum library and then defines the
following:

-   `Magnum_FOUND` --- Whether the library was found
-   `Magnum::Magnum` --- Base library imported target
-   `MAGNUM_DEPLOY_PREFIX` --- Prefix where to put final application
    executables, defaults to `.`. If a relative path is used, it's relative to
    `CMAKE_INSTALL_PREFIX`.
-   `MAGNUM_INCLUDE_INSTALL_PREFIX` --- Prefix where to put
    platform-independent include and other files, defaults to `.`. If a
    relative path is used, it's relative to `CMAKE_INSTALL_PREFIX`.
-   `MAGNUM_PLUGINS_DEBUG_DIR` --- Base directory with dynamic plugins for
    debug builds. Empty by default, which means the directory is autodetected
    based on library and executable location; override if needed.
-   `MAGNUM_PLUGINS_RELEASE_DIR` --- Base directory with dynamic plugins for
    release builds. Empty by default, which means the directory is autodetected
    based on library and executable location; override if needed.
-   `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.
-   `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

If Magnum is built for @ref CORRADE_TARGET_EMSCRIPTEN "Emscripten", the
following variables contain paths to various support files --- see
@ref platforms-html5 for more information about each file:

-   `MAGNUM_EMSCRIPTENAPPLICATION_JS` --- Path to the `EmscriptenApplication.js`
    file
-   `MAGNUM_WINDOWLESSEMSCRIPTENAPPLICATION_JS` --- Path to the
    `WindowlessEmscriptenApplication.js` file
-   `MAGNUM_WEBAPPLICATION_CSS` --- Path to the `WebApplication.css` file

However, this command will try to find only the base library, not the optional
components. The base library depends on @ref corrade-cmake 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
-   `GL` -- @ref GL library
-   `MeshTools` --- @ref MeshTools library
-   `Primitives` --- @ref Primitives library
-   `SceneGraph` --- @ref SceneGraph library
-   `Shaders` --- @ref Shaders library
-   `ShaderTools` --- @ref ShaderTools library
-   `Text` --- @ref Text library
-   `TextureTools` --- @ref TextureTools library
-   `Trade` --- @ref Trade library
-   `Vk` --- @ref Vk library

Platform namespace is split into more components:

-   `AndroidApplication` --- @ref Platform::AndroidApplication "AndroidApplication"
-   `EmscriptenApplication` --- @ref Platform::EmscriptenApplication "EmscriptenApplication"
-   `GlfwApplication` --- @ref Platform::GlfwApplication "GlfwApplication"
-   `GlxApplication` --- @ref Platform::GlxApplication "GlxApplication"
-   `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"
-   `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

There are also extensions to @ref Corrade::TestSuite::Tester for testing GPU
code:

-   `OpenGLTester` --- @ref GL::OpenGLTester class
-   `VulkanTester` --- @ref Vk::VulkanTester class

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.

-   `AnyAudioImporter` --- @ref Audio::AnyImporter "AnyAudioImporter" plugin
-   `AnyImageConverter` --- @ref Trade::AnyImageConverter "AnyImageConverter"
    plugin
-   `AnyImageImporter` --- @ref Trade::AnyImageImporter "AnyImageImporter"
    plugin
-   `AnySceneConverter` --- @ref Trade::AnySceneConverter "AnySceneConverter"
    plugin
-   `AnySceneImporter` --- @ref Trade::AnySceneImporter "AnySceneImporter"
    plugin
-   `AnyShaderConverter` --- @ref ShaderTools::AnyConverter "AnyShaderConverter"
    plugin
-   `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 "magnum-distancefieldconverter"
    executable
-   `fontconverter` --- @ref magnum-fontconverter "magnum-fontconverter"
    executable
-   `imageconverter` --- @ref magnum-imageconverter "magnum-imageconverter"
    executable
-   `sceneconverter` --- @ref magnum-sceneconverter "magnum-imageconverter"
    executable
-   `shaderconverter` --- @ref magnum-shaderconverter "magnum-shaderconverter"
    executable
-   `gl-info` --- @ref magnum-gl-info "magnum-gl-info" executable
-   `vk-info` --- @ref magnum-vk-info "magnum-vk-info" executable
-   `al-info` --- @ref magnum-al-info "magnum-al-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:

@code{.cmake}
find_package(Magnum REQUIRED Trade MeshTools Primitives Sdl2Application)
@endcode

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::GLContext`.

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 a preprocessing step instead.

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_STATIC_UNIQUE_GLOBALS` --- Defined if static libraries keep
    their globals unique even across different shared libraries. Enabled by
    default for static builds.
-   `MAGNUM_TARGET_GL` --- Defined if compiled with OpenGL interoperability
    enabled
-   `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.
-   `MAGNUM_TARGET_VK` --- Defined if compiled with Vulkan interoperability
    enabled

The following variables are provided for backwards compatibility purposes only
when @ref MAGNUM_BUILD_DEPRECATED is defined and will be removed in a future
release:

-   `MAGNUM_BUILD_MULTITHREADED` --- Alias to `CORRADE_BUILD_MULTITHREADED`.
    Use @ref CORRADE_BUILD_MULTITHREADED 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 of Magnum sources contains more useful CMake modules.
If a library requires presence of any of these, it mentions them in its usage
documentation.

-   [FindOpenAL.cmake](https://github.com/mosra/magnum/blob/master/modules/FindOpenAL.cmake)
    --- CMake module for finding OpenAL. This is a forked version of the
    upstream module that works properly with
    @ref CORRADE_TARGET_EMSCRIPTEN "Emscripten". Copy this to your module
    directory if you want to use the @ref Audio library on Emscripten.
-   [FindGLFW.cmake](https://github.com/mosra/magnum/blob/master/modules/FindGLFW.cmake)
    --- CMake module for finding GLFW. Copy this to your module directory if
    you want to use @ref Platform::GlfwApplication.
-   [FindEGL.cmake](https://github.com/mosra/magnum/blob/master/modules/FindEGL.cmake)
    --- CMake module for finding EGL. Copy this to your module directory if you
    want to use the @ref GL library on 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](https://github.com/mosra/magnum/blob/master/modules/FindOpenGLES2.cmake),
    [FindOpenGLES3.cmake](https://github.com/mosra/magnum/blob/master/modules/FindOpenGLES3.cmake)
    --- CMake module for finding OpenGL ES 2.0 / 3.0 library. Copy this to your
    module directory if you want to use the @ref GL library on
    @ref MAGNUM_TARGET_GLES "OpenGL ES".
-   [FindSDL2.cmake](https://github.com/mosra/magnum/blob/master/modules/FindSDL2.cmake)
    --- CMake module for finding SDL 2. Copy this to your module directory if
    you want to use @ref Platform::Sdl2Application.

*/
}