Reader and Pins File
The Reader lives at nix/pins.nix in the source repository. It reads schema v2 Pins Files and converts locked Fetcher arguments and real hashes into Nix inputs.
Arguments
| Argument | Default | Meaning |
|---|---|---|
pkgs | Required | Nixpkgs package set compatible with the configuration |
file | pins.json in the Reader's parent directory | Pins File to read; usually supplied explicitly |
config | null | Optional Pin configuration for restoring patched sources and Packages |
let
pkgs = import <nixpkgs> {};
pins = import ../nix/pins.nix {
inherit pkgs;
file = ./pins.json;
config = ./pins-config.nix;
};
in
pins.patchelf.sources.default.src
Relative paths resolve from the location of this Nix file. ../nix/pins.nix is the Reader path used by the quick start. Other projects should replace it with their own pinned tool source path.
Return structure
| Path | Contents |
|---|---|
pins.<pin>.version | Original locked Version |
pins.<pin>.sources.<source>.src | Nix source derivation; may include patches when configuration is supplied |
pins.<pin>.sources.<source>.hash | Real hash of the original Fetcher contents |
pins.<pin>.sources.<source>.fetcher | Persisted Fetcher arguments |
pins.<pin>.sources.<source>.derived | Derived hash attribute set; defaults to {} |
pins.<pin>.sources.<source>.packages.<package> | Package restored from configuration; available only when config is supplied |
Even with a single Source, the access path includes sources.default. Do not use the old flat pins.<pin>.src path.
When to pass configuration
With only file, the Reader restores the original locked source. It does not provide Packages or apply declared patches. With config, it reevaluates the configuration using the locked versions and hashes to restore patched Sources and Packages.
The Reader does not check upstream versions again. Only update changes locked results. Pin the configuration, Pins File, Reader version, and required Nixpkgs inputs together.
File compatibility
The current Reader only accepts schemaVersion = 2. Incompatible versions cause an error; changing the schema number manually is not a migration. See Updating and selecting Pins for failure records and update semantics.