From 1c0ba930b8d6aa5d97e6942852240861e6ab9bed Mon Sep 17 00:00:00 2001 From: Alex Date: Mon, 7 Feb 2022 11:51:12 +0100 Subject: Reorganize documentation for new website (#213) This PR should be merged after the new website is deployed. - [x] Rename files - [x] Add front matter section to all `.md` files in the book (necessary for Zola) - [x] Change all internal links to use Zola's linking system that checks broken links - [x] Some updates to documentation contents and organization Co-authored-by: Alex Auvolat Reviewed-on: https://git.deuxfleurs.fr/Deuxfleurs/garage/pulls/213 Co-authored-by: Alex Co-committed-by: Alex --- doc/book/src/development/devenv.md | 145 ------------------ doc/book/src/development/index.md | 14 -- doc/book/src/development/miscellaneous_notes.md | 98 ------------ doc/book/src/development/release_process.md | 195 ------------------------ doc/book/src/development/scripts.md | 113 -------------- 5 files changed, 565 deletions(-) delete mode 100644 doc/book/src/development/devenv.md delete mode 100644 doc/book/src/development/index.md delete mode 100644 doc/book/src/development/miscellaneous_notes.md delete mode 100644 doc/book/src/development/release_process.md delete mode 100644 doc/book/src/development/scripts.md (limited to 'doc/book/src/development') diff --git a/doc/book/src/development/devenv.md b/doc/book/src/development/devenv.md deleted file mode 100644 index 78affa48..00000000 --- a/doc/book/src/development/devenv.md +++ /dev/null @@ -1,145 +0,0 @@ -# Setup your development environment - -Depending on your tastes, you can bootstrap your development environment in a traditional Rust way or through Nix. - -## The Nix way - -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/index.md b/doc/book/src/development/index.md deleted file mode 100644 index 09147ece..00000000 --- a/doc/book/src/development/index.md +++ /dev/null @@ -1,14 +0,0 @@ -# Development - -Now that you are a Garage expert, you want to enhance it, you are in the right place! -We discuss here how to hack on Garage, how we manage its development, etc. - -## Rust API (docs.rs) -If you encounter a specific bug in Garage or plan to patch it, you may jump directly to the source code's documentation! - - - [garage\_api](https://docs.rs/garage_api/latest/garage_api/) - contains the S3 standard API endpoint - - [garage\_model](https://docs.rs/garage_model/latest/garage_model/) - contains Garage's model built on the table abstraction - - [garage\_rpc](https://docs.rs/garage_rpc/latest/garage_rpc/) - contains Garage's federation protocol - - [garage\_table](https://docs.rs/garage_table/latest/garage_table/) - contains core Garage's CRDT datatypes - - [garage\_util](https://docs.rs/garage_util/latest/garage_util/) - contains garage helpers - - [garage\_web](https://docs.rs/garage_web/latest/garage_web/) - contains the S3 website endpoint diff --git a/doc/book/src/development/miscellaneous_notes.md b/doc/book/src/development/miscellaneous_notes.md deleted file mode 100644 index 1adc5744..00000000 --- a/doc/book/src/development/miscellaneous_notes.md +++ /dev/null @@ -1,98 +0,0 @@ -# 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. - -```bash -cat > $HOME/.awsrc <