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>

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/