Installation And Usage

This chapter provides all the necessary information to obtain mp-units and build the user's source code using it.

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.

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=14
os=Linux

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

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 could 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)

CMake with presets support

It is recommended to use at least CMake 3.23 to build this project to benefit from CMake Presets generated by Conan. 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.

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 for each option and which compilers support them.

Conan options

cxx_modules

2.2.0 · True/False (Default: automatically determined from settings)

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

import_std

2.3.0 · True/False (Default: False)

Enables import std; usage.

std_format

2.2.0 · True/False (Default: automatically determined from settings)

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

no_crtp

2.2.0 · True/False (Default: automatically determined from settings)

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: see below)

Enables checking of preconditions and additional assertions in the code.

If the automatically determined default for import_std is True, then the contracts option is set to none by default. gsl-lite otherwise.

freestanding

2.2.0 · True/False (Default: False)

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

natural_units

2.5.0 · ON/OFF (Default: ON)

Enables experimental natural units systems support.

CMake options to set when Conan is not being used

CMake options

Conan will automatically set all the below CMake options based on its configuration (described above). Manual setting of the below CMake options is only needed when Conan is not being used.

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 · ON/OFF (Default: automatically determined)

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_NO_CRTP

2.2.0 · ON/OFF (Default: automatically determined)

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.

MP_UNITS_API_NATURAL_UNITS

2.5.0 · ON/OFF (Default: ON)

Enables experimental natural units systems support.

MP_UNITS_INSTALL

2.5.0 · ON/OFF (Default: ON)

Creates an installable target. Users may want to turn this off for example when consuming the library via CMake's add_subdirectory or similar mechanisms.

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.

Conan + CMake (release)

Tip

If you are new to the Conan package manager you may want to read Obtaining Dependencies and refer to the 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.txtconanfile.py

   [requires]
   mp-units/2.4.0
   
   [options]
   # The below mp-units options are set to defaults by Conan.
   # Uncomment and set to an explicit value to override the defaults.
   #
   # mp-units*:cxx_modules=True
   # mp-units*:import_std=False
   # mp-units*:std_format=True
   # mp-units*:no_crtp=True
   # mp-units*:contracts=gsl-lite
   # mp-units*:freestanding=False
   
   [layout]
   cmake_layout
   
   [generators]
   CMakeToolchain
   CMakeDeps
   

   from conan import ConanFile
   from conan.tools.build import can_run
   from conan.tools.cmake import CMake, cmake_layout
   
   class MPUnitsTestConan(ConanFile):
       settings = "os", "arch", "compiler", "build_type"
       generators = "CMakeDeps", "CMakeToolchain"
   
       def requirements(self):
           self.requires(
               "mp-units/2.4.0",
               options={
                   # The below mp-units options are set to defaults by Conan.
                   # Uncomment and set to an explicit value to override the defaults.
                   #
                   # "cxx_modules": False,
                   # "import_std": False,
                   # "std_format": True,
                   # "no_crtp": True,
                   # "contracts": "gsl-lite",
                   # "freestanding": False,
               },
           )
   
       def layout(self):
           cmake_layout(self)
   
       def build(self):
           cmake = CMake(self)
           cmake.configure()
           cmake.build()
           if can_run(self):
               cmake.ctest(cli_args=["--output-on-failure"])
   

2. Import mp-units and its dependencies definitions 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:

   conanfile.txt or conanfile.pyconanfile.py only

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

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

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 (CI and C++ build environments are 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.txtconanfile.py

   [requires]
   mp-units/2.5.0@mpusz/testing
   
   [options]
   # The below mp-units options are set to defaults by Conan.
   # Uncomment and set to an explicit value to override the defaults.
   #
   # mp-units*:cxx_modules=True
   # mp-units*:import_std=False
   # mp-units*:std_format=True
   # mp-units*:no_crtp=True
   # mp-units*:contracts=gsl-lite
   # mp-units*:freestanding=False
   
   [layout]
   cmake_layout
   
   [generators]
   CMakeToolchain
   CMakeDeps
   

   from conan import ConanFile
   from conan.tools.build import can_run
   from conan.tools.cmake import CMake, cmake_layout
   
   class MPUnitsTestConan(ConanFile):
       settings = "os", "arch", "compiler", "build_type"
       generators = "CMakeDeps", "CMakeToolchain"
   
       def requirements(self):
           self.requires(
               "mp-units/2.5.0@mpusz/testing",
               options={
                   # The below mp-units options are set to defaults by Conan.
                   # Uncomment and set to an explicit value to override the defaults.
                   #
                   # "cxx_modules": False,
                   # "import_std": False,
                   # "std_format": True,
                   # "no_crtp": True,
                   # "contracts": "gsl-lite",
                   # "freestanding": False,
               },
           )
   
       def layout(self):
           cmake_layout(self)
   
       def build(self):
           cmake = CMake(self)
           cmake.configure()
           cmake.build()
           if can_run(self):
               cmake.ctest(cli_args=["--output-on-failure"])
   

   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
   

Alternative installation scenarios

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 mp-units library source code from the project's ./src directory (not the entire repo from its root), 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_mp_units_lib_folder>)
# ...
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.

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

CPM or FetchContent (CMake)

mp-units can be consumed via CPM or CMake's built-in FetchContent mechanism. An example CPM configuration is shown below.

CPMFindPackage(
    NAME mp-units
    VERSION 2.4.0
    GIT_TAG 6e06eddf205deaf6c2f2f63500c8c70ec220a99f
    GITHUB_REPOSITORY mpusz/mp-units
    SOURCE_SUBDIR src
    SYSTEM YES
    EXCLUDE_FROM_ALL YES
    OPTIONS
        "MP_UNITS_BUILD_AS_SYSTEM_HEADERS ON"
        "MP_UNITS_INSTALL OFF"
)
# ...
target_link_libraries(<your_target> <PUBLIC|PRIVATE|INTERFACE> mp-units::mp-units)

Note

This is essentially a shortcut way to do what Copy + CMake mentions above, so the same prerequisites apply.

Install

If 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