Developer Setup
Set up a Ze development environment with all build, lint, and test dependencies.
Quick Start
./le is built from this repository with Go, so Go comes first. Install the
release go.mod names on its go line from
https://go.dev/dl/, or any Go 1.21 or newer, which downloads that release on
first use. Then put two directories on PATH: the Go toolchain's, and the one
go install writes to, where setup builds golangci-lint, staticcheck,
goimports, gopls and govulncheck:
export PATH="$PATH:/usr/local/go/bin" # the go.dev tarball's location
export PATH="$PATH:$(go env GOPATH)/bin" # or $(go env GOBIN) when GOBIN is set
Add both lines to ~/.profile (~/.zshenv for zsh) so every new shell has
them. A non-interactive shell such as ssh host command reads no ~/.bashrc.
Then:
git clone <repo-url> && cd ze
./le setup install
./le setup check
When the install directory is not on PATH, setup still builds the tools there,
reports each as [pending ] <tool> (in /root/go/bin, which is not on PATH),
and prints once the exact export PATH=... line for that directory and the
profile to keep it in. check reports the same rows the same way: a tool no
shell can run is never counted present.
This detects your OS (macOS with Homebrew or Debian/Ubuntu with apt), installs missing tools, vendors Go dependencies, and reports what it did.
le is the native development-tool personality built from cmd/ze. The root
./le is a dispatcher, and bin/le is an identical copy of it that ./le
installs whenever the two differ. Both run the newest build in
bin/builds/<UTC commit time>-<short sha>/le.
Setup behavior lives in internal/le/setup.Answer.
Builds follow HEAD, never your working tree, because a peer session's
half-written source would otherwise break every call in every session. Each
build records the git tree hash of le's inputs (internal cmd pkg api vendor go.mod go.sum feature-gates.txt feature-tags) at the commit it came from.
When a commit changes them, the next ./le call starts one build of HEAD in
the background and keeps running the newest build; the new one is smoke-tested
and renamed into place only when it passes, so after a git pull the new
commands arrive a couple of minutes later with no command of yours waiting. A
commit that changes no input reuses the newest build. On a fresh checkout with
no build at all, the first call builds HEAD in the foreground.
A HEAD that fails to build is reported once on stderr, with its log at
bin/builds/.failed-<commit>.log, and the newest good build keeps running. A
build that does not start is moved aside to bin/builds/.failed-<name> and the
call runs the next newest, saying so in one line. When the newest build starts
but misbehaves, take it out by hand:
./le rollback
It moves the newest build aside the same way, so the next call runs the one
before it, and HEAD is not built again until a commit changes the inputs.
Nothing is deleted: a peer executing that build keeps its file.
./le help lists rollback and Tab completes it; run it as ./le rollback,
because only the launcher moves a build.
./le --update is gone and says so with exit 2.
Do not delete bin/le or anything in bin/builds/. Several sessions share one
checkout and one of them can be executing that file right now. When you need
le to carry your own uncommitted edits, ask for a build of your own instead:
./le --name session verify current
--name comes first, before the command, and the launcher consumes it. Every
argument after it reaches the binary unchanged. --name session names the
build after CLAUDE_CODE_SESSION_ID (s-<its first eight characters>) and
refuses with exit 2 when that variable is unset; --name mywork picks the name
yourself. The build lands in bin/le-<name>/le, which bin/ already keeps out
of git, and it is rebuilt from the working tree on every call, so the toolchain
decides what to recompile and the binary carries your edits. The shared builds
are never written and never wait for a peer.
A name accepts letters, digits, dot, underscore and hyphen. A name carrying /
or .. is refused with a message and exit 2, never repaired into something safe.
The launcher exports the name to the process it runs and to that process's
children, so a script that calls ./le inside a named session reaches the same
build without repeating the option. A binary that is not the one you named
refuses to answer and reports both names:
le: --name asked for 'mywork' and this process is 'le' (/home/you/ze/bin/builds/20261025T114143Z-00b9273a2a/le).
Reach the named build through ./le --name mywork, never through a hardcoded binary path.
Check Mode
Probe the current host without installing anything:
./le setup check
The check action probes only and changes nothing: it installs no package, edits no
sysctl, and adds no loopback address. It exits 0 if all required tools are
present, nonzero if any are missing. Use it as a CI preflight check. Run
./le setup install to install what the probe found missing.
One row is behaviour rather than a binary: gopls-answers runs the language
server and checks that it replies. A server on PATH that does not answer fails
this check, because every LSP call against it fails the same way.
Editor plugin
A language server on PATH is not the whole capability. Claude Code reaches it through a plugin, and without that plugin the LSP tool refuses every Go file.
When Claude Code is installed (claude on PATH, or a ~/.claude directory)
and the plugin is not, ./le setup check reports the plugin as a pending step
and names the command that installs it. On a host without Claude Code the row
is skipped with the reason "Claude Code is not installed", because there is no
LSP tool to refuse anything and no session to run the slash command in.
| Plugin | Serves | Install |
|---|---|---|
gopls-lsp |
.go |
/plugin install gopls-lsp@claude-plugins-official |
Run the slash command inside a Claude Code session. The plugin and the binary it names fail the same way and have different fixes, so the report says which of the two is absent.
Tool caches: le exec
./le exec <path> [args...] runs a program with its caches in the one per-user
cache, $XDG_CACHE_HOME/ze, else ~/.cache/ze, instead of each tool's default
folder (~/Library/Caches on macOS). It sets four variables, creates their
directories, and then replaces itself with the program, so the program's exit
status is the caller's and every argument after the path reaches it untouched.
A heavy tool that needs a job slot is the exception: go test, golangci-lint run, staticcheck and the formatters, judged as the Bash hook judges a raw
command. In a checkout, le exec waits for a slot, then runs the tool as its
child on the same terminal, forwards every SIGINT, SIGTERM, SIGHUP and SIGQUIT
to it until it exits, releases the slot and exits with the tool's code. Inside
a live parent's slot (./le go lint run
starting the linter) or outside a checkout it holds nothing and replaces
itself, as for any other program. The main thread's post-edit lint goes past
the shim on purpose and takes no slot
(docs/contributing/running-commands.md, "Waiting for another session's job").
| Variable | Directory under the per-user cache |
|---|---|
GOCACHE |
go-cache |
GOPLSCACHE |
gopls |
GOLANGCI_LINT_CACHE |
golangci-lint-cache |
STATICCHECK_CACHE |
staticcheck-matrix |
When the working directory is inside a Ze checkout, the program also gets Ze's
patched GOROOT, with GOTOOLCHAIN=local and the tree's bin first on PATH, so
gopls analyzes the standard library Ze compiles. Anywhere else it gets the
GOROOT, GOTOOLCHAIN and PATH its caller had, and never a patched tree, so a tool
on another repository sees that repository's Go.
A bare name is looked up on PATH, skipping any file that carries the shim
marker. le exec refuses, with exit 1, a path that does not exist, is not an
executable file, or is a shim ./le setup wrote, because a shim handed back to
le exec would start it again in a loop; each refusal names the path and
./le setup. Warm, ./le exec /usr/bin/true takes about 50 ms on an Apple
silicon Mac.
Tool shims, PATH and the Go cache setting
./le setup install writes a shim for gopls, golangci-lint and
staticcheck, the tool rows marked Shim in the setup table, into the shim
directory it chooses from PATH. Each shim is a short sh script, mode 0755,
that carries the le exec marker on its second line and ends with:
exec '/path/to/ze/le' exec '/path/to/real/gopls' "$@"
The shim directory is the earliest PATH entry that is:
- an absolute path under HOME
- an existing directory this user can write
- outside any ze checkout (a directory holding
go.modbesidefeature-gates.txt, or under one) - ahead of every PATH directory holding a real
gopls,golangci-lintorstaticcheck
The PATH judged here is the caller's: the one the shell that ran ./le had,
which is the one an editor or a new shell searches. le's own PATH is not it,
because le puts the patched GOROOT's bin first before it runs any action
(see above), and that tree lives under the per-user cache, so under HOME and
writable. Setup restores the caller's PATH the way le exec does, dropping
every patched tree's bin a parent le left on it, and judges the shim
directory, the real tools and the gopls-answers row against that.
A directory listed twice counts at its first position, the one a lookup
reaches. The Go bin directory never qualifies, because it holds the real tools,
and a shim there would be overwritten by the next go install. Only when no
entry qualifies do the shims go in ~/bin, and the shim-dir row is pending
until PATH reaches ~/bin first.
The real tool is the first copy on PATH outside the shim directory that is not
itself a shim. An editor, the Claude LSP or a shell that finds the tool by PATH
then starts it through le exec, so its cache lands under ~/.cache/ze with no
shell variable. Each run rewrites a shim whose checkout or tool path changed,
so after moving the checkout or reinstalling a tool, run ./le setup install
again. When the checkout a shim names is gone, the shim exits 1 and says which
le is missing and that ./le setup install from the current checkout
rewrites it. Setup never overwrites a file in the shim directory that it did
not write: the row is pending and prints the mv command that moves the file
aside. A shimmed tool with no real copy on PATH is missing, and its own tool row
installs it; a shim found first on PATH does not count as the tool.
Once a tool's shim is current in the shim directory, the same run removes every
older shim for that tool in ~/bin, in every other directory of the caller's
PATH, and in every directory of le's own PATH (the patched tree's bin, where
an earlier setup wrote them), and the
tool's row names each one it removed. Directories are compared by identity, so
a second spelling of the shim directory (~/Bin for ~/bin on a
case-insensitive disk, or a link) is the same directory and keeps its shims. Only a file carrying the le exec marker
under a shimmed tool's name is removed, so a file setup did not write is never
touched. check removes nothing and reports the old shims as work left.
| Row | Present when | Otherwise |
|---|---|---|
<tool>-shim |
<shim directory>/<tool> runs le exec on the current real tool, and no older shim for it is left elsewhere |
install writes it and removes the old shims; check reports it missing |
shim-dir |
a PATH entry qualifies; the row names it | pending, with the shims in ~/bin and the lines below |
go-env-gocache |
go env GOCACHE names <per-user cache>/go-cache, links followed |
install runs go env -w GOCACHE=<that path> and prints the old and new value; check reports it |
le never edits a shell file. When no PATH entry qualifies, setup prints the
line that puts ~/bin first for ~/.zshenv (~/.profile for another shell)
and, when nu is on PATH, the line for the env file nu -c '$nu.env-path'
names:
export PATH='/Users/you/bin':"$PATH"
$env.PATH = ($env.PATH | split row (char esep) | prepend r#'/Users/you/bin'# | uniq)
Plain go outside le reads GOCACHE from go env, so the go-env-gocache row
is what keeps go build in any shell out of ~/Library/Caches/go-build. It
reads the setting with GOCACHE removed from the environment, so le's own value
does not hide it. When go env -w fails, for example under GOENV=off, the row
fails with the reason and prints the exact go env -w command.
With the shims in place, the GOPLSCACHE, GOLANGCI_LINT_CACHE and
STATICCHECK_CACHE lines in ~/.zshenv or env.nu are no longer needed:
le exec sets them. The gopls-answers row names the gopls the caller's PATH
reaches and whether it is the shim; a gopls started by absolute path, or one ahead of
the shim directory, keeps its default cache.
What It Installs
Build and Lint
| Tool | Purpose |
|---|---|
go |
Go toolchain |
git |
Version control |
protobuf (protoc) |
Protocol buffer compiler |
jq |
JSON processing |
golangci-lint |
Go linter (via go install) |
staticcheck |
Feature-tag structural type checker, pinned to 2026.2.2 (honnef.co/go/tools v0.8.2 in, built from the vendor tree with go install -mod=vendor so it links the x/tools requires). go.modgo.mod |
goimports |
Go import formatter (via go install) |
gopls |
Go language server behind the agent LSP tool (via go install) |
govulncheck |
Dependency vulnerability scanner for the verification gate, built from the vendored copy (via go install) |
The linter's module dependency and setup install target move together. Use the
pinned release: its exhaustive analyzer checks enum switches through type
aliases as well as directly named types. An existing golangci-lint on PATH is
only presence-probed by setup, so changing the pin alone does not replace that
binary.
Regenerate the checked-in protobuf Go files after you change
api/proto/ze.proto or the module path:
./le setup proto
The action builds both protoc plugins from the vendored module versions, runs
protoc, and applies explicit json_name options to Go struct tags.
Run the installed checker through the repository gate:
./le go staticcheck check
The target and its checked feature population are documented in
docs/contributing/testing.md.
Appliance
| Tool | Purpose |
|---|---|
qemu |
QEMU functional and install gate tests |
e2fsprogs |
mkfs.ext4 and debugfs for appliance builds |
xorriso |
ISO image creation |
grub |
GRUB EFI tooling for ISO builds (Linux only) |
iproute2 (ip) |
The Linux loopback step's ip -6 addr add (Linux only; slim Debian and Ubuntu images lack it, macOS uses ifconfig) |
Optional
| Tool | Purpose |
|---|---|
sshpass |
Optional SSH probe fallback |
docker / colima |
Container appliance and kernel builds |
xl2tpd |
L2TP LAC peer for the root-only L2TP PPP evidence tests (Linux only) |
ppp (pppd) |
pppd for the same tests, which run on Linux, where setup installs it with apt. macOS ships /usr/sbin/pppd, so setup reports it present there. Debian installs it as root:dip mode 4754, so a user outside dip cannot run it; setup counts the file as present, because the tests run it as root |
Platform Notes
macOS
- The Homebrew prefix is resolved, never assumed. It is
/opt/homebrewon Apple Silicon and/usr/localon Intel, so a hardcoded path is absent on half the Macs. Every consumer asks in the same order:HOMEBREW_PREFIXwhenbrew shellenvhas exported it, then thebrewbinary's own location (<prefix>/bin/brew), then the two documented defaults. Thebrewlink is not followed: on Intel it points into<prefix>/Homebrew, which would answer with the wrong prefix. Thedocker-buildxstep (Docker labs, below) is the one consumer that asksbrew --prefix: it needs brew to install the formula anyway, and Homebrew's caveat for that formula names the same path. - e2fsprogs is keg-only on Homebrew, so none of it is linked onto
PATHandwhichfinds nothing however well it is installed. It is looked for under<prefix>/opt/e2fsprogs/sbin, the link kept at the current version, and under<prefix>/Cellar/e2fsprogs/<version>/sbin, where an interrupted upgrade leaves it with no link. No PATH modification is needed afterbrew install e2fsprogs. - grub has no first-party Homebrew formula. ISO builds require Linux or a container (colima/docker). The setup action skips grub on macOS.
Docker labs
A Docker lab runs Ze in containers, so the kernel it tests is the Docker host's, and that kernel has to carry every feature Ze enrolls. A lab is never judged on a kernel that lacks one.
- macOS, the
zeColima profile: the labs run on the Colima profileze, which boots Ze's docker-host image (Ze's runtime kernel, dockerd, containerd)../le setup docker host startbuilds the image when needed and runs the profile, never touching Colima'sdefaultprofile, then makescolima-zethe current Docker context so a plaindockerreaches it. With DOCKER_HOST unset, every lab names the profile's socket,ze/docker.sockunder Colima's home ($COLIMA_HOMEwhen that directory exists, else~/.colima), itself, whatever the current Docker context says; when that socket is absent the lab stops before it builds anything and names./le setup docker host start. It never falls back todefaultor to Docker Desktop. A DOCKER_HOST you set is used as it is, and the lab's Docker kernel check judges that daemon../le setup docker host checknames anything missing (colima, lima, docker,brew install e2fsprogsformkfs.ext4), and./le setup docker host stopstops it. The image build and the profile's lifecycle are indocs/architecture/appliance/docker-host.md. - macOS, the QEMU guest: the second route boots the same docker-host
image under QEMU with HVF, on Ze's own arm64 runtime kernel, and runs the
labs from the host le against the guest's dockerd through a forwarded
socket. Build the kernel
cache entry once with
./le build host-driverand then./ze-host appliance kernel --target runtime --arch arm64(the./zewrapper builds withoutappliance), then run a lab as./le test qemu docker-lab lab "test integration interop-ipsec". With nolabthe action stops after the guest's Docker kernel check. - Linux: the labs run on the host's own Docker, on a kernel that carries
every registered feature.
./le setup docker kernel checkasks the Docker daemon in hand and names each missing feature. It cross-builds the linuxzeit probes with for the daemon's architecture (tmp/qemu/linux-<arch>/ze);ze <path>names another, which must be a linux executable for that architecture../le setup docker kernel installputs Ze's cached runtime kernel under/bootand makes it GRUB's default, one statedsudostep at a time. It needsGRUB_DEFAULT=savedin/etc/default/grub, never reboots, and refuses on macOS. A kernel built with--builder qemuon a host with Docker is installed withbuilder qemu, because the cache entry is keyed by backend. When the daemon applies AppArmor (Ubuntu's default), the check runs its probe under Ze'sze-kernel-probeprofile, because Docker'sdocker-defaultdenies what the probe does;./le setup docker kernel apparmor confirm ze-kernel-probeinstalls and loads it, one statedsudostep at a time. The lab peers that write their network sysctls while they run (the VRRP scenarios' ze, strongSwan in some IPsec scenarios) run under the one generic profileze-lab-net-sysctlthe same way, loaded with./le setup docker kernel apparmor confirm ze-lab-net-sysctl; the action with noconfirmlists every profile and the steps each one runs. - BuildKit: the interop labs build some images with a named build context,
which only BuildKit accepts, and the docker CLI reaches BuildKit through its
buildx plugin. When
dockeris on PATH, setup runs adocker-buildxstep that is judged bydocker buildx versionanswering, never by a package being present../le setup checkreports itMISSINGand changes nothing. On macOS,./le setup installrunsbrew install docker-buildxwhen brew does not hold the formula. It then adds$(brew --prefix)/lib/docker/cli-pluginstocliPluginsExtraDirsin the docker config, because the docker CLI does not search the Homebrew directory until the config names it. The config is$DOCKER_CONFIG/config.jsonwhenDOCKER_CONFIGis set, else~/.docker/config.json. The edit keeps every other key and its value, adds no entry that is already there, refuses a file that is not a JSON object rather than replacing it, and replaces the file by rename after a sync. A symbolic link is followed, and a link to a file that does not exist is refused rather than replaced. With no home directory and noDOCKER_CONFIGthe step refuses instead of writing a relative path. Each failure (brew cannot install, brew names no prefix, the plugin still does not answer) leaves the steppendingwith the reason and the next command to run. On a Mac with no Homebrew the step changes nothing and names https://brew.sh. On Linux the plugin is a root package and setup runs nosudofor it. The step names the package that matches the installed docker,docker-buildx-pluginbeside Docker'sdocker-cewhen dpkg reports itinstall ok installed, anddocker-buildxbeside the distribution'sdocker.io, with thesudo apt-get installline, and reports itpending. The lab's BuildKit refusal names./le setup installas its fix. With no docker CLI the step isskipped.
docs/architecture/testing/qemu-integration.md, "Docker labs in the Ze-kernel
guest", is the guest path; the scheduled nightly runs the same path on amd64
under KVM (docs/architecture/testing/ci-workflows.md).
Linux
./le setup install installs the apt packages itself, the same way it installs the
Homebrew ones on macOS. Each command is echoed before it runs. It takes
apt-get update once per run, because a container image ships no package
lists, and it sets DEBIAN_FRONTEND=noninteractive so a package with a debconf
prompt cannot stop the run.
How it reaches root. The answer is decided before any command runs, and
sudo is always given -n, so no path can stop at a password prompt:
| State | What setup does |
|---|---|
| You are root (a container build) | Runs the command directly. sudo need not be installed |
sudo acts with no password |
Runs sudo -n <command> |
sudo wants a password, a terminal is attached |
Asks once with sudo -v, then runs sudo -n <command> |
sudo wants a password, no terminal (CI, an agent session) |
Prints the command, installs nothing, exits nonzero |
GRUB follows your host architecture. Debian packages one module set per
architecture: an amd64 host takes grub-efi-amd64-bin, an arm64 host takes
grub-efi-arm64-bin. Asking an arm64 host for the amd64 package installs
nothing at all, grub-mkstandalone included. ze appliance iso picks its GRUB
target from the architecture of the image it packs, so building an ISO for the
OTHER architecture needs that architecture's set too, through
dpkg --add-architecture.
Unprivileged user namespaces. Ubuntu 23.10+ ships
kernel.apparmor_restrict_unprivileged_userns=1, which blocks the sandbox
Chrome relies on and makes the agent-browser web functional tests fail to
launch Chrome (No usable sandbox!). It also breaks the kernel tests that run
in a user namespace of their own (userns.Enter, see
the testing guide): the namespace holds no
capability, so each such test fails and its message names this check. Setup
checks this tunable as userns-unrestricted. When it is restricted, ./le setup install
echoes and then runs these commands via sudo to lift it globally:
echo "kernel.apparmor_restrict_unprivileged_userns = 0" | sudo tee /etc/sysctl.d/60-ze-userns.conf
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
The /etc/sysctl.d drop-in makes the change survive reboots. It goes through
the same root route as the package installs, so on a root run the echoed lines
carry no sudo, and when root is out of reach it prints the commands to run by
hand instead. ./le setup check only reports the state, never changes it.
KVM device access. /dev/kvm is root:kvm mode 0660, so QEMU-backed
evidence (the appliance boot proofs and every ze-qemu-* target) needs your
user in the kvm group. Without it QEMU does not quietly fall back to
emulation: it refuses to start with Could not access KVM kernel module: Permission denied, and the calling native QEMU action reports a timeout instead. Setup
checks this as kvm-access and, in install mode, runs:
sudo usermod -aG kvm $USER
Group membership is fixed at login, so an existing shell keeps the old groups even after the command succeeds. Log out and back in, or run one command with the new group:
sg kvm -c './le test qemu vpp-hugepages'
Setup distinguishes the two states: kvm-access reports pending when the
group database lists you but the running session predates it, and missing
when the group is not granted at all. A host with no /dev/kvm (no hardware
virtualisation, or a VM without nested virt) reports n/a: QEMU runs under
tcg there, only slower. macOS has no /dev/kvm and needs no group; the
native QEMU actions select the Apple hypervisor (hvf) by platform.
PPP device access. The L2TP and PPPoE tests open /dev/ppp to drive the
kernel PPP channel. They run as you, in a user namespace of their own
(userns.Enter), where root holds the CAP_NET_ADMIN the PPP ioctls need,
and your supplementary groups still apply to the open. A stock Debian host
makes the device root:root mode 0600, so a test run as you cannot open it,
and the test fails naming ./le setup install and ppp-access. Setup checks this as ppp-access and grants
the device to the dip group. Debian ships dip (gid 30) for PPP dial-up,
pppd's documentation names it, and you are usually in it already, so a second
group of Ze's own would grant the same device to the same person under another
name. A host with no dip group gets one as a system group. In install mode
setup runs only the steps whose piece is absent, in this order:
sudo groupadd --system dip
printf '%s\n' '# ./le setup install: the dip group may open /dev/ppp, for the L2TP and PPPoE tests.' 'KERNEL=="ppp", GROUP="dip", MODE="0660", OPTIONS+="static_node=ppp"' | sudo tee /etc/udev/rules.d/60-ze-ppp.rules
sudo udevadm control --reload
sudo modprobe ppp_generic
sudo chgrp dip /dev/ppp
sudo chmod 0660 /dev/ppp
sudo usermod -aG dip $USER
The rule keeps the grant across module loads and reboots: KERNEL=="ppp"
applies when ppp_generic registers the device, and static_node=ppp applies
at boot to the node systemd creates before the module loads (systemd grants
/dev/kvm with the same line). The first open of that node loads the module.
modprobe runs only when /dev/ppp does not exist. The node is changed with
chgrp and chmod rather than udevadm trigger, because a static node with
no module loaded has no device udev can act on.
ppp-access is present when your session can open /dev/ppp read-write. It
is pending when the rule, the node and the group database are all in place
but your session predates the membership: log out and back in, or run
sg dip -c '<command>'. Otherwise ./le setup check reports it MISSING
with the absent pieces, and ./le setup install grants them. The check judges
the device with access(2) and does not open it, because opening /dev/ppp
loads ppp_generic and a check changes nothing. When root is out of reach, the
install prints the commands above with sudo instead of running them. macOS
reports the step skipped: it has no /dev/ppp, and the PPP tests run in the
Linux VM.
Kernel features. A test that needs a kernel feature runs on Ze's kernel,
which carries it. The nftables flowtable test needs NF_FLOW_TABLE,
NF_FLOW_TABLE_INET and NFT_FLOW_OFFLOAD, and the tc ingress policer tests
need NET_ACT_POLICE and NET_ACT_GACT. Ze's kernel builds all five in
(gokrazy/kernel/kernel.config and runtime.config). A distribution kernel
may build them as modules or not at all, and the kernel then answers the test
with a bare no such file or directory. The test still fails, never skips, and
its failure adds a line for each option the running kernel lacks or has not
loaded: the kernel release, the option, and the fix. The fix is to boot Ze's
kernel (on a Linux host, ./le setup docker kernel install, then reboot) or,
for a module that is built but not loaded, sudo modprobe <module>. The
options are read from /proc/config.gz, else /boot/config-<release>, and the
loaded modules from /proc/modules. Setup does not load these modules.
Loopback addresses. The functional fixtures give each end of a BGP session
its own address: RFC 4271 Section 5.1.3 forbids a peer its own address as
NEXT_HOP, so a session whose two ends share one address has every originated
route withheld. IPv4 spends 127.0.0.0/8, which Linux already routes to lo and
macOS does not, so setup adds 127.0.0.2 through 127.0.0.6 there. IPv6 gives a
host exactly ::1 on every platform. Setup adds fd00::2/128 for the speaker
and next-hop owner, fd00::3/127 for the recipient, and fe80::1 as the
next-hop owner's link-local. macOS already carries fe80::1/64 on lo0 from
boot, so setup adds fe80::1/128 only where it is absent, normally on Linux.
The one connected prefix fd00::2/127 contains exactly the two unique-local
addresses. This makes the RFC2545 compatibility
fixture's common-subnet condition real without routing all of fd00::/64
locally. Setup checks this as loopback-addresses and, in install mode, runs:
sudo ifconfig lo0 inet6 fd00::2/128 alias # macOS
sudo ifconfig lo0 inet6 fd00::3/127 alias
sudo ifconfig lo0 inet6 fe80::1/128 alias # only if lo0 lacks fe80::1
sudo ip -6 addr add fd00::2/128 dev lo # Linux
sudo ip -6 addr add fd00::3/127 dev lo
sudo ip -6 addr add fe80::1/128 dev lo
Presence requires a successful socket bind. IPv6 additionally requires the
address on lo (lo0 on macOS), and the unique-local pair at its exact
prefix; an address elsewhere, or fd00::3/128, does not establish this
fixture's common subnet. fe80::1 is ready at any prefix length, because the
fixtures use it only as a next hop and bind address, and its bind probe
includes the interface zone. An unreadable interface fails the
ownership check closed. Setup never silently removes an existing address with
a different prefix: resolve a conflicting assignment explicitly if the add
command fails.
These changes require an explicit setup install or the commands above.
setup check and test runners do not change host networking. Every command that
starts a functional suite (./le test functional, ./le verify worktree,
./le verify current) runs this same check before it
builds or runs anything, and refuses to start when an address is missing. The
refusal names each missing address and the commands above that add it
(FunctionalHostPreflight). The runners' own per-test probes stay, and check
bindability only.
These additions do not survive a reboot. Re-run ./le setup install after one;
./le setup check says when it is needed. The merge gate adds the same IPv6
addresses and prefix in .github/workflows/verify.yml.
These three, and the apt installs above, are every place setup reaches for root. All of them go through one helper, so the table of states earlier in this section governs each of them.
After Setup
Check that the checkout builds and its tests run with one scoped package test:
./le test unit pkg path ./internal/core/textbuf/
It runs the package's tests under the feature tags with the race detector,
admitted as a job, and a green run answers one line counting the packages
that passed and naming the log it wrote (../contributing/running-commands.md, "Testing
one package while you develop it").
./le verify changed is the day-to-day evidence once you have a change: it
judges only the change set against the upstream, so on a fresh clone it judges
nothing and proves nothing about the setup.
The full verification, ./le verify current, is Thomas's release check. It
refuses unless stdin and stdout are a terminal, so it is started by hand at one
when a release needs it, never from an agent or a script.
Check that appliance tools are detected:
./le setup check
Drift Guard
The dev setup action and ze doctor appliance checks share the same tool
list. A Go test (TestDevSetupMatchesDoctor in
internal/appliance/dev_setup_drift_test.go) fails if they disagree,
preventing the lists from drifting apart.