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