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

Most of the old MD documentation files removed

Browse Source
This commit is contained in:
Mateusz Pusz
2020-03-11 13:04:34 +01:00
parent 7f9f741aa0
commit 24af110fb8
11 changed files with 21 additions and 323 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/DESIGN.md
View File

@ -48,7 +48,7 @@ static_assert(10q_km / 5q_km == 2);
The most important concepts in the library are `Unit`, `Dimension`, and `Quantity`:
![Design UML](design.png)
![Design UML](_static/img/concepts.png)
`Unit` is a basic building block of the library. Every dimension works with a concrete
hierarchy of units. Such hierarchy defines a reference unit and often a few scaled versions of
@ -86,7 +86,7 @@ and `Ratio` is satisfied by any instantiation of `units::ratio<Num, Den, Exp>`.
The `scaled_unit` type is a framework's private type and the user should never instantiate it directly.
The public user interface to create units consists of:
![Units UML](units.png)
![Units UML](_static/img/units.png)
All below class templates indirectly derive from a `scaled_unit` class template and satisfy a
`Unit` concept:
@ -620,7 +620,7 @@ User-friendly, short name printed by the compiler and the debugger.
To fix it we have to provide a strong type. As we do not have opaque/strong typedefs
in the language we have to use inheritance:
![UML](downcast_1.png)
![UML](_static/img/downcast_1.png)
This gives us a nice looking strong type but does not solve the problem of how to switch from
a long instantiation of a `derived_dimension_base` class template that was generated by the
@ -636,7 +636,7 @@ specific base class template instantiation.
Downcasting facility is provided by injecting two classes into our hierarchy:
![UML](downcast_2.png)
![UML](_static/img/downcast_2.png)
In the above example `dim_area` is a downcasting target (child class) and a specific
`detail::derived_dimension` class template instantiation is a downcasting source (base class).

157
docs/INSTALL.md
View File

@ -1,157 +0,0 @@
# Installation Guide
## Repository structure
This repository contains three independent `cmake`-based projects:
1. `./src`
- header-only project containing whole `mp-units` library
2. `.`
- project used as an entry point for library development (it wraps `./src` project
together with usage examples and tests)
3. `./test_package` - library installation and Conan package verification
NOTE: Please note that this repository depends on a git submodule in the `./cmake/common`
subdirectory.
## Installation and Reuse
There are a few different ways of installing/reusing `units` in your project.
### Conan quick intro
In case you are not familiar with `conan`, to install it just do:
```shell
pip3 install -U conan
```
After that you might need to add a custom profile in `~/.conan/profile` for your
developnment environment. An example profile can look as follows:
```text
[settings]
os=Linux
os_build=Linux
arch=x86_64
arch_build=x86_64
compiler=gcc
compiler.version=9
compiler.cppstd=20
compiler.libcxx=libstdc++11
build_type=Release
[options]
[build_requires]
[env]
CC=/usr/bin/gcc-9
CXX=/usr/bin/g++-9
```
### Copy
As `units` is a header-only library you can simply copy `src/include` directory to
your source tree and use it as regular header files.
NOTE: Until C++20 arrives the library has some 3rd party dependencies that provide
experimental C++20 features. The list of dependencies include:
- `range-v3@ericniebler` (only for gcc-9, gcc-10 uses gcc's concepts implementation)
- `fmt@_`
All of them are easily to obtain with `conan`.
NOTE: In case a full library's repository is to be compiled (instead of just copying
`src/include` headers), additionally, the library's unit tests depend on
`Catch2@catchorg` and `linear_algebra@public-conan` conan packages.
### cmake + conan
To use `units` as a `cmake` imported library via `cmake` configuration files the following
steps may be done:
- clone the repository with its submodules:
```shell
git clone --recurse-submodules https://github.com/mpusz/units.git
```
or in case it is already cloned without submodules initialize, fetch, and checkout them with:
```shell
git submodule update --init
```
- add the following remotes to your local `conan` instance
```shell
conan remote add conan-mpusz https://api.bintray.com/conan/mpusz/conan-mpusz
```
- add `units` as a dependency to your `conan` file. For example to use testing version of
`0.5.0` of `mp-units` add:
- `conanfile.txt`
```ini
[requires]
mp-units/0.5.0@mpusz/testing
```
- `conanfile.py`
```python
requires = "mp-units/0.5.0@mpusz/testing"
```
- import `conan` dependencies to top level `CMakeLists.txt` file
```cmake
include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake)
conan_basic_setup(TARGETS)
```
- link your `cmake` target with units
```cmake
target_link_libraries(<your_target> PUBLIC|PRIVATE|INTERFACE CONAN_PKG::mp-units)
```
- install `conan` dependencies before configuring cmake
```shell
cd build
conan install .. -pr <your_conan_profile> -s compiler.cppstd=20 -b=outdated -u
```
## Full build and unit testing
In case you would like to build all the code in this repository (with unit tests and examples)
you should use the `CMakeLists.txt` from the parent directory and run Conan with
`CONAN_RUN_TESTS=True`.
```shell
git clone --recurse-submodules https://github.com/mpusz/units.git
mkdir units/build && cd units/build
conan remote add linear_algebra https://api.bintray.com/conan/twonington/public-conan
conan install .. -pr <your_conan_profile> -s compiler.cppstd=20 -e CONAN_RUN_TESTS=True -b outdated
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .
ctest -VV
```
## Packaging
To create a `conan` package and test `cmake` installation and `conan` packaging run:
```shell
conan create . <username>/<channel> -pr <your_conan_profile> -s compiler.cppstd=20 -e CONAN_RUN_TESTS=True -b outdated
```
## Upload package to conan server
```shell
conan upload -r <remote-name> --all mp-units/0.5.0@<user>/<channel>
```

