Re: [boost] [xpressive] HEAD doc issue

From: Eric Niebler (eric_at_[hidden])
Date: 2007-01-10 15:16:36

Vladimir Prus wrote:
> Eric Niebler wrote:
> 
>> Vladimir Prus wrote:
>>> Index: Jamfile.v2
>>> ===================================================================
>>> RCS file: /cvsroot/boost/boost/libs/xpressive/doc/Jamfile.v2,v
>>> retrieving revision 1.10
>>> diff -u -p -r1.10 Jamfile.v2
>>> --- Jamfile.v2       22 Oct 2006 03:28:00 -0000      1.10
>>> +++ Jamfile.v2       9 Jan 2007 20:01:43 -0000
>>> @@ -25,8 +25,6 @@ doxygen autodoc
>>>  xml xpressive
>>>      :
>>>          xpressive.qbk
>>> -    :
>>> -        <dependency>autodoc
>>>      ;
>>>  
>>>  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.

>> This doesn't seem right to me. I think I said what I 
>> meant to: that the xml rule invocation depends on the doxygen one.
> 
> How can it depend if the qbk -> xml process does not use the autodoc result
> in any way.

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.

>> Could you also explain how simply making one rule invocation depend on
>> another breaks the build? 
> 
> Because quickbook.jam has a bug? Which bug certainly can be fixed, but
> using <dependency> in Jamfile like this does not seem right to me either.

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.

>> Why should that be? And what's up with that 
>> error message:
>>
>> 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'
>>
>> That's awful. How's anyone supposed to make any sense of that?
> 
> Just like how anyone is supposed to make any sense of failed assert
> in a C++ program? Not all errors can be made cristal clear, 
> quickbook.jam in particular is deep wizardy. 

With an assert, at least I have the file and line information. What 
useful information does this error message give? I go to 
boost/tools/quickbook and ... what? Look in the Jamfile, I suppose. But 
nothing there looks wrong. And I can't make any sense of 
'object(file-target)@427'. Grepping jamfiles for that won't help, 
either. And 427 clearly isn't a line number -- quickbook/Jamfile.v2 
doesn't have that many lines.

OK, I know from previous run-ins with BBv2 that this is probably one of 
the hidden *actual* targets that BBv2 creates for me behind the scenes. 
I'm not supposed to know about it, right? ;-) It's times like this that 
I miss good ol' makefiles, which let me deal *directly* with the 
abstractions I care about: targets and dependencies.

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?

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