aboutsummaryrefslogtreecommitdiff
path: root/doc/book/src/development/devenv.md
diff options
context:
space:
mode:
authorQuentin Dufour <quentin@deuxfleurs.fr>2021-10-04 18:27:57 +0200
committerQuentin Dufour <quentin@deuxfleurs.fr>2021-10-19 16:56:07 +0200
commitdc017a0cab40cb2f33a01b420bb1b04038abb875 (patch)
tree239b6a9245b842a4daaceead93b71d8ddbeab498 /doc/book/src/development/devenv.md
parent1acf7e4c66aab0a0b5bcce8eb2965b35d587dd2a (diff)
downloadgarage-dc017a0cab40cb2f33a01b420bb1b04038abb875.tar.gz
garage-dc017a0cab40cb2f33a01b420bb1b04038abb875.zip
Build Garage with Nixfeature/static
Diffstat (limited to 'doc/book/src/development/devenv.md')
-rw-r--r--doc/book/src/development/devenv.md150
1 files changed, 139 insertions, 11 deletions
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.**