From cd1efb468c3fa627ecca1d787f4ba3fee21976ce Mon Sep 17 00:00:00 2001 From: Chip Hogg Date: Sun, 20 Oct 2024 14:43:46 -0400 Subject: [PATCH] Refresh installation instructions 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 | 91 +++++++++++++++++++++++-------------------------- 1 file changed, 43 insertions(+), 48 deletions(-) diff --git a/docs/install.md b/docs/install.md index 99f0cf9..87fefe3 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,67 +34,46 @@ 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. @@ -209,19 +190,19 @@ 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`**. @@ -229,20 +210,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 +326,17 @@ 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)