Gentoo Logo

Disclaimer : This document is not valid and is not maintained anymore.

Gentoo Common Lisp User Guide


1.  Overview


Warning: This guide is outdated. Use it with caution! The gentoo lisp team is slowly working on a new one.(pchrist, July 16, 2011)

Important: This guide describes the use of Common Lisp in Gentoo for those using ~arch keywords.


One of the great things about Common Lisp is the variety of quality implementions avaiable. Gentoo supports the following free software implementations:

dev-lisp/sbcl Steele Bank Common Lisp
dev-lisp/cmucl CMU Common Lisp
dev-lisp/clisp CLISP
dev-lisp/abcl Armed Bear Common Lisp
dev-lisp/ecls Embeddable Common Lisp (ECL)
dev-lisp/gcl GNU Common Lisp (GCL)
dev-lisp/openmcl OpenMCL


As of writing, there are over two-hundred Common Lisp libraries supported in Gentoo. All Common Lisp libraries in Gentoo are made available within the dev-lisp.

Each ebuild name begins with the "cl-" prefix for historical reasons. If the name of the library upstream does not begin with "cl-", then "cl-" is prefixed to create the Gentoo ebuild name. eg. "araneida" becomes "cl-araneida". If the name of the library upstream begins with "cl-", then the Gentoo ebuild name will be the same. eg. "cl-ppcre".

Integration of Implementations and Libraries

Important: Prior to the construction of the Gentoo Common Lisp Project and the Portage Overlay, integration of the Common Lisp implementations and libraries in Gentoo was achieved using the Common Lisp Controller which was ported from the Debian Project. After the construction of the Portage Overlay, the Lisp implementation ebuilds were redesigned to install the implementation the way the upstream developers intended. As CLISP 2.41, SBCL 0.9.18 and CMUCL 19d-pre1 became available in Portage proper (CVS/rsync) support for the Common Lisp Controller for CLISP, SBCL and CMUCL was dropped aslo.

