Commit 0a810111 authored by Robert P. Goldman's avatar Robert P. Goldman

Notes (comments and docstrings) from ASDF code tour.

parent eac0ab1e
......@@ -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))
......
......@@ -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))
......
......@@ -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)
......
......@@ -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.
......
......@@ -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.
......
......@@ -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) ()))
......@@ -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)
......
......@@ -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))
......
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