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)