magnum/doc/singles.dox

/*
    This file is part of Magnum.

    Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019,
                2020, 2021, 2022, 2023 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 singles Single-header libraries
@brief Magnum functionality exposed in easy-to-integrate single-header libraries

@m_footernavigation

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](https://github.com/mosra/magnum-singles)
repository. Each of them is automatically generated from unmodified Magnum
sources using the builtin @ref acme "single-header generator tool".

@m_class{m-fullwidth m-flat}

Class or library            | Single-header version
--------------------------- | ----------------------------
@ref Math, \n @ref EigenIntegration, \n @ref GlmIntegration | [MagnumMath.hpp](https://github.com/mosra/magnum-singles/tree/master/MagnumMath.hpp)

There are also @ref corrade-singles "single-header libraries for Corrade APIs".

@section singles-behavior 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:

<ul><li>
    The `*.h` extension denotes libraries that have everything inline in the
    header. A simple @cpp #include @ce is all you need.
</li><li>
    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:

    @code{cpp}
    #define MAGNUM_LIBRARYNAME_IMPLEMENTATION
    #include <MagnumLibraryName.hpp>
    @endcode

    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.
</li></ul>

@section singles-customization Customization points

All headers above are created with @ref CORRADE_STANDARD_ASSERT enabled to
avoid dragging the whole @ref 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
@cpp #define CORRADE_ASSERT @ce before including the file. See the
@ref 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 @ref Math types), see documentation of each
library for detailed library-specific behavior.
*/

}