From 46ce7b0347c5073303483ab9e04c4d0ebe573d40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Tue, 29 Oct 2013 16:28:11 +0100 Subject: [PATCH] Thoroughly documented also building and CMake usage of all other libs. --- doc/building.dox | 34 ++++++-------- doc/cmake.dox | 16 +++---- doc/namespaces.dox | 95 ++++++++++++++++++++++++---------------- modules/FindMagnum.cmake | 17 ++++--- src/Extensions.h | 5 ++- 5 files changed, 90 insertions(+), 77 deletions(-) diff --git a/doc/building.dox b/doc/building.dox index ed6b93cd8..10db305a4 100644 --- a/doc/building.dox +++ b/doc/building.dox @@ -142,7 +142,7 @@ By default the engine is built with everything except application libraries (see below). Using `WITH_*` CMake parameters you can specify which parts will be built and which not: - - `WITH_AUDIO` - Audio library. Requires **OpenAL** library. + - `WITH_AUDIO` - Audio library. - `WITH_DEBUGTOOLS` - DebugTools library. Enables also building of MeshTools, Primitives, SceneGraph, Shaders and Shapes libraries. - `WITH_MESHTOOLS` - MeshTools library. Enabled automatically if `WITH_DEBUGTOOLS` @@ -168,26 +168,18 @@ None of the @ref Platform "application libraries" is built by default (and you need at least one). Choose the one which suits your requirements and your platform best: -- `WITH_GLUTAPPLICATION` - @ref Platform::GlutApplication "GlutApplication", - available only if targeting desktop OpenGL. Requires **GLUT** library. -- `WITH_GLXAPPLICATION` - @ref Platform::GlxApplication "GlxApplication". - Available only if targetting desktop OpenGL or ES desktop emulation, not - available on Google Chrome Native Client or Emscripten. Requires **X11** and - **GLX** libraries. -- `WITH_NACLAPPLICATION` - @ref Platform::NaClApplication "NaClApplication", - available only if targeting Google Chrome Native Client. -- `WITH_SDL2APPLICATION` - @ref Platform::Sdl2Application "Sdl2Application". - Available also on Emscripten, but not on Google Chrome Native Client. - Requires **SDL2** library. -- `WITH_XEGLAPPLICATION` - @ref Platform::XEglApplication "XEglApplication", - available only if targeting OpenGL ES (see above). Not available on Google - Chrome Native Client or Emscripten. Requires **X11** and **EGL** libraries. -- `WITH_WINDOWLESSGLXAPPLICATION` - @ref Platform::WindowlessGlxApplication "WindowlessGlxApplication". - Available only if targetting desktop OpenGL or ES desktop emulation, not - available on Google Chrome Native Client or Emscripten. Requires **X11** and - **GLX** libraries. -- `WITH_WINDOWLESSNACLAPPLICATION` - @ref Platform::WindowlessNaClApplication "WindowlessNaClApplication", - available only if targeting Google Chrome Native Client. +- `WITH_GLUTAPPLICATION` - @ref Platform::GlutApplication "GlutApplication" +- `WITH_GLXAPPLICATION` - @ref Platform::GlxApplication "GlxApplication" +- `WITH_NACLAPPLICATION` - @ref Platform::NaClApplication "NaClApplication" +- `WITH_SDL2APPLICATION` - @ref Platform::Sdl2Application "Sdl2Application" +- `WITH_XEGLAPPLICATION` - @ref Platform::XEglApplication "XEglApplication" +- `WITH_WINDOWLESSGLXAPPLICATION` - @ref Platform::WindowlessGlxApplication "WindowlessGlxApplication" +- `WITH_WINDOWLESSNACLAPPLICATION` - @ref Platform::WindowlessNaClApplication "WindowlessNaClApplication" + +Note that [each namespace](namespaces.html) and all @ref Platform libraries +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. @subsection building-tests Building and running unit tests diff --git a/doc/cmake.dox b/doc/cmake.dox index cfaca8c6c..fbea44ae0 100644 --- a/doc/cmake.dox +++ b/doc/cmake.dox @@ -51,7 +51,7 @@ components. The base library depends on %Corrade and OpenGL libraries (or OpenGL ES libraries). Additional dependencies are specified by the components. The optional components are: -- `%Audio` -- Audio library (depends on OpenAL library) +- `%Audio` -- Audio library - `%DebugTools` -- DebugTools library (depends on `%MeshTools`, `%Primitives`, `%SceneGraph`, `%Shaders` and `%Shapes` components) - `%MeshTools` -- MeshTools library @@ -65,17 +65,17 @@ The optional components are: Platform namespace is split into more components: - `%GlutApplication` -- @ref Platform::GlutApplication "GlutApplication" - (depends on GLUT library) -- `%GlxApplication` -- @ref Platform::GlxApplication "GlxApplication" (depends - on GLX and X11 libraries) +- `%GlxApplication` -- @ref Platform::GlxApplication "GlxApplication" - `%NaClApplication` -- @ref Platform::NaClApplication "NaClApplication" - (only if targeting Google Chrome Native Client) - `%Sdl2Application` -- @ref Platform::Sdl2Application "Sdl2Application" - (depends on SDL2 library) - `%XEglApplication` -- @ref Platform::XEglApplication "XEglApplication" - (depends on EGL and X11 libraries) +- `%WindowlessNaClApplication` -- @ref Platform::WindowlessNaClApplication "WindowlessNaClApplication" - `%WindowlessGlxApplication` -- @ref Platform::WindowlessGlxApplication "WindowlessGlxApplication" - (depends on GLX and X11 libraries) + +Note that [each namespace](namespaces.html) and all @ref Platform libraries +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: diff --git a/doc/namespaces.dox b/doc/namespaces.dox index 229abad25..be3b9a526 100644 --- a/doc/namespaces.dox +++ b/doc/namespaces.dox @@ -33,8 +33,9 @@ Contains classes for interacting with OpenGL. -This library is built by default and found by default in CMake. See -@ref building and @ref cmake for more information. +This library is built by default. To use it, you need to add `${MAGNUM_INCLUDE_DIRS}` +to include path and link to `${MAGNUM_LIBRARIES}`. See @ref building and +@ref cmake for more information. */ /** @dir Platform @@ -46,8 +47,12 @@ This library is built by default and found by default in CMake. See Base classes for creating applications with various toolkits. See @ref platform for introduction. -Parts of this namespace are built when `WITH_*APPLICATION` is enabled and found -as `*Application` component in CMake. See @ref building and @ref cmake for more +Parts of this namespace are built if `WITH_*APPLICATION` is enabled in CMake, +with each library having specific toolkit dependencies and platform +requirements. To use particular application library, you need to request given +`*Application` component in CMake, add `${MAGNUM_*APPLICATION_INCLUDE_DIRS}` to +include path and link to `${MAGNUM_*APPLICATION_LIBRARIES}`. See particular +`*Application` class documentation, @ref building and @ref cmake for more information. */ @@ -60,8 +65,9 @@ information. Template classes for matrix and vector calculations. See @ref matrix-vector and @ref transformations for introduction. -This library is built by default and found by default in CMake. See -@ref building and @ref cmake for more information. +This library is built by default. To use it, you need to add `${MAGNUM_INCLUDE_DIRS}` +to include path and link to `${MAGNUM_LIBRARIES}`. See @ref building and +@ref cmake for more information. */ /** @dir Math/Algorithms @@ -72,8 +78,9 @@ This library is built by default and found by default in CMake. See Various matrix and vector algorithms. -This library is built by default and found by default in CMake. See -@ref building and @ref cmake for more information. +This library is built by default. To use it, you need to add `${MAGNUM_INCLUDE_DIRS}` +to include path and link to `${MAGNUM_LIBRARIES}`. See @ref building and +@ref cmake for more information. */ /** @dir Math/Geometry @@ -84,8 +91,9 @@ This library is built by default and found by default in CMake. See Functions for computing intersections, distances, areas and volumes. -This library is built by default and found by default in CMake. See -@ref building and @ref cmake for more information. +This library is built by default. To use it, you need to add `${MAGNUM_INCLUDE_DIRS}` +to include path and link to `${MAGNUM_LIBRARIES}`. See @ref building and +@ref cmake for more information. */ /** @dir Audio @@ -96,10 +104,12 @@ This library is built by default and found by default in CMake. See Audio import, playback and integration with @ref SceneGraph. -This library is built when `WITH_AUDIO` is enabled and found as `%Audio` -component in CMake. See @ref building and @ref cmake for more information. -Additional plugins are part of plugin repository, see @ref building-plugins and -@ref cmake-plugins for more information. +This library depends on **OpenAL** library. It is built if `WITH_AUDIO` is +enabled in CMake. To use this library, you need to request `%Audio` component +in CMake, add `${MAGNUM_AUDIO_INCLUDE_DIRS}` to include path and link to +`${MAGNUM_AUDIO_LIBRARIES}`. See @ref building and @ref cmake for more +information. Additional plugins are part of plugin repository, see +@ref building-plugins and @ref cmake-plugins for more information. */ /** @dir DebugTools @@ -111,8 +121,9 @@ Additional plugins are part of plugin repository, see @ref building-plugins and Debugging helpers, renderers and profilers. See @ref debug-tools for introduction. -This library is built when `WITH_DEBUGTOOLS` is enabled and found as -`%DebugTools` component in CMake. See @ref building and @ref cmake for more +This library is built if `WITH_DEBUGTOOLS` is enabled in CMake. To use this +library, you need to request `%DebugTools` component in CMake and link to +`${MAGNUM_DEBUGTOOLS_LIBRARIES}`. See @ref building and @ref cmake for more information. */ @@ -124,8 +135,9 @@ information. Tools for generating, optimizing and cleaning meshes. -This library is built when `WITH_MESHTOOLS` is enabled and found as -`%MeshTools` component in CMake. See @ref building and @ref cmake for more +This library is built if `WITH_MESHTOOLS` is enabled in CMake. To use this +library, you need to request `%MeshTools` component in CMake and link to +`${MAGNUM_MESHTOOLS_LIBRARIES}`. See @ref building and @ref cmake for more information. */ @@ -137,8 +149,9 @@ information. Basic primitives for testing purposes. -This library is built when `WITH_PRIMITIVES` is enabled and found as -`%Primitives` component in CMake. See @ref building and @ref cmake for more +This library is built if `WITH_PRIMITIVES` is enabled in CMake. To use this +library, you need to request `%Primitives` component in CMake and link to +`${MAGNUM_PRIMITIVES_LIBRARIES}`. See @ref building and @ref cmake for more information. */ @@ -152,8 +165,9 @@ information. Managing object hierarchy, transformations and interactions. See @ref scenegraph for introduction. -This library is built when `WITH_SCENEGRAPH` is enabled and found as -`%SceneGraph` component in CMake. See @ref building and @ref cmake for more +This library is built if `WITH_SCENEGRAPH` is enabled in CMake. To use this +library, you need to request `%SceneGraph` component in CMake and link to +`${MAGNUM_SCENEGRAPH_LIBRARIES}`. See @ref building and @ref cmake for more information. */ @@ -161,12 +175,14 @@ information. * @brief Namespace Magnum::Shaders */ /** @namespace Magnum::Shaders -@brief Sample shaders +@brief Builtin shaders -Collection of shaders for testing purposes. +Collection of shaders for easy prototyping and basic usage. -This library is built when `WITH_SHADERS` is enabled and found as `%Shaders` -component in CMake. See @ref building and @ref cmake for more information. +This library is built if `WITH_SHADERS` is enabled in CMake. To use this +library, you need to request `%Shaders` component in CMake and link to +`${MAGNUM_MESHTOOLS_SHADERS}`. See @ref building and @ref cmake for more +information. */ /** @dir Shapes @@ -177,8 +193,10 @@ component in CMake. See @ref building and @ref cmake for more information. Collision detection system. See @ref shapes for introduction. -This library is built when `WITH_SHAPES` is enabled and found as `%Shapes` -component in CMake. See @ref building and @ref cmake for more information. +This library is built if `WITH_SHAPES` is enabled in CMake. To use this +library, you need to request `%Shapes` component in CMake and link to +`${MAGNUM_SHAPES_LIBRARIES}`. See @ref building and @ref cmake for more +information. */ /** @dir Text @@ -189,10 +207,11 @@ component in CMake. See @ref building and @ref cmake for more information. Font texture creation and text layouting. -This library is built when `WITH_TEXT` is enabled and found as `%Text` -component in CMake. See @ref building and @ref cmake for more information. -Additional plugins are part of plugin repository, see @ref building-plugins and -@ref cmake-plugins for more information. +This library is built if `WITH_TEXT` is enabled in CMake. To use this library, +you need to request `%Text` component in CMake and link to `${MAGNUM_TEXT_LIBRARIES}`. +See @ref building and @ref cmake for more information. Additional plugins are +part of plugin repository, see @ref building-plugins and @ref cmake-plugins for +more information. */ /** @dir TextureTools @@ -203,8 +222,9 @@ Additional plugins are part of plugin repository, see @ref building-plugins and Tools for generating, compressing and optimizing textures. -This library is built when `WITH_TEXTURETOOLS` is enabled and found as -`%TextureTools` component in CMake. See @ref building and @ref cmake for more +This library is built if `WITH_TEXTURETOOLS` is enabled in CMake. To use this +library, you need to request `%TextureTools` component in CMake and link to +`${MAGNUM_TEXTURETOOLS_LIBRARIES}`. See @ref building and @ref cmake for more information. */ @@ -217,8 +237,9 @@ information. Contains plugin interfaces for importing data of various formats and classes for direct access to the data. -This library is built by default and found by default in CMake. See -@ref building and @ref cmake for more information. Additional plugins are part -of plugin repository, see @ref building-plugins and @ref cmake-plugins for more +This library is built by default. To use it, you need to add `${MAGNUM_INCLUDE_DIRS}` +to include path and link to `${MAGNUM_LIBRARIES}`. See @ref building and +@ref cmake for more information. Additional plugins are part of plugin +repository, see @ref building-plugins and @ref cmake-plugins for more information. */ diff --git a/modules/FindMagnum.cmake b/modules/FindMagnum.cmake index b63d1cb7f..c6223bf79 100644 --- a/modules/FindMagnum.cmake +++ b/modules/FindMagnum.cmake @@ -20,7 +20,7 @@ # components. The base library depends on Corrade and OpenGL libraries (or # OpenGL ES libraries). Additional dependencies are specified by the # components. The optional components are: -# Audio - Audio library (depends on OpenAL library) +# Audio - Audio library # DebugTools - DebugTools library (depends on MeshTools, Primitives, # SceneGraph, Shaders and Shapes components) # MeshTools - MeshTools library @@ -30,14 +30,13 @@ # Shapes - Shapes library (depends on SceneGraph component) # Text - Text library (depends on TextureTools component) # TextureTools - TextureTools library -# GlutApplication - GLUT application (depends on GLUT library) -# GlxApplication - GLX application (depends on GLX and X11 libraries) -# NaClApplication - NaCl application (only if targeting Google Chrome -# Native Client) -# Sdl2Application - SDL2 application (depends on SDL2 library) -# XEglApplication - X/EGL application (depends on EGL and X11 libraries) -# WindowlessGlxApplication - Windowless GLX application (depends on GLX -# and X11 libraries) +# GlutApplication - GLUT application +# GlxApplication - GLX application +# NaClApplication - NaCl application +# Sdl2Application - SDL2 application +# XEglApplication - X/EGL application +# WindowlessNaClApplication - Windowless NaCl application +# WindowlessGlxApplication - Windowless GLX application # Example usage with specifying additional components is: # find_package(Magnum [REQUIRED|COMPONENTS] # MeshTools Primitives GlutApplication) diff --git a/src/Extensions.h b/src/Extensions.h index e9fce378a..98b20519a 100644 --- a/src/Extensions.h +++ b/src/Extensions.h @@ -42,8 +42,9 @@ and string(), but these structs are better suited for compile-time decisions rather than %Extension instances. See Context::isExtensionSupported() for example usage. -This namespace is built by default and found by default in CMake. See -@ref building and @ref cmake for more information. +This namespace is built by default. To use it, you need to add `${MAGNUM_INCLUDE_DIRS}` +to include path and link to `${MAGNUM_LIBRARIES}`. See @ref building and +@ref cmake for more information. @see MAGNUM_ASSERT_EXTENSION_SUPPORTED() @todo Manual indices for extensions, this has gaps */