mpusz/mp-units
1
0
Fork 1
mirror of https://github.com/mpusz/mp-units.git synced 2025-07-29 18:07:16 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: Rework of "Getting Started" section

Browse Source 
Inspired by #603
This commit is contained in:
Mateusz Pusz
2024-09-05 08:17:35 +02:00
parent f0e19d004c
commit 2a4e1e3d95
5 changed files with 530 additions and 520 deletions
Download Patch File Download Diff File Expand all files Collapse all files

297
CONTRIBUTING.md
View File

@ -1,93 +1,220 @@
# Contributing to `mp-units` # Contributing
👍🎉 First off, thanks for taking the time to contribute! 🎉👍 👍🎉 First off, thanks for taking the time to contribute! 🎉👍
## Gitpod
The easiest way to start coding is to jump straight into [Gitpod](https://www.gitpod.io). You can either click the button
below or prefix any `mp-units` URL (main branch, other branches, issues, PRs, ...) in your web browser with `gitpod.io/#`
(e.g., <https://gitpod.io/#https://github.com/mpusz/mp-units>).
[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/mpusz/mp-units)
The above environment provides you with:
- all supported compilers for Linux development and the latest version of build tools like `cmake` and `conan`
- all Conan dependencies preinstalled on the machine
- all documentation generation tools ready to use
- completed prebuilds for all targets (Debug and Release builds for each compiler)
- VSCode preconfigured to benefit from all the above
## Download, Build, Install
Alternatively, please refer to our official docs for
[download, build, and install instructions](https://mpusz.github.io/mp-units/latest/getting_started/installation_and_usage)
if you want to setup a development environment on your local machine.
## Before Committing git Changes
There are a few steps recommended to check before committing and pushing your changes to the git repository.
### Naming Conventions
Here are the main rules for naming things in this repo:
- types, functions, variables naming in a `standard_case`
- template parameters in a `PascalCase`
- C++20 concepts names for now in a `PascalCase` but we plan to change it (see <https://github.com/mpusz/mp-units/issues/93>
for more details)
### Unified Code Formatting
There is a formatting standard enforced with the `pre-commit` script. Before committing your changes please do the following:
```bash
pip3 install -U pre-commit
pre-commit run --all-files
```
This will run `clang-format` for code formatting with the `.clang-format` file provided in the repo, `cmake-format` to format
the CMake files, and some other check as well.
The script will run on all the files in the repo and will apply the changes in-place when needed.
After the script is done please make sure to stage all those changes to git commit.
### Build All CMake Targets And Run Unit Tests
The simplest way to verify if all targets build correctly and all unit tests pass is to run:
```bash
conan build . -pr <your_conan_profile> -s compiler.cppstd=23 -o cxx_modules=True -c user.mp-units.build:all=True -b missing
```
as described in the
[Installation and Usage](https://mpusz.github.io/mp-units/latest/getting_started/installation_and_usage/#contributing-or-just-building-all-the-tests-and-examples)
chapter of our documentation.
_Hint:_ To ensure that that we always build all the targets and to save some typing of the Conan commands,
it is a good practice to set the following in the `~/.conan2/global.conf`:
```text
user.mp-units.build:all=True
```
Non-Conan users should:
- build `all` and `all_verify_interface_header_sets` CMake targets,
- run all unit tests.
### Backward Compatibility
Before submission, please remember to check if the code compiles fine on the supported compilers.
The CI will check it anyway but it is good to check at least some of the configurations before pushing changes.
Especially older compilers can be tricky as those do not support all the C++20 features well enough. The official
list of supported compilers can be always found in the
[Installation And Usage](https://mpusz.github.io/mp-units/latest/getting_started/cpp_compiler_support)
chapter of our documentation.
## Where To Start? ## Where To Start?
If you are looking for a good issue to start with, please check the following: If you are looking for a good issue to start with, please check the following:
- [good first issue](https://github.com/mpusz/mp-units/labels/good%20first%20issue) - issues that should be pretty simple to implement. - [good first issue](https://github.com/mpusz/mp-units/labels/good%20first%20issue) - issues that
- [help wanted](https://github.com/mpusz/mp-units/labels/help%20wanted) - issues that typically are a bit more involved than beginner issues. should be pretty simple to implement,
- [high priority](https://github.com/mpusz/mp-units/labels/high%20priority) - things to fix ASAP but often of higher complexity. - [help wanted](https://github.com/mpusz/mp-units/labels/help%20wanted) - issues that typically are
a bit more involved than beginner issues,
- [high priority](https://github.com/mpusz/mp-units/labels/high%20priority) - things to fix ASAP
but often of higher complexity.
## Gitpod
The easiest way to start coding is to jump straight into [Gitpod](https://www.gitpod.io)
environment. You can either click the button below
[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/mpusz/mp-units)
or prefix any `mp-units` URL (main branch, other branches, issues, PRs, ...) in your web browser
with `gitpod.io/#` (e.g., <https://gitpod.io/#https://github.com/mpusz/mp-units>).
The above environment provides you with:
- all supported compilers for Linux development and the latest version of build tools like `cmake`
and `conan`,
- all Conan dependencies preinstalled on the machine,
- all documentation generation tools ready to use,
- completed prebuilds for all targets (Debug and Release builds for each compiler),
- VSCode preconfigured to benefit from all the above.
## Building, testing, and packaging
Alternatively, please refer to our official docs for
[download, build, and install instructions](https://mpusz.github.io/mp-units/latest/getting_started/installation_and_usage) with the below changes
if you want to set up a development environment on your local machine.
### Conan configuration properties
[`user.mp-units.build:all`](#user.mp-units.build-all){ #user.mp-units.build-all }
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](https://mpusz.github.io/mp-units/latest/getting_started/project_structure#cmake-projects-and-dependencies).
It also runs unit tests during the Conan build (unless
[`tools.build:skip_test`](https://docs.conan.io/2/reference/commands/config.html?highlight=tools.build:skip_test#conan-config-list)
configuration property is set to `True`).
[conan build all support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[`user.mp-units.build:skip_la`](#user-skip-la){ #user-skip-la }
If `user.mp-units.build:all` is enabled, among others, Conan installs the external
[wg21-linear_algebra](https://conan.io/center/recipes/wg21-linear_algebra)
dependency and enables the compilation of linear algebra-based tests and usage examples.
Such behavior can be disabled with this option.
[conan skip la support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[`user.mp-units.analyze:clang-tidy`](#user.mp-units.analyze-clang-tidy){ #user.mp-units.analyze-clang-tidy }
Enables clang-tidy analysis.
[conan clang-tidy support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
### CMake options for mp-units project developers
[`MP_UNITS_DEV_BUILD_LA`](#MP_UNITS_DEV_BUILD_LA){ #MP_UNITS_DEV_BUILD_LA }
:   [:octicons-tag-24: 2.2.0][cmake build la support] · :octicons-milestone-24: `ON`/`OFF` (Default: `ON`)
Enables building code depending on the linear algebra library.
[cmake build la support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[`MP_UNITS_DEV_IWYU`](#MP_UNITS_DEV_IWYU){ #MP_UNITS_DEV_IWYU }
:   [:octicons-tag-24: 2.2.0][cmake iwyu support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
Enables include-what-you-use analysis.
[cmake iwyu support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[`MP_UNITS_DEV_CLANG_TIDY`](#MP_UNITS_DEV_CLANG_TIDY){ #MP_UNITS_DEV_CLANG_TIDY }
:   [:octicons-tag-24: 2.2.0][cmake clang-tidy support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
Enables clang-tidy analysis.
[cmake clang-tidy support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
### Building the entire repository
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`](#user.mp-units.build-all) = `True`.
```shell
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 and testing:
```shell
conan install . -pr <your_conan_profile> -s compiler.cppstd=23 -o '&:cxx_modules=True' -c user.mp-units.build:all=True -b missing
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
```
!!! hint
To ensure that we always build all the targets and to save some typing of the Conan commands,
we can set the following in the `~/.conan2/global.conf`:
```text
user.mp-units.build:all=True
```
### Packaging
To test CMake installation and Conan packaging run:
```shell
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.
In case you would like to upload **mp-units** package to the Conan server do the following:
```shell
conan upload -r <remote-name> --all mp-units/2.2.0@<user>/<channel>
```
## Building documentation
We are building our documentation using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). The easiest way to install all the required dependencies is with `pip`:
```shell
pip install -U mkdocs-material mkdocs-rss-plugin
```
Additionally, a [Cairo Graphics library](https://www.cairographics.org/) is required by
Material for MkDocs. Please follow the
[official MkDocs documentation to install it](https://squidfunk.github.io/mkdocs-material/plugins/requirements/image-processing/#cairo-graphics).
After that, you can either:
- easily [start a live server to preview the documentation as you write](https://squidfunk.github.io/mkdocs-material/creating-your-site/#previewing-as-you-write)
```shell
mkdocs serve
```
- [build the documentation](https://squidfunk.github.io/mkdocs-material/creating-your-site/#building-your-site)
```shell
mkdocs build
```
## Before Committing git Changes
There are a few steps recommended to check before committing and pushing your changes to the git
repository.
### Naming Conventions
Here are the main rules for naming things in this repo:
- types, functions, variables use `standard_case`,
- template parameters use `PascalCase`,
- C++ concept names, for now, use `PascalCase`, but we plan to change it
(see [GitHub Issue #93](https://github.com/mpusz/mp-units/issues/93) for more details).
### Unified Code Formatting
A formatting standard is enforced with the `pre-commit` script. Before committing your changes, please do the following:
```bash
pip install -U pre-commit
pre-commit run --all-files
```
This will run:
- `clang-format` for code formatting with the `.clang-format` file provided in the repo,
- `cmake-format` to format the CMake files,
- some other checks (e.g., python script checkers, whitespaces, etc.).
The script will run on all the files in the repo and will apply the changes in place when needed.
After the script is done, please make sure to review and stage all those changes for the git commit.
### Backward Compatibility
Before submission, please remember to check if the code compiles fine on the supported compilers.
The CI will check it anyway, but it is good to check at least some of the configurations before
pushing changes.
Especially older compilers can be tricky as those do not have full C++20 conformance.
The official list of supported compilers can be always found in the
[C++ compiler support (API/ABI)](https://mpusz.github.io/mp-units/latest/getting_started/cpp_compiler_support) chapter of our documentation.

1
docs/getting_started/contributing.md Symbolic link
View File

@ -0,0 +1 @@
../../CONTRIBUTING.md

600
docs/getting_started/installation_and_usage.md
View File

@ -1,155 +1,7 @@
# Installation And Usage # Installation And Usage
This chapter provides all the necessary information to obtain and build the code using **mp-units**. This chapter provides all the necessary information to obtain **mp-units** and build the user's
It also describes how to build or distribute the library and generate its documentation. source code using it.
## Project structure
### Repository directory tree and dependencies
The [GitHub repository](https://github.com/mpusz/mp-units) 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](https://github.com/gsl-lite/gsl-lite) or [ms-gsl](https://github.com/microsoft/GSL)
to verify runtime contracts (if contract checking is enabled),
- [{fmt}](https://github.com/fmtlib/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](https://github.com/catchorg/Catch2) library as a unit tests framework,
- [linear algebra](https://github.com/BobSteagall/wg21/tree/master/include)
library based on proposal [P1385](https://wg21.link/P1385) used in some examples
and tests.
- **_./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:
```mermaid
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`](#cxx_modules) Conan option is set to `True`,
- [`MP_UNITS_BUILD_CXX_MODULES`](#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](../users_guide/use_cases/wide_compatibility.md).
??? 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.
#### 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)](https://en.wikipedia.org/wiki/International_System_of_Quantities)
definitions,
??? 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)](https://en.wikipedia.org/wiki/International_System_of_Units)
definitions and associated math functions,
- `mp-units/systems/angular.h` provides strong angular units and associated math functions,
- `mp-units/systems/international.h` provides
[international yard and pound](https://en.wikipedia.org/wiki/International_yard_and_pound) units,
- `mp-units/systems/imperial.h` includes `international.h` and extends it with
[imperial units](https://en.wikipedia.org/wiki/Imperial_units),
- `mp-units/systems/usc.h` includes `international.h` and extends it with
[United States customary system of units](https://en.wikipedia.org/wiki/United_States_customary_units),
- `mp-units/systems/cgs.h` provides
[centimetre-gram-second system of units](https://en.wikipedia.org/wiki/Centimetre%E2%80%93gram%E2%80%93second_system_of_units),
- `mp-units/systems/iau.h` provides
[astronomical system of units](https://en.wikipedia.org/wiki/Astronomical_system_of_units),
- `mp-units/systems/hep.h` provides units used in
[high-energy physics](https://en.wikipedia.org/wiki/Particle_physics),
- `mp-units/systems/typographic.h` provides units used in
[typography or typesetting](https://en.wikipedia.org/wiki/Typographic_unit),
- `mp-units/systems/natural.h` provides an example implementation of
[natural units](https://en.wikipedia.org/wiki/Natural_units).
??? tip "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 ## Obtaining dependencies
@ -157,66 +9,82 @@ The systems definitions can be found in the `mp-units/systems/...` subdirectory:
This library assumes that most of the dependencies will be provided by the This library assumes that most of the dependencies will be provided by the
[Conan Package Manager](https://conan.io/). If you want to obtain required [Conan Package Manager](https://conan.io/). If you want to obtain required
dependencies by other means, some modifications to the library's CMake files might be needed. 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 ??? info "Conan quick intro"
In case you are not familiar with Conan, to install it (or upgrade) just do: In case you are not familiar with Conan, to install it (or upgrade) just do:
```shell ```shell
pip install -U conan 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:
```ini hl_lines="5" title="~/.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"}
```
!!! tip "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).
!!! tip "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:
```text title="~/.conan2/global.conf"
tools.cmake.cmaketoolchain:generator="Ninja Multi-Config"
``` ```
!!! tip "Separate build folders for different configurations" 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/global.conf_ file may also set `tools.cmake.cmake_layout:build_folder_vars` which ```ini hl_lines="5" title="~/.conan2/profiles/gcc12"
[makes working with several compilers or build configurations easier](https://docs.conan.io/2/reference/tools/cmake/cmake_layout.html#multi-setting-option-cmake-layout). [settings]
For example, the below line will force Conan to generate separate CMake presets and folders for arch=x86_64
each compiler and C++ standard version: build_type=Release
compiler=gcc
compiler.cppstd=20
compiler.libcxx=libstdc++11
compiler.version=12
os=Linux
```text title="~/.conan2/global.conf" [conf]
tools.cmake.cmake_layout:build_folder_vars=["settings.compiler", "settings.compiler.version", "settings.compiler.cppstd"] tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}
``` ```
In such a case, we will need to use a configuration-specific preset name in the Conan instructions !!! tip "Setting the language version"
provided below rather than just `conan-default` and `conan-release`
(e.g. `conan-gcc-13-23` and `conan-gcc-13-23-release`) 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).
!!! tip "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:
```text title="~/.conan2/global.conf"
tools.cmake.cmaketoolchain:generator="Ninja Multi-Config"
```
!!! tip "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](https://docs.conan.io/2/reference/tools/cmake/cmake_layout.html#multi-setting-option-cmake-layout).
For example, the below line will force Conan to generate separate CMake presets and folders for
each compiler and C++ standard version:
```text title="~/.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`)
??? info "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:
```shell
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 ## Build options
@ -225,7 +93,7 @@ tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}
Most of the below options are related to the C++ language features available in the compilers. Most of the below options are related to the C++ language features available in the compilers.
Please refer to the [C++ compiler support](cpp_compiler_support.md) chapter to learn more Please refer to the [C++ compiler support](cpp_compiler_support.md) chapter to learn more
about which C++ features are required and which compiler support them. about which C++ features are required for each option and which compilers support them.
### Conan options ### Conan options
@ -289,166 +157,92 @@ tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}
: [:octicons-tag-24: 2.2.0][conan freestanding] · :octicons-milestone-24: `True`/`False` (Default: `False`) : [:octicons-tag-24: 2.2.0][conan freestanding] · :octicons-milestone-24: `True`/`False` (Default: `False`)
Configures the library in the [freestanding](https://en.cppreference.com/w/cpp/freestanding) Configures the library in the [freestanding](https://en.cppreference.com/w/cpp/freestanding)
mode. When enabled, the library's source code should build with the compiler's mode. When enabled, the library's source code will build with the compiler's
[`-ffreestanding`](https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html) compilation option [`-ffreestanding`](https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html) compilation option
without any issues. without any issues.
[conan freestanding]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 [conan freestanding]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
### Conan configuration properties ??? info "CMake options to set when Conan is not being used"
[`user.mp-units.build:all`](#user.mp-units.build-all){ #user.mp-units.build-all } ### CMake options
: [:octicons-tag-24: 2.2.0][conan build all support] · :octicons-milestone-24: `True`/`False` (Default: `False`) 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.
Enables compilation of all the source code, including tests and examples. To support this, it requires some additional Conan build dependencies described in [`MP_UNITS_BUILD_AS_SYSTEM_HEADERS`](#MP_UNITS_BUILD_AS_SYSTEM_HEADERS){ #MP_UNITS_BUILD_AS_SYSTEM_HEADERS }
[Repository directory tree and dependencies](#repository-directory-tree-and-dependencies).
It also runs unit tests during Conan build (unless
[`tools.build:skip_test`](https://docs.conan.io/2/reference/commands/config.html?highlight=tools.build:skip_test#conan-config-list)
configuration property is set to `True`).
[conan build all support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 : [:octicons-tag-24: 2.2.0][cmake as system headers support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
[`user.mp-units.build:skip_la`](#user-skip-la){ #user-skip-la } Exports library as system headers.
: [:octicons-tag-24: 2.2.0][conan skip la support] · :octicons-milestone-24: `True`/`False` (Default: `True`) [cmake as system headers support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
If `user.mp-units.build:all` is enabled, among others, Conan installs the external [`MP_UNITS_BUILD_CXX_MODULES`](#MP_UNITS_BUILD_CXX_MODULES){ #MP_UNITS_BUILD_CXX_MODULES }
[wg21-linear_algebra](https://conan.io/center/recipes/wg21-linear_algebra)
dependency and enables the compilation of linear algebra-based tests and usage examples.
Such behavior can be disabled with this option.
[conan skip la support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 : [:octicons-tag-24: 2.2.0][cmake build cxx modules support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
[`user.mp-units.analyze:clang-tidy`](#user.mp-units.analyze-clang-tidy){ #user.mp-units.analyze-clang-tidy } Adds C++ modules to the list of default targets.
: [:octicons-tag-24: 2.2.0][conan clang-tidy support] · :octicons-milestone-24: `True`/`False` (Default: `False`) [cmake build cxx modules support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
Enables clang-tidy analysis. [`MP_UNITS_BUILD_IMPORT_STD`](#MP_UNITS_BUILD_IMPORT_STD){ #MP_UNITS_BUILD_IMPORT_STD }
[conan clang-tidy support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 : [:octicons-tag-24: 2.3.0][cmake import std support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
### CMake options Enables `import std;` usage.
[`MP_UNITS_BUILD_AS_SYSTEM_HEADERS`](#MP_UNITS_BUILD_AS_SYSTEM_HEADERS){ #MP_UNITS_BUILD_AS_SYSTEM_HEADERS } [cmake import std support]: https://github.com/mpusz/mp-units/releases/tag/v2.3.0
: [:octicons-tag-24: 2.2.0][cmake as system headers support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`) [`MP_UNITS_API_STD_FORMAT`](#MP_UNITS_API_STD_FORMAT){ #MP_UNITS_API_STD_FORMAT }
Exports library as system headers. : [:octicons-tag-24: 2.2.0][cmake std::format support] · :octicons-milestone-24: `ON`/`OFF` (Default: automatically determined)
[cmake as system headers support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 Enables the usage of [`std::format`](https://en.cppreference.com/w/cpp/utility/format/format)
and associated facilities for text formatting. If it is not supported, then
the [{fmt}](https://github.com/fmtlib/fmt) library is used instead.
[`MP_UNITS_BUILD_CXX_MODULES`](#MP_UNITS_BUILD_CXX_MODULES){ #MP_UNITS_BUILD_CXX_MODULES } [cmake std::format support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
: [:octicons-tag-24: 2.2.0][cmake build cxx modules support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`) [`MP_UNITS_API_STRING_VIEW_RET`](#MP_UNITS_API_STRING_VIEW_RET){ #MP_UNITS_API_STRING_VIEW_RET }
Adds C++ modules to the list of default targets. : [:octicons-tag-24: 2.2.0][cmake returning string_view] · :octicons-milestone-24: `ON`/`OFF` (Default: automatically determined)
[cmake build cxx modules support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 Enables returning `std::string_view` from the
[`unit_symbol()`](../users_guide/framework_basics/text_output.md#unit_symbol)
and [`dimension_symbol()`](../users_guide/framework_basics/text_output.md#dimension_symbol)
functions. If this feature is not available, those functions will return
`mp_units::basic_fixed_string<CharT, N>` instead.
[`MP_UNITS_BUILD_IMPORT_STD`](#MP_UNITS_BUILD_IMPORT_STD){ #MP_UNITS_BUILD_IMPORT_STD } [cmake returning string_view]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
: [:octicons-tag-24: 2.3.0][cmake import std support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`) [`MP_UNITS_API_NO_CRTP`](#MP_UNITS_API_NO_CRTP){ #MP_UNITS_API_NO_CRTP }
Enables `import std;` usage. : [:octicons-tag-24: 2.2.0][cmake no crtp support] · :octicons-milestone-24: `ON`/`OFF` (Default: automatically determined)
[cmake import std support]: https://github.com/mpusz/mp-units/releases/tag/v2.3.0 Removes the need for the usage of the CRTP idiom in the
[`quantity_spec` definitions](../users_guide/framework_basics/systems_of_quantities.md#defining-quantities).
[`MP_UNITS_API_STD_FORMAT`](#MP_UNITS_API_STD_FORMAT){ #MP_UNITS_API_STD_FORMAT } [cmake no crtp support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
: [:octicons-tag-24: 2.2.0][cmake std::format support] · :octicons-milestone-24: `ON`/`OFF` (Default: automatically determined) [`MP_UNITS_API_CONTRACTS`](#MP_UNITS_API_CONTRACTS){ #MP_UNITS_API_CONTRACTS }
Enables the usage of [`std::format`](https://en.cppreference.com/w/cpp/utility/format/format) : [:octicons-tag-24: 2.2.0][cmake contracts] · :octicons-milestone-24: `NONE`/`GSL-LITE`/`MS-GSL` (Default: `GSL-LITE`)
and associated facilities for text formatting. If it is not supported, then
the [{fmt}](https://github.com/fmtlib/fmt) library is used instead.
[cmake std::format support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 Enables checking of preconditions and additional asserts in the code.
[`MP_UNITS_API_STRING_VIEW_RET`](#MP_UNITS_API_STRING_VIEW_RET){ #MP_UNITS_API_STRING_VIEW_RET } [cmake contracts]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
: [:octicons-tag-24: 2.2.0][cmake returning string_view] · :octicons-milestone-24: `ON`/`OFF` (Default: automatically determined) [`MP_UNITS_API_FREESTANDING`](#MP_UNITS_API_FREESTANDING){ #MP_UNITS_API_FREESTANDING }
Enables returning `std::string_view` from the : [:octicons-tag-24: 2.2.0][cmake freestanding] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
[`unit_symbol()`](../users_guide/framework_basics/text_output.md#unit_symbol)
and [`dimension_symbol()`](../users_guide/framework_basics/text_output.md#dimension_symbol)
functions. If this feature is not available, those functions will return
`mp_units::basic_fixed_string<CharT, N>` instead.
[cmake returning string_view]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 Configures the library in the [freestanding](https://en.cppreference.com/w/cpp/freestanding)
mode. When enabled, the library's source code should build with the compiler's
[`-ffreestanding`](https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html) compilation option
without any issues.
[`MP_UNITS_API_NO_CRTP`](#MP_UNITS_API_NO_CRTP){ #MP_UNITS_API_NO_CRTP } [cmake freestanding]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
: [:octicons-tag-24: 2.2.0][cmake no crtp support] · :octicons-milestone-24: `ON`/`OFF` (Default: automatically determined)
Removes the need for the usage of the CRTP idiom in the
[`quantity_spec` definitions](../users_guide/framework_basics/systems_of_quantities.md#defining-quantities).
[cmake no crtp support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[`MP_UNITS_API_CONTRACTS`](#MP_UNITS_API_CONTRACTS){ #MP_UNITS_API_CONTRACTS }
: [:octicons-tag-24: 2.2.0][cmake contracts] · :octicons-milestone-24: `NONE`/`GSL-LITE`/`MS-GSL` (Default: `GSL-LITE`)
Enables checking of preconditions and additional asserts in the code.
[cmake contracts]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[`MP_UNITS_API_FREESTANDING`](#MP_UNITS_API_FREESTANDING){ #MP_UNITS_API_FREESTANDING }
: [:octicons-tag-24: 2.2.0][cmake freestanding] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
Configures the library in the [freestanding](https://en.cppreference.com/w/cpp/freestanding)
mode. When enabled, the library's source code should build with the compiler's
[`-ffreestanding`](https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html) compilation option
without any issues.
[cmake freestanding]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
#### Options for mp-units project developers
[`MP_UNITS_DEV_BUILD_LA`](#MP_UNITS_DEV_BUILD_LA){ #MP_UNITS_DEV_BUILD_LA }
: [:octicons-tag-24: 2.2.0][cmake build la support] · :octicons-milestone-24: `ON`/`OFF` (Default: `ON`)
Enables building code depending on the linear algebra library.
[cmake build la support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[`MP_UNITS_DEV_IWYU`](#MP_UNITS_DEV_IWYU){ #MP_UNITS_DEV_IWYU }
: [:octicons-tag-24: 2.2.0][cmake iwyu support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
Enables include-what-you-use analysis.
[cmake iwyu support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[`MP_UNITS_DEV_CLANG_TIDY`](#MP_UNITS_DEV_CLANG_TIDY){ #MP_UNITS_DEV_CLANG_TIDY }
: [:octicons-tag-24: 2.2.0][cmake clang-tidy support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
Enables clang-tidy analysis.
[cmake clang-tidy support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
## 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:
```shell
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 ## Installation and reuse
@ -461,42 +255,12 @@ only a few of many options possible.
The easiest and most recommended way to obtain **mp-units** is with the Conan package manager. The easiest and most recommended way to obtain **mp-units** is with the Conan package manager.
See [Conan + CMake (release)](#conan-cmake-release) for a detailed instruction. See [Conan + CMake (release)](#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**:
```cmake
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) ### Conan + CMake (release)
!!! tip !!! tip
If you are new to the Conan package manager, it is highly recommended to read If you are new to the Conan package manager you may want to read
[Obtaining Dependencies](#obtaining-dependencies) and refer to [Obtaining Dependencies](#obtaining-dependencies) and refer to the
[Consuming packages](https://docs.conan.io/2/tutorial/consuming_packages.html) [Consuming packages](https://docs.conan.io/2/tutorial/consuming_packages.html)
chapter of the official Conan documentation for more information. chapter of the official Conan documentation for more information.
@ -512,7 +276,6 @@ The following steps may be performed to obtain an official library release:
mp-units/2.2.0 mp-units/2.2.0
[options] [options]
mp-units:cxx_modules=True
[layout] [layout]
cmake_layout cmake_layout
@ -522,8 +285,7 @@ The following steps may be performed to obtain an official library release:
CMakeDeps CMakeDeps
``` ```
2. Import **mp-units** and its dependencies definitions to your project's build procedure 2. Import **mp-units** and its dependencies definitions with `find_package`:
with `find_package`:
```cmake ```cmake
find_package(mp-units REQUIRED) find_package(mp-units REQUIRED)
@ -552,7 +314,7 @@ of **mp-units** all the time.
Please note that even though the Conan packages that you will be using are generated **ONLY** 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 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 (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 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. changes might not be reflected in the project's documentation right away.
@ -572,7 +334,6 @@ with the following differences:
mp-units/2.3.0@mpusz/testing mp-units/2.3.0@mpusz/testing
[options] [options]
mp-units:cxx_modules=True
[layout] [layout]
cmake_layout cmake_layout
@ -594,91 +355,60 @@ with the following differences:
conan install . -pr <your_conan_profile> -s compiler.cppstd=20 -b=missing -u conan install . -pr <your_conan_profile> -s compiler.cppstd=20 -b=missing -u
``` ```
??? info "Alternative installation scenarios"
### Install ### Copy
In case you don't want to use Conan in your project and just want to install the **mp-units** As **mp-units** is a C++ header-only library you can simply copy all needed _src/*/include_ subdirectories
library on your file system and use `find_package(mp-units)` from another repository to find it; to your source tree.
it is enough to perform the following steps:
```shell !!! note
conan install . -pr <your_conan_profile> -s compiler.cppstd=20 -b=missing
mv CMakeUserPresets.json src In such a case, you are on your own to ensure all the dependencies are installed and their header
cd src files can be located during the build. Please also note that some compiler-specific flags are needed
cmake --preset conan-default -DCMAKE_INSTALL_PREFIX=<your_installation_path> to make the code compile without issues.
cmake --build --preset conan-release --target install
```
## Contributing (or just building all the tests and examples) ### Copy + CMake
In case you would like to build all the **mp-units** source code (with unit tests and examples), If you copy the **mp-units** library source code from **the project's _./src_ directory**
you should: (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**:
1. Use the _CMakeLists.txt_ from the top-level directory. ```cmake
2. Run Conan with [`user.mp-units.build:all`](#user.mp-units.build-all) = `True`. add_subdirectory(<path_to_mp_units_lib_folder>)
# ...
```shell target_link_libraries(<your_target> <PUBLIC|PRIVATE|INTERFACE> mp-units::mp-units)
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:
```shell
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](https://squidfunk.github.io/mkdocs-material/)
to build our documentation. The easiest way to install all the required dependencies
is with `pip`:
```shell
pip install -U mkdocs-material mkdocs-rss-plugin
```
Additionally, a [Cairo Graphics library](https://www.cairographics.org/) is required by
Material for MkDocs. Please follow the
[official MkDocs documentation to install it](https://squidfunk.github.io/mkdocs-material/plugins/requirements/image-processing/#cairo-graphics).
After that, you can either:
- easily [start a live server to preview the documentation as you write](https://squidfunk.github.io/mkdocs-material/creating-your-site/#previewing-as-you-write)
```shell
mkdocs serve
``` ```
- [build the documentation](https://squidfunk.github.io/mkdocs-material/creating-your-site/#building-your-site) !!! 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 "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()`](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).
### 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:
```shell ```shell
mkdocs build 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
``` ```
## Packaging
To test CMake installation and Conan packaging or create a Conan package run:
```shell
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
```shell
conan upload -r <remote-name> --all mp-units/2.2.0@<user>/<channel>
```

150
docs/getting_started/project_structure.md Normal file
View File

@ -0,0 +1,150 @@
# 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](https://github.com/mpusz/mp-units) 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](https://github.com/gsl-lite/gsl-lite) or [ms-gsl](https://github.com/microsoft/GSL)
to verify runtime contracts (if contract checking is enabled),
- [{fmt}](https://github.com/fmtlib/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](https://github.com/catchorg/Catch2) library as a unit tests framework,
- [linear algebra](https://github.com/BobSteagall/wg21/tree/master/include)
library based on proposal [P1385](https://wg21.link/P1385) used in some examples
and tests.
- **_./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:
```mermaid
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`.
## 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](../users_guide/use_cases/wide_compatibility.md).
??? 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.
### 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)](https://en.wikipedia.org/wiki/International_System_of_Quantities)
definitions,
??? 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)](https://en.wikipedia.org/wiki/International_System_of_Units)
definitions and associated math functions,
- `mp-units/systems/angular.h` provides strong angular units and associated math functions,
- `mp-units/systems/international.h` provides
[international yard and pound](https://en.wikipedia.org/wiki/International_yard_and_pound) units,
- `mp-units/systems/imperial.h` includes `international.h` and extends it with
[imperial units](https://en.wikipedia.org/wiki/Imperial_units),
- `mp-units/systems/usc.h` includes `international.h` and extends it with
[United States customary system of units](https://en.wikipedia.org/wiki/United_States_customary_units),
- `mp-units/systems/cgs.h` provides
[centimetre-gram-second system of units](https://en.wikipedia.org/wiki/Centimetre%E2%80%93gram%E2%80%93second_system_of_units),
- `mp-units/systems/iau.h` provides
[astronomical system of units](https://en.wikipedia.org/wiki/Astronomical_system_of_units),
- `mp-units/systems/hep.h` provides units used in
[high-energy physics](https://en.wikipedia.org/wiki/Particle_physics),
- `mp-units/systems/typographic.h` provides units used in
[typography or typesetting](https://en.wikipedia.org/wiki/Typographic_unit),
- `mp-units/systems/natural.h` provides an example implementation of
[natural units](https://en.wikipedia.org/wiki/Natural_units).
??? tip "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.

2
mkdocs.yml
View File

@ -130,8 +130,10 @@ nav:
- Introduction: getting_started/introduction.md - Introduction: getting_started/introduction.md
- Quick Start: getting_started/quick_start.md - Quick Start: getting_started/quick_start.md
- Look and Feel: getting_started/look_and_feel.md - Look and Feel: getting_started/look_and_feel.md
- Project Structure: getting_started/project_structure.md
- C++ compiler support (API/ABI): getting_started/cpp_compiler_support.md - C++ compiler support (API/ABI): getting_started/cpp_compiler_support.md
- Installation and Usage: getting_started/installation_and_usage.md - Installation and Usage: getting_started/installation_and_usage.md
- Contributing: getting_started/contributing.md
- FAQ: getting_started/faq.md - FAQ: getting_started/faq.md
- User's Guide: - User's Guide:
- Terms and Definitions: users_guide/terms_and_definitions.md - Terms and Definitions: users_guide/terms_and_definitions.md