The existing manual doesn't document ASDF's :weakly-depends-on, an issue which this patch addresses.
Two notes about this patch, which characterize it as interim:
1. It would help if I had a better example of the use of :weakly-depends-on. I believe I have the semantics right, but I don't have a good use case (a simple textual discussion is enough of a use case). It's not so much how to use the feature as how people write systems that use the feature. For example, would you write a piece of code that weakly depended on system foo, set up system foo so that it pushed :foo on the *features* and then sprinkle "#+ foo" around your code? It almost seems like we'd want a corresponding construct that would load a file only if some feature was present at system operate time (NOT at the time when the ASDF system definition was read).
2. I found that documenting this exposed a weakness in the ASDF manual's structure. The manual provides a section that documents the grammar, and a section that documents the ASDF object model. There isn't really a section that gives a semantic counterpart to the syntax. One might think that the object model documentation would fill this need, but it doesn't really. :weakly-depends-on is a good example of this hole, because weakly-depends-on is translated either into a component dependency or into nothing, so it has meaning only as part of a defsystem form. We can't describe its semantics in the section on the object model, because there is no object model component that corresponds directly to the weakly-depends-on argument.
BTW, line 1319 of asdf.lisp seems to be someone's debugging statement left around. Shouldn't it be excised?
diff --git a/asdf.texinfo b/asdf.texinfo index cfef5c6..0d26235 100644 --- a/asdf.texinfo +++ b/asdf.texinfo @@ -338,6 +338,7 @@ option := :components component-list | :output-files method-form | :operation-done-p method-form | :depends-on ( {dependency-def}* ) + | :weakly-depends-on ( {dependency-def}* ) | :serial [ t | nil ] | :in-order-to ( {dependency}+ )
@@ -381,6 +382,30 @@ is equivalent to (:file "c" :depends-on ("a" "b"))) @end lisp
+@subsection Weakly-depends-on + +The @code{weakly-depends-on} argument says of the component depended on +``if this component can be found, then impose a dependency, otherwise +ignore it.'' At the top level, this can be useful for allowing a system +to take advantage of another system, if it is present. For example, a +system might generate on-line documentation if a documentation +generation system (like TINAA, Albert, etc.) was present. A system that +does text matching might do only simple matching but weakly depend on a +regular expression system and, if that system is installed, would be +able to also do regular expression matching. + +Notes: +@itemize +@item +It's not entirely clear to me that this option is very helpful at a +level below the top-level. Since it uses find-component, the behavior +differs between top level and lower level; perhaps that needs to be +explained. +@item +Presumably this will be most useful when complemented by some +conditional loading construct in the system that has the dependency. +What is that construct? +@end itemize
@subsection Source location