Skip to content

Installation And Usage

This chapter provides all the necessary information to obtain and build the code using mp-units. It also describes how to build or distribute the library and generate its documentation.

Project structure

Repository directory tree and dependencies

The GitHub repository contains three independent CMake-based projects:

  • ./src

    • header-only project containing whole mp-units library
    • ./src/CMakeList.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.

Obtaining dependencies

This library assumes that most of the dependencies will be provided by the Conan Package Manager. If you want to obtain required dependencies by other means, some modifications to the library's CMake files might be needed. The rest of the dependencies responsible for documentation generation are provided by python3-pip.

Conan quick intro

In case you are not familiar with Conan, to install it (or upgrade) just do:

pip install -U conan

After that, you might need to add a custom profile file for your development environment in ~/.conan2/profiles directory. An example profile can look as follows:

~/.conan2/profiles/gcc12
[settings]
arch=x86_64
build_type=Release
compiler=gcc
compiler.cppstd=20
compiler.libcxx=libstdc++11
compiler.version=12
os=Linux

[conf]
tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}

Setting the language version

Please note that the mp-units library requires at least C++20 to be set in a Conan profile or forced via the Conan command line. If we do the former, we will not need to provide -s compiler.cppstd=20 every time we run a Conan command line (as provided in the command line instructions below).

Using Ninja as a CMake generator for Conan

It is highly recommended to set Ninja as a CMake generator for Conan. To do so, we should create a ~/.conan2/global.conf file that will set tools.cmake.cmaketoolchain:generator to one of the Ninja generators. For example:

~/.conan2/global.conf
tools.cmake.cmaketoolchain:generator="Ninja Multi-Config"

Separate build folders for different configurations

~/.conan2/global.conf file may also set tools.cmake.cmake_layout:build_folder_vars which makes working with several compilers or build configurations easier. For example, the below line will force Conan to generate separate CMake presets and folders for each compiler and C++ standard version:

~/.conan2/global.conf
tools.cmake.cmake_layout:build_folder_vars=["settings.compiler", "settings.compiler.version", "settings.compiler.cppstd"]

In such a case, we will need to use a configuration-specific preset name in the Conan instructions provided below rather than just conan-default and conan-release (e.g. conan-gcc-13-23 and conan-gcc-13-23-release)

Build options

Note

Most of the below options are related to the C++ language features available in the compilers. Please refer to the C++ compiler support chapter to learn more about which C++ features are required and which compiler support them.

Conan options

cxx_modules

2.2.0 · auto/True/False (Default: auto)

Configures CMake to add C++ modules to the list of default targets.

std_format

2.2.0 · auto/True/False (Default: auto)

Enables the usage of std::format and associated facilities for text formatting. If it is not supported, then the {fmt} library is used instead.

string_view_ret

2.2.0 · auto/True/False (Default: auto)

Enables returning std::string_view from the unit_symbol() and dimension_symbol() functions. If this feature is not available, those functions will return mp_units::basic_fixed_string<CharT, N> instead.

no_crtp

2.2.0 · auto/True/False (Default: auto)

Removes the need for the usage of the CRTP idiom in the quantity_spec definitions.

contracts

2.2.0 · none/gsl-lite/ms-gsl (Default: gsl-lite)

Enables checking of preconditions and additional asserts in the code.

freestanding

2.2.0 · True/False (Default: False)

Configures the library in the freestanding mode. When enabled, the library's source code should build with the compiler's -ffreestanding compilation option without any issues.

Conan configuration properties

user.mp-units.build:all

2.2.0 · True/False (Default: False)

Enables compilation of all the source code, including tests and examples. To support this, it requires some additional Conan build dependencies described in Repository directory tree and dependencies. It also runs unit tests during Conan build (unless tools.build:skip_test configuration property is set to True).

user.mp-units.build:skip_la

2.2.0 · True/False (Default: False)

If user.mp-units.build:all is enabled, among others, Conan installs the external wg21-linear_algebra dependency and enables the compilation of linear algebra-based tests and usage examples. Such behavior can be disabled with this option.

user.mp-units.analyze:clang-tidy

