Project:Common Lisp/Guide

From Gentoo Wiki
Jump to: navigation, search

Overview

Introduction

Warning
This guide is outdated. Use it with caution! The gentoo lisp team is slowly working on a new one.
Important
This guide describes the use of Common Lisp in Gentoo for those using ~arch keywords.

Implementations

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

Lisp implementations
Implementation Homepage
dev-lisp/sbcl Steel Bank Common Lisp
dev-lisp/clisp CLISP
dev-lisp/clozurecl Clozure Common Lisp
dev-lisp/cmucl CMU Common Lisp
dev-lisp/ecls Embeddable Common Lisp (ECL)
dev-lisp/gcl GNU Common Lisp (GCL)

Libraries

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 category in the Gentoo repository and the dev-lisp category in the lisp overlay

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 also.

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 and ASDF Binary Locations if your choice of Common Lisp implementation does not come bundled with ASDF. SBCL and ECL currently bundle ASDF.

root #emerge --ask 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 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 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 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/....

From SBCL:

mkennedy@localhostsbcl
This is SBCL 0.9.18, an implementation of ANSI Common Lisp.
More information about SBCL is available at <http://www.sbcl.org/>.

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
; #<PACKAGE "ASDF0">
; registering #<SYSTEM ASDF-BINARY-LOCATIONS {AEA3129}> as ASDF-BINARY-LOCATIONS
T
* (asdf:oos 'asdf:load-op :cl-fad)

; loading system definition from /usr/share/common-lisp/systems/cl-fad.asd into
; #<PACKAGE "ASDF0">
; loading system definition from /usr/lib/sbcl/sb-grovel/sb-grovel.asd into
; #<PACKAGE "ASDF2">
; 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 COMPONENT-PRESENT-P ...)
; compiling (DEFUN DIRECTORY-PATHNAME-P ...)
; compiling (DEFUN PATHNAME-AS-DIRECTORY ...)
; compiling (DEFUN DIRECTORY-WILDCARD ...)
; compiling (DEFUN LIST-DIRECTORY ...)
; compiling (DEFUN PATHNAME-AS-FILE ...)
; compiling (DEFUN FILE-EXISTS-P ...)
; compiling (DEFUN DIRECTORY-EXISTS-P ...)
; compiling (DEFUN WALK-DIRECTORY ...)
; compiling (DECLAIM (INLINE COPY-STREAM))
; compiling (DEFUN COPY-STREAM ...)
; compiling (DEFUN COPY-FILE ...)
; compiling (DEFUN DELETE-DIRECTORY-AND-FILES ...)
; 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
NIL
* 

From CLISP:

mkennedy@localhostclisp
[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 ...
; registering #<SYSTEM ASDF-BINARY-LOCATIONS #x203E6216> as ASDF-BINARY-LOCATIONS
;;  Loaded file /usr/share/common-lisp/systems/asdf-binary-locations.asd
;;  Loading file /usr/share/common-lisp/source/asdf-binary-locations/dev/main.lisp ...
WARNING: The generic function #<STANDARD-GENERIC-FUNCTION OUTPUT-FILES> is
         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
T
[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
NIL
[3]>

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 Loading /etc/gentoo-init.lisp
(when (probe-file #p"/etc/gentoo-init.lisp")
  (load #p"/etc/gentoo-init.lisp"))

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.

CMUCL changes
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 An ASDF .asd file prior to dev-lisp/cmucl-19d_pre1
:depends-on (#+cmu #:cmucl-clx #:foo #:bar)

Load the subsystem conditionally:

CODE An ASDF .asd file loading the CMUCL subsystem
#+cmu (require :clx)
...
  :depends-on (#:foo #:bar)