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:

• Try a change with webui-dev or fast first; run a VM test only to confirm.
• Run only the test for what you changed: update for router-update and the Update page, setup for router-setup, apply for the settings and the web UI, basic for the firewall and DHCP.
• Use -i to iterate on a test script.