Build a program from source
A recipe is a package.nami in a folder of its own. nami builds it the way nixpkgs builds its packages, in a sandbox, and you don’t need Nix.
name: helloversion: 2.12.1source: url: https://ftp.gnu.org/gnu/hello/hello-2.12.1.tar.gz sha256: 8d99142afd92576f30b0cd7cb42a8dc6809998bc5d607d88761f512e26c7db20nami build ./packages/hello
built /nix/store/...-hello-2.12.1
hello uses ./configure && make && make install, which the standard build already knows, so the recipe needs nothing more. Building it again does nothing: the same recipe always gives the same result.
Install your package
Install it by its folder. It’s built if needed, then installed.
nami install ./packages/hello
packages: - ripgrep - ./packages/helloAny nami file can list the folder the same way. A plain - hello also finds ./packages/hello, since nami looks in the nearest packages/ folder before the catalog; - nixpkgs:hello is always the catalog’s.
Check a download’s hash
Each download has a sha256:. A download that doesn’t match stops the build and prints the hash it got.
sha256sum hello-2.12.1.tar.gz # or put in any 64 hex digits and copy the real one from the error
A path: ./src source uses a folder next to the recipe instead, and needs no hash.
Add libraries and build tools
Libraries go in deps, and tools needed only for the build go in build-deps. Listing cmake or meson there makes the build use it.
name: zcat-liteversion: "0.1.0" # quote a version YAML would read as a numbersource: path: ./srcbuild-deps: [cmake]deps: [zlib]cmake-flags: [-DGREETING=nami]An entry can be a catalog name, one output of a package (libgcc.lib; nami info lists them), or another recipe’s folder. Only what the result really uses is installed with it, so CMake doesn’t come along.
Change a build step
The standard build runs unpack, patch, configure, build, check, install and fixup. You replace a step only when it doesn’t fit.
name: greetversion: "1.0"source: path: ./srcpatches: [./fix-paths.patch] # applied with patch -p1make-flags: [CC=cc]install: | # replaces the install step install -Dm755 greet $out/bin/greetconfigure-flags, meson-flags, build, check and build-env work the same way; Options has each. build-env is only for the build; a program’s environment when it runs goes in env: in a nami file.
Package a prebuilt program
Many apps come only as a finished program that looks for its libraries in /usr/lib. autoPatchelfHook points it at the libraries in deps instead.
name: bat-binversion: 0.24.0source: url: https://github.com/sharkdp/bat/releases/download/v0.24.0/bat-v0.24.0-x86_64-unknown-linux-gnu.tar.gz sha256: 0faf5d51b85bf81b92495dc93bf687d5c904adc9818b16f61ec2e7a4f925c77abuild-deps: [autoPatchelfHook]deps: [libgcc.lib] # for libgcc_s.so.1install: | install -Dm755 bat $out/bin/batIf a library is missing, the build names it (could not satisfy dependency libfoo.so.1). Find its package with nami search and add it to deps. The vscode example is a full one.
Package a .deb
For an app that’s only in Ubuntu’s archive or on its maker’s site as a .deb, nami recipe from-deb writes the recipe for you.
nami recipe from-deb dctrl-tools # Ubuntu's package, by name
nami recipe from-deb ./vendor-app_2.1_amd64.deb # a file you have
# dctrl-tools: Command-line tools to process Debian package information# Ubuntu noble's package, by `nami recipe from-deb dctrl-tools`.# Check it, then: nami build ./dctrl-toolsname: dctrl-toolsversion: 2.24-3build3source: url: https://archive.ubuntu.com/ubuntu/pool/main/d/dctrl-tools/dctrl-tools_2.24-3build3_amd64.deb sha256: …deps: - glibc # libc.so.6 - tre # libtre.so.5# Programs: grep-dctrl, sort-dctrl, tbl-dctrl, join-dctrlIt turns each library the app needs into a package in deps, and marks what it can’t place NOT FOUND, so read the file before you build it. Pass --release noble to look in another Ubuntu release.
Change a nixpkgs package
extends: rebuilds one of nixpkgs’ packages with your changes. Everything it depends on still comes ready-built.
extends: jqname: jq-patchedpatches: [./nami-help.patch] # added to nixpkgs' own patchesLists such as patches and deps are added to nixpkgs’ own, and source: and the steps replace them. A new version: and source: isn’t enough for Rust and Go packages, which also pin a hash of their dependencies.
Replace a library everywhere
When a library has a security fix the catalog doesn’t have yet, replace: puts your fixed library into every package that uses it, and builds only the library.
replace: libpng: ./packages/libpng-fix # an extends: recipe with the patch, and no name:packages: - gimplibpng replaced in 1 package: gimp
The two libraries’ versions must be the same length (1.6.43 to 1.6.44, not 1.6.9 to 1.6.10), and nami refuses a library that’s missing anything the old one had. When the catalog has the fix, take the line out and run nami apply --upgrade.
Set up the program with its package
A package.nami can also say how its program is set up, with the keys every nami file has, such as services: and files:.
# packages/htop/package.nami: the catalog's htop, set up your way
files:
/etc/htoprc: |
hide_threads=1
A recipe with nothing to build is the catalog’s package of the folder’s name. Its setup goes underneath the file that lists it.
Fix a build that fails
nami prints the last lines of the build’s output and where the whole log is.
| main.c:12:10: fatal error: zlib.h: No such file or directory
build failed (exit status: 2); full log: /nix/var/nami/logs/...-zcat-lite-0.1.0.log
Here zlib is missing from deps. nami build -K keeps the build folder so you can look inside, and NAMI_BUILD_DEBUG=1 logs every command. Builds have no network and see only what they depend on; inside Docker they need --privileged.
Keep your recipes
Put recipes in your config repo under packages/, in a project next to its project.nami, or in a public repository that shares them. nami upgrade builds them again. To build once and install everywhere, see Share builds.