ASDF（Lisp项目构建利器）使用说明

这篇文档的目的

这篇文档的目的是简要介绍ASDF的使用。它不是介绍ASDF高深的技巧和设计。一个系统定义文件只是定义了源文件的依赖和编译加载顺序。如果B.lisp文件含有被A.lisp使用的定义的代码，那么A.lisp依赖B.lisp。

在大多数情况下，解决依赖问题相当的繁琐，所以写一个小的脚本通常可以工作。但是，学习使用正确的工具会让你节省大量的时间。在这个小教程里面，我们将集中关注一个简单的例子和ASDF的简单用法。如果想进一步了解的话，请阅读ASDF 手册[1].

ASDF解决了什么问题？

当你从Internent或者从其他来源下载了某些软件的源代码，你通常不是得到得到一大堆的文件，而是一系列的以某种特别方式相互依赖的的组件。如果你想构建软件，你可能需要用正确的顺序构建这些组件，和组件依赖的组件，可能还要特别的对待某些组件。

当然，如果开发者已经准备了一切，你会感到非常的庆幸，你可以通过一个简单的命令来触发构建过程。

通俗的讲，ASDF是一个为了定义软件组件间的依赖关系和指定构建过程最终细节的可扩展的设施。它也相当广泛的被使用，所以你可以假设你的系统定义可以被许多人理解。

mk:defsystem是另一相同的工具，有着支持者和反对者。我们这里只讨论ASDF，因为我们不得不开始了。无论如何，这两种工具的实际区别只会出现在高级用户中显现。

使用ASDF定义系统

ASDF 系统定义保存在.asd后缀的文件中，为了表述清楚，我们假设我们为Cow工程来写一个系统定义文件。

定义文件名为com.asd,在大多数情况下，此文件和你的源代码位于同样的目录。如果是你用emacs, 你可能这些书写第一行文件

;;;; -*- Mode: Lisp; Syntax: ANSI-Common-Lisp; Base: 10 -*-

这将保证开启正确的语法支持，它是必须的，因为默认情况下emacs不知道任何.asd文件。

之后，cow.asd 可能书写如下:

(defpackage #:cow-asd

(:use :cl :asdf))

(in-package :cow-asd)

下面是defsystem定义形式，和一些可选的属性。

