Re: [BBv2 docs editorial] Installation

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-20 16:59:22

Andrey Melnikov <melnikov_at_[hidden]> writes:

> David Abrahams wrote:
>> Most of this looks good to me, because it is basically unchanged from
>> my last set of edits. Just a few notes...
>> 
>> 
>>>Chapter 22. Installation
>>>
>>>This section describes how to install Boost.Build from a released 
>>>Boost source distribution or CVS image. ^[2] All paths are given
>>>relative to the Boost.Build v2 root directory, which is located in the
>>>tools/build/v2 subdirectory of a full Boost distribution. ^[3]
>> 
>> 
>> Replace the part after "which is" with:
>> 
>> the top directory of a separate Boost.Build v2 installation or
>> the tools/build/v2 subdirectory of a full Boost libraries source
>> tree.
>> 
>>> 1. Boost.Build uses Boost.Jam, an extension of the Perforce Jam
>>> portable make replacement. The recommended way to get Boost.Jam is
>>> to download a prebuilt executable from SourceForge. If a prebuilt
>>> executable is not provided for your platform or you are using
>>> Boost's sources in an unreleased state, it may be necessary to 
>>> build bjam from sources included in the Boost source tree.
>> 
>> 
>> That last sentence should be broken into a separate paragraph under
>> this same numbered item:
>> 
>> If a prebuilt executable is not provided for your platform, you
>> will have to build bjam from sources included in the Boost
>> source tree. You may also need to rebuild bjam if you are using
>> the Boost libraries' sources in an unreleased state, since the
>> build instructions may depend on bjam features that are newer
>> than any prebuilt executable. Instructions for rebuilding bjam
>> can be found at
>> http://www.boost.org/tools/build/jam_src/index.html#building_bjam
>
> I remember a long discussion about this "unreleased state" paragraph. 
> But I cannot find it in Gmane. We should use the results of that 
> discussion.

Google 

"unreleased state" melnikov

yields one hit:

http://lists.boost.org/Archives/boost/2005/07/89714.php

> Also look at my attempts at http://tinyurl.com/bcgwf ("Getting up and 
> running...") 

Windows-centric, but I guess that's okay.

> and at http://tinyurl.com/7d7xr

I don't know if that's much help; it poses more questions than it
answers!

>>> 2. To install Boost.Jam, copy the executable, called bjam or bjam.exe
>>> to a location accessible in your PATH. 
>
> It isn't required. It is recommended, it is convenient, but it isn't a 
> requirement.

The way I see it we are dealing with two kinds of people. The first
have never used command-line tools, and since our instructions are
going to tell them to invoke bjam without qualification, it had better
be in the PATH. Everyone else will understand that they can probably
get away with using a long path to the executable when invoking it.

> Also we should point that on Windows it's a bad idea to copy anything to 
> the system folders. By default only the system folders are in PATH, so 
> we should recommend a folder structure and give some instructions to 
> change the PATH on Windows.

I am forced to agree, even though I don't like it :(

> There are several good layouts like \dev\bin\ , \dev\boost\bin, 
> \boost\bin (the libraries will go to \boost\lib) and maybe others.
>
>>> Go to the 
>>> Boost.Build root directory and run bjam --version. You should see:
>>> 
>>> Boost.Build V2 (Milestone N)
>>> Boost.Jam xx.xx.xx 
>>>
>>> where N is the version of Boost.Build you're using.
>
> IMO we can omit this step at all. Or we can add it to a more
> comprehensive Installation Troubleshooting guide. We should follow
> the 80/20 rule - 80% of users will need only 20% of the
> documentation.

I understand where you're coming from, but isn't it useful as a sanity
check? People like to have the experience that they did the last step
correctly.

>>> 3. Configure Boost.Build to recognize the build resources (such as
>>> compilers and libraries) you have installed on your system. Open
>>> the user-config.jam file in the Boost.Build root directory and
>>> follow the instructions there to describe your toolsets and
>>> libraries, and, if necessary, where they are located.
>
> How a user will find out if it's necessary or not? 

