1/*
2    This file is part of Magnum.
3
4    Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019
5              Vladimír Vondruš <mosra@centrum.cz>
6
7    Permission is hereby granted, free of charge, to any person obtaining a
8    copy of this software and associated documentation files (the "Software"),
9    to deal in the Software without restriction, including without limitation
10    the rights to use, copy, modify, merge, publish, distribute, sublicense,
11    and/or sell copies of the Software, and to permit persons to whom the
12    Software is furnished to do so, subject to the following conditions:
13
14    The above copyright notice and this permission notice shall be included
15    in all copies or substantial portions of the Software.
16
17    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
20    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
22    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
23    DEALINGS IN THE SOFTWARE.
24*/
25
26namespace Magnum {
27/** @page cmake-plugins Plugin usage with CMake
28@brief Guide how to find and use static Magnum plugins with CMake build system
29
30@tableofcontents
31@m_footernavigation
32
33If you are going to use dynamic plugins (the default) via a plugin manager,
34they don't need to be linked via CMake as the manager will look for them at
35runtime at specified location and loads them dynamically --- but if you are
36using them via a CMake subproject, additional steps need to be taken so CMake
37knows you need them to be built.
38
39If plugins are built as static (see @ref building-plugins for more
40information), they need to be linked into the executable and then explicitly
41imported. Also if you are going to use them as dependencies, you need to find
42the dependency and then link to it.
43
44@section cmake-plugins-installed Using Magnum Plugins that were externally built and installed
45
46The main logic is in the [FindMagnumPlugins.cmake](https://github.com/mosra/magnum-plugins/blob/master/modules/FindMagnumPlugins.cmake)
47module distributed in the `modules/` directory of the plugins repository,
48you are encouraged to copy it into your project and add path to the files to
49`CMAKE_MODULE_PATH`:
50
51@code{.cmake}
52# Path where FindMagnumPlugins.cmake can be found, adapt as needed
53set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/modules/" ${CMAKE_MODULE_PATH})
54@endcode
55
56Otherwise, if CMake won't be able to find this file in predefined locations, it
57will error out even if Magnum Plugins might be installed on the system. There
58are other Find modules that you might need for particular features or
59platforms, see the @ref cmake-plugins-modules "list below". Note that the
60module files are updated as the library evolves, you are encouraged to update
61your copies from time to time to avoid strange building issues.
62
63If you installed the library or its dependencies to non-standard location
64(other than `/usr`, e.g. `/home/xyz/projects`), set `CMAKE_PREFIX_PATH` to that
65directory to help CMake find it. You can enter more different dirs if you
66separate them with semicolons.
67
68@section cmake-plugins-subproject Using Magnum Plugins as a CMake subproject
69
70Continuing from @ref cmake-subproject, adding Magnum Plugins is very similar.
71Again, the @ref building-plugins-features "Plugins build-time options" have to
72be specified before the subdirectory gets added:
73
74@code{.cmake}
75...
76
77set(WITH_STBIMAGEIMPORTER ON CACHE BOOL "" FORCE) # enable what you need
78add_subdirectory(magnum-plugins EXCLUDE_FROM_ALL)
79
80find_package(MagnumPlugins REQUIRED ...) # see below
81@endcode
82
83Please note that in case of the (by default) dynamic plugins, because these are
84loaded at runtime, CMake doesn't know we need them to be built --- one option
85is to list them explicitly like shown below, another (but uglier) is to not use
86`EXCLUDE_FROM_ALL` on the `magnum` subdirectory, so everything is always built
87implicitly.
88
89@code{.cmake}
90set(WITH_STBIMAGEIMPORTER ON CACHE BOOL "" FORCE)
91set(WITH_TINYGLTFIMPORTER ON CACHE BOOL "" FORCE)
92add_subdirectory(magnum-plugins EXCLUDE_FROM_ALL)
93
94# So the StbImageImporter / TinyGltfImporter gets built implicitly
95add_custom_target(plugins ALL DEPENDS
96    MagnumPlugins::StbImageImporter
97    MagnumPlugins::TinyGltfImporter)
98@endcode
99
100@section cmake-plugins-find-module Finding the package and its components
101
102Basic usage is:
103
104@code{.cmake}
105find_package(MagnumPlugins REQUIRED)
106@endcode
107
108This command tries to find Magnum plugins and then defines:
109
110-   `MagnumPlugins_FOUND` --- Whether Magnum plugins were found
111
112This command will not try to find any actual plugin. The plugins are:
113
114-   `AssimpImporter` --- @ref Trade::AssimpImporter "AssimpImporter" plugin
115-   `BasisImageConverter` --- @ref Trade::BasisImageConverter "BasisImageConverter" plugin
116-   `BasisImporter` --- @ref Trade::BasisImporter "BasisImporter" plugin
117-   `DdsImporter` --- @ref Trade::DdsImporter "DdsImporter" plugin
118-   `DevIlImageImporter` --- @ref Trade::DevIlImageImporter "DevIlImageImporter"
119    plugin
120-   `DrFlacAudioImporter` --- @ref Audio::DrFlacImporter "DrFlacAudioImporter"
121    plugin
122-   `DrMp3AudioImporter` --- @ref Audio::DrMp3Importer "DrMp3AudioImporter"
123    plugin
124-   `DrWavAudioImporter` --- @ref Audio::DrWavImporter "DrWavAudioImporter"
125    plugin
126-   `Faad2AudioImporter` --- @ref Audio::Faad2Importer "Faad2AudioImporter"
127    plugin
128-   `FreeTypeFont` --- @ref Text::FreeTypeFont "FreeTypeFont" plugin
129-   `HarfBuzzFont` --- @ref Text::HarfBuzzFont "HarfBuzzFont" plugin
130-   `JpegImageConverter` --- @ref Trade::JpegImageConverter "JpegImageConverter"
131    plugin
132-   `JpegImporter` --- @ref Trade::JpegImporter "JpegImporter" plugin
133-   `MiniExrImageConverter` --- @ref Trade::MiniExrImageConverter "MiniExrImageConverter"
134    plugin
135-   `OpenGexImporter` --- @ref Trade::OpenGexImporter "OpenGexImporter" plugin
136-   `PngImageConverter` --- @ref Trade::PngImageConverter "PngImageConverter"
137    plugin
138-   `PngImporter` --- @ref Trade::PngImporter "PngImporter" plugin
139-   `StanfordImporter` --- @ref Trade::StanfordImporter "StanfordImporter"
140    plugin
141-   `StbImageConverter` --- @ref Trade::StbImageConverter "StbImageConverter"
142    plugin
143-   `StbImageImporter` --- @ref Trade::StbImageImporter "StbImageImporter"
144    plugin
145-   `StbTrueTypeFont` --- @ref Text::StbTrueTypeFont "StbTrueTypeFont" plugin
146-   `StbVorbisAudioImporter` --- @ref Audio::StbVorbisImporter "StbVorbisAudioImporter"
147    plugin
148-   `TinyGltfImporter` --- @ref Trade::TinyGltfImporter "TinyGltfImporter"
149    plugin
150
151Some plugins expose their internal state through separate libraries. The
152libraries are:
153
154-   `OpenDdl` --- @ref OpenDdl library
155
156Note that each plugin class / library namespace contains more detailed
157information about dependencies, availability on particular platform and also
158guide how to enable given library in build and use it with CMake.
159
160Example usage with specifying the plugins is:
161
162@code{.cmake}
163find_package(MagnumPlugins REQUIRED FreeTypeFont PngImporter)
164@endcode
165
166For each plugin is then defined:
167
168-   `MagnumPlugins_*_FOUND` --- Whether the plugin was found
169-   `MagnumPlugins::*` --- Plugin imported target
170
171The package is found if either debug or release version of each requested
172plugin is found. If both debug and release plugins are found, proper version is
173chosen based on actual build configuration of the project (i.e. `Debug` build
174is linked to debug plugins, `Release` build to release plugins). See @ref cmake
175for more information about autodetection of `MAGNUM_PLUGINS_DIR`.
176
177See also @ref cmake "Magnum usage with CMake" for more information.
178
179@section cmake-plugins-modules Other CMake modules
180
181The `modules/` directory of Magnum Plugins sources contains more useful CMake
182modules. If a plugin requires presence of any of these, it mentions them in its
183usage documentation.
184
185-   [FindAssimp.cmake](https://github.com/mosra/magnum-plugins/blob/master/modules/FindAssimp.cmake)
186    --- CMake module for finding Assimp. Copy this to your module directory if
187    you want to find and link to @ref Trade::AssimpImporter.
188-   [FindBasisUniversal.cmake](https://github.com/mosra/magnum-plugins/blob/master/modules/FindBasisUniversal.cmake)
189    --- CMake module for finding basis universal sources. Copy this to your module directory if
190    you want to find and link to @ref Trade::BasisImporter.
191-   [FindDevIL.cmake](https://github.com/mosra/magnum-plugins/blob/master/modules/FindDevIL.cmake)
192    --- CMake module for finding DevIL. This is a forked version of the upstream
193    module that doesn't attempt to find the often not distributed ILUT library.
194    Copy this to your module directory if you want to find and link to
195    @ref Trade::DevIlImageImporter.
196-   [FindFAAD2.cmake](https://github.com/mosra/magnum-plugins/blob/master/modules/FindFAAD2.cmake)
197    --- CMake module for finding FAAD2. Copy this to your module directory if
198    you want to find and link to @ref Audio::Faad2Importer.
199-   [FindHarfBuzz.cmake](https://github.com/mosra/magnum-plugins/blob/master/modules/FindHarfBuzz.cmake)
200    --- CMake module for finding HarfBuzz. Copy this to your module directory
201    if you want to find and link to @ref Text::HarfBuzzFont.
202
203See also @ref cmake-modules "relevant section for the main Magnum project".
204*/
205}
206