David Abrahams <dave@boost-consulting.com> wrote:
[...]
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?
I don't think that's necessary. I was just really dumb and not paying enough atention. (I figured it would take a while for boost to get built and rushed to get it started so that I could go and have the break that I was planning to have anyway.)
[...] 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?
"Parsing jam file"? Or better yet: "parsing build rules"?
[...] 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?
Maybe something along those lines: "Unable to find Python. Cannot build the Boost.Python lib. If you want to use Boost.Python, look at the docs at <link>. Proceeding with other libs..."
[...]
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?
The reason for that silly mistake was that I didn't pay enough attantion. I might have messed this up even with colors. There's little you can do if people fail on the very first word of the command line. Really. I think it's better to concentrate on more difficult stuff -- like getting all the options right.
[...]
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.
Yes, this restriction seems silly. If it's easy to fix and someone has the time to do it, think it should be done rather sooner than later. (Or at least bjam should issue an error or a warning for this.) But in the end most newbies should be able to just cut and paste a command line anyway, so I'd recommend to make this easier first.
[...]
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.
Um, I can't follow you here.
[...]
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? [...]
Oh it should. I didn't say anything against that, did I?
[...]
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.
Oh, this wasn't an error? Wow, then this should surely made very clear. If a build tool says it can't find/build/update some target, I surely read an error into this message.
[...]
Where did you get the idea you needed to pass "vc"? [...]
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.
Yes, I saw this yesterday. What can I say? I don't know anymore where I got this from. As I said, I didn't really pay a lot of attention.
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.
Better yet break the page so that I don't see bot at once.
[...]
Well, it says I should be patient, so I just let it do whatever it does.
It really should say "evaluating dependencies" here.
Actually /I/ don't care. As long as the tool is somehow making clear it's still working, I'm fine.
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.
Mhmm. Not seeing anything is always distracting. Seeing to much isn't good either. So the dots are probably a good idea.
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.
So what I need to look for is error messages that my compilers emits? Anything else? (Maybe a short "Look for error message from your compiler" in case of an error would help.)
Or is it "target"?
Not sure what you're after, so I can't tell you what to look for.
The tool said it updated 1120 of 1123 targets. It didn't say a word about what happened to the other three. If I had done this in order to reall use the resulting libs, I would have had to browse through 3-4k lines of message to find out what went wrong. (/If/ something went wrong. It didn't say it did.)
[...]
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?
Yes. I thought the "stage" was the indication.
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.
If it's that hard to do otherwise, then why do you give (incomplete) information on how to do so on the "Getting Started" guide?
[...]
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.
I suggest "stage" to be either removed or better explained.
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 ;-)
It's not that I've never done this. I have. But that doesn't mean it isn't a PITA to do so. Usually makfiles come with libs I need to use and usually they are pretty well prepared for what I need to do. So I just pass the to make and I'm done.
[...]
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?
Yes. TBH, this looks as if first there was a guide with headers and sections and later on someone came and put in the numbers in a few places that seemed important. Unfortunately that someone seems to have been very familiar with the whole process.
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"
That goes for all steps. They should have a number and a title. All other headers should be logically grouped on a level below those steps. (Sorry, I just don't know the correct English terms for structuring a document.)
I actually see the 2 as going with "Preparation," but it's not obvious why I see it that way.
It's under "Preparation", but so is the "Configuring the tools" header. Even worse, "Supported toolset" seems (when I look at the header's font sizes) to be under "Preparation" as well -- but it's got #3 three. That's very confusing.
"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.
For the novice, what is it good for at all? Do you want novices to use it? Should it be there at all?
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.
Wow, Firefox gave me no clue for this. I only found this out by accident when I was almost ready to give up searching and answer here that I don't know what you're talking about. :)
(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.
Um, actually I only scrolled back and forth the day after I posted here. When I tried this, I don't think I even noticed that I was looking at two different tables. :(
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.
Wow. :-o I hadn't thought this. If that's the case, you should really, really, really make it easier to build boost libs to Windows users.
[...]
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)
Um, I knew this would come up eventually. :) I could hack something in HTML, but isn't that just generated from some other format? Sorry, boost is progressing way too fast for me to keep up with. Other than that I'd need a SF user name first. I see if I find time to put the above into some HTML this weekend. (No promise, though. I mainly want to spend the weekend with my kids.)
[...]
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