diff --git a/doc/cmake.dox b/doc/cmake.dox index d381d4769..9c04f1103 100644 --- a/doc/cmake.dox +++ b/doc/cmake.dox @@ -36,18 +36,23 @@ 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` module distributed with the engine -in the `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. +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 @@ -251,24 +256,33 @@ 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: +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` --- CMake module for finding OpenAL. This is a forked - version of the upstream module that works properly with +- [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` --- 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 +- [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`, `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. +- [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. + */ } diff --git a/doc/namespaces.dox b/doc/namespaces.dox index 9b388b8fa..44bb5c21b 100644 --- a/doc/namespaces.dox +++ b/doc/namespaces.dox @@ -258,10 +258,18 @@ Audio import, playback and integration with @ref SceneGraph. This library depends on the [OpenAL](https://www.openal.org/) library. It is built if `WITH_AUDIO` is enabled when building Magnum. To use this library with -CMake, you need to request the `Audio` component of the `Magnum` package and -link to the `Magnum::Audio` target: +CMake, you need to copy +[FindOpenAL.cmake](https://github.com/mosra/magnum/blob/master/modules/FindOpenAL.cmake) +from the `modules/` directory in Magnum sources to a `modules/` dir in your +project and pointing `CMAKE_MODULE_PATH` to it (if not done already) so it is +able to correctly find the OpenAL library on all platforms. Then request the +`Audio` component of the `Magnum` package and link to the `Magnum::Audio` +target: @code{.cmake} +# Path where FindOpenAL.cmake can be found, adapt as needed +set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/modules/" ${CMAKE_MODULE_PATH}) + find_package(Magnum REQUIRED Audio) # ... @@ -322,6 +330,19 @@ find_package(Magnum REQUIRED GL) target_link_libraries(your-app Magnum::GL) @endcode +In case you're building for EGL or OpenGL ES platforms, you also need to copy +[FindEGL.cmake](https://github.com/mosra/magnum/blob/master/modules/FindEGL.cmake), +[FindOpenGLES2.cmake](https://github.com/mosra/magnum/blob/master/modules/FindOpenGLES2.cmake) +or [FindOpenGLES3.cmake](https://github.com/mosra/magnum/blob/master/modules/FindOpenGLES3.cmake) +from the `modules/` directory in Magnum sources to a `modules/` dir in your +project and pointing `CMAKE_MODULE_PATH` to it (if not done already) so it is +able to find the EGL and OpenGL ES libraries: + +@code{.cmake} +# Path where FindEGL.cmake and others can be found, adapt as needed +set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/modules/" ${CMAKE_MODULE_PATH}) +@endcode + See @ref building, @ref cmake and @ref opengl for more information. @m_class{m-block m-success} diff --git a/src/Magnum/Platform/GlfwApplication.h b/src/Magnum/Platform/GlfwApplication.h index 948738f28..ddd41bf7d 100644 --- a/src/Magnum/Platform/GlfwApplication.h +++ b/src/Magnum/Platform/GlfwApplication.h @@ -96,13 +96,17 @@ See @ref cmake for more information. @section Platform-GlfwApplication-usage General usage -In order to use this library from CMake, you need to copy `FindGLFW.cmake` from -the modules directory in Magnum source to the `modules/` dir in your project -(so it is able to find the GLFW library). Request the `GlfwApplication` -component of the `Magnum` package and link to the `Magnum::GlfwApplication` -target: +In order to use this library from CMake, you need to copy +[FindGLFW.cmake](https://github.com/mosra/magnum/blob/master/modules/FindGLFW.cmake) +from the `modules/` directory in Magnum sources to a `modules/` dir in your +project and pointing `CMAKE_MODULE_PATH` to it (if not done already) so it is +able to find the GLFW library. Then request the `GlfwApplication` component of +the `Magnum` package and link to the `Magnum::GlfwApplication` target: @code{.cmake} +# Path where FindGLFW.cmake can be found, adapt as needed +set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/modules/" ${CMAKE_MODULE_PATH}) + find_package(Magnum REQUIRED GlfwApplication) # ... diff --git a/src/Magnum/Platform/Sdl2Application.h b/src/Magnum/Platform/Sdl2Application.h index 28c25de4e..972aedb92 100644 --- a/src/Magnum/Platform/Sdl2Application.h +++ b/src/Magnum/Platform/Sdl2Application.h @@ -183,14 +183,17 @@ final package along with a PowerShell script for easy local installation. @section Platform-Sdl2Application-usage General usage -In order to use this library from CMake, you need to copy `FindSDL2.cmake` from -the `modules/` directory in Magnum source to the `modules/` dir in your project -(so it is able to find the SDL2 library). In case of Emscripten you need also -`FindOpenGLES2.cmake` / `FindOpenGLES3.cmake`. Request the `Sdl2Application` -component of the `Magnum` package and link to the `Magnum::Sdl2Application` -target: +In order to use this library from CMake, you need to copy +[FindSDL2.cmake](https://github.com/mosra/magnum/blob/master/modules/FindSDL2.cmake) +from the `modules/` directory in Magnum sources to a `modules/` dir in your +project and pointing `CMAKE_MODULE_PATH` to it (if not done already) so it is +able to find the SDL2 library. Then request the `Sdl2Application` component of +the `Magnum` package and link to the `Magnum::Sdl2Application` target: @code{.cmake} +# Path where FindSDL2.cmake can be found, adapt as needed +set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/modules/" ${CMAKE_MODULE_PATH}) + find_package(Magnum REQUIRED Sdl2Application) # ...