From 945fc7758583b249b506d6e56e33142a99434876 Mon Sep 17 00:00:00 2001 From: Chip Hogg Date: Sun, 20 Oct 2024 14:55:31 -0400 Subject: [PATCH] Swap order of single-file/full-install sections --- docs/install.md | 214 ++++++++++++++++++++++++------------------------ 1 file changed, 107 insertions(+), 107 deletions(-) diff --git a/docs/install.md b/docs/install.md index 87fefe3..588e1d1 100644 --- a/docs/install.md +++ b/docs/install.md @@ -78,113 +78,6 @@ Here's an overview of the tradeoffs involved. 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 @@ -340,3 +233,110 @@ Each package manager contains setup instructions on its page for Au. Here are t - **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.