Your first Pin

This tutorial uses NixOS/patchelf to demonstrate the complete workflow. GitHub is the starting example; nix-pins also supports other version checkers and fetchers.

Create a declaration

After installation, create a working directory at the root of your cloned nix-pins repository:

mkdir -p demo
cd demo

Create pins-config.nix:

{ pin }: {
  patchelf = pin.github "NixOS/patchelf";
}

patchelf is the local Pin name. pin.github reads the latest GitHub release, uses its original tag as the Version, and fetches source code at that tag. This shorthand creates a Source named default.

Update and inspect

nix-pins update
nix-pins status

By default, the CLI reads pins-config.nix from the current directory and writes the result to pins.json. update checks versions over the network and computes source hashes. status reports existing locked results without checking for new upstream versions.

The main paths in pins.json are pins.patchelf.version and pins.patchelf.sources.default. A Source contains Fetcher arguments, the source hash, and optional derived hashes. Commit the configuration and Pins File together so downstream consumers use the same locked results.

Use the result in Nix

Create source.nix in demo/. The path ../nix/pins.nix points to the Reader in the cloned tool repository:

let
  pkgs = import <nixpkgs> {};
  pins = import ../nix/pins.nix {
    inherit pkgs;
    file = ./pins.json;
  };
in
pins.patchelf.sources.default.src

Build the locked source:

nix build --impure --file source.nix --no-link

A downstream derivation can use this src as an input, for example in pkgs.stdenv.mkDerivation:

{
  pname = "patchelf";
  version = pins.patchelf.version;
  src = pins.patchelf.sources.default.src;
}

This snippet only shows the input attributes. The downstream project defines the full application build. When you add Packages or patches, the Reader also needs the config argument; see the Reader reference.

Update next time

nix-pins update patchelf

Review the changes to pins.json, then rebuild the downstream package. Other upstream sources do not need to use GitHub: combine a Checker and Fetcher independently with pin.mk, as shown in Combining Checkers and Fetchers.