[Boost-build] Getting started with BBv2

From: Jared W. Robinson (jared.robinson_at_[hidden])
Date: 2005-11-08 11:54:53

Hi,

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.

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

I've heard whisperings on the list that someone is working on
documentation. 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.

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.  In other words,
BJam and BBv2 are two different animals, although the latter is built on
the former. BBv2 is meant to have a pre-defined library of rules that
simplify and abstract common tasks for the end-user.

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, with the understanding that BJam may differ in some small
ways (such as having a "-d 2" debugging level and having a few more
built-in rules). I hope that any future documentation for BBv2 would be
at least as good as these two documents, and cover the same territory.

Third, I'd say that people should read
http://public.perforce.com/public/jam/src/Jam.html, although it isn't
comprehensive and can be somewhat confusing. With a firm understanding
of the first two references, this one should be a little more
digestible.  The BBv2 documentation suffers from a lack of context in
which to understand the concepts. Therefore, fourth, people should...

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)

I think that the modules could benefit greatly from Jamdoc documentation
(or we could call it BJamDoc), something like Javadoc, but for Jam --
where the documentation is stored with the code.

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.
- What are the built-in variables? I'd like a reference sheet that
  explains each one, and if they reside inside a module, which module
  and how to get at it. I stumbled severely because Jam has $(OS) and
  $(OSVERSION), but BJam seems to hide them from view.
   - What are the standard, possible values for os.name and os.version?
     I don't want to have to divine this. Here's what I've tracked down
     so far: NT, UNIX and SOLARIS, LINUX, OS2, MAC.
- 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.
- Which modules do what, and which ones to I have to explicitly import
  into my Jamfiles? Which ones are implicitly included? (Oh, and by the
  way, what is this modules.peek thing that I see used everywhere?)
- How do I make my Jamfiles compile different things on different
  platforms correctly? Answer: Use import os ; if [ os.name = UNIX ] ...
- How do I change the defaults for a compiler tool chain? How do I do it
  separate from editing the BBv2 files (so that I can upgrade to future
  versions of Boost.Build more easily)?
- Provide an example of how to generate a .cpp or .h file that will
  then be compiled into a target. For example, we are using cxxtest. For
  the moment, we depend on GNU Make to generate several runner.cpp
  files (one for each subdirectory containing filenames ending in
  "test.h"), and then we call BJam to do the compile for each
  runner.cpp. We'd like to move this to BJam, but haven't yet figured
  out how.
- List other OSS projects using BBv2 (not merely BJam). This may be a
  great resource for people to understand how to accomplish tasks in
  their own environment. As far as I can tell, the only OSS projects
  using BJam are using 'bjam' renamed to 'jam', not BBv1 or BBv2.
  Perhaps this is because Boost.Build is meant for helping to compile
  Boost, and is not ready for wider public use.

Other things I've noticed:
- If I rename bjam to 'jam' (or hard link it), it acts like Jam, and
  doesn't look for project-root.jam. For people who want to grow their
  own infrastructure rather than use Boost.Build, this may be what they
  want.

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.

Respectfully, 

- Jared Robinson

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.