From 06b074cd972234fca5b9abe429a7299e9c95af93 Mon Sep 17 00:00:00 2001 From: Chip Hogg Date: Mon, 21 Oct 2024 10:29:21 -0400 Subject: [PATCH] Refresh installation instructions (#302) The old flow of the page dates from the first open source release, when only bazel was fully supported, and we provided the single-file packaging as the "lowest common denominator" fallback that worked with everybody. This summer, we added official CMake support, and just last week, the community also added support for both conan and vcpkg. This radically changes and simplifies the recommended installation approach: now "full install" is the right choice for almost everyone! Accordingly, it's time to refresh our instructions. - Make up-front guidance simpler and more direct - Rearrange the table: put Full Install first; unify Full Install columns; clean up and explain some text - Remove decision flowchart: things are much simpler now, and we don't really need it - Refresh the bazel instructions to mention 0.3.5 (might as well) - Add links and instructions for installing with package managers - Move the single-file section _after_ the full install one I used "checkpoint commits" for this PR, so this last change is in a separate "pure-move" commit within the PR, to make this easier to review. The reviewer can also run `au-docs-serve` and do A/B comparison between two tabs: - https://aurora-opensource.github.io/au/main/install/ - http://127.0.0.1:8000/au/install/ Fixes #301. --- docs/install.md | 305 ++++++++++++++++++++++++------------------------ 1 file changed, 150 insertions(+), 155 deletions(-) diff --git a/docs/install.md b/docs/install.md index 99f0cf9..588e1d1 100644 --- a/docs/install.md +++ b/docs/install.md @@ -11,11 +11,13 @@ header file. For the latter approach, there are two options: ## Choosing a method -You should consider several factors before you decide how to install the Au library, such as: +These days, Au supports both bazel and CMake build systems natively. We also have community support +for the most popular C++ package managers, conan and vcpkg. Setup via any of these methods is +pretty quick, so **just doing a full install is usually best**. -- Tradeoffs in setup time, unit selection, and flexibility. -- Whether you're installing for production, or just trying it out. -- Your build system. +The main reason to consider a single-file approach is if you're not using any of these build +systems: clearly, a single file works with any build system imaginable. The _pre-built_ single file +packages are also the quickest way to start playing with the library. Here's an overview of the tradeoffs involved. @@ -32,196 +34,68 @@ Here's an overview of the tradeoffs involved. + - + + - - - - - - - - + + + + + - - + + - + -
Full Install Single FileFull Install
bazel, CMake, conan, vcpkgOther build systems Pre-built CustombazelCMakeconan, vcpkg, ...
Setup time~1 min~10 min~10 min~10 minNot yet supported
(use single-file instead for now)		Fast (a few minutes)Full Install unsupported (use single-file instead)InstantFast (a few minutes)
Unit selectionAny units desired, without needing "reinstall" Base units only
(or too many units)		 Any units desiredAny units desired, without needing "reinstall"
Compile time cost~10 unitsEach file only pays for the units it usesCost of core, plus ~10 units Very competitive up to a few dozen unitsEach file only pays for the units it uses
Flexibility + Include I/O, testing utilities, individual units as desired, on a per-file basis + Awkward: would need to download 
io.hh
and/or 
testing.hh
separately, and modify their includes manually 		- Include I/O, testing utilities, individual units as desired, on a per-file basis -
-So, which should _you_ use? - -``` mermaid -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 {#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`](./reference/quantity.md), - [`QuantityPoint`](./reference/quantity_point.md) -- [Magnitude](./reference/magnitude.md) types and values, including constants for any integer such - as `mag<5280>()`. -- All [prefixes](./reference/prefix.md) for SI (`kilo`, `mega`, ...) and informational (`kibi`, - `mebi`, ...) quantities. -- [Math functions](./reference/math.md), including unit-aware rounding and inverses, trigonometric - functions, square roots, and so on. -- _Bidirectional implicit conversion_ between `Quantity` types and any [equivalent counterparts in the - `std::chrono` library](./reference/corresponding_quantity.md#chrono-duration). - -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.hh) -- [`au_noio.hh`](./au_noio.hh) - (Same as above, but with `` 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](https://www.nist.gov/pml/owm/metric-si/si-units) like - this: - - ```cpp - constexpr auto newtons = kilo(gram) * meters / squared(second); - ``` - - 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: - - ```cpp - constexpr auto degrees = radians * Magnitude{} / mag<180>(); - ``` - - These will "work", in the sense of producing correct results. But these ad hoc unit definitions - are far less usable than [fully defined units](./howto/new-units.md). 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. - -??? warning "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")](https://godbolt.org/z/KrvfhP4M3). - - **If you don't care about compile times**, here are the files: - - - [`au_all_units.hh`](./au_all_units.hh) - - [`au_all_units_noio.hh`](./au_all_units_noio.hh) - (Same as above, but with `` 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: - -1. **Clone the repo**. Go to the [aurora-opensource/au](https://github.com/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` - -2. **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 the `au/units/` folder. For - example, `meters` will include the contents of `au/units/meters.hh`. - - Provide the `--noio` flag if you prefer to avoid the expense of the `` library. - -Now you have a file, `~/au.hh`, which you can add to your `third_party` folder. - ### Full library installation {#full} #### bazel 1. **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 `0.3.5` as an example. 2. **Form the URL to the archive**. - - For `0.3.4`, this would be: + - For `0.3.5`, this would be: ``` - https://github.com/aurora-opensource/au/releases/download/0.3.4/au-0.3.4.tar.gz + https://github.com/aurora-opensource/au/releases/download/0.3.5/au-0.3.5.tar.gz NOTE: Your au version ID goes HERE ^^^^^ ^^^^^ ``` 3. **Compute your SHA256 hash**. 1. Follow the URL from the previous step to download the archive. - 2. Compute the SHA256 hash: `sha256sum au-0.3.4.tar.gz` + 2. Compute the SHA256 hash: `sha256sum au-0.3.5.tar.gz` 3. The first token that appears is the hash. Save it for the next step. 4. **Add `http_archive` rule to `WORKSPACE`**. @@ -229,20 +103,20 @@ Now you have a file, `~/au.hh`, which you can add to your `third_party` folder. ```python http_archive( name = "au", - sha256 = "dd0f97e2720f02e3c5531a912c21b8eb889fcb984bac5f5f8b0f00e16b839216", - strip_prefix = "au-0.3.4", - urls = ["https://github.com/aurora-opensource/au/releases/download/0.3.4/au-0.3.4.tar.gz"], + sha256 = "7ec826dc42968dc1633de56e4f9d06e70de73e820d2ac4788e8453343a622c9b", + strip_prefix = "au-0.3.5", + urls = ["https://github.com/aurora-opensource/au/releases/download/0.3.5/au-0.3.5.tar.gz"], ) ``` - 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 of `0.3.4`. + - `strip_prefix`: write `"au-0.3.5"`, except use your ID from step 1 instead of `0.3.5`. - `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. +Here are the headers provided by each Au target. To use, add the entry from the "Dependency" column +to your `deps` attribute, and include the appropriate files. | Dependency | Headers provided | Notes | |------------|------------------|-------| @@ -345,3 +219,124 @@ In either case, here are the main targets and include files provided by the Au l ``` + +#### Package managers (conan, vcpkg) + +If you're using these in your project, we assume you already know how to add new libraries. These +methods have "community support", which means: + +- The recipes are added and maintained by external users +- Au's maintainers will provide our _best effort_ to respond to issues, but we'll need to rely on + users of these package managers to help us reproduce and understand them + +Each package manager contains setup instructions on its page for Au. Here are the packages: + +- **Conan:** [au](https://conan.io/center/recipes/au) +- **vcpkg:** [aurora-au](https://vcpkg.link/ports/aurora-au) + +### Single file {#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`](./reference/quantity.md), + [`QuantityPoint`](./reference/quantity_point.md) +- [Magnitude](./reference/magnitude.md) types and values, including constants for any integer such + as `mag<5280>()`. +- All [prefixes](./reference/prefix.md) for SI (`kilo`, `mega`, ...) and informational (`kibi`, + `mebi`, ...) quantities. +- [Math functions](./reference/math.md), including unit-aware rounding and inverses, trigonometric + functions, square roots, and so on. +- _Bidirectional implicit conversion_ between `Quantity` types and any [equivalent counterparts in the + `std::chrono` library](./reference/corresponding_quantity.md#chrono-duration). + +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.hh) +- [`au_noio.hh`](./au_noio.hh) + (Same as above, but with `` 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](https://www.nist.gov/pml/owm/metric-si/si-units) like + this: + + ```cpp + constexpr auto newtons = kilo(gram) * meters / squared(second); + ``` + + 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: + + ```cpp + constexpr auto degrees = radians * Magnitude{} / mag<180>(); + ``` + + These will "work", in the sense of producing correct results. But these ad hoc unit definitions + are far less usable than [fully defined units](./howto/new-units.md). 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. + +??? warning "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")](https://godbolt.org/z/KrvfhP4M3). + + **If you don't care about compile times**, here are the files: + + - [`au_all_units.hh`](./au_all_units.hh) + - [`au_all_units_noio.hh`](./au_all_units_noio.hh) + (Same as above, but with `` 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: + +1. **Clone the repo**. Go to the [aurora-opensource/au](https://github.com/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` + +2. **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 the `au/units/` folder. For + example, `meters` will include the contents of `au/units/meters.hh`. + - Provide the `--noio` flag if you prefer to avoid the expense of the `` library. + +Now you have a file, `~/au.hh`, which you can add to your `third_party` folder.