Re: [BBv2 docs editorial] Installation

From: Reece Dunn (msclrhd_at_[hidden])
Date: 2005-09-20 16:13:57

Andrey Melnikov wrote:
> David Abrahams wrote:
> 
>>>Chapter 22. Installation
>>>
>>>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.

You either need to place bjam in a directory that you can do:

d:/boost/bin/bjam.exe ...

or have it in a directory listed in PATH and do:

bjam ...

To me, the second is far easier to type and remember.

> 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 think Rene's installer adds bjam and sets the PATH variable correctly :).

>>>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 like the idea of a troubleshooting guide in general (including 
installation) complementing the FAQ. You can then mention in the 
introduction something like "If you encounter any problems, see the 
Troubleshooting Guide or try the mailing list."

This would then cover things like "I get a 'toolset not found' error --> 
ensure that you have setup user-config.jam 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? 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.

Indeed. An example would help here, such as configuring python support.

Also, I remember I had issues running doxygen under cygwin because of 
Windows and cygwin paths. This was fixed by using the recommended 
version of xsltproc, so this should be made clear (perhapse in the 
troubleshooting section) to help other users.

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

Replace this line with "If you have taken a copy of Boost from the CVS 
source control repository, it is necessary to rebuild bjam."

>>>The CVS version of Boost.Build requires the CVS version of Boost.Jam.

Should this be more generic like "Boost.Build requires an equal or 
higher version of Boost.Jam in order to run."

> "CVS state" again. We definitely need to look at that discussion.

"Boost's CVS state" can be confusing to first time users, especially if 
they don't know what CVS is ("Is CVS a part of Boost?").

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

Or "c:/cygwin/bin" :). Rene's Windows installer adds other tools like 
doxygen and xsltproc so you can use BoostBook without cygwin (although, 
I don't think it adds the DocBook files).

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

How about the last line being: "If you have the full Boost distribution, 
the tools/build/jam_src subdirectory allows you to build the Boost.Jam 
executable.".

- Reece