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:

    • Catch2 library as a unit tests framework,
    • linear algebra library based on proposal P1385 used in some examples and tests.

• ./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:

• cxx_modules Conan option is set to True,
• MP_UNITS_BUILD_CXX_MODULES CMake option is set to ON.

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

• mp-units/systems/isq.h provides International System of Quantities (ISQ) definitions,
• mp-units/systems/isq_angle.h provides a modification of the ISQ based on the proposals to make an angle a base quantity in the ISQ,

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

• mp-units/systems/si.h provides International System of Units (SI) definitions and associated math functions,
• mp-units/systems/iec.h provides units and prefixes defined by IEC (e.g., in the series of IEC 80000 standards),
• mp-units/systems/angular.h provides strong angular units and associated math functions,
• mp-units/systems/international.h provides international yard and pound units,
• mp-units/systems/imperial.h includes international.h and extends it with imperial units,
• mp-units/systems/usc.h includes international.h and extends it with United States customary system of units,
• mp-units/systems/cgs.h provides centimetre-gram-second system of units,
• mp-units/systems/iau.h provides astronomical system of units,
• mp-units/systems/hep.h provides units used in high-energy physics,
• mp-units/systems/typographic.h provides units used in typography or typesetting,
• mp-units/systems/natural.h provides an example implementation of natural 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.