Skip to content

Project structure

This chapter provides a high level overview of the project to make it easier to navigate, build, and use.

CMake projects and dependencies

The GitHub repository contains three independent CMake-based projects:

  • ./src

    • header-only project containing whole mp-units library
    • ./src/CMakeLists.txt file is intended as an entry point for library users

    • in case this library becomes part of the C++ standard, it will have no external dependencies but until then, it depends on the following:

      • gsl-lite or ms-gsl to verify runtime contracts (if contract checking is enabled),
      • {fmt} to provide text formatting of quantities (if std::format is not supported yet on a specific compiler).

  • .

    • project used as an entry point for library development and CI/CD
    • it wraps ./src project together with usage examples and tests

    • additionally to the dependencies of ./src project, it uses:

  • ./test_package

    • CMake library installation and Conan package verification.

Important: Library users should not use the top-level CMake file

Top level CMakeLists.txt file should only be used by mp-units developers and contributors as an entry point for the project's development. We want to ensure that everyone will build ALL the code correctly before pushing a commit. Having such options would allow unintended issues to leak to PRs and CI.

This is why our projects have two entry points:

  • ./CMakeLists.txt is to be used by projects developers to build ALL the project code with really restrictive compilation flags,
  • ./src/CMakeLists.txt contains only a pure library definition and should be used by the customers that prefer to use CMake's add_subdirectory() to handle the dependencies.

To learn more about the rationale, please check our FAQ.

Modules

The mp-units library provides the following C++ modules:

flowchart TD
    mp_units --- mp_units.systems --- mp_units.core
C++ Module CMake Target Contents
mp_units.core mp-units::core Core library framework and systems-independent utilities
mp_units.systems mp-units::systems All the systems of quantities and units
mp_units mp-units::mp-units Core + Systems

Note

C++ modules are provided within the package only when:

Header files

All of the project's header files can be found in the mp-units/... subdirectory.

Core library

  • mp-units/framework.h contains the entire library's framework definitions,
  • mp-units/concepts.h exposes only the library's concepts for generic code needs,
  • mp-units/format.h provides text formatting support,
  • mp-units/ostream.h enables streaming of the library's objects to the text output,
  • mp-units/math.h provides overloads of common math functions for quantities,
  • mp-units/random.h provides C++ pseudo-random number generators for quantities,
  • mp-units/compat_macros.h provides macros for wide compatibility.
More details

More detailed header files can be found in subfolders which typically should not be included by the end users:

  • mp-units/framework/... provides all the public interfaces of the framework,
  • mp-units/bits/... provides private implementation details only (no public definitions),
  • mp-units/ext/... contains external dependencies that at some point in the future should be replaced with C++ standard library facilities.

Systems and associated utilities

The systems definitions can be found in the mp-units/systems/... subdirectory:

Systems of quantities

Tip: Improving compile times

mp-units/systems/isq.h might be expensive to compile in every translation unit. There are some smaller, domain targeted files available for explicit inclusion in the mp-units/systems/isq/... subdirectory.

Systems of units

Tip: Improving compile times

mp-units/systems/si.h might be expensive to compile in every translation unit. There are some smaller files available for explicit inclusion in the mp-units/systems/si/... subdirectory.

mp-units/systems/si/unit_symbols.h is the most expensive to include.