mirror of
https://github.com/mpusz/mp-units.git
synced 2025-07-31 02:47:16 +02:00
docs: documentation updated for C++ modules
This commit is contained in:
@ -12,11 +12,34 @@
|
|||||||
a [preprocessor macro](../users_guide/framework_basics/systems_of_quantities.md#defining-quantities)
|
a [preprocessor macro](../users_guide/framework_basics/systems_of_quantities.md#defining-quantities)
|
||||||
providing a backward-compatible way to use it.
|
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
|
| Feature | gcc | clang | apple-clang | MSVC |
|
||||||
- clang-16
|
|----------------------|:----:|:-----:|:-----------:|:----:|
|
||||||
- apple-clang-15
|
| **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
|
## 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:
|
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
|
- _./CMakeLists.txt_ is **to be used by projects developers** to build **ALL** the project code
|
||||||
restrictive compilation flags,
|
with really restrictive compilation flags,
|
||||||
- _./src/CMakeLists.txt_ contains only a pure library definition and should be used by the customers
|
- _./src/CMakeLists.txt_ contains only a pure library definition and **should be used by the
|
||||||
that prefer to use CMake's `add_subdirectory()` to handle the dependencies.
|
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
|
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).
|
[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
|
## 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
|
### Conan Configuration Properties
|
||||||
|
|
||||||
[`user.build:all`](#user-build-all){ #user-build-all }
|
[`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
|
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).
|
[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`).
|
configuration property is set to `True`).
|
||||||
|
|
||||||
[build all support]: https://github.com/mpusz/mp-units/releases/tag/v0.8.0
|
[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
|
### 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 }
|
[`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`)
|
: [: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
|
[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 }
|
[`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`)
|
: [: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`)
|
: [: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
|
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
|
[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]
|
[requires]
|
||||||
mp-units/2.1.0
|
mp-units/2.1.0
|
||||||
|
|
||||||
|
[options]
|
||||||
|
mp-units:cxx_modules=True
|
||||||
|
|
||||||
[layout]
|
[layout]
|
||||||
cmake_layout
|
cmake_layout
|
||||||
|
|
||||||
@ -350,6 +389,9 @@ with the following differences:
|
|||||||
[requires]
|
[requires]
|
||||||
mp-units/2.2.0@mpusz/testing
|
mp-units/2.2.0@mpusz/testing
|
||||||
|
|
||||||
|
[options]
|
||||||
|
mp-units:cxx_modules=True
|
||||||
|
|
||||||
[layout]
|
[layout]
|
||||||
cmake_layout
|
cmake_layout
|
||||||
|
|
||||||
@ -396,7 +438,7 @@ you should:
|
|||||||
|
|
||||||
```shell
|
```shell
|
||||||
git clone https://github.com/mpusz/mp-units.git && cd units
|
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,
|
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:
|
To test CMake installation and Conan packaging or create a Conan package run:
|
||||||
|
|
||||||
```shell
|
```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.
|
The above will create a Conan package and run tests provided in _./test_package_ directory.
|
||||||
|
@ -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)
|
a [preprocessor macro](users_guide/framework_basics/systems_of_quantities.md#defining-quantities)
|
||||||
providing a backward-compatible way to use it.
|
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
|
```cpp
|
||||||
#include <mp-units/ostream.h>
|
#include <mp-units/ostream.h>
|
||||||
|
Reference in New Issue
Block a user