Re: [boost] Getting started guide updates

Subject: Re: [boost] Getting started guide updates
From: Steve M. Robbins (steve_at_[hidden])
Date: 2011-03-20 09:14:11

Hi Vladimir,

The document looks really good!

On Sun, Mar 20, 2011 at 01:48:41PM +0300, Vladimir Prus wrote:

> - To make the "bootstrap + bjam" process the only documented one, since it
> turns out to be fairly painless on Unix

Yes, bootstrap.sh has really improved building boost.

> The result can be previewed at http://lvk.cs.msu.su/~ghost/unix-variants.pdf ,
> see section 5. I would appreciate if folks take a look and suggest whether it
> can be improved further.

Reading through Section 5.1, I stumbled over specifying "toolset=gcc-4.5",
whereas the C++ compiler name is really "g++-4.5".  The first line in
this section mentions "... default compiler, typically g++" whereas the
4th line says "... command gcc-4.5 works".  But gcc-4.5 is not the C++
compiler, it is g++-4.5.  Is it true that bjam is smart enough to
use g++-4.5 in this case?  If so, it's worth clarifying that I
wouldn't have to edit project-config.jam in this case.

Small comment for Section 5.3: "--build-dir, option that specifies
where intermediate build products should be placed".  It controls also
where the final libraries are placed, I imagine.  Perhaps drop
"intermediate".  Also, you don't need a comma after --build-dir.

Overall, this is a really good introduction for someone using the
source distribution of Boost.  Footnote 1 invites Boost packagers to
help ensure the instructions can be used with their packages.
However, the document intertwines using Boost to build a program
(Sections 4 and 6) with description of the source layout and building
Boost itself (Sections 2, 3, 5).  This is very natural for
someone who just downloaded the boost sources but is not the
emphasis I'd place if I were writing this for Debian.

For a Debian user getting started with Boost, I would replace "1 Get
Boost" with a description of the Debian package structure.  I would
need only the "Header Organization" box from Section 2.  I would
remove Section 5 entirely.  In Section 6 I would emphasize the
"layout=system" library naming and mention the fully-decorated
naming in passing.  And, of course, the -I and -L options are
unnecessary as is setting LD_LIBRARY_PATH.  Etc.

Is your goal that a single document encompass the source distribution
and, say, the Debian distribution?

Cheers,
-Steve