(defsystem cow
:name "cow"
:version "0.0.0"
:maintainer "T. God"
:author "Desmon Table"
:licence "BSD sans advertising clause (see file COPYING for details)"
:description "Cow"
:long-description "Lisp implementation of our favorite ruminant"

正如你猜测的一样，只有第一行是必须的。

defsystem grammar

system-definition := ( defsystem system-designator system-option* )

system-option := :defsystem-depends-on system-list
| :weakly-depends-on system-list
| :class class-name (see discussion below)
| module-option
| option

module-option := :components component-list
| :serial [ t | nil ]
| :if-component-dep-fails component-dep-fail-option

option :=
| :pathname pathname-specifier
| :default-component-class class-name
| :perform method-form
| :explain method-form
| :output-files method-form
| :operation-done-p method-form
| :depends-on ( dependency-def* )
| :in-order-to ( dependency+ )

system-list := ( simple-component-name* )

component-list := ( component-def* )

component-def  := ( component-type simple-component-name option* )

component-type := :system | :module | :file | :static-file | other-component-type

other-component-type := symbol-by-name (see Component types)

dependency-def := simple-component-name
| ( :feature name )
| ( :version simple-component-name version-specifier)

dependency := (dependent-op requirement+)
requirement := (required-op required-component+)
| (feature feature-name)
dependent-op := operation-name
required-op := operation-name | feature

simple-component-name := string
|  symbol

pathname-specifier := pathname | string | symbol

method-form := (operation-name qual lambda-list &rest body)
qual := method qualifier

component-dep-fail-option := :fail | :try-next | :ignore

基本情况

最简单的例子中，你的工程有一个目录和一些文件。 最简单的情况是你的文件的依赖关系是线性的。也就是说，你可以简单的列出文件，第一个文件首先加载，第二而第二，以此类推。

在这种情况下，defsystem 的形式如下所示：

(defsystem cow

;;; (Optional items omitted)
:serial t ;; the dependencies are linear.
:components ((:file "defpackage")
(:file "legs")
(:file "tail")
(:file "head")))

复杂一点的例子

假设你的文件还是和上次一样，但是你想更精确的定义依赖。有一个文件叫做defpackage.lisp，其他文件都依赖它。并且假设tail.lisp依赖legs.lisp。defsystem形式将会如下

(defsystem cow

;;; (Optional items omitted)
:components ((:file "tail"
:depends-on ("package" "legs"))
(:file "legs"
:depends-on ("package"))
(:file "head"
:depends-on ("package"))
(:file "package")))

In this case you would keep the file

cow.asd

in the same directory as the source files. If you want to try out our nice

cow

system, you can jump directly to the pertinent section.

有模块的系统

假设我们有一个下面复杂的结构。我们有head.lisp和legs.lisp。但是我们还有一个子系统叫做repiratory，有多个文件组成，在文件夹breathing。（cow.asd的子文件夹）。同样的，我们还有另一个子系统叫做circulation。那么defsystem 形式可能如下面。

(defsystem cow
:components ((:file "head" :depends-on ("package"))
(:file "tail" :depends-on ("package"
circulation))
(:file "package")
(:module circulation
:components ((:file "water"
:depends-on
"package")
(:file "assorted-solids"
:depends-on
"package")
(:file "package")))
(:module respiratory
:pathname "breathing"
:components (...))))

注意circulation模块的所有在子文件夹circulation。

circulation

模块中的package.lisp是高层模块的。

一个模块可以作为组件可以包含文件其他模块，这个模块也可也包含文件和作为组件的模块。重要的是依赖关系只能在一个组件集里面定义。所以tail.lisp不能依赖文件assorted-solids，这是一个子模块的组成。

依赖其他系统

一个系统可也依赖其他系统，他的定义如下：

(defsystem cow
;;; ...
:components (...)
:depends-on ("other-system"))

如何使用system definition files

系统定义文件所在的目录是软件的一部分。但是，你不需要把那个目录作为你的当前工作目录以便构建和加载需要的软件。你只需要把一个软链接定义在ASDF的搜索目录即可。

通常的设置步骤如下。首先，你需要加载ASDF。在某些实现中ASDF可以已经加载。在其他系统，你只需要编写

(require 'asdf)

然而在某些系统中，你可能需要首先安装他们。你可以从这个下载它（一个单独的文件），把它存放可以读的地方。例如，你的登录名字是foo的话，那么你可以把ASDF文件放在目录/home/foo/lisp/utils/.你也需要编译这个文件。

现在，你的Common Lisp 实现的初始化配置文件（对于cmucl来说，就是你个人主目录.cmucl-init.lisp）应该添加如下变化的段落。

(load "/home/foo/lisp/utils/asdf")

(setf asdf:*central-registry*
;; Default directories, usually just the ``current directory''
'(*default-pathname-defaults*

;; Additional places where ASDF can find
;; system definition files
#p"/home/foo/lisp/systems/"
#p"/usr/share/common-lisp/systems/"))

构建和加载系统cow的命令如下：

(asdf:operate 'asdf:load-op 'cow)

如果cow.asd碰巧在你当前的工作目录，那么构建和加载过程将会从这个开始。如果没有的话，ASDF将会搜索cetral registry的目录，寻找cow.asd的系统定义文件或者软链接。如果找到的软连接的话，它将跟随它会找到原文件，运行构建过程在相应的目录。如果找到文件的话，它将在此目录运行构建过程。

所以，如果你做了一个符号链接/home/foo/lisp/system到cow的系统定义文件，例如：

$ cd <where-your-system-defs-are>

$ ln -s /home/foo/code/cow/cow.asd

那么你可以构建和加载cow软件通过键入如下的命名，而不需要在cow所在的目录

(asdf:operate 'asdf:load-op 'cow)

一些人，使用未进入符号（#：语法），而不是关键字符号，来定义包。如下：

(defpackage #:com.gigamonkeys.email-db

(:use #:common-lisp))

这可以节省一点点的内存因为它没有向关键字包中引入任何符号----这些符号在可以变成垃圾在defpackage完成之后。但是，区别是如此的少，可以归结为审美问题。

原文：

Getting started with ASDF

Mario S. Mommer <mommer@common-lisp.net>

Last modified: April 05, 2006.

Contents

Contents

Introduction

Purpose of this document

What problem does ASDF solve?

Legal matters

Defining systems with ASDF

The base case

A more complex example

A system with modules

A system that depends on other systems

How to use system definition files

Introduction

Purpose of this document

The aim of this document is to give a brief introduction to the use of

ASDF

, Another System Definition Facility. It is not about the arcane tricks and tips, and is not about the design of

ASDF

itself nor about system definition tools in general.

A system definition file is nothing else than a description of dependencies between files of source code in such a way that they can be compiled and loaded in the right order. A file

A.lisp

depends on a file

B.lisp

if the latter contains definitions and/or code that is used by

A.lisp

1.

Solving this problem is in the vast majority of cases fairly trivial, so hacking up some minimal script will usually work. Learning the right tool, however, will save you a lot of time down the road. In this minitutorial we will concentrate on the simple cases and on the general usage of a fairly well known tool,

ASDF

. We leave the more advanced features of this tool to the

ASDF

manual
2.

What problem does

ASDF

solve?

When you download the source code of some software from the Internet, or get it from some other source, you usually do not get an amorphous bunch of files, but instead get a system of components that depend on each other in some particular way. The consequence of this is that, if you want to build the software (be it a library, or be it an application), you will probably have to build these components, and the components of these components in order, perhaps giving some special treatment to some of them. You would, of course, be very grateful if the developer had prepared everything, and you could trigger the build process by a single command.

If you are a developer working in a project with a few components, you will probably want some mechanism that keeps track of the dependencies between these components, so that if you change one component, triggering a rebuild only recompiles and reloads the components which are affected.

Finally, you probably want a consistent way of dealing with the dependencies between components and of building and loading software systems, simply because it saves everyone time when installing software and using software.

ASDF

is, roughly speaking, an extensible facility for defining the dependencies between software components, and specifying eventual details of the build process. It is also in fairly wide use, so that you can assume that your system definition will be understood by many others.

The same can be said about

mk:defsystem

, which has fans as well as detractors. We will only concentrate here on

ASDF

, since we have to start somewhere. In any case, the actual differences between these two only become apparent for the power user.

Legal matters


This work is licensed under a Creative Commons Attribution 2.5 License.

Defining systems with

ASDF

An

ASDF

system definition is stored in a file with the extension

.asd

. To make the discussion clearer, we are going to pretend that we want to write the system definition facility for our software project, called, unassumingly,

cow

.

The system definition file should be called

cow.asd

, and, at least in the usual scenarios, should reside in the same directory as your source code. If you use emacs, you might want to put the following as the first line in

cow.asd

.

;;;; -*- Mode: Lisp; Syntax: ANSI-Common-Lisp; Base: 10 -*-

This makes sure that the proper syntax support is turned on, which is necessary because by default emacs knows nothing about

.asd

files.

After that,

cow.asd

should start with the following code (preceded or followed perhaps by comments; goes almost without saying)

(defpackage #:cow-asd
(:use :cl :asdf))

(in-package :cow-asd)

The next thing is to write a

defsystem

form, together with some (optional) extra information.

(defsystem cow
:name "cow"
:version "0.0.0"
:maintainer "T. God"
:author "Desmon Table"
:licence "BSD sans advertising clause (see file COPYING for details)"
:description "Cow"
:long-description "Lisp implementation of our favorite ruminant"

As you might have guessed, only the first line is mandatory.

The defsystem grammar

system-definition := ( defsystem system-designator system-option* )

system-option := :defsystem-depends-on system-list
| :weakly-depends-on system-list
| :class class-name (see discussion below)
| module-option
| option

module-option := :components component-list
| :serial [ t | nil ]
| :if-component-dep-fails component-dep-fail-option

option :=
| :pathname pathname-specifier
| :default-component-class class-name
| :perform method-form
| :explain method-form
| :output-files method-form
| :operation-done-p method-form
| :depends-on ( dependency-def* )
| :in-order-to ( dependency+ )

system-list := ( simple-component-name* )

component-list := ( component-def* )

component-def  := ( component-type simple-component-name option* )

component-type := :system | :module | :file | :static-file | other-component-type

other-component-type := symbol-by-name (see Component types)

dependency-def := simple-component-name
| ( :feature name )
| ( :version simple-component-name version-specifier)

dependency := (dependent-op requirement+)
requirement := (required-op required-component+)
| (feature feature-name)
dependent-op := operation-name
required-op := operation-name | feature

simple-component-name := string
|  symbol

pathname-specifier := pathname | string | symbol

method-form := (operation-name qual lambda-list &rest body)
qual := method qualifier

component-dep-fail-option := :fail | :try-next | :ignore

The base case

In the simplest case you have a directory with a few files. And the absolutely simplest case is when the dependency of your files is linear. That is, you can make a list of the files such that the first one should be loaded first, the second second, etc.

In such a case, the

defsystem

form can look like this.

(defsystem cow
;;; (Optional items omitted)
:serial t ;; the dependencies are linear.
:components ((:file "defpackage")
(:file "legs")
(:file "tail")
(:file "head")))

A more complex example

Suppose that we have the same files as before, but would like to specify the dependencies more accurately. There is a file called

defpackage.lisp

, from which everything else depends. And we have that, for some mysterious reason,

tail.lisp

depends on

legs.lisp

. The

defsystem

form for this project could look as follows.

(defsystem cow
;;; (Optional items omitted)
:components ((:file "tail"
:depends-on ("package" "legs"))
(:file "legs"
:depends-on ("package"))
(:file "head"
:depends-on ("package"))
(:file "package")))

In this case you would keep the file

cow.asd

in the same directory as the source files. If you want to try out our nice

cow

system, you can jump directly to the pertinent section.

A system with modules

Suppose that we have the following, more involved structure. We have a

head.lisp

, and

legs.lisp

. But we also have a subsystem called

respiratory

, which consists of a few more files, and lives in its own subdirectory called

breathing

(this is a subdirectory of the directory where

cow.asd

lives). Similarly, we have another subsystem called

circulation

. The

defsystem form

could look more or less like this.

(defsystem cow
:components ((:file "head" :depends-on ("package"))
(:file "tail" :depends-on ("package"
circulation))
(:file "package")
(:module circulation
:components ((:file "water"
:depends-on
"package")
(:file "assorted-solids"
:depends-on
"package")
(:file "package")))
(:module respiratory
:pathname "breathing"
:components (...))))

Note that the files in the module

circulation

all live in the subdirectory

circulation

. Thus the file

package.lisp

in the module

circulation

is a different one than that a level higher.

A module can have as components both files and other modules, which in turn can have files and modules as components. It is important to note that dependencies can only be defined inside a given set of components. So, the file

tail.lisp

cannot depend on the file

assorted-solids

, which is a component of a submodule.

A system that depends on other systems

A system that depends on other systems will look exactly like a regular one, except for an additional

:depends-on

option. It looks like this.

(defsystem cow
;;; ...
:components (...)
:depends-on ("other-system"))

How to use system definition files

System definition files live in the directory where the corresponding piece of software lives. However, you do not need to have that directory as your working directory to be able to build and load said software. You only need to put a symbolic link to the system definition file in a directory where

ASDF

searches.

The usual setup is as follows. To begin with, you need to have

ASDF

loaded. In some implementations

ASDF

is already loadad. In others, it is just a matter of writing

(require 'asdf)

whereas in others you might need to install it yourself first. You can get it, in a single file, from

here, and put it somewhere reasonable. For instance, if your login name was

foo

, in the directory

/home/foo/lisp/utils/

. You may also want to compile that file.
Now, somewhere in the init file of your Common Lisp implementation (for CMUCL it would be

.cmucl-init.lisp

in your home directory) a variation of the following passage should appear.

(load "/home/foo/lisp/utils/asdf")

(setf asdf:*central-registry*
;; Default directories, usually just the ``current directory''
'(*default-pathname-defaults*

;; Additional places where ASDF can find
;; system definition files
#p"/home/foo/lisp/systems/"
#p"/usr/share/common-lisp/systems/"))

The command to build and load system cow is

(asdf:operate 'asdf:load-op 'cow)

If the file

cow.asd

happens to be in the current working directory, the build and load process will start there. If not, ASDF will search through the directories in the central registry, and look for a system definition file named

cow.asd

, or for a symbolic link to one. If it finds the latter, it will follow the link to the original file, and run the build process in the corresponding directory. If it finds the file, it will run the build process in the directory where it finds it.

So, if you make a symbolic link in

/home/foo/lisp/systems/

to the

cow

system definition file, by executing (for example)

$ cd <where-your-system-defs-are>
$ ln -s /home/foo/code/cow/cow.asd

Then you can build and load the cow software without having to be in the directory where this software lives simply by issuing the command

(asdf:operate 'asdf:load-op 'cow)

Some folks, instead of keywords, use uninterned symbols, using the

#:

syntax.

(defpackage #:com.gigamonkeys.email-db
(:use #:common-lisp))

This saves a tiny bit of memory by not interning any symbols in the keyword package--the symbol can become garbage after

DEFPACKAGE

(or the code it expands into) is done with it. However, the difference is so slight that it really boils down to a matter of aesthetics.

参考：

[1] Programming in the Large: Packages and Symbols

http://www.gigamonkeys.com/book/programming-in-the-large-packages-and-symbols.html

[2] http://www.lispworks.com/documentation/lw60/CLHS/Body/m_defpkg.htm
[3]
http://common-lisp.net/~mmommer/asdf-howto.shtml

[4]
http://common-lisp.net/project/asdf/asdf.html#The-defsystem-form