Beaker

Lab supplies for CHICKEN Scheme.

  1. Beaker
  2. Description
  3. Dependencies
  4. Programs
    1. chicken-clean
    2. chicken-lint
    3. chicken-lock
  5. Extensions
    1. Repository Management
    2. Systems
  6. Nix Helpers
    1. Usage
    2. Fetching Egg Dependencies
      1. Combining Multiple Egg Caches
    3. Building Eggs
    4. Examples
  7. Links
  8. Author
  9. License

Description

Beaker is a collection of development tools.

It is currently fairly limited, including only a few programs and a handful of libraries to make common development tasks easier. If you have an idea for something that would be useful to include, don't hesitate to contact the author.

The project's source is available here.

Dependencies

Programs

chicken-clean

Usage: chicken-clean [-interactive | -quiet | -verbose]

The chicken-clean program deletes egg build artifacts.

A simple set of file patterns is used to determine what should be deleted. This includes compiled programs, binary objects (o, obj, so, dll), and files generated by the CHICKEN toolchain (build.sh, install.sh, import.scm, inline, profile, types).

When run with the -interactive flag, a confirmation prompt will be displayed before any files are deleted.

chicken-lint

Usage: chicken-lint [csc-options ...] filename ...

The chicken-lint program checks a source file with a set of simple lint rules.

Potential problems are written as S-expressions to standard error.

Note that this program invokes csc, so any compile-time code in the program will be executed.

chicken-lock

Usage: chicken-lock [egg ...]

The chicken-lock program generates a snapshot of all dependency versions for the given eggs, or for any egg files in the current directory.

The output is an override file that can then be used to install those same versions later on via the "-override" or "-from-list" flags to chicken-install. For example, you can record the current version of the r7rs egg and all of its dependencies, and then restore them later, like this:

$ chicken-lock r7rs > r7rs.lock
... time passes...
$ chicken-install -from-list r7rs.lock

If no egg names are given on the command line, this program will look for egg files in the current directory. This can be used to record the current version of all dependencies for an egg in local development:

$ cat example.egg
((synopsis "A nice example library")
 (build-dependencies matchable)
 (dependencies r7rs)
 (components (extension example)))
$ chicken-lock > example.egg.lock
... time passes ...
$ chicken-install -override example.egg.lock

Any extra arguments are passed through to chicken-install when fetching eggs. So, you can use "-override" to fix some subset of an egg's dependency versions when generating the snapshot, as well as other options like "-verbose" to print more information about what's happening.

Extensions

Repository Management

The (beaker repository) library provides a handful of procedures to help manage egg repositories.

[procedure] (chicken-install)

Returns the full pathname of the chicken-install command.

[procedure] (chicken-status)

Returns the full pathname of the chicken-status command.

[procedure] (egg-files #!optional (path repository-path))

Returns a list of all egg-info files in the repository path.

The path argument can be used to specify an alternative repository path, which should be a thunk returning a list of pathname strings.

[procedure] (repair-repository #!optional (path repository-path))

Installs any missing dependencies for the eggs in the repository path.

The path argument can be used to specify an alternative repository path, which should be a thunk returning a list of pathname strings.

If there are any missing dependencies, they are installed into the first repository in the path and a list of newly-installed eggs is returned.

If there are no missing dependencies, nothing is done and an empty list is returned.

[procedure] (create-repository destination #!optional source)

Initialises a new egg repository at the pathname destination.

If the directory destination doesn't exist, it is created. The core CHICKEN libraries are then installed into the repository and a new modules database is generated

If a source repository is given, its contents are also copied into the new repository. This can be used to copy an existing repository to another location.

Systems

The (beaker system) library provides an API for dynamically building, loading, and reloading extension libraries. It's intended to help enable rapid development in a manner similar to asdf from Common Lisp or the system egg from CHICKEN 4.

Rather than introduce a new way to define a system's components and dependencies, this library reuses the egg specification format. In fact, you can generally think of a "system" and an "egg" as one and the same.

An example csi session that loads, edits, and reloads an example system might look like the following:

#;> (import (beaker system))
#;> (load-system "example.egg")
building example
... output ...
; loading /tmp/temp70d6.29489.example.import.so ...
; loading /tmp/temp4871.29489.example.so ...
#;> (load-system "example.egg")
building example
#;> ,e example.scm
#;> (load-system "example.egg")
building example
... output ...
; loading /tmp/temp44a2.29609.example.so ...

Modules are imported automatically and import libraries are reloaded whenever a module's exports list changes. Note that removing a value from a module's export list does not remove it from the session when the extension is reloaded.

[procedure] (compile-system egg-file)

Compiles all out-of-date components for the given egg.

This is equivalent to running chicken-install -no-install.

[procedure] (clean-system egg-file)

Deletes all compiled programs and extension libraries for the given egg.

Auxiliary files such as import libraries are preserved.

[procedure] (load-system egg-file #!key (skip (quote ())))

Builds and loads the given egg.

When called for the first time, all out-of-date components are recompiled, the egg's extension libraries are loaded into the calling program and its modules are immediately imported.

Subsequent calls cause the components to be recompiled and reloaded as necessary.

Nix Helpers

This project also includes some helper functions for the Nix package manager that make it easy to build CHICKEN programs.

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.

Author

Evan Hanson

License

Copyright (c) 2015-2021, Evan Hanson <evhan@foldling.org>
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

  * Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
  * Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.
  * The name of the author may not be used to endorse or promote products
    derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.