Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Quickstart

Three TOML files describe an Aves build:

FileScopePurpose
aves.tomlWorkspacePins nixpkgs, sets policy, picks a runtime.
aves_manifest.tomlProjectPicks the board and the packages to build.
packages/<name>/package.tomlPackageDefines a single buildable component.

Plus board files at boards/<name>.toml.

1. Edit the manifest

aves_manifest.toml:

[nixpkgs]
channel = "nixos-25.05"

[project]
name  = "my-device"
board = "feather_nrf52840_express"

[packages.nrf52-adafruit-uf2-bootloader]
version = "0.10.0"

2. Build

aves build

You’ll see something like:

fetch    nrf52-adafruit-uf2-bootloader@0.10.0
toolchain gcc-arm-embedded, gnumake, python3, adafruit-nrfutil
build    feather_nrf52840_express
✓ build/nrf52-adafruit-uf2-bootloader/feather_nrf52840_express/bootloader.uf2

3. Find the output

Artifacts land at:

build/<package>/<board>/*.{uf2,hex,zip}

The exact extensions depend on the package’s [build] outputs globs — see Packages.

What happened

  1. The CLI read aves.toml to resolve the pinned nixpkgs revision and the nix-portable runtime.
  2. It read aves_manifest.toml to learn the board (feather_nrf52840_express) and the package list (just one bootloader).
  3. For each package, it cloned the source into ~/.local/share/aves/src/<pkg>/, evaluated the [build] inputs as Nix expressions, opened a sandbox, and ran the [build] command inside it with {board} substituted from the manifest.
  4. Files matching [build] outputs globs were copied into build/<package>/<board>/.

Because both the toolchain and the package versions are pinned, the same workspace produces byte-identical artifacts on any machine.