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

docs: documentation updated for C++ modules

Browse Source
This commit is contained in:
Mateusz Pusz
2024-01-06 08:51:01 +01:00
parent e23be9aab5
commit edb7de4b11
2 changed files with 75 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
docs/getting_started/installation_and_usage.md
View File

@ -12,11 +12,34 @@
a [preprocessor macro](../users_guide/framework_basics/systems_of_quantities.md#defining-quantities)
providing a backward-compatible way to use it.
As of today, the library compiles fine on the following compilers (or newer):
The below table provides the minimum compiler version required to compile the code using the
specific feature:
- gcc-12
- clang-16
- apple-clang-15
| Feature | gcc | clang | apple-clang | MSVC |
|----------------------|:----:|:-----:|:-----------:|:----:|
| **Minimum support** | 12 | 16 | 15 | None |
| **`std::format`** | None | None | None | None |
| **C++ modules** | None | 17 | None | None |
| **C++23 extensions** | None | None | None | None |
More requirements for C++ modules support can be found in the
[CMake's documentation](https://cmake.org/cmake/help/latest/manual/cmake-cxxmodules.7.html).
## 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 |
| `mp_units.systems` | `mp-units::systems` | All the systems of quantities and units |
| `mp_units` | `mp-units::mp-units` | Core + Systems |
## Repository Structure and Dependencies
@ -60,10 +83,12 @@ This repository contains three independent CMake-based projects:
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.
- _./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-building-of-tests-and-examples).
@ -138,6 +163,16 @@ tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}
## Build Options
### Conan Options
[cxx_modules](#cxx_modules){ #cxx_modules }
: [:octicons-tag-24: 2.2.0][cxx modules support] · :octicons-milestone-24: `True`/`False` (Default: `False`)
Configures CMake to add C++ modules to the list of default targets.
[cxx modules support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
### Conan Configuration Properties
[`user.build:all`](#user-build-all){ #user-build-all }
@ -146,7 +181,8 @@ tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}
Enables compilation of all the source code, including tests and examples. To support this, it requires some additional Conan build dependencies described in
[Repository Structure and Dependencies](#repository-structure-and-dependencies).
It also runs unit tests during Conan build (unless `tools.build:skip_test`
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`).
[build all support]: https://github.com/mpusz/mp-units/releases/tag/v0.8.0
@ -166,6 +202,15 @@ tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}
### CMake Options
[`MP_UNITS_BUILD_CXX_MODULES`](#MP_UNITS_BUILD_CXX_MODULES){ #MP_UNITS_BUILD_CXX_MODULES }
: [:octicons-tag-24: 2.2.0][build_cxx_modules support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
Adds C++ modules to the list of default targets.
[build_cxx_modules support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[`MP_UNITS_AS_SYSTEM_HEADERS`](#MP_UNITS_AS_SYSTEM_HEADERS){ #MP_UNITS_AS_SYSTEM_HEADERS }
: [:octicons-tag-24: 2.0.0][as system headers support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
@ -175,15 +220,6 @@ tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}
[as system headers support]: https://github.com/mpusz/mp-units/releases/tag/v2.0.0
[`MP_UNITS_BUILD_CXX_MODULES`](#MP_UNITS_BUILD_CXX_MODULES){ #MP_UNITS_BUILD_CXX_MODULES }
: [:octicons-tag-24: 2.2.0][build_cxx_modules support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
Add C++ modules to the list of default targets.
[build_cxx_modules support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[`MP_UNITS_BUILD_LA`](#MP_UNITS_BUILD_LA){ #MP_UNITS_BUILD_LA }
: [:octicons-tag-24: 2.0.0][build la support] · :octicons-milestone-24: `ON`/`OFF` (Default: `ON`)
@ -208,7 +244,7 @@ tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}
: [:octicons-tag-24: 2.0.0][use libfmt support] · :octicons-milestone-24: `ON`/`OFF` (Default: `ON`)
Forces usage of [{fmt}](https://github.com/fmtlib/fmt) library instead of the C++20 Standard
Library feature.
Library features.
[use libfmt support]: https://github.com/mpusz/mp-units/releases/tag/v2.0.0
@ -293,6 +329,9 @@ The following steps may be performed to obtain an official library release:
[requires]
mp-units/2.1.0
[options]
mp-units:cxx_modules=True
[layout]
cmake_layout
@ -350,6 +389,9 @@ with the following differences:
[requires]
mp-units/2.2.0@mpusz/testing
[options]
mp-units:cxx_modules=True
[layout]
cmake_layout
@ -396,7 +438,7 @@ you should:
```shell
git clone https://github.com/mpusz/mp-units.git && cd units
conan build . -pr <your_conan_profile> -s compiler.cppstd=20 -c user.build:all=True -b missing
conan build . -pr <your_conan_profile> -s compiler.cppstd=23 -o cxx_modules=True -c user.build:all=True -b missing
```
The above will download and install all of the dependencies needed for the development of the library,
@ -442,7 +484,7 @@ After that, you can either:
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 -c user.build:all=True -b missing
conan create . --user <username> --channel <channel> -pr <your_conan_profile> -s compiler.cppstd=20 -o cxx_modules=True -c user.build:all=True -b missing
```
The above will create a Conan package and run tests provided in _./test_package_ directory.

16
docs/index.md
View File

@ -25,11 +25,19 @@ The library source code is hosted on [GitHub](https://github.com/mpusz/mp-units)
a [preprocessor macro](users_guide/framework_basics/systems_of_quantities.md#defining-quantities)
providing a backward-compatible way to use it.
As of today, the library compiles fine on the following compilers (or newer):
The below table provides the minimum compiler version required to compile the code using the
specific feature:
| Feature | gcc | clang | apple-clang | MSVC |
|----------------------|:----:|:-----:|:-----------:|:----:|
| **Minimum support** | 12 | 16 | 15 | None |
| **`std::format`** | None | None | None | None |
| **C++ modules** | None | 17 | None | None |
| **C++23 extensions** | None | None | None | None |
More requirements for C++ modules support can be found in the
[CMake's documentation](https://cmake.org/cmake/help/latest/manual/cmake-cxxmodules.7.html).
- gcc-12
- clang-16
- apple-clang-15
```cpp
#include <mp-units/ostream.h>