From 0001dfd7f6e1d2c782d80c49d3148408287af8d4 Mon Sep 17 00:00:00 2001
From: Vincent Ambo <tazjin@google.com>
Date: Wed, 29 Jan 2020 00:03:24 +0000
Subject: docs(nix/buildLisp): Update the README with actual docs

---
 nix/buildLisp/README.md | 97 +++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 86 insertions(+), 11 deletions(-)

(limited to 'nix/buildLisp')

diff --git a/nix/buildLisp/README.md b/nix/buildLisp/README.md
index 513656f570..8e45f3479c 100644
--- a/nix/buildLisp/README.md
+++ b/nix/buildLisp/README.md
@@ -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.
-- 
cgit 1.4.1