Re: [boost] Improving Boost Build?

From: Edward Diener (eldiener_at_[hidden])
Date: 2007-05-16 08:25:59

John Maddock wrote:
> Irrespective of what happens with the CMake vs BBv2 debate, it's apparent 
> that there is still plenty of support for bbv2: indeed, I would echo 
> comments that it's a pleasure to use, provided you don't need to dig in and 
> write new rules yourself :-)
> 
> So, can we improve things to the point where 99% of the remaining issues are 
> dealt with?  I think so, the things that come to mind are:
> 
> 1) Consistent command line options (as Vladimir has already brought up): use 
> "feature=xyz" or "--feature=xyz" consistently throughout.  The first of 
> these looks to be the more commonly used within BBv2 at present, so I'd vote 
> for that, and keep "-" and "--" options for controlling how bjam itself 
> behaves (as in the -d and -a options).
> 
> 2) Better docs.  Yes, I know it's been said before, but we really must get 
> the existing toolsets and their options documented.  This need not take too 
> long if someone would step up and volunteer to do it.

The doc is much better in the 1.34 release but it is still very 
difficult to understand in any orderly way. The approach should be:

1) A complete explanation of the syntax elements.
2) A complete explanation of the purpose of each separate type of bjam file.
3) A complete explanation of all of the constructs used for building 
which can be in the bjam files, and how they relate to each other.
4) Tutorial
5) Examples

I suspect all of this is in the documentation somewhere, but it is very 
difficult to find and learn given the way the documentation is presented.

I admit that I learn from understanding the constructs of a technology 
first, and only then from a tutorial and example, so perhaps my order 
reflects my way of learning. When a tutorial is presented first, as in 
the case of the Boost Build docs, and I have no understanding yet of 
syntax elements or of build constructs and meanings even though I do 
understand what in general the technology is trying to accomplish, the 
tutorial is worthless to me.

I really do think that for a technology like Boost Build that one needs 
a pretty good grounding in syntax and constructs before one can 
effectively use it. I do understand that one can ask questions and get 
excellent responses, but this does not remove the need for 
well-organized documentation. The docs are much better, but still 
difficult to follow because the organization is largely from the point 
of view of those who largely understand it rather from those who are 
trying to learn.