diff options
Diffstat (limited to 'doc/book/cookbook/from-source.md')
| -rw-r--r-- | doc/book/cookbook/from-source.md | 75 |
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 | |