ic
/
magnum
mirror of https://github.com/mosra/magnum.git
6
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

doc: improve docs about external CMake modules. 

Hopefully this stops more people from running into issues with those.
pull/364/head
Vladimír Vondruš 7 years ago
parent
544f30b52f
commit
37996e12b7
4 changed files with 79 additions and 37 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 62
      doc/cmake.dox
  2. 25
      doc/namespaces.dox
  3. 14
      src/Magnum/Platform/GlfwApplication.h
  4. 15
      src/Magnum/Platform/Sdl2Application.h

62
doc/cmake.dox
Unescape View File

@ -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.
*/
}

25
doc/namespaces.dox
Unescape View File

@ -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}

14
src/Magnum/Platform/GlfwApplication.h
Unescape View File

@ -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)
# ...

15
src/Magnum/Platform/Sdl2Application.h
Unescape View File

@ -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)
# ...

Write Preview
Loading…
Cancel
Save