From a5b2b793e4fe447e3cca9a380bbea97e75e18a06 Mon Sep 17 00:00:00 2001 From: Mateusz Pusz Date: Thu, 25 Apr 2024 16:23:59 +0200 Subject: [PATCH] docs: "Project structure" chapter expanded --- .../getting_started/installation_and_usage.md | 87 +++++++++++++++++-- 1 file changed, 81 insertions(+), 6 deletions(-) diff --git a/docs/getting_started/installation_and_usage.md b/docs/getting_started/installation_and_usage.md index 8ecd0e5f..8d2d1f48 100644 --- a/docs/getting_started/installation_and_usage.md +++ b/docs/getting_started/installation_and_usage.md @@ -4,9 +4,12 @@ This chapter provides all the necessary information to obtain and build the code It also describes how to build or distribute the library and generate its documentation. -## Repository structure and dependencies +## Project structure -This repository contains three independent CMake-based projects: +### Repository directory tree and dependencies + +The [GitHub repository](https://github.com/mpusz/mp-units) contains three independent CMake-based +projects: - **_./src_** @@ -55,8 +58,7 @@ This repository contains three independent CMake-based projects: 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). - -## Modules +### Modules The **mp-units** library provides the following C++ modules: @@ -73,8 +75,81 @@ flowchart TD !!! note - C++ modules are provided within the package only when [`cxx_modules`](#cxx_modules) Conan - option is set to `True`. + 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