A feature is a normalized (toolset-independent) description - of an individual build parameter, such as whether inlining is - enabled.
+A feature is a normalized (toolset-independent) aspect of a + build configuration, such as whether inlining is enabled.
-A property is a (feature, value) pair. Each features is - described by a name and the set of attributes from the following - list:
+A feature value is a specific available setting for a + feature.
+ +A property is a (feature,value) pair, expressed as + <feature>value.
+ +A subfeature is a feature which only exists in the presence + of its parent, and whose identity can be derived (in the context of its + parent) from the name of its value.
+ +A value-string is a string of the form + value-subvalue1-subvalue2...-subvalueN, where value is + a feature value and subvalue1...subvalueN are values of related + subfeatures. For example, by using value-string properties + <toolset>gcc <toolset-version>3.0.1, can be expressed more + conscicely, as <toolset>gcc-3.0.1.
+ +A set of properties is called, naturally, property set. For + example, <toolset>gcc <runtime-link>static. + Sometimes it's better to represent a property set without spaces. In that + case property path is used, which consists of all properties, + joined with slashes. To continue with example, property path + representation would be + <toolset>gcc/<runtime-link>static .
+ +Each feature can have any of the following attributes:
Incidental features do not affect build products at all. Warning - level is one example. As a consequence, the build system doesn't try - to avoid confusing targets with different values of incident - properties.
+Incidental features are assumed not affect build products at all. + Warning level is one example. As a consequence, the build system + doesn't try to avoid confusing targets with different values of + incidental properties.
-Features which are not incident are assumed to affect build +
Features which are not incidental are assumed to affect build products, therefore they are put in different directories as described in target paths below.
Usually, each feature takes takes a single value from a fixed set. - In particular, this means that only one value can be used when - building a single target. When a feature is free-valued, it can have - several values at a time and each value can be an arbitrary string. - For example, it is possible to have several preprocessor symbols - defined simultaneously:
+Usually, each feature takes a single value from a fixed set. In + particular, this means that only one value can be used when building + a single target. When a feature is free, it can have several values + at a time and each value can be an arbitrary string. For example, it + is possible to have several preprocessor symbols defined + simultaneously:
<define>NDEBUG=1 <define>HAS_CONFIG_H=1
@@ -125,7 +147,7 @@
A symmetric feature's default value, is not automatically included +
A symmetric feature's default value is not automatically included in build variants. Normally a feature only generates a subvariant directory when its value differs from the value specified by the build variant, leading to an assymmetric @@ -137,7 +159,7 @@
The value of path features specifies a path. The path is treated +
The value of a path feature specifies a path. The path is treated as relative to the directory of Jamfile where path feature is used and is translated appropriately by the build system when the build is invoked from a different directory
@@ -146,19 +168,19 @@features whose values alone identify the feature. For example, a - user is not required to write "<toolset>", 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 +
Values of implicit features alone identify the feature. For + example, a user is not required to write "<toolset>", 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.
features which actually correspond to groups of properties. For - example, a build variant is a composite feature. When generating +
Composite features 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 @@ -171,14 +193,6 @@
See below.
TODO: give a name and describe the property set joined with slashes. I - use the term "property path" somewhere below.
+TODO: document active features..
-It is possible that build system tries to generate a target with a - certain set of properties but is is only possible to obtain a target with - somewhat different property set. It is needed to know if the actual - property set can be used instead of the property set that was needed. At - this moment we use a simple approach to answering that question. Two - property sets are called link-compatible when targets with those - property sets can be used interchangably. In turn, two property sets are - link compatible when there's no link-incompatible feature which has - different values in those property sets.
+When the build system tries to generate a target (such as library + dependency) matching a given build request, it may find that an exact + match isn't possible — for example, the target may impose additonal + build requirements. We need to determine whether a buildable version of + that target can actually be used.
+ +In general, there are many possible situations: a libary which is + dependency of a main target and should be linked into it, target which is + directly requested on the command line, or build executable which is used + in the build process itself. At this moment we use a simple approach.
+ +Two property sets are called link-compatible when targets + with those property sets can be used interchangably. In turn, two + property sets are link compatible when there's no link-incompatible + feature which has different values in those property sets. Whenever + requested and actual properties are link-compatible, it's OK. Otherwise, + it's an error.
Boost.Build extends Jam's command line in two ways. First, command - line arguments can be used not only to specify targets to build, but also - to specify build variants or arbitrary build request. Second, there are - additional command line options.
+The comamnd line may contain:
-For each project, there are several attributes.
-Project id is used to denote the project from other project. - Each project id is a hierarchical path, such as "boost/thread". When - project-id need to be referred from other projects there are two - alternatives:
+Project id is a short way to denote a project, as opposed to + the Jamfile's pathname. It is a hierarchical path, unrelated to + filesystem, such as "boost/thread". There are two ways to refer to a + project using project-id:
Source location specifies directory where sources for the +
Source location specifies the directory where sources for the project are located.
Project requirements are requirements that apply to all the @@ -499,11 +522,11 @@ like list of source and requirement.
It is possible to have different list of sources for different - toolsets, therefore it is possible to invoce main target rules several + toolsets, therefore it is possible to invoke main target rules several times for a single main target. For example:
- exe a.exe : a_gcc.cpp : <toolset> ; - exe a.exe : a.cpp ; + exe a : a_gcc.cpp : <toolset> ; + exe a : a.cpp ;Each call to the 'exe' rule defines a new main target alternative for the main target a.exe. In this case, the @@ -513,8 +536,8 @@
Target identifier is used to denote a target. It is described by the - following grammar:
+Target identifier is used to denote a target. It is described + by the following grammar:
target-id -> project-reference local-target-name
project-reference -> [jamfile-location] [ "@" [project-id] ]
@@ -546,7 +569,7 @@
After that, the target given by local-target-name in the found
project is used.
- Target reference is used to specify a source target, and may
+
Target reference is used to specify a source target, and may
additionally specify desired properties for that target. It has this
syntax:
@@ -557,9 +580,9 @@
exe compiler : compiler.cpp libs/cmdline/<optimization>space ;
- would cause the version of cmdline library, optimized to space,
+ would cause the version of cmdline library, optimized for space,
to be linked in even if the compile executable is build with
- speed optimization.
+ optimization for speed.
Ambiguity resolution
@@ -568,7 +591,7 @@
pathname, it is checked if there's a jamfile in the specified path. If
there is one, it is loaded and if the specified target is declared by
that project it is used. Otherwise, we just treat the target reference as
- file name.
+ a file name.
Target paths
@@ -580,17 +603,18 @@
For example, we might have these paths:
@@ -603,15 +627,17 @@The build works in this way. On startup, the project in the current - directory is read. As the result a tree of projects is constructed. After - that, the build request is constructed from the command line. Then, the - steps are:
+ directory is read. In turn, it may request building of other projects, + which will be loaded recursively. Parent projects are also loaded to + inherit some of their properties. As the result, a tree of projects is + constructed. After that, the build request is constructed from the + command line. Then, the steps are:Last modified: Aug 5, 2002
+Last modified: Aug 12, 2002
© Copyright Vladimir Prus 2002. Permission to copy, use, modify,
sell and distribute this document is granted provided this copyright
diff --git a/new/feature.jam b/new/feature.jam
index 6f3d8e2e3..577ae91e4 100644
--- a/new/feature.jam
+++ b/new/feature.jam
@@ -3,23 +3,6 @@
# all copies. This software is provided "as is" without express or implied
# warranty, and with no claim as to its suitability for any purpose.
-# Glossary
-#
-# feature - a normalized aspect of a build configuration
-#
-# value - a specific available setting for a feature
-#
-# property - a feature-value pair, expressed ase A feature is a normalized (toolset-independent) description
- of an individual build parameter, such as whether inlining is
- enabled. A feature is a normalized (toolset-independent) aspect of a
+ build configuration, such as whether inlining is enabled. A property is a (feature, value) pair. Each features is
- described by a name and the set of attributes from the following
- list: A feature value is a specific available setting for a
+ feature. A property is a (feature,value) pair, expressed as
+ <feature>value. A subfeature is a feature which only exists in the presence
+ of its parent, and whose identity can be derived (in the context of its
+ parent) from the name of its value. A value-string is a string of the form
+ value-subvalue1-subvalue2...-subvalueN, where value is
+ a feature value and subvalue1...subvalueN are values of related
+ subfeatures. For example, by using value-string properties
+ <toolset>gcc <toolset-version>3.0.1, can be expressed more
+ conscicely, as <toolset>gcc-3.0.1. A set of properties is called, naturally, property set. For
+ example, <toolset>gcc <runtime-link>static.
+ Sometimes it's better to represent a property set without spaces. In that
+ case property path is used, which consists of all properties,
+ joined with slashes. To continue with example, property path
+ representation would be
+ <toolset>gcc/<runtime-link>static . Each feature can have any of the following attributes: Incidental features do not affect build products at all. Warning
- level is one example. As a consequence, the build system doesn't try
- to avoid confusing targets with different values of incident
- properties. Incidental features are assumed not affect build products at all.
+ Warning level is one example. As a consequence, the build system
+ doesn't try to avoid confusing targets with different values of
+ incidental properties. Features which are not incident are assumed to affect build
+ Features which are not incidental are assumed to affect build
products, therefore they are put in different directories as
described in target paths below.
@@ -66,24 +66,46 @@
Definition
-
Usually, each feature takes takes a single value from a fixed set. - In particular, this means that only one value can be used when - building a single target. When a feature is free-valued, it can have - several values at a time and each value can be an arbitrary string. - For example, it is possible to have several preprocessor symbols - defined simultaneously:
+Usually, each feature takes a single value from a fixed set. In + particular, this means that only one value can be used when building + a single target. When a feature is free, it can have several values + at a time and each value can be an arbitrary string. For example, it + is possible to have several preprocessor symbols defined + simultaneously:
<define>NDEBUG=1 <define>HAS_CONFIG_H=1
@@ -125,7 +147,7 @@
A symmetric feature's default value, is not automatically included +
A symmetric feature's default value is not automatically included in build variants. Normally a feature only generates a subvariant directory when its value differs from the value specified by the build variant, leading to an assymmetric @@ -137,7 +159,7 @@
The value of path features specifies a path. The path is treated +
The value of a path feature specifies a path. The path is treated as relative to the directory of Jamfile where path feature is used and is translated appropriately by the build system when the build is invoked from a different directory
@@ -146,19 +168,19 @@features whose values alone identify the feature. For example, a - user is not required to write "<toolset>", 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 +
Values of implicit features alone identify the feature. For + example, a user is not required to write "<toolset>", 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.
features which actually correspond to groups of properties. For - example, a build variant is a composite feature. When generating +
Composite features 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 @@ -171,14 +193,6 @@
See below.
TODO: give a name and describe the property set joined with slashes. I - use the term "property path" somewhere below.
+TODO: document active features..
-It is possible that build system tries to generate a target with a - certain set of properties but is is only possible to obtain a target with - somewhat different property set. It is needed to know if the actual - property set can be used instead of the property set that was needed. At - this moment we use a simple approach to answering that question. Two - property sets are called link-compatible when targets with those - property sets can be used interchangably. In turn, two property sets are - link compatible when there's no link-incompatible feature which has - different values in those property sets.
+When the build system tries to generate a target (such as library + dependency) matching a given build request, it may find that an exact + match isn't possible — for example, the target may impose additonal + build requirements. We need to determine whether a buildable version of + that target can actually be used.
+ +In general, there are many possible situations: a libary which is + dependency of a main target and should be linked into it, target which is + directly requested on the command line, or build executable which is used + in the build process itself. At this moment we use a simple approach.
+ +Two property sets are called link-compatible when targets + with those property sets can be used interchangably. In turn, two + property sets are link compatible when there's no link-incompatible + feature which has different values in those property sets. Whenever + requested and actual properties are link-compatible, it's OK. Otherwise, + it's an error.
Boost.Build extends Jam's command line in two ways. First, command - line arguments can be used not only to specify targets to build, but also - to specify build variants or arbitrary build request. Second, there are - additional command line options.
+The comamnd line may contain:
-For each project, there are several attributes.
-Project id is used to denote the project from other project. - Each project id is a hierarchical path, such as "boost/thread". When - project-id need to be referred from other projects there are two - alternatives:
+Project id is a short way to denote a project, as opposed to + the Jamfile's pathname. It is a hierarchical path, unrelated to + filesystem, such as "boost/thread". There are two ways to refer to a + project using project-id:
Source location specifies directory where sources for the +
Source location specifies the directory where sources for the project are located.
Project requirements are requirements that apply to all the @@ -499,11 +522,11 @@ like list of source and requirement.
It is possible to have different list of sources for different - toolsets, therefore it is possible to invoce main target rules several + toolsets, therefore it is possible to invoke main target rules several times for a single main target. For example:
- exe a.exe : a_gcc.cpp : <toolset> ; - exe a.exe : a.cpp ; + exe a : a_gcc.cpp : <toolset> ; + exe a : a.cpp ;Each call to the 'exe' rule defines a new main target alternative for the main target a.exe. In this case, the @@ -513,8 +536,8 @@
Target identifier is used to denote a target. It is described by the - following grammar:
+Target identifier is used to denote a target. It is described + by the following grammar:
target-id -> project-reference local-target-name
project-reference -> [jamfile-location] [ "@" [project-id] ]
@@ -546,7 +569,7 @@
After that, the target given by local-target-name in the found
project is used.
- Target reference is used to specify a source target, and may
+
Target reference is used to specify a source target, and may
additionally specify desired properties for that target. It has this
syntax:
@@ -557,9 +580,9 @@
exe compiler : compiler.cpp libs/cmdline/<optimization>space ;
- would cause the version of cmdline library, optimized to space,
+ would cause the version of cmdline library, optimized for space,
to be linked in even if the compile executable is build with
- speed optimization.
+ optimization for speed.
Ambiguity resolution
@@ -568,7 +591,7 @@
pathname, it is checked if there's a jamfile in the specified path. If
there is one, it is loaded and if the specified target is declared by
that project it is used. Otherwise, we just treat the target reference as
- file name.
+ a file name.
Target paths
@@ -580,17 +603,18 @@
For example, we might have these paths:
@@ -603,15 +627,17 @@The build works in this way. On startup, the project in the current - directory is read. As the result a tree of projects is constructed. After - that, the build request is constructed from the command line. Then, the - steps are:
+ directory is read. In turn, it may request building of other projects, + which will be loaded recursively. Parent projects are also loaded to + inherit some of their properties. As the result, a tree of projects is + constructed. After that, the build request is constructed from the + command line. Then, the steps are:Last modified: Aug 5, 2002
+Last modified: Aug 12, 2002
© Copyright Vladimir Prus 2002. Permission to copy, use, modify,
sell and distribute this document is granted provided this copyright
diff --git a/v2/build/feature.jam b/v2/build/feature.jam
index 6f3d8e2e3..577ae91e4 100644
--- a/v2/build/feature.jam
+++ b/v2/build/feature.jam
@@ -3,23 +3,6 @@
# all copies. This software is provided "as is" without express or implied
# warranty, and with no claim as to its suitability for any purpose.
-# Glossary
-#
-# feature - a normalized aspect of a build configuration
-#
-# value - a specific available setting for a feature
-#
-# property - a feature-value pair, expressed ase