Newer
Older
When creating a new component type,
you should provide methods for @code{compile-op}.
When @code{compile-op} is invoked,
component dependencies often cause some parts of the system
to be loaded as well as compiled.
Invoking @code{compile-op}
does not necessarily load all the parts of the system, though;
use @code{load-op} to load a system.
@deffn Operation @code{load-op} @code{&key} @code{proclamations}
This operation loads a system.
The default methods for @code{load-op} compile files before loading them.
For parity, your own methods on new component types should probably do so too.
@deffn Operation @code{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.
@deffn Operation @code{test-op}
This operation will perform some tests on the module.
The default method will do nothing.
The default dependency is to require
@code{load-op} to be performed on the module first.
The default @code{operation-done-p} is that the operation is @emph{never} done
---
we assume that if you invoke the @code{test-op},
you want to test the system, even if you have already done so.
The results of this operation are not defined by ASDF.
It has proven difficult to define how the test operation
should signal its results to the user
in a way that is compatible with all of the various test libraries
and test techniques in use in the community.
@c @deffn Operation test-system-version &key minimum
@c Asks the system whether it satisfies a version requirement.
@c The default method accepts a string, which is expected to contain of a
@c number of integers separated by #\. characters. The method is not
@c recursive. The component satisfies the version dependency if it has
@c the same major number as required and each of its sub-versions is
@c greater than or equal to the sub-version number required.
@c @lisp
@c (defun version-satisfies (x y)
@c (labels ((bigger (x y)
@c (cond ((not y) t)
@c ((not x) nil)
@c ((> (car x) (car y)) t)
@c ((= (car x) (car y))
@c (bigger (cdr x) (cdr y))))))
@c (or (not (cdr y)) (bigger (cdr x) (cdr y))))))
@c @end lisp
@c If that doesn't work for your system, you can override it. I hope
@c you have as much fun writing the new method as @verb{|#lisp|} did
@c reimplementing this one.
@c @end deffn
@c @deffn Operation feature-dependent-op
@c An instance of @code{feature-dependent-op} will ignore any components
@c which have a @code{features} attribute, unless the feature combination
@c it designates is satisfied by @code{*features*}. This operation is
@c not intended to be instantiated directly, but other operations may
@c inherit from it.
@c @end deffn
@node Creating new operations, , Predefined operations of ASDF, Operations
@comment node-name, next, previous, up
@subsection 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 @code{operation}.
ASDF's pre-defined operations are in no way ``privileged'',
but it is requested that developers never use the @code{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 @code{source-file}:
@emph{FIXME describe this better}
@itemize
@item @code{output-files}
@item @code{perform}
The @code{perform} method must call @code{output-files}
to find out where to put its files,
because the user is allowed to override.
@item @code{output-files}
for local policy @code{explain}
@item @code{operation-done-p},
if you don't like the default one
Operations that print output should send that output to the standard
CL stream @code{*standard-output*}, as the Lisp compiler and loader do.
@node Components, , Operations, The object model of ASDF
@comment node-name, next, previous, up
@section Components
@cindex component
@cindex system
@cindex system designator
@vindex *system-definition-search-functions*
A @dfn{component} represents a source file or
(recursively) a collection of components.
A @dfn{system} is (roughly speaking) a top-level component
that can be found via @code{find-system}.
A @dfn{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).
@defun find-system system-designator &optional (error-p t)
Given a system designator, @code{find-system} finds and returns a system.
If no system is found, an error of type
@code{missing-component} is thrown,
or @code{nil} is returned if @code{error-p} is false.
To find and update systems, @code{find-system} funcalls each element
in the @code{*system-definition-search-functions*} list,
expecting a pathname to be returned.
The resulting pathname is loaded if either of the following conditions is true:
@item
there is no system of that name in memory
@item
the file's @code{last-modified} time exceeds the @code{last-modified} time
of the system in memory
When system definitions are loaded from @file{.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 @code{defpackage} and @code{in-package} forms
in his system definition files, however,
so that they can be loaded manually if need be.
The default value of @code{*system-definition-search-functions*}
is a list of two functions.
The first function looks in each of the directories given
by evaluating members of @code{*central-registry*}
for a file whose name is the name of the system and whose type is @file{asd}.
The first such file is returned,
whether or not it turns out to actually define the appropriate system.
The second function does something similar,
for the directories specified in the @code{source-registry}.
Hence, it is strongly advised to define a system
@var{foo} in the corresponding file @var{foo.asd}.
@end defun
@menu
* Common attributes of components::
* Pre-defined subclasses of component::
* Creating new component types::
@end menu
@node Common attributes of components, Pre-defined subclasses of component, Components, Components
@comment node-name, next, previous, up
@subsection Common attributes of components
All components, regardless of type, have the following attributes.
All attributes except @code{name} are optional.
@subsubsection Name
A component name is a string or a symbol.
If a symbol, its name is taken and lowercased.
Unless overridden by a @code{:pathname} attribute,
the name will be interpreted as a pathname specifier according
to a Unix-style syntax. @xref{The defsystem grammar,,Pathname specifiers}.
@subsubsection Version identifier
This optional attribute is used by the test-system-version operation.
@xref{Predefined operations of ASDF}.
For the default method of @code{test-system-version},
the version should be a string of integers separated by dots,
for example @samp{1.0.11}.
@subsubsection Required features
@emph{FIXME: This subsection seems to contradict the
@code{defsystem} grammar subsection,
which doesn't provide any obvious way to specify required features.
Furthermore, in 2009, discussions on the asdf-devel mailing list
suggested that the specification of required features may be broken,
and that no one may have been using them for a while.
Please contact the asdf-devel mailing list if you are interested
in getting this features feature fixed.}
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 @code{#+} does, and it will (somehow) be ignored for
certain operations unless the feature conditional is a member of
@code{*features*}.
@subsubsection 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
@lisp
:in-order-to ((compile-op (load-op "a" "b") (compile-op "c"))
(load-op (load-op "foo")))
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
@end lisp
This means the following things:
@itemize
@item
before performing compile-op on this component, we must perform
load-op on @var{a} and @var{b}, and compile-op on @var{c},
@item
before performing @code{load-op}, we have to load @var{foo}
@end itemize
The syntax is approximately
@verbatim
(this-op {(other-op required-components)}+)
required-components := component-name
| (required-components required-components)
component-name := string
| (:version string minimum-version-object)
@end verbatim
Side note:
This is on a par with what ACL defsystem does.
mk-defsystem is less general: it has an implied dependency
@verbatim
for all x, (load x) depends on (compile x)
@end verbatim
and using a @code{:depends-on} argument to say that @var{b} depends on
@var{a} @emph{actually} means that
@verbatim
@end verbatim
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 @code{(component-depends-on operation component)},
which returns a list
@lisp
((load-op "a") (load-op "b") (compile-op "c") ...)
@end lisp
@code{component-depends-on} can be subclassed for more specific
component/operation types: these need to @code{(call-next-method)}
and append the answer to their dependency, unless
they have a good reason for completely overriding the default dependencies.
combination to do this transparently.
But, we need to support CLISP.
If you have the time for some CLISP hacking,
I'm sure they'd welcome your fixes.
@c Doesn't CLISP now support LIST method combination?
@subsubsection pathname
This attribute is optional and if absent (which is the usual case),
the component name will be used.
@xref{The defsystem grammar,,Pathname specifiers},
for an explanation of how this attribute is interpreted.
Note that the @code{defsystem} macro (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. @xref{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 @file{.cl} extension''
is thus
@lisp
(defmethod source-file-type ((c cl-source-file) (s (eql (find-system 'my-sys))))
@end lisp
@subsubsection 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.
@code{(component-property component property-name)} and
associated @code{setf} method will allow
the programmatic update of this information.
Property names are compared as if by @code{EQL},
so use symbols or keywords or something.
* Pre-defined subclasses of component::
* Creating new component types::
@end menu
@node Pre-defined subclasses of component, Creating new component types, Common attributes of components, Components
@comment node-name, next, previous, up
@subsection Pre-defined subclasses of component
@deffn 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 @file{.h} file from @file{.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.
@emph{FIXME: describe these.}
@end deffn
@deffn Component module
A module is a collection of sub-components.
A module component has the following extra initargs:
@itemize
@item
@code{:components} the components contained in this module
@item
@code{:default-component-class}
All children components which don't specify their class explicitly
are inferred to be of this type.
@code{:if-component-dep-fails}
This attribute takes one of the values
@code{:fail}, @code{:try-next}, @code{:ignore},
its default value is @code{:fail}.
The other values can be used for implementing conditional compilation
based on implementation @code{*features*},
for the case where it is not necessary for all files in a module to be
@emph{FIXME: such conditional compilation has been reported
to be broken in 2009.}
@code{: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 @code{: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.
@code{module} may be subclassed to represent components such as
foreign-language linked libraries or archive files.
@end deffn
@deffn Component system
@code{system} is a subclass of @code{module}.
A system is a module with a few extra attributes for documentation
purposes; these are given elsewhere.
@xref{The defsystem grammar}.
Users can create new classes for their systems:
the default @code{defsystem} macro takes a @code{:classs} keyword argument.
@end deffn
@node Creating new component types, , Pre-defined subclasses of component, Components
@comment node-name, next, previous, up
@subsection 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.
@emph{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
@code{cl-source-file}:
@lisp
(defclass unportable-cl-source-file (cl-source-file)
())
@end lisp
A hypothetical function @code{system-dependent-dirname}
gives us the name of the subdirectory.
All that's left is to define how to calculate the pathname
of an @code{unportable-cl-source-file}.
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
@lisp
(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)))
@end lisp
The new component type is used in a @code{defsystem} form in this way:
@lisp
(defsystem :foo
:components
((:file "packages")
...
(:unportable-cl-source-file "threads"
:depends-on ("packages" ...))
...
)
@end lisp
@node Controlling where ASDF searches for systems, Controlling where ASDF saves compiled files, The object model of ASDF, Top
@comment node-name, next, previous, up
@chapter Controlling where ASDF searches for systems
@section Configurations
Configurations specify paths where to find system files.
1- An application may explicitly initialize the source-registry
configuration using the configuration API
(@pxref{Controlling where ASDF searches for systems,Configuration API,Configuration API}, below)
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
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 @code{CL_SOURCE_REGISTRY} if it exists.
3- The source registry will be configured from
user configuration file
@code{~/.config/common-lisp/source-registry.conf}
if it exists.
4- The source registry will be configured from
user configuration directory
@code{~/.config/common-lisp/source-registry.conf.d/}
if it exists.
5- The source registry will be configured from
system configuration file
@code{/etc/common-lisp/source-registry.conf}
if it exists.
6- The source registry will be configured from
system configuration directory
@code{/etc/common-lisp/source-registry.conf.d/}
if it exists.
7- The source registry will be configured from a default configuration,
which allows for implementation-specific software to be searched
(@pxref{Controlling where ASDF searches for systems,,Backward Compatibility}).
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
Each of these configuration 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 prepended to whatever directories are specified
in configuration files, no matter if the last one inherits or not.
@section Backward Compatibility
For backward compatibility, ASDF will fall back to its old ways
of searching for @code{.asd} files in the directories specified in
@code{asdf:*central-registry*}
if it fails to find a configuration for the source registry, or
if it fails to find a requested system in the configured source registry.
This new mechanism will therefore not affect you if you don't use it,
but will take precedence over the old mechanism if you do use it.
Moreover, when using SBCL, now as before, ASDF will first look
for a matching system in the implementation-specific @code{contrib} directory.
This allows for some magic implementation-provided systems
to be loaded specially in a version that matches your implementation.
@section Configuration DSL
Here is the grammar of the SEXP DSL for source-registry configuration:
@example
;; A configuration is single SEXP starting with keyword :source-registry
;; followed by a list of directives.
CONFIGURATION := (:source-registry DIRECTIVE ...)
;; A directive is one of the following:
DIRECTIVE :=
;; add a single directory to be scanned (no recursion)
(:directory DIRECTORY-PATHNAME-DESIGNATOR) |
;; add a directory hierarchy, recursing but excluding specified patterns
(:tree DIRECTORY-PATHNAME-DESIGNATOR) |
;; override the default defaults for exclusion patterns
(:exclude PATTERN ...) |
;; splice the parsed contents of another config file
(:include REGULAR-FILE-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
;; This directive specifies that some default must be spliced.
:default-registry
PATTERN := a string without wildcards, that will be matched exactly
against the name of a any subdirectory in the directory component
of a path. e.g. @code{"_darcs"} will match @file{#p"/foo/bar/_darcs/src/bar.asd"}
@end example
@section Configuration Directories
Configuration directories consist in files each contains
a list of directives without any enclosing @code{(:source-registry ...)} 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 @code{dpkg} or some future version of @code{clbuild})
to easily include configuration information about distributed software.
The convention is that, for sorting purposes,
the names of files in such a directory begin with two digits
that determine the order in which these entries will be read.
Also, the type of these files is conventionally @code{"conf"}
and as a limitation of some implementations, the type cannot be @code{NIL}.
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
Directories may be included by specifying a directory pathname
or namestring in an @code{:include} directive, e.g.::
(:include "/foo/bar/")
@section Shell-friendly syntax for configuration
When considering environment variable @code{CL_SOURCE_REGISTRY}
ASDF will skip to next configuration if it's an empty string.
It will @code{READ} the string as a SEXP in the DSL
if it begins with a paren @code{(}
and it will be interpreted much like @code{TEXINPUTS}
as @code{:} (colon) separated list of paths, where
* each entry is a directory to add to the search path.
* if the entry ends with a double slash @code{//}
then it instead indicates a tree in the subdirectories
of which to recurse.
* if the entry is the empty string (which may only appear once),
then it indicates that the inherited configuration should be
spliced there.
@section Search Algorithm
In case that isn't clear, the semantics of the configuration is that
when searching for a system of a given name,
directives are processed in order.
When looking in a directory, if the system is found, the search succeeds,
otherwise it continues.
When looking in a tree, if one system is found, the search succeeds.
If multiple systems are found, the consequences are unspecified:
the search may succeed with any of the found systems,
or an error may be raised.
ASDF currently returns the first system found,
XCVB currently raised an error.
If none is found, the search continues.
Exclude statements specify patterns of subdirectories the systems of which
to ignore. Typically you don't want to use copies of files kept by such
version control systems as Darcs.
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
(@pxref{Controlling where ASDF searches for systems,,Configurations} above).
@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 Configuration API
The specified functions are exported from your build system's package.
Thus for ASDF the corresponding functions are in package ASDF,
and for XCVB the corresponding functions are in package XCVB.
@defun initialize-source-registry
will read the configuration and initialize all internal variables.
@end defun
@defun clear-source-registry
undoes any source registry configuration
and clears any cache for the search 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-source-registry
checks whether a source registry has been initialized.
If not, initialize it.
This function will be called before any attempt to find a system
in the source registry.
If your application wants to override the provided defaults,
it will have to use the below function process-source-registry.
@end defun
@defun process-source-registry X &key inherit collect
If X is a CONS, parse it as a SEXP in the configuration DSL,
and extend or override inheritted configuration.
If X is a STRING, first parse it into a SEXP
as for the CL_SOURCE_REGISTRY
environment variable (see above) then process it.
If X is a PATHNAME, read the file as a single SEXP and process it.
The inheritted configuration is provided in keyword argument inherit,
itself a list of functions that take inherit
and collect keyword arguments
and defaulting to a list of functions
that implements the default behavior.
@end defun
@section Future
If this mechanism is successful, in the future, we may declare
@code{asdf:*central-registry*} obsolete and eventually remove it.
Any hook into implementation-specific search mechanisms will by then
have been integrated in the @code{:default-configuration} which everyone
should either explicitly use or implicit inherit. Some shell syntax
for it should probably be added somehow.
But we're not there yet. For now, let's see how practical this new
source-registry is.
@section Rejected ideas
Alternatives I considered and rejected included:
@enumerate
@item Keep @code{asdf:*central-registry*} as the master with its current semantics,
and somehow the configuration parser expands the new configuration
language into a expanded series of directories of subdirectories to
lookup, pre-recursing through specified hierarchies. This is kludgy,
and leaves little space of future cleanups and extensions.
@item Keep @code{asdf:*central-registry*} remains the master but extend its semantics
in completely new ways, so that new kinds of entries may be implemented
as a recursive search, etc. This seems somewhat backwards.
@item Completely remove @code{asdf:*central-registry*}
and break backwards compatibility.
Hopefully this will happen in a few years after everyone migrate to
a better ASDF and/or to XCVB, but it would be very bad to do it now.
@item Replace @code{asdf:*central-registry*} by a symbol-macro with appropriate magic
when you dereference it or setf it. Only the new variable with new
semantics is handled by the new search procedure.
@end enumerate
I've been suggested the below features, but have rejected them,
for the sake of keeping ASDF no more complex than strictly necessary.
@itemize
@item
More syntactic sugar: synonyms for the configuration directives, such as
@code{(:add-directory X)} for @code{(:directory X)}, or @code{(:add-directory-hierarchy X)}
or @code{(:add-directory X :recurse t)} for @code{(:tree X)}.
@item
The possibility to register individual files instead of directories.
@item
Integrate Xach Beane's tilde expander into the parser,
or something similar that is shell-friendly or shell-compatible.
I'd rather keep ASDF minimal. But maybe this precisely keeps it
minimal by removing the need for evaluated entries that ASDF has?
i.e. uses of @code{USER-HOMEDIR-PATHNAME} and @code{$SBCL_HOME}
Hopefully, these are already superseded by the @code{:default-registry}
@item
Using the shell-unfriendly syntax @code{/**} instead of @code{//} to specify recursion
down a filesystem tree in the environment variable.
It isn't that Lisp friendly either.
@end itemize
@section TODO
@itemize
@item Integrate into the rest of the documentation.
@item Add examples
@item Add proper defaults.
@item Get inspired by the XDG base directory specification?
@uref{http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html}
@end itemize
@section Credits
Thanks a lot to Stelian Ionescu for the initial idea.
Thanks to Rommel Martinez for the initial implementation attempt.
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}, Mon, 22 Feb 2010 00:07:33 -0500
@node Controlling where ASDF saves compiled files, Error handling, Controlling where ASDF searches for systems, Top
Robert P. Goldman
committed
@comment node-name, next, previous, up
@chapter Controlling where ASDF saves compiled files
@cindex asdf-output-translations
@vindex ASDF_OUTPUT_TRANSLATIONS
Robert P. Goldman
committed
Each Common Lisp implementation has its own format
for compiled files (fasls for short, short for ``fast loading'').
If you use multiple implementations
(or multiple versions of the same implementation),
you'll soon find your source directories
littered with various @file{fasl}s, @file{dfsl}s, @file{cfsl}s and so on.
Robert P. Goldman
committed
Worse yet, some implementations use the same file extension
while changing formats from version to version (or platform to platform)
which means that you'll have to recompile binaries
as you switch from one implementation to the next.
Robert P. Goldman
committed
As of version 1.600, ASDF includes the @code{asdf-output-translations} facility
to mitigate the problem.
Robert P. Goldman
committed
@section Configurations
Robert P. Goldman
committed
Configurations specify mappings from source locations to binary locations.
Robert P. Goldman
committed
Robert P. Goldman
committed
An application may explicitly initialize the output-translations
configuration using the Configuration API
in which case this takes precedence.
(@pxref{Controlling where ASDF saves compiled files,,Configuration API}.)
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
Robert P. Goldman
committed
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 whether the last one inherits or not.
@section Backward Compatibility
@c FIXME -- I think we should provide an easy way
@c to get behavior equivalent to A-B-L and
@c I will propose a technique for doing this.
We purposefully do NOT provide backward compatibility with earlier versions of
@code{ASDF-Binary-Locations} (8 Sept 2009),
@code{common-lisp-controller} (7.0) or
@code{cl-launch} (2.35),
each of which had similar general capabilities.
The previous APIs of these programs were not designed
for configuration by the end-user
in an easy way with configuration files.
Recent versions of same packages use
the new @code{asdf-output-translations} API as defined below:
@code{common-lisp-controller} (7.1) and @code{cl-launch} (3.00);
@code{ASDF-Binary-Locations} is fully superseded and not to be used anymore.
This incompatibility shouldn't inconvenience many people.
Indeed, few people use and customize these packages;
these few 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
@code{common-lisp-controller} and/or @code{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 @code{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 disable the new
builtin @code{asdf-output-translations}.
But if you configure both ASDF's new builtin and @code{ASDF-Binary-Locations}
(or an old @code{common-lisp-controller} or @code{cl-launch}),
you may experience ``interesting'' issues, so don't do it.
@section Configuration DSL
Here is the grammar of the SEXP DSL
for @code{asdf-output-translations} configuration:
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
@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 as the last component
e.g. @file{#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. @c XXX xref needed.