diff --git a/.cmake-format.yaml b/.cmake-format.yaml index b1465f47..600658bd 100644 --- a/.cmake-format.yaml +++ b/.cmake-format.yaml @@ -1,3 +1,4 @@ +include: ["cmake/.cmake-format-additional_commands-jegp.cmake_modules.yaml"] parse: additional_commands: add_mp_units_module: diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 2c86f575..9c1d49fc 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -46,14 +46,36 @@ jobs: path: .cache restore-keys: | mkdocs-material- - - name: Installing pip packages - run: | - pip install conan mkdocs-material mkdocs-rss-plugin mkdocs-material[imaging] mike - name: Prepare git run: | git config --global user.name github-actions git config --global user.email github-actions@github.com git fetch origin gh-pages --depth=1 + - name: Installing API reference dependencies + run: | + sudo apt install haskell-stack graphviz nodejs npm ghc cabal-install + npm install split mathjax-full mathjax-node-sre + cabal update + - name: Installing MathJax-Node-CLI + run: | + git clone https://github.com/mathjax/mathjax-node-cli --depth=1 + echo "${{ github.workspace }}/mathjax-node-cli/bin" >> $GITHUB_PATH + - name: Get git repos with API reference tools + run: | + git clone https://github.com/JohelEGP/jegp.cmake_modules.git --depth=1 + git clone https://github.com/JohelEGP/draft.git --branch=standardese_sources_base --depth=1 + git clone https://github.com/JohelEGP/cxxdraft-htmlgen.git --branch=standardese_sources_base --depth=1 + - name: Generate API reference + run: | + cmake -S docs/api_reference/src -B build \ + -DCMAKE_MODULE_PATH="${{ github.workspace }}/jegp.cmake_modules/modules" \ + -DJEGP_STANDARDESE_SOURCES_GIT_REPOSITORY="${{ github.workspace }}/draft" \ + -DJEGP_CXXDRAFT_HTMLGEN_GIT_REPOSITORY="${{ github.workspace }}/cxxdraft-htmlgen" + cmake --build build + mv build/mp-units.html docs/api_reference/gen + - name: Installing pip dependencies + run: | + pip install conan mkdocs-material mkdocs-rss-plugin mkdocs-material[imaging] mkdocs-exclude mike - name: Building docs run: | mike deploy --push --update-aliases `conan inspect . | sed -n -r 's/version: ([0-9]+.[0-9]+).[0-9]+/\1/p'` latest diff --git a/.gitignore b/.gitignore index a4547914..d0a116be 100644 --- a/.gitignore +++ b/.gitignore @@ -46,3 +46,7 @@ CMakeUserPresets.json # Conan *.pyc /test_package/build/ + +# cxxdraft-htmlgen +docs/api_reference/src/source/ +docs/api_reference/gen/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index fcfc2f8e..38ce4932 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -36,3 +36,5 @@ repos: rev: 5.0.4 hooks: - id: flake8 + +exclude: ^docs/javascripts/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 34e78cdf..fe1708c2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,93 +1,289 @@ -# Contributing to `mp-units` +# Contributing 馃憤馃帀 First off, thanks for taking the time to contribute! 馃帀馃憤 -## Gitpod -The easiest way to start coding is to jump straight into [Gitpod](https://www.gitpod.io). You can either click the button -below or prefix any `mp-units` URL (main branch, other branches, issues, PRs, ...) in your web browser with `gitpod.io/#` -(e.g., ). - -[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/mpusz/mp-units) - -The above environment provides you with: - -- all supported compilers for Linux development and the latest version of build tools like `cmake` and `conan` -- all Conan dependencies preinstalled on the machine -- all documentation generation tools ready to use -- completed prebuilds for all targets (Debug and Release builds for each compiler) -- VSCode preconfigured to benefit from all the above - -## Download, Build, Install - -Alternatively, please refer to our official docs for -[download, build, and install instructions](https://mpusz.github.io/mp-units/latest/getting_started/installation_and_usage) -if you want to setup a development environment on your local machine. - -## Before Committing git Changes - -There are a few steps recommended to check before committing and pushing your changes to the git repository. - -### Naming Conventions - -Here are the main rules for naming things in this repo: - -- types, functions, variables naming in a `standard_case` -- template parameters in a `PascalCase` -- C++20 concepts names for now in a `PascalCase` but we plan to change it (see - for more details) - -### Unified Code Formatting - -There is a formatting standard enforced with the `pre-commit` script. Before committing your changes please do the following: - -```bash -pip3 install -U pre-commit -pre-commit run --all-files -``` - -This will run `clang-format` for code formatting with the `.clang-format` file provided in the repo, `cmake-format` to format -the CMake files, and some other check as well. -The script will run on all the files in the repo and will apply the changes in-place when needed. -After the script is done please make sure to stage all those changes to git commit. - -### Build All CMake Targets And Run Unit Tests - -The simplest way to verify if all targets build correctly and all unit tests pass is to run: - -```bash -conan build . -pr -s compiler.cppstd=23 -o cxx_modules=True -c user.mp-units.build:all=True -b missing -``` - -as described in the -[Installation and Usage](https://mpusz.github.io/mp-units/latest/getting_started/installation_and_usage/#contributing-or-just-building-all-the-tests-and-examples) -chapter of our documentation. - -_Hint:_ To ensure that that we always build all the targets and to save some typing of the Conan commands, -it is a good practice to set the following in the `~/.conan2/global.conf`: - -```text -user.mp-units.build:all=True -``` - -Non-Conan users should: -- build `all` and `all_verify_interface_header_sets` CMake targets, -- run all unit tests. - -### Backward Compatibility - -Before submission, please remember to check if the code compiles fine on the supported compilers. -The CI will check it anyway but it is good to check at least some of the configurations before pushing changes. -Especially older compilers can be tricky as those do not support all the C++20 features well enough. The official -list of supported compilers can be always found in the -[Installation And Usage](https://mpusz.github.io/mp-units/latest/getting_started/cpp_compiler_support) -chapter of our documentation. - - -## Where To Start? +## Where to start? If you are looking for a good issue to start with, please check the following: -- [good first issue](https://github.com/mpusz/mp-units/labels/good%20first%20issue) - issues that should be pretty simple to implement. -- [help wanted](https://github.com/mpusz/mp-units/labels/help%20wanted) - issues that typically are a bit more involved than beginner issues. -- [high priority](https://github.com/mpusz/mp-units/labels/high%20priority) - things to fix ASAP but often of higher complexity. +- [good first issue](https://github.com/mpusz/mp-units/labels/good%20first%20issue) - issues that + should be pretty simple to implement, +- [help wanted](https://github.com/mpusz/mp-units/labels/help%20wanted) - issues that typically are + a bit more involved than beginner issues, +- [high priority](https://github.com/mpusz/mp-units/labels/high%20priority) - things to fix ASAP + but often of higher complexity. + + +## Gitpod + +The easiest way to start coding is to jump straight into [Gitpod](https://www.gitpod.io) +environment. You can either click the button below + +[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/mpusz/mp-units) + +or prefix any `mp-units` URL (main branch, other branches, issues, PRs, ...) in your web browser +with `gitpod.io/#` (e.g., ). + +The above environment provides you with: + +- all supported compilers for Linux development and the latest version of build tools like `cmake` + and `conan`, +- all Conan dependencies preinstalled on the machine, +- all documentation generation tools ready to use, +- completed prebuilds for all targets (Debug and Release builds for each compiler), +- VSCode preconfigured to benefit from all the above. + + +## Building, testing, and packaging + +Alternatively, please refer to our official docs for +[download, build, and install instructions](https://mpusz.github.io/mp-units/latest/getting_started/installation_and_usage) with the below changes +if you want to set up a development environment on your local machine. + + +### Conan configuration properties + +[`user.mp-units.build:all`](#user.mp-units.build-all){ #user.mp-units.build-all } + + Enables compilation of all the source code, including tests and examples. To support this, it requires some additional Conan build dependencies described in + [Repository directory tree and dependencies](https://mpusz.github.io/mp-units/latest/getting_started/project_structure#cmake-projects-and-dependencies). + It also runs unit tests during the 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`). + + [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 } + + 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. + + [conan skip la support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 + +[`user.mp-units.analyze:clang-tidy`](#user.mp-units.analyze-clang-tidy){ #user.mp-units.analyze-clang-tidy } + + Enables clang-tidy analysis. + + [conan clang-tidy support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 + + +### CMake options for mp-units project developers + +[`MP_UNITS_DEV_BUILD_LA`](#MP_UNITS_DEV_BUILD_LA){ #MP_UNITS_DEV_BUILD_LA } + +: 聽 [:octicons-tag-24: 2.2.0][cmake build la support] 路 :octicons-milestone-24: `ON`/`OFF` (Default: `ON`) + + Enables building code depending on the linear algebra library. + + [cmake build la support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 + +[`MP_UNITS_DEV_IWYU`](#MP_UNITS_DEV_IWYU){ #MP_UNITS_DEV_IWYU } + +: 聽 [:octicons-tag-24: 2.2.0][cmake iwyu support] 路 :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`) + + Enables include-what-you-use analysis. + + [cmake iwyu support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 + +[`MP_UNITS_DEV_CLANG_TIDY`](#MP_UNITS_DEV_CLANG_TIDY){ #MP_UNITS_DEV_CLANG_TIDY } + +: 聽 [:octicons-tag-24: 2.2.0][cmake clang-tidy support] 路 :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`) + + Enables clang-tidy analysis. + + [cmake clang-tidy support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 + + +### Building the entire repository + +To build all the **mp-units** source code (with unit tests and examples), you should: + +1. Use the _CMakeLists.txt_ from the top-level directory. +2. Run Conan with [`user.mp-units.build:all`](#user.mp-units.build-all) = `True`. + +```shell +git clone https://github.com/mpusz/mp-units.git && cd units +conan build . -pr -s compiler.cppstd=23 -c user.mp-units.build:all=True -b missing +``` + +The above will download and install all of the dependencies needed for the development of the library, +build all of the source code, and run unit tests. + +If you prefer to build the project via CMake rather than Conan, then you should replace +the `conan build` with `conan install` command and then follow with a regular CMake build and testing: + +```shell +conan install . -pr -s compiler.cppstd=23 -c user.mp-units.build:all=True -b missing +cmake --preset conan-default +cmake --build --preset conan-release +cmake --build --preset conan-release --target all_verify_interface_header_sets +cmake --build --preset conan-release --target test +``` + +!!! hint + + To ensure that we always build all the targets and to save some typing of the Conan commands, + we can set the following in the `~/.conan2/global.conf`: + + ```text + user.mp-units.build:all=True + ``` + +### Packaging + +To test CMake installation and Conan packaging run: + +```shell +conan create . --user --channel -pr -s compiler.cppstd=23 \ + -c user.mp-units.build:all=True -b missing +``` + +The above will create a Conan package and run tests provided in _./test_package_ directory. + +In case you would like to upload **mp-units** package to the Conan server, do the following: + +```shell +conan upload -r --all mp-units/2.2.0@/ +``` + + +## Building documentation + +We are building our documentation using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). +The easiest way to install all the required dependencies is with `pip`: + +```shell +pip install -U mkdocs-material mkdocs-rss-plugin +``` + +Additionally, a [Cairo Graphics library](https://www.cairographics.org/) is required by +Material for MkDocs. Please follow the +[official MkDocs documentation to install it](https://squidfunk.github.io/mkdocs-material/plugins/requirements/image-processing/#cairo-graphics). + +After that, you can either: + +- easily [start a live server to preview the documentation as you write](https://squidfunk.github.io/mkdocs-material/creating-your-site/#previewing-as-you-write) + +```shell +mkdocs serve +``` + +- [build the documentation](https://squidfunk.github.io/mkdocs-material/creating-your-site/#building-your-site) + +```shell +mkdocs build +``` + +### Generating API reference + +We need to take a few steps to set up our environment so that we are ready to generate API reference +documents. + +First, we need to satisfy the requirements described in . +On the Ubuntu platform, this is equivalent to the following instructions run from the user's home +directory: + +```bash +sudo apt install haskell-stack graphviz nodejs npm ghc cabal-install +npm install split mathjax-full mathjax-node-sre +cabal update +``` + +Also, installing `mathjax-node-cli` through npm does not help because `tex2html` is not called within +node.js. This is why we need to download `mathjax-node-cli` and add its `bin` folder to the `PATH` +environment variable: + +```bash +git clone https://github.com/mathjax/mathjax-node-cli +echo "export PATH=\"$PWD/mathjax-node-cli/bin:\$PATH\"" >> ~/.bashrc && source ~/.bashrc +``` + +Next, we need to clone the following git repositories: + +- +- `standardese_sources_base` branch of +- `standardese_sources_base` branch of + +For example: + +```bash +git clone https://github.com/JohelEGP/jegp.cmake_modules.git --depth=1 +git clone https://github.com/JohelEGP/draft.git --branch=standardese_sources_base --depth=1 +git clone https://github.com/JohelEGP/cxxdraft-htmlgen.git --branch=standardese_sources_base --depth=1 +``` + +Now, we are ready to start building our API reference. First, we need to configure CMake with the +following: + +```bash +cmake -S docs/api_reference/src -B build/docs/api_reference \ + -DCMAKE_MODULE_PATH="/modules" \ +聽 聽 聽 -DJEGP_STANDARDESE_SOURCES_GIT_REPOSITORY="" \ + -DJEGP_CXXDRAFT_HTMLGEN_GIT_REPOSITORY="" +``` + +Then we need to build the docs with CMake: + +```bash +cmake --build build/docs/api_reference +``` + +In the end, we need to move the generated documentation to the `docs/api_reference/gen` subdirectory: + +```bash +mv build/docs/api_reference/mp-units.html docs/api_reference/gen +``` + +or just link the entire directory: + +```bash +ln -sf ../../build/docs/api_reference/mp-units.html docs/api_reference/gen +``` + + +## Before committing git changes + +There are a few steps recommended to check before committing and pushing your changes to the git +repository. + + +### Naming conventions + +Here are the main rules for naming things in this repo: + +- types, functions, variables use `standard_case`, +- template parameters use `PascalCase`, +- C++ concept names, for now, use `PascalCase`, but we plan to change it + (see [GitHub Issue #93](https://github.com/mpusz/mp-units/issues/93) for more details). + +### Unified code formatting + +A formatting standard is enforced with the `pre-commit` script. Before committing your changes, +please do the following: + +```bash +pip install -U pre-commit +pre-commit run --all-files +``` + +This will run: + +- `clang-format` for code formatting with the `.clang-format` file provided in the repo, +- `cmake-format` to format the CMake files, +- some other checks (e.g., python script checkers, whitespaces, etc.). + +The script will run on all the files in the repo and will apply the changes in place when needed. +After the script is done, please make sure to review and stage all those changes for the git commit. + +### Backward compatibility + +Before submission, please remember to check if the code compiles fine on the supported compilers. +The CI will check it anyway, but it is good to check at least some of the configurations before +pushing changes. +Especially older compilers can be tricky as those do not have full C++20 conformance. +The official list of supported compilers can always be found in the +[C++ compiler support (API/ABI)](https://mpusz.github.io/mp-units/latest/getting_started/cpp_compiler_support) +chapter of our documentation. diff --git a/cmake/.cmake-format-additional_commands-jegp.cmake_modules.yaml b/cmake/.cmake-format-additional_commands-jegp.cmake_modules.yaml new file mode 100644 index 00000000..232dc6f5 --- /dev/null +++ b/cmake/.cmake-format-additional_commands-jegp.cmake_modules.yaml @@ -0,0 +1,82 @@ +parse: + additional_commands: + _jegp_common_yaml_anchors: + kwargs: + PUBLIC_INTERFACE_PRIVATE: &public_interface_private + kwargs: + PUBLIC: + + INTERFACE: + + PRIVATE: + + jegp_add_standardese_sources: + pargs: + nargs: 1 + flags: + - EXCLUDE_FROM_ALL + kwargs: + LIBRARIES: + + APPENDICES: + + EXTENSIONS: + + CHECKED: 1 + PDF: &standardese_pdf + pargs: + flags: + - EXCLUDE_FROM_MAIN + kwargs: + PATH: 1 + HTML: + <<: *standardese_pdf + kwargs: + SECTION_FILE_STYLE: 1 + LATEX_REGEX_REPLACE: + + HTML_REGEX_REPLACE: + + jegp_add_module: + pargs: &jegp_add_module_pargs + nargs: 1 + flags: + - IMPORTABLE_HEADER + kwargs: + SOURCES: + + COMPILE_OPTIONS: *public_interface_private + LINK_LIBRARIES: *public_interface_private + jegp_cpp_module: + pargs: *jegp_add_module_pargs + jegp_target_link_header_units: + pargs: + nargs: 1+ + jegp_cpp2_target_sources: + pargs: + nargs: 1 + kwargs: + JEGP_FILE_SET_KWARGS: &file_set + kwargs: + FILE_SET: 1 + TYPE: 1 + BASE_DIRS: + + FILES: + + PUBLIC: *file_set + INTERFACE: *file_set + PRIVATE: *file_set + jegp_add_headers_test: + pargs: + nargs: 1+ + kwargs: + PRIVATE_REGEXES: + + jegp_add_test: + pargs: + nargs: 1+ + flags: + - COMPILE_ONLY + kwargs: + TYPE: 1 + SOURCES: + + COMPILE_OPTIONS: + + LINK_LIBRARIES: + + jegp_add_build_error: + pargs: + nargs: 1+ + kwargs: + AS: 1 + TYPE: 1 + SOURCE: 1 + COMPILE_OPTIONS: + + LINK_LIBRARIES: + diff --git a/docs/api_reference.md b/docs/api_reference.md new file mode 100644 index 00000000..e4e45f97 --- /dev/null +++ b/docs/api_reference.md @@ -0,0 +1,74 @@ +--- +hide: + - navigation + - toc +--- + + + + + + + diff --git a/docs/api_reference/src/CMakeLists.txt b/docs/api_reference/src/CMakeLists.txt new file mode 100644 index 00000000..74fc94fb --- /dev/null +++ b/docs/api_reference/src/CMakeLists.txt @@ -0,0 +1,41 @@ +cmake_minimum_required(VERSION 3.24.0) +project(mp-units_reference_documentations LANGUAGES NONE) + +include(JEGPAddStandardeseSources) + +set(pdf_title "mp-units Library") +set(page_license "MIT License") +set(first_library_chapter "qties") +set(last_library_chapter "qties") +set(cover_title "mp-units Library Reference Documentations") +set(reply_to "\\href{${PROJECT_HOMEPAGE_URL}/discussions}{Discussions}, \\href{${PROJECT_HOMEPAGE_URL}/issues}{issues}") +jegp_add_standardese_sources( + mp-units_reference_documentations + LIBRARIES intro quantities + EXTENSIONS macros_extensions + CHECKED TRUE + # PDF PATH "mp-units.pdf" #[[EXCLUDE_FROM_MAIN]] + HTML PATH "mp-units.html" #[[EXCLUDE_FROM_MAIN]] + SECTION_FILE_STYLE "WithExtension" + LATEX_REGEX_REPLACE + # Latex commands. + [[\\href{([^}]+)}{([^}]+)};HREF(\1)(\2)]] + # Macros extensions. + [[\\refcpp{([^}]+)};REFCPP(\1)]] + [[\\irefcpp{([^}]+)};~(REFCPP(\1))]] + [[\\refcppx{([^}]+)}{([^}]+)};REFCPPX(\1)(\2)]] + [[\\irefcppx{([^}]+)}{([^}]+)};~(REFCPPX(\1)(\2))]] + [[\\refiev{([^}]+)};REFIEV(\1)]] + [[\\irefiev{([^}]+)};~(REFIEV(\1))]] + # Main matter and annexes. + [[\\\"{o};枚]] + HTML_REGEX_REPLACE + # Latex commands. + [[HREF\(([^)]+)\)\(([^)]+)\);\2]] + # Macros extensions. + [[REFCPP\(([^)]+)\);ISOCPP, [\1]]] + [[REFCPPX\(([^)]+)\)\(([^)]+)\);ISOCPP, [\1]]] # + [[ISOCPP;N4971]] + [[REFIEV\(([^)]+)\);IEC 60050, \1]] + # Main matter and annexes. +) diff --git a/docs/api_reference/src/intro.tex b/docs/api_reference/src/intro.tex new file mode 100644 index 00000000..4daca1c5 --- /dev/null +++ b/docs/api_reference/src/intro.tex @@ -0,0 +1,134 @@ +%!TEX root = std.tex + + +\rSec0[scope]{Scope} + +\pnum +\indextext{scope|(}% +This document describes the contents of the \defn{mp-units library}. +\indextext{scope|)} + + +\rSec0[refs]{References} + +\pnum +\indextext{references|(}% +The following documents are referred to in the text +in such a way that some or all of their content +constitutes requirements of this document. +For dated references, only the edition cited applies. +For undated references, +the latest edition of the referenced document +(including any amendments) applies. +\begin{itemize} +\item +IEC 60050-102:2007/AMD3:2021, +\doccite{Amendment 3 --- International Electrotechnical Vocabulary (IEV) --- +Part 102: Mathematics --- General concepts and linear algebra} +\item +IEC 60050-112:2010/AMD2:2020, +\doccite{Amendment 2 --- International Electrotechnical Vocabulary (IEV) --- +Part 112: Quantities and units} +\item +ISO 80000 (all parts), \doccite{Quantities and units} +\item +The \Cpp{} Standards Committee. +\IsoCpp{}: \doccite{Working Draft, Standard for Programming Language \Cpp{}}. +Edited by Thomas K\"{o}ppe. +Available from: \url{https://wg21.link/\IsoCpp{}} +\item +The \Cpp{} Standards Committee. +SD-8: \doccite{Standard Library Compatibility}. +Edited by Bryce Lelbach. +Available from: \url{https://wg21.link/SD8} +\end{itemize} +\indextext{references|)} + + +\rSec0[defs]{Terms and definitions} + +\pnum +\indextext{definitions|(}% +For the purposes of this document, +the terms and definitions given in +IEC 60050-102:2007/AMD3:2021, +IEC 60050-112:2010/AMD2:2020, +ISO 80000-2:2019, +and +\IsoCpp{}, +and the following apply. + +\pnum +ISO and IEC maintain terminology databases +for use in standardization +at the following addresses: +\begin{itemize} +\item ISO Online browsing platform: available at \url{https://www.iso.org/obp} +\item IEC Electropedia: available at \url{http://www.electropedia.org} +\end{itemize} +\indextext{definitions|)} + + +\rSec0[spec]{Specification} + +\rSec1[spec.ext]{External} + +\pnum +The specification of the mp-units library subsumes +\refcpp{description}, \refcpp{requirements}, \refcpp{concepts.equality}, and SD-8, +all assumingly amended for the context of this library. +\begin{note} +This means that, non exhaustively, +\begin{itemize} +\item \tcode{::mp_units2} is a reserved namespace, and +\item +\tcode{std::vector} +is a program-defined specialization and a library-defined specialization +from the point of view of the \Cpp{} standard library and the mp-units library, respectively. +\end{itemize} +\end{note} + +\pnum +The mp-units library is not part of the \Cpp{} implementation. + +\rSec1[spec.cats]{Categories} + +\pnum +Detailed specifications for each of the components in the library are in +\ref{\firstlibchapter}--\ref{\lastlibchapter}, +as shown in \tref{lib.cats}. + +\begin{floattable}{Library categories}{lib.cats} +{ll} +\topline +\hdstyle{Clause} & \hdstyle{Category} \\ \capsep +\ref{qties} & Quantities library \\ +\end{floattable} + +\pnum +The quantities library\iref{qties} +describes components for dealing with quantities. + +\rSec1[spec.mods]{Modules} + +\pnum +The mp-units library provides the +\defnx{mp-units modules}{module!mp-units}, +shown in \tref{modules}. + +\begin{multicolfloattable}{mp-units modules}{modules} +{lll} +\tcode{mp_units} \\ +\columnbreak +\tcode{mp_units.core} \\ +\columnbreak +\tcode{mp_units.systems} \\ +\end{multicolfloattable} + +\rSec1[spec.reqs]{Library-wide requirements} + +\rSec2[spec.res.names]{Reserved names} + +\pnum +The mp-units library reserves macro names that start with +\tcode{MP_UNITS\opt{\gterm{digit-sequence}}_}. diff --git a/docs/api_reference/src/macros_extensions.tex b/docs/api_reference/src/macros_extensions.tex new file mode 100644 index 00000000..53eabe67 --- /dev/null +++ b/docs/api_reference/src/macros_extensions.tex @@ -0,0 +1,11 @@ +\newcommand{\IsoCpp}{N4971} + +%% Inline non-parenthesized C++ reference +\newcommand{\refcpp}[1]{\href{https://wg21.link/#1}{\IsoCpp{}, [#1]}} +\newcommand{\irefcpp}[1]{\nolinebreak[3] (\refcpp{#1})} +\newcommand{\refcppx}[2]{\href{https://wg21.link/#1\##2}{\IsoCpp{}, [#1]}} +\newcommand{\irefcppx}[2]{\nolinebreak[3] (\refcppx{#1}{#2})} + +%% Inline IEV reference +\newcommand{\refiev}[1]{\href{https://www.electropedia.org/iev/iev.nsf/display?openform&ievref=#1}{IEC 60050, #1}} +\newcommand{\irefiev}[1]{\nolinebreak[3] (\refiev{#1})} diff --git a/docs/api_reference/src/quantities.tex b/docs/api_reference/src/quantities.tex new file mode 100644 index 00000000..56e0d69e --- /dev/null +++ b/docs/api_reference/src/quantities.tex @@ -0,0 +1,266 @@ +%!TEX root = std.tex +\rSec0[qties]{Quantities library} + +\rSec1[qties.summary]{Summary} + +\pnum +This Clause describes components for dealing with quantities, +as summarized in \tref{qties.summary}. + +\begin{modularlibsumtab}{Quantities library summary}{qties.summary} +\ref{qty.helpers} & Helpers & \tcode{mp_units.core} \\ +\ref{qty.traits} & Traits & \\ +\ref{qty.concepts} & Concepts & \\ +\ref{qty.types} & Types & \\ +\ref{qty.compat} & Compatibility & \\ +\ref{qty.one} & Dimension one & \\ \rowsep +\ref{qty.systems} & Systems & \tcode{mp_units.systems} \\ +\ref{qty.chrono} & \tcode{std::chrono} compatibility & \\ +\end{modularlibsumtab} + +\rSec1[mp.units.syn]{Module \tcode{mp_units} synopsis} +\indexmodule{mp_units}% +\begin{codeblock} +export module mp_units; + +export import mp_units.core; +export import mp_units.systems; +\end{codeblock} + +\rSec1[mp.units.core.syn]{Module \tcode{mp_units.core} synopsis} +\indexmodule{mp_units.core}% +\begin{codeblock} +export module mp_units.core; + +import std; + +export namespace mp_units { + +export enum class quantity_character { scalar, vector, tensor }; + +// \ref{qty.traits}, traits + +template +constexpr bool treat_as_floating_point = std::is_floating_point_v; + +template +constexpr bool is_scalar = + std::is_floating_point_v || (std::is_integral_v && !is_same_v); + +template +constexpr bool is_vector = false; + +template +constexpr bool is_tensor = false; + +template +struct quantity_values; + +template +struct quantity_like_traits; + +template +struct quantity_point_like_traits; + +// \ref{qty.concepts}, concepts + +template +concept @\deflibconcept{some_reference}@ = template_of(^std::remove_cvref_t) == ^reference; + +template +concept representation = @\seebelownc@; + +template +concept representation_of = @\seebelownc@; + +template +concept some_quantity_spec = @\seebelownc@; + +// \ref{qty.types}, types + +template +struct quantity_spec; // \notdef + +template +struct kind_of_; // \notdef + +template<@\unspec@... Expr> +struct derived_quantity_spec; + +// \ref{qty.type}, class template \tcode{quantity} +export template<@\libconcept{some_reference}@ auto R, + @\libconcept{representation_of}@ Rep = double> +class quantity; + +// \ref{qty.point.type}, class template \tcode{quantity_point} +template<@\unspec@> +class quantity_point; + +} +\end{codeblock} + +\rSec1[mp.units.systems.syn]{Module \tcode{mp_units.systems} synopsis} +\indexmodule{mp_units.systems}% +\begin{codeblock} +export module mp_units.systems; + +export import mp_units.core; +import std; + +export namespace mp_units { + +} +\end{codeblock} + +\rSec1[qty.helpers]{Helpers} + +\begin{itemdecl} +consteval bool @\exposidnc{converts-to-base-subobject-of}@(std::meta type, std::meta template_name); +\end{itemdecl} + +\begin{itemdescr} +\pnum +\expects +\tcode{is_type(type) \&\& is_template(template_name)} is \tcode{true}. + +\pnum +\returns +\tcode{true} if +\tcode{[:type:]} has an unambiguous and accessible base +that is a specialization of \tcode{[:template_name:]}, and +\tcode{false} otherwise. +\end{itemdescr} + +\rSec1[qty.traits]{Traits} + +\begin{itemdecl} +template +constexpr bool @\libglobal{is_scalar}@ = + std::is_floating_point_v || (std::is_integral_v && !is_same_v); + +template +constexpr bool @\libglobal{is_vector}@ = false; + +template +constexpr bool @\libglobal{is_tensor}@ = false; +\end{itemdecl} + +\begin{itemdescr} +\pnum +\remarks +Pursuant to \refcpp{namespace.std}\iref{spec.ext}, +users may specialize \tcode{is_scalar}, \tcode{is_vector}, and \tcode{is_tensor} to \tcode{true} +for cv-unqualified program-defined types +which respectively represent +a scalar\irefiev{102-02-18}, +a vector\irefiev{102-03-04}, and +% FIXME Undefined term. +a tensor, +and \tcode{false} for types which respectively do not. +\end{itemdescr} + +\rSec1[qty.concepts]{Concepts} + +\begin{itemdecl} +export template +concept @\deflibconcept{representation}@ = + (is_scalar || is_vector || is_tensor)&&std::regular && @\exposidnc{scalable}@; +\end{itemdecl} + +\begin{itemdecl} +export template +concept @\deflibconcept{representation_of}@ = + @\libconcept{representation}@ && ((Ch == quantity_character::scalar && is_scalar) || + (Ch == quantity_character::vector && is_vector) || + (Ch == quantity_character::tensor && is_tensor)); +\end{itemdecl} + +% FIXME Despite the `some_` prefix, it doesn't conform to the convention +% `template_of(^std::remove_cvref_t) == ^template_name`. +\begin{itemdecl} +template +concept @\defexposconceptnc{named-quantity-spec}@ = + (@\exposidnc{converts-to-base-subobject-of}@(^T, ^quantity_spec) && template_of(^T) != ^kind_of_); + +template +concept @\deflibconcept{some_quantity_spec}@ = + @\exposconceptnc{named-quantity-spec}@ || + detail::IntermediateDerivedQuantitySpec || + template_of(^T) == ^kind_of; +\end{itemdecl} + +\rSec1[qty.types]{Types} + +\rSec2[qty.types.general]{General} + +\pnum +A \defnadj{quantity}{type} +is a type \tcode{\placeholder{Q}} +that is a specialization of \tcode{quantity} or \tcode{quantity_point}. +\tcode{\placeholder{Q}} represents a quantity\irefiev{112-01-01} +with \tcode{\placeholder{Q}::rep} as its number +and \tcode{\placeholder{Q}::reference} as its reference. +\tcode{\placeholder{Q}} is a structural type\irefcppx{temp.param}{term.structural.type} +if \tcode{\placeholder{Q}::rep} is a structural type. + +\pnum +Each class template defined in subclause \ref{qty.types} +has data members and special members specified below, and +has no base classes or members other than those specified. + +\rSec2[qty.type]{Class template \tcode{quantity}} + +\begin{codeblock} +namespace mp_units { + +export template<@\libconcept{some_reference}@ auto R, + @\libconcept{representation_of}@ Rep = double> +class quantity { @\unspec@ }; + +} +\end{codeblock} + +Let \tcode{\placeholder{Q}} be a specialization of \tcode{quantity}. +\begin{itemize} +\item +If \tcode{Rep} is a scalar, +\tcode{\placeholder{Q}} represents a scalar quantity\irefiev{102-02-19}. +\item +If \tcode{Rep} is a vector, +\tcode{\placeholder{Q}} represents a vector\irefiev{102-03-04}. +% FIXME What if `Rep` is a tensor? +\end{itemize} + +\rSec2[qty.point.type]{Class template \tcode{quantity_point}} + +\begin{codeblock} +namespace mp_units { + +export template<@\unspec@> +class quantity_point { @\unspec@ }; + +} +\end{codeblock} + +A \defnadj{quantity point}{type} is a specialization of \tcode{quantity_point}. +Let \tcode{\placeholder{Q}} be a quantity point type. +\tcode{\placeholdernc{Q}::point_origin} represents +the origin point of a position vector\irefiev{102-03-15}. +\begin{itemize} +\item +If \tcode{Rep} is a scalar, +\tcode{\placeholder{Q}} represents the scalar quantity\irefiev{102-02-19} +of a position vector. +\item +If \tcode{Rep} is a vector, +\tcode{\placeholder{Q}} represents a position vector. +% FIXME What if `Rep` is a tensor? +\end{itemize} + +\rSec1[qty.compat]{Compatibility} + +\rSec1[qty.one]{Dimension one} + +\rSec1[qty.systems]{Systems} + +\rSec1[qty.chrono]{\tcode{std::chrono} compatibility} diff --git a/docs/getting_started/contributing.md b/docs/getting_started/contributing.md new file mode 120000 index 00000000..f939e75f --- /dev/null +++ b/docs/getting_started/contributing.md @@ -0,0 +1 @@ +../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/getting_started/installation_and_usage.md b/docs/getting_started/installation_and_usage.md index 1433569c..3a59deac 100644 --- a/docs/getting_started/installation_and_usage.md +++ b/docs/getting_started/installation_and_usage.md @@ -1,155 +1,7 @@ # Installation And Usage -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. - - -## Project structure - -### Repository directory tree and dependencies - -The [GitHub repository](https://github.com/mpusz/mp-units) contains three independent CMake-based -projects: - -- **_./src_** - - - header-only project containing whole **mp-units** library - - _./src/CMakeList.txt_ file is intended as an **entry point for library users** - - in case this library becomes part of the C++ standard, it will have no external dependencies - but until then, it depends on the following: - - - [gsl-lite](https://github.com/gsl-lite/gsl-lite) or [ms-gsl](https://github.com/microsoft/GSL) - to verify runtime contracts (if contract checking is enabled), - - [{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 - - additionally to the dependencies of _./src_ project, it uses: - - - [Catch2](https://github.com/catchorg/Catch2) library as a unit tests framework, - - [linear algebra](https://github.com/BobSteagall/wg21/tree/master/include) - library based on proposal [P1385](https://wg21.link/P1385) used in some examples - and tests. - -- **_./test_package_** - - - CMake library installation and Conan package verification. - - -!!! important "Important: Library users should not use the top-level CMake file" - - Top level _CMakeLists.txt_ file should only be used by **mp-units** developers and contributors - as an entry point for the project's development. We want to ensure that everyone will build **ALL** - the code correctly before pushing a commit. Having such options would allow unintended issues to - leak to PRs and CI. - - 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()`](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-the-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`, - - [`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. +This chapter provides all the necessary information to obtain **mp-units** and build the user's +source code using it. ## Obtaining dependencies @@ -157,66 +9,82 @@ The systems definitions can be found in the `mp-units/systems/...` subdirectory: This library assumes that most of the dependencies will be provided by the [Conan Package Manager](https://conan.io/). If you want to obtain required dependencies by other means, some modifications to the library's CMake files might be needed. -The rest of the dependencies responsible for documentation generation are provided by -`python3-pip`. -### Conan quick intro +??? info "Conan quick intro" -In case you are not familiar with Conan, to install it (or upgrade) just do: + In case you are not familiar with Conan, to install it (or upgrade) just do: -```shell -pip install -U conan -``` - -After that, you might need to add a custom profile file for your development environment -in _~/.conan2/profiles_ directory. An example profile can look as follows: - -```ini hl_lines="5" title="~/.conan2/profiles/gcc12" -[settings] -arch=x86_64 -build_type=Release -compiler=gcc -compiler.cppstd=20 -compiler.libcxx=libstdc++11 -compiler.version=12 -os=Linux - -[conf] -tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"} -``` - -!!! tip "Setting the language version" - - Please note that the **mp-units** library requires at least C++20 to be set in a Conan profile - or forced via the Conan command line. If we do the former, we will not need to provide - `-s compiler.cppstd=20` every time we run a Conan command line (as provided in the command - line instructions below). - -!!! tip "Using Ninja as a CMake generator for Conan" - - It is highly recommended to set Ninja as a CMake generator for Conan. To do so, we should - create a _~/.conan2/global.conf_ file that will set `tools.cmake.cmaketoolchain:generator` - to one of the Ninja generators. For example: - - ```text title="~/.conan2/global.conf" - tools.cmake.cmaketoolchain:generator="Ninja Multi-Config" + ```shell + pip install -U conan ``` -!!! tip "Separate build folders for different configurations" + After that, you might need to add a custom profile file for your development environment + in _~/.conan2/profiles_ directory. An example profile can look as follows: - _~/.conan2/global.conf_ file may also set `tools.cmake.cmake_layout:build_folder_vars` which - [makes working with several compilers or build configurations easier](https://docs.conan.io/2/reference/tools/cmake/cmake_layout.html#multi-setting-option-cmake-layout). - For example, the below line will force Conan to generate separate CMake presets and folders for - each compiler and C++ standard version: + ```ini hl_lines="5" title="~/.conan2/profiles/gcc12" + [settings] + arch=x86_64 + build_type=Release + compiler=gcc + compiler.cppstd=20 + compiler.libcxx=libstdc++11 + compiler.version=12 + os=Linux - ```text title="~/.conan2/global.conf" - tools.cmake.cmake_layout:build_folder_vars=["settings.compiler", "settings.compiler.version", "settings.compiler.cppstd"] + [conf] + tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"} ``` - In such a case, we will need to use a configuration-specific preset name in the Conan instructions - provided below rather than just `conan-default` and `conan-release` - (e.g. `conan-gcc-13-23` and `conan-gcc-13-23-release`) + !!! tip "Setting the language version" + + Please note that the **mp-units** library requires at least C++20 to be set in a Conan profile + or forced via the Conan command line. If we do the former, we will not need to provide + `-s compiler.cppstd=20` every time we run a Conan command line (as provided in the command + line instructions below). + + !!! tip "Using Ninja as a CMake generator for Conan" + + It is highly recommended to set Ninja as a CMake generator for Conan. To do so, we could + create a _~/.conan2/global.conf_ file that will set `tools.cmake.cmaketoolchain:generator` + to one of the Ninja generators. For example: + + ```text title="~/.conan2/global.conf" + tools.cmake.cmaketoolchain:generator="Ninja Multi-Config" + ``` + + !!! tip "Separate build folders for different configurations" + + _~/.conan2/global.conf_ file may also set `tools.cmake.cmake_layout:build_folder_vars` which + [makes working with several compilers or build configurations easier](https://docs.conan.io/2/reference/tools/cmake/cmake_layout.html#multi-setting-option-cmake-layout). + For example, the below line will force Conan to generate separate CMake presets and folders for + each compiler and C++ standard version: + + ```text title="~/.conan2/global.conf" + tools.cmake.cmake_layout:build_folder_vars=["settings.compiler", "settings.compiler.version", "settings.compiler.cppstd"] + ``` + + In such a case, we will need to use a configuration-specific preset name in the Conan instructions + provided below rather than just `conan-default` and `conan-release` + (e.g., `conan-gcc-13-23` and `conan-gcc-13-23-release`) + +??? info "CMake with presets support" + + It is recommended to use at least CMake 3.23 to build this project to benefit from CMake Presets + generated by Conan. All build instructions below assume that you have such support. If not, + your CMake invocations have to be replaced with something like: + + ```shell + mkdir build && cd build + cmake .. -G "Ninja Multi-Config" -DCMAKE_TOOLCHAIN_FILE=/conan_toolchain.cmake + cmake --build . --config Release + ``` + + !!! tip + + In case you can't use CMake 3.23 but you have access to CMake 3.20 or later, you can append + `-c tools.cmake.cmaketoolchain.presets:max_schema_version=2` to the `conan install` command + which will force Conan to use an older version of the CMake Presets schema. ## Build options @@ -225,7 +93,7 @@ tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"} 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. + about which C++ features are required for each option and which compilers support them. ### Conan options @@ -289,166 +157,92 @@ tools.build:compiler_executables={"c": "gcc-12", "cpp": "g++-12"} : [:octicons-tag-24: 2.2.0][conan freestanding] 路 :octicons-milestone-24: `True`/`False` (Default: `False`) Configures the library in the [freestanding](https://en.cppreference.com/w/cpp/freestanding) - mode. When enabled, the library's source code should build with the compiler's + mode. When enabled, the library's source code will build with the compiler's [`-ffreestanding`](https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html) compilation option without any issues. [conan freestanding]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 -### Conan configuration properties +??? info "CMake options to set when Conan is not being used" -[`user.mp-units.build:all`](#user.mp-units.build-all){ #user.mp-units.build-all } + ### CMake options -: [:octicons-tag-24: 2.2.0][conan build all support] 路 :octicons-milestone-24: `True`/`False` (Default: `False`) + Conan will automatically set all the below CMake options based on its configuration (described above). + Manual setting of the below CMake options is only needed when Conan is not being used. - Enables compilation of all the source code, including tests and examples. To support this, it requires some additional Conan build dependencies described in - [Repository directory tree and dependencies](#repository-directory-tree-and-dependencies). - 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`). + [`MP_UNITS_BUILD_AS_SYSTEM_HEADERS`](#MP_UNITS_BUILD_AS_SYSTEM_HEADERS){ #MP_UNITS_BUILD_AS_SYSTEM_HEADERS } - [conan build all support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 + : [:octicons-tag-24: 2.2.0][cmake as system headers support] 路 :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`) -[`user.mp-units.build:skip_la`](#user-skip-la){ #user-skip-la } + Exports library as system headers. -: [:octicons-tag-24: 2.2.0][conan skip la support] 路 :octicons-milestone-24: `True`/`False` (Default: `True`) + [cmake as system headers support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 - 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. + [`MP_UNITS_BUILD_CXX_MODULES`](#MP_UNITS_BUILD_CXX_MODULES){ #MP_UNITS_BUILD_CXX_MODULES } - [conan skip la support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 + : [:octicons-tag-24: 2.2.0][cmake build cxx modules support] 路 :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`) -[`user.mp-units.analyze:clang-tidy`](#user.mp-units.analyze-clang-tidy){ #user.mp-units.analyze-clang-tidy } + Adds C++ modules to the list of default targets. -: [:octicons-tag-24: 2.2.0][conan clang-tidy support] 路 :octicons-milestone-24: `True`/`False` (Default: `False`) + [cmake build cxx modules support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 - Enables clang-tidy analysis. + [`MP_UNITS_BUILD_IMPORT_STD`](#MP_UNITS_BUILD_IMPORT_STD){ #MP_UNITS_BUILD_IMPORT_STD } - [conan clang-tidy support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 + : [:octicons-tag-24: 2.3.0][cmake import std support] 路 :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`) -### CMake options + Enables `import std;` usage. -[`MP_UNITS_BUILD_AS_SYSTEM_HEADERS`](#MP_UNITS_BUILD_AS_SYSTEM_HEADERS){ #MP_UNITS_BUILD_AS_SYSTEM_HEADERS } + [cmake import std support]: https://github.com/mpusz/mp-units/releases/tag/v2.3.0 -: [:octicons-tag-24: 2.2.0][cmake as system headers support] 路 :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`) + [`MP_UNITS_API_STD_FORMAT`](#MP_UNITS_API_STD_FORMAT){ #MP_UNITS_API_STD_FORMAT } - Exports library as system headers. + : [:octicons-tag-24: 2.2.0][cmake std::format support] 路 :octicons-milestone-24: `ON`/`OFF` (Default: automatically determined) - [cmake as system headers support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 + 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. -[`MP_UNITS_BUILD_CXX_MODULES`](#MP_UNITS_BUILD_CXX_MODULES){ #MP_UNITS_BUILD_CXX_MODULES } + [cmake std::format support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 -: [:octicons-tag-24: 2.2.0][cmake build cxx modules support] 路 :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`) + [`MP_UNITS_API_STRING_VIEW_RET`](#MP_UNITS_API_STRING_VIEW_RET){ #MP_UNITS_API_STRING_VIEW_RET } - Adds C++ modules to the list of default targets. + : [:octicons-tag-24: 2.2.0][cmake returning string_view] 路 :octicons-milestone-24: `ON`/`OFF` (Default: automatically determined) - [cmake build cxx modules support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 + 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` instead. -[`MP_UNITS_BUILD_IMPORT_STD`](#MP_UNITS_BUILD_IMPORT_STD){ #MP_UNITS_BUILD_IMPORT_STD } + [cmake returning string_view]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 -: [:octicons-tag-24: 2.3.0][cmake import std support] 路 :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`) + [`MP_UNITS_API_NO_CRTP`](#MP_UNITS_API_NO_CRTP){ #MP_UNITS_API_NO_CRTP } - Enables `import std;` usage. + : [:octicons-tag-24: 2.2.0][cmake no crtp support] 路 :octicons-milestone-24: `ON`/`OFF` (Default: automatically determined) - [cmake import std support]: https://github.com/mpusz/mp-units/releases/tag/v2.3.0 + 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). -[`MP_UNITS_API_STD_FORMAT`](#MP_UNITS_API_STD_FORMAT){ #MP_UNITS_API_STD_FORMAT } + [cmake no crtp support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 -: [:octicons-tag-24: 2.2.0][cmake std::format support] 路 :octicons-milestone-24: `ON`/`OFF` (Default: automatically determined) + [`MP_UNITS_API_CONTRACTS`](#MP_UNITS_API_CONTRACTS){ #MP_UNITS_API_CONTRACTS } - 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. + : [:octicons-tag-24: 2.2.0][cmake contracts] 路 :octicons-milestone-24: `NONE`/`GSL-LITE`/`MS-GSL` (Default: `GSL-LITE`) - [cmake std::format support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 + Enables checking of preconditions and additional asserts in the code. -[`MP_UNITS_API_STRING_VIEW_RET`](#MP_UNITS_API_STRING_VIEW_RET){ #MP_UNITS_API_STRING_VIEW_RET } + [cmake contracts]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 -: [:octicons-tag-24: 2.2.0][cmake returning string_view] 路 :octicons-milestone-24: `ON`/`OFF` (Default: automatically determined) + [`MP_UNITS_API_FREESTANDING`](#MP_UNITS_API_FREESTANDING){ #MP_UNITS_API_FREESTANDING } - 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` instead. + : [:octicons-tag-24: 2.2.0][cmake freestanding] 路 :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`) - [cmake returning string_view]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 + Configures the library in the [freestanding](https://en.cppreference.com/w/cpp/freestanding) + mode. When enabled, the library's source code should build with the compiler's + [`-ffreestanding`](https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html) compilation option + without any issues. -[`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: `ON`/`OFF` (Default: automatically determined) - - 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 - -[`MP_UNITS_API_CONTRACTS`](#MP_UNITS_API_CONTRACTS){ #MP_UNITS_API_CONTRACTS } - -: [:octicons-tag-24: 2.2.0][cmake contracts] 路 :octicons-milestone-24: `NONE`/`GSL-LITE`/`MS-GSL` (Default: `GSL-LITE`) - - Enables checking of preconditions and additional asserts in the code. - - [cmake contracts]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 - -[`MP_UNITS_API_FREESTANDING`](#MP_UNITS_API_FREESTANDING){ #MP_UNITS_API_FREESTANDING } - -: [:octicons-tag-24: 2.2.0][cmake freestanding] 路 :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`) - - Configures the library in the [freestanding](https://en.cppreference.com/w/cpp/freestanding) - mode. When enabled, the library's source code should build with the compiler's - [`-ffreestanding`](https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html) compilation option - without any issues. - - [cmake freestanding]: 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 } - -: [:octicons-tag-24: 2.2.0][cmake build la support] 路 :octicons-milestone-24: `ON`/`OFF` (Default: `ON`) - - Enables building code depending on the linear algebra library. - - [cmake build la support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 - -[`MP_UNITS_DEV_IWYU`](#MP_UNITS_DEV_IWYU){ #MP_UNITS_DEV_IWYU } - -: [:octicons-tag-24: 2.2.0][cmake iwyu support] 路 :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`) - - Enables include-what-you-use analysis. - - [cmake iwyu support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 - -[`MP_UNITS_DEV_CLANG_TIDY`](#MP_UNITS_DEV_CLANG_TIDY){ #MP_UNITS_DEV_CLANG_TIDY } - -: [:octicons-tag-24: 2.2.0][cmake clang-tidy support] 路 :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`) - - Enables clang-tidy analysis. - - [cmake clang-tidy support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 - - -## CMake with presets support - -It is recommended to use at least CMake 3.23 to build this project as this version introduced support -for CMake Presets schema version 4, used now by Conan to generate presets files. All build instructions -below assume that you have such support. If not, your CMake invocations have to be replaced with something -like: - -```shell -mkdir build && cd build -cmake .. -G "Ninja Multi-Config" -DCMAKE_TOOLCHAIN_FILE=/conan_toolchain.cmake -cmake --build . --config Release -``` - -!!! tip - - In case you can't use CMake 3.23 but you have access to CMake 3.20 or later, you can append - `-c tools.cmake.cmaketoolchain.presets:max_schema_version=2` to the `conan install` command - which will force Conan to use an older version of the CMake Presets schema. + [cmake freestanding]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0 ## Installation and reuse @@ -461,42 +255,12 @@ only a few of many options possible. The easiest and most recommended way to obtain **mp-units** is with the Conan package manager. See [Conan + CMake (release)](#conan-cmake-release) for a detailed instruction. - -### Copy - -As **mp-units** is a C++ header-only library you can simply copy all needed _src/*/include_ subdirectories -to your source tree. - -!!! note - - In such a case, you are on your own to ensure all the dependencies are installed and their header - files can be located during the build. Please also note that some compiler-specific flags are needed - to make the code compile without issues. - - -### Copy + CMake - -If you copy the whole **mp-units** repository to your project's file tree, you can reuse CMake targets -defined by the library. To do so, **you should use _CMakeLists.txt_ file from the _./src_ directory**: - -```cmake -add_subdirectory(/src) -# ... -target_link_libraries( mp-units::mp-units) -``` - -!!! note - - You are still on your own to make sure all the dependencies are installed and their header and CMake - configuration files can be located during the build. - - ### Conan + CMake (release) !!! tip - If you are new to the Conan package manager, it is highly recommended to read - [Obtaining Dependencies](#obtaining-dependencies) and refer to + If you are new to the Conan package manager you may want to read + [Obtaining Dependencies](#obtaining-dependencies) and refer to the [Consuming packages](https://docs.conan.io/2/tutorial/consuming_packages.html) chapter of the official Conan documentation for more information. @@ -512,7 +276,6 @@ The following steps may be performed to obtain an official library release: mp-units/2.2.0 [options] - mp-units:cxx_modules=True [layout] cmake_layout @@ -522,8 +285,7 @@ The following steps may be performed to obtain an official library release: CMakeDeps ``` -2. Import **mp-units** and its dependencies definitions to your project's build procedure - with `find_package`: +2. Import **mp-units** and its dependencies definitions with `find_package`: ```cmake find_package(mp-units REQUIRED) @@ -552,7 +314,7 @@ of **mp-units** all the time. Please note that even though the Conan packages that you will be using are generated **ONLY** for builds that are considered stable (passed our CI tests), some minor regressions may happen - (our CI and C++20 build environment is not perfect yet). Also, please expect that the library + (CI and C++ build environments are not perfect yet). Also, please expect that the library interface might, and probably will, change occasionally. Even though we do our best, such changes might not be reflected in the project's documentation right away. @@ -572,7 +334,6 @@ with the following differences: mp-units/2.3.0@mpusz/testing [options] - mp-units:cxx_modules=True [layout] cmake_layout @@ -594,91 +355,60 @@ with the following differences: conan install . -pr -s compiler.cppstd=20 -b=missing -u ``` +??? info "Alternative installation scenarios" -### Install + ### Copy -In case you don't want to use Conan in your project and just want to install the **mp-units** -library on your file system and use `find_package(mp-units)` from another repository to find it; -it is enough to perform the following steps: + As **mp-units** is a C++ header-only library you can simply copy all needed _src/*/include_ subdirectories + to your source tree. -```shell -conan install . -pr -s compiler.cppstd=20 -b=missing -mv CMakeUserPresets.json src -cd src -cmake --preset conan-default -DCMAKE_INSTALL_PREFIX= -cmake --build --preset conan-release --target install -``` + !!! note + + In such a case, you are on your own to ensure all the dependencies are installed and their header + files can be located during the build. Please also note that some compiler-specific flags are needed + to make the code compile without issues. -## Contributing (or just building all the tests and examples) + ### Copy + CMake -In case you would like to build all the **mp-units** source code (with unit tests and examples), -you should: + If you copy the **mp-units** library source code from **the project's _./src_ directory** + (not the entire repo from its root), you can reuse CMake targets defined by the library. + To do so, **you should use _CMakeLists.txt_ file from the _./src_ directory**: -1. Use the _CMakeLists.txt_ from the top-level directory. -2. Run Conan with [`user.mp-units.build:all`](#user.mp-units.build-all) = `True`. - -```shell -git clone https://github.com/mpusz/mp-units.git && cd units -conan build . -pr -s compiler.cppstd=23 -o '&:cxx_modules=True' -c user.mp-units.build:all=True -b missing -``` - -The above will download and install all of the dependencies needed for the development of the library, -build all of the source code, and run unit tests. - -If you prefer to build the project via CMake rather than Conan, then you should replace -the `conan build` with `conan install` command and then follow with a regular CMake build: - -```shell -cmake --preset conan-default -cmake --build --preset conan-release -cmake --build --preset conan-release --target all_verify_interface_header_sets -cmake --build --preset conan-release --target test -``` - - -## Building documentation - -Starting from **mp-units 2.0** we are using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) -to build our documentation. The easiest way to install all the required dependencies -is with `pip`: - -```shell -pip install -U mkdocs-material mkdocs-rss-plugin -``` - -Additionally, a [Cairo Graphics library](https://www.cairographics.org/) is required by -Material for MkDocs. Please follow the -[official MkDocs documentation to install it](https://squidfunk.github.io/mkdocs-material/plugins/requirements/image-processing/#cairo-graphics). - -After that, you can either: - -- easily [start a live server to preview the documentation as you write](https://squidfunk.github.io/mkdocs-material/creating-your-site/#previewing-as-you-write) - - ```shell - mkdocs serve + ```cmake + add_subdirectory() + # ... + target_link_libraries( mp-units::mp-units) ``` -- [build the documentation](https://squidfunk.github.io/mkdocs-material/creating-your-site/#building-your-site) + !!! note + + You are still on your own to make sure all the dependencies are installed and their header and CMake + configuration files can be located during the build. + + !!! important "Important: Library users should not use the top-level CMake file" + + Top level _CMakeLists.txt_ file should only be used by **mp-units developers and contributors** + as an entry point for the project's development. + _./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-the-building-of-tests-and-examples). + + + ### Install + + If you don't want to use Conan in your project and just want to install the **mp-units** + library on your file system, and use `find_package(mp-units)` from another repository to find it; + it is enough to perform the following steps: ```shell - mkdocs build + conan install . -pr -s compiler.cppstd=20 -b=missing + mv CMakeUserPresets.json src + cd src + cmake --preset conan-default -DCMAKE_INSTALL_PREFIX= + cmake --build --preset conan-release --target install ``` - - -## Packaging - -To test CMake installation and Conan packaging or create a Conan package run: - -```shell -conan create . --user --channel -pr -s compiler.cppstd=20 -o '&:cxx_modules=True' -c user.mp-units.build:all=True -b missing -``` - -The above will create a Conan package and run tests provided in _./test_package_ directory. - - -## Uploading **mp-units** package to the Conan server - -```shell -conan upload -r --all mp-units/2.2.0@/ -``` diff --git a/docs/getting_started/project_structure.md b/docs/getting_started/project_structure.md new file mode 100644 index 00000000..9d6c04ae --- /dev/null +++ b/docs/getting_started/project_structure.md @@ -0,0 +1,150 @@ +# Project structure + +This chapter provides a high level overview of the project to make it easier to navigate, build, +and use. + + +## CMake projects and dependencies + +The [GitHub repository](https://github.com/mpusz/mp-units) contains three independent CMake-based +projects: + +- **_./src_** + + - header-only project containing whole **mp-units** library + - _./src/CMakeLists.txt_ file is intended as an **entry point for library users** + - in case this library becomes part of the C++ standard, it will have no external dependencies + but until then, it depends on the following: + + - [gsl-lite](https://github.com/gsl-lite/gsl-lite) or [ms-gsl](https://github.com/microsoft/GSL) + to verify runtime contracts (if contract checking is enabled), + - [{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 + - additionally to the dependencies of _./src_ project, it uses: + + - [Catch2](https://github.com/catchorg/Catch2) library as a unit tests framework, + - [linear algebra](https://github.com/BobSteagall/wg21/tree/master/include) + library based on proposal [P1385](https://wg21.link/P1385) used in some examples + and tests. + +- **_./test_package_** + + - CMake library installation and Conan package verification. + + +!!! important "Important: Library users should not use the top-level CMake file" + + Top level _CMakeLists.txt_ file should only be used by **mp-units** developers and contributors + as an entry point for the project's development. We want to ensure that everyone will build **ALL** + the code correctly before pushing a commit. Having such options would allow unintended issues to + leak to PRs and CI. + + 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()`](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-the-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`](installation_and_usage.md#cxx_modules) Conan option is set to `True`, + - [`MP_UNITS_BUILD_CXX_MODULES`](installation_and_usage.md#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. diff --git a/docs/javascripts/iframeResizer.contentWindow.min.js b/docs/javascripts/iframeResizer.contentWindow.min.js new file mode 100644 index 00000000..3961366c --- /dev/null +++ b/docs/javascripts/iframeResizer.contentWindow.min.js @@ -0,0 +1,9 @@ +/*! iFrame Resizer (iframeSizer.contentWindow.min.js) - v4.3.9 - 2023-11-10 + * Desc: Include this file in any page being loaded into an iframe + * to force the iframe to resize to the content size. + * Requires: iframeResizer.min.js on host page. + * Copyright: (c) 2023 David J. Bradshaw - dave@bradshaw.net + * License: MIT + */ +!function(a){if("undefined"!=typeof window){var r=!0,P="",u=0,c="",s=null,D="",d=!1,j={resize:1,click:1},l=128,q=!0,f=1,n="bodyOffset",m=n,H=!0,W="",h={},g=32,B=null,p=!1,v=!1,y="[iFrameSizer]",J=y.length,w="",U={max:1,min:1,bodyScroll:1,documentElementScroll:1},b="child",V=!0,X=window.parent,T="*",E=0,i=!1,Y=null,O=16,S=1,K="scroll",M=K,Q=window,G=function(){x("onMessage function not defined")},Z=function(){},$=function(){},_={height:function(){return x("Custom height calculation function not defined"),document.documentElement.offsetHeight},width:function(){return x("Custom width calculation function not defined"),document.body.scrollWidth}},ee={},te=!1;try{var ne=Object.create({},{passive:{get:function(){te=!0}}});window.addEventListener("test",ae,ne),window.removeEventListener("test",ae,ne)}catch(e){}var oe,o,I,ie,N,A,C={bodyOffset:function(){return document.body.offsetHeight+ye("marginTop")+ye("marginBottom")},offset:function(){return C.bodyOffset()},bodyScroll:function(){return document.body.scrollHeight},custom:function(){return _.height()},documentElementOffset:function(){return document.documentElement.offsetHeight},documentElementScroll:function(){return document.documentElement.scrollHeight},max:function(){return Math.max.apply(null,e(C))},min:function(){return Math.min.apply(null,e(C))},grow:function(){return C.max()},lowestElement:function(){return Math.max(C.bodyOffset()||C.documentElementOffset(),we("bottom",Te()))},taggedElement:function(){return be("bottom","data-iframe-height")}},z={bodyScroll:function(){return document.body.scrollWidth},bodyOffset:function(){return document.body.offsetWidth},custom:function(){return _.width()},documentElementScroll:function(){return document.documentElement.scrollWidth},documentElementOffset:function(){return document.documentElement.offsetWidth},scroll:function(){return Math.max(z.bodyScroll(),z.documentElementScroll())},max:function(){return Math.max.apply(null,e(z))},min:function(){return Math.min.apply(null,e(z))},rightMostElement:function(){return we("right",Te())},taggedElement:function(){return be("right","data-iframe-width")}},re=(oe=Ee,N=null,A=0,function(){var e=Date.now(),t=O-(e-(A=A||e));return o=this,I=arguments,t<=0||Ok[r]["max"+e])throw new Error("Value for min"+e+" can not be greater than max"+e)}}function h(e,n){null===i&&(i=setTimeout(function(){i=null,e()},n))}function e(){"hidden"!==document.visibilityState&&(O("document","Trigger event: Visibility change"),h(function(){b("Tab Visible","resize")},16))}function b(i,t){Object.keys(k).forEach(function(e){var n;k[n=e]&&"parent"===k[n].resizeFrom&&k[n].autoResize&&!k[n].firstRun&&A(i,t,k[e].iframe,e)})}function y(){F(window,"message",w),F(window,"resize",function(){var e;O("window","Trigger event: "+(e="resize")),h(function(){b("Window "+e,"resize")},16)}),F(document,"visibilitychange",e),F(document,"-webkit-visibilitychange",e)}function n(){function t(e,n){if(n){if(!n.tagName)throw new TypeError("Object is not a valid DOM element");if("IFRAME"!==n.tagName.toUpperCase())throw new TypeError("Expected