# Development setup

## Linux

### 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


### Manual install

Manually installing the system dependencies is not recommended as the package
versions you install might be incompatible with this project. Using the Nix
package manager as described above ensures that the proper version of each
required system dependencies is made available during your development process.
You'll thus avoid the classical "but it works on my machine" type of issue.

If you really want / need to
do that, you can manually install the software dependencies listed in
[`flake.nix`][nix-flake] using your distro package manager.


[nix-flake]: ../flake.nix

## Initial setup

Prior to run the example, some initial setup needs to be taken care of.

### Step 1: initializing the RSA keypair secret

Run the following command:

```bash
$ just init
# 2 new files should have been created:
# -> './rsa_private.pem'
# -> './rsa_public.pem'
```

### Step 2: provisioning the public part of the RSA keypair

You'll need to manually provision your device on fundamentum platform.

TODO: Streamline this process.

### Step 3: Start

All these variables can be found in fundamentum cloud.

```bash
cargo run -- --project-id {PROJECT_ID} --region-id {REGION_ID} --registry-id {REGISTRY_ID} --serial {SERIAL_NUMBER} --private-key {PATH_TO_PRIVATE_KEY} --endpoint {CLOUD_MQTT_ENDPOINT}
```

## 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.