nixos-router/DEVELOPING.md

Developing

Three tools, from instant to slow. Run them from the repository root; the flake only sees files git knows about, so git add new files first.

nix run .#webui-dev: the web UI on your machine

Sample settings, sample DHCP leases and your real interface counters, on https://127.0.0.1:8443 (password devpassword1). Templates and CSS are re-read on every request: edit, reload the browser. A template with a typo keeps the last good version and logs the error. Pings need root and show "no answer"; Apply does nothing useful here.

nix run .#fast: no VMs

Go formatting, vet and tests, then builds the installer, a router built from settings (through the release) and the home gateway. That runs shellcheck over the scripts and evaluates the modules: most failures of the VM tests (typos, type errors, a script that does not build) show up here, in about a minute (half of that when little changed).

nix run .#fast -- --drivers   also builds every VM test's driver: type-checks
                              the test scripts, builds the VMs' systems
nix run .#fast -- --all       also the checks that need no VM and `nix flake check`

nix run .#test -- NAME...: VM tests

One at a time (each needs gigabytes of memory), a line per test with its time, and for a failure the step that failed and what it said; the full log is in ${TMPDIR:-/tmp}/router-test-logs/NAME.log.

nix run .#test -- update setup
nix run .#test -- --all
nix run .#test -- --list

nix run .#test -- -i update builds the test's interactive driver and gives a Python prompt: start_all(), target.succeed("..."), test_script(). Boot the VMs once and try a step again instead of running the whole test.

Where the time goes

A VM test spends most of its time in the system under test, not in building: router-install (about a minute), booting (20 s each), and everything that runs router-apply on the router (building a NixOS system there takes about a minute) or waits for a rollback timer. A source change rebuilds the systems again on the host. So:

Measured (one at a time): webui 45 s, basic 107 s, onestick 77 s; the ones that install and rebuild on the device are the slow ones: apply and update several minutes, setup 11 minutes (three installs).

• Try a change with webui-dev or fast first; run a VM test only to confirm.
• A change to the web UI only needs webui (a single node, no install). apply, setup and update are for what an installed router does: on-device builds, rollback, router-setup, router-update. Run them before a release or when you touched those, not after every UI edit.
• Nix does not rerun a test whose inputs did not change, so --all after a small change is cheaper than it looks, except that the web UI is part of every installed system: any change to it invalidates apply, setup and update.
• Use -i to iterate on a test script.