[boost] Re: Customer Friendlier Boost Installation

From: David Abrahams (dave_at_[hidden])
Date: 2005-05-31 08:58:04

"Hendrik Schober" <SpamTrap_at_[hidden]> writes:

> 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"?

Well, it's much more than parsing.  It's actually "evaluating" or
"executing" them.  I think "executing" would be misleading, so maybe
"evaluating" would be better.

>> [...]
>>   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..."

It's currently:

---------------------------------------------------------------------
*** If you don't need Boost.Python, you can ignore this section  ***
*** pass --without-python to suppress this message in the future ***

skipping Boost.Python library build due to missing or incorrect configuration 
...

---------------------------------------------------------------------

How's that?

>> >> 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. 

Rene took care of it.

>   (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.

How so?

>> [...]
>> >> 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.

Sorry, I mean, e.g., at
http://www.boost.org/tools/build/v1/msvc-tools.html and all the other
pages like it.  These are the pages you clicked through to, and found
VC_71_ROOT on.

>> [...]
>> >> >   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?

Well, no, but telling you that we found 4471 targets and we're
updating 1123 of them has to be more cryptic than helpful!

>> [...]
>> >> >   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.

I guess you're right; it's an error and should stay.  But we should
tell you the names of the targets we can't find, right?

>> >> >   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.

Okay.

>> 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.

Okay.

>> >   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? 

If you want to find the error messages from your compiler, then yes.
You didn't really say what you're looking for.

>   Anything else?  (Maybe a short "Look for error message from your
>   compiler" in case of an error would help.)

You might be looking for errors from the linker, too.  I don't really
understand what you're after, though.  All that we output now other
than error messages from your compiler is stuff like:

   vc-c++ <name-of-some-obj-file-target-being-created-by-compilation>

>> > 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.)

Okay, so most of those messages are probably errors from your compiler
or linker and you'll have to browse them anyway, but it might be
helpful if we summarized at the end which targets couldn't be built, I
guess.

>
>> [...]
>> >   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?

I don't understand the question, but you'll have to take it up with
Rene.  I didn't write 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.

I agree.  I think I still don't really understand the differences
between stage and install.

>> >   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.)

That's correct enough.

>> 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?

I don't know; you have to ask Rene.

>> 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. :)

It's a matter of the stylesheet I use, I think.  I really prefer those
links to be subtle.  If they looked like links I think the document
would look wrong.

>> >   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.

Yes.

>> [...]
>> >   So here's an outline of what I would
>> >   have expected:
>> >
   ...

>> 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 eventually took me up on this; I hope everyone appreciates his
efforts as much as I do!

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com