Re: [boost] [xpressive] HEAD doc issue

From: Vladimir Prus (ghost_at_[hidden])
Date: 2007-01-11 02:21:44

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?

>>> 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.

Yes, you're supposed to be able to add <dependency> on random targets
to other random targets.

>>> 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.

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.

>>> 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.

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.

Usually, this error is emitted when you mention non-existent file or
target in the sources, and never caused confusion to any user. In this case,
it's emitted due to quickbook.jam bug, and I don't think there's much point
to try making the message more helpful in case of internal bugs, given
that to fix such bug you'd need to know a bit of Boost.Build anyway.

> 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?

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.

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.

- Volodya