# Development setup

## Linux

### Manual install

 -  `rustup`: see [install Rust](https://www.rust-lang.org/tools/install)
 -  `cargo-readme`: install with `cargo install cargo-readme`
 -  Install the following packages on your distro:
    -  `coreutils`
    -  `diffutils`
    -  `gcc`
    -  `just`
    -  `openssl`
    -  `protobuf`
    -  `pkg-config`
    -  `bash`
 -  Optional:
    -  `docker` in case you need to debug issues with the CI's container.

### Using `nix`

In case you want to use `nix`, it is possible to get all of the above system
dependencies automatically installed in your *developer environment* sandbox
without polluting your system.

 1. [Install `nix`](https://nixos.org/download).
 2. Enable flakes support either [temporarily][tempflakes] or [permanently][permflakes].
 3. Invoke `$ nix develop` from a terminal, at the root of this repository.

     -  All required commands should now be available from your terminal.
     -  *Pro tip*: Launch your editor from this terminal session (e.g.: `$
        code`). This will ensure that you editor and all of its extension have
        access to the required tools.
     -  *Pro tip*: It is even possible to skip the `nix develop` command if you
        [install `direnv`](https://direnv.net/#getting-started) and
        [extend it with `nix-direnv`](https://github.com/nix-community/nix-direnv#installation).
        We will however leave this as an exercise for the reader.

[tempflakes]: https://nixos.wiki/wiki/Flakes#Enable_flakes_temporarily
[permflakes]: https://nixos.wiki/wiki/Flakes#Enable_flakes_permanently_in_NixOS

## Generating documentation for this package

It is possible to generate all documentation by running:

```bash
$ just doc
# ..
```

### Package

To generate only the package documentation (i.e.: without its dependencies),
run:

```bash
$ just doc-package-only
# ..
```

### Readme

The `README.md` file for this project is generated from the crate's `lib.rs`
comment.

To only re-generate the readme file, run:

```bash
$ just doc-readme
# ..
```

Note that running `just check` will also validate that the `README.md` file is
up to date with the package sources and fail if not.

Please make sure to always commit the resulting `README.md` file to version
control.