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

feat: 💥 API-related Conan, CMake, and preprocessor options redesigned

Browse Source
This commit is contained in:
Mateusz Pusz
2024-04-16 21:48:36 +01:00
parent 7b57ce5ab1
commit 8e0a26b933
26 changed files with 490 additions and 207 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
docs/getting_started/cpp_compiler_support.md Normal file
View File

@@ -0,0 +1,90 @@
# C++ compiler support (API/ABI) { #cpp-compiler-support }
!!! info
**mp-units** library tries to provide the best user experience possible with the C++ language.
To achieve that, it extensively uses the latest C++ language features.
Even though the library benefits from the latest C++ versions (if available), C++20 is enough
to compile and use all of the library's functionality. Newer features can be hidden behind
some [preprocessor macros](../users_guide/use_cases/wide_compatibility.md#compatibility-macros)
providing a backward-compatible way to use them.
The table below provides the minimum compiler version required to compile the code using a specific
C++ feature:
| C++ Feature | C++ version | gcc | clang | apple-clang | MSVC |
|-----------------------------------------------------------|:-----------:|:---:|:-----:|:-----------:|:----:|
| **Minimum support** | 20 | 12 | 16 | 15 | None |
| **`std::format`** | 20 | 13 | 17 | None | None |
| **C++ modules** | 20 | 14 | 17 | None | None |
| **Static `constexpr` variables in `constexpr` functions** | 23 | 13 | 17 | None | None |
| **Explicit `this` parameter** | 23 | 14 | 18 | None | None |
!!! important
Enabling/disabling features listed above may influence the API of the library and the ABI of
the customers' projects.
## `std::format`
- Provides [powerful text formatting capabilities](../users_guide/framework_basics/text_output.md#stdformat)
for C++.
- An alternative [fmtlib](https://github.com/fmtlib/fmt) library can be used instead if
- the C++ language feature is not supported,
- the customer's project did not switch to `std::format` yet (even when the compiler
supports it).
- To write code with wide compatibility
a [dedicated macro may be used](../users_guide/use_cases/wide_compatibility.md#mp_units_std_fmt).
- Tested with `__cpp_lib_format` [feature test macro](https://en.cppreference.com/w/cpp/feature_test).
- Related build options:
- Conan: [std_format](installation_and_usage.md#std_format)
- CMake: [MP_UNITS_API_STD_FORMAT](installation_and_usage.md#MP_UNITS_API_STD_FORMAT)
## C++ modules
- Provide new way to share declarations and definitions across translation units.
- If used, the library will distribute both "old-style" headers and module interface units
- associated with the same CMake targets.
- Even with full compiler support, a user may still decide to not pay for C++ modules compilation
if they are not needed by the customer's project.
- Feature test macro is not used for testing here because even if the compiler does not support
the entire C++ feature (e.g. header units), it is enough to build modules for this library.
- Related build options:
- Conan: [cxx_modules](installation_and_usage.md#cxx_modules)
- CMake: [MP_UNITS_BUILD_CXX_MODULES](installation_and_usage.md#MP_UNITS_BUILD_CXX_MODULES)
!!! note
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).
## Static `constexpr` variables in `constexpr` functions
- Allows 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
- `std::string_view` type has a reference semantics so it has to point to a storage with
a longer lifetime.
- If this feature is not available, the API returns `mp_units::basic_fixed_string<CharT, N>` instead.
- Tested as `__cpp_constexpr >= 202211L` [feature test macro](https://en.cppreference.com/w/cpp/feature_test).
- Related build options:
- Conan: [string_view_ret](installation_and_usage.md#string_view_ret)
- CMake: [MP_UNITS_API_STRING_VIEW_RET](installation_and_usage.md#MP_UNITS_API_STRING_VIEW_RET)
## Explicit `this` parameter
- This feature 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).
- To write code with wide compatibility
a [dedicated macro may be used](../users_guide/use_cases/wide_compatibility.md#QUANTITY_SPEC).
- Tested with `__cpp_explicit_this_parameter` [feature test macro](https://en.cppreference.com/w/cpp/feature_test).
- Related build options:
- Conan: [no_crtp](installation_and_usage.md#no_crtp)
- CMake: [MP_UNITS_API_NO_CRTP](installation_and_usage.md#MP_UNITS_API_NO_CRTP)
*[CRTP]: Curiously Recurring Template Parameter

159
docs/getting_started/installation_and_usage.md
View File

@@ -3,60 +3,12 @@
This chapter provides all the necessary information to obtain and build the code using **mp-units**.
It also describes how to build or distribute the library and generate its documentation.
## C++ compiler support { #cpp-compiler-support }
!!! info
**mp-units** library tries to provide the best user experience possible with the C++ language.
To achieve that, it extensively uses C++20 features and the
[explicit object parameter](https://en.cppreference.com/w/cpp/language/member_functions#Explicit_object_parameter)
from C++23.
Even though the library benefits from C++23 (if available), C++20 is enough to compile and
use all of the library's functionality. C++23 features are hidden behind
a [preprocessor macro](../users_guide/framework_basics/systems_of_quantities.md#defining-quantities)
providing a backward-compatible way to use it.
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`** | 13 | 17 | None | None |
| **C++ modules** | 14 | 17 | None | None |
| **C++23 extensions** | 14 | 18 | 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 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`.
## Repository structure and dependencies
This repository contains three independent CMake-based projects:
- _./src_
- **_./src_**
- header-only project containing whole **mp-units** library
- _./src/CMakeList.txt_ file is intended as an **entry point for library users**
@@ -68,7 +20,7 @@ This repository contains three independent CMake-based projects:
- [{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
@@ -79,7 +31,7 @@ This repository contains three independent CMake-based projects:
library based on proposal [P1385](https://wg21.link/P1385) used in some examples
and tests.
- *./test_package*
- **_./test_package_**
- CMake library installation and Conan package verification.
@@ -104,6 +56,27 @@ This repository contains three independent CMake-based projects:
[FAQ](faq.md#why-dont-we-have-cmake-options-to-disable-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`.
## Obtaining dependencies
This library assumes that most of the dependencies will be provided by the
@@ -118,7 +91,7 @@ The rest of the dependencies responsible for documentation generation are provid
In case you are not familiar with Conan, to install it (or upgrade) just do:
```shell
pip3 install -U conan
pip install -U conan
```
After that, you might need to add a custom profile file for your development environment
@@ -173,30 +146,59 @@ tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}
## 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](cpp_compiler_support.md) chapter to learn more
about which C++ features are required and which compiler support them.
### Conan options
[cxx_modules](#cxx_modules){ #cxx_modules }
: [:octicons-tag-24: 2.2.0][cxx modules support] · :octicons-milestone-24: `True`/`False` (Default: `False`)
: [:octicons-tag-24: 2.2.0][conan C++ modules support] · :octicons-milestone-24: `auto`/`True`/`False` (Default: `auto`)
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 C++ modules support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[use_fmtlib](#use_fmtlib){ #use_fmtlib }
[std_format](#std_format){ #std_format }
: [:octicons-tag-24: 2.2.0][use fmtlib support] · :octicons-milestone-24: `True`/`False` (Default: `False`)
: [:octicons-tag-24: 2.2.0][conan std::format support] · :octicons-milestone-24: `auto`/`True`/`False` (Default: `auto`)
Forces usage of [{fmt}](https://github.com/fmtlib/fmt) library instead of the C++20 Standard
Library features.
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.
[conan std::format support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[string_view_ret](#string_view_ret){ #string_view_ret }
: [:octicons-tag-24: 2.2.0][conan returning string_view] · :octicons-milestone-24: `auto`/`True`/`False` (Default: `auto`)
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.
[conan returning string_view]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[no_crtp](#no_crtp){ #no_crtp }
: [:octicons-tag-24: 2.2.0][conan no crtp support] · :octicons-milestone-24: `auto`/`True`/`False` (Default: `auto`)
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).
[conan no crtp support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[use fmtlib support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
### Conan configuration properties
[`user.mp-units.build:all`](#user.mp-units.build-all){ #user.mp-units.build-all }
: [:octicons-tag-24: 2.2.0][build all support] · :octicons-milestone-24: `True`/`False` (Default: `False`)
: [:octicons-tag-24: 2.2.0][conan build all support] · :octicons-milestone-24: `True`/`False` (Default: `False`)
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).
@@ -204,19 +206,19 @@ tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}
[`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/v2.2.0
[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 }
: [:octicons-tag-24: 2.2.0][skip la support] · :octicons-milestone-24: `True`/`False` (Default: `False`)
: [:octicons-tag-24: 2.2.0][conan skip la support] · :octicons-milestone-24: `True`/`False` (Default: `False`)
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.
[skip la support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[conan skip la support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
### CMake options
@@ -229,16 +231,37 @@ tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"}
[build_cxx_modules support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[`MP_UNITS_API_STD_FORMAT`](#MP_UNITS_API_STD_FORMAT){ #MP_UNITS_API_STD_FORMAT }
[`MP_UNITS_USE_FMTLIB`](#MP_UNITS_USE_FMTLIB){ #MP_UNITS_USE_FMTLIB }
: [:octicons-tag-24: 2.2.0][use fmtlib support] · :octicons-milestone-24: `AUTO`/`ON`/`OFF` (Default: `AUTO`)
: [:octicons-tag-24: 2.2.0][use fmtlib support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
Forces usage of [{fmt}](https://github.com/fmtlib/fmt) library instead of the C++20 Standard
Library features.
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.
[use fmtlib support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[`MP_UNITS_API_STRING_VIEW_RET`](#MP_UNITS_API_STRING_VIEW_RET){ #MP_UNITS_API_STRING_VIEW_RET }
: [:octicons-tag-24: 2.2.0][cmake returning string_view] · :octicons-milestone-24: `AUTO`/`ON`/`OFF` (Default: `AUTO`)
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.
[cmake returning string_view]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
[`MP_UNITS_API_NO_CRTP`](#MP_UNITS_API_NO_CRTP){ #MP_UNITS_API_NO_CRTP }
: [:octicons-tag-24: 2.2.0][cmake no crtp support] · :octicons-milestone-24: `AUTO`/`ON`/`OFF` (Default: `AUTO`)
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
#### Options for mp-units project developers
[`MP_UNITS_DEV_BUILD_LA`](#MP_UNITS_DEV_BUILD_LA){ #MP_UNITS_DEV_BUILD_LA }

24
docs/index.md
View File

@@ -16,27 +16,13 @@ The library source code is hosted on [GitHub](https://github.com/mpusz/mp-units)
??? info "Supported compilers"
This library tries to provide the best user experience possible with the C++ language.
To achieve that, it extensively uses C++20 features and the
[explicit object parameter](https://en.cppreference.com/w/cpp/language/member_functions#Explicit_object_parameter)
from C++23.
To achieve that, it extensively uses the latest C++ language features.
Even though the library benefits from C++23 (if available), C++20 is enough to compile and
use all of the library's functionality. C++23 features are hidden behind
a [preprocessor macro](users_guide/framework_basics/systems_of_quantities.md#defining-quantities)
providing a backward-compatible way to use it.
Even though the library benefits from the latest C++ versions (if available), C++20 is enough
to compile and use all of the library's functionality.
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`** | 13 | 17 | None | None |
| **C++ modules** | 14 | 17 | None | None |
| **C++23 extensions** | 14 | 18 | 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).
Please refer to [C++ compiler support chapter](getting_started/cpp_compiler_support.md)
for more details.
=== "C++ modules"

2
docs/users_guide/examples/tags_index.md
View File

@@ -3,7 +3,7 @@
!!! note
**mp-units** usage example applications are meant to be built on all of
[the supported compilers](../../getting_started/installation_and_usage.md#cpp-compiler-support).
[the supported compilers](../../getting_started/cpp_compiler_support.md).
This is why they benefit from the [Wide Compatibility](../use_cases/wide_compatibility.md) mode.
!!! tip

7
docs/users_guide/framework_basics/systems_of_quantities.md
View File

@@ -132,10 +132,15 @@ from such an instantiation.
Quantity specification definitions benefit from an
[explicit object parameter](https://en.cppreference.com/w/cpp/language/member_functions#Explicit_object_parameter)
added in C++23 to remove the need for CRTP idiom, which significantly simplifies the code.
However, as C++23 is far from being mainstream today, a portability macro `QUANTITY_SPEC()`
However, as C++23 is far from being mainstream today,
a [portability macro `QUANTITY_SPEC()`](../use_cases/wide_compatibility.md#QUANTITY_SPEC)
is provided and used consistently through the library to allow the code to compile with C++20
compilers, thanks to the CRTP usage under the hood.
See more in the
[C++ compiler support](../../getting_started/cpp_compiler_support.md#explicit-this-parameter)
chapter.
*[CRTP]: Curiously Recurring Template Parameter
For example, here is how the above quantity kind tree can be modeled in the library:

4
docs/users_guide/use_cases/wide_compatibility.md
View File

@@ -11,7 +11,7 @@ macros that can be used to ensure the wide compatibility of our code.
!!! note
Those macros are used in our short [example applications](../examples/tags_index.md) as those are meant
to be built on all of [the supported compilers](../../getting_started/installation_and_usage.md#cpp-compiler-support).
to be built on all of [the supported compilers](../../getting_started/cpp_compiler_support.md).
Some still do not support `std::format`, C++ modules, or C++ versions newer than C++20.
@@ -155,5 +155,5 @@ use [fmtlib](https://github.com/fmtlib/fmt) as their primary formatting facility
from additional features provided with the library).
This macro resolves to either the `std` or `fmt` namespace, depending on the value of
[MP_UNITS_USE_FMTLIB](../../getting_started/installation_and_usage.md#MP_UNITS_USE_FMTLIB)
[MP_UNITS_API_STD_FORMAT](../../getting_started/installation_and_usage.md#MP_UNITS_API_STD_FORMAT)
CMake option.