Re: [BBv2 doc editorial] tutorial/hierarchy

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-21 10:37:05

Vladimir Prus <ghost_at_[hidden]> writes:

> On Tuesday 20 September 2005 21:07, David Abrahams wrote:
>
>> > the project root is top/. Because there is no Jamfile in top/util/,
>> > the projects in top/app/ and top/util/foo/ are immediate children of
>> > the root project.
>>
>> It is not at all clear what the significance of the latter statement
>> is. I find it confusing to see it here with no explanation or way of
>> relating it to what I'm going to do with BB.
>
> I've just removed the "Because" clause. It did not add much value.

That doesn't help. What does it mean to me that these things are
immediate children? Nothing! Without some more information (and
perhaps even with it), that has no semantic value to the reader.

>> > Building a project does not automatically cause its sub-projects to
>> > be built unless the parent project's Jamfile explicitly requests it.
>> > In our example, top/Jamroot might contain:
>> >
>> > build-project app ;
>>
>> ^^^
>> Is this a directory or a subproject name? 

I don't actually know the answer to this question, you know.

>> It isn't clear from the example. It would be
>> clearer to use a subdirectory like util/foo, to
>> distinguish whether I'm going to be specifying a
>> path
>
> That will be problematic because of this:
>
> However, targets in <filename>top/util/foo/</filename>
> will be built only if they are needed by targets in
> <filename>top/</filename> or <filename>top/app/</filename>.
>
> You see, swapping app and util/foo will require saying that 'app' will be 
> built only if neede by util/foo, which is strange.

I didn't suggest you swap app and util/foo. Just use an example that
makes it clear whether I'm referring to a subproject or a directory.
The "immediate children" thing I'm complaining about gives some hint
that the answer may be important, but so far it's all vague and
confusing.

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