2.2.0 · True/False (Default: False)

Enables clang-tidy analysis.

CMake options

MP_UNITS_BUILD_AS_SYSTEM_HEADERS

2.2.0 · ON/OFF (Default: OFF)

Exports library as system headers.

MP_UNITS_BUILD_CXX_MODULES

2.2.0 · ON/OFF (Default: OFF)

Adds C++ modules to the list of default targets.

MP_UNITS_API_STD_FORMAT

2.2.0 · AUTO/TRUE/FALSE (Default: AUTO)

Enables the usage of std::format and associated facilities for text formatting. If it is not supported, then the {fmt} library is used instead.

MP_UNITS_API_STRING_VIEW_RET

2.2.0 · AUTO/TRUE/FALSE (Default: AUTO)

Enables returning std::string_view from the unit_symbol() and dimension_symbol() functions. If this feature is not available, those functions will return mp_units::basic_fixed_string<CharT, N> instead.

MP_UNITS_API_NO_CRTP

2.2.0 · AUTO/TRUE/FALSE (Default: AUTO)

Removes the need for the usage of the CRTP idiom in the quantity_spec definitions.

MP_UNITS_API_CONTRACTS

2.2.0 · NONE/GSL-LITE/MS-GSL (Default: GSL-LITE)

Enables checking of preconditions and additional asserts in the code.

MP_UNITS_API_FREESTANDING

2.2.0 · ON/OFF (Default: OFF)

Configures the library in the freestanding mode. When enabled, the library's source code should build with the compiler's -ffreestanding compilation option without any issues.

Options for mp-units project developers

MP_UNITS_DEV_BUILD_LA

2.2.0 · ON/OFF (Default: ON)

Enables building code depending on the linear algebra library.

MP_UNITS_DEV_IWYU

2.2.0 · ON/OFF (Default: OFF)

Enables include-what-you-use analysis.

MP_UNITS_DEV_CLANG_TIDY

2.2.0 · ON/OFF (Default: OFF)

Enables clang-tidy analysis.

CMake with presets support

It is recommended to use at least CMake 3.23 to build this project as this version introduced support for CMake Presets schema version 4, used now by Conan to generate presets files. All build instructions below assume that you have such support. If not, your CMake invocations have to be replaced with something like:

mkdir build && cd build
cmake .. -G "Ninja Multi-Config" -DCMAKE_TOOLCHAIN_FILE=<path_to_generators_dir>/conan_toolchain.cmake
cmake --build . --config Release

Tip

In case you can't use CMake 3.23 but you have access to CMake 3.20 or later, you can append -c tools.cmake.cmaketoolchain.presets:max_schema_version=2 to the conan install command which will force Conan to use an older version of the CMake Presets schema.

Installation and reuse

There are many different ways of installing/reusing mp-units in your project. Below we mention only a few of many options possible.

Important: Prefer using Conan if possible

The easiest and most recommended way to obtain mp-units is with the Conan package manager. See Conan + CMake (release) for a detailed instruction.

Copy

