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

Feature gates

Beyond the personality tags above, Ze can compile whole subsystems out at build time. Each optional subsystem is guarded by a ze_<feature> build tag. Leaving the tag off drops that subsystem's code from the binary, for a smaller image and less attack surface. A build with a subsystem compiled out does not link it and rejects its config block as unknown.

The default-on set lives in one place, feature-gates.txt, and the Makefile derives the ZE_FEATURES variable from it. make ze and make ze-appliance build with every default-on feature; make ze-stripped keeps only the SSH management plane and drops the rest; a bare go build -tags ze_core drops all of them.

Tag	Subsystem
ze_ssh	SSH server (the base operator management plane).
ze_web	Web interface.
ze_lg	Looking Glass.
ze_gnmi	gNMI server.
ze_mcp	MCP server.
ze_rest	REST API transport.
ze_grpc	gRPC API transport.
ze_telemetry	Prometheus / telemetry exporter.
ze_isis	IS-IS.
ze_ldp	LDP.
ze_ospf	OSPF.
ze_rsvpte	RSVP-TE.

Build a hardened, minimal daemon or add specific features on top:

make ze-stripped                                 # SSH only, all optional features dropped
go build -tags 'ze_core ze_ssh ze_web' ./cmd/ze  # SSH plus web only

REST and gRPC gate independently, so a build can ship one transport without the other. Metric collection stays linked in every build; only the HTTP exporter is behind ze_telemetry, so a no-telemetry binary still records counters but cannot expose them over HTTP.

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.