Re: [Boost-build] Documentation toolchain, ease of use

Subject: Re: [Boost-build] Documentation toolchain, ease of use
From: Steven Watanabe (watanabesj_at_[hidden])
Date: 2011-02-04 16:49:27

AMDG

On 2/4/2011 11:04 AM, Daniel James wrote:
> On 4 February 2011 18:33, Steven Watanabe<watanabesj_at_[hidden]>  wrote:
>> On 2/4/2011 10:12 AM, Daniel James wrote:
>>>
>>> I recently changed fop so that if initialized a second time it
>>> overwrites the initial settings. Glancing at the other tools, it looks
>>> like if they're initialized a second time it's ignored (which seems
>>> wrong to me).
>>>
>>
>> Overwriting the settings is potentially
>> dangerous if any targets are created in
>> between.  I'd rather have it be an error.
>> using xxx ; does appear in quite a few
>> Jamfiles, so changing it to overwrite the
>> settings with whatever would be found
>> by default would be a bad idea, as it
>> would almost certainly break anyone trying
>> to build the documentation on windows.
>
> Vladimir suggested I remove the reinitialisation check so that local
> configuration can overwrite global - which is a reasonable
> requirement. Maybe it should ignore reinitialisation without values,
> and be an error if it's reinitialised with values after being used for
> anything else  - assuming no actions are performed by configuration
> files, that we can detect use and it isn't too hairy to implement.
>

Uses that would break are fairly easy to
detect, since initializing the tool just
sets some variables in the module.  I just
need to set a flag .configuration-frozen
in all the rules that depend on the configuration.

Okay, so here are the proposed semantics
in detail.
* All parameters are optional
* The value of each parameter is the last value given in
   any call to using.
* The tool is not initialized at all unless
   there is a using statement somewhere.  It
   must be initialized before the first use.
* If a parameter is never specified, it will
   be deduced in some appropriate default manner.
* Any attempt to explicitly set a parameter
   after the tool has been "used", results
   in a hard error, where the exact meaning of
   "used" is defined by the tool.

I think this results in reasonably intuitive
behavior.

* Settings can be overridden.  The last one wins.
* The behavior of the module is "as though" all
   the configuration parameters were specified once
   up front.
* Jamfiles can safely initialize the tools that
   they need, without worrying about clobbering
   the settings from a config file.

>> To make things work with no user configuration,
>> I need a way to say "Make sure the tool is
>> initialized. I don't care how." and initializing
>> with no arguments seemed like the most natural
>> approach.
>
> This is really going to need a warning (or error) for any Jamfiles
> which don't have the necessary using directives (or whatever), even if
> they are already configured. Is that possible?
>

I think it's possible, but tricky.  I was just
going to make sure that everything in Boost
does it right and update the documentation
to describe the new way.  That way nothing
breaks.

I suppose that there's another way to solve the
problem:
* Make import sufficient to make a toolset usable
* Always use import in Jamfiles.  using is reserved
   for config files.
* Stop using global rules.  Rely on the module scoping
   rules to force users to import what they need.

I didn't really want to go this route, because
it will break code that works now, not all of
which is directly controlled by us.  Also it
is somewhat inconsistent with how all the other
main target rules work.

In Christ,
Steven Watanabe