diff --git a/Doxyfile-mcss b/Doxyfile-mcss index a5c7ef2f4..c48835bc7 100644 --- a/Doxyfile-mcss +++ b/Doxyfile-mcss @@ -108,7 +108,7 @@ HTML_EXTRA_STYLESHEET = \ ##! M_MAIN_PROJECT_URL = http://magnum.graphics/ ##! M_LINKS_NAVBAR1 = \ -##! "getting-started building cmake" \ +##! "getting-started building cmake custom-buildsystems" \ ##! "pages features platforms example-index tips utilities" ##! M_LINKS_NAVBAR2 = \ ##! "namespaces" \ diff --git a/doc/changelog.dox b/doc/changelog.dox index 332763a0f..abf4f75f2 100644 --- a/doc/changelog.dox +++ b/doc/changelog.dox @@ -410,6 +410,8 @@ See also: @subsection changelog-latest-docs Documentation +- New @ref custom-buildsystems page listing the most important things to keep + in mind when using Magnum with custom buildsystems. - Compiled code snippets for @ref Audio and @ref SceneGraph libraries, fixing cases where outdated or plain wrong API constructs were mentioned - Extended documentation for @ref Math::Matrix3::rotation(), diff --git a/doc/cmake.dox b/doc/cmake.dox index e462f24a6..603c7d955 100644 --- a/doc/cmake.dox +++ b/doc/cmake.dox @@ -25,16 +25,19 @@ namespace Magnum { /** @page cmake Usage with CMake -@brief Guide how to find and use Magnum with CMake build system +@brief Guide how to find and use Magnum with the CMake buildsystem. @m_keywords{CMake} @tableofcontents @m_footernavigation -Magnum uses CMake build system for both building and integration into your -projects. The logic is in module `FindMagnum.cmake` distributed with the engine -in `modules/` directory, you are encouraged to copy it along with +Magnum uses CMake as a primary build system for both building and integration +into your projects. The following guide explains how to use it. If you wish to +use a different buildsystem, see @ref custom-buildsystems instead. + +The main logic is in the `FindMagnum.cmake` module distributed with the engine +in the `modules/` directory, you are encouraged to copy it along with `FindCorrade.cmake` into your project and add path to the files to `CMAKE_MODULE_PATH`. Otherwise, if CMake won't be able to find this file in predefined locations, it will error out even if Magnum might be installed on diff --git a/doc/custom-buildsystems-order-plugins.dot b/doc/custom-buildsystems-order-plugins.dot new file mode 100644 index 000000000..0644a9345 --- /dev/null +++ b/doc/custom-buildsystems-order-plugins.dot @@ -0,0 +1,58 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 + Vladimír Vondruš + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. +*/ + +digraph "Magnum plugin dependency order" { + rankdir=BT + ranksep=0.5 + node [style=filled shape=rect margin="0.03,0.03"] + + MagnumAudio [style=solid label="Magnum\nAudio" class="m-info"] + MagnumMeshTools [style=solid label="Magnum\nMeshTools" class="m-info"] + MagnumText [style=solid label="Magnum\nText" class="m-info"] + MagnumTrade [style=solid label="Magnum\nTrade" class="m-info"] + + {rank=same MagnumAudio MagnumMeshTools MagnumText MagnumTrade} + + AudioImporter [label="*AudioImporter" class="m-success"] + ImageConverter [label="*ImageConverter" class="m-success"] + Importer [label="*Importer" class="m-success"] + MagnumFont [class="m-success"] + MagnumFontConverter [class="m-success"] + ObjImporter [class="m-success"] + TgaImageConverter [class="m-success"] + TgaImporter [class="m-success"] + + AudioImporter -> MagnumAudio + ImageConverter -> MagnumTrade + Importer -> MagnumTrade + MagnumFont -> MagnumText + MagnumFont -> TgaImporter + MagnumFontConverter -> MagnumText + MagnumFontConverter -> TgaImageConverter + ObjImporter -> MagnumTrade + ObjImporter -> MagnumMeshTools + TgaImageConverter -> MagnumTrade + TgaImporter -> MagnumTrade +} diff --git a/doc/custom-buildsystems-order.dot b/doc/custom-buildsystems-order.dot new file mode 100644 index 000000000..993609a22 --- /dev/null +++ b/doc/custom-buildsystems-order.dot @@ -0,0 +1,107 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 + Vladimír Vondruš + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. +*/ + +digraph "Magnum library dependency order" { + rankdir=BT + ranksep=0.8 + node [style=filled shape=rect margin="0.03,0.03"] + + CorradeUtility [style=solid label="Corrade\nUtility" class="m-primary"] + CorradeContainers [style=solid label="Corrade\nContainers" class="m-primary" style=dotted] + CorradePluginManager [style=solid label="Corrade\nPluginManager" class="m-info"] + CorradeInterconnect [style=solid label="Corrade\nInterconnect" class="m-info"] + CorradeTestSuite [style=solid label="Corrade\nTestSuite" class="m-info"] + + Magnum [class="m-primary"] + MagnumAnimation [label="Magnum\nAnimation" class="m-primary" style=dotted] + MagnumAudio [label="Magnum\nAudio" class="m-info"] + MagnumDebugTools [label="Magnum\nDebugTools" class="m-info"] + MagnumGL [label="Magnum\nGL" class="m-info"] + MagnumMath [label="Magnum\nMath" class="m-primary" style=dotted] + MagnumMeshTools [label="Magnum\nMeshTools" class="m-info"] + MagnumOpenGLTester [label="Magnum\nOpenGLTester" class="m-info"] + MagnumPrimitives [label="Magnum\nPrimitives" class="m-info"] + MagnumSceneGraph [label="Magnum\nSceneGraph" class="m-info"] + MagnumShaders [label="Magnum\nShaders" class="m-info"] + MagnumShapes [label="Magnum\nShapes" class="m-dim"] + MagnumText [label="Magnum\nText" class="m-info"] + MagnumTextureTools [label="Magnum\nTextureTools" class="m-info"] + MagnumTrade [label="Magnum\nTrade" class="m-info"] + MagnumVk [label="Magnum\nVk" class="m-info"] + + MagnumApplication [label="Magnum\n*Application" class="m-info"] + MagnumWindowlessApplication [label="Magnum\nWindowless*Application" class="m-info"] + + CorradeUtility -> CorradeContainers [dir=both style=dashed class="m-primary"] + {rank=same CorradeUtility CorradeContainers} + CorradePluginManager -> CorradeUtility [class="m-info"] + CorradeInterconnect -> CorradeUtility [class="m-info"] + CorradeTestSuite -> CorradeUtility [class="m-info"] + + {rank=same Magnum -> MagnumAnimation -> MagnumMath [dir=both style=dashed]} + Magnum -> CorradeUtility + + MagnumAudio -> Magnum + + MagnumDebugTools -> CorradeTestSuite [style=dotted] + MagnumDebugTools -> Magnum + MagnumDebugTools -> MagnumGL [style=dotted] + MagnumDebugTools -> MagnumMeshTools [style=dotted] + MagnumDebugTools -> MagnumPrimitives [style=dotted] + MagnumDebugTools -> MagnumShaders [style=dotted] + MagnumDebugTools -> MagnumShapes [style=dotted class="m-dim"] + MagnumDebugTools -> MagnumSceneGraph [style=dotted] + + MagnumGL -> Magnum + + MagnumMeshTools -> Magnum + + MagnumOpenGLTester -> MagnumWindowlessApplication + + MagnumPrimitives -> MagnumTrade + + MagnumSceneGraph -> Magnum + + MagnumShaders -> MagnumGL + + MagnumShapes -> MagnumSceneGraph [class="m-dim"] + + MagnumText -> MagnumTextureTools + MagnumText -> MagnumGL + + MagnumTextureTools -> Magnum + MagnumTextureTools -> MagnumGL [style=dotted] + + MagnumTrade -> Magnum + MagnumTrade -> CorradePluginManager + + MagnumVk -> Magnum + + MagnumApplication -> Magnum + MagnumApplication -> MagnumGL [style=dotted] + MagnumApplication -> MagnumVk [style=dotted] + + MagnumWindowlessApplication -> MagnumGL +} diff --git a/doc/custom-buildsystems.dox b/doc/custom-buildsystems.dox new file mode 100644 index 000000000..dafc4535e --- /dev/null +++ b/doc/custom-buildsystems.dox @@ -0,0 +1,133 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 + Vladimír Vondruš + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. +*/ + +namespace Magnum { +/** @page custom-buildsystems Using Magnum with custom buildsystems +@brief Guide and troubleshooting when you don't want to use CMake. + +While Magnum uses CMake as its primary buildsystem, it's possible to use Magnum +with a custom buildsystem as well. The following guide will highlight the most +important concepts for both using and building Magnum. + +@attention Please note that custom buildsystems are not officially supported, + though their use is *not discouraged*. This guide aims to cover the most + important aspects, but the topic is so broad that it's not feasible to + cover all platform differences and quirks --- that's why we let CMake do it + for us :) You are on your own here. Good luck. + +@section custom-buildsystems-usage Using already built Magnum with a custom buildsystem + +The easier situation is building Magnum itself with CMake, as explained in +@ref building, and then integrating the installed libraries and headers into +your buildsystem. For Magnum built this way, every library has a name +corresponding to the namespace name and the headers are also in a directory +with the same name. + +@subsection custom-buildsystems-usage-dependency-order Library dependency order + +Preserving library linking order is important to avoid linker errors. For +Corrade and libraries in the main Magnum repository the order is the following. +The @m_span{m-text m-primary} light blue @m_endspan libraries are the *core*, +which you need to link every time, the @m_span{m-text m-info} dark blue @m_endspan +libraries are extra functionality. Some libraries have cyclic dependencies, in +which case they are both compiled into a single library, the other part of the +cyclic dependency marked with a dotted rectangle. Deprecated libraries that are +scheduled for removal are marked with a @m_span{m-text m-dim} dim @m_endspan +color. In some cases a dependency is optional and you can remove the dependency +by not disabling parts or configuration options that require given dependency. +See documentation of each library for more information. + +@m_div{m-container-inflate} @m_div{m-row} @m_div{m-col-m-12 m-nopadt} +@dotfile custom-buildsystems-order.dot +@m_enddiv @m_enddiv @m_enddiv + +So, for example, in order to use the @ref Primitives library, you need to link +the libraries in this order, the leaf libraries first and the root dependencies +last: + + MagnumPrimitives MagnumTrade Magnum CorradePluginManager CorradeUtility + +Note that some libraries have dependencies outside of Magnum and the above +diagram doesn't include them --- again, see documentation of each library for +more information. + +@subsection custom-buildsystems-usage-static-plugins Static plugins + +While dynamic plugins work without buildsystem integration, static plugins are +handled automagically with CMake and you need to replicate the magic manually +when using a custom buildsystem. This is just about compiling an additonal +`*.cpp` file together with your final app, see @ref plugins-static for more +information. + +For linking static plugins, there's the following dependency order. Most +plugins have just a single dependency on its interface lib, however there are +some exceptions: + +@m_div{m-container-inflate} @m_div{m-row} @m_div{m-col-m-12 m-nopady} +@dotfile custom-buildsystems-order-plugins.dot +@m_enddiv @m_enddiv @m_enddiv + +@subsection custom-buildsystems-usage-resource-compilation Resource compilation + +The CMake macro @cmake corrade_add_resource() @ce provides a convenience +wrapper macro around the @ref corrade-rc executable. For the following CMake +code: + +@code{.cmake} +corrade_add_resource(MyApp_RESOURCES resources.conf) + +add_executable(MyApp main.cpp ${MyApp_RESOURCES}) +@endcode + +The following is an equivalent shell invocation: + +@code{.sh} +corrade-rc MyApp_RESOURCES resources.conf resources.cpp + +# Now compile resources.cpp into your app +@endcode + +In both cases, `MyApp_RESOURCES` can be used for importing the resources at +runtime with @ref CORRADE_RESOURCE_INITIALIZE(), if needed. Also note that the +@cmake corrade_add_resource() @ce is doing dependency tracking by introspecting +the `resources.conf` file. For a custom buildsystem you have to implement that +by parsing the file yourself. + +@subsection custom-buildsystems-usage-toolchains Cross-compilation + +Magnum maintains a set of CMake toolchains for cross-compiling. Each toolchain +typically sets custom linker and compiler flags and you may want to replicate +the behavior 1:1 to avoid issues. The toolchain files are available at +https://github.com/mosra/toolchains. + +@section custom-buildsystems-building Building Magnum with a custom buildsystem + +@todoc mention configure.h generation from .cmake templates +@todoc mention resources for shaders etc. +@todoc mention various platform-specific + +*/ + +} diff --git a/doc/getting-started.dox b/doc/getting-started.dox index 2ed042020..ad79ffedf 100644 --- a/doc/getting-started.dox +++ b/doc/getting-started.dox @@ -250,6 +250,7 @@ experimenting on your own! - @subpage cmake-plugins --- @copybrief cmake-plugins - @subpage cmake-integration --- @copybrief cmake-integration - @subpage cmake-extras --- @copybrief cmake-extras +- @subpage custom-buildsystems --- @copybrief custom-buildsystems */ }