diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo index f021724fb564dccb0d337c6d1cdba81bcffd61f4..90ffd2a56815f0d83b9e7393714b5ec39e662168 100644 --- a/doc/asdf.texinfo +++ b/doc/asdf.texinfo @@ -136,7 +136,7 @@ Configuring ASDF Using ASDF * Loading a system:: -* Other Operations:: +* Convenience Functions:: * Moving on:: Defining systems with defsystem @@ -935,11 +935,11 @@ on CMUCL and SCL, etc. @menu * Loading a system:: -* Other Operations:: +* Convenience Functions:: * Moving on:: @end menu -@node Loading a system, Other Operations, Using ASDF, Using ASDF +@node Loading a system, Convenience Functions, Using ASDF, Using ASDF @section Loading a system The system @var{foo} is loaded (and compiled, if necessary) @@ -958,17 +958,16 @@ and you can just use: (require :@var{foo}) @end example -In older versions of ASDF, you needed to use +In old versions of ASDF 1, you needed to use @code{(asdf:oos 'asdf:load-op :@var{foo})}. If your ASDF is too old to provide @code{asdf:load-system} though -we recommend that you upgrade to ASDF 3. +we recommend that you upgrade to the latest ASDF 3 release. @xref{Loading ASDF,,Loading ASDF from source}. -Note the name of a system is specified as a string or a symbol. -If a symbol (including a keyword), its name is taken and lowercased. +Note that the name of a system is specified as a string or a symbol. +If it is a symbol (including a keyword), its @code{symbol-name} is taken and lowercased. The name must be a suitable value for the @code{:name} initarg -to @code{make-pathname} in whatever filesystem the system is to be -found. +to @code{make-pathname} in whatever filesystem the system is to be found. The lower-casing-symbols behaviour is unconventional, but was selected after some consideration. @@ -978,12 +977,8 @@ or silently convert lowercase to uppercase (lpns). @c so this makes more sense than attempting to use @code{:case :common}, @c which is reported not to work on some implementations -@node Other Operations, Moving on, Loading a system, Using ASDF -@section Other Operations - -@c FIXME: this isn't a great name for this node -- these are not, in -@c fact, other OPERATIONS. OPERATIONS are objects. These are other -@c "convenience functions," or something like that. [2015/06/29:rpg] +@node Convenience Functions, Moving on, Loading a system, Using ASDF +@section Convenience Functions @findex load-system @findex compile-system @@ -1020,20 +1015,29 @@ should redirect all output from ASDF operations. @c FIXME: the following is too complicated for here, especially since @c :force hasn't been defined yet. Move it. [2014/02/27:rpg] -@findex already-loaded-systems -@findex require-system @findex load-system @vindex *load-system-operation* -For advanced users, note that -@code{require-system} calls @code{load-system} -with keyword arguments @code{:force-not (already-loaded-systems)}. -@code{already-loaded-systems} returns a list of the names of loaded systems. +@findex already-loaded-systems +@findex require-system @code{load-system} applies @code{operate} with the operation from -@code{*load-system-operation*} (which by default is @code{load-op}), +@code{*load-system-operation*} the system, and any provided keyword arguments. - - -@node Moving on, , Other Operations, Using ASDF +@code{*load-system-operation*} by default is @code{load-op}; +it would be @code{load-bundle-op} by default on ECL, if only an implementation bug were fixed. +For advanced users, note that +@code{already-loaded-systems} returns a list of the names of loaded systems. +@code{require-system} skips any update to systems that have already been loaded, +in the spirit of @code{cl:require}, +by calling @code{load-system} with @code{:force-not (already-loaded-systems)} +(note however that @code{cl:require} deals with implementation-provided modules +that are unlikely to have been compatibly updated since the current image was started, +whereas ASDF in general deals with user-provided systems at least one of which +is typically modified during a development session; +hence it doesn't usually make sense to check for updates to modules, +whereas it does usually make sense to check for updates to systems). + + +@node Moving on, , Convenience Functions, Using ASDF @section Moving on That's all you need to know to use ASDF to load systems written by others. @@ -1545,6 +1549,11 @@ where significant API incompatibilities are signaled by an increased major numbe Use the implementation's own @code{require} to load the @var{module-name}. +It is good taste to use @code{:if-feature @emph{:implementation-name}} +rather than @code{#+@emph{implementation-name}} +to only depend on the specified module on the specific implementation that provides it. +@xref{if-feature-option}. + @subsection Using logical pathnames @cindex logical pathnames @@ -1583,7 +1592,7 @@ ASDF currently provides no specific support for defining logical pathname translations. Note that the reasons we do not recommend logical pathnames are that -(1) there is no portable way to set up logical pathnames before they are used, +(1) there is no portable way to set up logical pathnames @emph{before} they are used, (2) logical pathnames are limited to only portably use a single character case, digits and hyphens. While you can solve the first issue on your own, diff --git a/operate.lisp b/operate.lisp index e69e249ca6f1f36abc1b3abccc1dc55570794ecf..5e0f19ccabd18f5c97a1d92dd1d0484ee351661e 100644 --- a/operate.lisp +++ b/operate.lisp @@ -161,19 +161,26 @@ to load it in current image." (apply 'operate 'test-op system args) t)) - -;;;; Define require-system, to be hooked into CL:REQUIRE when possible, -;; i.e. for ABCL, CLISP, ClozureCL, CMUCL, ECL, MKCL and SBCL +;;;;; Define the function REQUIRE-SYSTEM, that, similarly to REQUIRE, +;; only tries to load its specified target if it's not loaded yet. (with-upgradability () - (defun component-loaded-p (c) - (action-already-done-p nil (make-instance 'load-op) (find-component c ()))) + (defun component-loaded-p (component) + "has given COMPONENT been successfully loaded in the current image (yet)?" + (action-already-done-p nil (make-instance 'load-op) (find-component component ()))) (defun already-loaded-systems () + "return a list of the names of the systems that have been successfully loaded so far" (remove-if-not 'component-loaded-p (registered-systems))) - (defun require-system (s &rest keys &key &allow-other-keys) - (apply 'load-system s :force-not (already-loaded-systems) keys)) + (defun require-system (system &rest keys &key &allow-other-keys) + "Ensure the specified SYSTEM is loaded, passing the KEYS to OPERATE, but skip any update to the +system or its dependencies if they have already been loaded." + (apply 'load-system system :force-not (already-loaded-systems) keys))) + +;;;; Define the class REQUIRE-SYSTEM, to be hooked into CL:REQUIRE when possible, +;; i.e. for ABCL, CLISP, ClozureCL, CMUCL, ECL, MKCL and SBCL +(with-upgradability () (defvar *modules-being-required* nil) (defclass require-system (system)