Re: [Boost-users] install with b2 - conflicting documentation

Subject: Re: [Boost-users] install with b2 - conflicting documentation
From: Kirk Joppy (kirk.joppy_at_[hidden])
Date: 2013-06-23 14:34:12

I think my trouble was the result of slightly confusing documentation
so maybe this is a good chance to fix it. I also have some questions
regarding the build system that I'd like to ask below and will
indicate where I think the docs could be improved as I go along.
Referring now to the instructions at

http://www.boost.org/doc/libs/1_53_0/more/getting_started/windows.html#prepare-to-use-a-boost-library-binary

Section 5.2 indicates that the "simplified build" is available only
with Visual Studio so I moved on to section 5.3. It says I need to use
Boost.Build so I followed the instructions in section 5.3.1 with a
slight modification. Here is what I typed into cmd.exe:

$ cd boost_root\tools\build\v2\
$ bootstrap.bat gcc
$ b2 install --prefix=boost_root\my-build
Added boost_root\my-build\bin to PATH
$ cd boost_root
$ b2 --build-dir=boost_root\my-build\tmp toolset=gc --with-regex
--layout=tagged stage

In line 2, is "gcc" needed? If so is it just telling b2 what compiler
tool chain to use?

Why is it necessary to add boost_root\my-build\bin to PATH? Does the
second invocation of b2 use executables from there?

In the final invocation of b2, note that I did not follow the
instructions and put --build-type=complete. Of course, the first time
through I did do that but it takes forever and builds a ton of stuff I
didn't need. I think it would be really useful to change the
documentation so newbies like me don't spend a lot of time incorrectly
building the entire lib set. The chance of getting things right the
first time seems kind of low and it's a bit wasteful to wait an hour
for each attempt, particularly since building only regex, which is all
I needed, only takes a few seconds. The note about --with at the end
of 5.3.4 should maybe be moved up.

Also, I think it might be useful, particularly in the Windows
instructions, to explain why the files are being written to a
directory called stage. This confused me quite a lot until I realized
that it makes sense in the Unix multi-user environment. I really think
explaining the thinking behind how this is done in the documentation
would be a great help to newcomers.

My most important question is - do I actually need to go through the
steps in building Boost.Build into boost_root\my-build? It seems like
bootstrap.bat works from boost_root and makes b2.exe. What's the
difference between doing that and doing it from
boost_root\tools\build\v2 ?

Ok, now the last thing is that this other set of instructions found here

http://www.boost.org/doc/libs/1_53_0/doc/html/bbv2/installation.html

really confused me. I now realize they are instructions for installing
Boost.Build, but since I first found it through google search and
didn't know what I was doing, I thought it was instructions for the
libs. It might be useful to add an explicit note that they are not
instructions for the lib and perhaps a link to the "getting started"
page I refer to above.

Thanks so much. I'm trying to understand "why?" and not just "what?"

-kjoppy