docs/nix.md
Nix flakes are, in theory, guaranteed to be 100% reproducible on (nearly) any system. It does this by fully managing every dependency. This also means that you as a developer do not need to install any build / runtime packages to build bpftrace with Nix.
Rather than explain how Nix works (which is difficult to impossible in this kind of document), the rest of this guide will be a series of examples. Learning Nix flakes and the Nix language will be an exercise left to the reader.
These examples all assume you've already installed the nix CLI tool. If not,
see: https://nixos.org/download.html.
Also note again that we require no dependencies to be installed other than
nix itself.
Nix flakes are technically an experimental feature but it's widely used and understood that the interface is unlikely to change. To enable flakes, run:
$ mkdir -p ~/.config/nix
$ echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
When invoking nix build, flakes reconstruct the source tree from Git metadata
but skip submodules, so append .?submodules=1 (as below) to ensure libbpf is
present.
$ nix build .?submodules=1#
$ sudo ./result/bin/bpftrace -e 'BEGIN { print("hello world!") }'
Attached 1 probe
hello world!
^C
$ nix build .?submodules=1#bpftrace-llvm13
$ sudo ./result/bin/bpftrace --info 2>&1 | grep LLVM
LLVM: 13.0.1
$ nix build .?submodules=1#appimage
$ ldd ./result
not a dynamic executable
$ sudo ./result -e 'BEGIN { print("static!"); exit() }'
Attached 1 probe
static!
$ nix develop
[dxu@kashmir bpftrace]$ cmake -B build-nix -GNinja
[...]
[dxu@kashmir bpftrace]$ ninja -C build-nix
[...]
[dxu@kashmir bpftrace]$ exit
$ sudo ./build-nix/src/bpftrace --version
bpftrace v0.17.0-75-g68ea-dirty
nix develop opens a developer shell. We've configured the bpftrace flake
to be nearly the exact same as the default build environment except with a
few more tools available.
$ nix develop .#bpftrace-llvm18
dxu@kashmir bpftrace]$ cmake -B build-nix -GNinja
[...]
-- Found LLVM 18.1.7: /nix/store/50fcd75v40wca7vdk9bypgcvv6xhkfhx-llvm-18.1.7-dev/lib/cmake/llvm
[...]
$ nix develop
[dxu@kashmir bpftrace]$ cd build-nix; sudo ctest -V
[...]
$ nix develop .#bpftrace-fuzz
dxu@kashmir bpftrace]$ CC=afl-clang-fast CXX=afl-clang-fast++ cmake -B build-fuzz -DCMAKE_BUILD_TYPE=Debug -DBUILD_ASAN=1
[...]
This section has a few examples on how to interact with the Nix configuration.
Flakes have external inputs in the inputs = { ... } section of flake.nix.
To update a single input:
$ nix flake lock --update-input blazesym
warning: updating lock file '/home/dxu/dev/bpftrace/flake.lock':
• Updated input 'blazesym':
'github:libbpf/blazesym/6beb39ebc8e3a604c7b483951c85c831c1bbe0d1' (2025-02-14)
→ 'github:libbpf/blazesym/285b17f15a12885544b21f1ae352928910656767' (2025-03-04)
To update a single input to a specific revision:
$ nix flake lock --override-input blazesym github:libbpf/blazesym/6beb39ebc8e3a604c7b483951c85c831c1bbe0d1
warning: updating lock file '/home/dxu/dev/bpftrace/flake.lock':
• Updated input 'blazesym':
'github:libbpf/blazesym/285b17f15a12885544b21f1ae352928910656767' (2025-03-04)
→ 'github:libbpf/blazesym/6beb39ebc8e3a604c7b483951c85c831c1bbe0d1' (2025-02-14)
To update all inputs:
$ nix flake update
warning: updating lock file '/home/dxu/dev/bpftrace/flake.lock':
• Updated input 'nixpkgs':
'github:NixOS/nixpkgs/d9b69c3ec2a2e2e971c534065bdd53374bd68b97' (2025-02-24)
→ 'github:NixOS/nixpkgs/02032da4af073d0f6110540c8677f16d4be0117f' (2025-03-03)
*.nix files$ nix fmt
0 / 1 have been reformatted
*.nix files for errors$ nix flake check