/* This file is part of Magnum. Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025 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 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. 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(MAGNUM_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 `/bin` / `/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(MAGNUM_WITH_ANYIMAGEIMPORTER ON CACHE BOOL "" FORCE) set(MAGNUM_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 - `MaterialTools` --- @ref MaterialTools library - `MeshTools` --- @ref MeshTools library - `Primitives` --- @ref Primitives library - `SceneGraph` --- @ref SceneGraph library - `SceneTools` --- @ref SceneTools 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" 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 features 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_WEBGL` --- Defined if compiled for WebGL - `MAGNUM_TARGET_GLES2` --- Defined if compiled for OpenGL ES 2.0 / WebGL 1 instead of OpenGL ES 3.0+ / WebGL 2 - `MAGNUM_TARGET_EGL` --- Defined if compiled for EGL instead of a platform-specific OpenGL support library such as CGL, EAGL, GLX or WGL. - `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. - `MAGNUM_TARGET_HEADLESS` --- Alias to `MAGNUM_TARGET_EGL`, unless on iOS, Android, Emscripten or Windows RT. Use @ref MAGNUM_TARGET_EGL instead. - `MAGNUM_TARGET_DESKTOP_GLES` --- Defined if compiled for OpenGL ES but GLX / WGL is used instead of EGL. Use @ref MAGNUM_TARGET_EGL instead. - `MAGNUM_TARGET_GLES3` --- Defined if compiled for OpenGL ES 3.0+ / WebGL 2. Use an inverse of the @ref MAGNUM_TARGET_GLES2 variable 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. */ }