5.4 KiB
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:
lispPackagesForlispWithPackages
Finally, there are functions that provide pre-defined Lisps, for people who don't need to customize that:
abclPackages,eclPackages,cclPackages,claspPackages,sbclPackagesabclWithPackages,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)
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.
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 derivations 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 derivations 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:
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.
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.
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 ])'