Re: [Boost-build] naive usage of bootstrap.sh

Subject: Re: [Boost-build] naive usage of bootstrap.sh
From: Robert Ramey (ramey_at_[hidden])
Date: 2016-10-24 16:58:39

On 10/24/16 12:19 PM, Vladimir Prus wrote:

>> At the very least I think bootstrap.sh should not accept options such as
>> --with... or --without...
>
> Why? Again, maybe nobody cares any longer, but I think it was requested
> by some folks some time ago? Could you suggest a criteria which options
> should be accepted and which not?

I think this illustrates the fundamental difference of approach here.

I get the documentation - maybe I got it wrong - that the purpose of 
bootstrap.sh is to build the tool(s) I need to build boost.  This is a 
simple idea that I can fit into my brain and not lose track of.  It's 
also easy to explain what it does to someone else.  So I expect 
somewhere a statement like:

"the executable b2 is required to build / test the boost libraries"

"invoking bootstrap.sh will build the b2 executable"

OK now when I see switches like --with ... now all sudden I don't 
understand what I'm doing anymore and I have to research what these 
switches do and whether or not I need to use them and if so with what 
arguments.  When I open up the bootstrap.sh, it looks like that it 
passes on these values to some file project-config.jam.  I'm still stuck 
trying to figure out how to set them.

I know it's obvious to the developers of boost build and that there's 
likely a logic to it, but knowing this makes me feel only more 
inadequate as a programmer and person.  It's very disheartening.

Then there's the issue that if I figure all this out, tweak something in 
project-config.jam and then run the bootstrap.sh again - it wipes out my 
changes - moving them to a *.1 file.  Now figuring this out can take a 
lot of time.  When I do, I'm not disheartened this time, I'm pissed.  I 
feel that a joke has been played on me.

So ...

a) make a program have a clear purpose which can be described in a 
simple declarative sentence.
b) make sure the documentation includes that sentence
c) don't add functionality and/or side effects to the program which 
don't contribute to the stated purpose.

In this particular case, it would be far better to
a) remove the switches from bootstrap.sh,
b) remove the silent creation of project-config.jam,
c) add an explanation of project-config.jam, and
d) include a sample project-config.jam which is well commented
e) that users can use as starting point to modify by hand
f) and modify b2 so includes a short trace "reading site-config.jam, 
reading project-config.jam. etc.  so we can see what's happening.  (OK 
it likely has a way to do this somewhere).

It's basically about drawing a straight line from my brain to your 
program without having the program constantly surprising, helping, and 
outsmarting me.  I realize it's intended for my "own good" to make 
things easier - but it doesn't do that.

Robert Ramey