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