Re: [boost] [1.36.0] Getting Started changes (ticket #1744 plus other fixes)

From: David Abrahams (dave_at_[hidden])
Date: 2008-08-10 05:02:10

on Sat Aug 09 2008, Beman Dawes <bdawes-AT-acm.org> wrote:

> Before we can ship 1.36.0, some "Getting Started" documentation
> changes are needed. These changes are the only thing preventing 1.36
> from shipping. Enough said.

I'm very glad to make the changes provided we can figure out what they
are.  That is something I've been with concerned with for weeks.

> * Section 1, Get Boost, both Windows and Unix Variants: need to begin
> with a suggestion that users first check for the availability of
> platform specific installers, linked to the correct URL.
>
> [Rationale: the platform specific installers are the preferred way for
> users to install Boost if their platform is one of those supported.]
>
> Questions for Doug: Are the platform specific installers to be hosted
> on SourceForge as part of the "boost" package? What is the initial set
> of platform specific installers that will be provided for 1.36?

Waiting for someone to tell me what the URLs are.

> * Section 1, Get Boost, Windows: current text needs to be updated if
> Boost Consulting 

ahem. Boostpro Computing :)

> is not going to be also providing installers.
>
> [Rationale: The current wording is very specific, thus needs careful
> adjustment to match reality.]

We probably will continue to provide free installers, but they may be
the same as the Boost ones.  In that case, it doesn't make much sense to
point people at Boostpro in the Boost documentation.

> * New section, before the current section 1:  Suggest visiting
> http://www.boost.org/doc/libs/1_35_0/more/getting_started/index.html
> to see if there has been a "Getting Started" documentation update.

Good idea.  We should make the URL shorter though ;-)

> [Rationale: that way we can push out better docs as soon as available,
> instead of having to wait for the next release.]
>
> * Section 5.2.4, Invoke bjam, both Windows and Unix Variants: needs to
> say what library variants (static/dynamic, debug/release,
> multi-threaded/not) are build by default.
>
> [Rationale: (1) It is too late to change the default behavior for
> 1.36.0. (2) The worst problem with the new defaults isn't the specific
> choices, but that those choices aren't documented, 

I'm not so sure.  While they may have other benefits, the new defaults
are going to make the getting started instructions more complicated.

> and (3) it needs to be crystal clear how to build the full set.]

Yeah, but that's not nearly enough.  We also need to make sure that the
instructions for building the examples in the getting started guide are
all correct, including all their command-line variations, for all
platforms, and don't leave out "silly" details like the potential need
to set LD_LIBRARY_PATH (or whatever other platform-specific environment
variable may be required) now that we are no longer building static
libraries by default.  Testing these instructions for all platforms is a
large job, and I'm not in a position to do it by myself.

In case anyone's wondering why I didn't "simply" go ahead and update the
GSG when I discovered that the default build choices had broken it,
that's why.

> * Section 5.2.4, Invoke bjam, both Windows and Unix Variants: after
> the current contents, needs to give the exact command line for
> building all library variants.
>
> [Rationale: resolves (3) in prior item.]
>
> Since Dave is on vacation, I'm not sure he will be able to make these
> changes. If he can't make them, I'll give it a try.

I'm somewhat available, but like I said, the changes to the defaults
have made things a lot more problematic than they used to be, so we'll
need to get lots of people to put attention on this.

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com