[Home]Boost.Build Design Proposal

BOOST WIKI | RecentChanges | Preferences | Page List | Links List


This proposal has several goals:

To this end, I have tried to remove the distinction between toolsets, variants, and features. Instead, toolsets and variants will be treated as special kinds of features. This will allow the addition of properties like <std-library>stlport in a consistent way. I've also extended the notion of feature to include sub-features which can be used to specify version information.

Feature Attributes

implicit - features whose values alone identify the feature. For example, a user is not required to write "<toolset>gcc", but can simply write "gcc". Implicit feature names also don't appear in variant paths, although the values do. Thus: bin/gcc/... as opposed to bin/toolset-gcc/.... There should typically be only a few such features, to avoid possible name clashes.

executed - the feature corresponds to the name of a module containing an execute rule, used to actually prepare the build. For example, the toolset feature would be executed.

composite - features which actually correspond to groups of properties. For example, a build variant is a composite feature. When generating targets from a set of build properties, composite features are recursively expanded and /added/ to the build property set, so rules can find them if neccessary. Non-composite non-free features override components of composite features in a build property set. Composite features are always free features, though they may contain non-free features.

optional - An optional feature is allowed to have no value at all in a particular build. Normal non-free features are always given the first of their values if no value is otherwise specified.

symmetric - A symmetric feature has no default value, and is therefore not automatically included in all variants. A symmetric feature, when relevant to the toolset, always generates a corresponding subvariant directory.

free - as described in previous documentation

path - the (free) feature's value describes a path which might be given relative to the directory of the Jamfile.

dependency - the value of the (free) feature specifies a dependency of the target.

propagated - when used in a build request, the (free) feature is propagated to top-level targets which are dependencies of the requested build. Propagated features would be most useful for settings such as warning levels, output message style, etc., which don't affect the built products at all.

Ordinary features


     import features  # bring in definitions
        : feature subfeature properties ;

     feature profiling : off on ;
     feature threading : single multi ;
     feature runtime-link : dynamic static : symmetric ;
     feature optimization : off speed space ;
     feature define : : free ;
     feature "include" : : path free ;
     feature library-file : : free path dependency ;

This one is actually used by the build system

     feature target-type : : free ;


The toolset feature initially has no values.

     feature toolset : : implicit executed ;

this will be part of the result of loading the msvc toolset. It adds the value "msvc" to the set of permissible values for toolset.

     features.extend toolset : gcc ;

declares toolset-version as a subfeature of toolset. A subfeature is not translated into a new path element, but is instead appended to the feature name with a dash separator, as in "gcc-3.0.1".

     subfeature toolset version : : optional ;

A subfeature may also be declared relative to a particular value of its superfeature:

     subfeature <toolset>gcc version : 2.95.2 2.95.3 2.96 3.0 3.0.1 : optional ;

Link compatibility

These properties are link-compatible with one another
     features.link-compatible gcc-2.95.2 gcc-2.95.3 gcc-2.96 ;
This property is link-compatible with anything
     features.link-compatible <shared-linkable>true ;


     feature variant : : implicit composite ;

     variant debug : <debug-symbols>on <runtime-build>debug
                     <optimization>off <inlining>off ;

this would be executed as a result of declaring the "debug" variant

     features.extend variant : debug ;
     properties debug : <debug-symbols>on <runtime-build>debug
                        <optimization>off <inlining>off ;

Standard Library Replacement

A module called stlport.jam might contain the following:

     import features
        : feature subfeature properties ;
     feature std-library : implicit optional executed ;

     features.extend std-library : stlport ;
     subfeature toolset : version : optional ;

     subfeature stlport version : 4.0 4.5 : optional ;
     feature stlport-iostreams : on off : optional ;

     properties stlport-version : <sys-include>$(STLPORT_ROOT)/STLPort : optional ;
     properties stlport-iostreams : <sys-include>$(STLPORT_ROOT)/STLPort : optional ;

declare the features which generate directories at the top of the build tree, and the order in which the directories are generated. this forces the first few features in the sort order for target directory generation. Since library is labelled "optional" above, no directory may be generated for the library if it is not overridden.

     build.top-features toolset library variant ;

Target Types

     target-type DLL
             : .dll .lib                # suffixes
             : <shared-linkable>true ;  # requirements

BUILD specification

The variants and subvariants built are determined by combining each element with all other elements whose features do not overlap. this builds: gcc-3.0.1/stlport/debug, msvc/stlport/debug, msvc/debug

     build = gcc-3.0.1/stlport msvc/stlport msvc debug ;

more specifically, elements are first segregated according to whether or not they contain composite features, then the above combinations are applied within the two groups. Finally, each element of the first group is combined with each element of the second group, with values in the composite group being overridden by values in the other one, so

     build = gcc-3.0.1/stlport debug release <inlining>off ;


[buy lipitor online] [buy lipitor] [[buy lipitor online]]

[buy fioricet online] [buy fioricet] [[buy fioricet online]]

BOOST WIKI | RecentChanges | Preferences | Page List | Links List
Edit text of this page | View other revisions
Last edited August 24, 2008 2:34 pm (diff)
Disclaimer: This site not officially maintained by Boost Developers