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.
./test_package
- CMake library installation and Conan package verification.

!!! important "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()`](https://cmake.org/cmake/help/latest/command/add_subdirectory.html)
  to handle the dependencies.

To learn more about the rationale, please check our
[FAQ](faq.md#why-dont-we-have-cmake-options-to-disable-the-building-of-tests-and-examples).

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`](installation_and_usage.md#cxx_modules) Conan option is set to `True`,
- [`MP_UNITS_BUILD_CXX_MODULES`](installation_and_usage.md#MP_UNITS_BUILD_CXX_MODULES)
  CMake option is set to `ON`.

In addition, ./src/integrations hosts optional, self-contained integrations with third-party libraries. Each component owns its mp-units/integrations/<lib>.h header and, in a C++ modules build, the matching mp_units.integrations.<lib> module:

C++ Module	CMake Target	Third-party library
`mp_units.integrations.eigen`	`mp-units::integrations-eigen`	Eigen
`mp_units.integrations.glm`	`mp-units::integrations-glm`	GLM
`mp_units.integrations.blaze`	`mp-units::integrations-blaze`	Blaze

Each depends only on mp_units.core and is built solely when the matching third-party library is found (the module is added on top in a C++ modules build). A component is exported separately (find_package(mp-units-integrations-<lib>)), never through mp-unitsTargets, so that find_package(mp-units) never gains a dependency on a third-party library.

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.

??? info "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.

Third-party library integrations

Optional, opt-in headers under mp-units/integrations/ that adapt a third-party library to mp-units. Each is guarded with __has_include (a harmless no-op when its library is unavailable) and has a module counterpart (mp_units.integrations.<lib>). Currently these adapt linear algebra libraries, letting their vector and matrix types be used directly as quantity representations:

mp-units/integrations/eigen.h integrates Eigen,
mp-units/integrations/glm.h integrates GLM,
mp-units/integrations/blaze.h integrates Blaze.

See Representation Types for usage.

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 "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/yard_pound.h provides base units from the 1959 international yard and pound agreement,
mp-units/systems/imperial.h includes yard_pound.h and extends it with British Imperial units,
mp-units/systems/usc.h includes yard_pound.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.