nixpkgs/pkgs/development/lisp-modules-new/doc/api.md

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 differrent 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 ])'