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),
[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

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
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:

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

Loading…
Cancel
Save