mdebray/tvl-depot
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(nix/buildLisp): Update the README with actual docs

Browse source
This commit is contained in:
Vincent Ambo 2020-01-29 00:03:24 +00:00
parent 39b0176026
commit 0001dfd7f6
2 changed files with 87 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
nix/buildGo/README.md
View file

@ -85,7 +85,7 @@ in buildGo.program {
| parameter | type | use | required? |
|-----------|--------------|------------------------------------------------|-----------|
| `name` | `string` | Name of the library (and resulting executable) | yes |
| `name` | `string` | Name of the library | yes |
| `srcs` | `list<path>` | List of paths to source files | yes |
| `deps` | `list<drv>` | List of dependencies (i.e. other Go libraries) | no |
| `path` | `string` | Go import path for the resulting library | no |

97
nix/buildLisp/README.md
View file

@ -3,19 +3,94 @@ buildLisp.nix
This is a build system for Common Lisp, written in Nix.
The project is in its early stages and currently supports nothing
other than compiling a bunch of Lisp sources into a combined FASL
file.
It aims to offer an alternative to ASDF for users who live in a
Nix-based ecosystem. This offers several advantages over ASDF:
This is what it currently looks like:
* 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:
* There is no separate abstraction for tests at the moment (i.e. they
are built and run as programs)
* 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 |
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 |
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.
## Example
Using buildLisp could look like this:
```nix
nix.buildLisp.library {
name = "test-lib";
srcs = [
./nix/buildLisp/test-lib.lisp
];
{ 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 ];
}
```
Check back here in a few days for more information.