Re: [Boost-build] feature, properties, variants, and all the rest

Subject: Re: [Boost-build] feature, properties, variants, and all the rest
From: Stefan Seefeld (stefan_at_[hidden])
Date: 2016-12-23 15:44:47

On 23.12.2016 15:29, Steven Watanabe wrote:
> AMDG
>
> On 12/23/2016 09:05 AM, Stefan Seefeld wrote:
>> Hello,
>>
>> I'm still working on my b2 Python prototype (haven't given up just yet !
>> ;-) ). Instead of reinventing everything from scratch, I'm trying hard
>> to reuse ideas from b2 wherever I can. However, that is quite hard,
>> given the sparseness of its documentation...
>>
>> Right now I'm trying to understand properties and how they propagate
>> from the command-line & jamfiles to targets and actions.
>>
>> So let me outline my understanding of these concepts, combined with a
>> few basic questions I have:
>>
>> * Property sets are sets of properties (duh !). What does the
>> 'PropertySet' class (in build/property_set.py) add over a simple set()
>> (or list()) of property instances ?
>>
>   It's more like a dict than a set.  The main
> benefit is that it mirrors Jam, which makes
> porting jam modules much simpler.  There are
> also some functions specific to properties,
> like target_path or base, free, propagated, etc.

It would be great to understand their purpose, too. ;-)
>> * A Property is a feature with an associated value. What is a LazyProperty ?
>>
> I have no idea, since there's no such thing in Jam.

Ah. The code seems to suggest this is to allow "late" evaluation, as
otherwise a property requires the feature it represents a value for to
exist, which appears to be specific to Python, i.e. this is a constraint
not present in Jam. (I'm basically paraphrasing using my limited
understanding.)

>> * A Feature is a type of a property: it defines certain property
>> attributes, as well as ways to interpret it. Feature values are
>> typically restricted to finite sets of values, unless they are 'free'.
>> What attribute decides whether values are accumulative or exclusive ?
>> (For example, the 'link' value is either 'static' or 'shared', but
>> 'include' is an accumulative set of paths.) Further:
>>
>   Only free features can have multiple values.  In
> retrospect combining 'multiple values' with
> 'values not from a predefined list' was probably
> a mistake.

I was wondering about that indeed. :-)

>   There are a number of cases where
> the correct behavior is 'exactly one path',
> for instance.

yeah, I agree.
>>   - what is a 'sub-feature' ?
>>
>   It's a feature that is only present when another
> property is present:
> Ex: <toolset>msvc-14.0 is actually shorthand for
> <toolset>msvc <toolset-msvc:version>14.0
> where <toolset-msvc:version> is a subfeature.

I see. Thanks.

>>   - what is a 'symmetric' feature ?
>>
>   You can mostly ignore this.  It only
> means that when building a target path,
> the default value of the feature will
> be included.  The primary example of
> this is <toolset>.
>
>>   - what is a 'composite' feature ?
>>
> A composite feature contains other properties:
> Ex: <variant>release -> <optimization>on
>     <debug-symbols>off <define>NDEBUG

So 'variant' is a composite feature whose constituent (sub-)features are
'optimization' etc. ? So 'composite' is the parent of a 'subfeature' ?
>> It would be great to see examples of the above. I promise to try to
>> capture my understanding in a document, so this will at least result in
>> improved documentation. Please help ! :-)
>>
> In Christ,
> Steven Watanabe

How do properties propagate from command-line to (specific) target ? How
are they merged ? (I assume there are rules to obey, such as 'free'
properties can be simply merged, while others are exclusive, requiring
some 'override' rule, etc.
And how are properties combined with conditions ?
Are these mechanisms formally defined somewhere ? A few examples would
be really helpful to illustrate how that works.

Thanks !

        Stefan

-- 
      ...ich hab' noch einen Koffer in Berlin...