Getting started » Using Magnum with custom buildsystems

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.

Using already built Magnum with a custom buildsystem

The easier situation is building Magnum itself with CMake, as explained in Downloading and 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.

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 light blue libraries are the core, which you need to link every time, the dark blue 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 dim color. In some cases a dependency is optional (marked with a dotted line) and you can remove the dependency by disabling parts or configuration options that require given dependency. See documentation of each library for more information.

Magnum library dependency order CorradeUtility Corrade Utility CorradeContainers Corrade Containers CorradeUtility->CorradeContainers CorradePluginManager Corrade PluginManager CorradePluginManager->CorradeUtility CorradeInterconnect Corrade Interconnect CorradeInterconnect->CorradeUtility CorradeTestSuite Corrade TestSuite CorradeTestSuite->CorradeUtility Magnum Magnum Magnum->CorradeUtility MagnumAnimation Magnum Animation Magnum->MagnumAnimation MagnumMath Magnum Math MagnumAnimation->MagnumMath MagnumAudio Magnum Audio MagnumAudio->Magnum MagnumDebugTools Magnum DebugTools MagnumDebugTools->CorradeTestSuite MagnumDebugTools->Magnum MagnumGL Magnum GL MagnumDebugTools->MagnumGL MagnumMeshTools Magnum MeshTools MagnumDebugTools->MagnumMeshTools MagnumPrimitives Magnum Primitives MagnumDebugTools->MagnumPrimitives MagnumSceneGraph Magnum SceneGraph MagnumDebugTools->MagnumSceneGraph MagnumShaders Magnum Shaders MagnumDebugTools->MagnumShaders MagnumGL->Magnum MagnumMaterialTools Magnum MaterialTools MagnumTrade Magnum Trade MagnumMaterialTools->MagnumTrade MagnumMeshTools->MagnumGL MagnumMeshTools->MagnumTrade MagnumOpenGLTester Magnum OpenGLTester MagnumWindowlessApplication Magnum Windowless*Application MagnumOpenGLTester->MagnumWindowlessApplication MagnumPrimitives->MagnumMeshTools MagnumPrimitives->MagnumTrade MagnumSceneGraph->Magnum MagnumSceneTools Magnum SceneTools MagnumSceneTools->MagnumTrade MagnumShaders->MagnumGL MagnumShaderTools Magnum ShaderTools MagnumShaderTools->CorradePluginManager MagnumShaderTools->Magnum MagnumText Magnum Text MagnumText->MagnumGL MagnumTextureTools Magnum TextureTools MagnumText->MagnumTextureTools MagnumTextureTools->Magnum MagnumTextureTools->MagnumGL MagnumTrade->CorradePluginManager MagnumTrade->Magnum MagnumVk Magnum Vk MagnumVk->Magnum MagnumApplication Magnum *Application MagnumApplication->Magnum MagnumApplication->MagnumGL MagnumApplication->MagnumVk MagnumWindowlessApplication->MagnumGL

So, for example, in order to use the 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.

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 additional *.cpp file together with your final app, see Static plugins 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:

Magnum plugin dependency order MagnumAudio Magnum Audio MagnumMeshTools Magnum MeshTools MagnumText Magnum Text MagnumTrade Magnum Trade AudioImporter *AudioImporter AudioImporter->MagnumAudio ImageConverter *ImageConverter ImageConverter->MagnumTrade Importer *Importer Importer->MagnumTrade MagnumFont MagnumFont MagnumFont->MagnumText TgaImporter TgaImporter MagnumFont->TgaImporter MagnumFontConverter MagnumFontConverter MagnumFontConverter->MagnumText TgaImageConverter TgaImageConverter MagnumFontConverter->TgaImageConverter ObjImporter ObjImporter ObjImporter->MagnumMeshTools ObjImporter->MagnumTrade TgaImageConverter->MagnumTrade TgaImporter->MagnumTrade

Resource compilation

The CMake macro corrade_add_resource() provides a convenience wrapper macro around the Resource compiler executable. For the following CMake code:

corrade_add_resource(MyApp_RESOURCES resources.conf)

add_executable(MyApp main.cpp ${MyApp_RESOURCES})

The following is an equivalent shell invocation:

corrade-rc MyApp_RESOURCES resources.conf resources.cpp

# Now compile resources.cpp into your app

