Skip to content

Commit

Permalink
Refresh installation instructions
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
chiphogg committed Oct 20, 2024
1 parent fb03848 commit cd1efb4
Showing 1 changed file with 43 additions and 48 deletions.
91 changes: 43 additions & 48 deletions docs/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -32,67 +34,46 @@ Here's an overview of the tradeoffs involved.
<table>
<tr>
<th rowspan=2></th>
<th colspan=2>Full Install</th>
<th colspan=2>Single File</th>
<th colspan=3>Full Install</th>
</tr>
<tr>
<td>bazel, CMake, conan, vcpkg</td>
<td>Other build systems</td>
<td>Pre-built</td>
<td>Custom</td>
<td>bazel</td>
<td>CMake</td>
<td>conan, vcpkg, ...</td>
</tr>
<tr>
<td>Setup time</td>
<td class="best">~1 min</td>
<td class="good">~10 min</td>
<td class="good">~10 min</td>
<td class="good">~10 min</td>
<td class="poor">Not <i>yet</i> supported<br>(use <b>single-file</b> instead for now)</td>
<td class="good">Fast (a few minutes)</td>
<td rowspan="4" class="poor">Full Install unsupported (use single-file instead)</td>
<td class="best">Instant</td>
<td class="good">Fast (a few minutes)</td>
</tr>
<tr>
<td>Unit selection</td>
<td class="best">Any units desired, <i>without</i> needing "reinstall"</td>
<td class="fair">Base units only<br>(or too many units)</td>
<td class="good">Any units desired</td>
<td colspan=3 class="best">Any units desired, <i>without</i> needing "reinstall"</td>
</tr>
<tr>
<td>Compile time cost</td>
<td class="good">~10 units</td>
<td class="best"><i>Each file</i> only pays for the units it uses</td>
<td class="good">Cost of core, plus ~10 units</td>
<td class="good">Very competitive up to a few dozen units</td>
<td colspan=3 class="best"><i>Each file</i> only pays for the units it uses</td>
</tr>
<tr>
<td>Flexibility</td>
<td class="best">
Include I/O, testing utilities, individual units as desired, on a per-file basis
</td>
<td colspan=2 class="fair">
Awkward: would need to download <pre>io.hh</pre> and/or <pre>testing.hh</pre> separately, and
modify their includes manually
</td>
<td colspan=3 class="best">
Include I/O, testing utilities, individual units as desired, on a per-file basis
</td>
</tr>
</table>

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.
Expand Down Expand Up @@ -209,40 +190,40 @@ Now you have a file, `~/au.hh`, which you can add to your `third_party` folder.
#### 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`**.
- Follow this pattern:
```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 |
|------------|------------------|-------|
Expand Down Expand Up @@ -345,3 +326,17 @@ In either case, here are the main targets and include files provided by the Au l
```

<script src="../assets/hrh4.js" async=false defer=false></script>

#### 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)

0 comments on commit cd1efb4

Please sign in to comment.