Under the Common Lisp Controller scheme, each implementation includes code for redirection of compilation output (FASL files. The Common Lisp Controller code is saved in the Lisp implementation's image (or initialization) at emerge and is present when the user starts the Lisp implementation. Refer to the Common Lisp Controller documentation for more detail.

Using Common Lisp Without the Common Lisp Controller

Note: This section is relevant only if you are using the Portage Overlay which removes support for the Common Lisp Controller.

The most important feature of the Common Lisp Controller from our distribution's standpoint is the redirection of compiled output from source files located in user read-only directories under /usr/share/common-lisp/source/ to a user-writable path. This feature can be achieved using the ASDF Binary Locations extension to ASDF.

The first step is to install ASDF if your choice of Common Lisp implementation does not come bundled with ASDF. SBCL and ECL currently bundle ASDF.

Code Listing 1.1: Installing ASDF and ASDF Binary Locations from Portage

# emerge dev-lisp/cl-asdf dev-lisp/cl-asdf-binary-locations

Create a Gentoo Common Lisp initialization file somewhere in your home directory. You might call the file "gentoo-init.lisp" perhaps. You could include this initialization code directly in your Lisp implementation's initialization file (eg. ~/.sbclrc, ~/.clisprc, ~/.cmucl-init.lisp etc.), but it will make more sense to include it from an external file if you work with more than one implementation. The first thing our initialization code must do is load ASDF:

Code Listing 1.2: Loading ASDF from gentoo-init.lisp

(in-package #:cl-user)
#+(or sbcl ecl) (require :asdf)
#-(or sbcl ecl) (load #p"/usr/share/common-lisp/source/asdf/asdf.lisp")

If the implementation includes ASDF then you may need to load it using the implementation a specific REQUIRE. If the implemention doesn't include ASDF then we load it directly. The next step is to configure ASDF to use the Portage-installed Common Lisp libraries and then load ASDF Binary Locations:

Code Listing 1.3: Configuring ASDF

(push #p"/usr/share/common-lisp/systems/" asdf:*central-registry*)
(asdf:oos 'asdf:load-op :asdf-binary-locations)

Portage currently creates a directory of symlinks /usr/share/common-lisp/systems/ which point to ASDF system definition files (*.asd) in /usr/share/common-lisp/source/ rather than adding a path to each individual ASDF system definition file.

Finally, ASDF Binary Locations needs to be configured. We want all compiled output to be centralized under one user read-writable directory so we set ASDF:*CENTRALIZE-LISP-BINARIES* to true. By default, compiled output will be stored in a directory structure under ~/.fasls/. Some Common Lisp implementations, such as SBCL, use ASDF internally. We want to avoid interfering with that behaviour, therefore we configure ASDF Binary Locations to do nothing for definitions belonging to SBCL. This can be achieved by including the SBCL path in ASDF:*SOURCE-TO-TARGET-MAPPINGS*.

Code Listing 1.4: Configuring ASDF Binary Locations

(setf asdf:*centralize-lisp-binaries* t)
(setf asdf:*source-to-target-mappings* '((#p"/usr/lib/sbcl/" nil) (#p"/usr/lib64/sbcl/" nil)))

The following examples show how to use gentoo-init.lisp from various Common Lisp implementations. Note how ASDF system definitions are being found under /usr/share/common-lisp/systems/ and compiled to, for example, /home/mkennedy/.fasls/sbcl-0.9.18-linux-x86/usr/share/common-lisp/source/...

Code Listing 1.5: Using gentoo-init.lisp from SBCL

mkennedy@localhost:~$ sbcl
This is SBCL 0.9.18, an implementation of ANSI Common Lisp.
More information about SBCL is available at <>.

SBCL is free software, provided as is, with absolutely no warranty.
It is mostly in the public domain; some portions are provided under
BSD-style licenses.  See the CREDITS and COPYING files in the
distribution for more information.
* (load "gentoo-init")

; loading system definition from
; /usr/share/common-lisp/systems/asdf-binary-locations.asd into
* (asdf:oos 'asdf:load-op :cl-fad)

; loading system definition from /usr/share/common-lisp/systems/cl-fad.asd into
; loading system definition from /usr/lib/sbcl/sb-grovel/sb-grovel.asd into
; registering #<SYSTEM SB-GROVEL {A79FAC9}> as SB-GROVEL
; registering #<SYSTEM #:CL-FAD {AE43CE1}> as CL-FAD
; compiling file "/usr/share/common-lisp/source/cl-fad/packages.lisp" (written 17 OCT 2006 08:51:58 PM):
; compiling (IN-PACKAGE #:CL-USER)
; compiling (DEFPACKAGE :CL-FAD ...)
; compiling (DEFPACKAGE :CL-FAD-TEST ...)

; /home/mkennedy/.fasls/sbcl-0.9.18-linux-x86/usr/share/common-lisp/source/cl-fad/packages.fasl written
; compilation finished in 0:00:00
; compiling file "/usr/share/common-lisp/source/cl-fad/fad.lisp" (written 17 OCT 2006 08:51:58 PM):
; compiling (IN-PACKAGE :CL-FAD)
; compiling (DEFUN LIST-DIRECTORY ...)
; compiling (DEFUN PATHNAME-AS-FILE ...)
; compiling (DEFUN FILE-EXISTS-P ...)
; compiling (DEFUN DIRECTORY-EXISTS-P ...)
; compiling (DEFUN WALK-DIRECTORY ...)
; compiling (DEFUN COPY-STREAM ...)
; compiling (DEFUN COPY-FILE ...)
; compiling (PUSHNEW :CL-FAD ...)
; compiling (DEFVAR *HYPERDOC-BASE-URI* ...)
; compiling (LET (#) ...)

; /home/mkennedy/.fasls/sbcl-0.9.18-linux-x86/usr/share/common-lisp/source/cl-fad/fad.fasl written
; compilation finished in 0:00:00

Code Listing 1.6: Using gentoo-init.lisp from SBCL

mkennedy@localhost:~$ clisp
[1]> (load "gentoo-init")
;; Loading file /home/mkennedy/gentoo-init.lisp ...
;;  Loading file /usr/share/common-lisp/source/asdf/asdf.lisp ...
;;  Loaded file /usr/share/common-lisp/source/asdf/asdf.lisp
; loading system definition from /usr/share/common-lisp/systems/asdf-binary-locations.asd into #<PACKAGE ASDF3783>
;;  Loading file /usr/share/common-lisp/systems/asdf-binary-locations.asd ...
;;  Loaded file /usr/share/common-lisp/systems/asdf-binary-locations.asd
;;  Loading file /usr/share/common-lisp/source/asdf-binary-locations/dev/main.lisp ...
         being modified, but has already been called.
;;  Loaded file /usr/share/common-lisp/source/asdf-binary-locations/dev/main.lisp
0 errors, 0 warnings
;; Loaded file /home/mkennedy/gentoo-init.lisp
[2]> (asdf:oos 'asdf:load-op :cl-fad)
; loading system definition from /usr/share/common-lisp/systems/cl-fad.asd into #<PACKAGE ASDF4628>
;; Loading file /usr/share/common-lisp/systems/cl-fad.asd ...
; registering #<SYSTEM #:CL-FAD #x204042E6> as CL-FAD
;; Loaded file /usr/share/common-lisp/systems/cl-fad.asd
;; Compiling file /usr/share/common-lisp/source/cl-fad/packages.lisp ...
;; Wrote file /home/mkennedy/.fasls/clisp-2.41-unix-pc386/usr/share/common-lisp/source/cl-fad/packages.fas
;; Loading file /home/mkennedy/.fasls/clisp-2.41-unix-pc386/usr/share/common-lisp/source/cl-fad/packages.fas ...
;; Loaded file /home/mkennedy/.fasls/clisp-2.41-unix-pc386/usr/share/common-lisp/source/cl-fad/packages.fas
;; Compiling file /usr/share/common-lisp/source/cl-fad/fad.lisp ...
;; Wrote file /home/mkennedy/.fasls/clisp-2.41-unix-pc386/usr/share/common-lisp/source/cl-fad/fad.fas
;; Loading file /home/mkennedy/.fasls/clisp-2.41-unix-pc386/usr/share/common-lisp/source/cl-fad/fad.fas ...
;; Loaded file /home/mkennedy/.fasls/clisp-2.41-unix-pc386/usr/share/common-lisp/source/cl-fad/fad.fas
0 errors, 0 warnings

The Gentoo-Maintained gentoo-init.lisp

Now that you understand how integration of Common Lisp implementations and libraries is achieved in Gentoo, you might want to install the ready-made dev-lisp/gentoo-init which will install gentoo-init.lisp to /etc/gentoo-init.lisp for you. You could then load the file from your implementation's initialization file.

Code Listing 1.7: Loading /etc/gentoo-init.lisp

(when (probe-file #p"/etc/gentoo-init.lisp")
  (load #p"/etc/gentoo-init.lisp"))

2.  Overview of Changes

CMUCL Changes

Prior to dev-lisp/cmucl-19d_pre1, the Common Lisp Controller enabled CMUCL installation would also include a number of ASDF system definitions to wrap various CMUCL subsystems. With the inclusion of dev-lisp/cmucl-19d_pre1, subsystems are not wrapped by ASDF -- subsystems are loaded the CMUCL way via CMUCL's Extension to REQUIRE.

Before dev-lisp/cmucl-19d_pre1 After
(asdf:oos 'asdf:load-op :cmucl-clx) (require :clx)
(asdf:oos 'asdf:load-op :cmucl-graystream) (require :gray-streams)

If you previously used those ASDF components in your own ASDF system definition files, you'll need to remove them and instead conditionally load the appropriate CMUCL subsystem. For example:

Code Listing 2.1: An ASDF .asd file prior to dev-lisp/cmucl-19d_pre1

  :depends-on (#+cmu #:cmucl-clx #:foo #:bar)

load the subsystem conditionally:

Code Listing 2.2: An ASDF .asd file loading the CMUCL subsystem

#+cmu (require :clx)
  :depends-on (#:foo #:bar)


Page updated November 1, 2006

Summary: And overview of Common Lisp implementations and libraries in Portage and how to integrate them.

Matthew Kennedy

Donate to support our development efforts.

Copyright 2001-2015 Gentoo Foundation, Inc. Questions, Comments? Contact us.