1.0.29.50: update ASDF
[sbcl.git] / contrib / asdf / asdf.lisp
index 73999f7..ce424a5 100644 (file)
@@ -1,19 +1,20 @@
-;;; This is asdf: Another System Definition Facility.  1.115
+;;; This is asdf: Another System Definition Facility.
+;;; hash - $Format:%H$
 ;;;
 ;;; Feedback, bug reports, and patches are all welcome: please mail to
-;;; <cclan-list@lists.sf.net>.  But note first that the canonical
-;;; source for asdf is presently the cCLan CVS repository at
-;;; <URL:http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/cclan/asdf/>
+;;; <asdf-devel@common-lisp.net>.  But note first that the canonical
+;;; source for asdf is presently on common-lisp.net at
+;;; <URL:http://common-lisp.net/project/asdf/>
 ;;;
 ;;; If you obtained this copy from anywhere else, and you experience
 ;;; trouble using it, or find bugs, you may want to check at the
 ;;; location above for a more recent version (and for documentation
 ;;; and test files, if your copy came without them) before reporting
-;;; bugs.  There are usually two "supported" revisions - the CVS HEAD
+;;; bugs.  There are usually two "supported" revisions - the git HEAD
 ;;; is the latest development version, whereas the revision tagged
 ;;; RELEASE may be slightly older but is considered `stable'
 
-;;; Copyright (c) 2001-2007 Daniel Barlow and contributors
+;;; Copyright (c) 2001-2009 Daniel Barlow and contributors
 ;;;
 ;;; Permission is hereby granted, free of charge, to any person obtaining
 ;;; a copy of this software and associated documentation files (the
 (defpackage #:asdf
   (:export #:defsystem #:oos #:operate #:find-system #:run-shell-command
            #:system-definition-pathname #:find-component ; miscellaneous
-           #:hyperdocumentation #:hyperdoc
-
-           #:compile-op #:load-op #:load-source-op #:test-system-version
+           #:compile-system #:load-system #:test-system
+           #:compile-op #:load-op #:load-source-op
            #:test-op
-           #:operation                  ; operations
-           #:feature                    ; sort-of operation
-           #:version                    ; metaphorically sort-of an operation
+           #:operation           ; operations
+           #:feature             ; sort-of operation
+           #:version             ; metaphorically sort-of an operation
 
-           #:input-files #:output-files #:perform       ; operation methods
+           #:input-files #:output-files #:perform ; operation methods
            #:operation-done-p #:explain
 
            #:component #:source-file
@@ -85,7 +85,7 @@
            #:operation-on-warnings
            #:operation-on-failure
 
-           ;#:*component-parent-pathname*
+                                        ;#:*component-parent-pathname*
            #:*system-definition-search-functions*
            #:*central-registry*         ; variables
            #:*compile-file-warnings-behaviour*
            #:error-component #:error-operation
            #:system-definition-error
            #:missing-component
+           #:missing-component-of-version
            #:missing-dependency
+           #:missing-dependency-of-version
            #:circular-dependency        ; errors
            #:duplicate-names
 
+           #:try-recompiling
            #:retry
            #:accept                     ; restarts
 
-           #:preference-file-for-system/operation
-           #:load-preferences
+           #:standard-asdf-method-combination
+           #:around                     ; protocol assistants
            )
   (:use :cl))
 
 
 (in-package #:asdf)
 
-(defvar *asdf-revision* (let* ((v "1.115")
-                               (colon (or (position #\: v) -1))
-                               (dot (position #\. v)))
-                          (and v colon dot
-                               (list (parse-integer v :start (1+ colon)
-                                                      :junk-allowed t)
-                                     (parse-integer v :start (1+ dot)
-                                                      :junk-allowed t)))))
+(defvar *asdf-revision*
+  ;; find first tag that looks like /tags/[0-9]*\.[0-9]*. E.g., /tags/1.34
+  ;; return nil or a list of the major and minor version numbers
+  (let* ((v "$Format:%d$")
+         (to-find "tags/")
+         (start 0))
+    (when v
+      (loop for tag-start = (search to-find v :test #'char= :start2 start)
+         while tag-start do
+         (when tag-start
+           (let ((dot (position #\. v :start tag-start))
+                 (space (position #\space v :start tag-start)))
+             (when (and dot (or (not space) (< dot space)))
+               ;; success
+               (return
+                 (list (parse-integer v :start (+ tag-start (length to-find))
+                                      :junk-allowed t)
+                       (parse-integer v :start (1+ dot)
+                                      :junk-allowed t))))
+             (setf start (1+ tag-start))))))))
 
 (defvar *compile-file-warnings-behaviour* :warn)
 
@@ -148,6 +163,11 @@ and NIL NAME and TYPE components"
 (define-modify-macro appendf (&rest args)
   append "Append onto list")
 
+(defun asdf-message (format-string &rest format-args)
+  (declare (dynamic-extent format-args))
+  (apply #'format *verbose-out* format-string format-args))
+
+
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; classes, condiitons
 
@@ -174,12 +194,18 @@ and NIL NAME and TYPE components"
 
 (define-condition missing-component (system-definition-error)
   ((requires :initform "(unnamed)" :reader missing-requires :initarg :requires)
-   (version :initform nil :reader missing-version :initarg :version)
    (parent :initform nil :reader missing-parent :initarg :parent)))
 
+(define-condition missing-component-of-version (missing-component)
+  ((version :initform nil :reader missing-version :initarg :version)))
+
 (define-condition missing-dependency (missing-component)
   ((required-by :initarg :required-by :reader missing-required-by)))
 
+(define-condition missing-dependency-of-version (missing-dependency
+                                                 missing-component-of-version)
+  ())
+
 (define-condition operation-error (error)
   ((component :reader error-component :initarg :component)
    (operation :reader error-operation :initarg :operation))
@@ -224,14 +250,20 @@ and NIL NAME and TYPE components"
 ;;;; methods: components
 
 (defmethod print-object ((c missing-component) s)
-  (format s "~@<component ~S not found~
-             ~@[ or does not match version ~A~]~
+   (format s "~@<component ~S not found~
              ~@[ in ~A~]~@:>"
           (missing-requires c)
-          (missing-version c)
           (when (missing-parent c)
             (component-name (missing-parent c)))))
 
+(defmethod print-object ((c missing-component-of-version) s)
+  (format s "~@<component ~S does not match version ~A~
+              ~@[ in ~A~]~@:>"
+           (missing-requires c)
+           (missing-version c)
+           (when (missing-parent c)
+             (component-name (missing-parent c)))))
+
 (defgeneric component-system (component)
   (:documentation "Find the top-level system containing COMPONENT"))
 
@@ -336,7 +368,11 @@ and NIL NAME and TYPE components"
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;; finding systems
 
-(defvar *defined-systems* (make-hash-table :test 'equal))
+(defun make-defined-systems-table ()
+  (make-hash-table :test 'equal))
+
+(defvar *defined-systems* (make-defined-systems-table))
+
 (defun coerce-name (name)
   (typecase name
     (component (component-name name))
@@ -344,6 +380,10 @@ and NIL NAME and TYPE components"
     (string name)
     (t (sysdef-error "~@<invalid component designator ~A~@:>" name))))
 
+(defun system-registered-p (name)
+  (gethash (coerce-name name) *defined-systems*))
+
+
 ;;; for the sake of keeping things reasonably neat, we adopt a
 ;;; convention that functions in this list are prefixed SYSDEF-
 
@@ -351,13 +391,26 @@ and NIL NAME and TYPE components"
   '(sysdef-central-registry-search))
 
 (defun system-definition-pathname (system)
-  (some (lambda (x) (funcall x system))
-        *system-definition-search-functions*))
+  (let ((system-name (coerce-name system)))
+    (or
+     (some (lambda (x) (funcall x system-name))
+           *system-definition-search-functions*)
+     (let ((system-pair (system-registered-p system-name)))
+       (and system-pair
+            (system-source-file (cdr system-pair)))))))
 
 (defvar *central-registry*
-  '(*default-pathname-defaults*
-    #+nil "/home/dan/src/sourceforge/cclan/asdf/systems/"
-    #+nil "telent:asdf;systems;"))
+  '(*default-pathname-defaults*)
+"A list of 'system directory designators' ASDF uses to find systems.
+
+A 'system directory designator' is a pathname or a function
+which evaluates to a pathname. For example:
+
+    (setf asdf:*central-registry*
+          (list '*default-pathname-defaults*
+                #p\"/home/me/cl/systems/\"
+                #p\"/usr/share/common-lisp/systems/\"))
+")
 
 (defun sysdef-central-registry-search (system)
   (let ((name (coerce-name system)))
@@ -382,7 +435,7 @@ and NIL NAME and TYPE components"
 
 (defun find-system (name &optional (error-p t))
   (let* ((name (coerce-name name))
-         (in-memory (gethash name *defined-systems*))
+         (in-memory (system-registered-p name))
          (on-disk (system-definition-pathname name)))
     (when (and on-disk
                (or (not in-memory)
@@ -390,8 +443,7 @@ and NIL NAME and TYPE components"
       (let ((package (make-temporary-package)))
         (unwind-protect
              (let ((*package* package))
-               (format
-                *verbose-out*
+               (asdf-message
                 "~&~@<; ~@;loading system definition from ~A into ~A~@:>~%"
                 ;; FIXME: This wants to be (ENOUGH-NAMESTRING
                 ;; ON-DISK), but CMUCL barfs on that.
@@ -399,19 +451,17 @@ and NIL NAME and TYPE components"
                 *package*)
                (load on-disk))
           (delete-package package))))
-    (let ((in-memory (gethash name *defined-systems*)))
+    (let ((in-memory (system-registered-p name)))
       (if in-memory
           (progn (if on-disk (setf (car in-memory) (file-write-date on-disk)))
                  (cdr in-memory))
           (if error-p (error 'missing-component :requires name))))))
 
 (defun register-system (name system)
-  (format *verbose-out* "~&~@<; ~@;registering ~A as ~A~@:>~%" system name)
-  (setf (gethash (coerce-name  name) *defined-systems*)
+  (asdf-message "~&~@<; ~@;registering ~A as ~A~@:>~%" system name)
+  (setf (gethash (coerce-name name) *defined-systems*)
         (cons (get-universal-time) system)))
 
-(defun system-registered-p (name)
-  (gethash (coerce-name name) *defined-systems*))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;; finding components
@@ -492,11 +542,43 @@ system."))
   ;; empty method to disable initarg validity checking
   )
 
-(defgeneric perform (operation component))
-(defgeneric operation-done-p (operation component))
-(defgeneric explain (operation component))
-(defgeneric output-files (operation component))
-(defgeneric input-files (operation component))
+(define-method-combination standard-asdf-method-combination ()
+  ((around-asdf (around))
+   (around (:around))
+   (before (:before))
+   (primary () :required t)
+   (after (:after)))
+  (flet ((call-methods (methods)
+           (mapcar #'(lambda (method)
+                       `(call-method ,method))
+                   methods)))
+    (let* ((form (if (or before after (rest primary))
+                     `(multiple-value-prog1
+                          (progn ,@(call-methods before)
+                                 (call-method ,(first primary)
+                                              ,(rest primary)))
+                        ,@(call-methods (reverse after)))
+                     `(call-method ,(first primary))))
+           (standard-form (if around
+                              `(call-method ,(first around)
+                                            (,@(rest around)
+                                               (make-method ,form)))
+                              form)))
+      (if around-asdf
+          `(call-method ,(first around-asdf)
+                        (,@(rest around-asdf) (make-method ,standard-form)))
+          standard-form))))
+
+(defgeneric perform (operation component)
+  (:method-combination standard-asdf-method-combination))
+(defgeneric operation-done-p (operation component)
+  (:method-combination standard-asdf-method-combination))
+(defgeneric explain (operation component)
+  (:method-combination standard-asdf-method-combination))
+(defgeneric output-files (operation component)
+  (:method-combination standard-asdf-method-combination))
+(defgeneric input-files (operation component)
+  (:method-combination standard-asdf-method-combination))
 
 (defun node-for (o c)
   (cons (class-name (class-of o)) c))
