From a1e01f1dec2fc9c6323489cde1979da5ab998d6b Mon Sep 17 00:00:00 2001 From: Francois-Rene Rideau <tunes@google.com> Date: Tue, 27 Nov 2012 23:39:59 -0500 Subject: [PATCH] Quickly document force-not, require-system, *load-system-operation*. --- doc/asdf.texinfo | 67 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 47 insertions(+), 20 deletions(-) diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo index 83eb9aa4..35cc9df4 100644 --- a/doc/asdf.texinfo +++ b/doc/asdf.texinfo @@ -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 -- GitLab