Skip to content

Latest commit

 

History

History
417 lines (267 loc) · 12.6 KB

usage.rst

File metadata and controls

417 lines (267 loc) · 12.6 KB

Installation And Usage

Note

This library targets C++23/26 and extensively uses C++20 features. This is why it requires the latest C++ compilers. The following compilers (or newer) are supported:

  • gcc-10
  • clang-12
  • Visual Studio 16.9
  • Apple clang 13

Repository Structure and Dependencies

This repository contains three independent CMake-based projects:

  • ./src
    • header-only project containing whole mp-units library
    • when this library will become part of the C++ standard it will have no external dependencies but until then it depends on:
      • {fmt} to provide text formatting of quantities.
      • gsl-lite to verify runtime contracts with the gsl_Expects macro.
      • [only for clang < 14 with libc++] range-v3 to provide needed C++20 concepts and utilities.
  • .
    • 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:
  • ./test_package
    • library installation and Conan package verification.

Obtaining Dependencies

This library assumes that most of the dependencies will be provided by the Conan Package Manager. In case you would like to obtain required dependencies by other means some modifications to library's CMake files might be needed. The rest of the dependencies responsible for documentation generation are provided by :command:`python3-pip`.

.. seealso::

  A full list of dependencies can be found in `Repository Structure and Dependencies`_.

Conan Quick Intro

In case you are not familiar with Conan, to install it (or upgrade) just do:

pip3 install -U conan

After that you might need to add a custom profile file for your development environment in ~/.conan/profiles directory. An example profile can look as follows:

[settings]
os=Linux
os_build=Linux
arch=x86_64
arch_build=x86_64
compiler=gcc
compiler.version=10
compiler.cppstd=20
compiler.libcxx=libstdc++11
build_type=Release

[options]
[build_requires]

[conf]
tools.cmake.cmaketoolchain:generator=Ninja

[env]
CC=/usr/bin/gcc-10
CXX=/usr/bin/g++-10

Tip

Please note that mp-units library requires C++20 to be set either in a Conan profile or forced via Conan command line. If you do the former, you will not need to provide -s compiler.cppstd=20 every time your run a Conan command line (as it is suggested below).

Build Options

Environment Variables

CONAN_RUN_TESTS

Values: True/False

Defaulted to: False

Enables compilation of all the source code (tests and examples) and building the documentation. To support this it requires some additional Conan build dependencies described in Repository Structure and Dependencies. It also runs unit tests during Conan build.

Conan Options

downcast_mode

Values: off/on/auto

Defaulted to: on

Specifies how :ref:`design/downcasting:The Downcasting Facility` works:

  • off - no downcasting at all
  • on - downcasting always forced -> compile-time errors in case of duplicated definitions
  • automatic - downcasting automatically enabled if no collisions are present

build_docs

Values: True/False

Defaulted to: True

If enabled, Conan installs the documentation generation dependencies (i.e. doxygen). Additionally, enables project documentation generation when the project is being built by Conan.

CMake Options

UNITS_AS_SYSTEM_HEADERS

Values: ON/OFF

Defaulted to: OFF

Exports library as system headers.

UNITS_BUILD_DOCS

Values: ON/OFF

Defaulted to: ON

Enables project documentation generation.

UNITS_DOWNCAST_MODE

Values: OFF/ON/AUTO

Defaulted to: ON

Equivalent to downcast_mode.

UNITS_IWYU

Values: ON/OFF

Defaulted to: OFF

Enables include-what-you-use when compiling with a clang compiler. Additionally turns on UNITS_AS_SYSTEM_HEADERS.

UNITS_USE_LIBFMT

Values: ON/OFF

Defaulted to: ON

Enables usage of {fmt} library instead of the C++20 Standard Library feature.

Installation and Reuse

There are many different ways of installing/reusing mp-units in your project. Below we mention only a few of many options possible.

Copy

