diff --git a/README.asdf-output-translations b/README.asdf-output-translations deleted file mode 100644 index 72fb602b3000cd7324a42be31e4b4cbba07dffcb..0000000000000000000000000000000000000000 --- a/README.asdf-output-translations +++ /dev/null @@ -1,290 +0,0 @@ -======================== -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: diff --git a/asdf.texinfo b/asdf.texinfo index 250b9e2bd659d94ac7bda72dc0c8effd5049a50a..0bfa5ce72f61366fa7ded661117526f53b0e0795 100644 --- a/asdf.texinfo +++ b/asdf.texinfo @@ -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