As mp-units is a C++ header-only library you can simply copy all needed src/*/include subdirectories to your source tree.

Note

In such a case, you are on your own to ensure all the dependencies are installed and their header files can be located during the build. Please also note that some compiler-specific flags are needed to make the code compile without issues.

Copy + CMake

If you copy the whole mp-units repository to your project's file tree, you can reuse CMake targets defined by the library. To do so, you should use CMakeLists.txt file from the ./src directory:

add_subdirectory(<path_to_units_folder>/src)
# ...
target_link_libraries(<your_target> <PUBLIC|PRIVATE|INTERFACE> mp-units::mp-units)

Note

You are still on your own to make sure all the dependencies are installed and their header and CMake configuration files can be located during the build.

Conan + CMake (release)

Tip

If you are new to the Conan package manager, it is highly recommended to read Obtaining Dependencies and refer to Consuming packages chapter of the official Conan documentation for more information.

mp-units releases are hosted on Conan-Center. The following steps may be performed to obtain an official library release:

  1. Create Conan configuration file (either conanfile.txt or conanfile.py) in your project's top-level directory and add mp-units as a dependency of your project. For example, the simplest file may look as follows:

    conanfile.txt
    [requires]
mp-units/2.2.0

[options]
mp-units:cxx_modules=True

[layout]
cmake_layout

[generators]
CMakeToolchain
CMakeDeps

  2. Import mp-units and its dependencies definitions to your project's build procedure with find_package:

    find_package(mp-units REQUIRED)

  3. Link your CMake targets with mp-units:

    target_link_libraries(<your_target> <PUBLIC|PRIVATE|INTERFACE> mp-units::mp-units)

  4. Download, build, and install Conan dependencies before running the CMake configuration step:

    conan install . -pr <your_conan_profile> -s compiler.cppstd=20 -b=missing
cmake --preset conan-default
cmake --build --preset conan-release

Conan + CMake (Live At Head)

This chapter describes the procedure to Live At Head, which means using the latest stable version of mp-units all the time.

Note

Please note that even though the Conan packages that you will be using are generated ONLY for builds that are considered stable (passed our CI tests), some minor regressions may happen (our CI and C++20 build environment is not perfect yet). Also, please expect that the library interface might, and probably will, change occasionally. Even though we do our best, such changes might not be reflected in the project's documentation right away.

The procedure is similar to the one described in Conan + CMake (release) with the following differences:

  1. Before starting the previous procedure, add mp-units remote to your Conan configuration:

    conan remote add conan-mpusz https://mpusz.jfrog.io/artifactory/api/conan/conan-oss

  2. In your Conan configuration file, provide the package identifier of the mpusz/testing stream:

    conanfile.txt
    [requires]
mp-units/2.3.0@mpusz/testing

[options]
mp-units:cxx_modules=True

[layout]
cmake_layout

[generators]
CMakeToolchain
CMakeDeps

    Tip

    The identifiers of the latest packages can always be found in the project's README file or on the project's Artifactory.

  3. Force Conan to check for updated recipes with -u:

    conan install . -pr <your_conan_profile> -s compiler.cppstd=20 -b=missing -u

Install

In case you don't want to use Conan in your project and just want to install the mp-units library on your file system and use find_package(mp-units) from another repository to find it; it is enough to perform the following steps:

conan install . -pr <your_conan_profile> -s compiler.cppstd=20 -b=missing
mv CMakeUserPresets.json src
cd src
cmake --preset conan-default -DCMAKE_INSTALL_PREFIX=<your_installation_path>
cmake --build --preset conan-release --target install

Contributing (or just building all the tests and examples)

In case you would like to build all the mp-units source code (with unit tests and examples), you should:

  1. Use the CMakeLists.txt from the top-level directory.
  2. Run Conan with user.mp-units.build:all = True.
git clone https://github.com/mpusz/mp-units.git && cd units
conan build . -pr <your_conan_profile> -s compiler.cppstd=23 -o cxx_modules=True -c user.mp-units.build:all=True -b missing

The above will download and install all of the dependencies needed for the development of the library, build all of the source code, and run unit tests.

If you prefer to build the project via CMake rather than Conan, then you should replace the conan build with conan install command and then follow with a regular CMake build:

cmake --preset conan-default
cmake --build --preset conan-release
cmake --build --preset conan-release --target all_verify_interface_header_sets
cmake --build --preset conan-release --target test

Building documentation

Starting from mp-units 2.0 we are using Material for MkDocs to build our documentation. The easiest way to install all the required dependencies is with pip:

pip install -U mkdocs-material mkdocs-rss-plugin

Additionally, a Cairo Graphics library is required by Material for MkDocs. Please follow the official MkDocs documentation to install it.

After that, you can either:

Packaging

To test CMake installation and Conan packaging or create a Conan package run:

conan create . --user <username> --channel <channel> -pr <your_conan_profile> -s compiler.cppstd=20 -o cxx_modules=True -c user.mp-units.build:all=True -b missing

The above will create a Conan package and run tests provided in ./test_package directory.

Uploading mp-units package to the Conan server

conan upload -r <remote-name> --all mp-units/2.2.0@<user>/<channel>