Re: [boost] Documentation for build+install for users.

From: Beman Dawes (bdawes_at_[hidden])
Date: 2003-11-19 08:40:47

At 12:53 AM 11/18/2003, Rene Rivera wrote:

 >I finally finished, yes it took a while but it's been busy, a "Getting
 >Started" document to guide users in building and installing Boost with 
the
 >new system. The document is in CVS as 
boost-root/more/getting_started.html
 >
 >Comments are welcome.

Looks nice! I gave a "stage" build a test drive, and turned up these 
issues:

* bjam: ...failed updating 2 targets...

There are also two "The system cannot find the file specified" messages in 
the body of the log information. Both date-time library related.

* For everyday use by users who don't care about how it all works under the 
hood, it would be better not to report details during the bjam run. Just 
the ... messages. It would also be nice to document what this output 
looking like on a successful run to confirm to users that all is well.

* The bjam run produced only mt and mt-gd library variants. It would be 
preferable if it produced the set of variants that is usual for the 
particular compiler. For example, VC++ users often use static linking, and 
that is the default for that compiler/linker. getting_started.html didn't 
seem to even mention how to instruct bjam to produce other variants.

* The document is entirely focused on the Boost libraries that require 
separate compilation. Need mention of what steps are required for 
header-only libraries.

* It seems there is a final step that is missing. "Connect the Boost 
headers and libraries to your compiler." Because the details are different 
for each compiler, a table might be the best presentation. For example, the 
entry for the VC++ 7.1 IDE might read:

   Start IDE. On "Tools" menu, select "Options...", then select "Projects", 
"VC++ Build", then in "Show directories for:", for both "Include files" and 
"Library files", click "New Line" button and add paths. Click "OK".

The entries for a lot of command line compilers would be simpler.

* There are two different ways I might want to use the Boost libraries on 
Windows:

(1) If I use only an IDE compiler/linker, placing the Boost libraries in a 
separate directory is probably OK, and may be what some users prefer.

(2) If I use the command line compiler, I'd prefer to set up Boost 
libraries so they will be found automatically. Essentially I consider them 
to be part of the default library set. I've always accomplished this by 
copying the files into the compiler's lib directory, but the details might 
vary from compiler to compiler.

I gather the new procedure can support either (1) or (2), but at first 
reading it wasn't 100% clear to me how best to accomplish (2).

* Wouldn't it be better to default --builddir= to someplace out of the 
distribution tree?

* Every option except "-sTOOLS" is prefixed with "--". You might add "Note 
single hyphen." or similar to -sTOOLS, so it won't seem so much like a 
typo.

Nice work! getting_started.html is a big step forward.

That being said, I'm wondering if we should at least consider providing 
prebuilt libraries for some of the more common compilers?

--Beman