Re: [jamboost] Build process specification.

From: Vladimir Prus (ghost_at_[hidden])
Date: 2003-03-27 10:49:34

Ali Azarbayejani wrote:

> <1> We often say things like "A uses B", believing we all understand
> what that means. What *EXACTLY* does it mean? This is important
> because it is the basis for determining how Usage Requirements
> apply, which is the principle confusion I have with the
> specification. If A "uses" B, then B's Usage Requirements are
> applied to A's Build Properties (boost_build_v2.html), but what
> does "uses" mean exactly?
>
> I assume this "uses" relationship is meaningful only between Main
> Targets, yes?

Strictly speaking, we say that main targets uses virtual targets. The virtual 
targets come as result of generating other main targets.

> What are the ways to cause this relationship? Is the following
> true and complete?
>
> <a> A Main Target A "uses" a lib target B if B is in A's sources

Yes, except that "lib" is not necessary. All virtual targets generated from 
sources are "used".

> <b> A Main Target A "uses" a lib target B if property <library>B
> is in A's Requirements

Yes, but see below.

>
> <c> A Main Target A "uses" Main Target B if property
> <use/dependency>B property is in A's Requirements

Yes, but there's no difference between <library> and <uses/dependency>.
There's "dependency features". If there's dependency feature in requirements,
the main target it refers to is generated and main target "uses" all generated 
virtual targets.

> The above describes DIRECT "uses" relationships as I understand
> them.

Yes.

> <2> Does "uses" also include INDIRECT relationships? That is, if A
> "uses" B and B "uses" C, does A "uses" C? Or not?
>
> Does this vary depending on the feature-type (yuck!)?
> E.g. <library/link-to> applies to INDIRECT dependents but
> <include> applies only to DIRECT dependents?

No. Usage requirements from sources and "dependency" features are not
propagated further. Usage requirements from "dependency" features in usage
requirements are propagated. E.g.

lib a : a.cpp : <uses>b : : <library>c ;

Here, usage requirements of 'c' will be present if 'a's usage requirements. 
Usage requirements of 'b' will affect build properties of 'a' and nothing 
else.

> <3> If A "uses" B, is it true, as implied in the v2 specification
> (boost_build_v2.html), that a property appearing in
> Usage-Requirements in B is equivalent to the same property
> appearing in the Requirements of A?

Not exactly. Conditionals are expanded when generating "B".

lib a : a.cpp : <uses>b/<optimization>space ;
lib b : b.cpp : : : <optimization>space:<define>FOO ;

'a' will get <define>FOO even if it is build with <optimization>speed. 
For 'dependency' features in 'b's usage requirements, you'll also
get recursive usage requirements, as I've described above.

> That is, if you put property P in B's Usage-Requirements, would
> you get EXACTLY the same behavior if you removed P from B's
> Usage-Requirements and placed it in the Requirements of all of B's
> direct dependents? (Or all direct AND indirect dependents?)

A little bit different, as described above.

> (I know there are problems here...first of all, if you are allowed
> to establish "uses" relationships with the <library> property in
> Requirements (which I am starting not to like), then Requirements
> must be processed before "uses" relationships even can be
> determined, so Usage-Requirements from dependencies cannot
> possibly be equivalent to Requirements. This is a problem, either
> with functionality or terminology...or documentation.)

I'm not sure I see the problem, yet. Yes, requirements are processed before 
generating dependency main target and adding usage requirements, and
usage requirements in dependencies are not 100% equal to requirements,
but it still looks sensible to me. Can you elaborate?

- Volodya