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