From bf2af771cc6599a55abe8646a567b1411c6374cd Mon Sep 17 00:00:00 2001 From: Vladimir Prus Date: Tue, 16 Jul 2002 08:47:09 +0000 Subject: [PATCH] An attempt at documenting features. [SVN r14474] --- boost_build_v2.html | 239 ++++++++++++++++++++++++++++++++++++----- v2/boost_build_v2.html | 239 ++++++++++++++++++++++++++++++++++++----- 2 files changed, 424 insertions(+), 54 deletions(-) diff --git a/boost_build_v2.html b/boost_build_v2.html index bdeb66580..e5d7e04c6 100644 --- a/boost_build_v2.html +++ b/boost_build_v2.html @@ -17,7 +17,7 @@ img.banner { border: 0; float: left } h1 { text-align: right } br.clear { clear: left } - p.alert { color: red } + div.alert { color: red } table { align: center; border: thin; } @@ -30,8 +30,13 @@
-

This is preliminary version intended to document - everything implemeneted but not yet ready for any practical use.

+
+ This is preliminary version intended to document everything + implemeneted but not yet ready for any practical use. +
+
+
+
@@ -61,15 +66,185 @@

Definition

+

A feature is a normalized (toolset-independent) description + of an individual build parameter, 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:

+ + +

TODO: give a name and describe the property set joined with slashes. I use the term "property path" somewhere below.

Link compatible and imcompatible properties

+

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 that + 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.

+

Definition of property refinement

+

When a target with certain properties is requested, and that target + requires some set of properties, it is needed to find the set of + properties to use for building. This process is called property + refinement and is performed by these rules

+ +
    +
  1. If original properties and required properties are not + link-compatible, refinement fails.
    2. + +
  2. Each property in the required set is added to the original property + set
    3. + +
  3. If the original property set includes property with a different + value of non free-valued feature, that property is removed.
    4. +
+

Initialization

+

Immediately upon startup, the bjam executable attempts to + find the location of build system files. It does so by looking for a file + called boost-build.jam. That file is first looked in the + invocation directory and its parents up to the filesystem root, and then + in the directories from variable BOOST_BUILD_PATH. When found, the file + is loaded and should specify the build system location by calling the + boost-build rule:

+
+    rule boost-build ( location ? )
+   
+
+ The directory specified by location and directories in + BOOST_BUILD_PATH are searched for a file called + bootstrap.jam which is loaded and completes startup. + +

This arrangement allows to make build system work without any + environmental variables. For example, build system files can be placed in + a directory boost-build at your project root, and a file + boost-build.jam at the project root can contain:

+
+    boost-build boost-build ;
+   
+
+ In this case, running bjam in the project root will + automatically find the build system. +

Command line

Boost.Build extends Jam's command line in two ways. First, command @@ -162,8 +337,9 @@ --help - Access to the online help system. This prints general information - on how to use the help system with additional --help* options. + Access to the online help system. This prints general + information on how to use the help system with additional --help* + options. @@ -389,6 +565,36 @@ that project it is used. Otherwise, we just treat the target reference as file name.

+

Target paths

+ +

To distinguish targets build with different properties, they are put + in different directories. Rules for determining target paths are given + below:

+ +
    +
  1. All targets are placed under directory corresponding to the project + where they are defined.
    2. + +
  2. Each non free-valued, non incident property cause an additional + element to be added to the target path. That element has the form + <feature-name>-<feature-value> for ordinary + features and <feature-value> for implicit ones. [Note + about composite features].
    3. + +
  3. If the set of free-valued properties is different from the set of + free valued properties for the project to which the target belong, a + part of the form main_target-<name> is added to the + target path. Note:It would be nice to track free-valued features + also, but this appears to be complex and not extremely needed.
    4. +
+ +

For example, we might have these paths:

+
+    debug/optimization-off
+    debug/main-target-a
+   
+
+

Build process

The build works in this way. On startup, the project in the current @@ -432,30 +638,9 @@

The dependency graph constructed for each target is build of so called "virtual targets", which do not yet correspond to jam's targets. It is therefore converted to jam's dependency graph which is then build.

- -

The paths for build targets are determined with a method having two - properties. First, non-free features are represented in path. Second, - free features are not represented in path (because that would make them - overly long), but two targets with different free features are never - mixed. Each project has a base directory for all its target.

- -

Path for each target is relative to the base and has two components. - The first component represents all non-free features used to build the - target. If the set of free properties used to build the target is equal - to the set of free properties in the project's requirements, then the - second component is empty. Otherwise, the second part has the form - "main_target-<name>", where "name" is the name of main target which - build required the current target.

- -

For example, we might have these paths:

-
-    debug/optimization-off
-    debug/main-target-a
-   
-
-

Last modified: July 7, 2002

+

Last modified: July 16, 2002

© Copyright Vladimir Prus 2002. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright diff --git a/v2/boost_build_v2.html b/v2/boost_build_v2.html index bdeb66580..e5d7e04c6 100644 --- a/v2/boost_build_v2.html +++ b/v2/boost_build_v2.html @@ -17,7 +17,7 @@ img.banner { border: 0; float: left } h1 { text-align: right } br.clear { clear: left } - p.alert { color: red } + div.alert { color: red } table { align: center; border: thin; } @@ -30,8 +30,13 @@

-

This is preliminary version intended to document - everything implemeneted but not yet ready for any practical use.

