about summary refs log tree commit diff
path: root/nix/buildLisp
diff options
context:
space:
mode:
authorsterni <sternenseemann@systemli.org>2021-08-26T10·59+0200
committersterni <sternenseemann@systemli.org>2021-08-26T11·26+0000
commit2f447438240559231d4643c1230da6e01f46ff99 (patch)
treeb7710cbf1288fcb945554ea025b825b6d313a8c5 /nix/buildLisp
parentea6ee1e2196516775a41adc6d698fe4f83e5cbb2 (diff)
docs(nix/buildLisp): document NIX_BUILDLISP_LISP_ARGS r/2779
Change-Id: I54294da08ee08bcf6cba6c792a2a2235b988a778
Reviewed-on: https://cl.tvl.fyi/c/depot/+/3422
Tested-by: BuildkiteCI
Reviewed-by: tazjin <mail@tazj.in>
Diffstat (limited to 'nix/buildLisp')
-rw-r--r--nix/buildLisp/README.md24
1 files changed, 24 insertions, 0 deletions
diff --git a/nix/buildLisp/README.md b/nix/buildLisp/README.md
index 02435595ff1b..214700750d7f 100644
--- a/nix/buildLisp/README.md
+++ b/nix/buildLisp/README.md
@@ -224,6 +224,30 @@ This only influences `meta.targets` which is read by depot's CI to
 check which variants (see "Implementations") of the derivation to
 build, so it may not be useful outside of depot.
 
+## Influencing the Lisp Runtime
+
+Lisp implementations which create an executable by dumping an image
+usually parse a few implementation-specific command line options on
+executable startup that influence runtime settings related to things
+like GC. `buildLisp` generates a wrapper which makes sure that this
+never interferes with the argument parsing implemented in the actual
+application, but sometimes it is useful to run an executable with
+special settings. To allow this, the content of `NIX_BUILDLISP_LISP_ARGS`
+is passed to the lisp implementation.
+
+For example, you can make the underlying SBCL print its version for
+any executable built with `buildLisp` (and SBCL) like this:
+
+```console
+$ env NIX_BUILDLISP_LISP_ARGS="--version" ./result/bin/🕰️
+SBCL 2.1.2.nixos
+```
+
+In practice you'd probably want to specify options like
+`--dynamic-space-size` or `--tls-limit` (try passing `--help` for a
+full list). Naturally, these options are completely different for
+different implementations.
+
 [sbcl]: http://www.sbcl.org/
 [ccl]: https://ccl.clozure.com/
 [ecl]: https://common-lisp.net/project/ecl/