Re: [Boost-build] BBv2 documentation (was: Getting started with BBv2)

From: Reece Dunn (msclrhd_at_[hidden])
Date: 2005-11-13 04:54:41

Jared W. Robinson wrote:
> On Sun, Nov 06, 2005 at 11:08:22AM +0000, Reece Dunn wrote:
>> My advice for trying to extend BBv2 is to read the documentation, look 
>> at the BBv2 Wiki and look at how the other tools are written to see how 
>> they work. Observing on this list is another good way to pick up how 
>> BBv2 works. Then start small and work up.
> 
> I'm new here, and have been (somewhat painfully) learning about BBv2.
> The challenge was knowing where to start, what the gaps were, and
> understanding the history of the project.

Sure. BJam/BBv2 is not yet easy enough to use for a beginner, but it is 
getting there.

> At work, we're using BBv2. I'm experienced with GNU Make. This is
> completely different. The details are abstracted away almost too far.

I would not say that the details are abstracted away too far. This is 
where the documentation comes in. I personally like being able to say:

    exe hello : hello.cpp : <inlining>on <warnings>off ;

I realize that some options on some compilers lose some functionality 
(e.g. the warnings feature only covers some of the warning levels on the 
msvc compiler), but (1) that can't really be helped when designing an 
abstract, compiler-independant system and (2) the most common levels are 
covered (all=4, on=3, off=0).

BBv2 also takes care of some things that it is *very easy* to get wrong. 
Using Microsoft VC project files, I have commonly made changes in the 
debug version, where I should have changed all configurations. In BBv2, 
I don't need to care about debug/release settings as it takes care of 
them for me.

> For the casual user who wants to add one more target, or one more source
> file to the dependency list for a target, BBv2 makes life easy. But for
> those who desire to add a compile or link option, understanding the
> system is an uphill battle. It's also difficult to know how to plug BBv2
> into an existing project.

The <c[xx]flags> and <linkflags> features are there to pass specific 
options to the compiler/linker. If you want to make that option generic, 
you can add it as a feature. The documentation explains how to add a 
feature, but doesn't explain how to extend an existing toolset to add 
the options to support a new feature.

> I've heard whisperings on the list that someone is working on
> documentation.

There already exists some documentation (written by Volodya) that has 
had editorial comments provided by Dave and others on this list. There 
are others interested in writing the documentation (see previous posts, 
plus I am intersted as well).

> But what form it will take and when it will appear is a
> mystery, at least to me. I would like to see an O'Reilly book or
> something similar. In the meantime, here's what's been most useful to
> me. Feel free to correct incorrect terminology or analogies.

See http://www.boost.org/doc/html/bbv2.html for the current BBv2 
documentation.

> First, Boost Build Version 2 (BBv2) isn't GNU Make. Perhaps BJam could
> be compared to GNU Make, and BBv2 compared to a complex set of
> supporting Makefiles (i.e. infrastructure) that help Make know how to
> effectively perform a build.  BJam could be compared to the raw Python
> interpreter, whereas BBv2 could be compared to the default libraries (.py
> and .pyc) files that come with the Python distribution.

Indeed, Perforce Jam (Jam/MR) describes itself as "Make Redux". For 
Make: GNU Make -> BJam; automake -> BBv2. For Python: Python -> BJam; 
BBv2 -> SCons.

> Second, BJam is a descendant of Jam. BJam is poorly documented in
> comparison, so it's important to understand Jam. The best, and most
> effective way, IMHO, to get started is to read
> http://www.perforce.com/perforce/conf2001/wingerd/WPLaura.pdf
> followed by using http://public.perforce.com/public/jam/src/Jam.html as
> a reference.

See boost/tools/build/jam_src/Jam.html.

> Download Boost and look at the Jamfile.v2 files, and especially get
> acquainted with the Boost Build library (located in tools/build/v2).
> There are (sparse) tests in the .jam files that show how to use some of
> the features of the modules (see tools/build/v2/util/*.jam)

Indeed, looking at the BBv2 support for the various libraries and at the 
source code are good ways to learn.

> There are still some things I'm confused about, or that need more clear
> documentation. Perhaps this is coming, but here's what I'd like:
> - A table that lists compiler switches, descriptions, and how to
>   activate them in BBv2. For example, if I want -O3 or -Os for gcc, how do
>   I get it? If I want symbols, how do I get them? Currently, I search
>   through Boost Jamfiles, the tools/build/v2 directory, or even easier,
>   I search through my archives of the Boost-Jam mailing list. For people
>   on my team, this is a rather high barrier to entry.

This would most likely be a feature description table, e.g.:

    Feature : Value(s) : Description
    --------:----------:------------
    <link>  : shared   : Used with the lib rule to define a shared 
(dynamic-link) library.

Otherwise, it becomes too difficult to document the options /for each 
supported compiler/.

> - What are the built-in variables?
> - Give me a keyword list, and explanation of what the keywords do.
> - Give me a BBv2 rule list with references to the page that explains
>   each one.

I think having clearer reference tables for BBv2 would be a good thing.

> I may be completely wrong in my perceptions. However, I hope that what
> I've written will be useful to newcomers, and perhaps to the veterans so
> that they can make Boost.Build more approachable to newcomers.

Your comments (and comments from others) will help make the 
documentation clearer and easier to navigate.

My thoughts: I think it would be a good idea to pool the resources for 
revising the BBv2 documentation. I am currently writing some reference 
tables (based on Jared's observations) for features, etc. This is being 
written in QuickBook, which makes writing BoostBook documentation very easy.

I suggest that we divide the workload between interested parties, so 
someone will be working on the Overview/Layout, Getting Started, User 
Guide, Extenders Guide and Reference sections.

There is also a lot of information spread out all over the place (BBv2 
docs, Wiki, Boost/Getting Started, jam_src/index.html, etc.) that should 
be in one place (this is part of the confusion). Also, the BBv2 
documentation is difficult to access (www.boost.org -> Getting Started 
(Preparation) -> Boost.Build -> Boost.Build2 -> Documentation).

- Reece