From: Andrey Melnikov (melnikov_at_[hidden])
Date: 2005-09-20 16:54:53
Reece Dunn wrote:
> 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
> 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.
Yes. But only if you plan to use BB intensively. The need to set the
PATH can be both an advantade and a disadvantage. If you just install
Boost (or any other project that use BB), you don't need to change your
>>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 :).
It isn't official. What is the default location for bjam.exe used by the
installer? I think we should recommend it here if user is installing
>>>>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."
IMO the very frequent errors like this can be mentioned in the main guide.
>>>>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.
Python support in BB or in Boost? Both are used rather rarely, and only
by experienced users. I think msvc and maybe gcc will be enough here.
> 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.
This section (toolset configurations) isn't present in the documentation
at all. Are you willing to contribute the documentation for the doxygen
>>>>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?").
There was a very long discussion about how this paragraph should be
rephrased. I just cannot find it and asked for a help me with searching.
>>> 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).
CYGWIN (like unices) has a standard folder layout. Windows don't has a
common /bin folder. It has /sbin and /opt, but not /bin or /usr/bin. So
we should recomment such a location or at least to show the reasons for
such common location.
>>>>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
It isn't clear that jam_src is present in BOTH full distribution and
separate BBv2 distribution. It just has different locations
(tools/build/jam_src vs just jam_src)
Boost-Build list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk