Re: BBv1 / BBv2 thoughts/questions/comments

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
msvc.compile.c++ 
bin\extra\msvc-7.1\debug\threading-multi\read_write_mutex.obj
read_write_mutex.cpp
msvc.compile.c++ 
bin\extra\msvc-7.1\debug\threading-multi\recursive_mutex.obj
recursive_mutex.cpp

$ 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
: $(THREAD_SOURCES).cpp
: <define>BOOST_THREAD_BUILD_DLL=1
: : <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
* FAQ

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.

Alo