From edb7de4b116cd97a3e364da1795cbd6e5b6410d1 Mon Sep 17 00:00:00 2001 From: Mateusz Pusz Date: Sat, 6 Jan 2024 08:51:01 +0100 Subject: [PATCH] docs: documentation updated for C++ modules --- .../getting_started/installation_and_usage.md | 84 ++++++++++++++----- docs/index.md | 16 +++- 2 files changed, 75 insertions(+), 25 deletions(-) diff --git a/docs/getting_started/installation_and_usage.md b/docs/getting_started/installation_and_usage.md index 5ed8ce5c..6e361609 100644 --- a/docs/getting_started/installation_and_usage.md +++ b/docs/getting_started/installation_and_usage.md @@ -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 -s compiler.cppstd=20 -c user.build:all=True -b missing +conan build . -pr -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 --channel -pr -s compiler.cppstd=20 -c user.build:all=True -b missing +conan create . --user --channel -pr -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. diff --git a/docs/index.md b/docs/index.md index e814e40a..0150746e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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