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.