Re: [boost] Getting started build section

Subject: Re: [boost] Getting started build section
From: David Abrahams (dave_at_[hidden])
Date: 2008-11-11 03:25:02

on Thu Nov 06 2008, Vladimir Prus <vladimir-AT-codesourcery.com> wrote:

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

That's just not a goal of that document.

> Should we a separate document, then?

Not necessarily.  If only a small change is required in order to present
that information, it would be fine to add it.  However, I would not want
to do anything that would make it harder to use the GSG for its intended
purpose.  Also, note that everybody has his own pet "little thing" that
should be added to the GSG (how to compile 64-bit targets, how to turn
off library name gristing,...) so I have to be cautious even about
smallish changes, or the document will become too complex via accretion.

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

http://www.boost.org/doc/libs/1_37_0/more/getting_started/windows.html#get-boost
seems to give a pretty clear encouragement to do just that.

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

Fine, I'll take the latter, and delete "build" from "build engine" :-)

> Of course, this is not the most important issue.

No, it's not very important.

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

I agree that those are important.

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

I definitely don't have time right away, and I agree it should be done
for the next release.  Perhaps you could summarize our points of
agreement in a ticket?

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com