tvl-depot/nix/buildLisp/README.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

118 lines
4.3 KiB
Markdown
Raw Normal View History

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:
```nix
{ 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!)";
};
}
```