115
docs/README.md
View File

@ -1,115 +0,0 @@
# `mp-units` - Documentation
## How to build?
1. Install the requirements (Sphinx) with:
```shell
pip3 install -r docs/requirements.txt
```
2. Install all dependencies with Conan for a developer's build:
```shell
conan install .. -pr <your_conan_profile> -s compiler.cppstd=20 -e CONAN_RUN_TESTS=True -b outdated
```
3. Install Python 3
4. Build the documentation with a regular CMake build
## How to contribute?
To make any contribution to **mp-units** documentation please fork this repository and open
a Pull Request.
### Style Guidelines
This guidelines are just general good practices for the formatting and structure of the whole
documentation and do not pretend to be a stopper for any helpful contribution. Any contribution
that may include relevant information for **mp-units** users will always be welcomed.
**mp-units** documentation is written in [reStructuredText](http://docutils.sourceforge.net/rst.html)
and follows [reStructuredText Markup Specification](http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html).
[Quick reStructuredText](http://docutils.sourceforge.net/docs/user/rst/quickref.html) is also
used for reference.
Any detail not covered by this guidelines will follow the aforementioned rules.
#### Section titles
Use section titles in this level of importance:
```rst
Section Title
=============
Subsection Title
----------------
Subsubsection Title
^^^^^^^^^^^^^^^^^^^
```
#### Text emphasis/highlighting
- **Bold text** to highlight important text:
```rst
**mp-units** is a compile-time enabled Modern C++ library that provides compile-time dimensional
analysis and unit/quantity manipulation.
```
- *Italics* to refer to file names, directory names, and paths.
```rst
Create Conan configuration file (either *conanfile.txt* or *conanfile.py*) in your project's
top-level directory...
```
- ``Inline literals`` to refer to the in examples that is not a part of the **mp-units** library:
```rst
Let's assume that the user wants to implement an ``avg_speed`` function that will
be calculating the average speed based on provided distance and duration quantities.
```
#### Literal blocks
Most of the C++ code examples should be provided as literal blocks after double `::` symbol:
```rst
For this dimension-specific concepts come handy again and with usage of C++20 generic
functions our function can look as simple as::
constexpr Velocity auto avg_speed(Length auto d, Time auto t)
{
return d / t;
}
```
#### code-blocks
Use code-blocks for exceptional cases like code samples in other languages or a need
to emphasize specific lines of code:
```rst
Quantities of the same dimension can be easily added or subtracted with
each other and the result will always be a quantity of the same dimension:
.. code-block::
:emphasize-lines: 3-4
Length auto dist1 = 2q_m;
Length auto dist2 = 1q_m;
Length auto res1 = dist1 + dist2;
Length auto res2 = dist1 - dist2;
```
#### Indentation and line length
Make sure all indentation is done with spaces. Normally 2 space indentation for bulleted lists
and 4 space indentation for code blocks and RST directives contents:
Do not leave any unnecessary or trailing spaces.

0
docs/_static/img/design.png → docs/_static/img/concepts.png vendored
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 27 KiB

After

Width:  |  Height:  |  Size: 27 KiB

0
docs/downcast_1.png → docs/_static/img/downcast_1.png vendored
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

0
docs/downcast_2.png → docs/_static/img/downcast_2.png vendored
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 32 KiB

After

Width:  |  Height:  |  Size: 32 KiB

BIN
docs/design.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 27 KiB

16
docs/design.rst
View File

@ -11,3 +11,19 @@ Design
:maxdepth: 2
design/quantity
The Downcasting Facility
------------------------
..
http://www.nomnoml.com
[detail::derived_dimension_base<exp<si::dim_length, 2>>]<:-[dim_area]
..
http://www.nomnoml.com
[downcast_base<detail::derived_dimension_base<exp<si::dim_length, 2>>>]<:-[detail::derived_dimension_base<exp<si::dim_length, 2>>]
[detail::derived_dimension_base<exp<si::dim_length, 2>>]<:-[downcast_child<dim_area, detail::derived_dimension_base<exp<si::dim_length, 2>>>]
[downcast_child<dim_area, detail::derived_dimension_base<exp<si::dim_length, 2>>>]<:-[dim_area]

2
docs/framework/basic_concepts.rst
View File

@ -6,7 +6,7 @@ Basic Concepts
The most important concepts in the library are `Unit`, `Dimension`, and
`Quantity`:
.. image:: /_static/img/design.png
.. image:: /_static/img/concepts.png
:align: center
..

46
docs/nomnoml.md
View File

@ -1,46 +0,0 @@
# nomnoml
Graphs in the documentation are created with <http://www.nomnoml.com>.
## Concepts
```text
[<abstract>Dimension|
[base_dimension<Symbol, Unit>]<-[exp<Dimension, Num, Den>]
[derived_dimension<Child, Unit, Exponent...>]<-[exp<Dimension, Num, Den>]
[exp<Dimension, Num, Den>]<-[derived_dimension<Child, Unit, Exponent...>]
]
[<abstract>Quantity|
[quantity<Dimension, Unit, Rep>]
]
[<abstract>Unit]<-[Dimension]
[Dimension]<-[Quantity]
[Unit]<-[Quantity]
```
## Units
```text
#direction: right
[scaled_unit<Ratio, Unit>]<:-[unit<Child>]
[scaled_unit<Ratio, Unit>]<:-[named_unit<Child, Symbol, PrefixType>]
[scaled_unit<Ratio, Unit>]<:-[named_scaled_unit<Child, Symbol, PrefixType, Ratio, Unit>]
[scaled_unit<Ratio, Unit>]<:-[prefixed_unit<Child, Prefix, Unit>]
[scaled_unit<Ratio, Unit>]<:-[deduced_unit<Child, Dimension, Unit, Unit...>]
```
## Downcasting 1
```text
[detail::derived_dimension_base<exp<si::dim_length, 2>>]<:-[dim_area]
```
## Downcasting 2
```text
[downcast_base<detail::derived_dimension_base<exp<si::dim_length, 2>>>]<:-[detail::derived_dimension_base<exp<si::dim_length, 2>>]
[detail::derived_dimension_base<exp<si::dim_length, 2>>]<:-[downcast_child<dim_area, detail::derived_dimension_base<exp<si::dim_length, 2>>>]
[downcast_child<dim_area, detail::derived_dimension_base<exp<si::dim_length, 2>>>]<:-[dim_area]```

BIN
docs/units.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 33 KiB