Archive:PackagingDrafts/Lisp

Lisp Packaging Guidelines

This document seeks to document the conventions and customs surrounding the proper packaging of Common Lisp implementations and libraries in Fedora. This document does not describe conventions and customs for application programs that are written in Common Lisp.

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, a packaging format for Common Lisp libraries (see the cl-asdf package for details). Most modern Lisp libraries already ship with asdf system definition files (with names typically ending in ".asd"). 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. The ASDF manual describing how to write .asd files is available here: http://constantly.at/lisp/asdf/ .

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.

Spec file template

Name:           # see normal package guidelines
Version:        # see normal package guidelines
Release:        1%{?dist}
Summary:        # see normal package guidelines (SNPG)

Group:          # SNPG
License:        # SNPG
URL:            # SNPG
Source0:        # SNPG
BuildRoot:      %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)

BuildRequires:   common-lisp-controller
Requires:        common-lisp-controller
Requires(post):  common-lisp-controller
Requires(preun): common-lisp-controller

%description

%prep
%setup -q

%build

%install
%{__rm} -rf %{buildroot}

# Replace @NAME@ below with the Common Lisp library name, which may be different from the
# package name if it is not already prefixed with "cl-".

mkdir -m 755 -p %{buildroot}%{_datadir}/common-lisp/source/@NAME@
mkdir -m 755 -p %{buildroot}%{_datadir}/common-lisp/systems
for s in *.lisp; do
  install -m 644 $s %{buildroot}%{_datadir}/common-lisp/source/@NAME@;
done;
for s in *.asd; do
  install -m 644 $s %{buildroot}%{_datadir}/common-lisp/source/@NAME@;
done;
cd %{buildroot}%{_datadir}/common-lisp/source/@NAME@
for asd in *.asd; do
  ln -s %{_datadir}/common-lisp/source/@NAME@/$asd ../../systems;
done

%post
/usr/sbin/register-common-lisp-source @NAME@

%preun
/usr/sbin/unregister-common-lisp-source @NAME@

%clean
%{__rm} -rf %{buildroot}

%files
%defattr(-,root,root,-)
%doc
%{_datadir}/common-lisp/source/@NAME@
%{_datadir}/common-lisp/systems/@NAME@.asd

%changelog

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 entering "(require 'asdf)" at the Lisp Read-Eval-Print loop (REPL). 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.