Re: [boost] Getting started build section

Subject: Re: [boost] Getting started build section
From: David Abrahams (dave_at_[hidden])
Date: 2008-11-06 14:26:29

on Thu Nov 06 2008, Vladimir Prus <ghost-AT-cs.msu.su> wrote:

> On Thursday 06 November 2008 19:55:33 David Abrahams wrote:
>> 
>> on Thu Nov 06 2008, Vladimir Prus <ghost-AT-cs.msu.su> wrote:
>> 
>> > On Thursday 06 November 2008 17:38:02 David Abrahams wrote:
>> >> 
>> >> on Thu Nov 06 2008, Vladimir Prus <ghost-AT-cs.msu.su> wrote:
>> >> 
>> >> > Dave,
>> >> > I am reading the getting started guide, and think some of the build
>> >> > instructions can be improved. I can do this myself, if we agree on
>> >> > the nature of the changes.
>> >> >
>> >> > For reference, I'm looking at:
>> >> >
>> >> > 	http://www.boost.org/doc/libs/1_37_0/more/getting_started/windows.html> >
>> >> > 5   Prepare to Use a Boost Library Binary
>> >> >
>> >> > 	I think the section title is too long-winded. "Prepare" does not even
>> >> > 	suggest any kind of building.  And of course, we have many libraries,
>> >> > 	so saying "a ... Binary" is not accurate.
>> >> > 	Would "Building Library Binaries" be more to the point?
>> >> 
>> >> No.  You may have used the installer.
>> >
>> > And what about "a ... Binary" being not accurate, given that there's
>> > lots of library binaries?
>> 
>> It *is* accurate.  We're working on a single example, and to build/run
>> that example you need a library binary, and this section describes what
>> you need to do to prepare to use it.
>
> Maybe it's just me, but when I start doing anything with a new tool or library,
> the first thing I do is to build all of it. Cherry-picking specific libraries
> is less common use-case.

Even if I were to stipulate to that assertion, none of it bears on the
accuracy of "a ... Binary" in the context of this tutorial.

Every mind-numbingly-long step in a tutorial has a serious negative
impact on learnability.  Building all of Boost is really slow.  Even
downloading all the binaries with the installer can be slow.

>> People who know they don't need binaries based on earlier sections of
>> the document shouldn't be instructed to build and install them from the
>> beginning.
>
> Oh, you mean that the first section of the document say this:
>
> 	To complete this tutorial, you'll need to at least install the 
> 	Static Multithreaded variants of the Boost.Regex binaries when 
> 	given the option.

Yes.

> I think there are some problems with the text in section 5, still:
>
> 	- It demands that you install *all* variants of Boost.Regex, while
> 	the above say only one variant is necessary.

Good point.

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

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

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

>> >> > 5.2.3   Select a Build Directory
>> >> > Boost.Build will place all intermediate files it generates while building into
>> >> > the build directory. If your Boost root directory is writable, this step isn't
>> >> > strictly
>> >> > necessary: by default Boost.Build will create a bin.v2/ subdirectory for that 
>> >> > purpose in your current working directory.
>> >> >
>> >> 
>> >> > 	I suggest that this section be dropped. In describes a non-mainstream usage
>> >> >       that is better be describe elsewhere. 
>> >> 
>> >> Maybe, but the thing I worry about is that a suitable "elsewhere"
>> >> doesn't exist.  People seem to expect the GSG to tell them all sorts of
>> >> things that perhaps should be in a Boost.Build guide.  I think that's
>> >> because they are having a hard time making the jump to that documentation.
>> >
>> > If you add a link to Boost.Build command line, that's where --build-dir is
>> > documented:
>> >
>> > 	http://www.boost.org/boost-build2/doc/html/bbv2/advanced/invocation.html> 
>> IMO the description of build-dir there is unsuitable for a beginning
>> user who doesn't know what these terms really mean:
>> 
>>     "project roots"
>>     "Jamroot files"
>>     "declare project name" 
>>     "the project name specified in Jamroot" 
>>     "build dir specified in Jamroot"
>> 
>> That might be OK if --build-dir is a truly esoteric option that almost nobody
>> needs.  Now that we put everything under bin.v2, that might be true.  It
>> certainly wasn't true with BBv1, where targets were always built inside
>> project directories by default.  I'd like to hear some other peoples'
>> opinions on whether it's still relevant.
>
> FWIW, I've filed an issue to improve --build-dir docs.

OK, still waiting to hear from others before removing it from the GSG.

>> >> > 	If the summary does not include any failed targets, your build is successful,
>> >> > 	and the library binaries can be found in the 'stage' directory. 
>> >> 
>> >> "the 'stage' directory" is too imprecise.  How will the reader find it?
>> >
>> > If no --stagedir option is given, the 'stage' directory is placed in
>> > boost source root and named 'stage', exactly. That's what I meant. In
>> > fact, this post is prompted by user report on boost-build that say we
>> > don't document --stagedir.  The --stagedir is an option defined in
>> > Boost Jamroot, not in Boost.Build, so probably should be
>> > documented. Though relying on bjam --help output may be acceptable,
>> > too.
>> 
>> --stagedir and --build-dir are very similar.  We should probably make the
>> same decision about documenting both of them.
>
> I agree with Steven, --stagedir controls where the build results go, so users
> need to know about it. --build-dir controls where intermediate products go,
> so it's rarely used option.

People need to know how to get rid of those intermediate products.
They're huge.

>> > Ok, not "lack", then:
>> >
>> > 	A the beginning of the build, you will be informed what functionality
>> >  	of C++ Boost libraries is disabled because the required third party
>> >  	libraries could not be found.
>> 
>> Personally I don't see how this improves on the text that I already
>> wrote covering this topic.  Nobody has reported confusion about that
>> text.
>
> 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.

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