From dc017a0cab40cb2f33a01b420bb1b04038abb875 Mon Sep 17 00:00:00 2001 From: Quentin Dufour Date: Mon, 4 Oct 2021 18:27:57 +0200 Subject: Build Garage with Nix --- doc/book/src/SUMMARY.md | 3 +- doc/book/src/development/devenv.md | 150 +++++++++++++++++-- doc/book/src/development/miscellaneous_notes.md | 134 +++++++++++++++++ doc/book/src/development/release_process.md | 184 ++++++++++++++++++++++++ doc/book/src/development/scripts.md | 113 +++++++++++++++ 5 files changed, 572 insertions(+), 12 deletions(-) create mode 100644 doc/book/src/development/miscellaneous_notes.md create mode 100644 doc/book/src/development/release_process.md create mode 100644 doc/book/src/development/scripts.md (limited to 'doc/book') diff --git a/doc/book/src/SUMMARY.md b/doc/book/src/SUMMARY.md index 9447c3b2..264714b1 100644 --- a/doc/book/src/SUMMARY.md +++ b/doc/book/src/SUMMARY.md @@ -25,7 +25,8 @@ - [Development](./development/index.md) - [Setup your environment](./development/devenv.md) - - [Your first contribution]() + - [Development scripts](./development/scripts.md) + - [Release process](./development/release_process.md) - [Working Documents](./working_documents/index.md) - [Load Balancing Data](./working_documents/load_balancing.md) diff --git a/doc/book/src/development/devenv.md b/doc/book/src/development/devenv.md index 6cb7c554..78affa48 100644 --- a/doc/book/src/development/devenv.md +++ b/doc/book/src/development/devenv.md @@ -1,17 +1,145 @@ # Setup your development environment -We propose the following quickstart to setup a full dev. environment as quickly as possible: +Depending on your tastes, you can bootstrap your development environment in a traditional Rust way or through Nix. - 1. Setup a rust/cargo environment. eg. `dnf install rust cargo` - 2. Install awscli v2 by following the guide [here](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html). - 3. Run `cargo build` to build the project - 4. Run `./script/dev-cluster.sh` to launch a test cluster (feel free to read the script) - 5. Run `./script/dev-configure.sh` to configure your test cluster with default values (same datacenter, 100 tokens) - 6. Run `./script/dev-bucket.sh` to create a bucket named `eprouvette` and an API key that will be stored in `/tmp/garage.s3` - 7. Run `source ./script/dev-env-aws.sh` to configure your CLI environment - 8. You can use `garage` to manage the cluster. Try `garage --help`. - 9. You can use the `awsgrg` alias to add, remove, and delete files. Try `awsgrg help`, `awsgrg cp /proc/cpuinfo s3://eprouvette/cpuinfo.txt`, or `awsgrg ls s3://eprouvette`. `awsgrg` is a wrapper on the `aws s3` command pre-configured with the previously generated API key (the one in `/tmp/garage.s3`) and localhost as the endpoint. +## The Nix way -Now you should be ready to start hacking on garage! +Nix is a generic package manager we use to precisely define our development environment. +Instructions on how to install it are given on their [Download page](https://nixos.org/download.html). +Check that your installation is working by running the following commands: +``` +nix-shell --version +nix-build --version +nix-env --version +``` + +Now, you can clone our git repository (run `nix-env -iA git` if you do not have git yet): + +```bash +git clone https://git.deuxfleurs.fr/Deuxfleurs/garage +cd garage +``` + +*Optionnaly, you can use our nix.conf file to speed up compilations:* + +```bash +sudo mkdir -p /etc/nix +sudo cp nix/nix.conf /etc/nix/nix.conf +sudo killall nix-daemon +``` + +Now you can enter our nix-shell, all the required packages will be downloaded but they will not pollute your environment outside of the shell: + +```bash +nix-shell +``` + +You can use the traditionnal Rust development workflow: + +```bash +cargo build # compile the project +cargo run # execute the project +cargo test # run the tests +cargo fmt # format the project, run it before any commit! +cargo clippy # run the linter, run it before any commit! +``` + +You can build the project with Nix by running: + +```bash +nix-build +``` + +You can parallelize the build (if you use our nix.conf file, it is already automatically done). +To use all your cores when building a derivation use `-j`, and to build multiple derivations at once use `--max-jobs`. +The special value `auto` will be replaced by the number of cores of your computer. +An example: + +```bash +nix-build -j $(nproc) --max-jobs auto +``` + +Our build has multiple parameters you might want to set: + - `release` build with release optimisations instead of debug + - `target allows` for cross compilation + - `compileMode` can be set to test or bench to build a unit test runner + - `git_version` to inject the hash to display when running `garage stats` + +An example: + +```bash +nix-build \ + --arg release true \ + --argstr target x86_64-unknown-linux-musl \ + --argstr compileMode build \ + --git_version $(git rev-parse HEAD) +``` + +*The result is located in `result/bin`. You can pass arguments to cross compile: check `.drone.yml` for examples.* + +If you modify a `Cargo.toml` or regenerate any `Cargo.lock`, you must run `cargo2nix`: + +``` +cargo2nix -f +``` + +Many tools like rclone, `mc` (minio-client), or `aws` (awscliv2) will be available in your environment and will be useful to test Garage. + +**This is the recommended method.** + +## The Rust way + +You need a Rust distribution installed on your computer. +The most simple way is to install it from [rustup](https://rustup.rs). +Please avoid using your package manager to install Rust as some tools might be outdated or missing. + +Now, check your Rust distribution works by running the following commands: + +```bash +rustc --version +cargo --version +rustfmt --version +clippy-driver --version +``` + +Now, you need to clone our git repository ([how to install git](https://git-scm.com/downloads)): + +```bash +git clone https://git.deuxfleurs.fr/Deuxfleurs/garage +cd garage +``` + +You can now use the following commands: + +```bash +cargo build # compile the project +cargo run # execute the project +cargo test # run the tests +cargo fmt # format the project, run it before any commit! +cargo clippy # run the linter, run it before any commit! +``` + +This is specific to our project, but you will need one last tool, `cargo2nix`. +To install it, run: + +```bash +cargo install --git https://github.com/superboum/cargo2nix --branch main cargo2nix +``` + +You must use it every time you modify a `Cargo.toml` or regenerate a `Cargo.lock` file as follow: + +```bash +cargo build # Rebuild Cargo.lock if needed +cargo2nix -f +``` + +It will output a `Cargo.nix` file which is a specific `Cargo.lock` file dedicated to Nix that is required by our CI +which means you must include it in your commits. + +Later, to use our scripts and integration tests, you might need additional tools. +These tools are listed at the end of the `shell.nix` package in the `nativeBuildInputs` part. +It is up to you to find a way to install the ones you need on your computer. + +**A global drawback of this method is that it is up to you to adapt your environment to the one defined in the Nix files.** diff --git a/doc/book/src/development/miscellaneous_notes.md b/doc/book/src/development/miscellaneous_notes.md new file mode 100644 index 00000000..c259cba1 --- /dev/null +++ b/doc/book/src/development/miscellaneous_notes.md @@ -0,0 +1,134 @@ +# Miscellaneous Notes + +## Quirks about cargo2nix/rust in Nix + +If you use submodules in your crate (like `crdt` and `replication` in `garage_table`), you must list them in `default.nix` + +The Windows target does not work. it might be solvable through [overrides](https://github.com/cargo2nix/cargo2nix/blob/master/overlay/overrides.nix). Indeed, we pass `x86_64-pc-windows-gnu` but mingw need `x86_64-w64-mingw32` + +We have a simple [PR on cargo2nix](https://github.com/cargo2nix/cargo2nix/pull/201) that fixes critical bugs but the project does not seem very active currently. We must use [my patched version of cargo2nix](https://github.com/superboum/cargo2nix) to enable i686 and armv6l compilation. We might need to contribute to cargo2nix in the future. + + +## Nix + +Nix has no armv7 + musl toolchains but armv7l is backward compatible with armv6l. + +Signing keys are generated with: + +``` +nix-store --generate-binary-cache-key nix.web.deuxfleurs.fr cache-priv-key.pem cache-pub-key.pem +``` + +We copy the secret key in our nix folder: + +``` +cp cache-priv-key.pem /etc/nix/signing-key.sec +``` + +Manually sign + +We can sign the whole store with: + +``` +nix sign-paths --all -k /etc/nix/signing-key.sec +``` + +Or simply the current package and its dependencies with: + +``` +nix sign-paths --recursive -k /etc/nix/signing-key.sec +``` + +Setting a key in `nix.conf` will do the signature at build time automatically without additional commands, edit the `nix.conf` of your builder: + +```toml +secret-key-files = /etc/nix/signing-key.sec +max-jobs = auto +cores = 8 +``` + +Now you are ready to build your packages: + +```bash +cat > $HOME/.awsrc <