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

From: Rene Rivera (grafik.list_at_[hidden])
Date: 2003-11-19 10:51:14

[2003-11-19] Beman Dawes wrote:

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

I've been running stage builds for a while now and I haven't seen that
(trying another one now). So it's something new in date-time.

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

The only control we have for that is the debug output level of bjam. It
defaults to 1, setting it 0 would remove all the "progress" messages so we
could make 0 the default. But I don't think we really want to... As a user
if I'm building I'd like to get some feedback that the building is doing
something, otherwise I might wonder if the build is caught in an infinite
loop and I should abort it ;-)

>It would also be nice to document what this output 
>looking like on a successful run to confirm to users that all is well.

OK, will add something about the output.

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

Yes it would be preferable, but not sure if it's possible. I can certainly
put code in there that given the toolsets they specified sets the variants
to build. But the problem is that there is only one set of variants, so if
you specify more than one toolset the variants for one might not be what you
want for the others. Or we can make building the additional static versions
the default, but that's more compiling.

As for docs, the best I could probably do is to point them to the relevant
section in the Boost.Build docs about specifying variants, with a short
intro before that.

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

There is a short explanation of copying the headers files, and where they
get copied to, right before #5 (top of Build and Install section). Other
than what you mention below, is there more that should be said?

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

I thought about adding such a section, but the number of "this is how you
use your compiler" instructions I would have to write scared me off. Do we
really want to instruct users on the use of their tools? After all we have
enough problems keeping the docs for what we write up to date.

Would it be enough to add short explanation to the effect of "you should add
the lib and include dirs to your tools"?

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

It's what I would expect, and it's what other library products do :-)

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

The usual way I've seen that done is with environment variables.

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

It can support (2) in that one can copy the libs and includes where one
wants, and one could point the the stage (or install) to any directory using
the path options.

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

Any suggestions?

For Windows we could probably default to C:\Boost\build, or something such.
But for unix I can't think of an easy outside default.

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

Good idea, will add comments for that.

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

Thanks :-)

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

Possibly... More steps for the distribution wizard ;-) Or perhaps that is
something others could contribute with.

-- grafik - Don't Assume Anything
-- rrivera (at) acm.org - grafik (at) redshift-software.com
-- 102708583 (at) icq