building

Pre-Alpha. This page describes behavior that may change.

Building Ze from source is a single command if you have Go 1.25 and a working C toolchain on the path. The Makefile is the source of truth for every other build target, and make help lists them all. This page is the short version.

Prerequisites

You need Go 1.25 or newer. The repo lives at codeberg.org/thomas-mangin/ze (the canonical development host) and mirrors to GitHub.

go version    # 1.25 or newer
git clone https://codeberg.org/thomas-mangin/ze.git
cd ze

The shortest path

make build

That builds bin/ze (the daemon and CLI), bin/ze-test (the functional test driver), bin/ze-chaos (the chaos orchestrator), and bin/ze-analyse, and regenerates docs/comparison.html from the markdown source. bin/ze-perf is not included; build it separately with make ze-perf. The version is injected via ldflags from the current date in the form YY.MM.DD.

If you only want the daemon, the per-binary target is faster.

make ze        # bin/ze only
make chaos     # bin/ze-chaos only
make test      # bin/ze-test only
make analyse   # bin/ze-analyse only

Protocol buffer toolchain

Regenerating the gRPC API stubs requires protoc, protoc-gen-go, and protoc-gen-go-grpc on the PATH. These are only needed if you edit api/proto/*.proto; the committed generated Go files are enough for a normal build.

make ze-setup      # Install protoc-gen-go and protoc-gen-go-grpc into $GOBIN

protoc itself is not a Go tool, so install it from your system package manager (brew install protobuf, apt install protobuf-compiler, etc.) or from the protocol buffers release page. After ze-setup finishes, make generate regenerates the proto stubs. See gRPC API for the resulting service surface.

Gokrazy VM appliance

make ze-gokrazy-deps and make ze-gokrazy build a bootable x86_64 VM image with Ze as its only application. The first target fetches the Linux kernel, gokrazy init, and serial-busybox packages into the Go module cache (one-time, ~42 MB). The second target cross-compiles Ze and assembles the image. make ze-gokrazy-run boots the result in QEMU for testing. The full appliance build walkthrough is on the appliance page.

Build tags

Compile-time features live in ZE_TAGS. The maprib tag swaps the default BART trie RIB for a Go map implementation, useful for benchmarking.

ZE_TAGS=maprib make ze

Tests

The Makefile splits tests into a few targets so you can run only what you need.

Target	What it runs
make ze-unit-test	Go unit tests for everything except cmd/ze-chaos.
make ze-functional-test	Functional tests against a built bin/ze.
make ze-fuzz-test	All fuzz tests.
make ze-chaos-test	Unit and functional chaos suites, and chaos web tests.
make ze-test	Lint, unit, functional, ExaBGP, and fuzz combined.
make ze-verify	The full pre-commit check: lint, unit, functional, and ExaBGP.
make ze-ci	Lint, unit tests, and build.
make ze-verify-changed	Run ze-verify only on packages touched in your branch.

ze-verify is the one that must pass before you submit a patch. ze-ci is a lighter target (lint, unit tests, and build) used in CI.

Test parallelism

The Makefile caps test parallelism at half the available cores so a make ze-verify does not pin every core on the box. If you want to override that, set GOMAXPROCS directly. The Go test cache lives in tmp/go-cache rather than TMPDIR because Unix socket tests can hit the path-length limit on /tmp.

Build outputs

Everything that comes out of the build lands in bin/.

bin/ze            # daemon, CLI, and the SSH server
bin/ze-test       # functional test driver
bin/ze-chaos      # chaos orchestrator
bin/ze-analyse    # MRT and RIB analysis tool

Other useful targets

make help                 # The full list of targets and a one-line description for each
make generate             # Regenerate plugin imports
make ze-lint              # Run the linter pass
make ze-perf              # Build `bin/ze-perf`. Run benchmarks with `make ze-perf-bench`
make ze-spec-status       # Spec status report
make ze-command-list      # Generated command list
make ze-doc-drift         # Detect docs that have drifted from the code

See also

• Contributing for what to do once you have a working build.
• In-tree CONTRIBUTING.md for the canonical version.
• Plugin development if you are extending Ze rather than modifying the core.

Adapted from main/Makefile and main/CONTRIBUTING.md.