doc/lisp: add links to sections and upstream websites
Also clean up complex paragraphs and fix section on building wrappers
This commit is contained in:
Kasper Gałkowski
parent
b991ea8385
commit
9ce6e34ddf
1 changed files with 29 additions and 51 deletions
|
|
@ -1,36 +1,32 @@
|
|||
# lisp-modules {#lisp}
|
||||
|
||||
This document describes the Nixpkgs infrastructure for building Common Lisp
|
||||
libraries that use ASDF (Another System Definition Facility). It lives in
|
||||
`pkgs/development/lisp-modules`.
|
||||
systems that use [ASDF](https://asdf.common-lisp.dev/) (Another System
|
||||
Definition Facility). It lives in `pkgs/development/lisp-modules`.
|
||||
|
||||
## Overview {#lisp-overview}
|
||||
|
||||
The main entry point of the API are the Common Lisp implementation packages
|
||||
themselves (e.g. `abcl`, `ccl`, `clasp-common-lisp`, `clisp` `ecl`,
|
||||
themselves (e.g. `abcl`, `ccl`, `clasp-common-lisp`, `clisp`, `ecl`,
|
||||
`sbcl`). They have the `pkgs` and `withPackages` attributes, which can be used
|
||||
to discover available packages and to build wrappers, respectively.
|
||||
|
||||
The `pkgs` attribute set contains packages that were automatically imported from
|
||||
Quicklisp, and any other manually defined ones. Not every package works for all
|
||||
the CL implementations (e.g. `nyxt` only makes sense for `sbcl`).
|
||||
The `pkgs` attribute set contains packages that were automatically
|
||||
[imported](#lisp-importing-packages-from-quicklisp) from Quicklisp, and any
|
||||
other [manually defined](#lisp-defining-packages-inside) ones. Not every package
|
||||
works for all the CL implementations (e.g. `nyxt` only makes sense for `sbcl`).
|
||||
|
||||
The `withPackages` function is of primary utility. It is used to build runnable
|
||||
wrappers, with a pinned and pre-built ASDF FASL available in the `ASDF`
|
||||
environment variable, and `CL_SOURCE_REGISTRY`/`ASDF_OUTPUT_TRANSLATIONS`
|
||||
configured to find the desired systems on runtime.
|
||||
|
||||
With a few exceptions, the primary thing that the infrastructure does is to run
|
||||
`asdf:load-system` for each system specified in the `systems` argument to
|
||||
`build-asdf-system`, and save the FASLs to the Nix store. Then, it makes these
|
||||
FASLs available to wrappers. Any other use-cases, such as producing SBCL
|
||||
executables with `sb-ext:save-lisp-and-die`, are achieved via overriding the
|
||||
`buildPhase` etc.
|
||||
The `withPackages` function is of primary utility. It is used to build
|
||||
[runnable wrappers](#lisp-building-wrappers), with a pinned and pre-built
|
||||
[ASDF FASL](#lisp-loading-asdf) available in the `ASDF` environment variable,
|
||||
and `CL_SOURCE_REGISTRY`/`ASDF_OUTPUT_TRANSLATIONS` configured to
|
||||
[find the desired systems on runtime](#lisp-loading-systems).
|
||||
|
||||
In addition, Lisps have the `withOverrides` function, which can be used to
|
||||
substitute any package in the scope of their `pkgs`. This will be useful
|
||||
together with `overrideLispAttrs` when dealing with slashy ASDF systems, because
|
||||
they should stay in the main package and be built by specifying the `systems`
|
||||
[substitute](#lisp-including-external-pkg-in-scope) any package in the scope of
|
||||
their `pkgs`. This will also be useful together with `overrideLispAttrs` when
|
||||
[dealing with slashy systems](#lisp-dealing-with-slashy-systems), because they
|
||||
should stay in the main package and be built by specifying the `systems`
|
||||
argument to `build-asdf-system`.
|
||||
|
||||
## The 90% use case example {#lisp-use-case-example}
|
||||
|
|
@ -94,7 +90,7 @@ The maintainer's job is to:
|
|||
|
||||
1. Re-run the `ql-import.lisp` script when there is a new Quicklisp release
|
||||
2. [Add any missing native dependencies](#lisp-quicklisp-adding-native-dependencies) in `ql.nix`
|
||||
3. For packages that still don't build, package them manually in `packages.nix`
|
||||
3. For packages that still don't build, [package them manually](#lisp-defining-packages-inside) in `packages.nix`
|
||||
|
||||
Also, the `imported.nix` file **must not be edited manually**! It should only be
|
||||
generated as described in this section (by running `ql-import.lisp`).
|
||||
|
|
@ -139,13 +135,14 @@ During Quicklisp import:
|
|||
|
||||
## Defining packages manually inside Nixpkgs {#lisp-defining-packages-inside}
|
||||
|
||||
New packages, that for some reason are not in Quicklisp, and so cannot be
|
||||
auto-imported, can be written in the `packages.nix` file.
|
||||
Packages that for some reason are not in Quicklisp, and so cannot be
|
||||
auto-imported, or don't work straight from the import, are defined in the
|
||||
`packages.nix` file.
|
||||
|
||||
In that file, use the `build-asdf-system` function, which is a wrapper around
|
||||
`mkDerivation` for building ASDF systems. Various other hacks are present, such
|
||||
as `build-with-compile-into-pwd` for systems which create files during
|
||||
compilation.
|
||||
compilation (such as cl-unicode).
|
||||
|
||||
The `build-asdf-system` function is documented with comments in
|
||||
`nix-cl.nix`. Also, `packages.nix` is full of examples of how to use it.
|
||||
|
|
@ -203,28 +200,6 @@ sbcl.pkgs.alexandria.overrideLispAttrs (oldAttrs: rec {
|
|||
})
|
||||
```
|
||||
|
||||
## Overriding packages in scope {#lisp-overriding-packages-in-scope}
|
||||
|
||||
Packages can be woven into a new scope by using `withOverrides`:
|
||||
|
||||
```
|
||||
let
|
||||
sbcl' = sbcl.withOverrides (self: super: {
|
||||
alexandria = super.alexandria.overrideLispAttrs (oldAttrs: rec {
|
||||
pname = "alexandria";
|
||||
version = "1.4";
|
||||
src = fetchFromGitLab {
|
||||
domain = "gitlab.common-lisp.net";
|
||||
owner = "alexandria";
|
||||
repo = "alexandria";
|
||||
rev = "v${version}";
|
||||
hash = "sha256-1Hzxt65dZvgOFIljjjlSGgKYkj+YBLwJCACi5DZsKmQ=";
|
||||
};
|
||||
});
|
||||
});
|
||||
in builtins.elemAt sbcl'.pkgs.bordeaux-threads.lispLibs 0
|
||||
```
|
||||
|
||||
### Dealing with slashy systems {#lisp-dealing-with-slashy-systems}
|
||||
|
||||
Slashy (secondary) systems should not exist in their own packages! Instead, they
|
||||
|
|
@ -245,8 +220,8 @@ ecl.pkgs.alexandria.overrideLispAttrs (oldAttrs: {
|
|||
})
|
||||
```
|
||||
|
||||
See the respective section on using `withOverrides` for how to weave it back
|
||||
into `ecl.pkgs`.
|
||||
See the [respective section](#lisp-including-external-pkg-in-scope) on using
|
||||
`withOverrides` for how to weave it back into `ecl.pkgs`.
|
||||
|
||||
Note that sometimes the slashy systems might not only have more dependencies
|
||||
than the main one, but create a circular dependency between `.asd`
|
||||
|
|
@ -258,13 +233,16 @@ Wrappers can be built using the `withPackages` function of Common Lisp
|
|||
implementations (`abcl`, `ecl`, `sbcl` etc.):
|
||||
|
||||
```
|
||||
sbcl.withPackages (ps: [ ps.alexandria ps.bordeaux-threads ])
|
||||
nix-shell -p 'sbcl.withPackages (ps: [ ps.alexandria ps.bordeaux-threads ])'
|
||||
```
|
||||
|
||||
Such a wrapper can then be executed like this:
|
||||
Such a wrapper can then be used like this:
|
||||
|
||||
```
|
||||
result/bin/sbcl
|
||||
$ sbcl
|
||||
* (load (sb-ext:posix-getenv "ASDF"))
|
||||
* (asdf:load-system 'alexandria)
|
||||
* (asdf:load-system 'bordeaux-threads)
|
||||
```
|
||||
|
||||
### Loading ASDF {#lisp-loading-asdf}
|
||||
|
|
|
|||
Loading…
Reference in a new issue