Archive:PackagingDrafts/Lisp

Lisp Packaging Guidelines

This document seeks to document the conventions and customs surrounding the proper packaging of Lisp implementations and libraries in Fedora.

Introduction

Most Common Lisp implementations provide a compiler to generate their own binary representation of source. These binary files typically end in .fasl (for Fast Load). These .fasl files are not compatible across Common Lisp implementations, or even between different versions of the same implementation. This unique property calls for special support on the packaging front.

The Common Lisp community currently rallies around a common packaging and deployment technology called asdf (Another System Definition Format). Projects deployed using asdf include a system definition file. These files include information about project dependencies, licensing, and the authors. Projects don't typically distribute binaries, but rather depend on the asdf utilities to compile the Lisp source code on demand. When you run program that depends on a library managed by asdf, the asdf system will automatically compile the dependent Lisp code on demand and cache the results.

The Debian Lisp community have developed tools and guidelines for packaging and maintaining asdf managed libraries on Linux systems. Their tool is called common-lisp-controller and, combined with asdf, it ensures that .fasl files are managed properly on the system. For instance, when a Common Lisp implementation is upgraded, the .fasl files for all of the packages built using the old implementation are deleted so that new ones may be generated on demand.

The rest of this packaging guideline aims to describe how to package Common Lisp implementations, libraries and programs to take advantage of asdf and the common-lisp-controller.

Guidelines for Libraries and Programs written in Common Lisp

Naming

Lisp libraries should have their package names prefixed with "cl-", except in the case where the library name already starts with "cl-".

Rationale: There is some overlap between Lisp library names and existing Fedora packages. Creating a special name space for Lisp libraries should simplify life for everybody.

-devel sub-package

Pure lisp libraries do not require -devel sub-packages, as they install source code by default.

Use of asdf

Libraries should be managed by asdf. Most modern Lisp libraries already ship with asdf system definition files. If none exist, then one will have to be written. The contents of these files is not all that different from an RPM .spec file, so this should not be too difficult for a Lisp-savvy packager.

Install location and hooking into the common-lisp-controller

Libraries should depend on the common-lisp-controller package. Lisp source should be installed in %{_datadir}/common-lisp/source/<library>. The package should own that directory. The parent directories are owned by the common-lisp-controller package. A symlink to the asdf system definition file should be created from %{_datadir}/common-lisp/systems/<library>.asd to %{_datadir}/common-lisp/source/<library>/<library>.asd (this target directory is also owned by common-lisp-controller). The %post section should call "%{_sbindir}/register-common-lisp-source <library>". The %preun section should call "%{_sbindir}/unregister-common-lisp-source <library>" These scripts are provided by common-lisp-controller.

Guidelines for Common Lisp implementations

Naming

There are no special requirements here. Common Lisp implementations should be packaged using their normal project name.

-devel sub-package

Common Lisp implementations do not require -devel sub-packages, and they necessarily include all development tools by default.

Use of asdf

Common Lisp implementations should be able to load asdf by simply (require 'asdf). This may involve modifying search paths or related changes at build time.

Install location and hooking into the common-lisp-controller

Common Lisp implementations should depend on the common-lisp-controller package.

Common Lisp implementations should install a script in %{_libdir}/common-lisp/bin/<impl>.sh that supports a single command on the command line: "install-clc". This should load %{_datadir}/common-lisp/source/common-lisp-controller/common-lisp-controller.lisp, call (common-lisp-controller:init-common-lisp-controller-v4 <implementation>) and then save the resulting image as default for the system.

The %post section should call "%{_sbindir}/register-common-lisp-implementation <implementation>". The %preun section should call "%{_sbindir}/unregister-common-lisp-implementation <implementation>"

These scripts, and the %{_libdir}/common-lisp/bin directory are provided and owned by the common-lisp-controller package.

All implementations should be modified to load common-lisp-controller's %{_sysconfdir}/lisp-config.lisp on startup.

Further reading

See http://www.cliki.net/common-lisp-controller and http://common-lisp.net/project/asdf/ for more details on common-lisp-controller and asdf.