Commit a1e01f1d authored by Francois-Rene Rideau's avatar Francois-Rene Rideau
Browse files

Quickly document force-not, require-system, *load-system-operation*.

parent c8ea6442
......@@ -644,7 +644,8 @@ by evaluating the following Lisp form:
@end example
On some implementations (namely recent versions of
ABCL, Allegro CL, Clozure CL, CMUCL, ECL, GNU CLISP, LispWorks, MKCL, SBCL and XCL),
ABCL, Allegro CL, Clozure CL, CMUCL, ECL, GNU CLISP,
LispWorks, MKCL, SBCL and XCL),
ASDF hooks into the @code{CL:REQUIRE} facility
and you can just use:
......@@ -695,6 +696,13 @@ Reminder: before ASDF can operate on a system, however,
it must be able to find and load that system's definition.
@xref{Configuring ASDF,,Configuring ASDF to find your systems}.
For the advanced users, note that
@code{require-system} calls @code{load-system}
with keyword arguments @code{:force-not (loaded-systems)}.
@code{loaded-systems} returns a list of the names of loaded systems.
@code{load-system} applies @code{operate} with the operation from
@code{*load-system-operation*}, which by default is @code{load-op},
the system, and any provided keyword arguments.
@section Summary
......@@ -1316,8 +1324,8 @@ and easier than having them all be @code{EQL} methods.
Operations are invoked on systems via @code{operate}.
@anchor{operate}
@deffn {Generic function} @code{operate} @var{operation} @var{system} @&rest @var{initargs}
@deffnx {Generic function} @code{oos} @var{operation} @var{system} @&rest @var{initargs}
@deffn {Generic function} @code{operate} @var{operation} @var{system} @&rest @var{initargs} @&key @code{force} @code{force-not} @code{verbose} @&allow-other-keys
@deffnx {Generic function} @code{oos} @var{operation} @var{system} @&rest @var{initargs} @&key @&allow-other-keys
@code{operate} invokes @var{operation} on @var{system}.
@code{oos} is a synonym for @code{operate}.
......@@ -1332,6 +1340,16 @@ to invoke other operations on the system or its components:
the new operations will be created
with the same @var{initargs} as the original one.
If @var{force} is @code{t}, then all systems
are forced to be recompiled even if not modified since last compilation.
If @var{force} is a list, then it specifies a list of systems that
are forced to be recompiled even if not modified since last compilation.
If @var{force-not} is @code{t}, then all systems
are forced not to be recompiled even if modified since last compilation.
If @var{force-not} is a list, then it specifies a list of systems that
are forced not to be recompiled even if modified since last compilation.
@var{force} takes precedences over @var{force-not};
both of them apply to systems that are dependencies and were already compiled.
@end deffn
@menu
......@@ -3256,9 +3274,9 @@ ASDF-dependent code you may check for this feature
to see if the new API is present.
@emph{All} versions of ASDF should have the @code{:asdf} feature.
Additionally, all versions of asdf 2
Additionally, all versions of ASDF 2
define a function @code{(asdf:asdf-version)} you may use to query the version;
and the source code of recent versions of asdf 2 features the version number
and the source code of recent versions of ASDF 2 features the version number
prominently on the second line of its source code.
If you are experiencing problems or limitations of any sort with ASDF 1,
......@@ -3477,7 +3495,8 @@ It is trivial to disable output translations.
@xref{FAQ,,``How can I wholly disable the compiler output cache?''}.
@item
Some systems in the large have been known not to play well with output translations.
Some systems in the large have been known
not to play well with output translations.
They were relatively easy to fix.
Once again, it is also easy to disable output translations,
or to override its configuration.
......@@ -3497,9 +3516,11 @@ Other issues include the following:
@itemize
@item
ASDF pathname designators are now specified in places where they were unspecified,
ASDF pathname designators are now specified
in places where they were unspecified,
and a few small adjustments have to be made to some non-portable defsystems.
Notably, in the @code{:pathname} argument to a @code{defsystem} and its components,
Notably, in the @code{:pathname} argument
to a @code{defsystem} and its components,
a logical pathname (or implementation-dependent hierarchical pathname)
must now be specified with @code{#p} syntax
where the namestring might have previously sufficed;
......@@ -3527,20 +3548,26 @@ when recursing through directories.
On Windows, only LispWorks supports proper default configuration pathnames
based on the Windows registry.
Other implementations make do with environment variables,
that you may have to define yourself if you're using an older version of Windows.
that you may have to define yourself
if you're using an older version of Windows.
Windows support is somewhat less tested than Unix support.
Please help report and fix bugs.
@emph{Update}: As of ASDF 2.21, all implementations
should now use the same proper default configuration pathnames
and they should actually work, though they haven't all been tested.
@item
The mechanism by which one customizes a system so that Lisp files
may use a different extension from the default @file{.lisp} has changed.
Previously, the pathname for a component was lazily computed when operating on a system,
Previously, the pathname for a component
was lazily computed when operating on a system,
and you would
@code{(defmethod source-file-type ((component cl-source-file) (system (eql (find-system 'foo))))
(declare (ignorable component system)) "lis")}.
Now, the pathname for a component is eagerly computed when defining the system,
and instead you will @code{(defclass cl-source-file.lis (cl-source-file) ((type :initform "lis")))}
and use @code{:default-component-class cl-source-file.lis} as argument to @code{defsystem},
and use @code{:default-component-class cl-source-file.lis}
as argument to @code{defsystem},
as detailed in a @pxref{FAQ,How do I create a system definition where all the source files have a .cl extension?} below.
@findex source-file-type
......@@ -3568,7 +3595,8 @@ Starting with current candidate releases of ASDF 2,
it should always be a good time to upgrade to a recent ASDF.
You may consult with the maintainer for which specific version they recommend,
but the latest @code{release} should be correct.
We trust you to thoroughly test it with your implementation before you release it.
We trust you to thoroughly test it with your implementation
before you release it.
If there are any issues with the current release,
it's a bug that you should report upstream and that we will fix ASAP.
......@@ -3586,6 +3614,7 @@ if you allow such configuration.
If your system provides a mechanism to hook into @code{CL:REQUIRE},
then it would be nice to add ASDF to this hook the same way that
ABCL, CCL, CLISP, CMUCL, ECL, SBCL and SCL do it.
Please send us appropriate code to this end.
@item
You may, like SBCL, have ASDF be implicitly used to require systems
......@@ -3949,13 +3978,9 @@ What would be a nice interface for this functionality?
** reuse the same scratch package whenever a system is reloaded from disk
** proclamations probably aren't
** when a system is reloaded with fewer components than it previously had, odd things happen
Have a package ASDF-USER instead of all these temporary packages?
We should do something inventive when processing a @code{defsystem} form,
like take the list of kids and @code{setf} the slot to @code{nil},
then transfer children from old to new list as they're found.
** proclamations probably aren't
** (stuff that might happen later)
......@@ -3965,9 +3990,11 @@ then transfer children from old to new list as they're found.
@code{(asdf:compile-system :araneida :force t)}
also forces compilation of every other system the @code{:araneida} system depends on.
also forces compilation of every other system
the @code{:araneida} system depends on.
This is rarely useful to me;
usually, when I want to force recompilation of something more than a single source file,
usually, when I want to force recompilation
of something more than a single source file,
I want to recompile only one system.
So it would be more useful to have @code{make-sub-operation}
refuse to propagate @code{:force t} to other systems, and
......
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