The toolchain: binaries and commands

Xo is experimental, and the commands and flags below may change before 1.0. The specification’s section 10.1 is the authoritative list of commands and flags; this page is the practical guide to it.

What xo is

xo is one binary: the compiler, the formatter, the test runner, the module tools, and the editor and agent servers. It is written in Xo (the self-hosted compiler, built from selfhost/xo in the repository; you may see it called xo1 in the project’s notes). The original implementation, written in Go, is frozen and serves as the seed that builds the first Xo compiler on a machine.

The layout

An installed toolchain is a directory, and xo finds the rest of the toolchain relative to itself:

bin/xo          the toolchain
bin/xo-gobind   a helper that binds Go packages for use go
lib/xo/         std, third_party, the prebuilt native runtime, zoneinfo.zip

Keep the layout: bin/xo looks for the standard library and the runtime in ../lib/xo, so a copy of bin/xo on its own does not work. Put bin on your PATH, or link bin/xo from a directory on your PATH (symbolic links are followed). Set XO_STD to point at the standard library when it lives somewhere else, as it does in a checkout.

Building it from source

From a checkout of the repository, the Go seed (Go 1.26 or later) builds the first Xo xo. On an arm64 host (Apple silicon, arm64 Linux):

go build -o .tools/bin/xo-seed ./cmd/xo
XO_SELF_DRIVER=0 .tools/bin/xo-seed build --backend=arm64 -o .tools/bin/xo selfhost/xo
export XO_STD="$PWD/std"

On an x86-64 host, with clang installed:

go build -o .tools/bin/xo-seed ./cmd/xo
XO_SELF_DRIVER=0 XO_LLVM_SPLIT=12 XO_LLVM_LTO=none \
  .tools/bin/xo-seed build --backend=llvm -o .tools/bin/xo selfhost/xo
export XO_STD="$PWD/std"

The arm64 build takes a few minutes; the x86-64 build took about 36 minutes and 10 GB of memory on a 16 vCPU Linux machine. After that, any Xo xo rebuilds itself without Go (scripts/bootstrap-xo.sh; see the bootstrap post for how that is checked). Getting started walks through a first program.

Backends and targets

--backend picks how a program is built. Each backend needs different tools on the machine.

• --no-gc builds on a native backend whose memory is reference counted instead of collected: arm64 on arm64 hosts, LLVM otherwise. --backend=llvm and --backend=arm64 already imply it. A construct a native build does not support yet is error XO1201 at compile time.
• --targets=all (Go backend) builds linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64, windows/arm64, and wasip1/wasm, one binary per target.
• --ld=macho links an arm64 program with Xo’s own assembler and linker, with no cc. It needs the prebuilt runtime in lib/xo of a packaged toolchain (or XO_RTPACK). On a Mac it is the default when that runtime is present. --ld=cc uses the system linker.
• Windows (x86-64) and Intel Macs build natively through the LLVM backend; this work is in progress and tested on a smaller scale than the arm64 hosts.
• Linux programs with no C library at all are an opt-in experiment (XO_NOLIBC=1 with a native backend), in progress: they refuse use c and TLS for now.
• use c works only on the native backends, and use go only on the Go backend.
• A program that names time zones reads them from Go’s zoneinfo.zip, lib/xo/zoneinfo.zip, XO_ZONEINFO, or with --tzdata=system, from the system’s zone files.

Commands

xo help lists every command, and xo help <command> or -h/--help prints a command’s usage. Every command that reports diagnostics or results accepts --json, and xo query answers in JSON by default when its output is not a terminal. The examples run in a module directory.

A directory argument covers every directory below it, skipping testdata, vendor/, and names starting with . or _. So xo check . checks every module under the current directory, and the Go-style pattern ./... (or cmd/...) means the same thing: xo check ./..., xo test ./.... A pattern that matches no .xo files is an error, and xo run takes one directory, not a pattern.

Build, run, and test

Useful flags of all three: --backend, --no-gc, -o, --json, --tzdata=embedded|system. xo build and xo run take --stamp NAME=VALUE (sets a string constant for this build). xo build also takes --targets, --ld, --ci (fail on unformatted code or a leftover dbg), and --release. xo test takes --seed=N, --explore=N, --cases=N, --run=NAME, -v, and --real (tests that declare effects run with real capabilities).

Check and edit

xo check --fix is the agent loop’s check: it applies every unambiguous fix, reformats what it changed, and reports what remains.

Modules and dependencies

xo mod clean empties the module cache, and xo mod proxy serve serves it as a module proxy. Every module command takes --offline. See Dependencies and capabilities for effect ceilings and vouches.

Bindings

You rarely need to run these yourself: xo check and the builds bind a missing package or header on first use.

Servers and debugging

Environment variables

Two more apply only to the Go seed when it builds the first Xo xo: XO_SELF_DRIVER=0 makes the seed do the build itself (as in the commands above), and XO1 points it at an Xo compiler you already built.

Coming later

Developer harnesses written in Xo, under an xo dev command, are planned (decision 0209) but do not exist yet.