doc: sweeping update of CMake usage instructions.

Putting more emphasis into CMake subproject setup.

doc/building.dox

@@ -536,12 +536,12 @@ information. See also @ref corrade-cmake and @ref Corrade/Corrade.h for
 related info for the Corrade library.
 
 By default the engine is built with nearly everything except the @ref Audio
-library, plugins, command-line utilities and application libraries (see below).
+and @ref Vk libraries, plugins, command-line utilities and application
-Using the following `WITH_*` CMake options you can specify which parts will be
+libraries (see below). Using the following `WITH_*` CMake options you can
-built and which not:
+specify which parts will be built and which not:
 
 -   `WITH_AUDIO` --- Build the @ref Audio library. Depends on
-    [OpenAL](https://www.openal.org/), not built by default.
+    [OpenAL](https://www.openal.org/), not enabled by default.
 -   `WITH_DEBUGTOOLS` --- Build the @ref DebugTools library.
 -   `WITH_GL` --- Build the @ref GL library. Enabled automatically if
     `WITH_SHADERS` is enabled.
@@ -557,7 +557,8 @@ built and which not:
 -   `WITH_TEXTURETOOLS` --- Build the @ref TextureTools library. Enabled
     automatically if `WITH_TEXT` or `WITH_DISTANCEFIELDCONVERTER` is enabled.
 -   `WITH_TRADE` --- Build the @ref Trade library.
--   `WITH_VK` --- Build the @ref Vk library
+-   `WITH_VK` --- Build the @ref Vk library. Depends on Vulkan, not enabled by
+    default.
 
 There are more involved component dependencies that are not described here (for
 example the @ref DebugTools has some functionality that gets built only when

doc/cmake.dox

@@ -124,11 +124,14 @@ set(WITH_ANYSCENEIMPORTER ON CACHE BOOL "" FORCE)
 add_subdirectory(magnum EXCLUDE_FROM_ALL)
 
 # So the AnyImageImporter / AnySceneImporter gets built implicitly
-add_custom_target(plugins ALL DEPENDS
+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:

doc/namespaces.dox

@@ -32,8 +32,7 @@
 Contains classes for interacting with OpenGL.
 
 This library is built as part of Magnum by default. To use this library with
-CMake, you need to find the `Magnum` package and link to the `Magnum::Magnum`
+CMake, find the `Magnum` package and link to the `Magnum::Magnum` target:
-target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED)
@@ -57,10 +56,9 @@ Base classes for creating applications with various toolkits.
 
 Parts of this namespace are built if `WITH_*APPLICATION` is enabled when
 building Magnum, with each library having specific toolkit dependencies and
-platform requirements. To use a particular application library with CMake, you
+platform requirements. To use a particular application library with CMake,
-need to request given `*Application` component of the `Magnum` package and link
+request given `*Application` component of the `Magnum` package and link
-to the `Magnum::Application` target. Example using the @ref Platform::Sdl2Application
+to the `Magnum::Application` target, for example:
-library:
 
 @code{.cmake}
 find_package(Magnum REQUIRED Sdl2Application)
@@ -69,9 +67,9 @@ find_package(Magnum REQUIRED Sdl2Application)
 target_link_libraries(your-app PRIVATE Magnum::Application)
 @endcode
 
-See documentation of particular `*Application` classs, the
+Please see documentation of a particular `*Application` classs, the
 @ref magnum-gl-info "magnum-gl-info" utility documentation, @ref building,
-@ref cmake and @ref platform for more information.
+@ref cmake and @ref platform for more information about usage requirements.
 */
 
 /** @dir Magnum/Math
@@ -83,8 +81,7 @@ See documentation of particular `*Application` classs, the
 Template classes for matrix and vector calculations.
 
 This library is built as part of Magnum by default. To use this library with
-CMake, you need to find the `Magnum` package and link to the `Magnum::Magnum`
+CMake, find the `Magnum` package and link to the `Magnum::Magnum` target:
-target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED)
@@ -125,8 +122,7 @@ more information.
 Literals for easy construction of angle and color values.
 
 This library is built as part of Magnum by default. To use this library with
-CMake, you need to find the `Magnum` package and link to the `Magnum::Magnum`
+CMake, find the `Magnum` package and link to the `Magnum::Magnum` target:
-target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED)
@@ -155,8 +151,7 @@ See @ref building, @ref cmake and @ref types for more information.
 Various matrix and vector algorithms.
 
 This library is built as part of Magnum by default. To use this library with
-CMake, you need to find the `Magnum` package and link to the `Magnum::Magnum`
+CMake, find the `Magnum` package and link to the `Magnum::Magnum` target:
-target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED)
@@ -190,8 +185,7 @@ See @ref building and @ref cmake for more information.
 @brief Functions for calculating distances
 
 This library is built as part of Magnum by default. To use this library with
-CMake, you need to find the `Magnum` package and link to the `Magnum::Magnum`
+CMake, find the `Magnum` package and link to the `Magnum::Magnum` target:
-target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED)
@@ -215,8 +209,7 @@ See @ref building and @ref cmake for more information.
 @brief Functions for calculating intersections
 
 This library is built as part of Magnum by default. To use this library with
-CMake, you need to find the `Magnum` package and link to the `Magnum::Magnum`
+CMake, find the `Magnum` package and link to the `Magnum::Magnum` target:
-target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED)
@@ -242,9 +235,17 @@ See @ref building and @ref cmake for more information.
 /** @namespace Magnum::Animation
 @brief Keyframe-based animation
 
-This library is built as part of Magnum by default. To use it, you need to
+This library is built as part of Magnum by default. To use this library with
-find `Magnum` package and link to `Magnum::Magnum` target. See @ref building,
+CMake, find the `Magnum` package and link to the `Magnum::Magnum` target:
-@ref cmake and @ref animation for more information.
+
+@code{.cmake}
+find_package(Magnum REQUIRED)
+
+# ...
+target_link_libraries(your-app PRIVATE Magnum::Magnum)
+@endcode
+
+See @ref building, @ref cmake and @ref animation for more information.
 @experimental
 */
 
@@ -256,26 +257,30 @@ find `Magnum` package and link to `Magnum::Magnum` target. See @ref building,
 
 Audio import, playback and integration with @ref SceneGraph.
 
-This library depends on the [OpenAL](https://www.openal.org/) library. It is
+This library depends on the [OpenAL](https://www.openal.org/) library and is
 built if `WITH_AUDIO` is enabled when building Magnum. To use this library with
-CMake, you need to copy
+CMake, put [FindOpenAL.cmake](https://github.com/mosra/magnum/blob/master/modules/FindOpenAL.cmake)
-[FindOpenAL.cmake](https://github.com/mosra/magnum/blob/master/modules/FindOpenAL.cmake)
+into your `modules/` directory, request the `Audio` component of the `Magnum`
-from the `modules/` directory in Magnum sources to a `modules/` dir in your
+package and link to the `Magnum::Audio` target:
-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)
 
 # ...
 target_link_libraries(your-app PRIVATE Magnum::Audio)
 @endcode
 
+Additionally, if you're using Magnum as a CMake subproject, do the following
+* *before* calling @cmake find_package() @ce to ensure it's enabled, as the
+library is not built by default. Using OpenAL itself as a CMake subproject
+isn't isn't tested at the moment, so you need to provide it as a system
+dependency and point `CMAKE_PREFIX_PATH` to its installation dir if necessary.
+
+@code{.cmake}
+set(WITH_AUDIO ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+@endcode
+
 Additional plugins and utilities are built separately. See particular
 `Audio::*Importer` class documentation, the @ref magnum-al-info "magnum-al-info"
 utility documentation, @ref building, @ref building-plugins, @ref cmake,
@@ -296,8 +301,8 @@ utility documentation, @ref building, @ref building-plugins, @ref cmake,
 Debugging helpers, renderers and profilers.
 
 This library is built if `WITH_DEBUGTOOLS` is enabled when building Magnum. To
-use this library with CMake, you need to request the `DebugTools` component of
+use this library with CMake, request the `DebugTools` component of the `Magnum`
-the `Magnum` package and link to the `Magnum::DebugTools` target:
+package and link to the `Magnum::DebugTools` target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED DebugTools)
@@ -319,9 +324,8 @@ C++11 wrappers around OpenGL objects with state tracking and transparent
 extension support.
 
 All of this library except @ref GL::OpenGLTester is built if `WITH_GL` is
-enabled when building Magnum. To use this library with CMake, you need to
+enabled when building Magnum. To use this library with CMake, request the `GL`
-request the `GL` component of the `Magnum` package and link to the `Magnum::GL`
+component of the `Magnum` package and link to the `Magnum::GL` target:
-target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED GL)
@@ -330,18 +334,11 @@ find_package(Magnum REQUIRED GL)
 target_link_libraries(your-app PRIVATE Magnum::GL)
 @endcode
 
-In case you're building for EGL or OpenGL ES platforms, you also need to copy
+In case you're building for EGL or OpenGL ES platforms, you also need to put
 [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
+into your `modules/` directory.
-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.
 
@@ -366,8 +363,8 @@ See @ref building, @ref cmake and @ref opengl for more information.
 Tools for generating, optimizing and cleaning meshes.
 
 This library is built if `WITH_MESHTOOLS` is enabled when building Magnum. To
-use this library with CMake, you need to request the `MeshTools` component of
+use this library with CMake, request the `MeshTools` component of the `Magnum`
-the `Magnum` package and link to the `Magnum::MeshTools` target:
+package and link to the `Magnum::MeshTools` target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED MeshTools)
@@ -392,8 +389,8 @@ See @ref building and @ref cmake for more information.
 Basic primitives for testing purposes.
 
 This library is built if `WITH_PRIMITIVES` is enabled when building Magnum. To
-use this library with CMake, you need to request the `Primitives` component of
+use this library with CMake, request the `Primitives` component of the `Magnum`
-the `Magnum` package and link to the `Magnum::Primitives` target:
+package and link to the `Magnum::Primitives` target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED Primitives)
@@ -414,8 +411,8 @@ See @ref building and @ref cmake for more information.
 Managing object hierarchy, transformations and interactions.
 
 This library is built if `WITH_SCENEGRAPH` is enabled when building Magnum. To
-use this library with CMake, you need to request the `SceneGraph` component of
+use this library with CMake, request the `SceneGraph` component of the `Magnum`
-the `Magnum` package and link to the `Magnum::SceneGraph` target:
+package and link to the `Magnum::SceneGraph` target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED SceneGraph)
@@ -436,8 +433,8 @@ See @ref building, @ref cmake and @ref scenegraph for more information.
 Collection of shaders for easy prototyping and basic usage.
 
 This library is built if `WITH_SHADERS` is enabled when building Magnum. To
-use this library with CMake, you need to request the `Shaders` component of the
+use this library with CMake, request the `Shaders` component of the `Magnum`
-`Magnum` package and link to the `Magnum::Shaders` target:
+package and link to the `Magnum::Shaders` target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED Shaders)
@@ -501,8 +498,8 @@ See @ref building, @ref cmake and @ref shaders for more information.
 Font texture creation and text layout.
 
 This library is built if `WITH_TEXT` is enabled when building Magnum. To use
-this library with CMake, you need to request the `Text` component of the
+this library with CMake, request the `Text` component of the `Magnum` package
-`Magnum` package and link to the `Magnum::Text` target:
+and link to the `Magnum::Text` target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED Text)
@@ -527,9 +524,8 @@ and `*FontConverter` class documentation, the
 Tools for generating, compressing and optimizing textures.
 
 This library is built if `WITH_TEXTURETOOLS` is enabled when building Magnum.
-To use this library with CMake, you need to request the `TextureTools`
+To use this library with CMake, request the `TextureTools` component of the
-component of the `Magnum` package in CMake and link to the
+`Magnum` package in CMake and link to the `Magnum::TextureTools` target:
-`Magnum::TextureTools` target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED TextureTools)
@@ -557,8 +553,8 @@ Contains plugin interfaces for importing data of various formats and classes
 for direct access to the data.
 
 This library is built if `WITH_TRADE` is enabled when building Magnum. To use
