[boost] Re: Customer Friendlier Boost Installation

From: David Abrahams (dave_at_[hidden])
Date: 2005-05-25 17:45:45

"Hendrik Schober" <SpamTrap_at_[hidden]> writes:

> Caleb Epstein <caleb.epstein_at_[hidden]> wrote:
>> [...]
>> I really think the Getting Started guide is more than adequate, and is
>> concise and easy to follow.  There are gigantic yellow numbers next to
>> the important steps.  [...] really how much more hand-holding
>> does one need?
>
>
>   OK, so I went to the that guide, downloaded boost
>   1.32, downloaded bjam.exe, unzipped everything,
>   and typed, IMHO according to the guide,

>     C:\Temp\Download\boost\boost_1_32_0>..\bjam.exe bjam "-sTOOLS=VC71_ROOT" stage
      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Surely you didn't type any of that stuff?

Just to be absolutely picky about it, the guide does not tell you to
type
        .\bjam.exe    ...stuff...

but
        bjam          ...stuff...

And that might be why you repeated "bjam" on the command-line.

>   After quite a pause ("what's it doing now?") 

Good point; we should have it say something.

>   it
>   spit out a lengthy messagethat that I have an
>   incorrect configuration. It couldn't find Python.
>   Mhmm. Do I need this? Will it even work without
>   Python? (I know it will. But not from the guide.)

Well the message you *actually* get is:

   skipping Boost.Python library build due to _missing_ _or_
   _incorrect_ configuration

followed by some other stuff.  So if that is insufficient to make it
clear that the build will will work even without Python, what do we
need to do in order to make it clear?

>   Next thing it emits is
>     don't know how to make bjam
>   Yikes! What does that mean? It surely doesn't mean
>   it wants to compile/link bjam as I am /running/ it
>   already, right? Scary.

No, it means that you typed an extra "bjam" on your command-line.  I
really don't know what we could do to make it clearer that you're not
supposed to do that.

>   Right after that, it emitted
>     don't know how to make -sTOOLS=VC71_ROOT

bjam has this (silly, IMO) restriction -- inherited from jam -- that
options must precede targets on the command-line.  You are the victim
of that, combined with the fact that you added an extra "bjam" which
was interpreted as a target.  Therefore, -sTOOLS=VC71_ROOT was
interpreted as a target.

But where did you get the idea that VC71_ROOT was a legal toolset
name?

>   Now I am really really baffled. I mean, I pasted
>   that line from the guide (except for replacing
>   "gcc" with what I thought the guide says I need
>   to replace it with). 

If you misread the guide sufficiently badly, it's possible to produce
arbitrarily bad outcomes.  Of course, if you're misreading the guide
it's the guide's fault.  But how could we have made it clearer?  It's
hard for me to see how we led you to invent the command line you used.

>   Doesn't that thing even
>   recognise its options?
>   Finally, it advices
>     ...patience...
>   Oh good. So I'll wait. Further:
>     ...found 4471 targets...
>     ...updating 1123 targets...
>     ...can't find 2 targets...
>   Um, what are targets? 

Standard build-system-eze for "element of the build dependency graph."
These messages are inherited from jam; should we remove them?

>   Why does it only "update"
>   a quarter of them? 

The others are up-to-date.

>   Why wouldn't it find 2 of them?
>   I read the guide again. Damn! I messed this up! I
>   need to pass "vc", not "VC71_ROOT"! The guid is a
>   bit terse in that area...

Where did you get the idea you needed to pass "vc"?  This is not a
criticism; we need to know how you were led into this so we can figure
out how to fix it.

>   CTRL-C
>     C:\Temp\Download\boost\boost_1_32_0>..\bjam.exe bjam "-sTOOLS=vc" stage
>   Alas, same result. Excep that now it
>     don't know how to make -sTOOLS=vc

It's that extra "bjam" again.

>   Huh?
>   Well, it says I should be patient, so I just let
>   it do whatever it does.
>   There really are a few libs in "bin" at the end.
>   And the thing says
>     ...updated 1120 targets...
>   Mhmm. Three missing. It might have even emitted an
>   error message. No way I'm going to wade through
>   3-4k lines of messages to find those three.

Should the tool be silent while building unless it encounters an
error?

Perhaps a string of dots, just so you know there's progress?

>   Now I would need to link to this stuff. But where
>   exactly do I need to point my linker at? 

Really, is there something unclear about
http://www.boost.org/more/getting_started.html#Build_Install
??

  The default build and install attempts to build all available
  libraries and install to default locations the libraries and Boost
  header files. On Unix systems the default install location is
  "/usr/local", and on Windows systems the default is
  "C:\Boost". Within those directories libraries are installed to the
  "lib" subdirectory, and headers to an "include/boost-1_31"
  subdirectory, the version will reflect the distribution you are
  installing.

I can't imagine how we could make this clearer.  Can you help?

>   The guide
>   has something on automatic linking on Windows, but
>   I can't find where in the folder hierarchy this
>   assumes I'm anchored.

I don't know what you mean by "anchored."  I would assume that the
dynamic libraries need to be in your PATH, and that's all.  But I'm
not an expert in this area.

>   Still long ways to go before I can start to work.
>   Add to this that, as with all new stuff, I will
>   still stumble more later while using this, that I
>   would have to write a usage guide for my fellows
>   if I want to use this (hey, some of them aren't as
>   good reading English, they will never be able to
>   follow this guide!), and that we need to figure
>   this out for another handful of platforms -- and I
>   start to think if it really is worth all the hassle.

I can understand that.

>   Conclusion: I have seen smoother installations on
>   Windows, 

Certainly.  We should be providing an installer with pre-built
binaries.

>   I have installed easier to build libs, and
>   I have seen guides that weren't written for mere
>   insiders. 

Now wait a minute.  Whatever it's failings, this guide was written
specifically for non-insiders.

>   I'm no command-line afficinado, I can
>   barely read makefiles, and I am used to having a
>   GUI and online-help for every option.
>   Call me dumb, but I am one of millions of potential
>   boost users.
>   We use boost since years ago, when I threw out all
>   home-grown smart pointers and replaced them by
>   boost's. So we /know/ boost is worth quite a lot
>   of hassle and we even use one library that's not
>   headers-only. (However, this one -- regex -- comes
>   with a makefile and this we knew how to integrate
>   into the build.)
>   But if this was my first look at boost, I'd delete
>   it right away. Seriously, on this platform are
>   millions of C++ users that only heard very vague
>   rumours of C++ being standardized -- if they heard
>   about it at all. Those don't see much benefit it
>   smart pointers, consider the MPL to be black art,
>   and can't be bothered if it isn't really easy to
>   use.

Yep, we need to do better.  Can you help us understand what to change?

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