Re: [boost] Getting started build section

Subject: Re: [boost] Getting started build section
From: Vladimir Prus (ghost_at_[hidden])
Date: 2008-11-06 10:58:29

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?

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

> 
> >
> > 5.2   Or, Build Binaries From Source
> > If you're using an earlier version of Visual C++, or a compiler from another vendor, 
> > you'll need to use Boost.Build to create your own binaries.
> >
> > 	Earlier than what? No version of Visual C++ is mentioned in the preceding
> > text.
> 
> Good point; 
> 
> >
> > Boost.Build is a text-based system for developing, testing, and installing 
> > software. To use it, you'll need an executable called bjam.
> >
> > 5.2.1   Get bjam
> > bjam is the command-line tool that drives the Boost Build system. To build Boost
> > binaries,
> > you'll invoke bjam from the Boost root.
> >
> >
> > 	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. 

> 
> > First, find the toolset corresponding to your compiler in the following table.
> >
> > 	The kylix should be removed from the table. 
> 
> Have we dropped it?

Years ago (the product is dead, nobody used the Boost.Build support either)

> 
> >       "FreeScale" should be "Freescale".
> 
> Good point; 
> 
> > 	This should also link to the list of toolchains in Boost.Build docs.
> 
> Exact link, please.

http://www.boost.org/boost-build2/doc/html/bbv2/reference/tools.html

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

> 
> >       FWIW, the case of building source straight
> > 	from CD does not seem reasonable, since with large number of headers the
> > 	performance will be horrible. 
> 
> True.
> 
> >       Likewise, building from a network drive is not
> > 	a good idea. 
> 
> Why?  I know companies where people do that successfully.

I presume this depends on exact network infrastructure and usage scenarios,
but a couple of couple of 8-core servers compiling from network disk can
bring down a decent storage solution quite easily.

> >       So, copying source to a local drive and building from there is
> > 	the best thing.
> >
> > bjam --build-dir=build-directory --toolset=toolset-name --build-type=complete stage
> >
> > 	Per above, I suggest we drop --build-dir. --toolset= should
> > 	become toolset=
> 
> Sorry, I thought I had changed the --toolset= business already.
> 
> > 	This section should also link to Boost.Build doc section about command line
> > 	syntax.
> 
> Exact link, please.

http://www.boost.org/boost-build2/doc/html/bbv2/advanced/invocation.html

> 
> >
> > 5.3   Expected Build Output
> >
> > 	This section fails to mention the single most important point -- that
> > 	the libraries are produced, and where they are produced. In fact, I
> > 	don't see an obvious purpose of this section to the user -- it just
> > 	says "oh, and those kinds of message appear". 
> 
> The purpose is to help all the people who have told us over the years
> that they get gobs of messages and they don't know how to tell whether
> everything worked or not.  People have been confused by the ICU and
> Python-related messages.  People have been confused by the number of
> targets built/skipped messages.  People have been confused and upset by
> the long pathnames they are seeing; at least telling them that they're
> normal eliminates much of that effect.
> 
> > 	This section fails to explain what is produced as result -- like that
> > 	libraries will be placed in the 'stage' directory.
> 
> That's certainly important.
> 
> > 	I'd suggest rewording the section like this:
> >
> > 	5.3 Interpreting the results.
> 
> I like the new section title.
> 
> > 	The build process produces a large number of output during compilation,
> > 	including diagnostic messages from Boost.Build, names of files being
> > 	compiled and messages from the compiler. A summary is printed at the end.
> 
> I would want to clarify "a summary is printed at the end" so the reader
> doesn't think we mean that we summarize these messages at the end of the
> document she is reading.
> 
> > 	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.

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

> >       You might want to check that you don't require the disabled
> > 	functionality, and perform additional configuration (see individual libraries
> > 	documentation).
> >
> > 	
> > If it seems like the build system can't find your compiler and/or linker, 
> > consider setting up a user-config.jam file as described in the Boost.Build
> > documentation.
> 
> Exact link please.

http://www.boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html

> 
> > 	This should have a link to Boost.Build section about configuration, not to the
> > top-level
> > 	docs.
> 
> I think you raise a number of good points above.  Certainly I welcome
> more participation from the Boost.Build team in ensuring a smooth
> Getting Started experience.  In particular, I think helping people
> transition from the GSG to the Boost.Build documentation is crucial.

I fully agree. Note that some of the links I gave above are to recently-updated
sections, meant to give a relatively complete instructions to somebody who just
wants to build boost with slightly custom settings.

- Volodya