Getting started » Single-header libraries

Magnum functionality exposed in easy-to-integrate single-header libraries.

Selected Magnum functionality is also available as single-header libraries, with the goal of providing significantly smaller, faster-compiling and generally better alternatives to commonly available implementations while being as easy as possible to integrate into existing projects. The general rule is having preprocessed size not not exceeding 10k lines — to put this in perspective, not even the <string> header can fit there.

So far, the following classes and libraries are provided as single-header libs, all of them available for download through the magnum-singles repository. Each of them is automatically generated from unmodified Magnum sources using the builtin single-header generator tool.

Class or library	Single-header version
Math, EigenIntegration, GlmIntegration	MagnumMath.hpp, depends on `CorradePair.h`

There are also single-header libraries for Corrade APIs.

Behavior

To keep file size small, the single-header versions have all the comments and documentation stripped away, except for a short description and a single top-level license block, containing also credit information for all contributors. Documentation is meant to be retrieved online, the wrapping namespaces and all API naming stay completely the same as when using Magnum directly.

The files retain their own include guards, which makes it possible to mix them together. However, when combining more than one, make sure to have all files from the same revision to avoid API mismatches. The concrete revision that was used to generate each library is printed in its header comment.

There are two kinds of libraries, distinguished with file extension:

The *.h extension denotes libraries that have everything inline in the header. A simple #include is all you need.
The *.hpp extension denotes libraries that have a separate implementation part with non-inline definitions. Desired usage is to build the implementation just once by defining a macro before including the library header:
```
#define MAGNUM_LIBRARYNAME_IMPLEMENTATION
#include <MagnumLibraryName.hpp>
```
In all other files the library is meant to be included without defining the macro. Thanks to this approach, complex implementation details don't inflate compile times while still keeping the library as a single file.

Customization points

All headers above are created with CORRADE_STANDARD_ASSERT enabled to avoid dragging the whole Corrade::Utility::Debug class along. Apart from that, every header includes only the assertion macros it actually needs and it's possible to override them by providing e.g. your own #define CORRADE_ASSERT before including the file. See the Corrade/Utility/Assert.h file documentation for more information.

Some files contain additional disabled-by-default functionality (for example integration with GLM and Eigen for Math types), see documentation of each library for detailed library-specific behavior.

« Extras library usage with CMake | Getting started | Using Magnum with custom buildsystems »