-this library with CMake, you need to request the `Trade` component of the
+this library with CMake, request the `Trade` component of the `Magnum` package
-`Magnum` package and link to the `Magnum::Trade` target:
+and link to the `Magnum::Trade` target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED Trade)
@@ -583,8 +579,8 @@ Additional plugins and utilities are built separately. See particular
 C++14 wrappers and helpers for Vulkan development.
 
 This library is built if `WITH_VK` is enabled when building Magnum. To use this
-library with CMake, you need to request the `Vk` component of the `Magnum`
+library with CMake, request the `Vk` component of the `Magnum` package and link
-package and link to the `Magnum::Vk` target:
+to the `Magnum::Vk` target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED Vk)
@@ -593,6 +589,15 @@ find_package(Magnum REQUIRED Vk)
 target_link_libraries(your-app PRIVATE Magnum::Vk)
 @endcode
 
+Additionally, if you're using Magnum as a CMake subproject, do the following
+* *before* calling @cmake find_package() @ce to ensure it's enabled, as the
+library is not built by default:
+
+@code{.cmake}
+set(WITH_VK ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+@endcode
+
 See @ref building, @ref cmake and @ref vulkan for more information.
 
 @m_class{m-block m-success}

src/Magnum/Animation/Easing.h

@@ -43,6 +43,18 @@ namespace Magnum { namespace Animation {
 A collection of predefined [easing / tweening](https://en.wikipedia.org/wiki/Inbetweening)
 functions for adding life to animation interpolation.
 
+This library is built as part of Magnum by default. To use this library with
+CMake, find the `Magnum` package and link to the `Magnum::Magnum` target:
+
+@code{.cmake}
+find_package(Magnum REQUIRED)
+
+# ...
+target_link_libraries(your-app PRIVATE Magnum::Magnum)
+@endcode
+
+See @ref building, @ref cmake and @ref animation for more information.
+
 @m_class{m-row m-container-inflate}
 
 @parblock

src/Magnum/Audio/Extensions.h

@@ -46,9 +46,11 @@ Each struct has the same public methods as @ref Extension class (currently just
 compile-time decisions rather than @ref Extension instances. See
 @ref Context::isExtensionSupported() for example usage.
 
-This namespace is built if `WITH_AUDIO` is enabled when building Magnum. To use
+This library depends on the [OpenAL](https://www.openal.org/) library and is
-this library with CMake, you need to request the `Audio` component of the
+built if `WITH_AUDIO` is enabled when building Magnum. To use this library with
-`Magnum` package and link to the `Magnum::Audio` target.
+CMake, put [FindOpenAL.cmake](https://github.com/mosra/magnum/blob/master/modules/FindOpenAL.cmake)
+into your `modules/` directory, request the `Audio` component of the `Magnum`
+package and link to the `Magnum::Audio` target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED Audio)
@@ -57,6 +59,17 @@ find_package(Magnum REQUIRED Audio)
 target_link_libraries(your-app PRIVATE Magnum::Audio)
 @endcode
 
+Additionally, if you're using Magnum as a CMake subproject, do the following
+* *before* calling @cmake find_package() @ce to ensure it's enabled, as the
+library is not built by default. Using OpenAL itself as a CMake subproject
+isn't isn't tested at the moment, so you need to provide it as a system
+dependency and point `CMAKE_PREFIX_PATH` to its installation dir if necessary.
+
+@code{.cmake}
+set(WITH_AUDIO ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+@endcode
+
 See @ref building and @ref cmake for more information.
 @see @ref MAGNUM_ASSERT_AUDIO_EXTENSION_SUPPORTED()
 */

src/Magnum/GL/Extensions.h

@@ -63,8 +63,8 @@ but these structs are better suited for compile-time decisions rather than
 usage.
 
 This library is built if `WITH_GL` is enabled when building Magnum. To use this
-library with CMake, you need to request the `GL` component of the `Magnum`
+library with CMake, request the `GL` component of the `Magnum` package and link
-package and link to the `Magnum::GL` target:
+to the `Magnum::GL` target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED GL)

src/Magnum/GL/OpenGLTester.h

@@ -71,8 +71,8 @@ the base features.
 This class is available on platforms with corresponding
 `Platform::Windowless*Application` implementation, which currently means all
 platforms. It is built into a separate static library and only if
-`WITH_OPENGLTESTER` is enabled when building Magnum. To use it with CMake, you
+`WITH_OPENGLTESTER` is enabled when building Magnum. To use it with CMake,
-need to request the `OpenGLTester` component of the `Magnum` package. Derive
+request the `OpenGLTester` component of the `Magnum` package. Derive
 your test class from this class instead of @ref Corrade::TestSuite::Tester and
 either link to `Magnum::OpenGLTester` target or add it to the `LIBRARIES`
 section of the @ref corrade-cmake-add-test "corrade_add_test()" macro:
@@ -84,6 +84,14 @@ find_package(Magnum REQUIRED OpenGLTester)
 corrade_add_test(YourTest YourTest.cpp LIBRARIES Magnum::OpenGLTester)
 @endcode
 
+Additionally, if you're using Magnum as a CMake subproject, ensure it's enabled
+as it's not built by default:
+
+@code{.cmake}
+set(WITH_OPENGLTESTER ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+@endcode
+
 See @ref building, @ref cmake and @ref testsuite for more information.
 
 @section GL-OpenGLTester-running Running the test executables

src/Magnum/Platform/AndroidApplication.h

@@ -56,13 +56,10 @@ namespace Magnum { namespace Platform {
 
 @m_keywords{Application}
 
-Application running on Android.
+Application running on Android. Available only on
-
-This application library is available only on
 @ref CORRADE_TARGET_ANDROID "Android", see respective sections
 in the @ref building-corrade-cross-android "Corrade" and
-@ref building-cross-android "Magnum" building documentation. It is built if
+@ref building-cross-android "Magnum" building documentation.
-`WITH_ANDROIDAPPLICATION` is enabled when building Magnum.
 
 @section Platform-AndroidApplication-bootstrap Bootstrap application
 
@@ -90,12 +87,12 @@ together with a troubleshooting guide is available in @ref platforms-android.
 
 @section Platform-AndroidApplication-usage General usage
 
-In order to use this library from CMake, you need to copy `FindEGL.cmake`
+This application library is built if `WITH_ANDROIDAPPLICATION` is enabled when
-and `FindOpenGLES2.cmake` (or `FindOpenGLES3.cmake`) from the `modules/`
+building Magnum. To use this library with CMake, put [FindEGL.cmake](https://github.com/mosra/magnum/blob/master/modules/FindEGL.cmake)
-directory in Magnum source to the `modules/` dir in your project (so it is able
+and [FindOpenGLES2.cmake](https://github.com/mosra/magnum/blob/master/modules/FindOpenGLES2.cmake) (or
-to find EGL and OpenGL ES libraries). Request the `AndroidApplication`
+[FindOpenGLES3.cmake](https://github.com/mosra/magnum/blob/master/modules/FindOpenGLES3.cmake))
-component of the `Magnum` package and link to the `Magnum::AndroidApplication`
+into your `modules/` directory, request the `AndroidApplication` component of
-target:
+the `Magnum` package and link to the `Magnum::AndroidApplication` target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED)
@@ -109,10 +106,27 @@ if(CORRADE_TARGET_ANDROID)
 endif()
 @endcode
 
+Additionally, if you're using Magnum as a CMake subproject, do the following
+* *before* calling @cmake find_package() @ce to ensure it's enabled, as the
+library is not built by default:
+
+@code{.cmake}
+set(WITH_ANDROIDAPPLICATION ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+@endcode
+
 If no other application is requested, you can also use the generic
 `Magnum::Application` alias to simplify porting. Again, see @ref building and
 @ref cmake for more information. Note that unlike on other platforms you need
-to create *shared library* instead of executable.
+to create a *shared library* instead of an executable:
+
+@code{.cmake}
+if(NOT CORRADE_TARGET_ANDROID)
+    add_executable(your-app ...)
+else()
+    add_library(your-app SHARED ...)
+endif()
+@endcode
 
 In C++ code you need to implement at least @ref drawEvent() to be able to draw
 on the screen. The subclass must be then made accessible from JNI using

src/Magnum/Platform/EmscriptenApplication.h

@@ -61,13 +61,10 @@ namespace Magnum { namespace Platform {
 
 @m_keywords{Application}
 
-Application running on Emscripten.
+Application running on Emscripten. Available only on
-
-This application library is available only on
 @ref CORRADE_TARGET_EMSCRIPTEN "Emscripten", see respective sections
 in the @ref building-corrade-cross-emscripten "Corrade" and
-@ref building-cross-emscripten "Magnum" building documentation. It is built if
+@ref building-cross-emscripten "Magnum" building documentation.
-`WITH_EMSCRIPTENAPPLICATION` is enabled when building Magnum.
 
 @section Platform-EmscriptenApplication-bootstrap Bootstrap application
 
@@ -111,8 +108,12 @@ together with a troubleshooting guide is available in @ref platforms-html5.
 
 @section Platform-EmscriptenApplication-usage General usage
 
-Request the `EmscriptenApplication` component of the `Magnum` package and link
+This application library is built if `WITH_EMSCRIPTENAPPLICATION` is enabled
-to the `Magnum::EmscriptenApplication` target:
+when building Magnum. To use this library with CMake, put
+[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))
+into your `modules/` directory, request the `EmscriptenApplication` component
+of the `Magnum` package and link to the `Magnum::EmscriptenApplication` target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED)
@@ -126,6 +127,15 @@ if(CORRADE_TARGET_EMSCRIPTEN)
 endif()
 @endcode
 
+Additionally, if you're using Magnum as a CMake subproject, do the following
+* *before* calling @cmake find_package() @ce to ensure it's enabled, as the
+library is not built by default:
+
+@code{.cmake}
+set(WITH_EMSCRIPTENAPPLICATION ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+@endcode
+
 If no other application is requested, you can also use the generic
 `Magnum::Application` alias to simplify porting. See @ref building and
 @ref cmake for more information.

src/Magnum/Platform/GlfwApplication.h

@@ -62,10 +62,7 @@ namespace Implementation {
 
 Application using the [GLFW](http://glfw.org) toolkit. Supports keyboard and
 mouse handling with support for changing cursor and mouse tracking and warping.
-
+Available on all platforms where GLFW is ported.
-This application library is available on all platforms where GLFW is ported. It
-depends on the [GLFW](http://glfw.org) library and is built if
-`WITH_GLFWAPPLICATION` is enabled when building Magnum.
 
 @m_class{m-block m-success}
 
@@ -96,23 +93,34 @@ See @ref cmake for more information.
 
 @section Platform-GlfwApplication-usage General usage
 
-In order to use this library from CMake, you need to copy
+This application library depends on the [GLFW](http://glfw.org) library and is
+built if `WITH_GLFWAPPLICATION` is enabled when building Magnum. To use this
+library with CMake, put
 [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
+into your `modules/` directory, request the `GlfwApplication` component of the
-project and pointing `CMAKE_MODULE_PATH` to it (if not done already) so it is
+`Magnum` package and link to the `Magnum::GlfwApplication` target:
-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)
 
 # ...
 target_link_libraries(your-app PRIVATE Magnum::GlfwApplication)
 @endcode
 
+Additionally, if you're using Magnum as a CMake subproject, bundle the
+[glfw repository](https://github.com/glfw/glfw) and do the following
+* *before* calling @cmake find_package() @ce to ensure it's enabled, as the
+library is not built by default. If you want to use system-installed GLFW, omit
+the first part and point `CMAKE_PREFIX_PATH` to its installation dir if
+necessary.
+
+@code{.cmake}
+add_subdirectory(glfw)
+
+set(WITH_GLFWAPPLICATION ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+@endcode
+
 If no other application is requested, you can also use the generic
 `Magnum::Application` alias to simplify porting. Again, see @ref building and
 @ref cmake for more information.

src/Magnum/Platform/GlxApplication.h

@@ -43,11 +43,8 @@ namespace Magnum { namespace Platform {
 @m_keywords{Application}
 
 Application using pure X11 and GLX. Supports keyboard and mouse handling.
-
+Available on desktop OpenGL and
-This application library is available on desktop OpenGL and
+@ref MAGNUM_TARGET_DESKTOP_GLES "OpenGL ES emulation on desktop" on Linux.
-@ref MAGNUM_TARGET_DESKTOP_GLES "OpenGL ES emulation on desktop" on Linux. It
-depends on the **X11** library and is built if `WITH_GLXAPPLICATION` is enabled
-in CMake.
 
 @section Platform-GlxApplication-bootstrap Bootstrap application
 
@@ -57,9 +54,9 @@ more information.
 
 @section Platform-GlxApplication-usage General usage
 
-In order to use this library from Cmake, you need to request the
+This application library depends on the **X11** library and is built if `WITH_GLXAPPLICATION` is enabled when building Magnum. To use this library from
-`GlxApplication` component of the `Magnum` package and link to the
+CMake, request the `GlxApplication` component of the `Magnum` package and link
-`Magnum::GlxApplication` target:
+to the `Magnum::GlxApplication` target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED GlxApplication)
@@ -68,6 +65,15 @@ find_package(Magnum REQUIRED GlxApplication)
 target_link_libraries(your-app PRIVATE Magnum::GlxApplication)
 @endcode
 
+Additionally, if you're using Magnum as a CMake subproject, do the following
+* *before* calling @cmake find_package() @ce to ensure it's enabled, as the
+library is not built by default:
+
+@code{.cmake}
+set(WITH_GLXAPPLICATION ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+@endcode
+
 If no other application is requested, you can also use the generic
 `Magnum::Application` alias to simplify porting. See @ref building and
 @ref cmake for more information.

src/Magnum/Platform/Sdl2Application.h

@@ -95,14 +95,11 @@ namespace Implementation {
 @m_keywords{Application}
 
 Application using [Simple DirectMedia Layer](http://www.libsdl.org/) toolkit.
-Supports keyboard and mouse handling.
+Supports keyboard and mouse handling. This application library is available for
-
+all platforms for which SDL2 is ported except Android (thus also
-This application library is in theory available for all platforms for which
+@ref CORRADE_TARGET_EMSCRIPTEN "Emscripten", see
-SDL2 is ported (thus also @ref CORRADE_TARGET_EMSCRIPTEN "Emscripten", see
 respective sections in @ref building-corrade-cross-emscripten "Corrade's" and
-@ref building-cross-emscripten "Magnum's" building documentation). It depends
+@ref building-cross-emscripten "Magnum's" building documentation).
-on the [SDL2](http://www.libsdl.org) library (Emscripten has it built in) and
-is built if `WITH_SDL2APPLICATION` is enabled in CMake.
 
 @m_class{m-block m-success}
 
@@ -205,23 +202,31 @@ 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
+This application library depends on the [SDL2](http://www.libsdl.org) library
+(Emscripten has it built in) and is built if `WITH_SDL2APPLICATION` is enabled
+when building Magnum. To use this library with CMake, put
 [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
+into your `modules/` directory, request the `Sdl2Application` component of
-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)
 
 # ...
 target_link_libraries(your-app PRIVATE Magnum::Sdl2Application)
 @endcode
 
+Additionally, if you're using Magnum as a CMake subproject, do the following
+* *before* calling @cmake find_package() @ce to ensure it's enabled, as the
+library is not built by default.  Using SDL2 itself as a CMake subproject isn't
+tested at the moment, so you need to provide it as a system dependency and
+point `CMAKE_PREFIX_PATH` to its installation dir if necessary.
+
+@code{.cmake}
+set(WITH_SDL2APPLICATION ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+@endcode
+
 If no other application is requested, you can also use the generic
 `Magnum::Application` alias to simplify porting. Again, see @ref building and
 @ref cmake for more information.

src/Magnum/Platform/WindowlessCglApplication.h

@@ -56,8 +56,7 @@ namespace Magnum { namespace Platform {
 @m_keywords{WindowlessGLContext}
 
 GL context used in @ref WindowlessCglApplication. Does not have any default
-framebuffer. It is built if `WITH_WINDOWLESSCGLAPPLICATION` is enabled in
+framebuffer.
-CMake.
 
 Meant to be used when there is a need to manage (multiple) GL contexts
 manually. See @ref platform-windowless-contexts for more information. If no
@@ -151,8 +150,7 @@ class WindowlessCglContext::Configuration {
 @m_keywords{WindowlessApplication}
 
 Application for offscreen rendering using @ref WindowlessCglContext. This
-application library is available on desktop OpenGL on macOS. It is built if
+application library is available on desktop OpenGL on macOS.
-`WITH_WINDOWLESSCGLAPPLICATION` is enabled in CMake.
 
 @section Platform-WindowlessCglApplication-bootstrap Bootstrap application
 
@@ -175,7 +173,8 @@ See @ref cmake for more information.
 
 @section Platform-WindowlessCglApplication-usage General usage
 
-In order to use this library from CMake, you need to request the
+This application library is built if `WITH_WINDOWLESSCGLAPPLICATION` is enabled
+when building Magnum. To use this library from CMake, request the
 `WindowlessCglApplication` component of the `Magnum` package and link to the `Magnum::WindowlessCglApplication` target:
 
 @code{.cmake}
@@ -190,6 +189,15 @@ if(CORRADE_TARGET_APPLE)
 endif()
 @endcode
 
+Additionally, if you're using Magnum as a CMake subproject, do the following
+* *before* calling @cmake find_package() @ce to ensure it's enabled, as the
+library is not built by default:
+
+@code{.cmake}
+set(WITH_WINDOWLESSCGLAPPLICATION ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+@endcode
+
 If no other application is requested, you can also use the generic
 `Magnum::WindowlessApplication` alias to simplify porting. Again, see
 @ref building and @ref cmake for more information.

src/Magnum/Platform/WindowlessEglApplication.h

@@ -55,8 +55,7 @@ namespace Magnum { namespace Platform {
 @m_keywords{WindowlessGLContext}
 
 GL context using EGL without any windowing system, used in
-@ref WindowlessEglApplication. Does not have any default framebuffer. It is
+@ref WindowlessEglApplication. Does not have any default framebuffer.
-built if `WITH_WINDOWLESSEGLAPPLICATION` is enabled in CMake.
 
 Meant to be used when there is a need to manage (multiple) GL contexts
 manually. See @ref platform-windowless-contexts for more information. If no
@@ -279,8 +278,7 @@ application library is in theory available for all platforms for which EGL
 works (Linux desktop or ES, @ref CORRADE_TARGET_IOS "iOS",
 @ref CORRADE_TARGET_ANDROID "Android" and also
 @ref CORRADE_TARGET_EMSCRIPTEN "Emscripten"). See other
-`Windowless*Application` classes for an alternative. It is built if
+`Windowless*Application` classes for an alternative.
-`WITH_WINDOWLESSEGLAPPLICATION` is enabled in CMake.
 
 @section Platform-WindowlessEglApplication-bootstrap Bootstrap application
 
@@ -341,9 +339,9 @@ together with a troubleshooting guide is available in @ref platforms-html5.
 
 @section Platform-WindowlessEglApplication-usage General usage
 
-In order to use this library from CMake, you need to copy `FindEGL.cmake` from
+This application library is built if `WITH_WINDOWLESSEGLAPPLICATION` is enabled
-the modules directory in Magnum source to the `modules/` dir in your project
+when building Magnum. To use this library from CMake, put [FindEGL.cmake](https://github.com/mosra/magnum/blob/master/modules/FindEGL.cmake)
-(so it is able to find the EGL library). Request the `WindowlessEglApplication`
+into your `modules/` directory, request the `WindowlessEglApplication`
 component of the `Magnum` package and link to the
 `Magnum::WindowlessEglApplication` target:
 
@@ -354,6 +352,15 @@ find_package(Magnum REQUIRED WindowlessEglApplication)
 target_link_libraries(your-app PRIVATE Magnum::WindowlessEglApplication)
 @endcode
 
+Additionally, if you're using Magnum as a CMake subproject, do the following
+* *before* calling @cmake find_package() @ce to ensure it's enabled, as the
+library is not built by default:
+
+@code{.cmake}
+set(WITH_WINDOWLESSEGLAPPLICATION ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+@endcode
+
 If no other application is requested, you can also use the generic
 `Magnum::WindowlessApplication` alias to simplify porting. Again, see
 @ref building and @ref cmake for more information.

src/Magnum/Platform/WindowlessGlxApplication.h

@@ -59,8 +59,7 @@ namespace Magnum { namespace Platform {
 @m_keywords{WindowlessGLContext}
 
 GL context using pure X11 and GLX, used in @ref WindowlessGlxApplication. Does
-not have any default framebuffer. It is built if `WITH_WINDOWLESSGLXAPPLICATION`
+not have any default framebuffer.
-is enabled in CMake.
 
 Meant to be used when there is a need to manage (multiple) GL contexts
 manually. See @ref platform-windowless-contexts for more information. If no
@@ -247,9 +246,7 @@ CORRADE_ENUMSET_OPERATORS(WindowlessGlxContext::Configuration::Flags)
 
 Application for offscreen rendering using @ref WindowlessGlxContext. This
 application library is available on desktop OpenGL and
-@ref MAGNUM_TARGET_DESKTOP_GLES "OpenGL ES emulation on desktop" on Linux. It
+@ref MAGNUM_TARGET_DESKTOP_GLES "OpenGL ES emulation on desktop" on Linux.
-depends on **X11** library and is built if `WITH_WINDOWLESSGLXAPPLICATION` is
-enabled in CMake.
 
 @section Platform-WindowlessGlxApplication-bootstrap Bootstrap application
 
@@ -272,8 +269,11 @@ See @ref cmake for more information.
 
 @section Platform-WindowlessGlxApplication-usage General usage
 
-In order to use this library from CMake, you need to request the
+This application library depends on the **X11** library and is built if
-`WindowlessGlxApplication` component of the `Magnum` package and link to the `Magnum::WindowlessGlxApplication` target:
+`WITH_WINDOWLESSGLXAPPLICATION` is enabled when building Magnum. To use this
+library with CMake, you need to request the `WindowlessGlxApplication`
+component of the `Magnum` package and link to the
+`Magnum::WindowlessGlxApplication` target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED)
@@ -287,6 +287,15 @@ if(CORRADE_TARGET_UNIX)
 endif()
 @endcode
 
+Additionally, if you're using Magnum as a CMake subproject, do the following
+* *before* calling @cmake find_package() @ce to ensure it's enabled, as the
+library is not built by default:
+
+@code{.cmake}
+set(WITH_WINDOWLESSGLXAPPLICATION ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+@endcode
+
 If no other application is requested, you can also use the generic
 `Magnum::WindowlessApplication` alias to simplify porting. Again, see
 @ref building and @ref cmake for more information.

src/Magnum/Platform/WindowlessIosApplication.h

@@ -54,8 +54,7 @@ namespace Magnum { namespace Platform {
 @m_keywords{WindowlessGLContext}
 
 GL context using EAGL on iOS, used in @ref WindowlessIosApplication. Does not
-have any default framebuffer. It is built if `WITH_WINDOWLESSIOSAPPLICATION` is
+have any default framebuffer.
-enabled in CMake.
 
 Meant to be used when there is a need to manage (multiple) GL contexts
 manually. See @ref platform-windowless-contexts for more information. If no
@@ -143,8 +142,7 @@ class WindowlessIosContext::Configuration {
 @m_keywords{WindowlessApplication}
 
 Application for offscreen rendering using @ref WindowlessIosContext. Does not
-have any default framebuffer. It is built if `WITH_WINDOWLESSIOSAPPLICATION` is
+have any default framebuffer.
-enabled in CMake.
 
 @section Platform-WindowlessIosApplication-bootstrap Bootstrap application
 
@@ -167,9 +165,9 @@ See @ref cmake for more information.
 
 @section Platform-WindowlessIosApplication-usage General usage
 
-In order to use this library from CMake, you need to copy `FindEGL.cmake` from
+This application library is built if `WITH_WINDOWLESSIOSAPPLICATION` is
-the modules directory in Magnum source to the `modules/` dir in your project
+enabled when building Magnum. To use this library from CMake, put [FindEGL.cmake](https://github.com/mosra/magnum/blob/master/modules/FindEGL.cmake)
-(so it is able to find the EGL library). Request the `WindowlessIosApplication`
+into your `modules/` directory, request the `WindowlessIosApplication`
 component of the `Magnum` package and link to the
 `Magnum::WindowlessIosApplication` target:
 
@@ -185,6 +183,15 @@ if(CORRADE_TARGET_IOS)
 endif()
 @endcode
 
+Additionally, if you're using Magnum as a CMake subproject, do the following
+* *before* calling @cmake find_package() @ce to ensure it's enabled, as the
+library is not built by default:
+
+@code{.cmake}
+set(WITH_WINDOWLESSIOSAPPLICATION ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+@endcode
+
 If no other application is requested, you can also use the generic
 `Magnum::WindowlessApplication` alias to simplify porting. Again, see
 @ref building and @ref cmake for more information.

src/Magnum/Platform/WindowlessWglApplication.h

@@ -59,8 +59,7 @@ namespace Magnum { namespace Platform {
 
 @m_keywords{WindowlessGLContext}
 
-GL context using pure WINAPI, used in @ref WindowlessWglApplication. It is
+GL context using pure WINAPI, used in @ref WindowlessWglApplication.
-built if `WITH_WINDOWLESSWGLAPPLICATION` is enabled in CMake.
 
 Meant to be used when there is a need to manage (multiple) GL contexts
 manually. See @ref platform-windowless-contexts for more information. If no
@@ -246,8 +245,7 @@ CORRADE_ENUMSET_OPERATORS(WindowlessWglContext::Configuration::Flags)
 @m_keywords{WindowlessApplication}
 
 Application for offscreen rendering using @ref WindowlessWglContext. This
-application library is available on desktop OpenGL on Windows. It is built if
+application library is available on desktop OpenGL on Windows.
-`WITH_WINDOWLESSWGLAPPLICATION` is enabled in CMake.
 
 @section Platform-WindowlessWglApplication-bootstrap Bootstrap application
 
@@ -270,8 +268,10 @@ See @ref cmake for more information.
 
 @section Platform-WindowlessWglApplication-usage General usage
 
-In order to use this library from CMake, you need to request the
+This application library is built if `WITH_WINDOWLESSWGLAPPLICATION` is enabled
-`WindowlessWglApplication` component of the `Magnum` package and link to the `Magnum::WindowlessWglApplication` target:
+when building Magnum. To use this library from CMake, request the
+`WindowlessWglApplication` component of the `Magnum` package and link to the
+`Magnum::WindowlessWglApplication` target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED)
@@ -285,6 +285,15 @@ if(CORRADE_TARGET_WINDOWS)
 endif()
 @endcode
 
+Additionally, if you're using Magnum as a CMake subproject, do the following
+* *before* calling @cmake find_package() @ce to ensure it's enabled, as the
+library is not built by default:
+
+@code{.cmake}
+set(WITH_WINDOWLESSWGLAPPLICATION ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+@endcode
+
 If no other application is requested, you can also use the generic
 `Magnum::WindowlessApplication` alias to simplify porting. Again, see
 @ref building and @ref cmake for more information.

src/Magnum/Platform/WindowlessWindowsEglApplication.h

@@ -55,7 +55,6 @@ namespace Magnum { namespace Platform {
 @m_keywords{WindowlessGLContext}
 
 GL context using pure WINAPI and EGL, used in @ref WindowlessWindowsEglApplication.
-It is built if `WITH_WINDOWLESSWINDOWSEGLAPPLICATION` is enabled in CMake.
 
 Meant to be used when there is a need to manage (multiple) GL contexts
 manually. See @ref platform-windowless-contexts for more information. If no
@@ -216,8 +215,7 @@ CORRADE_ENUMSET_OPERATORS(WindowlessWindowsEglContext::Configuration::Flags)
 @m_keywords{WindowlessApplication}
 
 Application for offscreen rendering using @ref WindowlessWindowsEglContext.
-This application library is available on OpenGL ES (also ANGLE) on Windows. It
+This application library is available on OpenGL ES (also ANGLE) on Windows.
-is built if `WITH_WINDOWLESSWINDOWSEGLAPPLICATION` is enabled in CMake.
 
 @section Platform-WindowlessWindowsEglApplication-bootstrap Bootstrap application
 
@@ -240,11 +238,11 @@ See @ref cmake for more information.
 
 @section Platform-WindowlessWindowsEglApplication-usage General usage
 
-In order to use this library from CMake, you need to copy `FindEGL.cmake` from
+This application library is built if `WITH_WINDOWLESSWINDOWSEGLAPPLICATION` is
-the modules directory in Magnum source to the `modules/` dir in your project
+enabled when building Magnum. To use this library from CMake, put [FindEGL.cmake](https://github.com/mosra/magnum/blob/master/modules/FindEGL.cmake)
-(so it is able to find the EGL library). Request the
+into your `modules/` directory, request the `WindowlessWindowsEglApplication`
-`WindowlessWindowsEglApplication` component of the `Magnum` package and link to
+component of the `Magnum` package and link to the
-the `Magnum::WindowlessGlxApplication` target:
+`Magnum::WindowlessGlxApplication` target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED)
@@ -258,6 +256,15 @@ if(CORRADE_TARGET_WINDOWS)
 endif()
 @endcode
 
+Additionally, if you're using Magnum as a CMake subproject, do the following
+* *before* calling @cmake find_package() @ce to ensure it's enabled, as the
+library is not built by default:
+
+@code{.cmake}
+set(WITH_WINDOWLESSWINDOWSEGLAPPLICATION ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+@endcode
+
 If no other application is requested, you can also use the generic
 `Magnum::WindowlessApplication` alias to simplify porting. Again, see
 @ref building and @ref cmake for more information.

src/Magnum/Platform/XEglApplication.h

@@ -45,8 +45,7 @@ namespace Magnum { namespace Platform {
 Application using pure X11 and EGL. Supports keyboard and mouse handling.
 
 This application library is available on both desktop OpenGL and
-@ref MAGNUM_TARGET_GLES "OpenGL ES" on Linux. It depends on **X11** and **EGL**
+@ref MAGNUM_TARGET_GLES "OpenGL ES" on Linux.
-libraries and is built if `WITH_XEGLAPPLICATION` is enabled in CMake.
 
 @section Platform-XEglApplication-bootstrap Bootstrap application
 
@@ -56,11 +55,11 @@ more information.
 
 @section Platform-XEglApplication-usage General usage
 
-In order to use this library from CMake, you need to copy `FindEGL.cmake` from
+This application library depends on **X11** and **EGL** libraries and is built
-the modules directory in Magnum source to the `modules/` dir in your project
+if `WITH_XEGLAPPLICATION` is enabled when building Magnum. To use this library
-(so it is able to find the EGL library). Request the `XEglApplication`
+from CMake, put [FindEGL.cmake](https://github.com/mosra/magnum/blob/master/modules/FindEGL.cmake)
-component of the `Magnum` package and link to the `Magnum::XEglApplication`
+into your `modules/` directory, request the `XEglApplication` component of the
-target:
+`Magnum` package and link to the `Magnum::XEglApplication` target:
 
 @code{.cmake}
 find_package(Magnum REQUIRED XEglApplication)
@@ -69,6 +68,15 @@ find_package(Magnum REQUIRED XEglApplication)
 target_link_libraries(your-app PRIVATE Magnum::XEglApplication)
 @endcode
 
+Additionally, if you're using Magnum as a CMake subproject, do the following
+* *before* calling @cmake find_package() @ce to ensure it's enabled, as the
+library is not built by default:
+
+@code{.cmake}
+set(WITH_XEGLAPPLICATION ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+@endcode
+
 If no other application is requested, you can also use the generic
 `Magnum::Application` alias to simplify porting. Again, see @ref building and
 @ref cmake for more information.

src/MagnumPlugins/AnyAudioImporter/AnyImporter.h

@@ -58,17 +58,7 @@ namespace Magnum { namespace Audio {
 @m_keywords{AnyAudioImporter}
 
 Detects file type based on file extension, loads corresponding plugin and then
-tries to open the file with it.
+tries to open the file with it. Supported formats:
-
-This plugin depends on the @ref Audio library and is built if
-`WITH_ANYAUDIOIMPORTER` is enabled when building Magnum. To use as a dynamic
-plugin, you need to load the @cpp "AnyAudioImporter" @ce plugin from
-`MAGNUM_PLUGINS_IMPORTER_DIR`. To use as a static plugin or as a dependency of
-another plugin with CMake, you need to request the `AnyAudioImporter` component
-of the `Magnum` package and link to the `Magnum::AnyAudioImporter` target. See
-@ref building, @ref cmake and @ref plugins for more information.
-
-Supported formats:
 
 -   AAC (`*.aac`), loaded with any plugin that provides `AacAudioImporter`
 -   MP3 (`*.mp3`), loaded with any plugin that provides `Mp3AudioImporter`
@@ -79,6 +69,36 @@ Supported formats:
 -   FLAC (`*.flac`), loaded with any plugin that provides `FlacAudioImporter`
 
 Only loading from files is supported.
+
+@section Audio-AnyImporter-usage Usage
+
+This plugin depends on the @ref Audio library and is built if
+`WITH_ANYAUDIOIMPORTER` is enabled when building Magnum. To use as a dynamic
+plugin, load @cpp "AnyAudioImporter" @ce via
+@ref Corrade::PluginManager::Manager.
+
+Additionally, if you're using Magnum as a CMake subproject, do the following:
+
+@code{.cmake}
+set(WITH_ANYAUDIOIMPORTER ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+
+# So the dynamically loaded plugin gets built implicitly
+add_dependencies(your-app Magnum::AnyAudioImporter)
+@endcode
+
+To use as a static plugin or as a dependency of another plugin with CMake, you
+need to request the `AnyAudioImporter` component of the `Magnum` package and
+link to the `Magnum::AnyAudioImporter` target:
+
+@code{.cmake}
+find_package(Magnum REQUIRED AnyAudioImporter)
+
+# ...
+target_link_libraries(your-app PRIVATE Magnum::AnyAudioImporter)
+@endcode
+
+See @ref building, @ref cmake and @ref plugins for more information.
 */
 class MAGNUM_ANYAUDIOIMPORTER_EXPORT AnyImporter: public AbstractImporter {
     public:

src/MagnumPlugins/AnyImageConverter/AnyImageConverter.h

@@ -54,20 +54,10 @@ namespace Magnum { namespace Trade {
 @brief Any image converter plugin
 
 Detects file type based on file extension, loads corresponding plugin and then
-tries to convert the file with it.
+tries to convert the file with it. Supported formats for uncompressed data:
 
-This plugin depends on the @ref Trade library and is built if
+-   Basis Universal (`*.basis`), converted with @ref BasisImageConverter or any
-`WITH_ANYIMAGECONVERTER` is enabled when building Magnum. To use as a dynamic
+    other plugin that provides it
-plugin, you need to load the @cpp "AnyImageConverter" @ce plugin from
-`MAGNUM_PLUGINS_IMPORTER_DIR`. To use as a static plugin or as a dependency of
-another plugin with CMake, you need to request the `AnyImageConverter`
-component of the `Magnum` package and link to the `Magnum::AnyImageConverter`
-target. See @ref building, @ref cmake and @ref plugins for more information.
-
-Supported formats for uncompressed data:
-
--   Basis Universal (`*.basis`), converted with @ref BasisImageConverter or any other
-    plugin that provides it
 -   Windows Bitmap (`*.bmp`), converted with any plugin that provides
     `BmpImageConverter`
 -   OpenEXR (`*.exr`), converted with any plugin that provides
@@ -81,9 +71,38 @@ Supported formats for uncompressed data:
 -   Truevision TGA (`*.tga`, `*.vda`, `*.icb`, `*.vst`), converted with
     @ref TgaImageConverter or any other plugin that provides it
 
-No supported formats for compressed data yet.
+No supported formats for compressed data yet. Only exporting to files is
+supported.
+
+@section Trade-AnyImageConverter-usage Usage
+
+This plugin depends on the @ref Trade library and is built if
+`WITH_ANYIMAGECONVERTER` is enabled when building Magnum. To use as a dynamic
+plugin, load @cpp "AnyImageConverter" @ce via
+@ref Corrade::PluginManager::Manager.
+
+Additionally, if you're using Magnum as a CMake subproject, do the following:
+
+@code{.cmake}
+set(WITH_ANYIMAGECONVERTER ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+
+# So the dynamically loaded plugin gets built implicitly
+add_dependencies(your-app Magnum::AnyImageConverter)
+@endcode
+
+To use as a static plugin or as a dependency of another plugin with CMake, you
+need to request the `AnyImageConverter` component of the `Magnum` package and
+link to the `Magnum::AnyImageConverter` target:
+
+@code{.cmake}
+find_package(Magnum REQUIRED AnyImageConverter)
+
+# ...
+target_link_libraries(your-app PRIVATE Magnum::AnyImageConverter)
+@endcode
 
-Only exporting to files is supported.
+See @ref building, @ref cmake and @ref plugins for more information.
 */
 class MAGNUM_ANYIMAGECONVERTER_EXPORT AnyImageConverter: public AbstractImageConverter {
     public:

src/MagnumPlugins/AnyImageImporter/AnyImageImporter.h

@@ -54,17 +54,7 @@ namespace Magnum { namespace Trade {
 @brief Any image importer plugin
 
 Detects file type based on file extension, loads corresponding plugin and then
-tries to open the file with it.
+tries to open the file with it. Supported formats:
-
-This plugin depends on the @ref Trade library and is built if
-`WITH_ANYIMAGEIMPORTER` is enabled when building Magnum. To use as a dynamic
-plugin, you need to load the @cpp "AnyImageImporter" @ce plugin from
-`MAGNUM_PLUGINS_IMPORTER_DIR`. To use as a static plugin or as a dependency of
-another plugin with CMake, you need to request the `AnyImageImporter` component
-of the `Magnum` package and link to the `Magnum::AnyImageImporter` target. See
-@ref building, @ref cmake and @ref plugins for more information.
-
-Supported formats:
 
 -   Basis Universal (`*.basis`), loaded @ref BasisImporter or any other plugin
     that provides it
@@ -104,6 +94,36 @@ Supported formats:
 
 Detecting file type through @ref openData() is supported only for a subset of
 formats that are marked as such in the list above.
+
+@section Trade-AnyImageImporter-usage Usage
+
+This plugin depends on the @ref Trade library and is built if
+`WITH_ANYIMAGEIMPORTER` is enabled when building Magnum. To use as a dynamic
+plugin, load @cpp "AnyImageImporter" @ce via
+@ref Corrade::PluginManager::Manager.
+
+Additionally, if you're using Magnum as a CMake subproject, do the following:
+
+@code{.cmake}
+set(WITH_ANYIMAGEIMPORTER ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+
+# So the dynamically loaded plugin gets built implicitly
+add_dependencies(your-app Magnum::AnyImageImporter)
+@endcode
+
+To use as a static plugin or as a dependency of another plugin with CMake, you
+need to request the `AnyImageImporter` component of the `Magnum` package and
+link to the `Magnum::AnyImageImporter` target:
+
+@code{.cmake}
+find_package(Magnum REQUIRED AnyImageImporter)
+
+# ...
+target_link_libraries(your-app PRIVATE Magnum::AnyImageImporter)
+@endcode
+
+See @ref building, @ref cmake and @ref plugins for more information.
 */
 class MAGNUM_ANYIMAGEIMPORTER_EXPORT AnyImageImporter: public AbstractImporter {
     public:

src/MagnumPlugins/AnySceneImporter/AnySceneImporter.h

@@ -54,17 +54,7 @@ namespace Magnum { namespace Trade {
 @brief Any scene importer plugin
 
 Detects file type based on file extension, loads corresponding plugin and then
-tries to open the file with it.
+tries to open the file with it. Supported formats:
-
-This plugin depends on the @ref Trade library and is built if
-`WITH_ANYSCENEIMPORTER` is enabled when building Magnum. To use as a dynamic
-plugin, you need to load the @cpp "AnySceneImporter" @ce plugin from
-`MAGNUM_PLUGINS_IMPORTER_DIR`. To use as a static plugin or as a dependency of
-another plugin with CMake, you need to request the `AnySceneImporter` component
-of the `Magnum` package in CMake and link to the `Magnum::AnySceneImporter`
-target. See @ref building, @ref cmake and @ref plugins for more information.
-
-Supported formats:
 
 -   3ds Max 3DS and ASE (`*.3ds`, `*.ase`), loaded with any plugin that
     provides `3dsImporter`
@@ -106,6 +96,36 @@ Supported formats:
 -   XGL (`*.xgl`, `*.zgl`), loaded with any plugin that provides `XglImporter`
 
 Only loading from files is supported.
+
+@section Trade-AnySceneImporter-usage Usage
+
+This plugin depends on the @ref Trade library and is built if
+`WITH_ANYSCENEIMPORTER` is enabled when building Magnum. To use as a dynamic
+plugin, load @cpp "AnySceneImporter" @ce via
+@ref Corrade::PluginManager::Manager.
+
+Additionally, if you're using Magnum as a CMake subproject, do the following:
+
+@code{.cmake}
+set(WITH_ANYSCENEIMPORTER ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+
+# So the dynamically loaded plugin gets built implicitly
+add_dependencies(your-app Magnum::AnySceneImporter)
+@endcode
+
+To use as a static plugin or as a dependency of another plugin with CMake, you
+need to request the `AnySceneImporter` component of the `Magnum` package in
+CMake and link to the `Magnum::AnySceneImporter` target:
+
+@code{.cmake}
+find_package(Magnum REQUIRED AnySceneImporter)
+
+# ...
+target_link_libraries(your-app PRIVATE Magnum::AnySceneImporter)
+@endcode
+
+See @ref building, @ref cmake and @ref plugins for more information.
 */
 class MAGNUM_ANYSCENEIMPORTER_EXPORT AnySceneImporter: public AbstractImporter {
     public:

src/MagnumPlugins/MagnumFont/MagnumFont.h

@@ -58,15 +58,6 @@ namespace Magnum { namespace Text {
 /**
 @brief Simple bitmap font plugin
 
-This plugin depends on the @ref Text library and the
-@ref Trade::TgaImporter "TgaImporter" plugin. It is built if `WITH_MAGNUMFONT`
-is enabled when building Magnum. To use as a dynamic plugin, you need to load
-the @cpp "MagnumFont" @ce plugin from `MAGNUM_PLUGINS_FONT_DIR`. To use as a
-static plugin or as a dependency of another plugin with CMake, you need to
-request the `MagnumFont` component of the `Magnum` package and link to the
-`Magnum::MagnumFont` target. See @ref building, @ref cmake and @ref plugins
-for more information.
-
 The font consists of two files, one text file containing character and glyph
 info and one TGA file containing the glyphs in distance field format. The font
 can be conveniently created from any other format using
@@ -124,6 +115,36 @@ rectangle=45 0 44 25
 
 # ...
 @endcode
+
+@section Text-MagnumFont-usage Usage
+
+This plugin depends on the @ref Text library and the
+@ref Trade::TgaImporter "TgaImporter" plugin. It is built if `WITH_MAGNUMFONT`
+is enabled when building Magnum. To use as a dynamic plugin, load
+@cpp "MagnumFont" @ce via @ref Corrade::PluginManager::Manager.
+
+Additionally, if you're using Magnum as a CMake subproject, do the following:
+
+@code{.cmake}
+set(WITH_MAGNUMFONT ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+
+# So the dynamically loaded plugin gets built implicitly
+add_dependencies(your-app Magnum::MagnumFont)
+@endcode
+
+To use as a static plugin or as a dependency of another plugin with CMake, you
+need to request the `MagnumFont` component of the `Magnum` package and link to
+the `Magnum::MagnumFont` target:
+
+@code{.cmake}
+find_package(Magnum REQUIRED MagnumFont)
+
+# ...
+target_link_libraries(your-app PRIVATE Magnum::MagnumFont)
+@endcode
+
+See @ref building, @ref cmake and @ref plugins for more information.
 */
 class MAGNUM_MAGNUMFONT_EXPORT MagnumFont: public AbstractFont {
     public:

src/MagnumPlugins/MagnumFontConverter/MagnumFontConverter.h

@@ -58,15 +58,36 @@ Expects filename prefix, creates two files, `prefix.conf` and `prefix.tga`. See
 @ref MagnumFont for more information about the font. The plugin requires the
 passed @ref AbstractGlyphCache to support @ref GlyphCacheFeature::ImageDownload.
 
+@section Text-MagnumFontConverter-usage Usage
+
 This plugin depends on the @ref Text library and the
 @ref Trade::TgaImageConverter "TgaImageConverter" plugin. It is built if
 `WITH_MAGNUMFONTCONVERTER` is enabled when building Magnum. To use as a
-dynamic plugin, you need to load the @cpp "MagnumFontConverter" @ce plugin from
+dynamic plugin, load @cpp "MagnumFontConverter" @ce via
-`MAGNUM_PLUGINS_FONTCONVERTER_DIR`. To use as a static plugin or as a
+@ref Corrade::PluginManager::Manager.
-dependency of another plugin with CMake, you need to request the
+
-`MagnumFontConverter` component of the `Magnum` package and link to the
+Additionally, if you're using Magnum as a CMake subproject, do the following:
-`Magnum::MagnumFontConverter` target. See @ref building, @ref cmake and
+
-@ref plugins for more information.
+@code{.cmake}
+set(WITH_MAGNUMFONTCONVERTER ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+
+# So the dynamically loaded plugin gets built implicitly
+add_dependencies(your-app Magnum::MagnumFontConverter)
+@endcode
+
+To use as a static plugin or as a dependency of another plugin with CMake, you
+need to request the `MagnumFontConverter` component of the `Magnum` package and
+link to the `Magnum::MagnumFontConverter` target:
+
+@code{.cmake}
+find_package(Magnum REQUIRED MagnumFontConverter)
+
+# ...
+target_link_libraries(your-app PRIVATE Magnum::MagnumFontConverter)
+@endcode
+
+See @ref building, @ref cmake and @ref plugins for more information.
 */
 class MAGNUM_MAGNUMFONTCONVERTER_EXPORT MagnumFontConverter: public Text::AbstractFontConverter {
     public:

src/MagnumPlugins/ObjImporter/ObjImporter.h

@@ -60,13 +60,34 @@ Loads Wavefront OBJ (`*.obj`) files, with the following supported features:
 -   vertex positions, normals and 2D texture coordinates
 -   triangles, lines and points
 
+@section Trade-ObjImporter-usage Usage
+
 This plugin depends on the @ref Trade library and is built if `WITH_OBJIMPORTER`
-is enabled when building Magnum. To use as a dynamic plugin, you need to load
+is enabled when building Magnum. To use as a dynamic plugin, load
-the @cpp "ObjImporter" @ce plugin from `MAGNUM_PLUGINS_IMPORTER_DIR`. To use as
+@cpp "ObjImporter" @ce via @ref Corrade::PluginManager::Manager.
-a static plugin or as a dependency of another plugin with CMake, you need to
+
-request the `ObjImporter` component of the `Magnum` package and link to the
+Additionally, if you're using Magnum as a CMake subproject, do the following:
-`Magnum::ObjImporter` target. See @ref building, @ref cmake and @ref plugins
+
-for more information.
+@code{.cmake}
+set(WITH_OBJIMPORTER ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+
+# So the dynamically loaded plugin gets built implicitly
+add_dependencies(your-app Magnum::ObjImporter)
+@endcode
+
+To use as a static plugin or as a dependency of another plugin with CMake, you
+need to request the `ObjImporter` component of the `Magnum` package and link to
+the `Magnum::ObjImporter` target:
+
+@code{.cmake}
+find_package(Magnum REQUIRED ObjImporter)
+
+# ...
+target_link_libraries(your-app PRIVATE Magnum::ObjImporter)
+@endcode
+
+See @ref building, @ref cmake and @ref plugins for more information.
 
 @section Trade-ObjImporter-limitations Behavior and limitations
 

src/MagnumPlugins/TgaImageConverter/TgaImageConverter.h

@@ -58,14 +58,35 @@ Creates Truevision TGA (`*.tga`) files from images with format
 @ref PixelFormat::RGB8Unorm, @ref PixelFormat::RGBA8Unorm or
 @ref PixelFormat::R8Unorm.
 
+@section Trade-TgaImageConverter-usage Usage
+
 This plugin depends on the @ref Trade library and is built if
 `WITH_TGAIMAGECONVERTER` is enabled when building Magnum. To use as a dynamic
-plugin, you need to load the @cpp "TgaImageConverter" @ce plugin from
+plugin, load @cpp "TgaImageConverter" @ce via
-`MAGNUM_PLUGINS_IMAGECONVERTER_DIR`. To use as a static plugin or as a
+@ref Corrade::PluginManager::Manager.
-dependency of another plugin with CMake, you need to request the
+
-`TgaImageConverter` component of the `Magnum` package and link to the
+Additionally, if you're using Magnum as a CMake subproject, do the following:
-`Magnum::TgaImageConverter` target. See @ref building, @ref cmake and
+
-@ref plugins for more information.
+@code{.cmake}
+set(WITH_TGAIMAGECONVERTER ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+
+# So the dynamically loaded plugin gets built implicitly
+add_dependencies(your-app Magnum::TgaImageConverter)
+@endcode
+
+To use as a static plugin or as a dependency of another plugin with CMake, you
+need to request the `TgaImageConverter` component of the `Magnum` package and
+link to the `Magnum::TgaImageConverter` target:
+
+@code{.cmake}
+find_package(Magnum REQUIRED TgaImageConverter)
+
+# ...
+target_link_libraries(your-app PRIVATE Magnum::TgaImageConverter)
+@endcode
+
+See @ref building, @ref cmake and @ref plugins for more information.
 */
 class MAGNUM_TGAIMAGECONVERTER_EXPORT TgaImageConverter: public AbstractImageConverter {
     public:

src/MagnumPlugins/TgaImporter/TgaImporter.h

@@ -60,18 +60,39 @@ namespace Magnum { namespace Trade {
 Supports Truevision TGA (`*.tga`, `*.vda`, `*.icb`, `*.vst`) uncompressed BGR,
 BGRA or grayscale images with 8 bits per channel.
 
-This plugin depends on the @ref Trade library and is built if `WITH_TGAIMPORTER`
-is enabled when building Magnum. To use as a dynamic plugin, you need to load
-the @cpp "TgaImporter" @ce plugin from `MAGNUM_PLUGINS_IMPORTER_DIR`. To use as
-a static plugin or use this as a dependency of another plugin with CMake, you
-need to request the `TgaImporter` component of the `Magnum` package and link to
-the `Magnum::TgaImporter` target. See @ref building, @ref cmake and
-@ref plugins for more information.
-
 The images are imported with @ref PixelFormat::RGB8Unorm,
 @ref PixelFormat::RGBA8Unorm or @ref PixelFormat::R8Unorm, respectively. Images
 are imported with default @ref PixelStorage parameters except for alignment,
 which may be changed to `1` if the data require it.
+
+@section Trade-TgaImporter-usage Usage
+
+This plugin depends on the @ref Trade library and is built if `WITH_TGAIMPORTER`
+is enabled when building Magnum. To use as a dynamic plugin, load
+@cpp "TgaImporter" @ce via @ref Corrade::PluginManager::Manager.
+
+Additionally, if you're using Magnum as a CMake subproject, do the following:
+
+@code{.cmake}
+set(WITH_TGAIMPORTER ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+
+# So the dynamically loaded plugin gets built implicitly
+add_dependencies(your-app Magnum::TgaImporter)
+@endcode
+
+To use as a static plugin or use this as a dependency of another plugin with
+CMake, you need to request the `TgaImporter` component of the `Magnum` package
+and link to the `Magnum::TgaImporter` target:
+
+@code{.cmake}
+find_package(Magnum REQUIRED TgaImporter)
+
+# ...
+target_link_libraries(your-app PRIVATE Magnum::TgaImporter)
+@endcode
+
+See @ref building, @ref cmake and @ref plugins for more information.
 */
 class MAGNUM_TGAIMPORTER_EXPORT TgaImporter: public AbstractImporter {
     public:

src/MagnumPlugins/WavAudioImporter/WavImporter.h

@@ -73,13 +73,34 @@ Supports mono and stereo files of the following formats:
 -   A-Law, imported as @ref BufferFormat::MonoALaw / @ref BufferFormat::StereoALaw
 -   μ-Law, imported as @ref BufferFormat::MonoMuLaw / @ref BufferFormat::StereoMuLaw
 
+@section Audio-WavImporter-usage Usage
+
 This plugin is built if `WITH_WAVAUDIOIMPORTER` is enabled when building
-Magnum. To use dynamic plugin, you need to load the @cpp "WavAudioImporter" @ce
+Magnum. To use dynamic plugin, load @cpp "WavAudioImporter" @ce
-plugin from `MAGNUM_PLUGINS_AUDIOIMPORTER_DIR`. To use as a static plugin or as
+via @ref Corrade::PluginManager::Manager.
-a dependency of another plugin with CMake, you need to request the
+
-`WavAudioImporter` component of the `Magnum` package and link to the
+Additionally, if you're using Magnum as a CMake subproject, do the following:
-`Magnum::WavAudioImporter` target. See @ref building, @ref cmake and
+
-@ref plugins for more information.
+@code{.cmake}
+set(WITH_WAVAUDIOIMPORTER ON CACHE BOOL "" FORCE)
+add_subdirectory(magnum EXCLUDE_FROM_ALL)
+
+# So the dynamically loaded plugin gets built implicitly
+add_dependencies(your-app Magnum::WavAudioImporter)
+@endcode
+
+To use as a static plugin or as a dependency of another plugin with CMake, you
+need to request the `WavAudioImporter` component of the `Magnum` package and
+link to the `Magnum::WavAudioImporter` target:
+
+@code{.cmake}
+find_package(Magnum REQUIRED WavAudioImporter)
+
+# ...
+target_link_libraries(your-app PRIVATE Magnum::WavAudioImporter)
+@endcode
+
+See @ref building, @ref cmake and @ref plugins for more information.
 
 @section Audio-WavImporter-limitations Behavior and limitations