From 744bd219d489dda0d128137c447a38ac6e06d7e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Tue, 15 Oct 2019 17:42:18 +0200 Subject: [PATCH] doc: further iterate on plugin CMake usage, update changelog. --- doc/changelog.dox | 5 +++++ doc/cmake.dox | 27 +++++++++++++++++++++++++-- doc/plugins.dox | 20 ++++++++++---------- 3 files changed, 40 insertions(+), 12 deletions(-) diff --git a/doc/changelog.dox b/doc/changelog.dox index 71515ccc8..41862923c 100644 --- a/doc/changelog.dox +++ b/doc/changelog.dox @@ -53,6 +53,11 @@ See also: MSVC 2017. See also [mosra/magnum-bootstrap#18](https://github.com/mosra/magnum-bootstrap/issues/18), [mosra/magnum#343](https://github.com/mosra/magnum/pull/343) and [mosra/magnum#354](https://github.com/mosra/magnum/issues/354). +- When using Magnum as a CMake subproject, it now puts all binaries into a + common directory to simplify `PATH` handling and dynamic plugin loading. + For more information see @ref cmake-subproject, + [mosra/magnum#357](https://github.com/mosra/magnum/issues/357) and + [mosra/magnum-plugins#63](https://github.com/mosra/magnum-plugins/issues/63). - New @ref Image::pixels(), @ref ImageView::pixels() and @ref Trade::ImageData::pixels() accessors for convenient direct access to pixel data of any image diff --git a/doc/cmake.dox b/doc/cmake.dox index 44a7c9968..aefc1c94b 100644 --- a/doc/cmake.dox +++ b/doc/cmake.dox @@ -70,10 +70,16 @@ repositories into your project (as a Git submodule, bundling a downloaded archive etc.) and use @cb{.cmake} add_subdirectory() @ce. With that approach you don't need to care about `FindCorrade.cmake` / `FindMagnum.cmake`, however the usual tradeoffs when bundling code apply --- slower full rebuilds, IDEs -having more to parse etc. +having more to parse etc. In this case, the +@ref building-features "build-time options" are @cmake set() @ce before +the @cmake add_subdirectory() @ce call. Note that, unless you require CMake +3.13 at least, it's needed to use the `CACHE ... FORCE` arguments +[in order to have the options set properly](https://cmake.org/cmake/help/latest/policy/CMP0077.html). For example: @code{.cmake} add_subdirectory(corrade EXCLUDE_FROM_ALL) # so only things you use are built + +set(WITH_ANYIMAGEIMPORTER ON CACHE BOOL "" FORCE) # enable what you need add_subdirectory(magnum EXCLUDE_FROM_ALL) find_package(Magnum REQUIRED ...) # see below @@ -106,7 +112,24 @@ add_subdirectory(corrade EXCLUDE_FROM_ALL) add_subdirectory(magnum EXCLUDE_FROM_ALL) @endcode -@section cmake-find-module Finding the package and its component +Please note that in case of the (by default) dynamic plugins, because these are +loaded at runtime, CMake doesn't know we need them to be built --- one option +is to list them explicitly like shown below, another (but uglier) is to not use +`EXCLUDE_FROM_ALL` on the `magnum` subdirectory, so everything is always built +implicitly. + +@code{.cmake} +set(WITH_ANYIMAGEIMPORTER ON CACHE BOOL "" FORCE) +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 + Magnum::AnyImageImporter + Magnum::AnySceneImporter) +@endcode + +@section cmake-find-module Finding the package and its components Basic usage is: diff --git a/doc/plugins.dox b/doc/plugins.dox index 718288469..fd3602f95 100644 --- a/doc/plugins.dox +++ b/doc/plugins.dox @@ -42,16 +42,16 @@ embedded systems that don't support dynamic loading, built statically into the executable. Depending on the target platform requirements, different set of plugins can be deployed for different platforms. -The @ref building "Magnum repository" contains a few basic plugins for opening -simple formats, such as TGA images or WAV audio files. These plugins are -included because the file formats are so simple that no external library is -needed for loading their contents and thus they are suitable for quick demos -and prototyping without needing to deal with additional dependencies. +The @ref building "core Magnum repository" contains a few basic plugins for +opening simple formats, such as TGA images or WAV audio files. These plugins +are included because the file formats are so simple that no 3rd party libraries +are needed for loading their contents and thus they are suitable for quick +demos and prototyping without needing to deal with additional dependencies. -Additional plugins (such as importers for PNG and JPEG images, TrueType fonts -etc.) are available in the @ref building-plugins "Magnum Plugins" repository. -Majority of these plugins depends on external libraries, thus not all of them -might be available on all platforms. +Additional plugins (such as importers for PNG and JPEG images, glTF scenes, +TrueType fonts etc.) are available in the @ref building-plugins "Magnum Plugins" +repository. Majority of these plugins depends on external libraries, thus not +all of them might be available on all platforms. @section plugins-types Plugin interfaces @@ -91,7 +91,7 @@ whole lifetime of all plugin instances created using it. @section plugins-dependencies Plugin dependencies -Some plugins have dependencies, for example the @ref Trade::OpenGexImporter "OpenGexImporter" +Some plugins have dependencies, for example the @ref Trade::TinyGltfImporter "TinyGltfImporter" plugin uses @ref Trade::AnyImageImporter "AnyImageImporter" to load texture data. The dependency loading is done automatically, but in some cases it's across plugin types (for example the @ref Text::MagnumFont "MagnumFont" plugin