Boost logo

Boost-Build :

From: Alo Sarv (alo17_at_[hidden])
Date: 2005-07-23 05:36:13

Vladimir Prus wrote:
>>2. Why does msvc build display the source files separately during build,
>>but no other toolset do? I understand it's "standard" for MSVC to show
>>that (e.g. when launched from IDE), but shouldn't all toolsets generate
>>roughly the same output?
> What do you mean? For all toolsets, Boost.Build generates something like:
> toolset.compile.c bin/toolset/debug/a.o
> toolset.compile.c bin/toolset/debug/b.o
> toolset.compile.c bin/toolset/debug/c.o
$ bjam msvc

$ bjam gcc
gcc.compile.c++ bin\extra\gcc\debug\threading-multi\barrier.o
gcc.compile.c++ bin\extra\gcc\debug\threading-multi\condition.o
gcc.compile.c++ bin\extra\gcc\debug\threading-multi\exceptions.o

With msvc, it prints the filename separately on new line.

>>5. Just a note about the manual from someone who just spent 4 days
>>learning BB - BBv2 manual IS a lot better than v1 one, but the
>>organization is bit rough, it's hard to find specific things in it, so
>>you end up clicking through all the pages each time you need a specific
>>thing. You can't just hop in there to look up a single thing, you'd have
>>to read the entire manual in detail (at least once) to get the features
>>overview ...
> Can you suggest the organization that would work better for you?

1. In the beginning of Tutorial, start out with something like is shown
on "Project Hiararchies" page - list all files, and their purposes in
order to build minimal project; currently the first Hello, world chapter
has no mention of project-root.jam, so the reader is unable to create a
hello-world sample before he reads 4 more chapters.

2. Moving on from 1., list the purposes and functions different files in
the hierarchy have; I'v used BB now for about a week, and I'm still
confused between Jamfile, project-root.jam, site-config.jam,
user-config.jam and custom .jam files, e.g. what can I do in each of them.

3. Then list target types (exe, lib, more?); the syntax for describing a
target includes many fields (4 I think?), separated by :'s; describe
each fields purpose, and add a complete list of values that can be
placed in each field; for example, SOURCES field can also contain
references to libraries, which wasn't intuitive at first.

4. Using the title "pre-built targets" isn't intuitivly refering to
external libraries, I would suggest titling it as "Linking against
external libraries".

5. Projects, why, how. Personally I'm still confused between project
"requirements" and "usage-requirements"; I was unable to specify both.
For example, I'm keeping Boost libraries sources in my code tree, so I
have something like this:
local BOOST_ROOT ;
project boost
: requirements <include>$(BOOST_ROOT)
<threading>multi <define>BOOST_ALL_DYN_LINK=1
lib boost_thread
: : <include>$(BOOST_ROOT) <threading>multi
As you notice, I had to use <include>$(BOOST_ROOT) twice, and I still
haven't figured out why...

6. Command-line arguments full reference - currently all command-line
arguments are spread across the manual. You go briefly over command-line
args in Chapter 23, subsection "Command line" - but how does this fit
under "Detailed Rerefence" heading?

... Adding custom command-line arguments. Requesting specific compiler
version from commandline (bjam gcc-4.0)? Requesting custom
compile-command from commandline (bjam gcc="distcc g++-4.0" or bjam
gcc="colorgcc") ? Setting variables from commandline (bjam
sBOOST_ROOT=c:\boost - worked with BBv1, doesn't with BBv2 ?) ...

7. Writing custom targets (I think I'm refering to "rules" actually
here) - e.g. 'install' rule, which should copy files to system. Speaking
of which - I don't see any reference of such commands, e.g. FileClone,
SymLink, MkDir etc - in the manual.

8. Variables, their usage; local, global variables; accessing variables
cross Jamfiles (again from the above example, I'm unable to access
BOOST_ROOT variable from anywhere else except the Jamfile that declared
it, even with the 'local' keyword dropped from variale declaration).

Overall, if you look at the manual index we currently see:
* Tutorial
* User documentation
* Extended Manual
* Detailed Reference

In tutorial section, it's normal to leave out feature listings, and
focus on getting minimal examples running; altough I would recommend
starting out with a full example (including all required files), and
then explaining it line-by line, instead of showing snippets of code in
each page.

What exactly is the difference between UserDoc, ExtMan and DetRef ?
Which one should I search if I want to do X ? Or Y ?

What about hierarchy like this:

1. Getting Started
[ includes installation and tutorial, with 1-2 small, but complete
examples (points 1. and 2.) ]
2. Writing Jamfiles
[ includes detailed reference of what you can do with Jamfiles, e.g
targets, variables, dependencies, projects; starting simple, moving
towards more complex things (3, 4, 5) ]
3. Invoking Bjam
[ includes detailed reference on command-line arguments, how bjam
scans Jamfiles in folders; how it works to achieve targets;
multi-threaded compilations; what other black magic can one do from
commandline (overriding compile-commands, etc) (6) ]
4. Extending Boost.Build
[ includes overview of the tools/v2/ folder's contents; when/how to
write custom jam code - e.g. new toolsets, OS features, custom
targets (QT's uic / moc are good examples for this) (7, 8) ]
5. Frequently Asked Questions
[ no changes needed ]

Another thing that I was unable to find in this manual was actual Jam
language reference - had to do some googling around to find something on
it; maybe there was a link somewhere in the manual, but I couldn't find
it; anyway, shouldn't a build-system manual also include reference
manual of the actual language used to extend the build system? External
link would be sufficient.



Boost-Build list run by bdawes at, david.abrahams at, gregod at, cpdaniel at, john at