Re: [boost] [xpressive] HEAD doc issue

From: Eric Niebler (eric_at_[hidden])
Date: 2007-01-11 14:52:49

Vladimir Prus wrote:
> Eric Niebler wrote:
> 
>>>>>  boostbook standalone
>>>>> @@ -36,4 +34,5 @@ boostbook standalone
>>>>>          <xsl:param>toc.max.depth=3
>>>>>          <xsl:param>toc.section.depth=3
>>>>>          <xsl:param>chunk.section.depth=3
>>>>> +    <dependency>autodoc
>>>>>      ;
>>>> Wouldn't that only create the necessary dependency when the docs are
>>>> built "standalone"?
>>> Looking at doc/Jamfile.v2, I see:
>>>
>>>     <dependency>../libs/xpressive/doc//autodoc.xml
>>>
>>> so I suppose everything is in shape.
>>
>> Ah, thanks.
> 
> So, this change is OK?

Yes, I committed the change to HEAD yesterday.

>> Understood. But I should be able to make X depend on Y if I feel like
>> it, even if X doesn't actually *use* Y's result, right? Not that I want
>> to do that, I'm just trying to understand.
> 
> Yes, you're supposed to be able to add <dependency> on random targets
> to other random targets.

Good, thanks.

>> OK. I'm still surprised to learn that there is *anything* a Jamfile can
>> do do make it an error to say that X depends on Y. It gets back to our
>> earlier discussion about targets and dependencies. In order for BBv2's
>> <dependency> to work, rule authors must follow a convention, which they
>> can get wrong. I'm guessing that's what happened here.
> 
> I'm not sure what "convention" you mean. The story is that the building
> of each type of rule is completely customizable, so to make extreme example,
> it's possible to write code that will check if there is any <dependency>
> property, and immediately fail.

The convention I refer to is on 
http://boost.org/boost-build2/doc/html/bbv2/advanced/targets.html, which 
states:

"Most main target rules in Boost.Build have the same common signature 
... Some main target rules have a different list of parameters as 
explicitly stated in their documentation."

It is the convention that most rules take "requirements" as the 3rd 
parameter, and if they don't, then the <dependency> property won't work. 
My surprise is regarding how easy it is to intentionally or 
inadvertently subvert this core abstraction.

>>>>
>>>> error: Unable to find file or target named
>>>> error:     'object(file-target)@427'
>>>> error: referred from project at
>>>> error:     '/home/ghost/Work/Boost/boost/tools/quickbook'
>>>>
<snip>
> 
> As I've said, that message is a result of a bug in quickbook.jam. What 
> are you trying to do here? Find and fix that bug? In order to conveniently
> do that, you must be familiar with Boost.Build internals.

Quickbook.jam is part of BBv2, and this is an internal error, and those 
should never happen. OK, I can accept that.

But I don't accept that others will not want to do something similar to 
what quickbook.jam is doing. There should be a way to do what 
quickbook.jam is doing without mucking about in Jam's internals and 
exposing the nasty bits in mysterious error message. That's really all 
I'm saying.

>> Why is the deep wizardry in quickbook.jam necessary? Or is it? What it's
>> trying to do is quite simple: "I'm about to use tool X. Make sure it's
>> built first." Does that require deep wizardry in BBv2, or is
>> quickbook.jam overly complicated? I'd think it should just be able to
>> add a dependency on the "install dist-bin" rule invocation in
>> tools/quickbook/Jamfile.v2, right?
> 
> I suppose there are some ways how quickbook.jam can be simplified. If you
> have some concrete proposals, please post them to boost-build list and
> I hope that João Abecasis, the quickbook.jam author, will comment.

I have occasion to do something like what quickbook.jam is doing. I want 
to use Wave to preprocess some code before sending it to Doxygen when 
building some documentation. But I want to make sure the Wave driver is 
built first. I thought I could just see how quickbook.jam does it, but I 
was put off by the complexity of it.

I probably don't know enough BBv2 to make any useful suggestions, but I 
can try.

> Personally, beyond this specific bug, I don't plan to improve
> quickbook.jam -- after all I don't use quickbook and did introduce
> quickbook.jam either.

Quickbook.jam is just one example of the larger need to be able to build 
a tool before a rule uses it. But I haven't done a lot of 
experimentation yet, so I don't know if there is an easy way to do this 
that João overlooked.

-- 
Eric Niebler
Boost Consulting
www.boost-consulting.com