topheader Welcome 3.233.215.231 @ xps.scios.ch on Thu Feb 20 15:20:21 CET 2020
topheader
 

ASDF Manual

Introduction

ASDF is another system definition facility: a tool for describing the sub-systems and files that comprise a system and for operating on these components in the right order so that they can be compiled, loaded, tested, etc.

ASDF presents two faces: one for system implementors who need to be able to describe their systems and one for Lisp programmers who want to use those systems. See the getting started guide to learn how to use ASDF to load a system. This document describes how to write your own system definitions for ASDF.

Defining systems with defsystem

This chapter describes how to use ASDF to define systems and develop software. First, some definitions:

  • component - a piece of a system. Systems are made of components. They range from individual files, to groups of files called modules, to entire sub-systems.
  • module - a component comprised of a group of components. A module is smaller than a system but (usually) larger than a single file.
  • operation - something done to a system. The most typical operations are compile, load, and test but ASDF is extensible so many others are possible.
  • system - a group of files, modules and sub-systems (i.e., components) packaged into a coherent whole.

The defsystem form

Systems are defined with the defsystem macro 1 This section begins with a simple example, then gives the full grammar of defsystem. Here is a complete system definition that should be saved in the file hello-lisp.asd 2:

(defpackage hello-lisp-system (:use :common-lisp :asdf))  
 
(in-package :hello-lisp-system)  
 
(defsystem "hello-lisp"  
  :description "hello-lisp: a sample Lisp system."  
  :version "0.2"  
  :author "Joe User <joe@example.com>"  
  :licence "Public Domain"  
  :components ((:file "packages")  
               (:file "macros" :depends-on ("packages"))  
               (:file "hello" :depends-on ("macros"))))

