Commit d5f314c9 authored by Robert P. Goldman's avatar Robert P. Goldman
Browse files

Merge branch 'docs' of ssh://common-lisp.net/project/asdf/public_html/asdf into docs

parents cb1043ac d4d1698b
......@@ -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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment