Boost logo

Boost-Build :

Subject: Re: [Boost-build] feature, properties, variants, and all the rest
From: Steven Watanabe (watanabesj_at_[hidden])
Date: 2016-12-23 16:39:36


On 12/23/2016 01:44 PM, Stefan Seefeld wrote:
> On 23.12.2016 15:29, Steven Watanabe wrote:
>> 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' ?

  The term 'subfeature' means something different.
<optimization> can be used independently
from <variant>. <variant> just bundles them
for convenience.

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

  Free features on the command line are applied to
every target. Non-free features are used to
create a property set which is passed to the
command line targets (The default target being the
current project). When building a target, you
can determine which value of a feature will win
from the source:
target requirements > build-request > target default-build > feature default
free features always append. Dependencies are
built using the propagated features of the current target.

lib A : a.cpp ;
exe B : A b.cpp : debug <define>XX ;

$ b2 B release define=YY

B is built with
- <variant>debug (requirements override command line release)
- <define>XX (target requirements)
- <define>YY (command line free feature)
A is built as a dependency of B and gets
- <variant>debug (propagated from B)
- <define>YY (command line free feature)

  In general, b2 --debug-build will explain in
detail which properties are used to build
each target.

> And how are properties combined with conditions ?

  Conditional properties are evaluated when
processing target requirements. The actual
algorithm evaluates all conditionals repeatedly,
until it reaches a fixed point.


rule c ( properties * )
  if <variant>debug in $(properties)
  { return <define>DEBUG }

<toolset>msvc:<link>shared <link>shared:<variant>debug <conditional>@c

Initial properties:
- <toolset>msvc
Round 1:
- <toolset>msvc <link>shared (Other conditionals are not satisfied)
Round 2:
- <toolset>msvc <link>shared <variant>debug
Round 3:
- <toolset>msvc <link>shared <variant>debug <define>DEBUG
Round 4:
- <toolset>msvc <link>shared <variant>debug <define>DEBUG
(Identical to round 3, terminating the algorithm)

> Are these mechanisms formally defined somewhere ? A few examples would
> be really helpful to illustrate how that works.

Try this:

In Christ,
Steven Watanabe

Boost-Build list run by bdawes at, david.abrahams at, gregod at, cpdaniel at, john at