Some notes about this example:

  • The file starts with defpackage and in-package forms to define and use a package expressly for this system definition. By convention, this package is named by taking the system name and suffixing -system - note that it is not the same package that you will use for the application code. This is not required by ASDF, but helps avoid namespace pollution and so is considered good form.
  • The defsystem form defines a system named “hello-lisp” that contains three source files: packages, macros and hello.
  • The :depends-on clauses tell ASDF that the file macros depends on packages (presumably because the package it's in is defined in packages), and the file hello depends on macros (and hence transitively on packages). This means that ASDF will compile and load packages and macros before starting the compilation of the file hello.
  • The files are located in the same directory as the file with the system definition. ASDF resolves symbolic links before loading the system definition file and stores its location in the resulting system 3 . This is a good thing because the user can move the system sources without having to edit the system definition.
  • the :version, :author, description and other fields are not required but they provide documentation and information for people that want to use this system.

A more involved example

Let's illustrate some more involved uses of defsystem via a slightly convoluted example:

(defsystem "foo"  
  :version "1.0"  
  :components  
  ((:module "foo"  
    :components ((:file "bar")  
                 (:file "baz")  
                 (:file "quux"))  
    :perform (compile-op :after (op c) (do-something c))  
    :explain (compile-op :after (op c) (explain-something c)))  
   (:file "blah")))

The :perform tokens need explaining: essentially, these clauses:

:perform (compile-op :after (op c)  
           (do-something c))  
:explain (compile-op :after (op c)  
           (explain-something c))

have the effect of

 (defmethod perform :after ((op compile-op) (c (eql ...)))  
      (do-something c))  
 
 (defmethod explain :after ((op compile-op) (c (eql ...)))  
      (explain-something c))

where is the component in question. 4

The defsystem grammar

system-definition := ( defsystem system-designator {option}* )  
 
option         := :components component-list  
                | :pathname pathname  
                | :default-component-class  
                | :perform method-form  
                | :explain method-form  
                | :output-files  method-form  
                | :operation-done-p method-form  
                | :depends-on ( {dependency-def}* )  
                | :serial [ t | nil ]  
                | :weakly-depends-on ( {dependency-def}* )  
                | :in-order-to ( {dependency}+ )  
                | :class symbol  
 
component-list := ( {component-def}* )  
 
component-def  := component-name  
                | ( component-type name {option}* )  
 
component-type := :module | :file  
                | :system | other-component-type  
 
dependency-def := component-name  
                | ( :feature feature-name )  
                | ( :version component-name version-specifier)  
 
dependency     := ( dependent-op {requirement}+ )  
requirement    := ( required-op {required-component}+ )  
                | ( feature feature-name )  
dependent-op   := operation-name  
required-op    := operation-name  
 
component-name := string  
                | symbol  
 
operation-name := symbol  
feature-name   := symbol  
 
version-specifier := number[.number]*

Serial dependencies

If the :serial t option is specified for a module, ASDF will add dependencies for each each child component, on all the children textually preceding it. This is done as if by :depends-on.

:serial t  
:components ((:file "a") (:file "b") (:file "c"))

is equivalent to

:components ((:file "a")  
             (:file "b" :depends-on ("a"))  
             (:file "c" :depends-on ("a" "b")))

Weakly-depends-on

The weakly-depends-on argument says of the component depended on “if this component can be found, then impose a dependency, otherwise ignore it.” At the top level, this can be useful for allowing a system to take advantage of another system, if it is present. For example, a system might generate on-line documentation if a documentation generation system (like TINAA, Albert, etc.) was present. A system that does text matching might do only simple matching but weakly depend on a regular expression system and, if that system is installed, would be able to also do regular expression matching.

Notes:
  • It's not entirely clear that this option is very helpful at a level below the top-level. Since it uses find-component, the behavior differs between top level and lower level; perhaps that needs to be explained.
  • Presumably this will be most useful when complemented by some conditional loading construct in the system that has the dependency. What is that construct?

Source location

The :pathname option is optional in all cases for systems defined via defsystem, and in the usual case the user is recommended not to supply it.

Instead, ASDF follows a hairy set of rules that are designed so that

  1. find-system will load a system from disk and have its pathname default to the right place
  2. this pathname information will not be overwritten with *default-pathname-defaults* (which could be somewhere else altogether) if the user loads up the .asd file into his editor and interactively re-evaluates that form.

If a system is being loaded for the first time, its top-level pathname will be set to:

  • The host/device/directory parts of *load-truename*, if it is bound
  • *default-pathname-defaults*, otherwise

If a system is being redefined, the top-level pathname will be

  • changed, if explicitly supplied or obtained from *load-truename* (so that an updated source location is reflected in the system definition)
  • changed if it had previously been set from *default-pathname-defaults*
  • left as before, if it had previously been set from *load-truename* and *load-truename* is currently unbound (so that a developer can evaluate a defsystem form from within an editor without clobbering its source location)

Other code in .asd files

Files containing defsystem forms are regular Lisp files that are executed by load. Consequently, you can put whatever Lisp code you like into these files (e.g., code that examines the compile-time environment and adds appropriate features to *features*). However, some conventions should be followed, so that users can control certain details of execution of the Lisp in .asd files:

  • Any informative output (other than warnings and errors, which will be handled by the condition system) should be sent to the Common Lisp stream *standard-output*, so that users can easily control the disposition of output from ASDF operations.

System dependencies

Warning: As of July 20, 2009, this aspect of ASDF is in flux. We suggest not relying too heavily on the current syntax.

There are several ways in which one system can depend on another:

  • simple dependency (the default)
  • weak dependency (using :weakly-depends-on)
  • contingent dependency (not currently implemented)

The following tables illustrate how these dependencies work:

Simple

component statuseffect
expressioncomponent acomponent/feature b
a (:depends-on (:b))presentpresent(operate b), (operate a)
a (:depends-on (:b))presentabsenterror
a (:depends-on (:b))absentpresenterror
a (:depends-on (:b))absentabsenterror

:weakly-depends-on

component statuseffect
expressioncomponent acomponent/feature b
a (:weakly-depends-on (:b))presentpresent(operate b), (operate a)
a (:weakly-depends-on (:b))presentabsent(operate a)
a (:weakly-depends-on (:b))absentpresenterror
a (:weakly-depends-on (:b))absentabsenterror

Contingent

component statuseffect
expressioncomponent acomponent/feature b
a (:contingent-on (:b))presentpresent(operate b), (operate a)
a (:contingent-on (:b))presentabsent
a (:contingent-on (:b))absentpresenterror
a (:contingent-on (:b))absentabsenterror

The object model of ASDF

ASDF is entirely object-oriented. Both a system's structure and the operations that can be performed on systems follow a protocol. ASDF is extensible to new operations and to new component types. This allows the addition of behaviours: for example, a new component could be added for Java JAR archives, and methods specialised on compile-op added for it that would accomplish the relevant actions.

This chapter deals with components, the building blocks of a system, and operations, the actions that can be performed on a system.

Operations

An operation object of the appropriate type is instantiated whenever the user wants to do something with a system like:

  • compile all its files,
  • load the files into a running lisp environment,
  • copy its source files somewhere else.

Operations can be invoked directly, or examined to see what their effects would be without performing them. FIXME: document how! There are a bunch of methods specialised on operation and component type that actually do the grunt work.

The operation object contains whatever state is relevant for this purpose (perhaps a list of visited nodes, for example) but primarily is a nice thing to specialise operation methods on and easier than having them all be EQL methods.

Operations are invoked on systems via operate or its synonym oos:

X operate operation-class  system  &rest  args  &key  (verbose t)  version  force  &allow-other-keys

function

Operate does three things:

  1. It creates an instance of operation-class using any keyword parameters as initargs.
  2. It finds the asdf-system specified by system (possibly loading it from disk).
  3. It then calls traverse with the operation and system as arguments

The traverse operation is wrapped in with-compilation-unit and error handling code. If a version argument is supplied, then operate also ensures that the system found satisfies it using the version-satisfies method.

Note that dependencies may cause the operation to invoke other operations on the system or its components: the new operations will be created with the same initargs as the original one.

X oos operation-class  system  &rest  args  &key  force  (verbose t)  version  &allow-other-keys

function

Short for operate on system and an alias for the operate function. Operate does three things:

  1. It creates an instance of operation-class using any keyword parameters as initargs.
  2. It finds the asdf-system specified by system (possibly loading it from disk).
  3. It then calls traverse with the operation and system as arguments

The traverse operation is wrapped in with-compilation-unit and error handling code. If a version argument is supplied, then operate also ensures that the system found satisfies it using the version-satisfies method.

Note that dependencies may cause the operation to invoke other operations on the system or its components: the new operations will be created with the same initargs as the original one.

Predefined operations of ASDF

All the operations described in this section are in the ASDF package. They are invoked via the operate generic function.

(asdf:operate 'asdf:operation-name 'system-name {operation-options ...})

– Operation: compile-op &key proclamations

This operation compiles the specified component. If proclamations are supplied, they will be proclaimed. This is a good place to specify optimization settings.

When creating a new component type, you should provide methods for compile-op.

When compile-op is invoked, component dependencies often cause some parts of the system to be loaded as well as compiled. Invoking compile-op does not necessarily load all the parts of the system, though; use load-op to load a system.

– Operation: load-op &key proclamations

This operation loads a system.

The default methods for load-op compile files before loading them. For parity, your own methods on new component types should probably do so too.

– Operation: load-source-op

This operation will load the source for the files in a module even if the source files have been compiled. Systems sometimes have knotty dependencies which require that sources are loaded before they can be compiled. This is how you do that.

If you are creating a component type, you need to implement this operation - at least, where meaningful.

– Operation: test-op

This operation should test the specified component. ASDF does not (currently) provide a method for returning a value from the test-op (or any other operation), so the implementor must ensure that executing test-op has the side effect of printing useful information about the tests to the CL stream *standard-output*.

The default method for test-op does nothing, and will have to be overridden, but invoking test-op on a component for which nothing is defined will be a simple no-op.

The default dependency for test-op on a system is to require load-op on that system.

The default method for operation-done-p for test-op is to return nil regardless of component because tests should usually be run whether or not they have been run previously.

Creating new operations

ASDF was designed to be extensible in an object-oriented fashion. To teach ASDF new tricks, a programmer can implement the behaviour he wants by creating a subclass of operation.

ASDF's pre-defined operations are in no way “privileged”, but it is requested that developers never use the ASDF package for operations they develop themselves. The rationale for this rule is that we don't want to establish a “global ASDF operation name registry”, but also want to avoid name clashes.

An operation must provide methods for the following generic functions when invoked with an object of type source-file: FIXME describe this better

  • output-files
  • perform The perform method must call output-files to find out where to put its files, because the user is allowed to override
  • output-files for local policy explain
  • operation-done-p, if you don't like the default one

Operations that print output should send that output to the standard CL stream *standard-output*, as the Lisp compiler and loader do.

Components

A component represents a source file or (recursively) a collection of components. A system is (roughly speaking) a top-level component that can be found via find-system.

A system designator is a string or symbol and behaves just like any other component name (including with regard to the case conversion rules for component names).

– Function: find-system system-designator &optional (error-p t)

Given a system designator, find-system finds and returns a system. If no system is found, an error of type missing-component is thrown, or nil is returned if error-p is false.

To find and update systems, find-system funcalls each element in the *system-definition-search-functions* list, expecting a pathname to be returned. The resulting pathname is loaded if either of the following conditions is true:

  • there is no system of that name in memory
  • the file's last-modified time exceeds the last-modified time of the system in memory

When system definitions are loaded from .asd files, a new scratch package is created for them to load into, so that different systems do not overwrite each others operations. The user may also wish to (and is recommended to) include defpackage and in-package forms in his system definition files, however, so that they can be loaded manually if need be.

The default value of *system-definition-search-functions* is a function that looks in each of the directories given by evaluating members of *central-registry* for a file whose name is the name of the system and whose type is asd. The first such file is returned, whether or not it turns out to actually define the appropriate system. Hence, it is strongly advised to define a system foo in the corresponding file foo.asd.

Common attributes of components

All components, regardless of type, have the following attributes. All attributes except name are optional.

Name

A component name is a string or a symbol. If a symbol, its name is taken and lowercased. The name must be a suitable value for the :name initarg to make-pathname in whatever filesystem the system is to be found.

The lower-casing-symbols behaviour is unconventional, but was selected after some consideration. Observations suggest that the type of systems we want to support either have lowercase as customary case (Unix, Mac, windows) or silently convert lowercase to uppercase (lpns), so this makes more sense than attempting to use :case :common as argument to make-pathname, which is reported not to work on some implementations

Version identifier

This optional attribute is used by the test-system-version operation. See Predefined operations of ASDF. For the default method of test-system-version, the version should be a string of integers separated by dots, for example '1.0.11'.

Required features

Traditionally defsystem users have used reader conditionals to include or exclude specific per-implementation files. This means that any single implementation cannot read the entire system, which becomes a problem if it doesn't wish to compile it, but instead for example to create an archive file containing all the sources, as it will omit to process the system-dependent sources for other systems.

Each component in an ASDF system may therefore specify features using the same syntax as #+ does, and it will (somehow) be ignored for certain operations unless the feature conditional is a member of *features*.

Dependencies

This attribute specifies dependencies of the component on its siblings. It is optional but often necessary.

There is an excitingly complicated relationship between the initarg and the method that you use to ask about dependencies

Dependencies are between (operation component) pairs. In your initargs for the component, you can say

:in-order-to ((compile-op (load-op "a" "b")  
              (compile-op "c"))  
              (load-op (load-op "foo")))

This means the following things:

  • before performing compile-op on this component, we must perform load-op on a and b, and compile-op on c,
  • before performing load-op, we have to load foo

The syntax is approximately

(this-op {(other-op required-components)}+)  
 
required-components := component-name  
                     | (required-components required-components)  
 
component-name := string  
                | (:version string minimum-version-object)

Side note:

This is on a par with what ACL defsystem does. mk-defsystem is less general: it has an implied dependency

for all x, (load x) depends on (compile x)

and using a :depends-on argument to say that b depends on a actually means that

(compile b) depends on (load a)

This is insufficient for e.g. the McCLIM system, which requires that all the files are loaded before any of them can be compiled ]

