|
|
Boost : |
From: Hendrik Schober (SpamTrap_at_[hidden])
Date: 2005-05-27 06:32:23
David Abrahams <dave_at_[hidden]> 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_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