NIXTAMAL MANIFEST(5)()

NAME

Nixtamal Manifest(5) - Setting up for pinning down inputs

SYNOPSIS

Nixtamal uses KDL for its manifest describing inputs. At the highest level, this includes:

manifest version
default hashing algorithm
patches (optional)
list of inputs

the input kind & its specific attributes
a command to check if ‘fresh’
hashing information
patches to apply to the input

NOTE:

A KDL Schema file is shipped alongside this documentation for use with schema-aware editors and validators. It can be found in the installation directory under share/nixtamal/nixtamal-manifest.schema.

DEFAULT MANIFEST.KDL

version "0.4.0"
inputs {

        nixpkgs {

                archive {

                        url "https://github.com/NixOS/nixpkgs/archive/{{fresh_value}}.tar.gz"

                }

                hash algorithm=SHA-256

                fresh-cmd {

                        $ git ls-remote "https://github.com/NixOS/nixpkgs.git" --refs "refs/heads/nixos-unstable"

                        | cut -f1

                }

        }
}

TOP-LEVEL NODES

version: Version of the Nixtamal spec the manifest.kdl is using.
default-hash-algorithm: Hash algorithm to use by default for inputs when the input does not note its hash algorithm. Defaults to SHA-256.
patches: Map of patches to be applied to inputs where the patch name should be unique. Each patch has a URL (first argument). See Patches.
inputs: Map of inputs to be pinned where the input+node name should be unique & will be used in the Nix output as well as logs & errors. These nodes also can have a frozen property to be skipped during refreshes. See Input node.

PATCHES

Patches are defined at the top-level and can be applied to any input. This allows defining a patch once and applying it to multiple inputs.

url: Templated node URL or file reference for the patch. Supports https://, http://, and file:// URLs.
hash: Optional node for hash algorithm information. The algorithm property will be used when prefetching, locking, & for integrity verification. The optional expected property may be used to assert a known hash. If not specified, no hash verification is performed. Defaults to the top-level default-hash-algorithm or SHA-256.

INPUT NODE

At a high level these should be seen as

“kind”: There are specific nodes for each different type of supported fetchers/prefetchers: file, archive, git, darcs, pijul (with more to come in the future).
hash: An optional node for hash algorithm information for a input. The algorithm property will be used when prefetching, locking, & for importing (which falls back to top-level default-hash-algorithm or defined default SHA-256). The optional expected property may be used to assert a known hash.
CAUTION!:

The bootstrapping Nixpkgs pin (either manually set or using nixpkgs-nixtamal or nixpkgs as defaults) must be SHA-256 to be compatible with builtins.fetchTarball.

fresh-cmd: Command (with or without pipes using $ & | nodes) that can shelled out to to return a string that will be locked as the fresh command value which can be used both to prevent unnecessary prefectching, but also for use in a Templated node.
patches: List of patch names (as arguments) to apply to this input. Patches are defined at the top-level in the Patches section.

File

url: Templated node URL reference for the input
mirrors: Templated node URL mirror references for the input

Git

repository: Templated node repository reference for the input
mirrors: Templated node repository mirror references for the input
WARNING:

Probably not yet supported upstream.

“reference”: branch or ref node as the reference point for getting stable reference
submodules: Leaf node for enabling submodules on a repository
lfs: Leaf node for enabling Git LFS on a repository

Darcs

repository: Templated node repository reference for the input
mirrors: Templated node repository mirror references for the input
NOTE:

Recently upstreamed. See: <https://github.com/NixOS/nixpkgs/pull/467172>

“reference”: context or tag node as the reference point for getting stable reference; in the case of Darcs, if neither is supplied a context will be assumed & copied from nix-prefetch-darcs

Pijul

remote: Templated node remote reference for the input
mirrors: Templated node remote mirror references for the input
NOTE:

Recently upstreamed. See: <https://github.com/NixOS/nixpkgs/pull/467890>

“reference”: channel or state or change (not recommended) node as the reference point for getting stable reference; if unsure, try channel main

TEMPLATED NODE

Some nodes have values with string substitution via Jingoo <https://tategakibunko.github.io/jingoo/templates/templates.en.html> , which is probably overkill, but could give you flexibilty with if statements. The templated nodes include:

inputs >> file > url
inputs >> file > mirrors
inputs >> archive > url
inputs >> archive > mirrors
inputs >> git > repository
inputs >> git > mirrors
inputs >> darcs > repository
inputs >> darcs > mirrors
inputs >> pijul > remote
inputs >> pijul > mirrors
inputs >> fresh-cmd > $
inputs >> fresh-cmd > |

The input kind affects the values for substition:

FILE

Key	Type	Description
name	string	input name
fresh_value	string nullable	fresh command return value

GIT

Key	Type	Description
name	string	input name
fresh_value	string nullable	fresh command return value
branch	string nullable	branch name
ref	string nullable	reference name
datetime	string nullable	Datetime of latest revision
lfs	bool	repository uses LFS
submodules	bool	repository uses submodules
rev / revision	string nullable	latest revision

DARCS

Key	Type	Description
name	string	input name
fresh_value	string nullable	fresh command return value
context	string nullable	path to context file
tag	string nullable	tag
datetime	string nullable	datetime of latest patch
weak_hash	string nullable	latest weak hash of the repository

PIJUL

Key	Type	Description
name	string	input name
fresh_value	string nullable	fresh command return value
channel	string nullable	remote channel
change	string nullable	change
datetime	string nullable	datetime of latest patch
state	string nullable	latest state of the remote or supplied state

INPUT SHOWCASE

Darcs using exposed WeakHash to avoid needless refresh

nixtamal {

        darcs {

                repository "https://darcs.toastal.in.th/nixtamal/stable/"

                mirrors "https://smeder.ee/~toastal/nixtamal.darcs"

        }

        fresh-cmd {

                $ curl -sL "https://darcs.toastal.in.th/nixtamal/stable/_darcs/weak_hash"

        }
}

File with mirror + templated nodes

mozilla-tls-guidelines {

        file {

                url "https://ssl-config.mozilla.org/guidelines/{{fresh_value}}.json"

                mirrors "https://raw.githubusercontent.com/mozilla/ssl-config-generator/refs/tags/v{{fresh_value}}/src/static/guidelines/{{fresh_value}}.json"

        }

        fresh-cmd {

                $ curl -sL "https://wiki.mozilla.org/Security/Server_Side_TLS"

                | htmlq -w -t "table.wikitable:last-of-type > tbody > tr:nth-child(2) > td:first-child"

                | head -n1

        }
}

Local directory checking for latest modification

soupault-plugins {

        file {

                url "file:///home/toastal/my-project"

        }

        fresh-cmd {

                $ find "/home/toastal/my-project" "-print0"

                | xargs "-0" stat -c %Y

                | sort -n

                | tail -n1

        }
}

Basic Pijul with BLAKE3 hash

pijul {

        pijul {

                remote "https://nest.pijul.com/pijul/pijul"

                channel main

        }

        hash algorithm=BLAKE3
}

Inputs with patches

patches {

        nixpkgs-pr123 "https://github.com/NixOS/nixpkgs/pull/123.diff"

        my-fix "./patches/my-fix.patch"
}
inputs {

        nixpkgs {

                git {

                        repository "https://github.com/NixOS/nixpkgs.git"

                        ref "refs/heads/nixos-unstable"

                }

                patches "nixpkgs-pr123" "my-fix"

        }

        nixpkgs-stable {

                git {

                        repository "https://github.com/NixOS/nixpkgs.git"

                        ref "refs/heads/nixos-24.05"

                }

                patches "my-fix"

        }
}

Local patches (starting with ./ or ../) are applied directly from the repository and & be tracked by your VCS. “Remote” patches (meaning not local to the repository such as HTTPS, absolute paths with file:, & so forth) are fetched & hashed during nixtamal lock.

AUTHOR

toastal