diff --git a/action.lisp b/action.lisp index 157f88a6c8bab9bcb9ac1eb5426f5509d3f21aad..842e6b891f42910bf3568d31073d1e5c02407bf7 100644 --- a/action.lisp +++ b/action.lisp @@ -115,7 +115,14 @@ You can put together sentences using this phrase.")) and each <component> is a component designator with respect to FIND-COMPONENT in the context of the COMPONENT argument, and means that the component depends on - <operation> having been performed on each <component>; or + <operation> having been performed on each <component>; + + [Note: an <operation> is an operation designator -- it can be either an + operation name or an operation object. Similarly, a <component> may be + a component name or a component object. Finally, the degenerate case of + (<operation>) is treated as a no-op.] + + or (FEATURE <feature>), which means that the component depends on the <feature> expression satisfying FEATUREP. @@ -188,10 +195,12 @@ each of its declared dependencies must first be loaded as by LOAD-OP.")) (:documentation "A SELFWARD-OPERATION depends on another operation on the same component. I.e., if O is a SELFWARD-OPERATION, and its SELFWARD-OPERATION designates a list of operations L, then the action (O . C) of O on component C depends on each (S . C) for S in L. +E.g. before a component may be loaded by LOAD-OP, it must have been compiled by COMPILE-OP. A operation-designator designates a singleton list of the designated operation; a list of operation-designators designates the list of designated operations; -NIL is not a valid operation designator in that context. -E.g. before a component may be loaded by LOAD-OP, it must have been compiled by COMPILE-OP.")) +NIL is not a valid operation designator in that context. Note that orderings between +the operations in a list of SELWARD-OPERATION should be indicated separately in order +that they be scheduled properly.")) (defmethod component-depends-on ((o selfward-operation) (c component)) `(,@(loop :for op :in (ensure-list (selfward-operation o)) :collect `(,op ,c)) diff --git a/bundle.lisp b/bundle.lisp index 9c3bfe3c033d4420d2b38d283b51242676bfdad7..d68d378c6cf2b59d4de8bf990886b939ecbe5f54 100644 --- a/bundle.lisp +++ b/bundle.lisp @@ -64,7 +64,12 @@ ((selfward-operation :initform '(fasl-op lib-op) :allocation :class)) (:documentation "produce fasl and asd files for the system")) - (defclass monolithic-op (operation) ()) ;; operation on a system and its dependencies + (defclass monolithic-op (operation) () + (:documentation "A MONOLITHIC operation operates on a system *and all of its +dependencies*. So, for example, a monolithic concatenate operation will +concatenate together a system's components and all of its dependencies, but a +simple concatenate operation will concatenate only the components of the system +itself.")) ;; operation on a system and its dependencies (defclass monolithic-bundle-op (monolithic-op bundle-op) ((prologue-code :accessor monolithic-op-prologue-code) @@ -72,7 +77,8 @@ (defclass monolithic-bundle-compile-op (monolithic-bundle-op bundle-compile-op) () - (:documentation "Abstract operation for ways to bundle the outputs of compiling *Lisp* files over all systems")) + (:documentation "Abstract operation for ways to bundle the outputs of compiling +*Lisp* files over a system, and all of its dependencies.")) (defclass monolithic-binary-op (monolithic-op binary-op) ((selfward-operation :initform '(monolithic-fasl-op monolithic-lib-op) :allocation :class)) diff --git a/component.lisp b/component.lisp index 83f13edecdca8ae62c119c2a18a8c1b1217816a8..f8a5f26a767901f38362b9a258155455074a3048 100644 --- a/component.lisp +++ b/component.lisp @@ -142,6 +142,9 @@ another pathname in a degenerate way.")) :initarg :build-operation :initform nil :reader component-build-operation))) (defun component-find-path (component) + "Return a path from a root system to the COMPONENT. +The return value is a list of component NAMES; a list of +strings." (check-type component (or null component)) (reverse (loop :for c = component :then (component-parent c) @@ -160,7 +163,9 @@ another pathname in a degenerate way.")) ;;;; Component hierarchy within a system ;; The tree typically but not necessarily follows the filesystem hierarchy. (with-upgradability () - (defclass child-component (component) ()) + (defclass child-component (component) () + (:documentation "A CHILD-COMPONENT is a component that may be part of +a PARENT-COMPONENT.")) (defclass file-component (child-component) ((type :accessor file-type :initarg :type))) ; no default @@ -189,7 +194,9 @@ another pathname in a degenerate way.")) (default-component-class :initform nil :initarg :default-component-class - :accessor module-default-component-class)))) + :accessor module-default-component-class))) + (:documentation "A PARENT-COMPONENT is a component that may have +children.")) (with-upgradability () (defun compute-children-by-name (parent &key only-if-needed-p) diff --git a/lisp-action.lisp b/lisp-action.lisp index 6adc154f4e2a24b2e3822021fbb0971f3ae91518..d4ce3626228960cfd4d2a3ae25ab2c8c4a21b74a 100644 --- a/lisp-action.lisp +++ b/lisp-action.lisp @@ -38,7 +38,9 @@ ;;; Our default operations: loading into the current lisp image (with-upgradability () (defclass prepare-op (upward-operation sideway-operation) - ((sideway-operation :initform 'load-op :allocation :class))) + ((sideway-operation :initform 'load-op :allocation :class)) + (:documentation "Load the necessary dependencies for the COMPONENT to which we apply +the PREPARE-OP.")) (defclass load-op (basic-load-op downward-operation sideway-operation selfward-operation) ;; NB: even though compile-op depends on prepare-op it is not needed-in-image-p, ;; so we need to directly depend on prepare-op for its side-effects in the current image. diff --git a/operate.lisp b/operate.lisp index c8c8f66cf13a489c98268294d7f6613de501ede7..a4b42762c01d4e52086fcb394eba800d9938f2c2 100644 --- a/operate.lisp +++ b/operate.lisp @@ -23,11 +23,11 @@ 1. It creates an instance of OPERATION-CLASS using any keyword parameters as initargs. 2. It finds the asdf-system specified by SYSTEM (possibly loading it from disk). -3. It then calls TRAVERSE with the operation and system as arguments +3. It then calls MAKE-PLAN with the operation and system as arguments -The traverse operation is wrapped in WITH-COMPILATION-UNIT and error handling code. -If a VERSION argument is supplied, then operate also ensures that the system found -satisfies it using the VERSION-SATISFIES method. +The operation of making a plan is wrapped in WITH-COMPILATION-UNIT and error +handling code. If a VERSION argument is supplied, then operate also ensures +that the system found satisfies it using the VERSION-SATISFIES method. Note that dependencies may cause the operation to invoke other operations on the system or its components: the new operations will be created with the same initargs as the original one. diff --git a/operation.lisp b/operation.lisp index 6949114fc6ab7a7a97595ba9359f93ccb7bae3b1..41fbacbc4795c7cc31e38daa422752eb30687e61 100644 --- a/operation.lisp +++ b/operation.lisp @@ -58,6 +58,11 @@ (declare (ignorable context)) nil) + ;; build op was intended to be the master, default operation on a system + ;; (LOAD-OP typically serves that function now). This feature has not yet + ;; been fully implemented yet. + ;; This is a path forward, but is not backwardly compatible, and is not used + ;; yet. [2014/01/26:rpg] (defclass build-op (operation) ())) diff --git a/plan.lisp b/plan.lisp index a7cfb1fd8423429d574c1dd0ad4a03cdebc68eb1..75d4a93164a3b5f65faebbdb2d64507edc330b2b 100644 --- a/plan.lisp +++ b/plan.lisp @@ -302,9 +302,16 @@ the action of OPERATION on COMPONENT in the PLAN")) (defmethod traverse-action (plan operation component needed-in-image-p) (block nil + ;; ACTION-VALID-P among other things, handles forcing logic, including + ;; FORCE-NOT. (unless (action-valid-p plan operation component) (return nil)) + ;; the following is needed by POIU, which tracks a dependency graph, + ;; instead of just a dependency order as in vanilla ASDF (plan-record-dependency plan operation component) + ;; needed in image distinguishes b/w things that must happen in the + ;; current image and those things that simply need to have been done. (let* ((aniip (needed-in-image-p operation component)) + ;; effectively needed in image (eniip (and aniip needed-in-image-p)) (status (plan-action-status plan operation component))) (when (and status (or (action-done-p status) (action-planned-p status) (not eniip))) @@ -402,6 +409,9 @@ the action of OPERATION on COMPONENT in the PLAN")) ;;;; Incidental traversals + +;;; Making a FILTERED-SEQUENTIAL-PLAN can be used to, e.g., all of the source +;;; files required by a bundling operation. (with-upgradability () (defclass filtered-sequential-plan (sequential-plan) ((action-filter :initform t :initarg :action-filter :reader plan-action-filter) diff --git a/upgrade.lisp b/upgrade.lisp index d6cfcf4b0a32d1ec2df58eef6413d7b36a2d18a4..fa0586de3ab1b3676c02cac45820ba1e4118f4cb 100644 --- a/upgrade.lisp +++ b/upgrade.lisp @@ -51,6 +51,8 @@ You can compare this string with e.g.: (ASDF:VERSION-SATISFIES (ASDF:ASDF-VERSIO (defun upgrading-p () (and *previous-asdf-versions* (not (equal *asdf-version* (first *previous-asdf-versions*))))) (defmacro when-upgrading ((&key (upgrading-p '(upgrading-p)) when) &body body) + "A wrapper macro for code that should only be run when upgrading a +previously-loaded version of ASDF." `(with-upgradability () (when (and ,upgrading-p ,@(when when `(,when))) (handler-bind ((style-warning #'muffle-warning))