Re: [boost] Getting started build section

Subject: Re: [boost] Getting started build section
From: Vladimir Prus (vladimir_at_[hidden])
Date: 2008-11-06 14:44:54

David Abrahams wrote:

>> - Many users will jump straight to section 5 (e.g. because they
>> just want to get Boost libraries, and are not interested in
>> preceding sections).
> 
> I don't believe you, but if so, they're in the wrong place.  This is a
> getting started guide, not a "how to build boost" guide.

Oh, probably I've misunderstood the purpose of this text :-(
So, you say we don't have any direct instructions how, given boost source,
to end up with binaries for all libraries, and getting started is not meant
to incorporate such instructions? Should we a separate document, then?

>>       Or even if they read section 1, at this point
>> they already forgotten that Boost.Regex is going to be used in
>> example. And they were not instructed, previously, to run the
>> installer. So, this passage can be interpreted as asking the user to
>> run the installer twice -- which is how I've interpreted it.
> 
> It's simple.  The passage says to re-run the installer if, the first
> time, you didn't select the options needed for the upcoming step.  I 
> don't understand what you're objecting to.

There's no "first time" previously in the document -- this the first time
user is asked to run the installer.

>>> > I would not try, actually. For most users, bjam and Boost.Build are not
>>> > independent projects, so saying that Boost.Build is invoked by typing
>>> > bjam on the command line seems reasonable.
>>> 
>>> I was trying to make the distinction and relationship between bjam and
>>> Boost.Build a little clearer.  I think you may be forgetting the many
>>> people who used to say, "I read all through the bjam documentation but I
>>> can't figure out how to <do something that's Boost.Build functionality>"
>>
>> I think this problem better solved by giving pointers to Boost.Build
>> docs, and generally stressing that "bjam" is just the command-line
>> name of Boost.Build.
> 
> I think you're forgetting all those people who pick it up and try to use
> it as "a better Perforce jam," expecting Boost.Build features and
> command-line options to be there.  It can't be used as instructed
> without the BB sources, and that's very different from other binary
> build tools.  I don't see a great advantage in changing this
> already-short text and the possible downsides are unattractive to me.

Getting started clearly cannot accurately explain the relation between
bjam and Boost.Build, so all that's needed is a sentence to get users
going without creating false impressions. I think "bjam drives Boost.Build"
is factually incorrect. Possible different wordings are:

        "Boost.Build is invoked by typing 'bjam' on the command line",

or

        "bjam is the underlying build engine for Boost.Build"

or something like that. Of course, this is not the most important issue.

>> I'd personally be happy with any wording for this section that:
>>
>> 1. Emphasized how user can know if the build is successful, and how to
>> diagnose the problems. E.g. many users, on IRC, fail to report actual
>> compiler errors, or compiler commands and instead report the "failed XXX"
>> message from Boost.Build. Also, where to look for results of the build.
>>
>> 2. Emphasizes that if there are no errors, the only thing user might
>> care about is those configuration notices. The syntax of:
>>
>> toolset-name.c++ long/path/to/file/being/built
>>
>> is something, IMO, that need to be described at all.
> 
> I disagree strongly unless we suppress those messages.  People have
> repeatedly complained that they don't understand what it means when the
> tool spits out these messages.

Ok, I'm don't very much mind about leaving it, but it would be great if (1)
and (2) are addressed.

Where do we go from here? We've agreed on some points, and disagreed on others.
Are you planning to act on the agreed points, or want me to? I realize you
might not have time right away, but would be great to have this cleaned up
for the next release.

Thanks,
Volodya