Commit f0817225 authored by Francois-Rene Rideau's avatar Francois-Rene Rideau

Some documentation tweaks

Update documentation about preloaded and immutable systems.

Update comments about the ASDF cache.

Explain that we need test cases more than bug fixes.
parent 438b24f0
;;;; -------------------------------------------------------------------------
;;;; Stamp cache
;;;; Session cache
(uiop/package:define-package :asdf/cache
(:use :uiop/common-lisp :uiop :asdf/upgrade)
......@@ -10,10 +10,13 @@
#:clear-configuration-and-retry #:retry))
(in-package :asdf/cache)
;;; This stamp cache is useful for:
;; * consistency of stamps used within a single run
;; * fewer accesses to the filesystem
;; * the ability to test with fake timestamps, without touching files
;;; The ASDF session cache is instrumental in achieving:
;; * Consistency in the view of the world relied on by ASDF within a given session.
;; Inconsistencies in file stamps, definitions, etc., could cause infinite loops
;; (a.k.a. stack overflows) and other erratic behavior.
;; * Speed and reliability of ASDF, with fewer side-effects from access to the filesystem,
;; no expensive recomputations of transitive dependencies for input-files or output-files.
;; * Testability of ASDF with the ability to fake timestamps without actually touching files.
(with-upgradability ()
(defvar *asdf-cache* nil)
......
......@@ -4708,12 +4708,16 @@ and get inspiration (or disinspiration)
from what it does in @file{header.lisp} and @file{upgrade.lisp}.
@end defun
@defun register-preloaded-system name @Arest{} keys
@defun register-preloaded-system name @Arest{} keys @Akeys{} version @AallowOtherKeys{}
A system with name @var{name},
created by @code{make-instance} with extra keys @var{keys}
(e.g. @code{:version}),
is registered as @emph{preloaded}.
That is, its code has already been loaded into the current image,
If @var{version} is @code{t} (default), then the version is copied from the defined system
of the same name (if registered) or else is @code{nil}
(this automatic copy of version is only available starting since ASDF 3.1.8).
A preloaded system is considered as having already been loaded into the current image,
and if at some point some other system @code{:depends-on} it yet no source code is found,
it is considered as already provided,
and ASDF will not raise a @code{missing-component} error.
......@@ -4722,24 +4726,34 @@ This function is particularly useful if you distribute your code
as fasls with either @code{compile-bundle-op} or @code{monolithic-compile-bundle-op},
and want to register systems so that dependencies will work uniformly
whether you're using your software from source or from fasl.
Note that if the system was already defined or loaded from source code,
its build information will remain active until you call @code{clear-system} on it,
at which point a system without build information will be registered in its place.
@end defun
@defun register-immutable-system name @Arest{} keys
A system with name @var{name},
created by @code{make-instance} with extra keys @var{keys}
(e.g. @code{:version}),
is registered as @emph{immutable}.
That is, its code has already been loaded into the current image,
and if at some point some other system @code{:depends-on} it,
it is considered as already provided, and
no attempt will be made to search for an updated version from the source-registry
or any other method.
There will be no search for an @file{.asd} file, and no @code{missing-component} error.
This function (available since ASDF 3.1.5) is particularly useful if
you distribute a large body of code as a precompiled image,
A system with name @var{name} is registered as preloaded,
and additionally is marked as @emph{immutable}:
that is, attempts to compile or load it will be succeed
without actually reading, creating or loading any file,
as if the system was passed as a @code{force-not} argument
to all calls to @code{plan} or @code{operate}.
There will be no search for an updated @file{.asd} file
to override the loaded version,
whether from the source-register or any other method.
If a @var{version} keyword argument is specified as @code{t} or left unspecified,
then the version is copied from the defined system
of the same name (if registered) or else is @code{nil}.
This automatic copy of version is available starting
since immutable systems have been available in ASDF 3.1.5.
This function, available since ASDF 3.1.5, is particularly useful
if you distribute a large body of code as a precompiled image,
and want to allow users to extend the image with further extension systems,
but without making thousands of filesystem requests looking for inexistent (or worse, out of date) source code
but without making thousands of filesystem requests looking for inexistent
(or worse, out of date) source code
for all the systems that came bundled with the image but aren't
distributed as source code to regular users.
@cindex immutable systems
......
......@@ -439,6 +439,23 @@ Corman Common Lisp <admin@cormanlisp.com>
If you're unsure about the bug or want to discuss how to fix it,
you can send email to the project mailing-list below.
</p>
<p>
Note that the most valuable thing you can send this way are test cases,
if possible as <tt>.script</tt> files readily runnable by our test system.
If you're courageous, send us merge requests on
<a href="https://gitlab.common-lisp.net/asdf/asdf/">gitlab</a>.
</p>
<p>
While bug fixes are useful, they are not usually as valuable as test cases:
small easy fixes will be obvious from the test case,
and large fixes written by someone who isn't a maintainer or working tightly with one
will probably not be correct and not fit the codebase:
any modification at one point is likely to have repercussions
at other unobvious places in the codebase,
for the code to be correct in a wider variety of scenarios
than casual developers usually think about.
Now, if you're willing to become a maintainer, you're welcome to join the team!
</p>
<a id="mailing-lists"></a>
<h3>Mailing Lists</h3>
......
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