Installation and Usage¶
This chapter explains how to obtain mp-units and build your code with it.
Obtaining dependencies¶
Most dependencies are provided via the Conan Package Manager. If you obtain them differently you may need to adjust some CMake files.
Conan quick intro
Install or upgrade Conan with:
Then create a profile for your environment in ~/.conan2/profiles. Example:
[settings]
arch=x86_64
build_type=Release
compiler=gcc
compiler.cppstd=20
compiler.libcxx=libstdc++11
compiler.version=15
os=Linux
[conf]
tools.build:compiler_executables={"c": "gcc-15", "cpp": "g++-15"}
Setting the language version
mp-units requires at least C++20. Setting it in the profile avoids repeating
-s compiler.cppstd=20
in the Conan command line command each time.
Using Ninja as a CMake generator for Conan
Prefer Ninja. You can set the tools.cmake.cmaketoolchain:generator
in ~/.conan2/global.conf:
Separate build folders for different configurations
Optionally set tools.cmake.cmake_layout:build_folder_vars
to get separate build
folders per compiler/std version:
tools.cmake.cmake_layout:build_folder_vars=["settings.compiler", "settings.compiler.version", "settings.compiler.cppstd"]
Then use a configuration-specific preset name in the Conan instructions
provided below rather than the default conan-default
and conan-release
(e.g., conan-gcc-13-23
and conan-gcc-13-23-release
)
CMake with Presets support
Use CMake 3.23+ to benefit from Conan-generated presets. Otherwise, you need to do something like:
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: auto from settings)Adds C++ modules to the default targets.
import_std
¶
-
2.3.0 路
True
/False
(Default:False
)Enables
import std;
usage.
std_format
¶
-
2.2.0 路
True
/False
(Default: auto from settings)Enables
std::format
and associated facilities for text formatting. If not supported, falls back to {fmt}.
no_crtp
¶
-
2.2.0 路
True
/False
(Default: auto from settings)Avoids CRTP in
quantity_spec
definitions.
contracts
¶
-
2.2.0 路
none
/gsl-lite
/ms-gsl
(Default: see below)Enables precondition checks and additional assertions.
If
import_std
defaults toTrue
,contracts
defaults tonone
; otherwisegsl-lite
.
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.
CMake options to set when Conan is not being used
CMake options¶
Conan sets all the below CMake options automatically 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: 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_NO_CRTP
-
2.2.0 路
ON
/OFF
(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. 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 ways to install or reuse mp-units. Below we list a few common approaches.
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:
-
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:
[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"])
-
Import mp-units and its dependencies definitions with
find_package
: -
Link your CMake targets with mp-units:
-
Download, build, and install Conan dependencies before running the CMake configuration step:
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:
-
Before starting the previous procedure, add mp-units remote to your Conan configuration:
-
In your Conan configuration file, provide the package identifier of the
mpusz/testing
stream:[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.
-
Force Conan to check for updated recipes with
-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: