From 7d12d0858bfa9cd9f93b81e2a9c6e31d204e528a Mon Sep 17 00:00:00 2001
From: Francois-Rene Rideau <tunes@google.com>
Date: Wed, 12 Mar 2014 15:22:08 -0400
Subject: [PATCH] Document the BUILD-OP operation as the new default, push
 (ASDF:BUILD :FOO) as the new recommended way to interact with ASDF 3.1.

---
 action.lisp    | 15 +--------------
 interface.lisp |  2 +-
 operate.lisp   | 28 +++++++++++++++++++++++-----
 3 files changed, 25 insertions(+), 20 deletions(-)

diff --git a/action.lisp b/action.lisp
index 59810e7..93da2ee 100644
--- a/action.lisp
+++ b/action.lisp
@@ -18,7 +18,6 @@
    #:traverse-actions #:traverse-sub-actions #:required-components ;; in plan
    #:action-path #:find-action #:stamp #:done-p
    #:operation-definition-warning #:operation-definition-error ;; condition
-   #:build-op ;; THE generic operation
    ))
 (in-package :asdf/action)
 
@@ -57,6 +56,7 @@
            (component 'component)
            (opix (position operation formals))
            (coix (position component formals))
+
            (prefix (subseq formals 0 opix))
            (suffix (subseq formals (1+ coix) len))
            (more-args (when keyp `(&rest ,rest &key &allow-other-keys))))
@@ -222,7 +222,6 @@ dependencies.")))
     (:documentation "Error condition related to definition of incorrect OPERATION objects."))
 
   (defmethod initialize-instance :before ((o operation) &key)
-    ;; build-op is a special case.
     (unless (typep o '(or downward-operation upward-operation sideway-operation
                           selfward-operation non-propagating-operation))
       (warn 'operation-definition-warning
@@ -399,15 +398,3 @@ in some previous image, or T if it needs to be done.")
                     (action-description operation component)))
           (mark-operation-done operation component)
           (return))))))
-
-;;; Generic build operation
-(with-upgradability ()
-  ;; BUILD-OP was intended to be the default "master" operation to invoke on a system in ASDF3
-  ;; (LOAD-OP typically serves that function now).
-  ;; This feature has not yet been fully implemented yet, and is not used by anyone yet.
-  ;; This is a path forward, and its default below is to backward compatibly depend on LOAD-OP.
-  ;; [2014/01/26:rpg]
-  (defclass build-op (non-propagating-operation) ())
-  (defmethod component-depends-on ((o build-op) (c component))
-    `((,(or (component-build-operation c) 'load-op) ,c))))
-
diff --git a/interface.lisp b/interface.lisp
index 70b9eeb..98078a6 100644
--- a/interface.lisp
+++ b/interface.lisp
@@ -27,7 +27,7 @@
    #:operation #:make-operation #:find-operation
    #:upward-operation #:downward-operation #:sideway-operation #:selfward-operation
                       #:non-propagating-operation
-   #:build-system #:build-op
+   #:build-op #:build #:build-system
    #:load-op #:prepare-op #:compile-op
    #:prepare-source-op #:load-source-op #:test-op
    #:feature #:version #:version-satisfies #:upgrade-asdf
diff --git a/operate.lisp b/operate.lisp
index 79ac3f8..1fc00a5 100644
--- a/operate.lisp
+++ b/operate.lisp
@@ -9,7 +9,7 @@
   (:export
    #:operate #:oos
    #:*systems-being-operated*
-   #:build-system
+   #:build-op #:build #:build-system
    #:load-system #:load-systems #:load-systems*
    #:compile-system #:test-system #:require-system
    #:*load-system-operation* #:module-provide-asdf
@@ -106,17 +106,35 @@ The :FORCE or :FORCE-NOT argument to OPERATE can be:
 (with-upgradability ()
   (defvar *load-system-operation* 'load-op
     "Operation used by ASDF:LOAD-SYSTEM. By default, ASDF:LOAD-OP.
-You may override it with e.g. ASDF:LOAD-FASL-OP from asdf-bundle,
+You may override it with e.g. ASDF:LOAD-FASL-OP from asdf-bundle (recommended on ECL?)
 or ASDF:LOAD-SOURCE-OP if your fasl loading is somehow broken.
 
-This may change in the future as we will implement component-based strategy
+This may change in the future if we implement component-directed strategy
 for how to load or compile stuff")
 
-  (defun build-system (system &rest keys)
-    "Shorthand for `(operate 'asdf:build-op system)`."
+  (defclass build-op (non-propagating-operation) ()
+    (:documentation "Since ASDF3, BUILD-OP is the recommended 'master' operation,
+to operate by default on a system or component.
+Its meaning is configurable via the :BUILD-OPERATION option of a component,
+which is typically the name of a specific operation to which to delegate the build,
+and may be NIL, which designates the *LOAD-SYSTEM-OPERATION*
+that will load the system in the current image, and its typically LOAD-OP."))
+  (defmethod component-depends-on ((o build-op) (c component))
+    `((,(or (component-build-operation c) *load-system-operation*) ,c)))
+
+
+  (defun build (system &rest keys)
+    "The recommended way to interact with ASDF3.1 is via (ASDF:BUILD :FOO).
+It will build system FOO using the operation BUILD-OP,
+the meaning of which is configurable by the system, and
+defaults to *LOAD-SYSTEM-OPERATION*, usually LOAD-OP, to load it in current image."
     (apply 'operate 'build-op system keys)
     t)
 
+  (defun build-system (system &rest keys)
+    "Alias for function BUILD"
+    (apply 'build system keys))
+
   (defun load-system (system &rest keys &key force force-not verbose version &allow-other-keys)
     "Shorthand for `(operate 'asdf:load-op system)`. See OPERATE for details."
     (declare (ignore force force-not verbose version))
-- 
1.9.0.279.gdc9e3eb

