~evhan/beaker

beaker/nix.md -rw-r--r-- 3.0 KiB
ca9604fcEvan Hanson Add links to example uses of Nix helpers 1 year, 6 months ago

=== Usage

The helpers can be imported directly from the Git repository archive:

let
  beaker = import (fetchTarball https://git.sr.ht/~evhan/beaker/archive/master.tar.gz) {};
in
  doStuff { with beaker; ... }

This library only includes two attributes, so it's also relatively harmless to pull into scope, for example:

with import (fetchTarball https://git.sr.ht/~evhan/beaker/archive/3679375a.tar.gz) {};

eggProgram {
  name = "example";
  src = ./.;
  eggCache = eggCache {
    eggs = ./example.egg.lock;
    hash = "sha256:00x5k7rhs1fy7fj5kma1yp2ikzbq98bfm33si5y8z8m25chb45sg";
  };
}

=== Fetching Egg Dependencies

[procedure] eggCache attrSet

A fixed-output derivation that fetches a set of eggs for installation.

The list of eggs to cache should be specified via eggs, which expects a path to a file in "override" format specifying a list of egg names and versions. This file can be generated via chicken-status -list (for all installed eggs) or chicken-lock (for a specific egg's dependencies).

eggCache {
  name = "example-egg-cache";
  hash = "sha256:03pz5927dkazrf8hf53w03r80ca98fwp09gmd8iiywxc5vl8ll2m";
  eggs = ./eggs.lock;
}

Alternatively, you can specify the list of eggs directly:

eggCache {
  name = "example-egg-cache";
  hash = "sha256:01fq1398aj4r54yw6ym8i56i236yb3pvmn6a54iahz09cp615g2x";
  eggs = [
    { name = "srfi-18"; version = "0.1"; }
    { name = "srfi-69"; version = "0.4"; }
  ];
}

==== Combining Multiple Egg Caches

To merge multiple egg caches, you can use symlinkJoin:

pkgs.symlinkJoin {
  name = "example-egg-caches";
  paths = [
    (eggCache { ... })
    (eggCache { ... })
  ];
}

The result will be a single egg cache containing all of the specified eggs. Note that if any input paths contain different versions of the same egg, the first one listed takes precedence.

=== Building Eggs

[procedure] eggProgram attrSet

Builds any eggs in the given src directory, bundling all dependencies and placing the resulting binaries into <path>/bin.

Egg dependencies must be provided via eggCache so that all inputs are known at build time. If any dependencies are missing from the cache, the build will fail with the error message "extension or version not found: <egg>".

eggProgram {
  name = "example-program";
  src = ./.;
  eggCache = eggCache { ... };
}

Apart from eggCache, this derivation accepts all the same attributes as stdenv.mkDerivation.

=== Examples

These eggs provide examples of using these Nix functions:

In each of these projects, the lock file that's used to populate the eggCache has been created by running chicken-lock > ${name}.egg.lock, and then checking that file in to source control.