Skip to content
Snippets Groups Projects
Commit 4158a412 authored by Francois-Rene Rideau's avatar Francois-Rene Rideau
Browse files

Merge branch 'master' of http://common-lisp.net/project/asdf/asdf

Conflicts:
	README.asdf-output-translations
parents 50e98dab 9b5eaf96
No related branches found
No related tags found
No related merge requests found
========================
ASDF Output Translations
========================
This file specifies how ASDF stores "binary" outputs for its operations,
typically Lisp FASL files, but also any other files
that may be generated, e.g. C files and executables from CFFI-GROVEL.
Configurations
==============
Configurations specify mappings from source locations to binary locations.
1- An application may explicitly initialize the output-translations
configuration using the `Configuration API`_ below,
in which case this takes precedence.
It may itself compute this configuration from the command-line,
from a script, from its own configuration file, etc.
2- The source registry will be configured from
the environment variable ``ASDF_OUTPUT_TRANSLATIONS`` if it exists.
3- The source registry will be configured from
user configuration file
``~/.config/common-lisp/asdf-output-translations.conf``
if it exists.
4- The source registry will be configured from
user configuration directory
``~/.config/common-lisp/asdf-output-translations.conf.d/``
if it exists.
5- The source registry will be configured from
system configuration file
``/etc/common-lisp/asdf-output-translations.conf``
if it exists.
6- The source registry will be configured from
system configuration directory
``/etc/common-lisp/asdf-output-translations.conf.d/``
if it exists.
Each of these configurations is specified as a SEXP
in a trival domain-specific language (defined below).
Additionally, a more shell-friendly syntax is available
for the environment variable (defined yet below).
Each of these configurations is only used if the previous
configuration explicitly or implicitly specifies that it
includes its inherited configuration.
Additionally, some implementation-specific directories
may be automatically added to whatever mappings are specified
in configuration files, no matter if the last one inherits or not.
Backward Compatibility
======================
We purposefully do NOT provide backward compatibility with earlier versions of
asdf-binary-locations (8 Sept 2009),
common-lisp-controller (7.00) or
cl-launch (2.35),
each of which had similar general capabilities.
Future versions of same packages (if any)
will hopefully use the new ASDF API as defined below.
These previous programs' API was not designed
for easy configuration by the end-user
in an easy way with configuration files,
and their previous API didn't fit the new paradigm.
But this incompatibility won't inconvenience many people.
Indeed, few people use and customize these packages;
these people are experts who can trivially adapt to the new configuration.
Most people are not experts, could not properly configure these features
(except inasmuch as the default configuration of
common-lisp-controller and/or cl-launch
might have been doing the right thing for some users),
and yet will experience software that "just works",
as configured by the system distributor, or by default.
Nevertheless, if you want to use the old ASDF-Binary-Locations
(the one available as an extension to load of top of ASDF,
not the one built into a few old versions of ASDF),
it may still work if you just make sure you do not configure the new
builtin ASDF-Output-Translations.
But if you configure both ASDF's new builtin and ASDF-Binary-Locations
(or an old common-lisp-controller or cl-launch),
you may experience "interesting" issues, so don't do it.
Configuration DSL
=================
Here is the grammar of the SEXP DSL for asdf-output-translations configuration:
;; A configuration is single SEXP starting with keyword :source-registry
;; followed by a list of directives.
CONFIGURATION := (:output-translations DIRECTIVE ...)
;; A directive is one of the following:
DIRECTIVE :=
;; include a configuration file or directory
(:include PATHNAME-DESIGNATOR) |
;; Your configuration expression MUST contain
;; exactly one of either of these:
:inherit-configuration | ; splices contents of inherited configuration
:ignore-inherited-configuration | ; drop contents of inherited configuration
;; enable global cache in ~/.common-lisp/cache/sbcl-1.0.35-x86-64/ or something.
:enable-user-cache |
;; Disable global cache. Map / to /
:disable-cache |
;; add a single directory to be scanned (no recursion)
(DIRECTORY-DESIGNATOR DIRECTORY-DESIGNATOR)
DIRECTORY-DESIGNATOR :=
ABSOLUTE-COMPONENT-DESIGNATOR |
(ABSOLUTE-COMPONENT-DESIGNATOR RELATIVE-COMPONENT-DESIGNATOR ...)
ABSOLUTE-COMPONENT-DESIGNATOR :=
STRING | ;; namestring (directory is assumed, better be absolute or bust, ``/**/*.*`` added)
PATHNAME | ;; pathname (better be an absolute directory or bust)
:HOME | ;; designates the user-homedir-pathname ~/
:USER-CACHE | ;; designates the default location for the user cache
:SYSTEM-CACHE | ;; designates the default location for the system cache
:ROOT | ;; the root of the filesystem hierarchy
:CURRENT-DIRECTORY ;; the current directory
RELATIVE-COMPONENT-DESIGNATOR :=
STRING | ;; namestring, directory is assumed. If the last component, ``/**/*.*`` is added
PATHNAME | ;; pathname unless last component, directory is assumed.
:IMPLEMENTATION | ;; a directory based on implementation, e.g. sbcl-1.0.32.30-linux-x86-64
:IMPLEMENTATION-TYPE | ;; a directory based on lisp-implementation-type only, e.g. sbcl
:CURRENT-DIRECTORY | ;; all components of the current directory, without the :absolute
:UID | ;; current UID -- not available on Windows
:USER ;; current USER name -- NOT IMPLEMENTED(!)
Relative components better be either relative
or subdirectories of the path before them, or bust.
The last component, if not a pathname, is notionally completed by ``/**/*.*``.
You can specify more fine-grained patterns by using a pathname object,
e.g. ``#p"some/path/**/foo*/bar-*.fasl"``
You may use ``#+features`` to customize the configuration file.
The second designator of a mapping may be ``NIL``, indicating that files are not mapped
to anything but themselves (same as if the second designator was the same as the first).
``:include`` statements cause the search to recurse with the path specifications
from the file specified.
An ``:inherit-configuration`` statement cause the search to recurse with the path
specifications from the next configuration
(see section Configurations_ above).
:enable-user-cache is the same as ``(:root :user-cache)``.
:disable-cache is the same as ``(:root :root)``.
:user-cache uses the contents of variable ``asdf::*user-cache*``
which by default is the same as using
``(:home ".cache" "common-lisp" :implementation)``.
:system-cache uses the contents of variable ``asdf::*system-cache*``
which by default is the same as using
``(:root "var" "cache" "common-lisp" :uid :implementation-type)``
Configuration Directories
=========================
Configuration directories consist in files each contains
a list of directives without any enclosing ``(:asdf-output-translations ...)`` form.
The files will be sorted by namestring as if by ``#'string<`` and
the lists of directives of these files with be concatenated in order.
An implicit ``:inherit-configuration`` will be included
at the end of the list.
This allows for packaging software that has file granularity
(e.g. Debian's ``dpkg`` or some future version of ``clbuild``)
to easily include configuration information about distributed software.
Directories may be included by specifying a directory pathname
or namestring in an ``:include`` directive, e.g.::
(:include "/foo/bar/")
Shell-friendly syntax for configuration
=======================================
When considering environment variable ``ASDF_OUTPUT_TRANSLATIONS``
ASDF will skip to next configuration if it's an empty string.
It will ``READ`` the string as a SEXP in the DSL
if it begins with a paren ``(``
and it will be interpreted as a colon-separated list of directories.
Directories should come in pairs, each pair indicating a :map directive.
The magic empty entry indicates the splicing of inherited configuration
rather than one of entry in a mapping pair.
Semantics of Output Translations
================================
From the specified configuration, a list of mappings is extracted
in a straightforward way:
mappings are collected in order, recursing through
included or inherited configuration as specified.
To this list is prepended some implementation-specific mappings,
and is appended a global default.
The list is then compiled to a mapping table as follows:
for each entry, in order, resolve the first designated directory
into an actual directory pathname for source locations.
If no mapping was specified yet for that location,
resolve the second designated directory to an output location directory
add a mapping to the table mapping the source location to the output location,
and add another mapping from the output location to itself
(unless a mapping already exists for the output location).
Based on the table, a mapping function is defined,
mapping source pathnames to output pathnames:
given a source pathname, locate the longest matching prefix
in the source column of the mapping table.
Replace that prefix by the corresponding output column
in the same row of the table, and return the result.
If no match is found, return the source pathname.
(A global default mapping the filesystem root to itself
may ensure that there will always be a match,
with same fall-through semantics).
Caching Results
===============
The implementation is allowed to either eagerly compute the information
from the configurations and file system, or to lazily re-compute it
every time, or to cache any part of it as it goes.
To explicitly flush any information cached by the system, use the API below.
Output location API
===================
The specified functions are exported from package ASDF.
(initialize-output-translations parameter)
will read the configuration and initialize all internal variables.
You can provide a parameter which is NIL, a configuration SEXP,
a configuration string, a pathname to load, or a symbol fbound
to a function that returns one of the previous.
(clear-output-translations)
undoes any output location configuration
and clears any cache for the mapping algorithm.
You might want to call that before you
dump an image that would be resumed with a different configuration,
and return an empty configuration.
Note that this does not include clearing information about
systems defined in the current image, only about
where to look for systems not yet defined.
(ensure-output-translations parameter)
checks whether output translations have been initialized.
If not, initialize them with given parameter.
This function will be called before any attempt to operate on a system
(with a parameter NIL).
(apply-output-translations PATHNAME)
Applies the configured output location translations to PATHNAME
(calls ensure-output-translations for the translations).
Credits
=======
Thanks a lot to Bjorn Lindberg and Gary King for ASDF-Binary-Locations,
and to Peter van Eynde for Common Lisp Controller.
All bad design ideas and implementation bugs are to mine, not theirs.
But so are good design ideas and elegant implementation tricks.
-- Francois-Rene Rideau <fare@tunes.org>
..
;;; Local Variables:
;;; mode: rst
;;; End:
......@@ -381,6 +381,7 @@ control what directories are added to the ASDF search path.
@section Configuring where ASDF stores object files
@findex clear-output-locations
ASDF lets you configure where object files will be stored.
Sensible defaults are provided and
......@@ -393,10 +394,10 @@ and without write privileges on shared source directories, etc.
This also allows to keep source directories uncluttered
by plenty of object files.
Starting with ASDF 1.6, the @code{asdf-output-translations} facility
Starting with ASDF 1.600, the @code{asdf-output-translations} facility
was added to ASDF itself, that controls where object files will be stored.
This facility is fully described in the document
@file{README.asdf-output-translations}.
This facility is fully described in a chapter of this manual,
@ref{Controlling where ASDF saves compiled files}.
The simplest way to add a translation to your search path,
say from @file{/foo/bar/baz/quux/}
......@@ -448,7 +449,7 @@ if the configuration may change
between the machine where you save it at the time you save it
and the machine you resume it at the time you resume it.
Finally note that before ASDF 1.6,
Finally note that before ASDF 1.600,
other ASDF add-ons offered the same functionality,
each in subtly different and incompatible ways:
ASDF-Binary-Locations, cl-launch, common-lisp-controller.
......@@ -1466,6 +1467,7 @@ The new component type is used in a @code{defsystem} form in this way:
@comment node-name, next, previous, up
@chapter Controlling where ASDF saves compiled files
@cindex asdf-output-translations
@vindex ASDF_OUTPUT_TRANSLATIONS
Each Common Lisp implementation has its own format
for compiled files (fasls for short).
......@@ -1481,32 +1483,320 @@ implementation to the next.
As of version 1.600, ASDF includes @code{asdf-output-translations}
to mitigate the problem.
@section Default locations
@findex output-files-for-system-and-operation
@section Configurations
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:
Configurations specify mappings from source locations to binary locations.
@itemize
@item
SBCL, version 1.0 on Mac OS X for intel: @code{sbcl-1.0-darwin-x86}
@enumerate
@item
Franz Allegro, version 8.0, ANSI Common Lisp: @code{allegro-8.0a-macosx-x86}
@item
An application may explicitly initialize the output-translations
configuration using the Configuration API
(@pxref{Controlling where ASDF saves compiled files,,Configuration API})
in which case this takes precedence.
It may itself compute this configuration from the command-line,
from a script, from its own configuration file, etc.
@item
The source registry will be configured from
the environment variable @code{ASDF_OUTPUT_TRANSLATIONS} if it exists.
@item
The source registry will be configured from
user configuration file
@file{~/.config/common-lisp/asdf-output-translations.conf}
if it exists.
@item
The source registry will be configured from
user configuration directory
@file{~/.config/common-lisp/asdf-output-translations.conf.d/}
if it exists.
@item
The source registry will be configured from
system configuration file
@file{/etc/common-lisp/asdf-output-translations.conf}
if it exists.
@item
The source registry will be configured from
system configuration directory
@file{/etc/common-lisp/asdf-output-translations.conf.d/}
if it exists.
@end enumerate
@item
Franz Allegro, version 8.1, Modern (case sensitive) Common Lisp: @code{allegro-8.1m-macosx-x86}
Each of these configurations is specified as a SEXP
in a trival domain-specific language (defined below).
Additionally, a more shell-friendly syntax is available
for the environment variable (defined yet below).
Each of these configurations is only used if the previous
configuration explicitly or implicitly specifies that it
includes its inherited configuration.
Additionally, some implementation-specific directories
may be automatically added to whatever mappings are specified
in configuration files, no matter if the last one inherits or not.
@section Backward Compatibility
@comment{FIXME -- I think we should provide an easy way to get behavior equivalent to A-B-L and I will propose a technique for doing this.}
We purposefully do NOT provide backward compatibility with earlier versions of
asdf-binary-locations (8 Sept 2009),
common-lisp-controller (7.00) or
cl-launch (2.35),
each of which had similar general capabilities.
Future versions of same packages (if any)
will hopefully use the new ASDF API as defined below.
These previous programs' API was not designed
for easy configuration by the end-user
in an easy way with configuration files,
and their previous API didn't fit the new paradigm.
But this incompatibility won't inconvenience many people.
Indeed, few people use and customize these packages;
these people are experts who can trivially adapt to the new configuration.
Most people are not experts, could not properly configure these features
(except inasmuch as the default configuration of
common-lisp-controller and/or cl-launch
might have been doing the right thing for some users),
and yet will experience software that "just works",
as configured by the system distributor, or by default.
Nevertheless, if you want to use the old ASDF-Binary-Locations
(the one available as an extension to load of top of ASDF,
not the one built into a few old versions of ASDF),
it may still work if you just make sure you do not configure the new
builtin ASDF-Output-Translations.
But if you configure both ASDF's new builtin and ASDF-Binary-Locations
(or an old common-lisp-controller or cl-launch),
you may experience "interesting" issues, so don't do it.
@section Configuration DSL
Here is the grammar of the SEXP DSL for asdf-output-translations configuration:
@verbatim
;; A configuration is single SEXP starting with keyword :source-registry
;; followed by a list of directives.
CONFIGURATION := (:output-translations DIRECTIVE ...)
;; A directive is one of the following:
DIRECTIVE :=
;; include a configuration file or directory
(:include PATHNAME-DESIGNATOR) |
;; Your configuration expression MUST contain
;; exactly one of either of these:
:inherit-configuration | ; splices contents of inherited configuration
:ignore-inherited-configuration | ; drop contents of inherited configuration
;; enable global cache in ~/.common-lisp/cache/sbcl-1.0.35-x86-64/ or something.
:enable-user-cache |
;; Disable global cache. Map / to /
:disable-cache |
;; add a single directory to be scanned (no recursion)
(DIRECTORY-DESIGNATOR DIRECTORY-DESIGNATOR)
DIRECTORY-DESIGNATOR :=
ABSOLUTE-COMPONENT-DESIGNATOR |
(ABSOLUTE-COMPONENT-DESIGNATOR RELATIVE-COMPONENT-DESIGNATOR ...)
ABSOLUTE-COMPONENT-DESIGNATOR :=
STRING | ;; namestring (directory is assumed, better be absolute or bust, ``/**/*.*'' added)
PATHNAME | ;; pathname (better be an absolute directory or bust)
:HOME | ;; designates the user-homedir-pathname ~/
:USER-CACHE | ;; designates the default location for the user cache
:SYSTEM-CACHE | ;; designates the default location for the system cache
:ROOT | ;; the root of the filesystem hierarchy
:CURRENT-DIRECTORY ;; the current directory
RELATIVE-COMPONENT-DESIGNATOR :=
STRING | ;; namestring, directory is assumed. If the last component, /**/*.* is added
PATHNAME | ;; pathname unless last component, directory is assumed.
:IMPLEMENTATION | ;; a directory based on implementation, e.g. sbcl-1.0.32.30-linux-x86-64
:IMPLEMENTATION-TYPE | ;; a directory based on lisp-implementation-type only, e.g. sbcl
:CURRENT-DIRECTORY | ;; all components of the current directory, without the :absolute
:UID | ;; current UID -- not available on Windows
:USER ;; current USER name -- NOT IMPLEMENTED(!)
@end verbatim
Relative components better be either relative
or subdirectories of the path before them, or bust.
The last component, if not a pathname, is notionally completed by @file{/**/*.*}.
You can specify more fine-grained patterns by using a pathname object,
e.g. @code{#p"some/path/**/foo*/bar-*.fasl"}
You may use @code{#+features} to customize the configuration file.
The second designator of a mapping may be @code{NIL}, indicating that files are not mapped
to anything but themselves (same as if the second designator was the same as the first).
@code{:include} statements cause the search to recurse with the path specifications
from the file specified.
An @code{:inherit-configuration} statement cause the search to recurse with the path
specifications from the next configuration
(see section Configurations_ above).
@itemize
@item :enable-user-cache is the same as @code{(:root :user-cache)}.
@item :disable-cache is the same as @code{(:root :root)}.
@item :user-cache uses the contents of variable @code{asdf::*user-cache*}
which by default is the same as using
@code{(:home ".cache" "common-lisp" :implementation)}.
@item :system-cache uses the contents of variable @code{asdf::*system-cache*}
which by default is the same as using
@code{(:root "var" "cache" "common-lisp" :uid :implementation-type)}
@end itemize
By default, all output file pathnames will be relocated
to some thus-named subdirectory of @file{~/.cache/common-lisp/}.
See the document @file{README.asdf-output-translations}
for a full specification on how to configure @code{asdf-output-translations}.
@section Configuration Directories
Configuration directories consist in files each contains
a list of directives without any enclosing @code{(:asdf-output-translations ...)} form.
The files will be sorted by namestring as if by @code{#'string<} and
the lists of directives of these files with be concatenated in order.
An implicit @code{:inherit-configuration} will be included
at the end of the list.
This allows for packaging software that has file granularity
(e.g. Debian's @command{dpkg} or some future version of @command{clbuild})
to easily include configuration information about distributed software.
Directories may be included by specifying a directory pathname
or namestring in an @code{:include} directive, e.g.:
@verbatim
(:include "/foo/bar/")
@end verbatim
@section Shell-friendly syntax for configuration
When considering environment variable @code{ASDF_OUTPUT_TRANSLATIONS}
ASDF will skip to next configuration if it's an empty string.
It will @code{READ} the string as an SEXP in the DSL
if it begins with a paren @code{(}
and it will be interpreted as a colon-separated list of directories.
Directories should come in pairs, each pair indicating a :map directive.
The magic empty entry indicates the splicing of inherited configuration
rather than one of entry in a mapping pair.
@section Semantics of Output Translations
From the specified configuration, a list of mappings is extracted
in a straightforward way:
mappings are collected in order, recursing through
included or inherited configuration as specified.
To this list is prepended some implementation-specific mappings,
and is appended a global default.
The list is then compiled to a mapping table as follows:
for each entry, in order, resolve the first designated directory
into an actual directory pathname for source locations.
If no mapping was specified yet for that location,
resolve the second designated directory to an output location directory
add a mapping to the table mapping the source location to the output location,
and add another mapping from the output location to itself
(unless a mapping already exists for the output location).
Based on the table, a mapping function is defined,
mapping source pathnames to output pathnames:
given a source pathname, locate the longest matching prefix
in the source column of the mapping table.
Replace that prefix by the corresponding output column
in the same row of the table, and return the result.
If no match is found, return the source pathname.
(A global default mapping the filesystem root to itself
may ensure that there will always be a match,
with same fall-through semantics).
@section Caching Results
The implementation is allowed to either eagerly compute the information
from the configurations and file system, or to lazily re-compute it
every time, or to cache any part of it as it goes.
To explicitly flush any information cached by the system, use the API below.
@section Output location API
The specified functions are exported from package ASDF.
@defun initialize-output-translations
will read the configuration and initialize all internal variables.
@end defun
@defun clear-output-translations
undoes any output location configuration
and clears any cache for the mapping algorithm.
You might want to call that before you
dump an image that would be resumed with a different configuration,
and return an empty configuration.
Note that this does not include clearing information about
systems defined in the current image, only about
where to look for systems not yet defined.
@end defun
@defun ensure-output-translations
checks whether output translations have been initialized.
If not, initialize them.
This function will be called before any attempt to operate on a system.
If your application wants to override the provided defaults,
it will have to use the below function process-output-translations.
@end defun
@defun apply-output-translations PATHNAME
Applies the configured output location translations to @var{PATHNAME}
(calls ensure-output-translations for the translations).
@end defun
@section Credits
Thanks a lot to Bjorn Lindberg and Gary King for ASDF-Binary-Locations,
and to Peter van Eynde for Common Lisp Controller.
All bad design ideas and implementation bugs are to mine, not theirs.
But so are good design ideas and elegant implementation tricks.
-- Francois-Rene Rideau @email{fare@@tunes.org}
@c @section Default locations
@c @findex output-files-for-system-and-operation
@c The default binary location for each Lisp implementation
@c is a subdirectory of each source directory.
@c To account for different Lisps, Operating Systems, Implementation versions,
@c and so on, ASDF borrows code from SLIME
@c to create reasonable custom directory names.
@c Here are some examples:
@c @itemize
@c @item
@c SBCL, version 1.0 on Mac OS X for intel: @code{sbcl-1.0-darwin-x86}
@c @item
@c Franz Allegro, version 8.0, ANSI Common Lisp: @code{allegro-8.0a-macosx-x86}
@c @item
@c Franz Allegro, version 8.1, Modern (case sensitive) Common Lisp: @code{allegro-8.1m-macosx-x86}
@c @end itemize
@c By default, all output file pathnames will be relocated
@c to some thus-named subdirectory of @file{~/.cache/common-lisp/}.
@c See the document @file{README.asdf-output-translations}
@c for a full specification on how to configure @code{asdf-output-translations}.
@node Error handling, Miscellaneous additional functionality, Controlling where ASDF saves compiled files, Top
@comment node-name, next, previous, up
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment