/* This file is part of Magnum. Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016 Vladimír Vondruš 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 - `imageconverter` -- @ref magnum-imageconverter executable - `info` -- @ref magnum-info executable - `al-info` -- @ref 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: 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: - `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` -- 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. */ }