Re: [jamboost] Re: [BBv2 docs editorial] Installation

From: Andrey Melnikov (melnikov_at_[hidden])
Date: 2005-09-20 18:47:44

David Abrahams wrote:
> 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
> 

So the final version was:

>Andrey Melnikov <melnikov_at_[hidden]> writes:
>> ----
>> We compiled a version of bjam executable (bjam.exe or bjam) for you, 
>and
>> tested it with Boost release. We strongly recommend you simply to
>> download prebuilt bjam for your platform:
>> - <a>windows</a>
>> - <a>linux</a>
>> - <a>freebsd</a>
>> - <a>solaris</a>
>> - <a>Mac OS X</a>
>
>> If your platform isn't in the list, or if you downloaded the latest
>> Boost beta sources from CVS instead of official Boost release,
>> <a>installation guide</a> describes how to compile bjam from sources
>> located in tools/build/jam_src by running build.bat or build.sh.
>
>> Latest Boost sources may fail to compile with prebuilt bjam because
>> prebuilt version could become incompatible with Boost *.jam files.
>> -----
>
>You are missing a bunch of articles, and personally, I don't like the
>style of "We compiled ... for you." It seems that it would better to
>say that using the prebuilt bjam executable, if there is one available,

And then I posted a flamy reply and the discussion was over.

The opened issues are:
- "We compiled a version for you"
- English grammar is poor

Can someone fix the grammar?

>>Also look at my attempts at http://tinyurl.com/bcgwf ("Getting up and 
>>running...") 
>>and at http://tinyurl.com/7d7xr
> 
> 
> I don't know if that's much help; it poses more questions than it
> answers!

There is no content there. Look at the structure. Do we need something 
like this?

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

It isn't clear how to set the PATH. IDE people probably never used "my 
computer/properties/advanced/environment variables" dialog.

> Everyone else will understand that they can probably
> get away with using a long path to the executable when invoking it.

It isn't that obvious. For example, cl.exe (the msvc compiler) cannot be 
run without some folders in the PATH because it won't be able to find 
a DLL.

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

What are the possible outcomes of this command? Can it fail? If it can, 
we should tell users what to do in this case.

>>>>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.
> 
Just omit "so you can rebuild Boost.Jam from source".

Andrey