In both cases, MyApp_RESOURCES can be used for importing the resources at runtime with CORRADE_RESOURCE_INITIALIZE(), if needed. Also note that the corrade_add_resource() is doing dependency tracking by introspecting the resources.conf file. For a custom buildsystem you have to implement that by parsing the file yourself.

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.

Building Magnum with a custom buildsystem

Magnum Plugins

The Magnum Plugins repository follows the same plugin dependency rules as the core Magnum repository, with the following special cases:

Magnum Plugins dependency order Magnum Magnum MagnumAudio Magnum Audio MagnumAudio->Magnum MagnumMeshTools Magnum MeshTools MagnumMeshTools->Magnum MagnumShaderTools Magnum ShaderTools MagnumShaderTools->Magnum MagnumText Magnum Text MagnumText->Magnum MagnumTrade Magnum Trade MagnumTrade->Magnum AnyImageImporter AnyImageImporter AnyImageImporter->MagnumTrade MagnumOpenDdl MagnumOpenDdl MagnumOpenDdl->Magnum AudioImporter *AudioImporter AudioImporter->MagnumAudio ImageConverter *ImageConverter ImageConverter->MagnumTrade Importer *Importer SceneConverter *SceneConverter SceneConverter->MagnumTrade ShaderConverter *ShaderConverter ShaderConverter->MagnumShaderTools Importer->MagnumTrade Font *Font Font->MagnumText AssimpImporter AssimpImporter AssimpImporter->MagnumTrade AssimpImporter->AnyImageImporter FreeTypeFont FreeTypeFont FreeTypeFont->MagnumText HarfBuzzFont HarfBuzzFont HarfBuzzFont->FreeTypeFont OpenGexImporter OpenGexImporter OpenGexImporter->MagnumTrade OpenGexImporter->AnyImageImporter OpenGexImporter->MagnumOpenDdl GltfImporter GltfImporter GltfImporter->MagnumTrade GltfImporter->AnyImageImporter CgltfImporter CgltfImporter CgltfImporter->MagnumTrade CgltfImporter->AnyImageImporter UfbxImporter UfbxImporter TinyGltfImporter TinyGltfImporter TinyGltfImporter->MagnumTrade TinyGltfImporter->AnyImageImporter UfbxImporter->MagnumTrade UfbxImporter->AnyImageImporter MeshOptimizerSceneConverter MeshOptimizerSceneConverter MeshOptimizerSceneConverter->MagnumMeshTools MeshOptimizerSceneConverter->MagnumTrade StanfordSceneConverter StanfordSceneConverter StanfordImporter StanfordImporter StanfordImporter->MagnumMeshTools StanfordImporter->MagnumTrade StanfordSceneConverter->MagnumMeshTools StanfordSceneConverter->MagnumTrade

Magnum Integration

The Magnum Integration repository has the following dependency order:

Magnum Integration dependency order Magnum Magnum MagnumGL Magnum GL MagnumGL->Magnum MagnumMeshTools Magnum MeshTools MagnumMeshTools->Magnum MagnumPrimitives Magnum Primitives MagnumTrade Magnum Trade MagnumPrimitives->MagnumTrade MagnumSceneGraph Magnum SceneGraph MagnumSceneGraph->Magnum MagnumShaders Magnum Shaders MagnumShaders->MagnumGL MagnumTrade->Magnum MagnumBulletIntegration Magnum BulletIntegration MagnumBulletIntegration->MagnumGL MagnumBulletIntegration->MagnumSceneGraph MagnumBulletIntegration->MagnumShaders MagnumEigenIntegration Magnum EigenIntegration MagnumEigenIntegration->Magnum MagnumDartIntegration Magnum DartIntegration MagnumDartIntegration->MagnumGL MagnumDartIntegration->MagnumPrimitives MagnumDartIntegration->MagnumSceneGraph MagnumDartIntegration->MagnumShaders MagnumGlmIntegration Magnum GlmIntegration MagnumGlmIntegration->Magnum MagnumImGuiIntegration Magnum ImGuiIntegration MagnumImGuiIntegration->MagnumGL MagnumImGuiIntegration->MagnumShaders MagnumOvrIntegration Magnum OvrIntegration MagnumOvrIntegration->MagnumGL

Magnum Extras

The Magnum Extras repository has the following dependency order:

Magnum Extras dependency order MagnumGL Magnum GL MagnumText Magnum Text MagnumTrade Magnum Trade MagnumUi Magnum Ui MagnumUi->MagnumGL MagnumUi->MagnumText MagnumUi->MagnumTrade