Archive:PackagingDrafts/Lisp

From FedoraProject

(Difference between revisions)
Jump to: navigation, search
m (1 revision(s))
(Rewritten)
Line 4: Line 4:
  
  
 +
= Introduction =
  
= common-lisp-controller =
+
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.
  
Fedora Lisp implementations and libraries should be packages as per the common-lisp-controller guidelines found below.  These guidelines have been adopted from Debian's common-lisp-controller package and provide critical infrastructure for maintaining lisp libraries given a multitude of lisp implementations with incompatible binary forms (.fasl files, etc).
+
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.
  
= Naming =
+
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.
  
Lisp implementations should be named as per usual.
+
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 Program 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-".
 
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.
 
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.
 
= Packaging libraries =
 
 
Library packages should install .lisp files as per the common-lisp-controller guidelines described below.
 
  
 
== -devel sub-package ==
 
== -devel sub-package ==
Line 25: Line 26:
 
Pure lisp libraries do not require -devel sub-packages, as they install source code by default.
 
Pure lisp libraries do not require -devel sub-packages, as they install source code by default.
  
= Further reading =
+
== Use of asdf ==
  
See http://www.cliki.net/common-lisp-controller
+
Libraries should be managed by asdf. Most modern Lisp libraries already ship with asdf system definition files. If none exist, than 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.
  
Here's the common-lisp-controller design document from Debian...
+
== Install location and hooking into the common-lisp-controller ==
<pre>
+
; Copyright (C) 2000,2004  Peter Van Eynde and Kevin M. Rosenberg
+
; Licensed under the LLGPL, see debian/copyright file
+
  
This is the general design of the new 'light weight' common-lisp-controller v4.
+
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 package 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.
  
Common Lisp Libraries:
+
= Guidelines for Common Lisp implementations =
  
Libraries should:
+
== Naming ==
- use adsf
+
- install their source packages in /usr/share/common-lisp/source/<library>
+
- install a symlink to their asdf package from /usr/share/common-lisp/systems/<library>.asd to
+
/usr/share/common-lisp/source/<library>/<library>.asd
+
- after install call "/usr/sbin/register-common-lisp-source <library>"
+
- before removal of the package call "/usr/sbin/unregister-common-lisp-source <library>"
+
Libraries can be automaticly created with the "asdf-install-2-deb" package.
+
  
Common Lisp Implementations::
+
There are no special requirements here.  Common Lisp implementations should be packaged using their normal project name.
  
Implementations should:
+
== -devel sub-package ==
- install a script /usr/lib/common-lisp/bin/<impl>.sh that has the following
+
commands:
+
/usr/lib/common-lisp/bin/<impl>.sh install-clc
+
This should load /usr/share/common-lisp/source/common-lisp-controller/common-lisp-controller.lisp
+
then call
+
(common-lisp-controller:init-common-lisp-controller-v4 <implementation)
+
and then save the resulting image as default for the system.
+
- after install call "/usr/sbin/register-common-lisp-implementation <implementation>"
+
- before removal call "/usr/sbin/unregister-common-lisp-implementation <implementation>"
+
- should load /etc/lisp-config.lisp on startup.
+
  
There are 2 scenarious:
+
Common Lisp implementations do not require -devel sub-packages, and they necessarily include all development tools by default.
  
- a user wants to use a system-wide library.
+
== Use of asdf ==
(asdf:oos 'asdf:compile-op :<library>)
+
will load the system at
+
/usr/share/common-lisp/systems/<library>.asd
+
that will use the source at
+
/usr/share/common-lisp/source/<library>
+
fasls will be placed in
+
/var/cache/common-lisp-controller/<userid>/<implementation>/<library>/
+
- a user wants to use another library. He or she used adsf-install
+
and the sources got placed in ~/.sbcl or ~/sdf-install-dir/. We do not interfere
+
with this use as we expect the user to be able to correct all errors :-).
+
  
User interface:
+
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.
  
To load a library "cil" do:
+
== Install location and hooking into the common-lisp-controller ==
(clc:clc-require :cil)
+
  
To recompile all libraries, dropping into the
+
Common Lisp implementations should depend on the common-lisp-controller package.
debugger on error, do:
+
(clc:clc-build-all-packages)
+
to do so while ignoring build errors,
+
do:
+
(clc:clc-build-all-packages t)
+
  
To add user packages, use clc-register-user-package. This will
+
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.
place a link to the user's asdf file in ~/.clc/systems.
+
  
Technical Implementation:
+
The %post section should call "%{_sbindir}/register-common-lisp-implementation <implementation>".
 +
The %preun section should call "%{_sbindir}/unregister-common-lisp-implementation <implementation>"
  
- register-common-lisp-source:
+
These scripts, and the %{_libdir}/common-lisp/bin directory are provided and owned by the common-lisp-controller package.
does nothing
+
  
- unregister-common-lisp-source:
+
All implementations should be modified to load common-lisp-controller's %{_sysconfdir}/lisp-config.lisp on startup.
does: (after checking stuff):
+
rm -rf /var/cache/common-lisp-controller/*/*/<library>
+
  
- register-common-lisp-implementation
 
does nothing
 
  
- unregister-common-lisp-implementation
+
= Further reading =
does: (after checking stuff):
+
rm -rf /var/cache/common-lisp-controller/*/<implementation>
+
 
+
- clc-init.lisp:
+
  
loads adsf
+
See http://www.cliki.net/common-lisp-controller.
builds pathname translations for /usr/share/common-lisp/source/
+
adds /usr/share/common-lisp/systems/ and <code>/.clc/systems
+
to the asdf registry
+
</pre>
+

Revision as of 13:16, 6 July 2008

Contents

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 Program 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, than 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 package 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.