Development¶

Setup for Building¶

just >= 1.46 is used as a command runner, also see just installation instruction for installation instructions. Some Linux distributions and FreeBSD tend to ship very outdated versions of just.

Next, obtain Rust, see install Rust for further details.

The project uses cross for building, which requires a container runtime, either docker or podman. Once installed, just build {target} and just release {target} can be used for debug or release builds.

upx is required for compressed Linux binaries.

Local Building on Linux¶

Alternatively, one can also build locally without using cross. Production releases on Linux link against musl. For this purpose, a special compiler target must be installed:

rustup target add x86_64-unknown-linux-musl

A matching x86_64 GCC wrapper for linking against musl must be installed in addition via:

sudo apt install musl-tools

Local Building on FreeBSD¶

No extra requirements.

Setup for Testing¶

Tests run in isolated virtual machines managed by vagrant for both Linux and FreeBSD tests. On Debian/Ubuntu/Mint systems:

sudo apt install vagrant virtualbox`

Virtual machines with Linux and FreeBSD guests can then be provisioned by running:

just setup linux
just setup freebsd

This will create 4 VMs, two nodes running Linux plus two nodes running FreeBSD.

VMs can be controlled through a number of convenience wrappers: just reset {platform} (halt, reset to initial state, boot) and just halt {platform} (simply shut down) are probably the most important ones. {platform} can be either linux or freebsd.

Setup for Checking Feature Flags¶

Unexpected combinations of feature flags are known to break applications if not treated carefully. This project uses cargo-hack to check if all possible / allowed feature permutations actually result in compiled code. Once installed, it can be triggered as follows:

just test-features

Setup for Detailed Linting¶

This project aspires to pass tests by clippy. Once installed, it can be triggered as follows:

just clippy

Setup for Linting the Test Suite¶

Python should be >= 3.12. For system-Python on recent Debian/Ubuntu/Mint system, the following should do:

sudo apt install python3 python3-dev python3-venv python3-pip

Set up the Python portion of the testing tools in a dedicated Python virtual environment:

python3 -m venv env
source env/bin/activate
pip install -vU pip setuptools
pip install -vr tests/requirements.txt

Alternatively, conda can also be used, see miniforge.

Building the Documentation¶

Assuming the previously created Python virtual environment, the required dependencies can be installed as follows:

pip install -vr docs/requirements.txt

Then, the documentation can be build as follows:

just clean-docs
just docs-build

The built docs are located in docs/build.

Development Commands¶

There two types of tests. First, a test suite using pytest, testing through the CLI of abgleich. This is where most tests happen, done through tests on virtual machines. Second, there is tests contained in the Rust-code tested through cargo, and feature-build tests.

Testing the CLI¶

Clean up stuff:

just clean-build  # all build relicts
just reset linux  # reset Linux VMs to known-good state
just reset freebsd  # reset FreeBSD VMs to known-good state

Build specific debug binaries:

just build x86_64-unknown-linux-musl
just build x86_64-unknown-linux-gnu
just build x86_64-unknown-freebsd

Build specific release binaries:

just release x86_64-unknown-linux-musl
just release x86_64-unknown-linux-gnu
just release x86_64-unknown-freebsd

Run all tests against debug builds:

just test linux
just test freebsd

Run specific tests against debug builds, see pytest -k for what is a valid expression:

just debug {platform} {expression}

Testing Internals and Features¶

Test internal tests within the Rust code:

just test-internal

Test feature permutations:

just test-features

Environment Variables for Testing¶

ABGLEICH_TEST_LOGTODISK: Set to 1 for writing test logs to disk
ABGLEICH_TEST_RELEASE: Set to 1 for testing release builds instead of debug builds
ABGLEICH_TEST_TARGET: Test specific build targets, interesting primarily on Linux with possible values being x86_64-unknown-linux-musl (equivalent of default) or x86_64-unknown-linux-gnu
ABGLEICH_TEST_VERBOSE: Set to 1 for much more verbosity during testing

Environment variables starting with RUST such as RUST_BACKTRACE are passed through.