Installation¶
Au can be installed in multiple ways. First, we’ll help you decide which one is right for you. Then, we’ll provide full instructions for each option.
Broadly, you can either do a “full install” of the library, or you can package it into a single header file. For the latter approach, there are two options:
- Pre-built versions you can download right away.
- Custom versions with exactly the units you choose.
Choosing a method¶
You should consider several factors before you decide how to install the Au library, such as:
- Tradeoffs in setup time, unit selection, and flexibility.
- Whether you’re installing for production, or just trying it out.
- Your build system.
Here’s an overview of the tradeoffs involved.
Legend | Unsupported | Fair | Good | Best |
---|
Single File | Full Install | ||||
---|---|---|---|---|---|
Pre-built | Custom | bazel | CMake | conan, vcpkg, ... | |
Setup time | ~1 min | ~10 min | ~10 min | ~10 min | Not yet supported (use single-file instead for now) |
Unit selection | Base units only (or too many units) |
Any units desired | Any units desired, without needing "reinstall" | ||
Compile time cost | ~10 units | Very competitive up to a few dozen units | Each file only pays for the units it uses | ||
Flexibility |
Awkward: would need to download io.hhand/or testing.hhseparately, and modify their includes manually |
Include I/O, testing utilities, individual units as desired, on a per-file basis |
So, which should you use?
graph TD
Usage[What's your use case?]
SetupTime[Got 10 minutes for setup?]
BuildSystem[What's your build system?]
UsePreBuilt[Use pre-built single file]
UseCustom[Use custom single file]
UseFullInstall[Use full install]
Usage -->|Just playing around with Au| SetupTime
SetupTime -->|No! Just let me start!| UsePreBuilt
SetupTime -->|Sure| UseCustom
Usage -->|Ready to use in my project!| BuildSystem
BuildSystem -->|bazel| UseFullInstall
BuildSystem -->|CMake| UseFullInstall
BuildSystem -->|other| UseCustom
Installation instructions¶
Here are the instructions for each installation method we support.
Single file¶
The Au library can be packaged as a single header file, which you can include in your project just like any other header. This works with any build system!
To take this approach, obtain the single file by one of the methods described below. Then, put it
inside a third_party
folder (for example, as third_party/au.hh
). Now you’re up and running with
Au!
Every single-file package automatically includes the following features:
- Basic “unit container” types:
Quantity
,QuantityPoint
- Magnitude types and values, including constants for any integer such
as
mag<5280>()
. - All prefixes for SI (
kilo
,mega
, …) and informational (kibi
,mebi
, …) quantities. - Math functions, including unit-aware rounding and inverses, trigonometric functions, square roots, and so on.
- Bidirectional implicit conversion between
Quantity
types and any equivalent counterparts in thestd::chrono
library.
Here are the two ways to get a single-file packaging of the library.
Pre-built single file¶
Tip
This approach is mainly for playing with the library. It’s very fast to get up and running, but it’s not the best choice as the “production” installation of your library.
For a single-file approach, most users will be much better served by the next section, which explains how to customize it to get exactly the units you want.
We provide pre-generated single-file versions of the library, automatically generated from the latest commit in the repo:
au.hh
au_noio.hh
(Same as above, but with<iostream>
support stripped out)
These include very few units (to keep compile times short). However, combinations of these units should get you any other unit you’re likely to want. The units we include are:
- Every SI base unit (
seconds
,meters
,kilo(grams)
,amperes
,kelvins
,moles
,candelas
) - Base units for angles and information (
radians
,bits
) - A base dimensionless unit (
unos
)
Note
How do you go about constructing other units from these? By composing them. For example, you can make other coherent SI units like this:
Now you can call, say, newtons(10)
and get a quantity equivalent to 10 Newtons. You can also
scale a unit by multiplying by Magnitude objects. For example:
These will “work”, in the sense of producing correct results. But these ad hoc unit definitions are far less usable than fully defined units. Both the type names and the unit symbols will be needlessly complicated.
Again, we recommend following the directions in the next section to get exactly the units you care about.
Pre-built files with all units
We also provide pre-built files with every unit the library knows about.
We don’t advertise this option widely, because the library’s compile time slowdown is largely proportional to the number of units included in a translation unit. Thus, not only will this configuration be the slowest of all, but it will get increasingly slower as the library gets better over time (by supporting more and more units out of the box).
Therefore, these files are only for use cases where you don’t care about compile time. The primary example is the Compiler Explorer (“godbolt”).
If you don’t care about compile times, here are the files:
au_all_units.hh
au_all_units_noio.hh
(Same as above, but with<iostream>
support stripped out)
Custom single file¶
It’s easy to package the library in a custom single file with exactly the units you need. Here’s how:
-
Clone the repo. Go to the aurora-opensource/au repo, and follow the typical instructions.
- If you’re just a user of Au, not a contributor, this should be:
git clone https://github.com/aurora-opensource/au.git
- If you’re just a user of Au, not a contributor, this should be:
-
Run the script.
tools/bin/make-single-file --units meters seconds newtons > ~/au.hh
creates a file,~/au.hh
, which packages the entire library in a single file with these three units.- To see the full list of available units, search the
.hh
files in theau/units/
folder. For example,meters
will include the contents ofau/units/meters.hh
. - Provide the
--noio
flag if you prefer to avoid the expense of the<iostream>
library.
- To see the full list of available units, search the
Now you have a file, ~/au.hh
, which you can add to your third_party
folder.
Full library installation¶
bazel¶
-
Choose your Au version.
- This can be a tag, or a commit hash. Let’s take
0.3.4
as an example.
- This can be a tag, or a commit hash. Let’s take
-
Form the URL to the archive.
- For
0.3.4
, this would be:
- For
-
Compute your SHA256 hash.
- Follow the URL from the previous step to download the archive.
- Compute the SHA256 hash:
sha256sum au-0.3.4.tar.gz
- The first token that appears is the hash. Save it for the next step.
-
Add
http_archive
rule toWORKSPACE
.- Follow this pattern:
- In particular, here’s how to fill out the fields:
sha256
: Use the SHA256 hash you got from step 3.strip_prefix
: write"au-0.3.4"
, except use your ID from step 1 instead of0.3.4
.urls
: This should be a list, whose only entry is the URL you formed in step 2.
At this point, the Au library is installed, and you can use it in your project!
Here are the headers provided by each Au target. To use, add the “Dependency” to your deps
attribute, and include the appropriate files.
Dependency | Headers provided | Notes |
---|---|---|
@au//au |
"au/au.hh" "au/units/*.hh" |
Core library functionality. See all available units |
@au//au:io |
"au/io.hh" |
operator<< support |
@au//au:testing |
"au/testing.hh" |
Utilities for writing googletest tests Note: testonly = True |
CMake¶
There are two ways to include the Au library in your CMake project.
-
(Recommended) Use the
FetchContent
module to download the library directly from GitHub. -
Install the library to the system, and use
find_package
.
We recommend FetchContent
because each project can get the exact version of Au that they need, and
can update it independently of other projects. FetchContent
also means you don’t need to manually
clone the Au repo, or build and run the tests. On the other hand, if you want a single global
system-wide version of Au, then you can install it to the system, and simply use find_package
.
In either case, here are the main targets and include files provided by the Au library:
Target | Headers provided | Notes |
---|---|---|
Au::au |
"au/au.hh" "au/io.hh" "au/units/*.hh" |
Core library functionality. See all available units |
Au::testing |
"au/testing.hh" |
Utilities for writing googletest tests |
Note
These instructions are for adding Au to a project that uses CMake, not building Au itself using CMake.
Au is a bazel-first project, so most Au development would normally be done using bazel.
However, we do have instructions for doing this with CMake as well: see the find_package
tab
below.
Add the following to your CMakeLists.txt
file:
include(FetchContent)
FetchContent_Declare(
Au
GIT_REPOSITORY https://github.com/aurora-opensource/au
GIT_TAG "main" # Or a specific tag.
EXCLUDE_FROM_ALL
)
FetchContent_MakeAvailable(Au)
You should now be able to depend on Au targets, such as Au::au
or Au::testing
, and include
headers from them, such as #include "au/au.hh"
or #include "au/testing.hh"
.
Before you can use find_package
, you need to install the library to your system. This means
cloning the repo, building the library, running the tests, and installing it.
First, clone the repository.
If you want a specific release, check out the tag you want. Note that the first version of Au that supports CMake is 0.3.5.
Now, build and test the library. These commands will include both the explicit tests, and also several CMake-generated tests to make sure that the includes are set up correctly.
# CMake is a "meta build system", not a build system.
# This first command generates the actual build files.
cmake -S . -B cmake/build -DCMAKE_VERIFY_INTERFACE_HEADER_SETS=TRUE
# This command builds Au, checks include paths, and runs unit tests.
cmake \
--build cmake/build \
--target \
all \
all_verify_interface_header_sets \
test
If the tests pass, you can install the library to your system.
At this point, the Au
CMake library is installed to your system, and can be found via the
usual find_package
mechanism!