mirror of
https://github.com/boostorg/build.git
synced 2026-02-17 13:42:14 +00:00
An attempt at documenting features.
[SVN r14474]
This commit is contained in:
Vladimir Prus
@@ -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; }
|
||||
</style>
|
||||
</head>
|
||||
@@ -30,8 +30,13 @@
|
||||
</h1>
|
||||
<hr>
|
||||
|
||||
<p class="alert">This is preliminary version intended to document
|
||||
everything implemeneted but not yet ready for any practical use.</p>
|
||||
<div class="alert">
|
||||
This is preliminary version intended to document everything
|
||||
implemeneted but not yet ready for any practical use.
|
||||
</div>
|
||||
<br>
|
||||
<br>
|
||||
|
||||
<hr>
|
||||
|
||||
<dl class="page-index">
|
||||
@@ -61,15 +66,185 @@
|
||||
|
||||
<h4>Definition</h4>
|
||||
|
||||
<p>A <em>feature</em> is a normalized (toolset-independent) description
|
||||
of an individual build parameter, such as whether inlining is
|
||||
enabled.</p>
|
||||
|
||||
<p>A <em>property</em> is a (feature, value) pair. Each features is
|
||||
described by a name and the set of attributes from the following
|
||||
list:</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<em>incident</em>
|
||||
|
||||
<p>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.</p>
|
||||
|
||||
<p>Features which are not incident are assumed to affect build
|
||||
products, therefore they are put in different directories as
|
||||
described in <a href="#target_paths">target paths</a> below.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>propagated</em>
|
||||
|
||||
<p>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.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>free-valued</em>
|
||||
|
||||
<p>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.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>optional</em>
|
||||
|
||||
<p>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.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>symmetric</em>
|
||||
|
||||
<p>There exists so called <em>build variants</em>, 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.</p>
|
||||
|
||||
<div class="alert">
|
||||
Need to explain why they are called "symmetric"
|
||||
</div>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>path</em>
|
||||
|
||||
<p>The value of path features specifies a path. The path is treated
|
||||
as relative to the directory of Jamfile where path feature is
|
||||
used.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>implicit</em>
|
||||
|
||||
<p>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.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>composite</em>
|
||||
|
||||
<p>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.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>link-incompatible</em>
|
||||
|
||||
<p>See <a href="#link_compatibility">below</a>.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>executed</em>
|
||||
|
||||
<div class="alert">
|
||||
Do we need it?
|
||||
</div>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>dependency</em>
|
||||
|
||||
<div class="alert">
|
||||
Do we need it?
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p>TODO: give a name and describe the property set joined with slashes. I
|
||||
use the term "property path" somewhere below.</p>
|
||||
|
||||
<h4>Link compatible and imcompatible properties</h4>
|
||||
|
||||
<p>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 <em>link-compatible</em> 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.</p>
|
||||
|
||||
<h4>Definition of property refinement</h4>
|
||||
|
||||
<p>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 <em>property
|
||||
refinement</em> and is performed by these rules</p>
|
||||
|
||||
<ol>
|
||||
<li>If original properties and required properties are not
|
||||
link-compatible, refinement fails.</li>
|
||||
|
||||
<li>Each property in the required set is added to the original property
|
||||
set</li>
|
||||
|
||||
<li>If the original property set includes property with a different
|
||||
value of non free-valued feature, that property is removed.</li>
|
||||
</ol>
|
||||
|
||||
<h3><a name="initialization">Initialization</a></h3>
|
||||
|
||||
<p>Immediately upon startup, the <tt>bjam</tt> executable attempts to
|
||||
find the location of build system files. It does so by looking for a file
|
||||
called <tt>boost-build.jam</tt>. 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
|
||||
<tt>boost-build</tt> rule:</p>
|
||||
<pre>
|
||||
rule boost-build ( location ? )
|
||||
|
||||
</pre>
|
||||
The directory specified by location and directories in
|
||||
<tt>BOOST_BUILD_PATH</tt> are searched for a file called
|
||||
<tt>bootstrap.jam</tt> which is loaded and completes startup.
|
||||
|
||||
<p>This arrangement allows to make build system work without any
|
||||
environmental variables. For example, build system files can be placed in
|
||||
a directory <tt>boost-build</tt> at your project root, and a file
|
||||
<tt>boost-build.jam</tt> at the project root can contain:</p>
|
||||
<pre>
|
||||
boost-build boost-build ;
|
||||
|
||||
</pre>
|
||||
In this case, running <tt>bjam</tt> in the project root will
|
||||
automatically find the build system.
|
||||
|
||||
<h3><a name="command_line">Command line</a></h3>
|
||||
|
||||
<p>Boost.Build extends Jam's command line in two ways. First, command
|
||||
@@ -162,8 +337,9 @@
|
||||
<tr>
|
||||
<td><tt>--help</tt></td>
|
||||
|
||||
<td>Access to the online help system. This prints general information
|
||||
on how to use the help system with additional --help* options.</td>
|
||||
<td>Access to the online help system. This prints general
|
||||
information on how to use the help system with additional --help*
|
||||
options.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
@@ -389,6 +565,36 @@
|
||||
that project it is used. Otherwise, we just treat the target reference as
|
||||
file name.</p>
|
||||
|
||||
<h4>Target paths</h4>
|
||||
|
||||
<p>To distinguish targets build with different properties, they are put
|
||||
in different directories. Rules for determining target paths are given
|
||||
below:</p>
|
||||
|
||||
<ol>
|
||||
<li>All targets are placed under directory corresponding to the project
|
||||
where they are defined.</li>
|
||||
|
||||
<li>Each non free-valued, non incident property cause an additional
|
||||
element to be added to the target path. That element has the form
|
||||
<tt><feature-name>-<feature-value></tt> for ordinary
|
||||
features and <tt><feature-value></tt> for implicit ones. [Note
|
||||
about composite features].</li>
|
||||
|
||||
<li>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 <tt>main_target-<name></tt> is added to the
|
||||
target path. <b>Note:</b>It would be nice to track free-valued features
|
||||
also, but this appears to be complex and not extremely needed.</li>
|
||||
</ol>
|
||||
|
||||
<p>For example, we might have these paths:</p>
|
||||
<pre>
|
||||
debug/optimization-off
|
||||
debug/main-target-a
|
||||
|
||||
</pre>
|
||||
|
||||
<h3><a name="build_process">Build process</a></h3>
|
||||
|
||||
<p>The build works in this way. On startup, the project in the current
|
||||
@@ -432,30 +638,9 @@
|
||||
<p>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.</p>
|
||||
|
||||
<p>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.</p>
|
||||
|
||||
<p>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.</p>
|
||||
|
||||
<p>For example, we might have these paths:</p>
|
||||
<pre>
|
||||
debug/optimization-off
|
||||
debug/main-target-a
|
||||
|
||||
</pre>
|
||||
<hr>
|
||||
|
||||
<p class="revision">Last modified: July 7, 2002</p>
|
||||
<p class="revision">Last modified: July 16, 2002</p>
|
||||
|
||||
<p>© Copyright Vladimir Prus 2002. Permission to copy, use, modify,
|
||||
sell and distribute this document is granted provided this copyright
|
||||
|
||||
@@ -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; }
|
||||
</style>
|
||||
</head>
|
||||
@@ -30,8 +30,13 @@
|
||||
</h1>
|
||||
<hr>
|
||||
|
||||
<p class="alert">This is preliminary version intended to document
|
||||
everything implemeneted but not yet ready for any practical use.</p>
|
||||
<div class="alert">
|
||||
This is preliminary version intended to document everything
|
||||
implemeneted but not yet ready for any practical use.
|
||||
</div>
|
||||
<br>
|
||||
<br>
|
||||
|
||||
<hr>
|
||||
|
||||
<dl class="page-index">
|
||||
@@ -61,15 +66,185 @@
|
||||
|
||||
<h4>Definition</h4>
|
||||
|
||||
<p>A <em>feature</em> is a normalized (toolset-independent) description
|
||||
of an individual build parameter, such as whether inlining is
|
||||
enabled.</p>
|
||||
|
||||
<p>A <em>property</em> is a (feature, value) pair. Each features is
|
||||
described by a name and the set of attributes from the following
|
||||
list:</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<em>incident</em>
|
||||
|
||||
<p>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.</p>
|
||||
|
||||
<p>Features which are not incident are assumed to affect build
|
||||
products, therefore they are put in different directories as
|
||||
described in <a href="#target_paths">target paths</a> below.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>propagated</em>
|
||||
|
||||
<p>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.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>free-valued</em>
|
||||
|
||||
<p>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.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>optional</em>
|
||||
|
||||
<p>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.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>symmetric</em>
|
||||
|
||||
<p>There exists so called <em>build variants</em>, 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.</p>
|
||||
|
||||
<div class="alert">
|
||||
Need to explain why they are called "symmetric"
|
||||
</div>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>path</em>
|
||||
|
||||
<p>The value of path features specifies a path. The path is treated
|
||||
as relative to the directory of Jamfile where path feature is
|
||||
used.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>implicit</em>
|
||||
|
||||
<p>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.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>composite</em>
|
||||
|
||||
<p>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.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>link-incompatible</em>
|
||||
|
||||
<p>See <a href="#link_compatibility">below</a>.</p>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>executed</em>
|
||||
|
||||
<div class="alert">
|
||||
Do we need it?
|
||||
</div>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<em>dependency</em>
|
||||
|
||||
<div class="alert">
|
||||
Do we need it?
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p>TODO: give a name and describe the property set joined with slashes. I
|
||||
use the term "property path" somewhere below.</p>
|
||||
|
||||
<h4>Link compatible and imcompatible properties</h4>
|
||||
|
||||
<p>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 <em>link-compatible</em> 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.</p>
|
||||
|
||||
<h4>Definition of property refinement</h4>
|
||||
|
||||
<p>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 <em>property
|
||||
refinement</em> and is performed by these rules</p>
|
||||
|
||||
<ol>
|
||||
<li>If original properties and required properties are not
|
||||
link-compatible, refinement fails.</li>
|
||||
|
||||
<li>Each property in the required set is added to the original property
|
||||
set</li>
|
||||
|
||||
<li>If the original property set includes property with a different
|
||||
value of non free-valued feature, that property is removed.</li>
|
||||
</ol>
|
||||
|
||||
<h3><a name="initialization">Initialization</a></h3>
|
||||
|
||||
<p>Immediately upon startup, the <tt>bjam</tt> executable attempts to
|
||||
find the location of build system files. It does so by looking for a file
|
||||
called <tt>boost-build.jam</tt>. 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
|
||||
<tt>boost-build</tt> rule:</p>
|
||||
<pre>
|
||||
rule boost-build ( location ? )
|
||||
|
||||
</pre>
|
||||
The directory specified by location and directories in
|
||||
<tt>BOOST_BUILD_PATH</tt> are searched for a file called
|
||||
<tt>bootstrap.jam</tt> which is loaded and completes startup.
|
||||
|
||||
<p>This arrangement allows to make build system work without any
|
||||
environmental variables. For example, build system files can be placed in
|
||||
a directory <tt>boost-build</tt> at your project root, and a file
|
||||
<tt>boost-build.jam</tt> at the project root can contain:</p>
|
||||
<pre>
|
||||
boost-build boost-build ;
|
||||
|
||||
</pre>
|
||||
In this case, running <tt>bjam</tt> in the project root will
|
||||
automatically find the build system.
|
||||
|
||||
<h3><a name="command_line">Command line</a></h3>
|
||||
|
||||
<p>Boost.Build extends Jam's command line in two ways. First, command
|
||||
@@ -162,8 +337,9 @@
|
||||
<tr>
|
||||
<td><tt>--help</tt></td>
|
||||
|
||||
<td>Access to the online help system. This prints general information
|
||||
on how to use the help system with additional --help* options.</td>
|
||||
<td>Access to the online help system. This prints general
|
||||
information on how to use the help system with additional --help*
|
||||
options.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
@@ -389,6 +565,36 @@
|
||||
that project it is used. Otherwise, we just treat the target reference as
|
||||
file name.</p>
|
||||
|
||||
<h4>Target paths</h4>
|
||||
|
||||
<p>To distinguish targets build with different properties, they are put
|
||||
in different directories. Rules for determining target paths are given
|
||||
below:</p>
|
||||
|
||||
<ol>
|
||||
<li>All targets are placed under directory corresponding to the project
|
||||
where they are defined.</li>
|
||||
|
||||
<li>Each non free-valued, non incident property cause an additional
|
||||
element to be added to the target path. That element has the form
|
||||
<tt><feature-name>-<feature-value></tt> for ordinary
|
||||
features and <tt><feature-value></tt> for implicit ones. [Note
|
||||
about composite features].</li>
|
||||
|
||||
<li>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 <tt>main_target-<name></tt> is added to the
|
||||
target path. <b>Note:</b>It would be nice to track free-valued features
|
||||
also, but this appears to be complex and not extremely needed.</li>
|
||||
</ol>
|
||||
|
||||
<p>For example, we might have these paths:</p>
|
||||
<pre>
|
||||
debug/optimization-off
|
||||
debug/main-target-a
|
||||
|
||||
</pre>
|
||||
|
||||
<h3><a name="build_process">Build process</a></h3>
|
||||
|
||||
<p>The build works in this way. On startup, the project in the current
|
||||
@@ -432,30 +638,9 @@
|
||||
<p>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.</p>
|
||||
|
||||
<p>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.</p>
|
||||
|
||||
<p>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.</p>
|
||||
|
||||
<p>For example, we might have these paths:</p>
|
||||
<pre>
|
||||
debug/optimization-off
|
||||
debug/main-target-a
|
||||
|
||||
</pre>
|
||||
<hr>
|
||||
|
||||
<p class="revision">Last modified: July 7, 2002</p>
|
||||
<p class="revision">Last modified: July 16, 2002</p>
|
||||
|
||||
<p>© Copyright Vladimir Prus 2002. Permission to copy, use, modify,
|
||||
sell and distribute this document is granted provided this copyright
|
||||
|
||||
Reference in New Issue
Block a user