Re: [jamboost] An easy way to add a feature?

From: Vladimir Prus (ghost_at_[hidden])
Date: 2003-12-08 01:28:01

Hi Zbynek,

> I'd like to add propagated non-free link-incompatible feature for my
> project. It should have a name and 4 possible values and it should
> expand into different <define>s. I've looked at the extender manual but
> that didn't help. Where else would be a good place to look? Thanks.

Maybe, you can take a look at the attached? I wrote it some time ago but had 
to time to integrate to html docs.

As far as expanding into <define> is concerned, you can try specifying 
'composite' attribute to feature and then look how 'feature.compose' is used 
in builtin.jam. Alas, running

bjam --help feature.compose

won't give much information :-(

- Volodya
 --Boundary-00=_xnB1/9GkrImiKa6 Content-Type: text/plain;
charset="iso-8859-1";
name="new_feature"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
filename="new_feature"

Adding a new feature.

Suppose you are not happy with the standard set of features, and would like 
to add your own.

Why would you want this, as opposed to passing flags to C++ compiler directly?

1. If you specify a feature, you will be able to build your project with two
different settings of the feature. If you pass compiler options,
Boost.Build assumes you know what you are doing, and would not care about
the options.

2. The feature makes sense for more than one compiler.

3. You use the feature to refer to a target.

Adding a feature requires three steps:

1. Declaring a feature. For that, the "feature.feature" rule is used. You
should have to decide on the set of feature attributes:

- if feature has several value, and significally affects build, make
it "propagated", so that whole project is build with the same value
by default

- if feature does not have a fixed list of value, it must be "free".

- if feature is used to contain value of path, it must be "path".

- if feature is used to refer to some target, it must be "dependency".

2. Converting the feature value into variable. To use feature in build action,
it must be converted into a variable, acessible in build action. This is
accomplished by "toolset.flags" rule.

3. Using the variable. The variable set in step 2 can be used in build action
to form command parameters or files. 

Example 1.

Let's invent fictional feature which causes to use C++ VM, an as-yet
non-existent beast similiar in spirit to Java VM. For example, let's adjust
the gcc toolset.

Step 1.
Add to builtin.jam the following line.

feature cppvm : no yes : propagated ;

Step 2.
Add to gcc.jam the following line.

flags gcc OPTIONS <cppvm>yes : -use-vm ;

Step 3.
Oops. The gcc.link and gcc.compile actions already use OPTIONS variable, so
we don't have anything to do. Assume gcc.compile actions contained
nothing but

actions gcc.compile
{
g++ -o $(<) $(>)
}

then we would rewrite it to be: 

actions gcc.compile
{
g++ $(OPTIONS) -o $(<) $(>)
}

And our <cppvm> feature would work.

Example 2. 

Referring to a file. 

Let's see how we can make a feature which refers to a target. For example,
when linking dynamic libraries on windows, one sometimes needs to specific
"DEF file", telling what functions should be exported. It would be nice to
use this file like this:

lib a : a.cpp : <def-file>a.def ;

Step 1.

Since the feature refers to a target, it must be "dependency".

feature def-file : : free dependency ;

Step 2. 
One of the toolsets which cares about DEF files is msvc. The following line 
should be added to it.

flags msvc.link DEF_FILE <def-file> ;

Step 3.
Since the DEF_FILE variable is not used by the msvc.link action, we need to
modify it to be:

actions link bind DEF_FILE
{
$(.LD) .... /DEF:$(DEF_FILE) ....
}

Note the "bind DEF_FILE" part. It tells bjam that DEF_FILE refers to a file,
otherwise the variable will contain internal target name, which is not likely 
to make sense for the linker.

We've almost done, but should stop for a small workaround. Add the following
code to msvc.jam

rule link
{
DEPENDS $(<) : [ on $(<) return $(DEF_FILE) ] ;
}

This is needed to accomodate some bug in bjam, which hopefully will be fixed
one day.

 --Boundary-00=_xnB1/9GkrImiKa6--