Browse Source

doc: further iterate on plugin CMake usage, update changelog.

findsdl-include-root
Vladimír Vondruš 7 years ago
parent
commit
744bd219d4
  1. 5
      doc/changelog.dox
  2. 27
      doc/cmake.dox
  3. 20
      doc/plugins.dox

5
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), 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#343](https://github.com/mosra/magnum/pull/343) and
[mosra/magnum#354](https://github.com/mosra/magnum/issues/354). [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 - New @ref Image::pixels(), @ref ImageView::pixels() and
@ref Trade::ImageData::pixels() accessors for convenient direct access to @ref Trade::ImageData::pixels() accessors for convenient direct access to
pixel data of any image pixel data of any image

27
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 archive etc.) and use @cb{.cmake} add_subdirectory() @ce. With that approach
you don't need to care about `FindCorrade.cmake` / `FindMagnum.cmake`, however you don't need to care about `FindCorrade.cmake` / `FindMagnum.cmake`, however
the usual tradeoffs when bundling code apply --- slower full rebuilds, IDEs 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} @code{.cmake}
add_subdirectory(corrade EXCLUDE_FROM_ALL) # so only things you use are built 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) add_subdirectory(magnum EXCLUDE_FROM_ALL)
find_package(Magnum REQUIRED ...) # see below find_package(Magnum REQUIRED ...) # see below
@ -106,7 +112,24 @@ add_subdirectory(corrade EXCLUDE_FROM_ALL)
add_subdirectory(magnum EXCLUDE_FROM_ALL) add_subdirectory(magnum EXCLUDE_FROM_ALL)
@endcode @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: Basic usage is:

20
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 executable. Depending on the target platform requirements, different set of
plugins can be deployed for different platforms. plugins can be deployed for different platforms.
The @ref building "Magnum repository" contains a few basic plugins for opening The @ref building "core Magnum repository" contains a few basic plugins for
simple formats, such as TGA images or WAV audio files. These plugins are opening simple formats, such as TGA images or WAV audio files. These plugins
included because the file formats are so simple that no external library is are included because the file formats are so simple that no 3rd party libraries
needed for loading their contents and thus they are suitable for quick demos are needed for loading their contents and thus they are suitable for quick
and prototyping without needing to deal with additional dependencies. demos and prototyping without needing to deal with additional dependencies.
Additional plugins (such as importers for PNG and JPEG images, TrueType fonts Additional plugins (such as importers for PNG and JPEG images, glTF scenes,
etc.) are available in the @ref building-plugins "Magnum Plugins" repository. TrueType fonts etc.) are available in the @ref building-plugins "Magnum Plugins"
Majority of these plugins depends on external libraries, thus not all of them repository. Majority of these plugins depends on external libraries, thus not
might be available on all platforms. all of them might be available on all platforms.
@section plugins-types Plugin interfaces @section plugins-types Plugin interfaces
@ -91,7 +91,7 @@ whole lifetime of all plugin instances created using it.
@section plugins-dependencies Plugin dependencies @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 plugin uses @ref Trade::AnyImageImporter "AnyImageImporter" to load texture
data. The dependency loading is done automatically, but in some cases it's data. The dependency loading is done automatically, but in some cases it's
across plugin types (for example the @ref Text::MagnumFont "MagnumFont" plugin across plugin types (for example the @ref Text::MagnumFont "MagnumFont" plugin

Loading…
Cancel
Save