=== 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/e9a0d500.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] eggRepository attrSet

Builds any eggs in the given `src` directory, producing a compiled egg
repository under `<path>/lib/chicken/<version>` and placing any resulting
binaries under `<path>/bin`.

Apart from `eggCache`, this derivation accepts all the same attributes as
`stdenv.mkDerivation`. If no `name` is given, the string `"eggs"` is used.

The result is suitable for use in the `buildInputs` of an `eggProgram`, in
order to satisfy its egg dependencies. Any dependencies not satisfied by
a compiled `eggRepository` must be provided as sources via `eggCache` so that
all inputs are known at build time.

    # create an extension repository from source
    eggRepository {
      src = ./.;
      eggCache = eggCache { ... };
    }

If any dependencies are missing from both the inputs and cache, the build will
fail with the error message `"extension or version not found: <egg>"`.

    [procedure] eggProgram attrSet

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

The `name` attribute is required. Apart from that, this derivation accepts all
the same attributes as `eggRepository`.

    # build a program entirely from source
    eggProgram {
      name = "example-program";
      src = ./.;
      eggCache = eggCache { ... };
    }

Unlike `eggRepository`, this derivation only includes shared object files in
the repository path. This means that all `egg-info`, `inline` and `link` files
are removed, making the result unsuitable for use in the `builtInputs` of
another `eggProgram`. It should only be used to create executables, not
extension repositories.

Combining the `eggRepository` and `eggProgram` derivations is useful to stage
build operations, for example to avoid rebuilding all egg dependencies
whenever the current source directory changes.

    let
      # pre-compile egg dependencies
      compiledEggs = eggRepository {
        src = eggCache { ... };
      };
    in
      # build program from source
      eggProgram {
        name = "example-program";
        src = ./.;
        buildInputs = [ compiledEggs ];
      }

==== Linking With External Libraries

When linking to external libraries, it's usually enough to use
`buildInputs`. This can either be done when compiling the egg itself, or
when building a program that uses the egg sources.

For example, to build a program using the openssl egg, you can either
build the program and its dependencies (including the OpenSSL library)
from source all at once, or you can compile the openssl egg first, then
link to the result. In either case, the `openssl` package should be
provided in `buildInputs` when building the egg:

    let
      opensslEggDependencies = [ pkgs.openssl pkgs.pkg-config ];
      opensslEggSources = eggCache {
        hash = "sha256-RCjCBvKOFmz92RIP1lP0svxjAC00gAmOLdeAB9PxE+8=";
        eggs = [
          { name = "openssl"; version = "2.2.4"; }
          { name = "srfi-18"; version = "0.1.6"; }
          { name = "address-info"; version = "1.0.5"; }
          { name = "srfi-1"; version = "0.5.1"; }
          { name = "srfi-14"; version = "0.2.1"; }
          { name = "srfi-13"; version = "0.3.3"; }
        ];
      };
      compiledOpensslEgg = eggRepository {
        src = opensslEggSources;
        buildInputs = opensslEggDependencies;
      };
    in {
      # build a program using the openssl egg sources
      fromSourceEgg = eggProgram {
        name = "example-from-source";
        src = ./.;
        eggCache = opensslEggSources;
        buildInputs = opensslEggDependencies;
      };
      # build a program linking to the compiled openssl egg
      fromCompiledEgg = eggProgram {
        name = "example-from-compiled";
        src = ./.;
        buildInputs = [ compiledOpensslEgg ];
      };
    }

=== Development Shell

When using `eggProgram`, the `nix develop` command will start a development
shell that causes CHICKEN to use an isolated build environment.

In this shell, environment variables are set so that CHICKEN will install all
files under a temporary build root, and the `chicken-install` program will
work in offline mode, fetching dependencies only from the given `eggCache`
and not from any network locations.

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