topheader Welcome 54.234.184.8 @ xps.scios.ch on Fri Mar 29 15:41:15 UTC 2024
topheader
 

ASDF Getting Started

Introduction

Simple Lisp programs are defined in a single file; to use them, you load the file and go. More complicated systems, however, are made up of many files (and possibly depend on other systems made up of their own files). Using these requires loading the sub-systems and files in the right order – an error-prone and tedious task.

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. This document describes ASDF for the second audience. If you want to build your own systems with ASDF, then you'll also want to read the ASDF system definition guide.

Installing ASDF

Download

Many Lisp implementations include a copy of ASDF. You can usually load this copy using Common-Lisp's require function:

* (require 'asdf)  
("ASDF")

Consult your Lisp's documentation for details. If ASDF doesn't come bundled with your Lisp or if you want to make sure that you have the most recent version, then you'll want to download it from the common-lisp.net website.

Setup

The single file asdf.lisp is all you need to use ASDF. Once you load it in a running Lisp, you're ready to go. For maximum convenience you will want to have ASDF loaded whenever you start your Lisp. check your implementation's manual for details on how to load it from the startup script or creating a custom Lisp image.

Using

ASDF provides three commands for the most common system operations: load-system, compile-system, and test-system:

X load-system system  &key

function

X compile-system system  &key

function

X test-system system  &rest  args  &key  force  (verbose t)  version

function

Shorthand for (operate 'asdf:test-op system). See operate for details.

Because ASDF is an extensible system for defining operations on components, it also provides a generic function: operate (which is usually abbreviated by oos). You'll use oos whenever you want to do something beyond compiling, loading and testing.

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.

Before ASDF can operate on a system, however, it must be able to find that system's definition.

How ASDF finds systems

You can load system definition files by hand:

(load "/path/to/my/system/my-system.asd")

or you can tell ASDF where to look to find them using the *central-registry* parameter.

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/"))

You'll need to set this variable up to match your system setup and will probably want to include it in your Lisp's startup script.

Controlling where ASDF saves compiled files

Each Common Lisp implementation has its own format for compiled files (fasls for short). If you use multiple implementations (or multiple versions of the same implementation), you'll soon find your source directories littered with various DFSLs, FASLs, CFSLs and so on. Worse yet, some implementations use the same file extension or change formats from version to version which means that you'll have to recompile binaries as you switch from one implementation to the next.

As of version 1.365, ASDF includes ASDF-binary-locations to mitigate the problem.

Default Locations

The default binary location for each Lisp implementation is a subdirectory of each source directory. To account for different Lisps, Operating Systems, Implementation versions, and so on, ASDF borrows code from SLIME to create reasonable custom directory names. Here are some examples:

  • SBCL, version 1.0 on Mac OS X for intel: sbcl-1.0-darwin-x86
  • Franz Allegro, version 8.0, ANSI Common Lisp: allegro-8.0a-macosx-x86
  • Franz Allegro, version 8.1, Modern (case sensitive) Common Lisp: allegro-8.1m-macosx-x86

If you want to keep FASL files out of source tree entirely *centralize-lisp-binaries* to put compiled files into sub-directories of a single central location (see

Here is a summary of the variables that control ASDF's source-to-binary mappings:

  • *enable-asdf-binary-locations*: If false, then ASDF will place binaries in the same directory as the source. If true, then ASDF will move the binaries using the rest of the configuration. Defaults to nil.
  • *centralize-lisp-binaries*: 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 explicit mapping will be placed in subdirectories of their sources. Defaults to nil.
  • *default-toplevel-directory*. 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*. Defaults to a sub-directory named .fasls in the current user's home directory.
  • *include-per-user-information*. specifies whether or not to include user information in the directory. Only used when *centralize-lisp-binaries* is true. Defaults to nil.
  • *map-all-source-files*. If true, then all source files will be mapped by ASDF. If nil, then only Common Lisp Source Files (i.e., instances of cl-source-file or its subclasses) will be. Defaults to nil.
  • *source-to-target-mappings*. This 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. The default depends on the Lisp implementation.

These variables are used by output-files-for-system-and-operation to determine where to place a source file's binary. You can further customize ABL by writing additional methods on the generic function output-files-for-system-and-operation.

See the manual for more details.

Summary

To use ASDF:

Indices

Copyright © 2001-2009 Daniel Barlow and contributors

ASDF has an MIT style license

Last updated 18 October 2009 at 22:44

 
 
cl/getting-started.txt · Last modified: 2010/01/12 02:08 by admin
topheader
© 1998-2021, SciOS Scientific Operating Systems GmbH

Legal | Credits | Profile | Contact | Customer Login