forked from mpusz/mp-units
Documentation cleanup
This commit is contained in:
Mateusz Pusz
22
README.md
22
README.md
@@ -1,8 +1,8 @@
|
||||
[](https://raw.githubusercontent.com/mpusz/units/master/LICENSE)
|
||||
[](https://travis-ci.com/mpusz/units)
|
||||
[](https://ci.appveyor.com/project/mpusz/units)
|
||||
[ ](https://bintray.com/mpusz/conan-mpusz/mp-units%3Ampusz/0.3.1%3Astable/link)
|
||||
[ ](https://bintray.com/mpusz/conan-mpusz/mp-units%3Ampusz/_latestVersion)
|
||||
[](https://bintray.com/mpusz/conan-mpusz/mp-units%3Ampusz/0.3.1%3Astable/link)
|
||||
[](https://bintray.com/mpusz/conan-mpusz/mp-units%3Ampusz/_latestVersion)
|
||||
|
||||
# `mp-units` - A Units Library for C++
|
||||
|
||||
@@ -35,10 +35,10 @@ static_assert(10_km / 5_km == 2);
|
||||
## Repository structure
|
||||
|
||||
That repository contains the following independent `cmake`-based projects:
|
||||
- `./src` - header-only project for `units`
|
||||
- `.` - project used for development needs that wraps `./src` project together with
|
||||
usage examples and unit tests
|
||||
- `./test_package` - library installation and Conan package verification
|
||||
- `./src` - header-only project for `units`
|
||||
- `.` - project used for development needs that wraps `./src` project together with
|
||||
usage examples and unit tests
|
||||
- `./test_package` - library installation and Conan package verification
|
||||
|
||||
Please note that the projects depend on `cmake` git submodule in the `./cmake/common`
|
||||
subdirectory.
|
||||
@@ -52,7 +52,7 @@ NOTE: This library as of now compiles correctly only with gcc-9.1 and newer.
|
||||
|
||||
## 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)
|
||||
|
||||
## 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
|
||||
|
||||
- 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
|
||||
- `upcasting_traits` renamed to `downcasting_traits`
|
||||
- `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
|
||||
- `base_dimension` is a value provided as `const&` to the `exp` type
|
||||
- integrated with Compiler Explorer
|
||||
- gsl-lite deppendency removed
|
||||
- gsl-lite dependency removed
|
||||
- Fractional dimension exponents support added
|
||||
- `QuantityOf` concept introduced
|
||||
- `quantity_cast<U, Rep>()` support added
|
||||
|
||||
- 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`)
|
||||
- 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
|
||||
- Initial library release
|
||||
|
||||
@@ -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
|
||||
register it for a downcasting facitlity:
|
||||
register it for a downcasting facility:
|
||||
|
||||
```cpp
|
||||
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
|
||||
template<typename T>
|
||||
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
|
||||
struct bit : units::derived_unit<bit, digital_information> {};
|
||||
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
|
||||
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
|
||||
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.
|
||||
|
||||
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?
|
||||
|
||||
@@ -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.
|
||||
|
||||
## Copy
|
||||
### 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. They can be easily obtained with conan
|
||||
experimental C++20 features. The list of dependncies include:
|
||||
- `range-v3@ericniebler`
|
||||
|
||||
```python
|
||||
requires = (
|
||||
"cmcstl2/2019.03.18@mpusz/stable",
|
||||
"gsl-lite/0.33.0@nonstd-lite/stable"
|
||||
)
|
||||
```
|
||||
All of them are easily obtained with `conan`.
|
||||
|
||||
## cmake + conan
|
||||
### cmake + conan
|
||||
|
||||
To use `units` as a `cmake` imported library via `cmake` configuration files the following
|
||||
steps may be done:
|
||||
- add the following remotes to your local `conan` instance
|
||||
|
||||
```bash
|
||||
$ 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
|
||||
```shell
|
||||
conan remote add conan-mpusz https://api.bintray.com/conan/mpusz/conan-mpusz
|
||||
```
|
||||
|
||||
- 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`
|
||||
|
||||
```text
|
||||
[requires]
|
||||
mp-units/0.0.1@mpusz/testing
|
||||
mp-units/0.4.0@mpusz/testing
|
||||
```
|
||||
|
||||
- `conanfile.py`
|
||||
|
||||
```python
|
||||
requires = "mp-units/0.0.1@mpusz/testing"
|
||||
requires = "mp-units/0.4.0@mpusz/testing"
|
||||
```
|
||||
|
||||
- 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)
|
||||
```
|
||||
|
||||
- install conan dependencies before configuring cmake
|
||||
- install `conan` dependencies before configuring cmake
|
||||
|
||||
```bash
|
||||
$ cd build
|
||||
$ conan install .. -pr <your_conan_profile> -s cppstd=20 -b=outdated -u
|
||||
```shell
|
||||
cd build
|
||||
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)
|
||||
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
|
||||
conan install .. <your_profile_and_settings> -s cppstd=20
|
||||
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:
|
||||
|
||||
```bash
|
||||
$ conan create . <username>/<channel> -s cppstd=20 -b=outdated <your_profile_and_settings>
|
||||
```shell
|
||||
conan create . <username>/<channel> -s cppstd=20 -b=outdated <your_profile_and_settings>
|
||||
```
|
||||
|
||||
|
||||
# Upload package to conan server
|
||||
## Upload package to conan server
|
||||
|
||||
```bash
|
||||
$ conan upload -r <remote-name> --all mp-units/0.0.1@<user>/<channel>
|
||||
```shell
|
||||
conan upload -r <remote-name> --all mp-units/0.4.0@<user>/<channel>
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user