@@ -532,6 +614,8 @@ the head of the tree"))
                   :parent o :original-initargs args args)))))
 
 
+(defgeneric component-visited-p (operation component))
+
 (defgeneric visit-component (operation component data))
 
 (defmethod visit-component ((o operation) (c component) data)
@@ -539,8 +623,6 @@ the head of the tree"))
     (push (cons (node-for o c) data)
           (operation-visited-nodes (operation-ancestor o)))))
 
-(defgeneric component-visited-p (operation component))
-
 (defmethod component-visited-p ((o operation) (c component))
   (assoc (node-for o c)
          (operation-visited-nodes (operation-ancestor o))
@@ -563,7 +645,7 @@ the head of the tree"))
 (defgeneric component-visiting-p (operation component))
 
 (defmethod component-visiting-p ((o operation) (c component))
-  (let ((node (cons o c)))
+  (let ((node (node-for o c)))
     (member node (operation-visiting-nodes (operation-ancestor o))
             :test 'equal)))
 
@@ -653,40 +735,73 @@ the head of the tree"))
 ;;; So you look at this code and think "why isn't it a bunch of
 ;;; methods".  And the answer is, because standard method combination
 ;;; runs :before methods most->least-specific, which is back to front
-;;; for our purposes.  And CLISP doesn't have non-standard method
-;;; combinations, so let's keep it simple and aspire to portability
+;;; for our purposes.
 
 (defgeneric traverse (operation component))
 (defmethod traverse ((operation operation) (c component))
   (let ((forced nil))
-    (labels ((do-one-dep (required-op required-c required-v)
+    (labels ((%do-one-dep (required-op required-c required-v)
                (let* ((dep-c (or (find-component
                                   (component-parent c)
                                   ;; XXX tacky.  really we should build the
                                   ;; in-order-to slot with canonicalized
                                   ;; names instead of coercing this late
                                   (coerce-name required-c) required-v)
-                                 (error 'missing-dependency
-                                        :required-by c
-                                        :version required-v
-                                        :requires required-c)))
+                                 (if required-v
+                                     (error 'missing-dependency-of-version
+                                            :required-by c
+                                            :version required-v
+                                            :requires required-c)
+                                     (error 'missing-dependency
+                                            :required-by c
+                                            :requires required-c))))
                       (op (make-sub-operation c operation dep-c required-op)))
                  (traverse op dep-c)))
+             (do-one-dep (required-op required-c required-v)
+               (loop
+                  (restart-case
+                      (return (%do-one-dep required-op required-c required-v))
+                    (retry ()
+                      :report (lambda (s)
+                                (format s "~@<Retry loading component ~S.~@:>"
+                                        required-c))
+                      :test
+                      (lambda (c)
+#|
+                        (print (list :c1 c (typep c 'missing-dependency)))
+                        (when (typep c 'missing-dependency)
+                          (print (list :c2 (missing-requires c) required-c
+                                       (equalp (missing-requires c)
+                                               required-c))))
+|#
+                        (and (typep c 'missing-dependency)
+                             (equalp (missing-requires c)
+                                     required-c)))))))
              (do-dep (op dep)
                (cond ((eq op 'feature)
                       (or (member (car dep) *features*)
                           (error 'missing-dependency
                                  :required-by c
-                                 :requires (car dep)
-                                 :version nil)))
+                                 :requires (car dep))))
                      (t
                       (dolist (d dep)
                         (cond ((consp d)
-                               (assert (string-equal
-                                        (symbol-name (first d))
-                                        "VERSION"))
-                               (appendf forced
-                                        (do-one-dep op (second d) (third d))))
+                               (cond ((string-equal
+                                       (symbol-name (first d))
+                                       "VERSION")
+                                      (appendf
+                                       forced
+                                       (do-one-dep op (second d) (third d))))
+                                     ((and (string-equal
+                                            (symbol-name (first d))
+                                            "FEATURE")
+                                           (find (second d) *features*
+                                                 :test 'string-equal))
+                                      (appendf
+                                       forced
+                                       (do-one-dep op (second d) (third d))))
+                                     (t
+                                      (error "Dependencies must be (:version <version>), (:feature <feature>), or a name"))))
                               (t
                                (appendf forced (do-one-dep op d nil)))))))))
       (aif (component-visited-p operation c)
@@ -696,45 +811,51 @@ the head of the tree"))
       (if (component-visiting-p operation c)
           (error 'circular-dependency :components (list c)))
       (setf (visiting-component operation c) t)
-      (loop for (required-op . deps) in (component-depends-on operation c)
-            do (do-dep required-op deps))
-      ;; constituent bits
-      (let ((module-ops
-             (when (typep c 'module)
-               (let ((at-least-one nil)
-                     (forced nil)
-                     (error nil))
-                 (loop for kid in (module-components c)
-                       do (handler-case
-                              (appendf forced (traverse operation kid ))
-                            (missing-dependency (condition)
-                              (if (eq (module-if-component-dep-fails c) :fail)
-                                  (error condition))
-                              (setf error condition))
-                            (:no-error (c)
-                              (declare (ignore c))
-                              (setf at-least-one t))))
-                 (when (and (eq (module-if-component-dep-fails c) :try-next)
-                            (not at-least-one))
-                   (error error))
-                 forced))))
-        ;; now the thing itself
-        (when (or forced module-ops
-                  (not (operation-done-p operation c))
-                  (let ((f (operation-forced (operation-ancestor operation))))
-                    (and f (or (not (consp f))
-                               (member (component-name
-                                        (operation-ancestor operation))
-                                       (mapcar #'coerce-name f)
-                                       :test #'string=)))))
-          (let ((do-first (cdr (assoc (class-name (class-of operation))
-                                      (slot-value c 'do-first)))))
-            (loop for (required-op . deps) in do-first
-                  do (do-dep required-op deps)))
-          (setf forced (append (delete 'pruned-op forced :key #'car)
-                               (delete 'pruned-op module-ops :key #'car)
-                               (list (cons operation c))))))
-      (setf (visiting-component operation c) nil)
+      (unwind-protect
+           (progn
+             (loop for (required-op . deps) in
+                  (component-depends-on operation c)
+                  do (do-dep required-op deps))
+             ;; constituent bits
+             (let ((module-ops
+                    (when (typep c 'module)
+                      (let ((at-least-one nil)
+                            (forced nil)
+                            (error nil))
+                        (loop for kid in (module-components c)
+                           do (handler-case
+                                  (appendf forced (traverse operation kid ))
+                                (missing-dependency (condition)
+                                  (if (eq (module-if-component-dep-fails c)
+                                          :fail)
+                                      (error condition))
+                                  (setf error condition))
+                                (:no-error (c)
+                                  (declare (ignore c))
+                                  (setf at-least-one t))))
+                        (when (and (eq (module-if-component-dep-fails c)
+                                       :try-next)
+                                   (not at-least-one))
+                          (error error))
+                        forced))))
+               ;; now the thing itself
+               (when (or forced module-ops
+                         (not (operation-done-p operation c))
+                         (let ((f (operation-forced
+                                   (operation-ancestor operation))))
+                           (and f (or (not (consp f))
+                                      (member (component-name
+                                               (operation-ancestor operation))
+                                              (mapcar #'coerce-name f)
+                                              :test #'string=)))))
+                 (let ((do-first (cdr (assoc (class-name (class-of operation))
+                                             (slot-value c 'do-first)))))
+                   (loop for (required-op . deps) in do-first
+                      do (do-dep required-op deps)))
+                 (setf forced (append (delete 'pruned-op forced :key #'car)
+                                      (delete 'pruned-op module-ops :key #'car)
+                                      (list (cons operation c)))))))
+        (setf (visiting-component operation c) nil))
       (visit-component operation c (and forced t))
       forced)))
 
@@ -749,7 +870,7 @@ the head of the tree"))
   nil)
 
 (defmethod explain ((operation operation) (component component))
-  (format *verbose-out* "~&;;; ~A on ~A~%" operation component))
+  (asdf-message "~&;;; ~A on ~A~%" operation component))
 
 ;;; compile-op
 
@@ -765,8 +886,7 @@ the head of the tree"))
 
 (defmethod perform :after ((operation operation) (c component))
   (setf (gethash (type-of operation) (component-operation-times c))
-        (get-universal-time))
-  (load-preferences c operation))
+        (get-universal-time)))
 
 ;;; perform is required to check output-files to find out where to put
 ;;; its answers, in case it has been overridden for site policy
@@ -816,8 +936,49 @@ the head of the tree"))
 (defmethod perform ((o load-op) (c cl-source-file))
   (mapcar #'load (input-files o c)))
 
+(defmethod perform around ((o load-op) (c cl-source-file))
+  (let ((state :initial))
+    (loop until (or (eq state :success)
+                    (eq state :failure)) do
+         (case state
+           (:recompiled
+            (setf state :failure)
+            (call-next-method)
+            (setf state :success))
+           (:failed-load
+            (setf state :recompiled)
+            (perform (make-instance 'asdf:compile-op) c))
+           (t
+            (with-simple-restart
+                (try-recompiling "Recompile ~a and try loading it again"
+                                  (component-name c))
+              (setf state :failed-load)
+              (call-next-method)
+              (setf state :success)))))))
+
+(defmethod perform around ((o compile-op) (c cl-source-file))
+  (let ((state :initial))
+    (loop until (or (eq state :success)
+                    (eq state :failure)) do
+         (case state
+           (:recompiled
+            (setf state :failure)
+            (call-next-method)
+            (setf state :success))
+           (:failed-compile
+            (setf state :recompiled)
+            (perform (make-instance 'asdf:compile-op) c))
+           (t
+            (with-simple-restart
+                (try-recompiling "Try recompiling ~a"
+                                  (component-name c))
+              (setf state :failed-compile)
+              (call-next-method)
+              (setf state :success)))))))
+
 (defmethod perform ((operation load-op) (c static-file))
   nil)
+
 (defmethod operation-done-p ((operation load-op) (c static-file))
   t)
 
@@ -865,72 +1026,25 @@ the head of the tree"))
 (defmethod perform ((operation test-op) (c component))
   nil)
 
-(defgeneric load-preferences (system operation)
-  (:documentation
-   "Called to load system preferences after <perform operation
-system>. Typical uses are to set parameters that don't exist until
-after the system has been loaded."))
-
-(defgeneric preference-file-for-system/operation (system operation)
-  (:documentation
-   "Returns the pathname of the preference file for this system.
-Called by 'load-preferences to determine what file to load."))
-
-(defmethod load-preferences ((s t) (operation t))
-  ;; do nothing
-  (values))
-
-(defmethod load-preferences ((s system) (operation basic-load-op))
-  (let* ((*package* (find-package :common-lisp))
-         (file (probe-file (preference-file-for-system/operation s operation))))
-    (when file
-      (when *verbose-out*
-        (format *verbose-out*
-                "~&~@<; ~@;loading preferences for ~A/~(~A~) from ~A~@:>~%"
-                (component-name s)
-                (type-of operation) file))
-      (load file))))
-
-(defmethod preference-file-for-system/operation ((system t) (operation t))
-  ;; cope with anything other than systems
-  (preference-file-for-system/operation (find-system system t) operation))
-
-(defmethod preference-file-for-system/operation ((s system) (operation t))
-  (let ((*default-pathname-defaults*
-         (make-pathname :name nil :type nil
-                        :defaults *default-pathname-defaults*)))
-     (merge-pathnames
-      (make-pathname :name (component-name s)
-                     :type "lisp"
-                     :directory '(:relative ".asdf"))
-      (truename (user-homedir-pathname)))))
+(defmethod operation-done-p ((operation test-op) (c system))
+  "Testing a system is _never_ done."
+  nil)
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;; invoking operations
 
-(defvar *operate-docstring*
-  "Operate does three things:
-
-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
-
-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.")
-
-(defun operate (operation-class system &rest args &key (verbose t) version
+(defun operate (operation-class system &rest args &key (verbose t) version force
                 &allow-other-keys)
-  (let* ((op (apply #'make-instance operation-class
+  (declare (ignore force))
+  (let* ((*package* *package*)
+         (*readtable* *readtable*)
+         (op (apply #'make-instance operation-class
                     :original-initargs args
                     args))
          (*verbose-out* (if verbose *standard-output* (make-broadcast-stream)))
          (system (if (typep system 'component) system (find-system system))))
     (unless (version-satisfies system version)
-      (error 'missing-component :requires system :version version))
+      (error 'missing-component-of-version :requires system :version version))
     (let ((steps (traverse op system)))
       (with-compilation-unit ()
         (loop for (op . component) in steps do
@@ -954,17 +1068,45 @@ method.")
                              (get-universal-time))
                        (return)))))))))
 
-(setf (documentation 'operate 'function)
-      *operate-docstring*)
-
-(defun oos (operation-class system &rest args &key force (verbose t) version)
+(defun oos (operation-class system &rest args &key force (verbose t) version
+            &allow-other-keys)
   (declare (ignore force verbose version))
   (apply #'operate operation-class system args))
 
-(setf (documentation 'oos 'function)
-      (format nil
-              "Short for _operate on system_ and an alias for the `operate` function. ~&~&~a"
-              *operate-docstring*))
+(let ((operate-docstring
+  "Operate does three things:
+
+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
+
+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."))
+  (setf (documentation 'oos 'function)
+        (format nil
+                "Short for _operate on system_ and an alias for the [operate][] function. ~&~&~a"
+                operate-docstring))
+  (setf (documentation 'operate 'function)
+        operate-docstring))
+
+(defun load-system (system &rest args &key force (verbose t) version)
+  "Shorthand for `(operate 'asdf:load-op system)`. See [operate][] for details."
+  (declare (ignore force verbose version))
+  (apply #'operate 'load-op system args))
+
+(defun compile-system (system &rest args &key force (verbose t) version)
+  "Shorthand for `(operate 'asdf:compile-op system)`. See [operate][] for details."
+  (declare (ignore force verbose version))
+  (apply #'operate 'compile-op system args))
+
+(defun test-system (system &rest args &key force (verbose t) version)
+  "Shorthand for `(operate 'asdf:test-op system)`. See [operate][] for details."
+  (declare (ignore force verbose version))
+  (apply #'operate 'test-op system args))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;; syntax
@@ -991,9 +1133,6 @@ method.")
            (cond ((and s (eq (type-of (cdr s)) ',class))
                   (setf (car s) (get-universal-time)))
                  (s
-                  #+clisp
-                  (sysdef-error "Cannot redefine the existing system ~A with a different class" s)
-                  #-clisp
                   (change-class (cdr s) ',class))
                  (t
                   (register-system (quote ,name)
@@ -1065,6 +1204,47 @@ Returns the new tree (which probably shares structure with the old one)"
 
 (defvar *serial-depends-on*)
 
+(defun sysdef-error-component (msg type name value)
+  (sysdef-error (concatenate 'string msg
+                             "~&The value specified for ~(~A~) ~A is ~W")
+                type name value))
+
+(defun check-component-input (type name weakly-depends-on depends-on components in-order-to)
+  "A partial test of the values of a component."
+  (when weakly-depends-on (warn "We got one! XXXXX"))
+  (unless (listp depends-on)
+    (sysdef-error-component ":depends-on must be a list."
+                            type name depends-on))
+  (unless (listp weakly-depends-on)
+    (sysdef-error-component ":weakly-depends-on must be a list."
+                            type name weakly-depends-on))
+  (unless (listp components)
+    (sysdef-error-component ":components must be NIL or a list of components."
+                            type name components))
+  (unless (and (listp in-order-to) (listp (car in-order-to)))
+    (sysdef-error-component ":in-order-to must be NIL or a list of components."
+                            type name in-order-to)))
+
+(defun %remove-component-inline-methods (ret rest)
+  (loop for name in +asdf-methods+
+        do (map 'nil
+                ;; this is inefficient as most of the stored
+                ;; methods will not be for this particular gf n
+                ;; But this is hardly performance-critical
+                (lambda (m)
+                  (remove-method (symbol-function name) m))
+                (component-inline-methods ret)))
+  ;; clear methods, then add the new ones
+  (setf (component-inline-methods ret) nil)
+  (loop for name in +asdf-methods+
+        for v = (getf rest (intern (symbol-name name) :keyword))
+        when v do
+        (destructuring-bind (op qual (o c) &body body) v
+          (pushnew
+           (eval `(defmethod ,name ,qual ((,o ,op) (,c (eql ,ret)))
+                             ,@body))
+           (component-inline-methods ret)))))
+
 (defun parse-component-form (parent options)
 
   (destructuring-bind
@@ -1143,47 +1323,6 @@ Returns the new tree (which probably shares structure with the old one)"
 
       ret)))
 
-(defun %remove-component-inline-methods (ret rest)
-  (loop for name in +asdf-methods+
-        do (map 'nil
-                ;; this is inefficient as most of the stored
-                ;; methods will not be for this particular gf n
-                ;; But this is hardly performance-critical
-                (lambda (m)
-                  (remove-method (symbol-function name) m))
-                (component-inline-methods ret)))
-  ;; clear methods, then add the new ones
-  (setf (component-inline-methods ret) nil)
-  (loop for name in +asdf-methods+
-        for v = (getf rest (intern (symbol-name name) :keyword))
-        when v do
-        (destructuring-bind (op qual (o c) &body body) v
-          (pushnew
-           (eval `(defmethod ,name ,qual ((,o ,op) (,c (eql ,ret)))
-                             ,@body))
-           (component-inline-methods ret)))))
-
-(defun check-component-input (type name weakly-depends-on depends-on components in-order-to)
-  "A partial test of the values of a component."
-  (when weakly-depends-on (warn "We got one! XXXXX"))
-  (unless (listp depends-on)
-    (sysdef-error-component ":depends-on must be a list."
-                            type name depends-on))
-  (unless (listp weakly-depends-on)
-    (sysdef-error-component ":weakly-depends-on must be a list."
-                            type name weakly-depends-on))
-  (unless (listp components)
-    (sysdef-error-component ":components must be NIL or a list of components."
-                            type name components))
-  (unless (and (listp in-order-to) (listp (car in-order-to)))
-    (sysdef-error-component ":in-order-to must be NIL or a list of components."
-                            type name in-order-to)))
-
-(defun sysdef-error-component (msg type name value)
-  (sysdef-error (concatenate 'string msg
-                             "~&The value specified for ~(~A~) ~A is ~W")
-                type name value))
-
 (defun resolve-symlinks (path)
   #-allegro (truename path)
   #+allegro (excl:pathname-resolve-symbolic-links path)
@@ -1196,11 +1335,11 @@ Returns the new tree (which probably shares structure with the old one)"
 ;;; is ambiguous, send a bug report
 
 (defun run-shell-command (control-string &rest args)
-  "Interpolate ARGS into CONTROL-STRING as if by FORMAT, and
+  "Interpolate `args` into `control-string` as if by `format`, and
 synchronously execute the result using a Bourne-compatible shell, with
-output to *VERBOSE-OUT*.  Returns the shell's exit code."
+output to `*verbose-out*`.  Returns the shell's exit code."
   (let ((command (apply #'format nil control-string args)))
-    (format *verbose-out* "; $ ~A~%" command)
+    (asdf-message "; $ ~A~%" command)
     #+sbcl
     (sb-ext:process-exit-code
      (sb-ext:run-program
@@ -1217,7 +1356,16 @@ output to *VERBOSE-OUT*.  Returns the shell's exit code."
       :input nil :output *verbose-out*))
 
     #+allegro
-    (excl:run-shell-command command :input nil :output *verbose-out*)
+    ;; will this fail if command has embedded quotes - it seems to work
+    (multiple-value-bind (stdout stderr exit-code)
+        (excl.osi:command-output
+         (format nil "~a -c \"~a\""
+                 #+mswindows "sh" #-mswindows "/bin/sh" command)
+         :input nil :whole nil
+         #+mswindows :show-window #+mswindows :hide)
+      (format *verbose-out* "~{~&; ~a~%~}~%" stderr)
+      (format *verbose-out* "~{~&; ~a~%~}~%" stdout)
+      exit-code)
 
     #+lispworks
     (system:call-system-showing-output
@@ -1234,26 +1382,28 @@ output to *VERBOSE-OUT*.  Returns the shell's exit code."
                 (ccl:run-program "/bin/sh" (list "-c" command)
                                  :input nil :output *verbose-out*
                                  :wait t)))
+
     #+ecl ;; courtesy of Juan Jose Garcia Ripoll
     (si:system command)
+
     #-(or openmcl clisp lispworks allegro scl cmu sbcl ecl)
     (error "RUN-SHELL-PROGRAM not implemented for this Lisp")
     ))
 
+(defgeneric system-source-file (system)
+  (:documentation "Return the source file in which system is defined."))
 
-(defgeneric hyperdocumentation (package name doc-type))
-(defmethod hyperdocumentation ((package symbol) name doc-type)
-  (hyperdocumentation (find-package package) name doc-type))
-
-(defun hyperdoc (name doc-type)
-  (hyperdocumentation (symbol-package name) name doc-type))
+(defmethod system-source-file ((system-name t))
+  (system-source-file (find-system system-name)))
 
-(defun system-source-file (system-name)
-  (let ((system (asdf:find-system system-name)))
-    (make-pathname
-     :type "asd"
-     :name (asdf:component-name system)
-     :defaults (asdf:component-relative-pathname system))))
+(defmethod system-source-file ((system system))
+  (let ((pn (and (slot-boundp system 'relative-pathname)
+                 (make-pathname
+                  :type "asd"
+                  :name (asdf:component-name system)
+                  :defaults (asdf:component-relative-pathname system)))))
+    (when pn
+      (probe-file pn))))
 
 (defun system-source-directory (system-name)
   (make-pathname :name nil
@@ -1261,7 +1411,8 @@ output to *VERBOSE-OUT*.  Returns the shell's exit code."
                  :defaults (system-source-file system-name)))
 
 (defun system-relative-pathname (system pathname &key name type)
-  (let ((directory (pathname-directory pathname)))
+  ;; you're not allowed to muck with the return value of pathname-X
+  (let ((directory (copy-list (pathname-directory pathname))))
     (when (eq (car directory) :absolute)
       (setf (car directory) :relative))
     (merge-pathnames
@@ -1270,7 +1421,6 @@ output to *VERBOSE-OUT*.  Returns the shell's exit code."
                     :directory directory)
      (system-source-directory system))))
 
-
 (pushnew :asdf *features*)
 
 #+sbcl
@@ -1316,4 +1466,8 @@ output to *VERBOSE-OUT*.  Returns the shell's exit code."
   (pushnew 'module-provide-asdf sb-ext:*module-provider-functions*)
   (pushnew 'contrib-sysdef-search *system-definition-search-functions*))
 
+(if *asdf-revision*
+    (asdf-message ";; ASDF, revision ~a" *asdf-revision*)
+    (asdf-message ";; ASDF, revision unknown; possibly a development version"))
+
 (provide 'asdf)