tjh.dev
1## The API
2
3This page documents the Nix API of nix-cl.
4
5## Overview
6
7The core API functions are `build-asdf-system` and
8`lispWithPackagesInternal`.
9
10They are considered more low-level that the rest of the API, which
11builds on top of them to provide a more convenient interface with sane
12defaults.
13
14The higher-level API provides a lot of pre-configured packages,
15including all of Quicklisp, and consists of the functions:
16
17- `lispPackagesFor`
18- `lispWithPackages`
19
20Finally, there are functions that provide pre-defined Lisps, for
21people who don't need to customize that:
22
23- `abclPackages`, `eclPackages`, `cclPackages`, `claspPackages`, `sbclPackages`
24- `abclWithPackages`, `eclWithPackages`, `cclWithPackages`, `claspWithPackages`, `sbclWithPackages`
25
26The following is an attempt to document all of this.
27
28## Packaging systems - `build-asdf-system`
29
30Packages are declared using `build-asdf-system`. This function takes
31the following arguments and returns a `derivation`.
32
33#### Required arguments
34
35##### `pname`
36Name of the package/library
37
38##### `version`
39Version of the package/library
40
41##### `src`
42Source of the package/library (`fetchzip`, `fetchgit`, `fetchhg` etc.)
43
44##### `lisp`
45This command must load the provided file (`$buildScript`) then exit
46immediately. For example, SBCL's --script flag does just that.
47
48#### Optional arguments
49
50##### `patches ? []`
51
52Patches to apply to the source code before compiling it. This is a
53list of files.
54
55##### `nativeLibs ? []`
56
57Native libraries, will be appended to the library
58path. (`pkgs.openssl` etc.)
59
60##### `javaLibs ? []`
61
62Java libraries for ABCL, will be appended to the class path.
63
64##### `lispLibs ? []`
65
66Lisp dependencies These must themselves be packages built with
67`build-asdf-system`
68
69##### `systems ? [ pname ]`
70
71Some libraries have multiple systems under one project, for example,
72[cffi] has `cffi-grovel`, `cffi-toolchain` etc. By default, only the
73`pname` system is build.
74
75`.asd's` not listed in `systems` are removed before saving the library
76to the Nix store. This prevents ASDF from referring to uncompiled
77systems on run time.
78
79Also useful when the `pname` is differrent than the system name, such
80as when using [reverse domain naming]. (see `jzon` ->
81`com.inuoe.jzon`)
82
83[cffi]: https://cffi.common-lisp.dev/
84[reverse domain naming]: https://en.wikipedia.org/wiki/Reverse_domain_name_notation
85
86##### `asds ? systems`
87
88The .asd files that this package provides. By default, same as
89`systems`.
90
91#### Return value
92
93A `derivation` that, when built, contains the sources and pre-compiled
94FASL files (Lisp implementation dependent) alongside any other
95artifacts generated during compilation.
96
97#### Example
98
99[bordeaux-threads.nix] contains a simple example of packaging
100`alexandria` and `bordeaux-threads`.
101
102[bordeaux-threads.nix]: /examples/bordeaux-threads.nix
103
104## Building a Lisp with packages: `lispWithPackagesInternal`
105
106Generators of Lisps configured to be able to `asdf:load-system`
107pre-compiled libraries on run-time are built with
108`lispWithPackagesInternal`.
109
110#### Required Arguments
111
112##### `clpkgs`
113
114An attribute set of `derivation`s returned by `build-asdf-system`
115
116#### Return value
117
118`lispWithPackagesInternal` returns a function that takes one argument:
119a function `(lambda (clpkgs) packages)`, that, given a set of
120packages, returns a list of package `derivation`s to be included in
121the closure.
122
123#### Example
124
125The [sbcl-with-bt.nix] example creates a runnable Lisp where the
126`bordeaux-threads` defined in the previous section is precompiled and
127loadable via `asdf:load-system`:
128
129[sbcl-with-bt.nix]: /examples/sbcl-with-bt.nix
130
131## Reusing pre-packaged Lisp libraries: `lispPackagesFor`
132
133`lispPackagesFor` is a higher level version of
134`lispPackagesForInternal`: it only takes one argument - a Lisp command
135to use for compiling packages. It then provides a bunch of ready to
136use packages.
137
138#### Required Arguments
139
140##### `lisp`
141
142The Lisp command to use in calls to `build-asdf-system` while building
143the library-provided Lisp package declarations.
144
145#### Return value
146
147A set of packages built with `build-asdf-system`.
148
149#### Example
150
151The [abcl-package-set.nix] example generates a set of thousands of packages for ABCL.
152
153[abcl-package-set.nix]: /examples/abcl-package-set.nix
154
155## Reusing pre-packaged Lisp libraries, part 2: `lispWithPackages`
156
157This is simply a helper function to avoid having to call
158`lispPackagesFor` if all you want is a Lisp-with-packages wrapper.
159
160#### Required Arguments
161
162##### `lisp`
163
164The Lisp command to pass to `lispPackagesFor` in order for it to
165generate a package set. That set is then passed to
166`lispWithPackagesInternal`.
167
168#### Return value
169
170A Lisp-with-packages function (see sections above).
171
172#### Example
173
174The [abcl-with-packages.nix] example creates an `abclWithPackages` function.
175
176[abcl-with-packages.nix]: /examples/abcl-with-packages.nix
177
178## Using the default Lisp implementations
179
180This is the easiest way to get going with `nix-cl` in general. Choose
181the CL implementation of interest and a set of libraries, and get a
182lisp-with-packages wrapper with those libraries pre-compiled.
183
184#### `abclPackages`, `eclPackages`, `cclPackages`, `claspPackages`, `sbclPackages`
185
186Ready to use package sets.
187
188#### `abclWithPackages`, `eclWithPackages`, `cclWithPackages`, `claspWithPackages`, `sbclWithPackages`
189
190Ready to use wrapper generators.
191
192#### Example
193
194For example, to open a shell with SBCL + hunchentoot + sqlite in PATH:
195```
196nix-shell -p 'with import ./. {}; sbclWithPackages (ps: [ ps.hunchentoot ps.sqlite ])'
197```