+
+ This is preliminary version intended to document everything + implemeneted but not yet ready for any practical use. +
+
+
+
@@ -61,15 +66,185 @@

Definition

+

A feature is a normalized (toolset-independent) description + of an individual build parameter, 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:

+ +
    +
  • + incident + +

    Incident 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.

    + +

    Features which are not incident are assumed to affect build + products, therefore they are put in different directories as + described in target paths below.

    +
    • + +
  • + propagated + +

    Features of this kind are propagated to depencies. That is, if a + main target is build with particular value of a propagated feature, + the build systems attempts to build all the source targets with the + same value of that feature.

    +
    • + +
  • + free-valued + +

    Usually, each feature takes values from a fixed set. In addition, + only one value can be used to build a single target. When a feature + is free-valued, it can have several values at a time and each value + can be arbitrary string. For example, it is possible to have several + preprocessor symbols defined at the same time, and each value can be + any string.

    +
    • + +
  • + optional + +

    An optional feature is not required to have a value during build. + When a value of non-optional feature is not specified, it is always + given the default value.

    +
    • + +
  • + symmetric + +

    There exists so called build variants, which are major + predefined sets of properties. Ordinary, features without explictly + specified value in a given variant are given their default value. + [Otherwise, we'd have to specify value of each features]. Symmetric + features differs by the fact that they are not included in build + variants.

    + +
    + Need to explain why they are called "symmetric" +
    +
    • + +
  • + path + +

    The value of path features specifies a path. The path is treated + as relative to the directory of Jamfile where path feature is + used.

    +
    • + +
  • + implicit + +

    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 + features, to avoid possible name clashes.

    +
    • + +
  • + 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.

    +
    • + +
  • + link-incompatible + +

    See below.

    +
    • + +
  • + executed + +
    + Do we need it? +
    +
    • + +
  • + dependency + +
    + Do we need it? +
    +
    • +
+

TODO: give a name and describe the property set joined with slashes. I use the term "property path" somewhere below.

Link compatible and imcompatible properties

+

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 that + 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.

+

Definition of property refinement

+

When a target with certain properties is requested, and that target + requires some set of properties, it is needed to find the set of + properties to use for building. This process is called property + refinement and is performed by these rules

+ +
    +
  1. If original properties and required properties are not + link-compatible, refinement fails.
    2. + +
  2. Each property in the required set is added to the original property + set
    3. + +
  3. If the original property set includes property with a different + value of non free-valued feature, that property is removed.
    4. +
+

Initialization

+

Immediately upon startup, the bjam executable attempts to + find the location of build system files. It does so by looking for a file + called boost-build.jam. That file is first looked in the + invocation directory and its parents up to the filesystem root, and then + in the directories from variable BOOST_BUILD_PATH. When found, the file + is loaded and should specify the build system location by calling the + boost-build rule:

+
+    rule boost-build ( location ? )
+   
+
+ The directory specified by location and directories in + BOOST_BUILD_PATH are searched for a file called + bootstrap.jam which is loaded and completes startup. + +

This arrangement allows to make build system work without any + environmental variables. For example, build system files can be placed in + a directory boost-build at your project root, and a file + boost-build.jam at the project root can contain:

+
+    boost-build boost-build ;
+   
+
+ In this case, running bjam in the project root will + automatically find the build system. +

Command line

Boost.Build extends Jam's command line in two ways. First, command @@ -162,8 +337,9 @@ --help - Access to the online help system. This prints general information - on how to use the help system with additional --help* options. + Access to the online help system. This prints general + information on how to use the help system with additional --help* + options. @@ -389,6 +565,36 @@ that project it is used. Otherwise, we just treat the target reference as file name.

+

Target paths

+ +

To distinguish targets build with different properties, they are put + in different directories. Rules for determining target paths are given + below:

+ +
    +
  1. All targets are placed under directory corresponding to the project + where they are defined.
    2. + +
  2. Each non free-valued, non incident property cause an additional + element to be added to the target path. That element has the form + <feature-name>-<feature-value> for ordinary + features and <feature-value> for implicit ones. [Note + about composite features].
    3. + +
  3. If the set of free-valued properties is different from the set of + free valued properties for the project to which the target belong, a + part of the form main_target-<name> is added to the + target path. Note:It would be nice to track free-valued features + also, but this appears to be complex and not extremely needed.
    4. +
+ +

For example, we might have these paths:

+
+    debug/optimization-off
+    debug/main-target-a
+   
+
+

Build process

The build works in this way. On startup, the project in the current @@ -432,30 +638,9 @@

The dependency graph constructed for each target is build of so called "virtual targets", which do not yet correspond to jam's targets. It is therefore converted to jam's dependency graph which is then build.

- -

The paths for build targets are determined with a method having two - properties. First, non-free features are represented in path. Second, - free features are not represented in path (because that would make them - overly long), but two targets with different free features are never - mixed. Each project has a base directory for all its target.

- -

Path for each target is relative to the base and has two components. - The first component represents all non-free features used to build the - target. If the set of free properties used to build the target is equal - to the set of free properties in the project's requirements, then the - second component is empty. Otherwise, the second part has the form - "main_target-<name>", where "name" is the name of main target which - build required the current target.

- -

For example, we might have these paths:

-
-    debug/optimization-off
-    debug/main-target-a
-   
-
-

Last modified: July 7, 2002

+

Last modified: July 16, 2002

© Copyright Vladimir Prus 2002. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright