+
+ + 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/manifest.kdl.
+
+ +
+
+ Default + manifest.kdl +
+
+
+
+
+
+
+ version "0.5.0"
+inputs {
+
+ nixpkgs {
+
+ archive {
+
+ url "https://github.com/NixOS/nixpkgs/archive/{{fresh_value}}.tar.gz"
+
+ }
+
+ hash algorithm=SHA-256
+
+ fetch-time eval
+
+ 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. + +
- + default-fetch-time + +
- + Default fetch time for inputs when not specified at the input level. Can + be eval (fetch during Nix evaluation using builtins.fetch*) + or build (fetch during build using pkgs.fetch*). Defaults to + eval. + +
- + 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. See + Input node. + +
+
+ Fetch + Time +
++ Inputs can be fetched either during Nix evaluation or during build + time: +
+
+
+ -
+
- + eval + +
- + Fetch the input during Nix evaluation using builtins.fetch* + functions. This is the default behavior and is suitable for inputs that + need to be available during evaluation, such as the bootstrap + Nixpkgs. + +
- + build + +
- + Fetch the input during build time using pkgs.fetch* functions. This + is suitable for most inputs and allows for better caching and parallel + fetching. + +
+
+ The fetch time can be set globally using default-fetch-time + or per-input using the fetch-time property on file, + archive, and git input types. +
++ Caution!: +
+
+
+
+
+ Inputs with patches cannot use eval fetch time, as
+ patches are applied during build time. The system will automatically enforce
+ this constraint.
+
+ +
+
+ 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 +
+
+
+
+ -
+
- + prop: + frozen + +
- + A boolean (frozen=#true) that prevents trying refresh or otherwise + get a new fresh value for this input. + +
- + âkindâ + +
- + There are specific nodes for each different type of supported + fetchers/prefetchers: file, archive, git, + darcs, pijul, fossil (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 +
+
+
+ -
+
- + prop: + fetch-time + +
- + Property to set when to fetch this input: eval or build. + Defaults to the top-level default-fetch-time or build. + +
- + url + +
- + Templated node URL reference for the input + +
- + mirrors + +
- + Templated node URL mirror references for the input + +
+
+ Archive +
+
+
+ -
+
- + prop: + fetch-time + +
- + Property to set when to fetch this input: eval or build. + Defaults to the top-level default-fetch-time or build. + +
- + url + +
- + Templated node URL reference for the input + +
- + mirrors + +
- + Templated node URL mirror references for the input + +
+
+ Git +
+
+
+
+ -
+
- + prop: + fetch-time + +
- + Property to set when to fetch this input: eval or build. + Defaults to the top-level default-fetch-time or build. + +
- + 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 tag or ref node as the + reference point for getting stable reference. tag provides + convenience over using ref with full tag paths. + +
- + 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 + +
+
+ Fossil +
+
+
+ -
+
- + repository + +
- + Templated node repository reference for the input + +
- + âreferenceâ + +
- + branch or tag or check-in node as the + reference point for getting stable reference + +
+
+ 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 >> fossil > repository + +
- + 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 + | +
+ archive +
+| + 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 + | +
+ fossil +
+| + Key + | ++ Type + | ++ Description + | +
| + name + | ++ string + | ++ input name + | +
| + fresh_value + | ++ string nullable + | ++ fresh command return value + | +
| + branch + | ++ string nullable + | ++ branch name + | +
| + tag + | ++ string nullable + | ++ tag + | +
| + checkin + | ++ string nullable + | ++ check-in + | +
| + date + | ++ string nullable + | ++ date of latest patch + | +
+ 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"
+
+ }
+}
+
+ +
+
+ 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
+
+ }
+}
+
+ +
+
+ Eval + time file with mirror + templated nodes +
+
+
+
+
+
+
+ mozilla-tls-guidelines {
+
+ file fetch-time=eval {
+
+ 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
+
+ }
+}
+
+ +
+
+ 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 +
+| + | + 0.5.0 + | +