# Developer's guide

## Targeted rust version

All development targets `stable`.

## rust tool chain

Install `rust` as described [here](https://www.rust-lang.org/tools/install).

Then, install [rustfmt](https://github.com/rust-lang/rustfmt) and [clippy](https://github.com/rust-lang/rust-clippy), which are required to make sure that changes can pass CI tests (see below):

```sh
rustup component add rustfmt clippy
```

### Other useful tools

[tarpaulin](https://docs.rs/crate/cargo-tarpaulin/) for calculating test coverage:

```sh
cargo install cargo-tarpaulin
```


## Continuous integration (CI)

GitHub actions/work flows handle all CI:

* `rustfmt` checks code formatting
* `clippy` checks for code "lint".
* The library is built, and tests are run, against both rust `stable` and `beta`.

### More about clippy

`clippy` is a very opinionated code "linter".
Any changes must pass all `clippy` checks.
Some of these checks may seem stylistic, meaning that you are being asked to replace working code with a different implementation.
In these cases `clippy` is suggesting a more idiomatic approach to do what you are asking.
We accept `clippy`'s recommendations for two reasons.
First, it is best to respect language idioms  whenever possible ("don't force rust to act like C or C++").
Second, these recommendations have been useful in learning more about rust.

## Building the library

```sh
cargo build
```

### Building examples

```sh
cargo build --examples
```

### Release mode builds

Add `--release` to any of the above.
This flags adds optimizations and removes debugging symbols.

## Building the documentation

```sh
cargo doc
```

Then, point your browser at `target/doc/tskit/index.html`.

## Running tests

To run tests and doc tests:

```sh
cargo test
```

To test examples:

```sh
cargo test --examples
```

### Test coverage

Using `tarpaulin`:

```sh
cargo tarpaulin --exclude-files '*.c' --exclude-files '*.h' -o html
```

We exclude `*.c` and `*.h` because it is `tskit`'s job to manage the coverage of those files.

Some notes on what `tarpaulin` does:

* The coverage includes the test code itself, which is a bit annoying.
  In the future, we may move all tests to a separate directory and exclude them from the calculation.

## Running optimized examples

The default build is `debug`, which makes the examples slow.
To run `release` builds of examples:

```sh
cargo build --release --examples
```

The binaries will be in `target/release/examples/`.

## Tips and tricks

### Cleaning up the various builds

```sh
cargo clean
```

### Cleaning out the dependency database

```sh
rm -f Cargo.lock
```