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.
288 lines
14 KiB
288 lines
14 KiB
/* |
|
This file is part of Magnum. |
|
|
|
Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 |
|
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} |
|
|
|
@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. |
|
|
|
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}) |
|
@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. |
|
|
|
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, 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. |
|
- `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 |
|
- `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 |
|
|
|
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 |
|
- `AnySceneImporter` --- @ref Trade::AnySceneImporter "AnySceneImporter" |
|
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 |
|
- `gl-info` --- @ref magnum-gl-info "magnum-gl-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 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_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. |
|
|
|
*/ |
|
}
|
|
|