I read this as saying it would be clear from the instructions in the
user-config.jam file. However, if you find this confusing it would
probably be best to drop any reference to describing where they are
located. If they need to do it, it _should_ be clear from the
user-config.jam instructions and there's no need to say so ahead of
time.

> Also, at this point the user doesn't know what are toolsets and
> projects. So we should restructure the documentation and put an
> introductory chapter before the Installation chapter. It's
> impossible to install BB without understanding the toolsets.

I totally agree. We need a section early on that describes the
overall structure and main concepts of Boost.Build. That will help to
address troy d. straszheim's sense of being "at sea" with the architecture.

>>> 4. You should now be able to go to the example/hello/ directory and
>>> run bjam there. A simple application will be built. You can also
>>> play with other projects in the example/ directory.
>>>
>>>If you are using Boost's CVS state, be sure to rebuild bjam even if
>>>you have a previous version. The CVS version of Boost.Build requires
>>>the CVS version of Boost.Jam.
>
> "CVS state" again. We definitely need to look at that discussion.

Not sure exactly what you're referring to. I recognize it as an
unfortunate complication, but specifics would help.

>>>When bjam is invoked, it always needs to be able to find the
>>>Boost.Build root directory, where the interpreted source code of
>>>Boost.Build is located. There are two ways to tell bjam about the root
>>>directory:
>>>
>>> ● Set the environment variable BOOST_BUILD_PATH to the absolute path
>>> of the Boost.Build root directory.
>>> ● At the root directory of your project 
>>> or in any of its parent directories, create a file called 
>> 
>> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> italicize this
>> 
>>> boost-build.jam, with a single
>>> line:
>>> 
>>> boost-build /path/to/boost.build ;
>
> I remember a discussion about this. Where is it? What is the best way to 
> search Boost mail archives?

try various approaches: google, gmane, ASPN, ...

That's what I do.

>> Add
>> We recommend this approach: once you've set up a boost-build.jam
>> file in a parent directory of the one in which you do most of
>> your development, it should almost never be necessary to think
>> about it again, and you won't be cluttering your environment
>> with settings specific to a single tool.
>
> If a user creates c:\boost_build, puts bjam.exe there and adds 
> c:\boost_build to the path, it will be "cluttering your environment
> with settings specific to a single tool" too. So we should discourage 
> such policy and recommend to use a common folder like \dev\bin for bjam 
> and other tools like doxygen etc. IMO it's a good practice.
>
>> Then consider swapping the two bullets.
>
> I agree. We can even recommend the environment as a last resort only if 
> it's impossible to use the files.
>
>>>N.B. When bjam is invoked from anywhere in the Boost directory tree 
>>>other than the Boost.Build root and its subdirectories, Boost.Build v1
>>>is used by default. To override the default and use Boost.Build v2,
>>>you have to add the --v2 command line option to all bjam invocations.
>
> This is valid only if Boost.Build was downloaded as a part of Boost. 
> This paragraph isn't applicable for the standalone version of BB. Are 
> there other issues related to the difference between the two distributions?

This whole thing will go away once we retire v1, so I don't think
fixing it is urgent.

>>>━━━━━━━━━━━━
>>>
>>>^[2] Note that packages prepared for Unix/Linux systems usually make
>>>their own choices about where to put things and even which parts of
>>>Boost to include. When we say “released source distribution” we mean a
>>>distribution of Boost as released on its SourceForge project page.
>>>
>>>^[3] The Boost.Build subset of boost is also distributed separately,
>> 
>> strike this--------^^^^
>> 
>>>for those who are only interested in getting a build tool. The
>>>top-level directory of a Boost.Build distribution contains all the
>>>subdirectories of the tools/build/v2 subdirectory from a full Boost
>>>distribution, so it is itself a valid Boost.Build root directory. It
>>>also contains the tools/build/jam_src subdirectory of a full Boost
>>>distribution, so you can rebuild Boost.Jam from source.
>> 
>
> The last sentense sounds like you are unable to rebuild Boost.Jam if you 
> have downloaded complete Boost tree.

Please suggest a fix.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com