End side note

In ASDF, the dependency information for a given component and operation can be queried using (component-depends-on operation component), which returns a list

((load-op "a") (load-op "b") (compile-op "c") ...)

component-depends-on can be subclassed for more specific component/operation types: these need to (call-next-method) and append the answer to their dependency, unless they have a good reason for completely overriding the default dependencies

pathname

This attribute is optional and if absent will be inferred from the component's name, type (the subclass of source-file), and the location of its parent.

The rules for this inference are:

(for source-files)

  • the host is taken from the parent
  • pathname type is (source-file-type component system)
  • the pathname case option is :local
  • the pathname is merged against the parent

(for modules)

  • the host is taken from the parent
  • the name and type are NIL
  • the directory is (:relative component-name)
  • the pathname case option is :local
  • the pathname is merged against the parent

Note that the DEFSYSTEM operator (used to create a “top-level” system) does additional processing to set the filesystem location of the top component in that system. This is detailed elsewhere, See Defining systems with defsystem.

The answer to the frequently asked question “how do I create a system definition where all the source files have a .cl extension” is thus

(defmethod source-file-type ((c cl-source-file)  
                             (s (eql (find-system 'my-sys))))  
   "cl")
properties

This attribute is optional.

Packaging systems often require information about files or systems in addition to that specified by ASDF's pre-defined component attributes. Programs that create vendor packages out of ASDF systems therefore have to create “placeholder” information to satisfy these systems. Sometimes the creator of an ASDF system may know the additional information and wish to provide it directly.

(component-property component property-name) and associated setf method will allow the programmatic update of this information. Property names are compared as if by EQL, so symbols or keywords are usually used for property names.

Pre-defined subclasses of component

– Component: source-file

A source file is any file that the system does not know how to generate from other components of the system.

Note that this is not necessarily the same thing as “a file containing data that is typically fed to a compiler”. If a file is generated by some pre-processor stage (e.g. a .h file from .h.in by autoconf) then it is not, by this definition, a source file. Conversely, we might have a graphic file that cannot be automatically regenerated, or a proprietary shared library that we received as a binary: these do count as source files for our purposes.

Subclasses of source-file exist for various languages. FIXME: describe these.

– Component: module

A module is a collection of sub-components.

A module component has the following extra initargs:

  • :components the components contained in this module
  • :default-component-class All child components which don't specify their class explicitly are inferred to be of this type.
  • :if-component-dep-fails This attribute takes one of the values :fail, :try-next, :ignore, its default value is :fail. The other values can be used for implementing conditional compilation based on implementation *features*, for the case where it is not necessary for all files in a module to be compiled.
  • :serial When this attribute is set, each subcomponent of this component is assumed to depend on all subcomponents before it in the list given to :components, i.e. all of them are loaded before a compile or load operation is performed on it.

The default operation knows how to traverse a module, so most operations will not need to provide methods specialised on modules.

module may be subclassed to represent components such as foreign-language linked libraries or archive files.

– Component: system

system is a subclass of module.

A system is a module with a few extra attributes for documentation purposes; these are given elsewhere. See The defsystem grammar.

Users can create new classes for their systems: the default defsystem macro takes a :classs keyword argument.

Creating new component types

New component types are defined by subclassing one of the existing component classes and specializing methods on the new component class.

FIXME: this should perhaps be explained more throughly, not only by example …

As an example, suppose we have some implementation-dependent functionality that we want to isolate in one subdirectory per Lisp implementation our system supports. We create a subclass of cl-source-file:

(defclass unportable-cl-source-file (cl-source-file) ())

A hypothetical function system-dependent-dirname gives us the name of the subdirectory. All that's left is to define how to calculate the pathname of an unportable-cl-source-file.

(defmethod component-pathname ((component unportable-cl-source-file))  
  (let ((pathname (call-next-method))  
  (name (string-downcase (system-dependent-dirname))))  
    (merge-pathnames (make-pathname  
          :directory (list :relative name)) pathname)))

The new component type is used in a defsystem form in this way:

 (defsystem :foo  
     :components  
     ((:file "packages")  
      ...  
      (:unportable-cl-source-file "threads"  
       :depends-on ("packages" ...))  
      ...  
     )

Controlling where ASDF saves compiled files

ASDF includes code to control where the binaries files are places. The location depends on the the Common Lisp implementation and platform. The getting-started guides summaries the variables that control the mapping. The details for each variable can be found below:

Customization

X *centralize-lisp-binaries*

variable

If true, compiled lisp files without an explicit mapping (see *source-to-target-mappings*) will be placed in subdirectories of *default-toplevel-directory*. If false, then compiled lisp files without an explicitly mapping will be placed in subdirectories of their sources.

X *default-toplevel-directory*

variable

If *centralize-lisp-binaries* is true, then compiled lisp files without an explicit mapping (see *source-to-target-mappings*) will be placed in subdirectories of *default-toplevel-directory*.

X *include-per-user-information*

variable

When *centralize-lisp-binaries* is true this variable controls whether or not to customize the output directory based on the current user. It can be nil, t or a string. If it is nil (the default), then no additional information will be added to the output directory. If it is t, then the user's name (as taken from the return value of #'user-homedir-pathname) will be included into the centralized path (just before the lisp-implementation directory). Finally, if *include-per-user-information* is a string, then this string will be included in the output-directory.

X *map-all-source-files*

variable

If true, then all subclasses of source-file will have their output locations mapped by ASDF-Binary-Locations. If nil (the default), then only subclasses of cl-source-file will be mapped.

X *enable-asdf-binary-locations*

variable

If true, then compiled lisp files will be placed into a directory computed from the Lisp version, Operating System and computer archetecture. See implementation-specific-directory-name for details.

X *source-to-target-mappings*

variable

The *source-to-target-mappings* variable specifies mappings from source to target. If the target is nil, then it means to not map the source to anything. I.e., to leave it as is. This has the effect of turning off ASDF-Binary-Locations for the given source directory. Examples:

;; compile everything in .../src and below into .../cmucl  
'(("/nfs/home/compbio/d95-bli/share/common-lisp/src/"  
   "/nfs/home/compbio/d95-bli/lib/common-lisp/cmucl/"))  
 
;; leave SBCL innards alone (SBCL specific)  
(list (list (princ-to-string (sb-ext:posix-getenv "SBCL_HOME")) nil))

X implementation-specific-directory-name

function

Return a name that can be used as a directory name that is unique to a Lisp implementation, Lisp implementation version, operating system, and hardware architecture.

X output-files-for-system-and-operation system  operation  component  source  possible-paths

function

Returns the directory where the componets output files should be placed. This may depends on the system, the operation and the component. The ASDF default input and outputs are provided in the source and possible-paths parameters.

Notes and Issues

  • SBCL ships with several included ASDF libraries which used to confuse ABL because it would try to recompile the FASLs and then run into directory permission problems. ASDF knows about these and uses a mapping like /usr/local/lib/sbcl to nil so that the FASLs are not relocated.

Special variables

X *asdf-revision*

variable

No documentation found

X *central-registry*

variable

A list of 'system directory designators' ASDF uses to find systems.

A 'system directory designator' is a pathname or a function which evaluates to a pathname. For example:

(setf asdf:*central-registry*  
      (list '*default-pathname-defaults*  
            #p"/home/me/cl/systems/"  
            #p"/usr/share/common-lisp/systems/"))

X *compile-file-warnings-behaviour*

variable

No documentation found

X *compile-file-failure-behaviour*

variable

No documentation found

X *resolve-symlinks*

variable

Determine whether or not ASDF resolves symlinks when defining systems.

Defaults to t.

X *system-definition-search-functions*

variable

No documentation found

Error handling

It is an error to define a system incorrectly: an implementation may detect this and signal a generalised instance of SYSTEM-DEFINITION-ERROR.

Operations may go wrong (for example when source files contain errors). These are signalled using generalised instances of OPERATION-ERROR.

Compilation error and warning handling

ASDF checks for warnings and errors when a file is compiled. The variables *compile-file-warnings-behaviour* and *compile-file-errors-behavior* controls the handling of any such events. The valid values for these variables are :error, :warn, and :ignore.

Additional Functionality

ASDF includes several additional features that are generally useful for system definition and development. These include:

  1. system-relative-pathname

It's often handy to locate a file relative to some system. The system-relative-pathname function meets this need. It takes two arguments: the name of a system and a relative pathname. It returns a pathname built from the location of the system's source file and the relative pathname. For example

> (asdf:system-relative-pathname 'cl-ppcre "regex.data")  
#P"/repository/other/cl-ppcre/regex.data"

Getting the latest version

To get the greatest and latest, you can:

  • download just the source for asdf.lisp,
  • download the tarball to get all bells and whistles,
  • pull the latest from our git repository
    git clone http://common-lisp.net/project/asdf/asdf.git

TODO list

Outstanding spec questions, things to add

  • packaging systems
  • manual page component?
  • style guide for .asd files
  • You should either use keywords or be careful with the package that you evaluate defsystem forms in. Otherwise (defsystem partition …) being read in the cl-user package will intern a cl-user:partition symbol, which will then collide with the partition:partition symbol. Actually there's a hairier packages problem to think about too. in-order-to is not a keyword: if you read defsystem forms in a package that doesn't use ASDF, odd things might happen
  • extending defsystem with new options You might not want to write a whole parser, but just to add options to the existing syntax. Reinstate parse-option or something akin
  • document all the error classes
  • what to do with compile-file failure
  • Should check the primary return value from compile-file and see if that gets us any closer to a sensible error handling strategy
  • foreign files
  • lift unix-dso stuff from db-sockets
  • Diagnostics
  • A “dry run” of an operation can be made with the following form:
    (traverse (make-instance '<operation-name>) (find-system <system-name>) 'explain)

    This uses unexported symbols. What would be a nice interface for this functionality?

missing bits in implementation

  • all of the above
  • reuse the same scratch package whenever a system is reloaded from disk
  • rules for system pathname defaulting are not yet implemented properly
  • proclamations probably aren't
  • when a system is reloaded with fewer components than it previously had, odd things happen

we should do something inventive when processing a defsystem form, like take the list of kids and setf the slot to nil, then transfer children from old to new list as they're found

  • traverse may become a normal function If you're defining methods on traverse, speak up.
  • a lot of load-op methods can be rewritten to use input-files and so perhaps they should be.
  • (stuff that might happen later)
  • david lichteblau's patch for symlink resolution?
  • Propagation of the :force option. “I notice that
    (oos 'compile-op :araneida :force t)
  • also forces compilation of every other system the :araneida system depends on. This is rarely useful to me; usually, when I want to force recompilation of something more than a single source file, I want to recompile only one system. So it would be more useful to have make-sub-operation refuse to propagate :force t to other systems, and propagate only something like :force :recursively. Ideally what we actually want is some kind of criterion that says to which systems (and which operations) a :force switch will propagate. The problem is perhaps that force' is a pretty meaningless concept. How obvious is it that load :force t should force _compilation_? But we don't really have the right dependency setup for the user to compile :force t` and expect it to work (files will not be loaded after compilation, so the compile environment for subsequent files will be emptier than it needs to be) What does the user actually want to do when he forces? Usually, for me, update for use with a new version of the lisp compiler. Perhaps for recovery when he suspects that something has gone wrong. Or else when he's changed compilation options or configuration in some way that's not reflected in the dependency graph.
  • Other possible interface: have a 'revert' function akin to 'make clean'
     (asdf:revert 'asdf:compile-op 'araneida)
  • would delete any files produced by 'compile-op 'araneida. Of course, it wouldn't be able to do much about stuff in the image itself. How would this work?
  • traverse There's a difference between a module's dependencies (peers) and its components (children). Perhaps there's a similar difference in operations? For example, (load “use”) depends-on (load “macros”) is a peer, whereas (load “use”) depends-on (compile “use”) is more of a `subservient' relationship.

Inspiration

mk-defsystem (defsystem-3.x)

We aim to solve basically the same problems as mk-defsystem does. However, our architecture for extensibility better exploits CL language features (and is documented), and we intend to be portable rather than just widely-ported. No slight on the mk-defsystem authors and maintainers is intended here; that implementation has the unenviable task of supporting pre-ANSI implementations, which is no longer necessary.

The surface defsystem syntax of ASDF is more-or-less compatible with mk-defsystem, except that we do not support the source-foo and binary-foo prefixes for separating source and binary files, and we advise the removal of all options to specify pathnames.

The mk-defsystem code for topologically sorting a module's dependency list was very useful.

defsystem-4 proposal

Marco and Peter's proposal for defsystem 4 served as the driver for many of the features in here. Notable differences are:

  • We don't specify output files or output file extensions as part of the system.

If you want to find out what files an operation would create, ask the operation.

  • We don't deal with CL packages

If you want to compile in a particular package, use an in-package form in that file (ilisp / SLIME will like you more if you do this anyway)

  • There is no proposal here that defsystem does version control.

A system has a given version which can be used to check dependencies, but that's all.

The defsystem 4 proposal tends to look more at the external features, whereas this one centres on a protocol for system introspection.

kmp's "The Description of Large Systems", MIT AI Memo 801

Available in updated for Common Lisp form on the web.

In our implementation we borrow kmp's overall PROCESS-OPTIONS and concept to deal with creating component trees from defsystem surface syntax. [ this is not true right now, though it used to be and probably will be again soon ].

Footnotes

  1. Systems can be constructed programmatically by instantiating components using make-instance. Most of the time, however, it is much more practical to use defsystem.
  2. Though it can be changed, ASDF's standard system finding algorithms looks for a system named foo in a file named foo.asd.
  3. It is possible, though almost never necessary, to override this behaviour.
  4. note that although this also supports :before methods, they may not do what you want them to - a :before method on perform ((op compile-op) (c (eql …))) will run after all the dependencies and sub-components have been processed, but before the component in question has been compiled.

Copyright © 2001-2009 Daniel Barlow and contributors

ASDF has an MIT style license

Last updated 18 October 2009 at 22:44

 
 
cl/asdf_manual.txt · Last modified: 2010/01/12 03:04 by admin
topheader
© 1998-2019, SciOS Scientific Operating Systems GmbH

Legal | Credits | Profile | Contact | Customer Login