=== 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";
      };
    }

You can use a specific version of the Nix packages collection by setting the
`pkgs` property in the import statement. By default, the `<nixpkgs>` path is
used.

=== 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:

* [dust](https://git.sr.ht/~evhan/dust/tree/master/item/default.nix)
* [sourcehut](https://git.sr.ht/~evhan/chicken-sourcehut/tree/master/item/default.nix)
* [sq](https://hg.sr.ht/~evhan/sq/browse/default.nix?rev=tip)

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.