|
|
Boost : |
From: David Abrahams (dave_at_[hidden])
Date: 2005-05-26 09:56:41
"Hendrik Schober" <SpamTrap_at_[hidden]> writes:
> 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.
Heh. Maybe we should write bjam in a different color so you're more
likely to notice the difference between it and the rest of the
command-line?
>> > After quite a pause ("what's it doing now?")
>>
>> Good point; we should have it say something.
>
> I supposed it checked some dependencies.
Actually no. That's what it's doing during
...patience...
During the initial pause it's actually processing the instructions in
all the Jamfiles, just building an internal representation of the
projects and dependencies among targets.
> I don't think this pause was very distracting to me. But a short
> note would do a lot for many people.
What should it say?
>> [...]
>> > 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.
Yes, I understand all that. Let me ask again:
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.
>
> Nothing. This was my fault.
What about the color thing?
>> > 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.
Well, jamma culpa too. And bjamma culpa for not fixing that
restriction. It makes it hard for us every time we have to tell
people to add some special bjam option to the command-line. The ones
beginning with a single "-" (and only those) need to come first.
Dumb, dumb, dumb.
> 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.
Understood.
>> 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.
Okay, maybe we should put "quick boost install instructions" in a box
at the top of every toolset description page.
>> > 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).
Good point.
>> > 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.
Why shouldn't the tool output messages in non-build-system-ese? I
have seldom seen a use for the "found... updatinig... can't find..."
messages. Maybe we should only give those if you request diagnostic
output.
> (I suppose that's obj files
> as well as lib files? Even boost doesn't have
> more than 4000 libs.)
Sources and headers too. Leaves are nodes in the graph too.
>> > 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.
Probably most of those were leaves.
>> > Why wouldn't it find 2 of them?
>
> I'm still amazed by this, BTW.
I don't know, offhand. There are diagnostic options in bjam that
allow us to find out, but you don't really care, do you? That's why I
think we should disable those messages.
>> > 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).
No, not in that table. There's one in
http://www.boost.org/more/getting_started.html#Results, which comes
*after* step 5. I can see how, if you're in a hurry, you might lose
your place and mistake the meaning of that table. I think we ought to
change the column headings somehow and provide an overall table
caption that helps to disambiguate 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.
>
> Yeah, meanwhile I know. :)
>
>> > Huh?
>> > Well, it says I should be patient, so I just let
>> > it do whatever it does.
It really should say "evaluating dependencies" here.
>> > 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.
Well, what do you think? I mean, of course, dots while there's
success, and error messages when there are errors.
> 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?
It would help if you're looking for errors and your compiler puts
"error" in each error message.
> Or is it "target"?
Not sure what you're after, so I can't tell you what to look for.
>> > 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".
Did you not notice the word "default?"
Of course, not giving an indication of how to get behavior other than
the default, knowing that it's only a default is not much help to you,
is it?
> But that wasn't the problem. I found the stuff in the "bin"
> folder.
Well, if you subvert the things we do to make it easy for you
(install) and instead start grabbing things from our
implementation-detail directories, I think you forfeit the right to
expect it to be simple.
>> 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.
Bingo.
> 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.
Yes.
> 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.
You seem a little schitzophrenic about whether you're able to handle
make-like things, now ;-)
>> [...]
>> > 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.
I get it.
>> [...] 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.
Really?
> Not everything having a
> number really is a step. For example, #2 isn't a
> step, but some explanation.
Well it is a step, but it needs a title: "Get Boost.Jam"
I actually see the 2 as going with "Preparation," but it's not obvious
why I see it that way.
> "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.
This is a good point. I wonder how I never noticed it.
> 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.
>From my reading, it's not all that clear what the difference between
"stage" and "install" is. We should tell the user explicitly that
"stage" does *not* copy Boost header files.
> 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.)
Understood. It's not always easy to fine-tune how much information we
should give to the casual user up-front.
> Further, the different header levels are easy to
> confuse by the font types and sizes used.
Yup.
> 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.
Yeah, I favor the style used in http://boost-consulting.com/mplbook/,
where each heading in the text links you back to the index so you can
see where you are.
> (I had to scroll back and forth several times today to finally
> understand why the toolset table apears twice.
...and still didn't get it, apparently. Our problem, not yours.
> 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.
Very good suggestion.
> 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.
Yeah.
> 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.
Good idea.
> 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.
Also very good. That stuff belongs on its own page, and not just for
the beginners' sake.
> 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.
OK.
> The same goes for "Automatic Linking on Windows".
> Why should users of all other platforms have to
> read this?
Maybe because more than 90% of all C++ developers target windows
(sometimes among others). This is an actual statistic, not just my
off-the-cuff estimate.
> (BTW, the auto-link anchor seems to
> be missing. The link from the top of the page
> doesn't work.)
Thanks.
> OK, I understand that that's a lot of vague
> chriticism.
No, no, it's very concrete and helpful!
> 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.
Excellent! Can I give you CVS access so you can try making a modified
page? (send me your SF user name)
> 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.
I think Rene can answer that; I know it's something we've addressed
and that works.
> 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.
I'd like to get to generating project files automatically eventually.
Unfortunately, that's some ways off still.
-- Dave Abrahams Boost Consulting www.boost-consulting.com
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk