|
|
Boost : |
From: Hendrik Schober (SpamTrap_at_[hidden])
Date: 2005-05-26 06:08:10
David Abrahams <dave_at_[hidden]> wrote:
> "Hendrik Schober" <SpamTrap_at_[hidden]> writes:
> [...]
> > 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?
Actually, I really typed "..\bjam.exe" as this was
where I put my copy of bjam. (I'm not editing my
path env variable just for trying out a lib that I
downloaded.) The prompt was provided by the system
and the rest I just pasted.
> 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.
Yep, because I copied the line from the docs. :)
(Did I mention I don't like typing commands?)
> > After quite a pause ("what's it doing now?")
>
> Good point; we should have it say something.
I supposed it checked some dependencies. I
don't think this pause was very distracting
to me. But a short note would do a lot for
many people.
> [...]
> > 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?
Suppose you never heard of boost until this
fellow told you you should check it out. You
download it. The "Getting Start(l)ed" guide
says it needs to get built before you can use
it. <sigh> It doesn't come with a project for
your IDE. <breathing very deeply> It doesn't
even come with one of those dreaded make files
from the Unix-guys <grin>, but with a special
build tool that you have to build yourself
<oh, no> ...wait, here it says you can download
a pre-built version <phew>.
Already pretty non-standard for Windows so far.
But now this tool spits out that something is
incorrectly configured so it can't do whatever
it meant to do with something called Python
lib. <what's this>
Besides the obvious questions left open ("What
did I do wrong?" "Should I have configured
this?" "Where?") the most fundamental question
is: "What does that mean?"
Someome testing boost due to hearsay won't know
what "Boost.Python" is. Is it something that the
build tool needs? Something that the lib needs?
/I/ knew it was one of the libs boost came with
(which I wasn't interested in.) Others don't.
> > 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.
Nothing. This was my fault.
> > 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.
I see. Mea culpa.
Yet, that's the problem of having to learn
how to use a special tool just to use a lib.
I'm not saying that Boost.Build wasn't a good
idea. The regression testing with dozens of
compilers times dozens of libs really is very
impressing and I'm sure it would have been a
lot harder to do this in other ways. What you
did was great -- but I don't want to have to
deal with it. I just want to /use/ these libs,
not test them on dozens of platforms.
> But where did you get the idea that VC71_ROOT was a legal toolset
> name?
As I said elsewhere: Trying to read too fast.
There was this table saying something that I
interpreted as "click on your compiler's name
to get what you'll need further down", there
was some variable to be found there, elsewhere
one was needed.
> > 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.
<g>
See, I have little spare time. So I try things
out while I'm waiting for the compiler. I don't
have too much time for a given test this way
and my mind is wandering. (Did the build just
fail?)
Of course, if I really needed to use a boost
lib that needs to be built, I'd take more time.
But if you want people to check things out (and
if you want more users, you want this), it
should be possible to do so without having to
read all of the Boost.Build docs and understand
yet another tool (that they won't encounter
anywhere else).
> > 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?
I don't think so. But maybe some explanation in
the docs (in non-build-system-eze) of what they
are would be good. (I suppose that's obj files
as well as lib files? Even boost doesn't have
more than 4000 libs.)
> > Why does it only "update"
> > a quarter of them?
>
> The others are up-to-date.
I thought that much. I suppose I had tried to
build before and forgot about it when I wrote
that posting.
> > Why wouldn't it find 2 of them?
I'm still amazed by this, BTW.
> > 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.
I'm still unable to understand the sentence
"Invoke the build system, specifying the toolset(s)
you wish to use, to build and install." (step #5)
in any other way. The examples below used "gcc", I
figured I should replace this by "vc", which was to
be found in the table right above this (step #3).
> > 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.
Yeah, meanwhile I know. :)
> > 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?
I honestly don't know. I'm used to see so many
messages. (I'm mostly working on a 700kLOC project
lately.) But in my IDE I know how to find the
errors. Even if I had piped the output into some
log file, would grepping for "error" help? Or is
it "target"?
> > 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
> ??
Yes, of course.
> 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 didn't start the intall, because I'd hate to
have the stuff at "C:\Boost". But that wasn't
the problem. I found the stuff in the "bin"
folder.
> I can't imagine how we could make this clearer. Can you help?
See below.
> > 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.
Sorry for the bad wording. (I'm German.)
I need to tell the IDE where it finds the libs.
Now that I think of it, the install target might
have just copied all lib files into the same
folder and I should have pointed my IDE there.
But I didn't want to use this, as I hate to
have too many things in the drive's root. So
yesterday I was wondering whether the autolink
would name the libs with a folder like
"release\runtime-link-static\libboost_filesystem-vc71-s-1_32.lib"
Maybe I should just have used the installer and
be done with this. But then I thought I am not
all that dumb. I have read and even understood
makefiles, have built things from the command
line, have used 3rd-party libs without needing
expensive commercial support, and I remember
hacking batch files in the DOS days.
> [...]
> > 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 know that this was the intention. I'm just
telling the tale of me failing despite this.
> [...] Can you help us understand what to change?
I'll try.
First, the numbering is odd. It's unclear where
a step (if it's numbered in a How-To guide, I
assume it to be steps that I need to follow)
begins and where it ends. Not everything having a
number really is a step. For example, #2 isn't a
step, but some explanation. "Step" #3 is a table
supporting the header above it ("Configuring the
tools"). It wearing a new number made me think it
explains some new step yesterday, but since it
doesn't explain what this (supposed) step would
be, I felt free to guess and thus copied the
'VC71_ROOT' just in case -- which then I used at
the wrong place.
Having #4 (chdir) being its own step seems silly.
In #5, the "stage" is mentioned. Now I think this
wasn't all that good as it lead me to believe I
could use it without really understanding what
the build system does and how. IMHO it should
either be removed or better explained what to do
with the outcome of it. (I only just found that
"stage" actually copies the libs into a common
folder /after/ I finished this paragraph. It
actually is described in a table following "The
build and install system can be controlled
through a set of options..." which I didn't
bother to read, as I didn't want to learn how
to fully make use of it. I just wanted to get
up and running.)
Further, the different header levels are easy to
confuse by the font types and sizes used. There's
a nice overview at the beginning of the page
showing all this, but this doesn't help me when
I'm in the middle of the page. (I had to scroll
back and forth several times today to finally
understand why the toolset table apears twice.
So either the different levels should be easier
to tell from each other (maybe add a numbering
scheme) or the page should be broken into several
pages, so that I realize when I enter the next
main section.
And please make the relationship between the
headers and the numbering of (what I believe to
be) the steps clear. I still don't know what
this means.
IMO Supplemental information(like what to do
with .zip/.tar files etc.) shouldn't interupt
the reading. Most people know how to deal with
compressed files on their platform, so a footnote
leading to more info would do. Also, for a
"Getting Started" guide a link to some explanation
of how to access CVS would do. No need to clutter
the beginner's guide with info that 98% of the
beginners won't need.
The "Results" section I actually consider very
well written and easy to understand. However,
it's almost 1/3rd of the whole guide and it's
hard to remember you're in the middle of it when
you read the doc for the first time. Now I really
think this page should be broken.
The same goes for "Automatic Linking on Windows".
Why should users of all other platforms have to
read this? (BTW, the auto-link anchor seems to
be missing. The link from the top of the page
doesn't work.)
OK, I understand that that's a lot of vague
chriticism. So here's an outline of what I would
have expected:
1. Download the lib from <link>, unzip it.
If you want to use the header-only libs, goto
#4.2.
If you want to use (one of) the following libs
- ...
- ...
...
you need to build them.
2. Boost is built using a special tool. Either
download bjam as a pre-built binary from
<link>, or download its sources and follow
the instructions at <link> to build it
yourself.
Make sure a bjam executable is in either your
path or the current directory.
3. Pick the tool name for your platform/compiler/
std lib from the nth column of following table:
<table>
(If your platform/compiler/std lib isnt in this
table you can't follow this guide. Please look
here <link> for how to setup things yourself.)
Invoke bjam like this:
bjam "-sTOOLS=<tool_name>" install
replacing <tool_name> with the name picked from
the table.
Here <link> is an explanation of common messages
of bjam and what they mean.
Here <link> is a documentation of what else you
can do with bjam.
4. The libs are built.
4.1. Point your linker to <folder> for the libs.
Here <link> is an explanation of the names of
the built libraries.
Windows compiler can automatically pick up the
libarary needed. Here <link> is explained how
this works.
4.2. Point your compiler to <folder> for the headers.
5. The documentation for all libs shipped with boost
can be found at <folder>/index.html.
One more thing: We have boost checked in into our
CVS repository. We export it into every project it
is used in, using the version tag specified in this
project's checkout script. This allows using
different boost versions in different projects,
without requiring all developers to have the right
versions in a specific folder on their machine.
If we're going to use boost libs that require
linking, I don't see how Boost.Build would fit into
this scheme.
Other libs we use come with project files for all
the platforms we need them for and we just add them
to the project. That's very easy.
Schobi
-- SpamTrap_at_[hidden] is never read I'm Schobi at suespammers dot org "Coming back to where you started is not the same as never leaving" Terry Pratchett
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk