[boost] Getting started build section

Subject: [boost] Getting started build section
From: Vladimir Prus (ghost_at_[hidden])
Date: 2008-11-06 04:53:34

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?

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.

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.
        

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. Besides, bjam does not really drives Boost.Build (just like my car does not
        drive me, usually).

First, find the toolset corresponding to your compiler in the following table.

        The kylix should be removed from the table. "FreeScale" should be "Freescale".
        This should also link to the list of toolchains in Boost.Build docs.

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. FWIW, the case of building source straight
        from CD does not seem reasonable, since with large number of headers the
        performance will be horrible. Likewise, building from a network drive is not
        a good idea. 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=
        This section should also link to Boost.Build doc section about command line
        syntax.

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

        This section fails to explain what is produced as result -- like that
        libraries will be placed in the 'stage' directory.

        I'd suggest rewording the section like this:

        5.3 Interpreting the results.

        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.

        If the summary does not include any failed targets, your build is successful,
        and the library binaries can be found in the 'stage' directory. 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. 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. 

        This should have a link to Boost.Build section about configuration, not to the top-level
        docs.

Comments?

- Volodya