building

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

Building Ze from source is a single command if you have Go 1.26 and a working toolchain on the path. CGO is disabled globally. The Makefile is the source of truth for every build target, and make help lists them all grouped by category. This page is the short version.

Prerequisites

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

go version    # 1.26 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

Ze uses a unified binary with positive build tags to select personalities. The main binary (bin/ze) is built with the ze_core tag. Other binaries are build-tag variants of the same source:

Binary	Build tag	Purpose
bin/ze	ze_core	Daemon, CLI, SSH server.
bin/ze-test	ze_test	Functional test driver.
bin/ze-chaos	ze_chaos	Chaos testing orchestrator.
bin/ze-perf	ze_perf	Performance benchmark tool.
bin/ze-analyze	ze_analyze	MRT and RIB analysis tool.

Additional tags layer features on top:

Tag	Purpose
ze_distro	Linux distribution features (systemd, package management).
ze_appliance	Appliance management commands.
ze_setup	Build tooling and setup commands.
ze_stripped	Minimal build with reduced feature set.
maprib	Swaps the BART trie RIB for a Go map (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

Docker

make ze-docker                                        # Build ze:latest
make ze-docker ZE_DOCKER_IMAGE=myregistry/ze          # Custom image name
make ze-docker ZE_TAGS=maprib                          # With build tags

The image is ~89 MB: a static binary on a scratch base. See Docker for the full guide.

Other useful targets

make help                 # The full list of targets, grouped by category
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.