Re: [boost] Getting started build section

Subject: Re: [boost] Getting started build section
From: Vladimir Prus (ghost_at_[hidden])
Date: 2008-11-06 13:14:55

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.

> >> > The installers supplied by BoostPro Computing will download and
> >> > install pre-compiled binaries into the lib\ subdirectory of the
> >> > boost root, typically C:\Program Files\boost\boost_1_37_0\lib\. If
> >> > you installed all variants of the Boost.Regex binary, you're done
> >> > with this step. Otherwise, please run the installer again and
> >> > install them now.
> >> >
> >> > 	I can't understand what the second sentence say. If installer
> >> > allows to install only some variants of Boost.Regex, then
> >> > documentation should to request the user to run the installer
> >> > again, and install the remaining ones. I can't fix this text
> >> > without knowing what it means.
> >> 
> >> Umm, that's exactly what it means.  There's nothing to fix.
> >
> > If you want to say that users should always install all variants of
> > Boost.Regex, please say so. 
> 
> That's not what I want to say.
> 
> > Instructing the user to run installer again, and then select all
> > variants, seems to have no benefits over selecting all variants in the
> > first place. Am I missing something?
> 
> 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.

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

> 
> >> > The last sentence of 5.2 and the first sentence of 5.2.1 essentially duplicate
> >> > each
> >> > 	other. 
> >> 
> >> No; 5.2.1 makes it clear you'll be using bjam from the command-line and
> >> explains its role in the process.  For example, it's not just something
> >> that sets up your environment or post-processes library files.
> >> 
> >> > Besides, bjam does not really drives Boost.Build (just like my car
> >> > does not drive me, usually).
> >> 
> >> Umm, right.  Lots of terms we use in CS don't map meaningfully onto
> >> everyday objects.  How would you characterize bjam's role in the system?
> >
> > 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.

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

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

> 
> >> >       Otherwise,
> >> > 	you can browse the output to see which libraries failed to build, and which
> >> > 	compile errors were produced.  You can also run bjam again, with the same
> >> > 	option, to try compiling the failed files again.
> >> >
> >> > 	A the beginning of the build, you will be informed what functionality
> >> > 	of C++ Boost libraries is disabled because of lack of required third party
> >> > 	libraries. 
> >> 
> >> I think lacking a 3rd-party library is not the only reason the functionality
> >> might be disabled.  Don't you need some environment variables set for
> >> ICU, or something?
> >
> > 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.

- Volodya