diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo index fdfe6e637e9c1bb08b3ce8dc767e5e6d0b45706e..db392ca55c1d180b7d80290b1a654d7d7e59e705 100644 --- a/doc/asdf.texinfo +++ b/doc/asdf.texinfo @@ -1084,7 +1084,7 @@ If your file is loaded by ASDF 3, this is the context in which it will be read; this line will thus ensure that the system definition is read the same as within ASDF when you load it interactively with @code{cl:load}. -However, we recommend that you load @code{.asd} files +However, we recommend that you load @file{.asd} files through function @code{asdf::load-asd} rather than through @code{cl:load}, in which case you don't need this @code{in-package} form. Recent versions of SLIME (2013-02 and later) know to do just that. @@ -1097,13 +1097,13 @@ from both package @code{asdf} and @code{common-lisp} to be readily available in the current package, most importantly including @code{defsystem} itself. Indeed, starting with ASDF 3.1, -@code{.asd} files are read in the package @code{asdf-user} +@file{.asd} files are read in the package @code{asdf-user} that uses @code{asdf}, @code{uiop} and @code{uiop/common-lisp} (a variant of @code{common-lisp} that has some portability fixes on old implementations). ASDF 3 releases before 3.1 also read in package @code{asdf-user} but that package don't use the full @code{uiop}, only @code{uiop/package}. -ASDF 1 and ASDF 2 releases (up until 2.26) instead read @code{.asd} files +ASDF 1 and ASDF 2 releases (up until 2.26) instead read @file{.asd} files in a temporary package @code{asdf@emph{N}} that uses @code{asdf} and @code{common-lisp}. You may thus have to package-qualify some symbols with @code{uiop:} @@ -1692,7 +1692,7 @@ However, it is recommended to keep such forms to a minimal, and to instead define @code{defsystem} extensions that you use with @code{:defsystem-depends-on}. -If however, you might insist on including code in the @code{.asd} file itself, +If however, you might insist on including code in the @file{.asd} file itself, e.g., to examine and adjust the compile-time environment, possibly adding appropriate features to @code{*features*}. If so, here are some conventions we recommend you follow, @@ -2996,7 +2996,7 @@ ASDF 3 relies on the environment variables that Windows usually exports. @section Backward Compatibility For backward compatibility as well as to provide a practical backdoor for hackers, -ASDF will first search for @code{.asd} files in the directories specified in +ASDF will first search for @file{.asd} files in the directories specified in @code{asdf:*central-registry*} before it searches in the source registry above. @@ -3653,7 +3653,6 @@ or you might experience ``interesting'' issues. Also, note that output translation is enabled by default. To disable it, use @code{(asdf:disable-output-translations)}. - @node Output Configuration DSL, Output Configuration Directories, Output Backward Compatibility, Controlling where ASDF saves compiled files @section Configuration DSL @@ -3952,8 +3951,8 @@ which will cause the initialization to happen next time around. @node Credits for output translations, , Output location API, Controlling where ASDF saves compiled files @section Credits for output translations -Thanks a lot to Bjorn Lindberg and Gary King for @code{ASDF-Binary-Locations}, -and to Peter van Eynde for @code{Common Lisp Controller}. +Thanks a lot to Peter van Eynde for @code{Common Lisp Controller} +and to Bjorn Lindberg and Gary King for @code{ASDF-Binary-Locations}. All bad design ideas and implementation bugs are to mine, not theirs. But so are good design ideas and elegant implementation tricks. @@ -4184,7 +4183,7 @@ See for instance @code{lambda-reader}. We invite you to embrace UTF-8 as the encoding for non-ASCII characters starting today, -even without any explicit specification in your @code{.asd} files. +even without any explicit specification in your @file{.asd} files. Indeed, on some implementations and configurations, UTF-8 is already the @code{:default}, and loading your code may cause errors if it is encoded in anything but UTF-8. @@ -4201,7 +4200,7 @@ use the extension system @code{asdf-encodings}, by specifying This extension system will register support for more encodings using the @code{*encoding-external-format-hook*} facility, so you can explicitly specify @code{:encoding :latin1} -in your @code{.asd} file. +in your @file{.asd} file. Using the @code{*encoding-detection-hook*} it will also eventually implement some autodetection of a file's encoding from an emacs-style @code{-*- mode: lisp ; coding: latin1 -*-} declaration, @@ -4221,7 +4220,7 @@ You can also browse the repository on @url{http://common-lisp.net/gitweb?p=projects/asdf/asdf-encodings.git}. When you use @code{asdf-encodings}, -any @code{.asd} file loaded +any @file{.asd} file loaded will use the autodetection algorithm to determine its encoding. If you depend on this detection happening, you should explicitly load @code{asdf-encodings} early in your build. @@ -4230,7 +4229,7 @@ the @code{:defsystem-depends-on} is loaded, the enclosing @code{defsystem} form has already been read. In practice, this means that the @code{*default-encoding*} -is usually used for @code{.asd} files. +is usually used for @file{.asd} files. Currently, this defaults to @code{:utf-8}, and you should be safe using Unicode characters in those files. This might matter, for instance, in meta-data about author's names. @@ -5161,6 +5160,10 @@ use (after loading ASDF but before using it): (asdf:disable-output-translations) @end example +Note that this does @emph{NOT} belong in a @file{.asd} file. +Please do not tamper with ASDF configuration from a @file{.asd} file, +and only do this from your personal configuration or build scripts. + @node Issues with using and extending ASDF to define systems, ASDF development FAQs, Issues with configuring ASDF, FAQ @section Issues with using and extending ASDF to define systems @@ -5377,7 +5380,7 @@ you also define the following method: "lis") @end lisp -@node How do I mark a source file to be loaded only and not compiled?, , How do I create a system definition where all the source files have a .cl extension?, Issues with using and extending ASDF to define systems +@node How do I mark a source file to be loaded only and not compiled?, How do I work with readtables?, How do I create a system definition where all the source files have a .cl extension?, Issues with using and extending ASDF to define systems @subsection How do I mark a source file to be loaded only and not compiled? There is no provision in ASDF for ensuring that @@ -5401,16 +5404,68 @@ to allow for such a trick. @cindex readtables +It is possible to configure the lisp syntax by modifying the currently-active readtable. +However, this same readtable is shared globally by all software being compiled by ASDF, +especially since @code{load} and @code{compile-file} both bind @var{*readtable*}, +so that its value is the same across the build at the start of every file +(unless overridden by some @code{perform :around} method), +even if a file locally binds it to a different readtable during the build. + +Therefore, the following hygiene restrictions apply. If you don't abide by these restrictions, +there will be situations where your output files will be corrupted during an incremental build. +We are not trying to prescribe new restrictions for the sake of good style: +these restrictions have always applied implicitly, and +we are simply describing what they have always been. + +@itemize +@item It is forbidden to modifying any standard character or standard macro dispatch defined in the CLHS. +@item No two dependencies may assign different meanings to the same non-standard character. +@item Using any non-standard character while expecting the implementation to treat some way + counts as such an assignment of meaning. +@item libraries need to document these assignments of meaning to non-standard characters. +@item free software libraries will register these changes on: + @url{http://www.cliki.net/Macro%20Characters} +@end itemize + +If you want to use readtable modifications that cannot abide by those restrictions, +you @emph{must} create a different readtable object and set @var{*readtable*} +to temporarily bind it to your new readtable (which will be undone after processing the file). -It is possible to configure the lisp syntax by modifying the -currently-active readtable. Unfortunately, CL has very limited support -for controlling the readtable (e.g., there is no @code{IN-READTABLE} the -way there is @code{IN-PACKAGE}). +For that, we recommend you use system @code{named-readtables} +to define or combine such readtables using @code{named-readtables:defreadtable} +and use them using @code{named-readtables:in-readtable}. +Equivalently, you can use system @code{cl-syntax}, +that itself uses @code{named-readtables}, +but may someday do more with, e.g. @var{*print-pprint-dispatch*}. + +For even more advanced syntax modification beyond what a readtable can express, +you may consider either: +@itemize +@item a @code{perform} method that compiles a constant file that contains a single form + @code{#.*code-read-with-alternate-reader*} in an environment where this special variable + was bound to the code read by your alternate reader, or +@item using the system @code{reader-interception}. +@end itemize + +Beware that @c unless and until the @code{syntax-control} branch is merged, +it is unsafe to use ASDF from the REPL to compile or load systems +while the readtable isn't the shared readtable previously used to build software. +You @emph{must} manually undo any binding of @var{*readtable*} at the REPL +and restore its initial value whenever you call @code{operate} +(via e.g. @code{load-system}, @code{test-system} or @code{require}) +from a REPL that is using a different readtable. @subsubsection How should my system use a readtable exported by another system? +Use from the @code{named-readtables} system the macro @code{named-readtables:in-readtable}. + +If the other system fails to use @code{named-readtables}, fix it and send a patch upstream. +In the day and age of Quicklisp and clbuild, there is little reason +to eschew using such an important library anymore. + @subsubsection How should my library make a readtable available to other systems? +Use from the @code{named-readtables} system the macro @code{named-readtables:defreadtable}. @node ASDF development FAQs, , Issues with using and extending ASDF to define systems, FAQ @section ASDF development FAQs @@ -5428,10 +5483,35 @@ interested, too. Here's the procedure for experimenting with tests in a REPL: @example +;; BEWARE! Some tests expect you to be in the .../asdf/test directory +;; If your REPL is not there yet, change your current directory: +;; under SLIME, you may: ,change-directory ~/common-lisp/asdf/test/ +;; otherwise you may evaluate something like: +(require "asdf") (asdf:upgrade-asdf) ;load UIOP & update asdf.lisp +(uiop:chdir (asdf:system-relative-pathname :asdf "test/")) +(setf *default-pathname-defaults* (uiop:getcwd)) + +;; Load the test script support. (load "script-support.lisp") -(in-package :asdf-test) -(compile-load-asdf) ; there are a number of other functions to load ASDF -;; experiment with test code from a .script file... + +;; Initialize the script support. +;; This will also change your *package* to asdf-test. +;; NB: this function is also available from package cl-user, +;; and also available with the shorter name da in both packages. +(asdf-test::debug-asdf) + +;; In case you modified ASDF since you last tested it, +;; you need to update asdf.lisp itself by evaluating 'make' in a shell, +;; or (require "asdf") (asdf:load-system :asdf) in another CL REPL, +;; if not done in this REPL above. +;; *Then*, in this REPL, you need to evaluate: +;(asdf-test::compile-load-asdf) + +;; Now, you may experiment with test code from a .script file. +;; See the instructions given at the end of your failing test +;; to identify which form is needed, e.g. +(frob-packages) +(asdf::with-asdf-cache () (load "test-utilities.script")) @end example @@ -5443,7 +5523,7 @@ Here's the procedure for experimenting with tests in a REPL: For an active list of things to be done, see the @file{TODO} file in the source repository. -Also, bugs that are now tracked on launchpad: +Also, bugs are now tracked on launchpad: @url{https://launchpad.net/asdf}. @node Bibliography, Concept Index, Ongoing Work, Top @@ -5479,11 +5559,16 @@ Also, bugs that are now tracked on launchpad: many ideas of which have been incorporated into ASDF 2 and 3, though many other of which still haven't. @url{http://common-lisp.net/projects/xcvb/} -@item Peter von Etter: ``faslpath'', 2009. +@item Peter von Etter: + ``faslpath'', 2009. @code{faslpath} is similar to the latter @code{quick-build} and our letter @code{asdf/package-system} extension, except that it uses the dot @code{.} rather than the slash @code{/} as a separator. @url{https://code.google.com/p/faslpath/} +@item Drew McDermott: + ``A Framework for Maintaining the Coherence of a Running Lisp,'' + International Lisp Conference, 2005, available in pre-print form at + @url{http://www.cs.yale.edu/homes/dvm/papers/lisp05.pdf} @item Dan Barlow: ``ASDF Manual'', 2004. Older versions of this document from the days of ASDF 1; they include ideas laid down by Dan Barlow, @@ -5505,9 +5590,6 @@ Also, bugs that are now tracked on launchpad: ``Lisp Machine Manual'', MIT, 1981. The famous CHINE NUAL describes one of the earliest variants of DEFSYSTEM. @url{https://bitsavers.trailing-edge.com/pdf/mit/cadr/chinual_4thEd_Jul81.pdf} -@item Drew McDermott: ``A Framework for Maintaining the Coherence of a - Running Lisp,'' International Lisp Conference, 2005, available in - pre-print form at @url{http://www.cs.yale.edu/homes/dvm/papers/lisp05.pdf}. @end itemize