Re: [Boost-build] [bbv2 test] explicit test-suite ?

From: David Abrahams (dave_at_[hidden])
Date: 2006-10-06 12:12:44

"Eric Niebler" <eric_at_[hidden]> writes:

> David Abrahams wrote:
>> Vladimir Prus <ghost_at_[hidden]> writes:
>> 
>>> But looking at the invocation of such function, you don't know what
>>> it does.  It's just that Boost.Build Jamfile is far away from actual
>>> files than make, so pretty much everything is function call.
>> 
>> To clarify, Volodya means that unlike Makefiles, which are written in
>> terms of actual files (low-level targets), Jamfiles are written in
>> terms of abstract targets that generate files.
>
>
> That doesn't really matter to me. Abstract or concrete, I should know 
> what the targets and dependencies are by looking at the Jamfile.

I understand that.  I just wanted to help you understand the system.

>> I'm not sure whether that helps, since we still don't syntactically
>> distinguish functions that generate targets from those that don't.
>> It would be interesting to think about ways to do that.  Even
>> naming conventions might help.  All that said, I am inclined to
>> agree with Volodya that this one case isn't enough to indicate a
>> great problem that needs to be dealt with.
>
> If once case isn't enough, perhaps another will help. I have a jamfile 
> for building some documentation. It has rule invocations like this:
>
>    doxygen blahdoc : [ glob ../../../boost/blah/*.hpp ] ;
>
>    xml blah : blah.qbk ;
>
> Somewhere inside blah.qbk, I have the line:
>    [xinclude blahdoc.boostbook]
>
> which causes QuickBook to pull in the doxygen-generated reference
> section. This works, but there's a problem. When I touch one of the
> header files, the doxygen rule fires and rebuilds blahdoc.boostbook,

Remember, "rules" really are just functions.  The doxygen rule only
"fires" in any real sense when your Jamfile is interpreted.  Okay,
there's one sense in which rules aren't just functions.  A rule with
an "actions" declaration block of the same name causes that action
block to be associated with building the low-level target(s) whose name
is/are contained in the rule's first argument.

To be painstakingly precise, when you touch a header file and rebuild,
one of the low-level targets in the dependency graph generated by the
program that is your Jamfile (plus the BBv2 framework) is seen to be
outdated, and some actions associated with one of the rules called by
the doxygen rule are executed.

> but the blah rule, 

blah rule?

> which invokes quickbook, doesn't. Because there
> isn't a dependency between the two rules. 
> And I have no way of knowing how to specify the dependency.

There's no way to create dependencies between rules in bjam.  It isn't
part of the programming model (nor in Make, IIUC).

> If this were make, I'd list the one target as one of the dependencies of 
> the other, and everything would just work. That doesn't work here. (I 
> know because that's the first thing I tried.) After searching, I 
> discovered that Jam has a DEPENDS intrinsic. 

Yes.  Operates on low-level targets.

> (Aside: IMO, the fact that Jam needs a hack like DEPENDS is
> indicative of the problem. Dependencies should be Jam's bread and
> butter. There should be syntax for stating dependencies, not a magic
> rule buried in some documentation. My $0.02)

I totally disagree with you there.  There's no need to invent special
syntax for something just because it's the bread and butter.  A
function call works quite well for this purpose.

> But I couldn't make it work. If I add "DEPENDS blah : blahdoc ; " to my 
> jamfile, blah *still* doesn't get rebuilt when blahdoc does.

Yeah, those are high-level abstract targets.

> It could be that the doxygen rule, or the xml rule, are creating
> targets with names other than those I expect.

They are.  Low-level ones whose names you don't want to know.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com