As mp-units is a C++ header-only library you can simply copy all needed src/*/include subdirectories to your source tree.

Important

In such a case you are on your own to make sure 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

In case 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:

add_subdirectory(<path_to_units_folder>/src)
# ...
target_link_libraries(<your_target> <PUBLIC|PRIVATE|INTERFACE> mp-units::mp-units)

Important

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 Conan package manager it is highly recommended to read Obtaining Dependencies and refer to Getting Started and Using packages chapters of the official Conan documentation for more information.

mp-units releases are hosted on Conan-Center. To obtain official library release the following steps may be performed:

  1. Create Conan configuration file (either conanfile.txt or conanfile.py) in your project's top-level directory and add mp-units as a dependency of your project. For example the simplest file may look as follows:
[requires]
mp-units/0.7.0

[generators]
CMakeToolchain
CMakeDeps
  1. Import mp-units and its dependencies definitions to your project's build procedure with find_package:
find_package(mp-units CONFIG REQUIRED)
  1. Link your CMake targets with mp-units:
target_link_libraries(<your_target> <PUBLIC|PRIVATE|INTERFACE> mp-units::mp-units)
target_compile_features(<your_target> <PUBLIC|PRIVATE|INTERFACE> cxx_std_20)

Important

Unfortunately, packages distributed via Conan-Center cannot force the minimum version of the C++ language used for your build process. This is why it is important to specify it in Conan profile file and with target_compile_features command for each CMake target directly linking with mp-units::mp-units in your project.

  1. Download, build, and install Conan dependencies before running CMake configuration step:
mkdir my_project/build && cd my_project/build
conan install .. -pr <your_conan_profile> -s compiler.cppstd=20 -b=missing
cmake .. -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
cmake --build .

Conan + CMake (Live At Head)

This chapter describes the procedure to Live At Head which means to use the latest version of mp-units all the time.

Note

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 interface might, and probably will, change from time to time. Even though we do our best, such changes might not be reflected in the project's documentation right away.

The procedure is similar to the one described in Conan + CMake (release) with the following differences:

  1. Before starting the previous procedure add mp-units remote to your Conan configuration:
conan remote add conan-mpusz https://mpusz.jfrog.io/artifactory/api/conan/conan-oss
  1. In your Conan configuration file provide package identifier of the mpusz/testing stream:
[requires]
mp-units/0.8.0@mpusz/testing

[generators]
CMakeToolchain
CMakeDeps

Tip

The identifiers of the latest packages can always be found in the project's README file or on the project's Artifactory.

  1. Force Conan to check for updated recipes -u and to build outdated packages -b outdated:
mkdir my_project/build && cd my_project/build
conan install .. -pr <your_conan_profile> -s compiler.cppstd=20 -b=outdated -u
cmake .. -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
cmake --build .

Install

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 it via find_package(mp-units) from another repository to find it, it is enough to perform the following steps:

mkdir units/build && cd units/build
conan install .. -pr <your_conan_profile> -s compiler.cppstd=20 -b=missing
cmake ../src -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
cmake --install . --prefix <install_dir>

Contributing (or just building all the tests, examples, and documentation)

In case you would like to build all the source code (with unit tests and examples) and documentation in mp-units repository, you should:

  1. Add remotes of additional Conan dependencies.
  2. Use the CMakeLists.txt from the top-level directory.
  3. Obtain Python dependencies.
  4. Run Conan with CONAN_RUN_TESTS = True.
git clone https://github.com/mpusz/units.git && cd units
pip3 install -r docs/requirements.txt
mkdir units/build && cd units/build
conan install .. -pr <your_conan_profile> -s compiler.cppstd=20 -e mp-units:CONAN_RUN_TESTS=True -b outdated -u
conan build ..

The above will download and install all of the dependencies needed for the development of the library, build all of the source code and documentation, and run unit tests.

If you prefer to build the project via CMake rather then Conan, then you should replace the last conan build .. step with the CMake build:

# ...
cmake .. -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
cmake --build .
ctest

Packaging

To test CMake installation and Conan packaging or create a Conan package run:

conan create . <username>/<channel> -pr <your_conan_profile> -s compiler.cppstd=20 -e mp-units:CONAN_RUN_TESTS=True -b outdated -u

The above will create a Conan package and run tests provided in ./test_package directory.

Uploading mp-units Package to the Conan Server

conan upload -r <remote-name> --all mp-units/0.8.0@<user>/<channel>