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
On 2009-07-20, at 20:49 , Robert Goldman wrote:
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:
- 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).
- 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.
i sent a message back in may, to call attention to a missing use case which is related to this. (look for things on 18.05). it set out the permutations among presence and processing. of which i recognized three use cases. [upon re-reading, i think the third table should indicate that both 'a' and 'b' are to be processed when both are present.]
in order to make things clear, the documentation should break out the state of the system model and the effect of the expression with sufficient detail that, if nothing else, the reader can construct such a state table on their own.
james anderson wrote:
On 2009-07-20, at 20:49 , Robert Goldman wrote:
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:
- 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).
- 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.
i sent a message back in may, to call attention to a missing use case which is related to this. (look for things on 18.05). it set out the permutations among presence and processing. of which i recognized three use cases. [upon re-reading, i think the third table should indicate that both 'a' and 'b' are to be processed when both are present.]
in order to make things clear, the documentation should break out the state of the system model and the effect of the expression with sufficient detail that, if nothing else, the reader can construct such a state table on their own.
I am inclined to agree (see my email, which crossed with yours, about that table). But one point I was trying to make was that there's no place in the existing manual's table of contents to put something like your table.
I'm willing to contribute text to the manual, but not willing to jump in and restructure it, at least not now.
Best, r
Hi Robert,
Thanks for the patch, I'll incorporate it.
-- Gary Warren King, metabang.com Cell: (413) 559 8738 Fax: (206) 338-4052 gwkkwg on Skype * garethsan on AIM * gwking on twitter
-
Gary King -
james anderson -
Robert Goldman