ASDF-Binary-Locations

How to use it - the short version

What it is

ASDF-Binary-Locations (ABL) is an ASDF-Extension that makes it easy to specify where your Common Lisp binaries (FASL files) should go.

How to use it - the short version

Install ASDF-Binary-Locations using your method of choice.
Customize it as desired (see below).
ASDF load it before loading anything else (perhaps from your Lisp's initialization file)

What it does

Each Common Lisp implementation has its own format for compiled files (fasls for short). If you use multiple implementations (or even just multiple versions of the same implementation), you'll soon find your source directories littered with various DFSLs, FASLs, CFSLs and so on. This is ugly and makes finding what you want more difficult. Worse yet, some implementations share the same file extension or change formats from version to version. This means that you'll have to recompile binaries as you switch from one implementation to the next. That's downright inefficient.

ASDF-Binary-Locations prevents this nightmare by:

Providing reasonable default locations for binaries of each Lisp and,
by allowing you to customize the locations as required.

Default Locations

ABL's 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, ABL 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

It may be more convenient to keep FASL files out of sources entirely and have ABL put all compiled files into subdirectories of a single central location (see *centralize-lisp-binaries* below).

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

*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 explicitly mapping will be placed in subdirectories of their sources.
*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*.
*include-per-user-information* - specifies whether or not to include user information in the directory. Only used when *centralize-lisp-binaries* is true.
*map-all-source-files* - If true, then all source files will be mapped by ABL. If nil (the default), then only Common Lisp Source Files (i.e., instances of cl-source-file or its subclasses) will be.
*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.

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.

Customization

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.

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*.

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.

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.

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

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.

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. ABL now knows about these and uses a mapping like /usr/local/lib/sbcl to nil so that the FASLs are not relocated.