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? | | 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 | | `srcs` | `list<path>` | List of paths to source files | yes |
| `deps` | `list<drv>` | List of dependencies (i.e. other Go libraries) | no | | `deps` | `list<drv>` | List of dependencies (i.e. other Go libraries) | no |
| `path` | `string` | Go import path for the resulting library | 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. This is a build system for Common Lisp, written in Nix.
The project is in its early stages and currently supports nothing It aims to offer an alternative to ASDF for users who live in a
other than compiling a bunch of Lisp sources into a combined FASL Nix-based ecosystem. This offers several advantages over ASDF:
file.
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
nix.buildLisp.library { { buildLisp, lispPkgs }:
name = "test-lib";
srcs = [ let libExample = buildLisp.library {
./nix/buildLisp/test-lib.lisp 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.