feedc0de/mp-units
1
0
Fork 0
forked from mpusz/mp-units
Code Pull Requests Activity

Documentation cleanup

Browse Source
This commit is contained in:
Mateusz Pusz
2019-10-04 08:29:24 +02:00
parent 7c4e5d086a
commit 9c436812f5
3 changed files with 73 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
README.md
View File

@@ -1,8 +1,8 @@
[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg?maxAge=3600)](https://raw.githubusercontent.com/mpusz/units/master/LICENSE) [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg?maxAge=3600)](https://raw.githubusercontent.com/mpusz/units/master/LICENSE)
[![Travis CI](https://img.shields.io/travis/com/mpusz/units/master.svg?label=Travis%20CI)](https://travis-ci.com/mpusz/units) [![Travis CI](https://img.shields.io/travis/com/mpusz/units/master.svg?label=Travis%20CI)](https://travis-ci.com/mpusz/units)
[![AppVeyor](https://img.shields.io/appveyor/ci/mpusz/units/master.svg?label=AppVeyor)](https://ci.appveyor.com/project/mpusz/units) [![AppVeyor](https://img.shields.io/appveyor/ci/mpusz/units/master.svg?label=AppVeyor)](https://ci.appveyor.com/project/mpusz/units)
[![Conan stable](https://api.bintray.com/packages/mpusz/conan-mpusz/mp-units%3Ampusz/images/download.svg?version=0.3.1%3Astable) ](https://bintray.com/mpusz/conan-mpusz/mp-units%3Ampusz/0.3.1%3Astable/link) [![Conan stable](https://api.bintray.com/packages/mpusz/conan-mpusz/mp-units%3Ampusz/images/download.svg?version=0.3.1%3Astable)](https://bintray.com/mpusz/conan-mpusz/mp-units%3Ampusz/0.3.1%3Astable/link)
[![Conan testing](https://api.bintray.com/packages/mpusz/conan-mpusz/mp-units%3Ampusz/images/download.svg) ](https://bintray.com/mpusz/conan-mpusz/mp-units%3Ampusz/_latestVersion) [![Conan testing](https://api.bintray.com/packages/mpusz/conan-mpusz/mp-units%3Ampusz/images/download.svg)](https://bintray.com/mpusz/conan-mpusz/mp-units%3Ampusz/_latestVersion)
# `mp-units` - A Units Library for C++ # `mp-units` - A Units Library for C++
@@ -35,10 +35,10 @@ static_assert(10_km / 5_km == 2);
## Repository structure ## Repository structure
That repository contains the following independent `cmake`-based projects: That repository contains the following independent `cmake`-based projects:
- `./src` - header-only project for `units` - `./src` - header-only project for `units`
- `.` - project used for development needs that wraps `./src` project together with - `.` - project used for development needs that wraps `./src` project together with
usage examples and unit tests usage examples and unit tests
- `./test_package` - library installation and Conan package verification - `./test_package` - library installation and Conan package verification
Please note that the projects depend on `cmake` git submodule in the `./cmake/common` Please note that the projects depend on `cmake` git submodule in the `./cmake/common`
subdirectory. subdirectory.
@@ -52,7 +52,7 @@ NOTE: This library as of now compiles correctly only with gcc-9.1 and newer.
## Library design ## Library design
`units` library design rationale and documentation can be found in `mp-units` library design rationale and documentation can be found in
[doc/DESIGN.md](doc/DESIGN.md) [doc/DESIGN.md](doc/DESIGN.md)
## Release notes ## Release notes
@@ -67,7 +67,7 @@ NOTE: This library as of now compiles correctly only with gcc-9.1 and newer.
- cmcstl2 dependency changed to range-v3 0.9.1 - cmcstl2 dependency changed to range-v3 0.9.1
- 0.3.0 Sep 16, 2019 (CppCon 2019 design) - 0.3.0 Sep 16, 2019 (CppCon 2019 design)
- The design as described on CppCon 2019 talk - The design as described on CppCon 2019 talk (<https://youtu.be/0YW6yxkdhlU>)
- Applied the feedback from the Cologne evening session - Applied the feedback from the Cologne evening session
- `upcasting_traits` renamed to `downcasting_traits` - `upcasting_traits` renamed to `downcasting_traits`
- `Dimension` template parameter removed from quantity - `Dimension` template parameter removed from quantity
@@ -81,15 +81,15 @@ NOTE: This library as of now compiles correctly only with gcc-9.1 and newer.
- cmcstl2 library updated to 2019.09.19 - cmcstl2 library updated to 2019.09.19
- `base_dimension` is a value provided as `const&` to the `exp` type - `base_dimension` is a value provided as `const&` to the `exp` type
- integrated with Compiler Explorer - integrated with Compiler Explorer
- gsl-lite deppendency removed - gsl-lite dependency removed
- Fractional dimension exponents support added - Fractional dimension exponents support added
- `QuantityOf` concept introduced - `QuantityOf` concept introduced
- `quantity_cast<U, Rep>()` support added - `quantity_cast<U, Rep>()` support added
- 0.2.0 July 18, 2019 (C++Now 2019 design) - 0.2.0 July 18, 2019 (C++Now 2019 design)
- The design as described on C++Now 2019 talk (https://youtu.be/wKchCktZPHU) - The design as described on C++Now 2019 talk (<https://youtu.be/wKchCktZPHU>)
- Added C++20 features supported by gcc-9.1 (`std::remove_cvref_t`, down with typename, `std::type_identity`) - Added C++20 features supported by gcc-9.1 (`std::remove_cvref_t`, down with typename, `std::type_identity`)
- Compile-time performance optimisations (`type_list`, `common_ratio`, `ratio`, `conditional_t`) - Compile-time performance optimizations (`type_list`, `common_ratio`, `ratio`, `conditional_t`)
- 0.1.0 May 18, 2019 - 0.1.0 May 18, 2019
- Initial library release - Initial library release

16
doc/DESIGN.md
View File

@@ -627,27 +627,27 @@ In order to extend the library with custom dimensions the user has to:
``` ```
2. Create a new dimension type with the recipe of how to construct it from base dimensions and 2. Create a new dimension type with the recipe of how to construct it from base dimensions and
register it for a downcasting facitlity: register it for a downcasting facility:
```cpp ```cpp
struct digital_information : units::derived_dimension<digital_information, units::exp<base_dim_digital_information, 1>> {}; struct digital_information : units::derived_dimension<digital_information, units::exp<base_dim_digital_information, 1>> {};
``` ```
2. Define a concept that will match a new dimension: 3. Define a concept that will match a new dimension:
```cpp ```cpp
template<typename T> template<typename T>
concept DigitalInformation = units::QuantityOf<T, digital_information>; concept DigitalInformation = units::QuantityOf<T, digital_information>;
``` ```
3. Define units and register them to a downcasting facility: 4. Define units and register them to a downcasting facility:
```cpp ```cpp
struct bit : units::derived_unit<bit, digital_information> {}; struct bit : units::derived_unit<bit, digital_information> {};
struct byte : units::derived_unit<byte, digital_information, units::ratio<8>> {}; struct byte : units::derived_unit<byte, digital_information, units::ratio<8>> {};
``` ```
4. Provide user-defined literals for the most important units: 5. Provide user-defined literals for the most important units:
```cpp ```cpp
inline namespace literals { inline namespace literals {
@@ -687,11 +687,11 @@ In order to extend the library with custom dimensions the user has to:
and allow implicit conversion to and from the underlying value type or types that are and allow implicit conversion to and from the underlying value type or types that are
convertible to/from that value type. convertible to/from that value type.
9. Should we standardize accompany tools (downcasting facility, `type_list` operations, `common_ratio`, etc)? 8. Should we standardize accompany tools (downcasting facility, `type_list` operations, `common_ratio`, etc)?
10. `k`, `K`, `W`, `F` UDLs conflict with gcc GNU extensions (https://gcc.gnu.org/onlinedocs/gcc-4.3.0/gcc/Fixed_002dPoint.html) 9. `k`, `K`, `W`, `F` UDLs conflict with gcc GNU extensions (<https://gcc.gnu.org/onlinedocs/gcc-4.3.0/gcc/Fixed_002dPoint.html>)
for floating point types. for floating point types.
11. `J` imaginary constants are a GCC extension 10. `J` imaginary constants are a GCC extension
12. Do we need custom/multiple systems? 11. Do we need custom/multiple systems?

56
doc/INSTALL.md
View File

@@ -1,45 +1,43 @@
# Installation and Reuse # Installation Guide
## Installation and Reuse
There are a few different ways of installing/reusing `units` in your project. There are a few different ways of installing/reusing `units` in your project.
## Copy ### Copy
As `units` is a header-only library you can simply copy `src/include` directory to 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. your source tree and use it as regular header files.
NOTE: Until C++20 arrives the library has some 3rd party dependencies that provide NOTE: Until C++20 arrives the library has some 3rd party dependencies that provide
experimental C++20 features. They can be easily obtained with conan experimental C++20 features. The list of dependncies include:
- `range-v3@ericniebler`
```python All of them are easily obtained with `conan`.
requires = (
"cmcstl2/2019.03.18@mpusz/stable",
"gsl-lite/0.33.0@nonstd-lite/stable"
)
```
## cmake + conan ### cmake + conan
To use `units` as a `cmake` imported library via `cmake` configuration files the following To use `units` as a `cmake` imported library via `cmake` configuration files the following
steps may be done: steps may be done:
- add the following remotes to your local `conan` instance - add the following remotes to your local `conan` instance
```bash ```shell
$ conan remote add conan-mpusz https://api.bintray.com/conan/mpusz/conan-mpusz conan remote add conan-mpusz https://api.bintray.com/conan/mpusz/conan-mpusz
$ conan remote add conan-nonstd https://api.bintray.com/conan/martinmoene/nonstd-lite
``` ```
- add `units` as a dependency to your `conan` file - add `units` as a dependency to your `conan` file. For example to use testing version of
`0.4.0` of `mp-units` add:
- `conanfile.txt` - `conanfile.txt`
```text ```text
[requires] [requires]
mp-units/0.0.1@mpusz/testing mp-units/0.4.0@mpusz/testing
``` ```
- `conanfile.py` - `conanfile.py`
```python ```python
requires = "mp-units/0.0.1@mpusz/testing" requires = "mp-units/0.4.0@mpusz/testing"
``` ```
- link your `cmake` target with units - link your `cmake` target with units
@@ -48,20 +46,20 @@ steps may be done:
target_link_libraries(<your_target> PUBLIC|PRIVATE|INTERFACE CONAN_PKG::mp-units) target_link_libraries(<your_target> PUBLIC|PRIVATE|INTERFACE CONAN_PKG::mp-units)
``` ```
- install conan dependencies before configuring cmake - install `conan` dependencies before configuring cmake
```bash ```shell
$ cd build cd build
$ conan install .. -pr <your_conan_profile> -s cppstd=20 -b=outdated -u conan install .. -pr <your_conan_profile> -s cppstd=20 -b=outdated -u
``` ```
# Full build and unit testing ## Full build and unit testing
In case you would like to build all the code in that repository (with unit tests and examples) In case you would like to build all the code in that repository (with unit tests and examples)
you should use `CMakeLists.txt` from the parent directory. you should use the `CMakeLists.txt` from the parent directory.
```bash ```shell
mkdir build && cd build mkdir build && cd build
conan install .. <your_profile_and_settings> -s cppstd=20 conan install .. <your_profile_and_settings> -s cppstd=20
cmake .. <your_cmake_configuration> cmake .. <your_cmake_configuration>
@@ -69,17 +67,17 @@ cmake --build .
``` ```
# Packaging ## Packaging
To create a `conan` package and test `cmake` installation and `conan` packaging run: To create a `conan` package and test `cmake` installation and `conan` packaging run:
```bash ```shell
$ conan create . <username>/<channel> -s cppstd=20 -b=outdated <your_profile_and_settings> conan create . <username>/<channel> -s cppstd=20 -b=outdated <your_profile_and_settings>
``` ```
# Upload package to conan server ## Upload package to conan server
```bash ```shell
$ conan upload -r <remote-name> --all mp-units/0.0.1@<user>/<channel> conan upload -r <remote-name> --all mp-units/0.4.0@<user>/<channel>
``` ```