Install

xo-unit uses supporting header-only libraries xo-ratio and xo-flatstring. and (optionally) cmake macros xo-cmake. These are on github:

xo-unit source (constexpr quantities, units and dimension-checking)
xo-ratio source (constexpr exact ratios)
xo-flatstring source (constexpr strings)
xo-cmake source (shared cmake macros)

xo-cmake is nccessary to invoke xo cmake build for:

site install
example programs
unit tests

Can omit to instead copy xo_unit, xo-ratio and xo-flatstring source trees; see instructions below for including as git submodule

Implementation relies on some c++20 features (for example class-instances as template arguments). Tested with gcc 12.3, 13.2

Include as submodule

One way to use xo-unit in a project is to import the source tree directly:

cd myproject
git submodule add -b main https://github.com/rconybea/xo-flatstring ext/xo-flatstring
git submodule add -b main https://github.com/rconybea/xo-ratio ext/xo-ratio
git submodule add -b main https://github.com/rconybea/xo-unit ext/xo-unit
git submodule update --init

This assumes you organize directly-incorporated dependencies under directory myproject/ext. You would then add to your compiler’s include path the directories myproject/ext/xo-flatstring/include, myproject/ext/xo-ratio/include, myproject/ext/xo-unit/include;

and add

#include <xo/unit/quantity.hpp>

to c++ source files that rely on xo-unit

Ubuntu Install Pattern

Example instructions (used for github actions CI) for build starting from stock ubuntu

Installing from source

Install scripts for xo-unit, xo-ratio and xo-flatstring depend on shared cmake macros and a bootstrap script xo-cmake-config fro xo-cmake.

Preamble:

mkdir -p ~/proj/xo
cd ~/proj/xo

git clone https://github.com/rconybea/xo-cmake
git clone https://github.com/rconybea/xo-flatstring
git clone https://github.com/rconybea/xo-ratio
git clone https://github.com/rconybea/xo-unit

PREFIX=~/local  # ..or other desired installation prefix

Ordering below is important; cmake support for each subsystem requires successful installation of its predecessor.

Install xo-cmake:

cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -B xo-cmake/.build -S xo-cmake
cmake --build xo-cmake/.build -j   # placeholder, no-op for now
cmake --install xo-cmake/.build

Build and Install xo-flatstring:

cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -DENABLE_TESTING=0 \
      -B xo-flatstring/.build -S xo-flatstring
cmake --build xo-flatstring/.build -j
cmake --install xo-flatstring/.build

Build and Install xo-ratio:

cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -DENABLE_TESTING=0 \
      -B xo-ratio/.build -S xo-ratio
cmake --build xo-ratio/.build -j
cmake --install xo-ratio/.build

Build and Install xo-unit:

cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -DENABLE_TESTING=0 \
      -B xo-unit/.build -S xo-unit
cmake --build xo-unit/.build -j
cmake --install xo-unit/.build

Directories under PREFIX will then contain:

PREFIX
+- bin
|  \- xo-cmake-config
+- include
|  \- xo
|     +- cxxutil/
|     +- flatstring/
|     +- ratio/
|     +- unit/
+- lib
|  \- cmake
|     +- indentlog/
|     +- randomgen/
|     +- xo_flatstring/
|     \- xo_unit/
+- share
   \- cmake
      \- xo_macros/

Use CMake Support

To use built-in cmake suport:

Make sure PREFIX/lib/cmake is searched by cmake (if necessary, include it in CMAKE_PREFIX_PATH)

Add to CMakeLists.txt:

FindPackage(xo_unit CONFIG REQUIRED)

target_link_libraries(mytarget INTERFACE xo_unit)

Build and Install with Unit Tests Enabled

Running unit tests require a few additional dependencies:

catch2 header-only unit-test framework
xo-indentlog logging with call-structure indenting
xo-randomgen fast random number generator (xoshiro256ss)

Preamble:

mkdir -p ~/proj/xo
cd ~/proj/xo

git clone https://github.com/rconybea/xo-cmake
git clone https://github.com/rconybea/indentlog xo-indentlog
git clone https://github.com/rconybea/randomgen xo-randomgen
git clone https://github.com/rconybea/xo-flatstring
git clone https://github.com/rconybea/xo-ratio
git clone https://github.com/rconybea/xo-unit

PREFIX=~/local  # ..or other desired installation prefix

Build and Install catch2 (assuming ubuntu here):

sudo apt-get install catch2  # on ubuntu, for example

Build and Install xo-cmake:

cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -B xo-cmake/.build -S xo-cmake
cmake --build xo-cmake/.build -j   # placeholder, no-op for now
cmake --install xo-cmake/.build

Build, Test and Install xo-indentlog:

cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -B xo-indentlog/.build -S xo-indentlog
cmake --build xo-indentlog/.build -j
cmake --build xo-indentlog/.build -- test   # run unit tests, cmake invokes ctest
(cd xo-indentlog/.build && ctest)           # or invoke ctest directly
cmake --install xo-indentlog/.build

Build and Install xo-randomgen (no unit tests yet):

cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -B xo-randomgen/.build -S xo-randomgen
cmake --build xo-randomgen/.build -j
cmake --install xo-randomgen/.build

Build, Test and Install xo-flatstring:

cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -B xo-flatstring/.build -S xo-flatstring
cmake --build xo-flatstring/.build -j
cmake --build xo-flatstring/.build -- test   # run unit tests, cmake invokes ctest
(cd xo-flatstring/.build && ctest)           # or invoke ctest directly
cmake --install xo-flatstring/.build

Build, Test and Install xo-ratio:

cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -B xo-ratio/.build -S xo-ratio
cmake --build xo-ratio/.build -j
cmake --build xo-ratio/.build -- test   # run unit tests, cmake invokes ctest
(cd xo-ratio/.build && ctest)           # or invoke ctest directly
cmake --install xo-ratio/.build

Build, Test and Install xo-unit:

cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -B xo-unit/.build -S xo-unit
cmake --build xo-unit/.build -j
cmake --build xo-unit/.build -- test   # run unit tests, cmake invokes ctest
(cd xo-unit/.build && ctest)           # or invoke ctest directly
cmake --install xo-unit/.build

Build Examples

To enable building example programs:

cd ~/proj/xo
cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -DXO_ENABLE_EXAMPLES=1 -B xo-unit/.build -S xo-unit

Run examples from the build directory:

~/proj/xo/xo-unit/.build/example/ex1/xo_unit_ex1
~/proj/xo/xo-unit/.build/example/ex2/xo_unit_ex2
# etc

Build and Install Documentation

xo-unit documentation has these additional dependencies:

doxygen annotation-driven inline documentation
sphinx documentation based on ReST files
sphinx-rtd-theme popular CSS theme for sphinx
breathe make doxygen-generated ingredients available from sphinx

Preamble (assuming ubuntu here):

sudo apt-get install doxygen
sudo apt-get install python3-sphinx
sudo apt-get install python3-sphinx-rtd-theme
sudo apt-get install python3-breathe

Build xo-unit docs

cd ~/proj/xo
cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -B xo-unit/.build
cmake --build xo-unit/.build -- docs
cmake --install xo-unit/.build   # if docs built,  installs to $PREFIX/share/doc/xo_unit/html

Supported compilers

developed with gcc 12.3.0 and gcc 13.2.0; github CI using gcc 11.4.0 (asof March 2024)