will use the autodetection algorithm to determine its encoding.
will use the autodetection algorithm to determine its encoding.
If you depend on this detection happening,
If you depend on this detection happening,
you should explicitly load @code{asdf-encodings} early in your build.
you should explicitly load @code{asdf-encodings} early in your build.
...
@@ -4230,7 +4229,7 @@ the @code{:defsystem-depends-on} is loaded, the enclosing
...
@@ -4230,7 +4229,7 @@ the @code{:defsystem-depends-on} is loaded, the enclosing
@code{defsystem} form has already been read.
@code{defsystem} form has already been read.
In practice, this means that the @code{*default-encoding*}
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
Currently, this defaults to @code{:utf-8}, and
you should be safe using Unicode characters in those files.
you should be safe using Unicode characters in those files.
This might matter, for instance, in meta-data about author's names.
This might matter, for instance, in meta-data about author's names.
...
@@ -5161,6 +5160,10 @@ use (after loading ASDF but before using it):
...
@@ -5161,6 +5160,10 @@ use (after loading ASDF but before using it):
(asdf:disable-output-translations)
(asdf:disable-output-translations)
@end example
@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
@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
@section Issues with using and extending ASDF to define systems
...
@@ -5377,7 +5380,7 @@ you also define the following method:
...
@@ -5377,7 +5380,7 @@ you also define the following method:
"lis")
"lis")
@end lisp
@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?
@subsection How do I mark a source file to be loaded only and not compiled?
There is no provision in ASDF for ensuring that
There is no provision in ASDF for ensuring that
...
@@ -5401,16 +5404,68 @@ to allow for such a trick.
...
@@ -5401,16 +5404,68 @@ to allow for such a trick.
@cindex readtables
@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
For that, we recommend you use system @code{named-readtables}
currently-active readtable. Unfortunately, CL has very limited support
to define or combine such readtables using @code{named-readtables:defreadtable}
for controlling the readtable (e.g., there is no @code{IN-READTABLE} the
and use them using @code{named-readtables:in-readtable}.
way there is @code{IN-PACKAGE}).
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?
@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?
@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
@node ASDF development FAQs, , Issues with using and extending ASDF to define systems, FAQ
@section ASDF development FAQs
@section ASDF development FAQs
...
@@ -5428,10 +5483,35 @@ interested, too.
...
@@ -5428,10 +5483,35 @@ interested, too.
Here's the procedure for experimenting with tests in a REPL:
Here's the procedure for experimenting with tests in a REPL:
@example
@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/