tvl-depot/nix/buildLisp/README.md
Griffin Smith 3089f6b6ce feat(nix/buildLisp): Add abstraction for test suites
Add support for explicitly specifying tests as part of a buildLisp
program or library.

Change-Id: I733213c1618f0fa60f645465560bce0522641efd
Reviewed-on: https://cl.tvl.fyi/c/depot/+/1481
Tested-by: BuildkiteCI
Reviewed-by: tazjin <mail@tazj.in>
2020-07-27 14:18:32 +00:00

4.3 KiB

buildLisp.nix

This is a build system for Common Lisp, written in Nix.

It aims to offer an alternative to ASDF for users who live in a Nix-based ecosystem. This offers several advantages over ASDF:

  • Simpler (logic-less) package definitions
  • Easy linking of native dependencies (from Nix)
  • Composability with Nix tooling for other languages
  • Effective, per-system caching strategies
  • Easy overriding of dependencies and whatnot
  • ... and more!

The project is still in its early stages and some important restrictions should be highlighted:

  • Only SBCL is supported (though the plan is to add support for at least ABCL and Clozure CL, and maybe make it extensible)

Usage

buildLisp exposes four different functions:

  • buildLisp.library: Builds a collection of Lisp files into a library.

    parameter type use required?
    name string Name of the library yes
    srcs list<path> List of paths to source files yes
    deps list<drv> List of dependencies no
    native list<drv> List of native dependencies no
    test see "Tests" Specification for test suite no

    The output of invoking this is a directory containing a FASL file that is the concatenated result of all compiled sources.

  • buildLisp.program: Builds an executable program out of Lisp files.

    parameter type use required?
    name string Name of the program yes
    srcs list<path> List of paths to source files yes
    deps list<drv> List of dependencies no
    native list<drv> List of native dependencies no
    main string Entrypoint function no
    test see "Tests" Specification for test suite no

    The main parameter should be the name of a function and defaults to ${name}:main (i.e. the exported main function of the package named after the program).

    The output of invoking this is a directory containing a bin/${name}.

  • buildLisp.bundled: Creates a virtual dependency on a built-in library.

    Certain libraries ship with Lisp implementations, for example UIOP/ASDF are commonly included but many implementations also ship internals (such as SBCLs various sb-* libraries).

    This function takes a single string argument that is the name of a built-in library and returns a "package" that simply requires this library.

  • buildLisp.sbclWith: Creates an SBCL pre-loaded with various dependencies.

    This function takes a single argument which is a list of Lisp libraries programs or programs. It creates an SBCL that is pre-loaded with all of that Lisp code and can be used as the host for e.g. Sly or SLIME.

Tests

Both buildLisp.library and buildLisp.program take an optional argument tests, which has the following supported fields:

parameter type use required?
name string Name of the test suite no
expression string Lisp expression to run tests yes
srcs list<path> List of paths to source files no
native list<drv> List of native dependencies no

the expression parameter should be a Lisp expression and will be evaluated after loading all sources and dependencies (including library/program dependencies). It must return a non-NIL value if the test suite has passed.

Example

Using buildLisp could look like this:

{ buildLisp, lispPkgs }:

let libExample = buildLisp.library {
    name = "lib-example";
    srcs = [ ./lib.lisp ];

    deps = with lispPkgs; [
      (buildLisp.bundled "sb-posix")
      iterate
      cl-ppcre
    ];
};
in buildLisp.program {
    name = "example";
    deps = [ libExample ];
    srcs = [ ./main.lisp ];
    tests = {
      deps = [ lispPkgs.fiveam ];
      srcs = [ ./tests.lisp ];
      expression = "(fiveam:run!)";
    };
}