[boost] Re: Customer Friendlier Boost Installation

From: Hendrik Schober (boost_at_[hidden])
Date: 2005-05-31 18:06:36

David Abrahams <dave_at_[hidden]> wrote:
> [...]
> > > 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 you know better than me what it should
  say. :)

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

  It fails to communicate soemthing very important
  to people who don't know boost: Boost.Python is
  not required when you only want to look at boost.
  /I/ know that Boost.XYZ means, "XYZ" is some lib
  I can use. Others don't know that. They just know
  that "something" didn't work. From "Boost.Python"
  they won't know whether they need it. Maybe
  sneaking the word "library" in there somewhere
  would help: "If you don't need the Boost.Python
  library, ..."
  /I/ would opt to check out boost without that lib.

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

  I'm in the process of trying to fail on producing
  a simpler "Getting Started" guide. :o>

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

  I didn't even know I got there.
  However, if you were to write instructions for
  every toolset you support... I wouldn't want
  to think this sentence any further.

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

  Oh, now I understand. Yes, if the bjam actually
  said what was wrong and what was OK in a way
  that those not familiar with bjam understood
  it -- that would indeed be very 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.

  Yes, meanwhile we knoe.

>                                                       But we should
> tell you the names of the targets we can't find, right?

  Absolutely.

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

  I was thinking of a way to find out why bjam
  didn't report /all/ targets finished.

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

  Then there was no indication why it reported
  not all targets to be finished. I consider this
  bad: The tool reports it failed (or at least
  that's how I interpreted what it said) but did
  not tell me why it failed to finish what target.

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

  Yes. This would at least tell me what to grep for.

> [...]
> > > >   But that wasn't the problem. I found the stuff in the "bin"
> > > >   folder.

  (Which I now know I wasn't supposed to look
  into.)

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

  The "stage" thing was the first one I found
  that seemed to allow me to change the default
  installation folder. I now know that this was
  wrong -- nut them I thought this was what I
  was looking for.

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

  Then I strongly suggest it. <g>

> [...]

  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