doc: initial version of a guide for custom buildsystem usage.

Will get extended later with things needed for building Magnum itself
with a custom buildsystem. Some users need that as well.

Co-authored-by: Ivan P <ivanpost777@gmail.com>

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

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

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

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š <mosra@centrum.cz>
+
+    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
+}

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š <mosra@centrum.cz>
+
+    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
+}

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š <mosra@centrum.cz>
+
+    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
+
+*/
+
+}

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
 
 */
 }