---
title: xx Build System
description: Practical, reproducible builds without build-system ceremony.
---

# Build consistently. Keep the build simple.

xx is a build system for projects that want more consistency than a collection of shell scripts without adopting a large, fully hermetic build environment.

Build definitions are small [Starlark](https://github.com/bazelbuild/starlark) files. They declare tools, environment changes, and commands. xx provisions versioned tools, gives each task a clean environment, and runs independent work concurrently.

xx is not fully hermetic. It deliberately chooses a practical middle ground: reproducible tool versions and controlled task environments, with familiar files and commands.

## Why xx?

- **Versioned tools:** A build declares Go or Node.js versions instead of relying on globally installed tools.
- **Small configuration:** Build files use readable Python-like Starlark.
- **Clean task environments:** Tasks start from an operating-system environment, then apply declared dependencies in order.
- **Portable builds:** The same build definition works on supported Windows, Linux, and macOS systems.
- **Shared setup work:** A requested tool version is provisioned once and reused by tasks that need it.

Managed Go and Node.js language packages are supported. More language and tool packages can be added without changing the core model.

## Install

Install xx from source:

```console
go install codeberg.org/tsukinoko-kun/xx@latest
```

This requires Go. Linux and macOS builds also need a C compiler when Go enables CGO. In a POSIX shell, `CGO_ENABLED=0 go install codeberg.org/tsukinoko-kun/xx@latest` builds without a C compiler. Projects using xx can request their own managed Go SDK version.

## First Project

From a project directory, initialize xx:

```console
xx init
```

This creates `.xx/main.star`. Entrypoints live in `.xx/` and can use `.star`, `.build`, `.starlark`, `.bzl`, or `.bazel` as their extension.

For a Go program in `main.go`, use:

```python
load("@go@1.26.5", "go_binary")

go_binary(
    entry_point="main.go",
    flags=["-trimpath"],
)
```

Run the entrypoint by its base name:

```console
xx run main
```

xx downloads the requested official Go SDK when it is not cached, then writes the binary to `.xx/out/main` (`.xx/out/main.exe` on Windows).

## Where Next?

- Read [Built-in packages](packages/index.md) for complete package APIs.
- Start with [Go examples](examples/go.md) for common build patterns.
- Read [Node.js examples](examples/nodejs.md) for npm, npx, and direct Node.js patterns.
- Read [Command examples](examples/commands.md) for task and environment patterns.

## Project Status

xx is early software. Managed Go and Node.js packages support Windows x86-64, Windows ARM64, Linux x86-64, Linux ARM64, and macOS ARM64.

Source and issue tracking are on [Codeberg](https://codeberg.org/tsukinoko-kun/xx). xx is available under the [Zlib License](https://codeberg.org/tsukinoko-kun/xx/src/branch/main/LICENSE.md).

<!--
Sitemap

URL: https://withxx.dev/index.md
Title: xx
Description: Practical, reproducible builds without build-system ceremony

URL: https://withxx.dev/examples/commands.md
Title: Command Examples
Description: General command, environment, and entrypoint patterns.

URL: https://withxx.dev/examples/go.md
Title: Go Examples
Description: Common Go build patterns with managed SDKs.

URL: https://withxx.dev/examples/index.md
Title: Examples
Description: Common xx build and task patterns.

URL: https://withxx.dev/examples/nodejs.md
Title: Node.js Examples
Description: Common Node.js task patterns with a managed distribution.

URL: https://withxx.dev/load.md
Title: Loading Files
Description: Split xx configuration into local Starlark modules.

URL: https://withxx.dev/packages/go.md
Title: Go Package
Description: Provision an official Go SDK, run or install Go tools, and build Go binaries.

URL: https://withxx.dev/packages/nodejs.md
Title: Node.js Package
Description: Provision official Node.js distributions and run npm and npx tasks.

URL: https://withxx.dev/packages/os.md
Title: OS Package
Description: Run commands and construct isolated task environments.
-->