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

From: Jared W. Robinson (jared.robinson_at_[hidden])
Date: 2005-11-14 11:26:31

On Sun, Nov 13, 2005 at 09:54:41AM +0000, Reece Dunn wrote:
> > 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 ;

Yes, I think you're right. The abstractions are fine when there is
sufficient documentation, and when people know how to short-circuit the
abstraction to get the options they need, such as resorting to using
<c[xx]flags> and <linkflags>.

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

Yes, I agree with this.

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

Yes, this is a start, and I've seen it before. It might be advantageous
to dump this into a Wiki somewhere and encourage people to expand on it.
I saw the crystalclear wiki, but it's not in a very usable state (yet).
Is anyone allowed to edit the pages there? Perhaps a wiki, somewhere,
needs to specifically invite users/visitors to flesh out the content.

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

Yes, that looks a little more up-to-date. It can be confusing.  Why
can't I directly use the variables OS, OSPLAT, NT, etc (Jam.html says
they exist) in my Jamfiles? Instead, I have to "import os;" and then use
"os.name". The Jam.html file also doesn't explain some of the BJam
extensions to Jam, such as classes, modules and namespacing.

Here are a few of the reasons I like the WPLaura.pdf so much:
- Variable Expansion. Definitely not what I was expecting, but very
  important to understand.
        X = ;
        ECHO "Hello $X!" ; # Prints NOTHING!
        X = Jared Reece
        ECHO "Hello $X!" ; # Prints "Hello Jared! Hello Reece!"
- You can't assign the output of system commands (e.g. "ls", or "find")
  to Jam variables.
- Actions accept only two arguments. But you can, so to speak, set
  environment variables:
  X on MyAction = Jared Reece Bla Bla Bla ;
- $< and $> are the same as $1 and $2.

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

A table like that would be great. It would be even better if it had a
reference/hyperlink to a page where the feature was used in-context. I
still think that for people migrating away from Makefiles, they're going
to want to know what features/values map to their compiler options.
Perhaps this could be put in specialized sections, or the features table
could have references/links to the page with the compiler-specific
mappings:

     Feature : Value(s) : Description       : Compiler option mappings
     --------:----------:-------------------:-------------------------
     <link>  : shared   : Used with the...  : MSVC, gcc, etc.

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

It sounds like QuickBook saves time. Unfortunately, it may limit
contributions from average users of BBv2. Could the QuickBook
documentation be spit-out to an editable Wiki? Or perhaps the a wiki
could be implemented with BoostBook being the wiki-markup. I don't know
if that's practical or possible -- just an idea really.

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

Perhaps a "Migration to BBv2 from GNU Make" section would be in order.
It could take an example OSS project that uses Makefiles and show how to
migrate it to BBv2. And it would be fantastic if this section of the
manual could point to an OSS project that was heavily using BBv2
(besides the Boost project).

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

Absolutely agreed. Very confusing indeed.

> Also, the BBv2 documentation is difficult to access (www.boost.org ->
> Getting Started (Preparation) -> Boost.Build -> Boost.Build2 ->
> Documentation).

Agreed. 

At some point, perhaps BBv2 should become its own project, separate from
(but still used by) Boost. Think of ctags, which was shipped as part of
the Vim distribution at one time. At some point, it could stand on its
own, and was no longer shipped with vim (but is very much used by many
people, including the vim community).

- Jared