1. Setup

Prerequisites

Nix

NixOS, or Nix on another host system, must be installed with flakes enabled. For example, on Arch Linux:

sudo pacman -S nix
sudo systemctl enable --now nix-daemon.service

# in /etc/nix/nix.conf
trusted-users = root <your-username>
experimental-features = nix-flakes nix-command

nix-channel --add https://nixos.org/channels/nixpkgs-unstable
nix-channel --update

See the Arch Linux Nix wiki page for more details.

NixOS hosts

The make devshell path runs directly on the host and requires two additions for NixOS hosts.

First, programs.nix-ld.enable must be set to true. Buildroot downloads a prebuilt host Rust toolchain (host-rust-bin). NixOS cannot run these binaries without a dynamic linker shim at the standard FHS path.

Second, FHS compatibility symlinks are required. Some Buildroot scripts assume POSIX utility paths that do not exist on NixOS:

systemd.tmpfiles.rules = [
  "L+ /bin/bash     - - - - /run/current-system/sw/bin/bash"
  "L+ /bin/true     - - - - /run/current-system/sw/bin/true"
  "L+ /usr/bin/file - - - - /run/current-system/sw/bin/file"
];

These changes are not required for the hermetic build (nix build) described below.

Direnv

It is recommended to use direnv and nix-direnv. The development shell provides all host tools automatically via direnv once enabled:

direnv allow

Local system additions or variables such as OUTPUT_BASE may be added in .envrc.local.

Pre-commit

Use the dedicated pre-commit shell so that hook tooling does not bleed into the Buildroot build shell:

./support/pre-commit/install-pre-commit.sh

This configures core.hooksPath=.githooks, installs a repository-local pre-commit launcher, and pre-warms hook environments using the .#pre-commit flake shell. To run hooks manually:

./support/pre-commit.sh
./support/pre-commit.sh run --files README.md

Building

Basic build

To build the release image (the default target):

make

All output goes to output/release or output/debug and is symlinked to output/latest. Sources are cached in dl/ for common use and to persist across clean builds.

For debug builds, see Build Variants.

Incremental targets

Buildroot's Makefile does not generally rebuild targets that may change due to dependencies. In this case an incremental rebuild is required. A common example is that uboot-rebuild will not re-pack into the programmed .fip without an additional arm-trusted-firmware-rebuild.

make linux-extract
make linux-menuconfig
make linux-rebuild
make arm-trusted-firmware-rebuild
make optee-os-rebuild
make uboot-rebuild
make rootfs-ubi
make savedefconfig BR2_DEFCONFIG=$(pwd)/configs/myd_yf135_defconfig

Nix hermetic build

See the buildroot.nix reproducibility documentation for limitations and recommendations.

make nix-lock
nix build .#toolchain
nix build
nix build .#sdk

The hermetic build proceeds in two stages: a toolchain SDK stage and an image stage that consumes the SDK as a Buildroot external toolchain. The make nix-lock command updates both lockfiles, buildroot.lock for the target sources and toolchain.lock for the toolchain SDK sources (required on the first build or after package or environment changes). The nix build .#toolchain command builds the stage-one toolchain SDK; running nix build directly builds or substitutes it automatically. The nix build command performs the full image build. The nix build .#sdk command produces a relocatable cross-compiler SDK tarball.

Build definition files:

• nix/build.nix: build definition
• nix/devshell.nix: development shell configurations

Make vs Nix

For typical local development, the make workflow allows incremental builds. This matches typical Buildroot usage:

• Rerun only specific Buildroot targets such as uboot-rebuild or linux-menuconfig.
• Reuse Buildroot-local caches such as dl/ and output/ccache, which can be easily inspected for build debugging.
• Reuse the Nix-cached toolchain SDK automatically: in the development shell, build goals resolve .#toolchain and pass it as an external toolchain, so make never compiles the cross toolchain itself (see Build Variants).

Use the Nix and Cachix path for reproducible full builds:

• nix build restores cached Nix outputs across machines and CI if cached.
• nix build .#sdk produces a relocatable cross-compiler SDK tarball.
• The Nix path is what CI uses to build and cache the release image. CI also builds the debug image through the make path, so both build paths are exercised on every run (see CI).

Use as a submodule

To use this repository as a submodule of a superproject, create a new BR2_EXTERNAL tree for project-specific packages, overlays, and defconfigs. See Parent Integration for full details, including the init.sh quick start, drift detection, and mkProject parameters.