David Abrahams <dave@boost-consulting.com> wrote:
"Hendrik Schober" <SpamTrap@gmx.de> 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@gmx.de 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