Finish writing about Garage features, and fix from-source instructions

1 files changed, 47 insertions, 28 deletions

diff --git a/doc/book/cookbook/from-source.md b/doc/book/cookbook/from-source.md
index 2b93da47..bacf93ab 100644
--- a/doc/book/cookbook/from-source.md
+++ b/doc/book/cookbook/from-source.md
@@ -20,57 +20,76 @@ sudo apt-get update
 sudo apt-get install build-essential
 ```
 
-## Using source from the Gitea repository (recommended)
+## Building from source from the Gitea repository
 
 The primary location for Garage's source code is the
-[Gitea repository](https://git.deuxfleurs.fr/Deuxfleurs/garage).
+[Gitea repository](https://git.deuxfleurs.fr/Deuxfleurs/garage),
+which contains all of the released versions as well as the code
+for the developpement of the next version.
 
-Clone the repository and build Garage with the following commands:
+Clone the repository and enter it as follows:
 
 ```bash
 git clone https://git.deuxfleurs.fr/Deuxfleurs/garage.git
 cd garage
-cargo build
 ```
 
-Be careful, as this will make a debug build of Garage, which will be extremely slow!
-To make a release build, invoke `cargo build --release` (this takes much longer).
+If you wish to build a specific version of Garage, check out the corresponding tag. For instance:
 
-The binaries built this way are found in `target/{debug,release}/garage`.
+```bash
+git tag  				# List available tags
+git checkout v0.8.0		# Change v0.8.0 with the version you wish to build
+```
 
-## Using source from `crates.io`
+Otherwise you will be building a developpement build from the `main` branch
+that includes all of the changes to be released in the next version.
+Be careful that such a build might be unstable or contain bugs,
+and could be incompatible with nodes that run stable versions of Garage.
 
-Garage's source code is published on `crates.io`, Rust's official package repository.
-This means you can simply ask `cargo` to download and build this source code for you:
+Finally, build Garage with the following command:
 
 ```bash
-cargo install garage
+cargo build --release
 ```
 
-That's all, `garage` should be in `$HOME/.cargo/bin`.
-
-You can add this folder to your `$PATH` or copy the binary somewhere else on your system.
-For instance:
+The binary built this way can now be found in `target/release/garage`.
+You may simply copy this binary to somewhere in your `$PATH` in order to
+have the `garage` command available in your shell, for instance:
 
 ```bash
-sudo cp $HOME/.cargo/bin/garage /usr/local/bin/garage
+sudo cp target/release/garage /usr/local/bin/garage
 ```
 
+If you are planning to develop Garage,
+you might be interested in producing debug builds, which compile faster but run slower:
+this can be done by removing the `--release` flag, and the resulting build can then
+be found in `target/debug/garage`.
 
-## Selecting features to activate in your build
+## List of available Cargo feature flags
 
-Garage supports a number of compilation options in the form of Cargo features,
+Garage supports a number of compilation options in the form of Cargo feature flags,
 which can be used to provide builds adapted to your system and your use case.
-The following features are available:
-
-| Feature | Enabled | Description |
-| ------- | ------- | ----------- |
-| `bundled-libs` | BY DEFAULT | Use bundled version of sqlite3, zstd, lmdb and libsodium |
-| `system-libs` | optional | Use system version of sqlite3, zstd, lmdb and libsodium if available (exclusive with `bundled-libs`, build using `cargo build --no-default-features --features system-libs`) |
-| `k2v` | optional | Enable the experimental K2V API (if used, all nodes on your Garage cluster must have it enabled as well) |
-| `kubernetes-discovery` | optional | Enable automatic registration and discovery of cluster nodes through the Kubernetes API |
-| `metrics` | BY DEFAULT | Enable collection of metrics in Prometheus format on the admin API |
+To produce a build with a given set of features, invoke the `cargo build` command
+as follows:
+
+```bash
+# This will build the default feature set plus feature1, feature2 and feature3
+cargo build --release --features feature1,feature2,feature3
+# This will build ONLY feature1, feature2 and feature3
+cargo build --release --no-default-features \
+            --features feature1,feature2,feature3
+```
+
+The following feature flags are available in v0.8.0:
+
+| Feature flag | Enabled | Description |
+| ------------ | ------- | ----------- |
+| `bundled-libs` | *by default* | Use bundled version of sqlite3, zstd, lmdb and libsodium |
+| `system-libs` | optional | Use system version of sqlite3, zstd, lmdb and libsodium<br>if available (exclusive with `bundled-libs`, build using<br>`cargo build --no-default-features --features system-libs`) |
+| `k2v` | optional | Enable the experimental K2V API (if used, all nodes on your<br>Garage cluster must have it enabled as well) |
+| `kubernetes-discovery` | optional | Enable automatic registration and discovery<br>of cluster nodes through the Kubernetes API |
+| `metrics` | *by default* | Enable collection of metrics in Prometheus format on the admin API |
 | `telemetry-otlp` | optional | Enable collection of execution traces using OpenTelemetry |
-| `sled` | BY DEFAULT | Enable using Sled to store Garage's metadata |
+| `sled` | *by default* | Enable using Sled to store Garage's metadata |
 | `lmdb` | optional | Enable using LMDB to store Garage's metadata |
 | `sqlite` | optional | Enable using Sqlite3 to store Garage's metadata |