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
_______________________________________________
asdf-devel mailing list
[email protected]
http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel
