boost/build
2
0
Fork 0
mirror of https://github.com/boostorg/build.git synced 2026-02-13 12:22:17 +00:00
Code Issues Projects Releases Wiki Activity

Document features (#498)

Browse Source 
* move feature documentation into each feature's source file

* sort features in the docs

* updated docs for features
This commit is contained in:
Dmitry
2019-10-28 15:22:42 +03:00
committed by Rene Rivera
parent ffecbecf86
commit b54f53ccbc
52 changed files with 952 additions and 510 deletions
Download Patch File Download Diff File Expand all files Collapse all files

423
doc/src/reference.adoc
View File

@@ -206,365 +206,70 @@ This section documents the features that are built-in into Boost.Build.
For features with a fixed set of values, that set is provided, with the
default value listed first.
[[bbv2.builtin.features.variant]]`variant`::
*Allowed values:* `debug`, `release`, `profile`.
+
A feature combining several low-level features, making it easy to
request common build configurations.
+
The value `debug` expands to
+
----
<optimization>off <debug-symbols>on <inlining>off <runtime-debugging>on
----
+
The value `release` expands to
+
----
<optimization>speed <debug-symbols>off <inlining>full <runtime-debugging>off
----
+
The value `profile` expands to the same as `release`, plus:
+
----
<profiling>on <debug-symbols>on
----
+
Users can define their own build variants using the `variant` rule
from the `common` module.
+
NOTE: Runtime debugging is on in debug builds to suit the expectations of
people used to various IDEs.
[[bbv2.builtin.features.link]]`link`::
*Allowed values:* `shared`, `static`
+
A feature controlling how libraries are built.
[[bbv2.builtin.features.runtime-link]]`runtime-link`::
*Allowed values:* `shared`, `static`
+
Controls if a static or shared C/{CPP} runtime should be used. There are
some restrictions how this feature can be used, for example on some
compilers an application using static runtime should not use shared
libraries at all, and on some compilers, mixing static and shared
runtime requires extreme care. Check your compiler documentation for
more details.
[[bbv2.builtin.features.threading]]`threading`::
*Allowed values:* `single`, `multi`
+
Controls if the project should be built in multi-threaded mode. This
feature does not necessary change code generation in the compiler, but
it causes the compiler to link to additional or different runtime
libraries, and define additional preprocessor symbols (for example,
`_MT` on Windows and `_REENTRANT` on Linux). How those symbols affect
the compiled code depends on the code itself.
[[bbv2.builtin.features.source]]`source`::
The `<source>X` feature has the same effect on building a target as
putting X in the list of sources. It is useful when you want to add
the same source to all targets in the project (you can put <source> in
requirements) or to conditionally include a source (using conditional
requirements, see
link:#bbv2.tutorial.conditions[the section called “Conditions and alternatives”]).
See also the `<library>` feature.
[[bbv2.builtin.features.library]]`library`::
This feature is almost equivalent to the `<source>` feature, except
that it takes effect only for linking. When you want to link all
targets in a Jamfile to certain library, the `<library>` feature is
preferred over `<source>X`--the latter will add the library to all
targets, even those that have nothing to do with libraries.
[[bbv2.builtin.features.dependency]]`dependency`::
Introduces a dependency on the target named by the value of this
feature (so it will be brought up-to-date whenever the target being
declared is). The dependency is not used in any other way.
[[bbv2.builtin.features.implicit-dependency]]`implicit-dependency`::
Indicates that the target named by the value of this feature may
produce files that are included by the sources of the target being
declared. See
link:#bbv2.reference.generated_headers[the section called “Generated headers”]
for more information.
[[bbv2.builtin.features.use]]`use`::
Introduces a dependency on the target named by the value of this
feature (so it will be brought up-to-date whenever the target being
declared is), and adds its usage requirements to the build properties
of the target being declared. The dependency is not used in any other
way. The primary use case is when you want the usage requirements
(such as `#include` paths) of some library to be applied, but do not
want to link to it.
[[bbv2.builtin.features.dll-path]]`dll-path`::
Specify an additional directory where the system should look for
shared libraries when the executable or shared library is run. This
feature only affects Unix compilers. Please see
link:#bbv2.faq.dll-path[the FAQ: “Why are the dll-path and hardcode-dll-paths properties useful? ”]
in link:#bbv2.faq[Frequently Asked Questions] for details.
[[bbv2.builtin.features.hardcode-dll-paths]]`hardcode-dll-paths`::
*Allowed values:* `true`, `false`.
+
Controls automatic generation of dll-path properties.
+
This property is specific to Unix systems. If an executable is built with
`<hardcode-dll-paths>true`, the generated binary will contain the list of all
the paths to the used shared libraries. As the result, the executable can be
run without changing system paths to shared libraries or installing the
libraries to system paths. This is very convenient during development.
Please see the link:#bbv2.faq.dll-path[FAQ entry] for details. Note
that on Mac OSX, the paths are unconditionally hardcoded by the
linker, and it is not possible to disable that behavior
[[bbv2.builtin.features.flags]]`cflags`; `cxxflags`; `linkflags`::
The value of those features is passed without modification to the
corresponding tools. For `cflags` that is both the C and {CPP}
compilers, for `cxxflags` that is the {CPP} compiler, and for
`linkflags` that is the linker. The features are handy when you are
trying to do something special that cannot be achieved by a
higher-level feature in Boost.Build.
[[bbv2.builtin.features.include]]`include`::
Specifies an additional include path that is to be passed to C and {CPP}
compilers.
[[bbv2.builtin.features.define]]`define`::
Specifies an preprocessor symbol that should be defined on the command
line. You may either specify just the symbol, which will be defined
without any value, or both the symbol and the value, separated by
equal sign.
[[bbv2.builtin.features.warnings]]`warnings`::
The `<warnings>` feature controls the warning level of compilers. It
has the following values:
+
* `off` - disables all warnings.
* `on` - enables default warning level for the tool.
* `all` - enables all warnings.
+
Default value is `all`.
[[bbv2.builtin.features.warnings-as-errors]]`warnings-as-errors`::
The `<warnings-as-errors>` makes it possible to treat warnings as
errors and abort compilation on a warning. The value `on` enables this
behavior. The default value is `off`.
[[bbv2.builtin.features.coverage]]`coverage`::
The `<coverage>` feature controls whether the code is instrumented to
generate coverage data during execution.
The value `on` enables this. The default value is `off`.
[[bbv2.builtin.features.build]]`build`::
*Allowed values:* `no`
+
The `build` feature is used to conditionally disable build of a
target. If `<build>no` is in properties when building a target, build
of that target is skipped. Combined with conditional requirements this
allows you to skip building some target in configurations where the
build is known to fail.
[[bbv2.builtin.features.tag]]`tag`::
The `tag` feature is used to customize the name of the generated
files. The value should have the form:
+
----
@rulename
----
+
where _rulename_ should be a name of a rule with the following
signature:
+
----
rule tag ( name : type ? : property-set )
----
+
The rule will be called for each target with the default name computed
by Boost.Build, the type of the target, and property set. The rule can
either return a string that must be used as the name of the target, or
an empty string, in which case the default name will be used.
+
Most typical use of the `tag` feature is to encode build properties,
or library version in library target names. You should take care to
return non-empty string from the tag rule only for types you care
about -- otherwise, you might end up modifying names of object files,
generated header file and other targets for which changing names does
not make sense.
[[bbv2.builtin.features.debug-symbols]]`debug-symbols`::
*Allowed values:* `on`, `off`.
+
The `debug-symbols` feature specifies if produced object files,
executables, and libraries should include debug information.
Typically, the value of this feature is implicitly set by the
`variant` feature, but it can be explicitly specified by the user. The
most common usage is to build release variant with debugging
information.
[[bbv2.builtin.features.runtime-debugging]]`runtime-debugging`::
*Allowed values:* `on`, `off`.
+
The `runtime-debugging` feature specifies whether produced object
files, executables, and libraries should include behavior useful only
for debugging, such as asserts. Typically, the value of this feature
is implicitly set by the `variant` feature, but it can be explicitly
specified by the user. The most common usage is to build release
variant with debugging output.
[[bbv2.builtin.features.target-os]]`target-os`::
The operating system for which the code is to be generated. The
compiler you used should be the compiler for that operating system.
This option causes Boost.Build to use naming conventions suitable for
that operating system, and adjust build process accordingly. For
example, with gcc, it controls if import libraries are produced for
shared libraries or not.
+
The complete list of possible values for this feature is: `aix`,
`appletv`, `bsd`, `cygwin`, `darwin`, `freebsd`, `hpux`, `iphone`, `linux`, `netbsd`,
`openbsd`, `osf`, `qnx`, `qnxnto`, `sgi`, `solaris`, `unix`, `unixware`, `windows`.
+
See link:#bbv2.tasks.crosscompile[the section called “Cross-compilation”]
for details of cross-compilation.
[[bbv2.builtin.features.architecture]]`architecture`::
*Allowed values:* `x86`, `ia64`, `sparc`, `power`, `mips1`, `mips2`,
`mips3`, `mips4`, `mips32`, `mips32r2`, `mips64`, `parisc`, `arm`,
`s390x`, `combined`, `combined-x86-power`.
+
The `architecture` features specifies the general processor family to
generate code for.
[[bbv2.builtin.features.instruction-set]]`instruction-set`::
*Allowed values:* depends on the used toolset.
+
The `instruction-set` specifies for which specific instruction set the
code should be generated. The code in general might not run on
processors with older/different instruction sets.
+
While Boost.Build allows a large set of possible values for this
features, whether a given value works depends on which compiler you
use. Please see
link:#bbv2.reference.tools.compilers[the section called “C++ Compilers”]
for details.
[[bbv2.builtin.features.address-model]]`address-model`::
*Allowed values:* `32`, `64`.
+
The `address-model` specifies if 32-bit or 64-bit code should be
generated by the compiler. Whether this feature works depends on the
used compiler, its version, how the compiler is configured, and the
values of the `architecture` `instruction-set` features. Please see
link:#bbv2.reference.tools.compilers[the section called “C++ Compilers”]
for details.
[[bbv2.builtin.features.cpp-template-depth]]`c++-template-depth`::
*Allowed values:* Any positive integer.
+
This feature allows configuring a {CPP} compiler with the maximal
template instantiation depth parameter. Specific toolsets may or may
not provide support for this feature depending on whether their
compilers provide a corresponding command-line option.
+
NOTE: Due to some internal details in the current Boost.Build
implementation it is not possible to have features whose valid values
are all positive integer. As a workaround a large set of allowed
values has been defined for this feature and, if a different one is
needed, user can easily add it by calling the feature.extend rule.
[[bbv2.builtin.features.embed-manifest]]`embed-manifest`::
*Allowed values:* `on`, `off`.
+
This feature is specific to the msvc toolset (see
link:#bbv2.reference.tools.compiler.msvc[the section called “Microsoft Visual {CPP}”]),
and controls whether the manifest files should be embedded inside executables
and shared libraries, or placed alongside them. This feature corresponds
to the IDE option found in the project settings dialog, under
Configuration Properties -> Manifest Tool -> Input and Output -> Embed
manifest.
[[bbv2.builtin.features.embed-manifest-file]]`embed-manifest-file`::
This feature is specific to the msvc toolset (see
link:#bbv2.reference.tools.compiler.msvc[the section called “Microsoft Visual {CPP}”]),
and controls which manifest files should be embedded inside executables and
shared libraries. This feature corresponds to the IDE option found in the
project settings dialog, under Configuration Properties -> Manifest
Tool -> Input and Output -> Additional Manifest Files.
[[bbv2.builtin.features.relevant]]`relevant`::
*Allowed values:* the name of any feature.
+
This feature is used to indicate which other features are relevant for a
given target. It is usually not necessary to manage it explicitly, as
Boost.Build can deduce it in most cases. Features which are not relevant
will not affect target paths, and will not cause conflicts.
+
* A feature will be considered relevant if any of the following are true
+
** It is referenced by `toolset.flags` or `toolset.uses-features`
** It is used by the requirements of a generator
** It is a sub-feature of a relevant feature
** It has a sub-feature which is relevant
** It is a composite feature, and any composed feature is relevant
** It affects target alternative selection for a main target
** It is a propagated feature and is relevant for any dependency
** It is relevant for any dependency created by the same main target
** It is used in the condition of a conditional property and the corresponding
value is relevant
** It is explicitly named as relevant
+
* Relevant features cannot be automatically deduced in the following cases:
+
** Indirect conditionals. Solution: return properties of the form
`<relevant>result-feature:<relevant>condition-feature`
+
NOTE: This isn't really a conditional, although for most purposes it
functions like one. In particular, it does not support multiple
comma-separated elements in the condition, and it does work correctly even
in contexts where conditional properties are not allowed
** Action rules that read properties. Solution: add toolset.uses-features to
tell Boost.Build that the feature is actually used.
** Generators and targets that manipulate property-sets directly. Solution: set <relevant> manually.
[[bbv2.builtin.features.visibility]]`visibility`::
*Allowed values:* `global`, `protected`, `hidden`.
+
This feature is used to specify the default symbol visibility in compiled
binaries. Not all values are supported on all platforms and on some
platforms (for example, Windows) symbol visibility is not supported at all.
+
The supported values have the following meaning:
+
* `global` - a.k.a. "default" in gcc documentation. Global symbols are considered
public, they are exported from shared libraries and can be redefined by another
shared library or executable.
* `protected` - a.k.a. "symbolic". Protected symbols are exported from shared
libraries but cannot be redefined by another shared library or executable.
This mode is not supported on some platforms, for example OS X.
* `hidden` - Hidden symbols are not exported from shared libraries and cannot
be redefined by a different shared library or executable loaded in a process.
In this mode, public symbols have to be explicitly marked in the source code
to be exported from shared libraries. This is the recommended mode.
+
By default compiler default visibility mode is used (no compiler flags are added).
+
NOTE: In Boost super-project Jamroot file this property is set to the default
value of `hidden`. This means that Boost libraries are built with hidden
visibility by default, unless the user overrides it with a different `visibility`
or a library sets a different `local-visibility` (see below).
[[bbv2.builtin.features.local-visibility]]`local-visibility`::
*Allowed values:* `global`, `protected`, `hidden`.
+
This feature has the same effect as the `visibility` feature but is intended
to be used by targets that require a particular symbol visibility. Unlike
the `visibility` feature, `local-visibility` is not inherited by the target
dependencies and only affects the target to which it is applied.
+
The `local-visibility` feature supports the same values with the same meaning
as the `visibility` feature. By default, if `local-visibility` is not specified
for a target, the value of the `visibility` feature is used.
include::../../src/tools/features/address-model-feature.jam[tag=doc]
include::../../src/tools/features/sanitizers-feature.jam[tag=addr-doc]
include::../../src/tools/features/allow-feature.jam[tag=doc]
include::../../src/tools/features/architecture-feature.jam[tag=doc]
include::../../src/tools/features/archiveflags-feature.jam[tag=doc]
include::../../src/tools/features/asmflags-feature.jam[tag=doc]
include::../../src/tools/features/exception-feature.jam[tag=asynch-doc]
include::../../src/tools/features/build-feature.jam[tag=doc]
include::../../src/tools/features/cflags-feature.jam[tag=doc]
include::../../src/tools/features/conditional-feature.jam[tag=doc]
include::../../src/tools/features/coverage-feature.jam[tag=doc]
include::../../src/tools/features/cxxflags-feature.jam[tag=doc]
include::../../src/tools/features/cxxstd-feature.jam[tag=doc]
include::../../src/tools/features/cxxabi-feature.jam[tag=doc]
include::../../src/tools/features/cxx-template-depth-feature.jam[tag=doc]
include::../../src/tools/features/debug-feature.jam[tag=doc]
include::../../src/tools/features/define-feature.jam[tag=doc]
include::../../src/tools/features/dll-feature.jam[tag=def-doc]
include::../../src/tools/features/dependency-feature.jam[tag=doc]
include::../../src/tools/features/dll-feature.jam[tag=doc]
include::../../src/tools/msvc.jam[tag=embed-doc]
include::../../src/tools/features/exception-feature.jam[tag=doc]
include::../../src/tools/features/fflags-feature.jam[tag=doc]
include::../../src/tools/features/file-feature.jam[tag=doc]
include::../../src/tools/features/find-lib-feature.jam[tag=doc]
include::../../src/tools/features/flags-feature.jam[tag=doc]
include::../../src/tools/features/dll-feature.jam[tag=hardcode-doc]
include::../../src/tools/features/dependency-feature.jam[tag=impl-doc]
include::../../src/tools/features/include-feature.jam[tag=doc]
include::../../src/tools/features/optimization-feature.jam[tag=inline-doc]
include::../../src/tools/features/instruction-set-feature.jam[tag=doc]
include::../../src/tools/features/library-feature.jam[tag=doc]
include::../../src/tools/features/find-lib-feature.jam[tag=path-doc]
include::../../src/tools/features/sanitizers-feature.jam[tag=leak-doc]
include::../../src/tools/features/link-feature.jam[tag=doc]
include::../../src/tools/features/linkflags-feature.jam[tag=doc]
include::../../src/tools/features/local-visibility-feature.jam[tag=doc]
include::../../src/tools/features/location-feature.jam[tag=doc]
include::../../src/tools/features/location-prefix-feature.jam[tag=doc]
include::../../src/tools/features/objcflags-feature.jam[tag=doc]
include::../../src/tools/features/name-feature.jam[tag=doc]
include::../../src/tools/features/optimization-feature.jam[tag=doc]
include::../../src/tools/features/debug-feature.jam[tag=prof-doc]
include::../../src/tools/features/relevant-feature.jam[tag=doc]
include::../../src/tools/features/rtti-feature.jam[tag=doc]
include::../../src/tools/features/runtime-feature.jam[tag=doc]
include::../../src/tools/features/search-feature.jam[tag=doc]
include::../../src/tools/features/source-feature.jam[tag=doc]
include::../../src/tools/features/strip-feature.jam[tag=doc]
include::../../src/tools/features/dll-feature.jam[tag=suppress-doc]
include::../../src/tools/features/tag-feature.jam[tag=doc]
include::../../src/tools/features/os-feature.jam[tag=doc]
include::../../src/tools/features/threading-feature.jam[tag=doc]
include::../../src/tools/features/sanitizers-feature.jam[tag=thread-doc]
include::../../src/tools/features/toolset-feature.jam[tag=doc]
include::../../src/tools/features/define-feature.jam[tag=undef-doc]
include::../../src/tools/features/sanitizers-feature.jam[tag=undef-doc]
include::../../src/tools/features/dependency-feature.jam[tag=use-doc]
include::../../src/tools/features/user-interface-feature.jam[tag=doc]
include::../../src/tools/features/variant-feature.jam[tag=doc]
include::../../src/tools/features/optimization-feature.jam[tag=vector-doc]
include::../../src/tools/features/version-feature.jam[tag=doc]
include::../../src/tools/features/visibility-feature.jam[tag=doc]
include::../../src/tools/features/warnings-feature.jam[tag=doc]
include::../../src/tools/features/lto-feature.jam[tag=doc]

15
src/tools/features/address-model-feature.jam
View File

@@ -3,11 +3,20 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# The addressing model to generate code for. Currently a limited set only
# specifying the bit size of pointers.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.address-model]]`address-model`::
*Allowed values:* `32`, `64`.
+
Specifies if 32-bit or 64-bit code should be generated by the compiler. Whether
this feature works depends on the used compiler, its version, how the compiler
is configured, and the values of the `architecture` `instruction-set` features.
Please see the section <<C++ Compilers>> for details.
|# # end::doc[]
feature.feature address-model
: 16 32 64 32_64
: propagated optional ;

13
src/tools/features/allow-feature.jam
View File

@@ -3,12 +3,17 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# This feature is used to allow specific generators to run. For example, QT
# tools can only be invoked when QT library is used. In that case, <allow>qt
# will be in usage requirement of the library.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.allow]]`allow`::
This feature is used to allow specific generators to run. For example, Qt tools
can only be invoked when Qt library is used. In that case, `<allow>qt` will be
in usage requirement of the library.
|# # end::doc[]
feature.feature allow
:
: free ;

13
src/tools/features/architecture-feature.jam
View File

@@ -3,10 +3,19 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# Type of CPU architecture to compile for.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.architecture]]`architecture`::
*Allowed values:* `x86`, `ia64`, `sparc`, `power`, `mips1`, `mips2`,
`mips3`, `mips4`, `mips32`, `mips32r2`, `mips64`, `parisc`, `arm`,
`s390x`, `combined`, `combined-x86-power`.
+
Specifies the general processor family to generate code for.
|# # end::doc[]
feature.feature architecture
:
# x86 and x86-64

10
src/tools/features/archiveflags-feature.jam
View File

@@ -3,10 +3,16 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.archiveflags]]`archiveflags`::
The value of this feature is passed without modification to the archiver tool
when creating static libraries.
|# # end::doc[]
feature.feature archiveflags
:
: free ;

9
src/tools/features/asmflags-feature.jam
View File

@@ -3,10 +3,15 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.asmflags]]`asmflags`::
The value of this feature is passed without modification to the assembler.
|# # end::doc[]
feature.feature asmflags
:
: free ;

14
src/tools/features/build-feature.jam
View File

@@ -3,10 +3,20 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# The value of 'no' prevents building of a target.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.build]]`build`::
*Allowed values:* `no`
+
Used to conditionally disable build of a target. If `<build>no` is in
properties when building a target, build of that target is skipped. Combined
with conditional requirements this allows you to skip building some target in
configurations where the build is known to fail.
|# # end::doc[]
feature.feature build
: yes no
: optional ;

13
src/tools/features/cflags-feature.jam
View File

@@ -3,10 +3,19 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.cflags]]`cflags`; `cxxflags`; `linkflags`::
The value of these features is passed without modification to the corresponding
tools. For `cflags` that is both the C and {CPP} compilers, for `cxxflags` that
is the {CPP} compiler, and for `linkflags` that is the linker. The features are
handy when you are trying to do something special that cannot be achieved by a
higher-level feature in Boost.Build.
|# # end::doc[]
feature.feature cflags
:
: free ;

23
src/tools/features/conditional-feature.jam
View File

@@ -3,10 +3,29 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.conditional]]`conditional`::
Used to introduce indirect conditional requirements. The value should have the
form:
+
----
@rulename
----
+
where _rulename_ should be a name of a rule with the following signature:
+
----
rule rulename ( properties * )
----
+
The rule will be called for each target with its properties and should return
any additional properties. See also section <<Requirements>> for an example.
|# # end::doc[]
feature.feature conditional
:
: incidental free ;

9
src/tools/features/coverage-feature.jam
View File

@@ -6,6 +6,15 @@
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.coverage]]`coverage`::
*Allowed values:* `off`, `on`.
+
Enables code instrumentation to generate coverage data during execution.
|# # end::doc[]
feature.feature coverage
:
off # Disable coverage generation for the tool (default).

34
src/tools/features/cxx-template-depth-feature.jam
View File

@@ -3,22 +3,30 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# Feature that allows us to configure the maximal template instantiation depth
# level allowed by a C++ compiler. Applies only to C++ toolsets whose compilers
# actually support this configuration setting.
#
# Note that Boost Build currently does not allow defining features that take any
# positive integral value as a parameter, which is what we need here, so we just
# define some of the values here and leave it up to the user to extend this set
# as he needs using the feature.extend rule.
#
import feature ;
import numbers ;
#| tag::doc[]
[[bbv2.builtin.features.cpp-template-depth]]`c++-template-depth`::
*Allowed values:* Any positive integer.
+
Allows configuring a {CPP} compiler with the maximal template instantiation
depth parameter. Specific toolsets may or may not provide support for this
feature depending on whether their compilers provide a corresponding
command-line option.
+
NOTE: Due to some internal details in the current Boost.Build implementation it
is not possible to have features whose valid values are all positive integer.
As a workaround a large set of allowed values has been defined for this feature
and, if a different one is needed, user can easily add it by calling the
feature.extend rule.
|# # end::doc[]
# TODO: This should be upgraded as soon as Boost Build adds support for custom
# validated feature values or at least features allowing any positive integral
# value. See related Boost Build related trac ticket #194.
#
import feature ;
import numbers ;
feature.feature c++-template-depth
:

10
src/tools/features/cxxabi-feature.jam
View File

@@ -3,10 +3,16 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# Used to select a specific variant of C++ ABI if the compiler supports several.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.cxxabi]]`c++abi`::
Selects a specific variant of C++ ABI if the compiler supports several.
|# # end::doc[]
feature.feature c++abi
:
: propagated optional ;

9
src/tools/features/cxxflags-feature.jam
View File

@@ -3,10 +3,15 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.cxxflags]]`cxxflags`::
See <<bbv2.builtin.features.cflags,`<cflags>`>>.
|# # end::doc[]
feature.feature cxxflags
:
: free ;

53
src/tools/features/cxxstd-feature.jam
View File

@@ -5,30 +5,45 @@
import feature ;
# The `cxxstd` feature specifies the version of the C++ Standard Language to
# build with. All the official versions of the standard since "98" are
# included: `98`, `03`, `11`, `14`, and `17`. It is also possible to
# specify using the experimental, work in progress, `latest` version. Some
# compilers specified intermediate versions for the experimental versions
# leading up to the released standard version. Those are included following
# the GNU nomenclature as `0x`, `1y`, `1z`, and `2a`. And depending on the
# compiler `latest` would map to one of those.
#
# NOTE: This is an `optional` feature. Hence when not specified the compiler
# default behaviour is used.
#
# NOTE: Please consult the toolset specific documentation for which `cxxstd`
# is supported.
#| tag::doc[]
[[bbv2.builtin.features.cxxstd]]`cxxstd`::
*Allowed values*: `98`, `03`, `0x`, `11`, `1y`, `14`, `1z`, `17`, `2a`,
`latest`.
+
Specifies the version of the C++ Standard Language to build with. All the
official versions of the standard since "98" are included. It is also possible
to specify using the experimental, work in progress, `latest` version. Some
compilers specified intermediate versions for the experimental versions leading
up to the released standard version. Those are included following the GNU
nomenclature as `0x`, `1y`, `1z`, and `2a`. Depending on the compiler `latest`
would map to one of those.
NOTE: This is an `optional` feature. Hence when not specified the compiler
default behaviour is used.
NOTE: Please consult the toolset specific documentation for which `cxxstd`
is supported.
|# # end::doc[]
feature.feature cxxstd
: 98 03 0x 11 1y 14 1z 17 2a latest
: optional composite propagated ;
# The cxxstd:dialet subfeature indicates if a non-standard dialect should be
# used. These usually have either/or extensions or platform specific
# functionality. Not specifying the dialect will default to 'iso'. Which will
# attempt to use ISO C++ Standard conformance to the best of the compiler's
# ability.
#| tag::doc[]
[[bbv2.builtin.features.cxxstd-dialect]]`cxxstd-dialect`::
*Subfeature of* `cxxstd`
+
*Allowed values*: `iso`, `gnu`, `ms`.
+
Indicates if a non-standard dialect should be used. These usually have
either/or extensions or platform specific functionality. Not specifying the
dialect will default to 'iso' which will attempt to use ISO C++ Standard
conformance to the best of the compiler's ability.
|# # end::doc[]
feature.subfeature cxxstd : dialect
: iso gnu ms

22
src/tools/features/debug-feature.jam
View File

@@ -3,14 +3,32 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.debug-symbols]]`debug-symbols`::
*Allowed values:* `on`, `off`.
+
Specifies if produced object files, executables, and libraries should include
debug information. Typically, the value of this feature is implicitly set by
the `variant` feature, but it can be explicitly specified by the user. The most
common usage is to build release variant with debugging information.
|# # end::doc[]
feature.feature debug-symbols
: on off
: propagated ;
#| tag::prof-doc[]
[[bbv2.builtin.features.profiling]]`profiling`::
*Allowed values:* `off`, `on`.
+
Enables generation of extra code to write profile information.
|# # end::prof-doc[]
feature.feature profiling
: off on
: propagated ;

18
src/tools/features/define-feature.jam
View File

@@ -3,14 +3,28 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.define]]`define`::
Specifies a preprocessor symbol that should be defined on the command line.
You may either specify just the symbol, which will be defined without any
value, or both the symbol and the value, separated by equal sign.
|# # end::doc[]
feature.feature define
:
: free ;
#| tag::undef-doc[]
[[bbv2.builtin.features.undef]]`undef`::
Specifies a preprocessor symbol to undefine.
|# # end::undef-doc[]
feature.feature undef
:
: free ;

36
src/tools/features/dependency-feature.jam
View File

@@ -19,14 +19,44 @@
import feature ;
feature.feature use
:
: free dependency incidental ;
#| tag::doc[]
[[bbv2.builtin.features.dependency]]`dependency`::
Introduces a dependency on the target named by the value of this feature (so it
will be brought up-to-date whenever the target being declared is). The
dependency is not used in any other way.
|# # end::doc[]
feature.feature dependency
:
: free dependency incidental ;
#| tag::impl-doc[]
[[bbv2.builtin.features.implicit-dependency]]`implicit-dependency`::
Indicates that the target named by the value of this feature may produce files
that are included by the sources of the target being declared. See the section
<<Generated headers>> for more information.
|# # end::impl-doc[]
feature.feature implicit-dependency
:
: free dependency incidental ;
#| tag::use-doc[]
[[bbv2.builtin.features.use]]`use`::
Introduces a dependency on the target named by the value of this feature (so it
will be brought up-to-date whenever the target being declared is), and adds its
usage requirements to the build properties of the target being declared. The
dependency is not used in any other way. The primary use case is when you want
the usage requirements (such as `#include` paths) of some library to be
applied, but do not want to link to it.
|# # end::use-doc[]
feature.feature use
:
: free dependency incidental ;

46
src/tools/features/dll-feature.jam
View File

@@ -3,14 +3,41 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.dll-path]]`dll-path`::
Specifies an additional directory where the system should look for shared
libraries when the executable or shared library is run. This feature only
affects Unix compilers. Please see
<<Why are the `dll-path` and `hardcode-dll-paths` properties useful?>>
in <<Frequently Asked Questions>> for details.
|# # end::doc[]
feature.feature dll-path
:
: free path ;
#| tag::hardcode-doc[]
[[bbv2.builtin.features.hardcode-dll-paths]]`hardcode-dll-paths`::
*Allowed values:* `true`, `false`.
+
Controls automatic generation of dll-path properties.
+
This property is specific to Unix systems. If an executable is built with
`<hardcode-dll-paths>true`, the generated binary will contain the list of all
the paths to the used shared libraries. As the result, the executable can be
run without changing system paths to shared libraries or installing the
libraries to system paths. This is very convenient during development. Please
see the <<bbv2.faq.dll-path,FAQ entry>> for details. Note that on Mac OSX,
the paths are unconditionally hardcoded by the linker, and it is not possible
to disable that behavior
|# # end::hardcode-doc[]
feature.feature hardcode-dll-paths
: true false
: incidental ;
@@ -23,11 +50,24 @@ feature.feature xdll-path
:
: free path ;
# Provides means to specify def-file for windows DLLs.
#| tag::def-doc[]
[[bbv2.builtin.features.def-file]]`def-file`::
Provides a means to specify def-file for windows DLLs.
|# # end::def-doc[]
feature.feature def-file
:
: free dependency ;
#| tag::suppress-doc[]
[[bbv2.builtin.features.suppress-import-lib]]`suppress-import-lib`::
Suppresses creation of import library by the linker.
|# # end::suppress-doc[]
feature.feature suppress-import-lib
: false true
: incidental ;

29
src/tools/features/exception-feature.jam
View File

@@ -7,16 +7,41 @@
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.exception-handling]]`exception-handling`::
*Allowed values:* `on`, `off`.
+
Disables exceptions.
|# # end::doc[]
feature.feature exception-handling
: on off
: propagated ;
# Whether there is support for asynchronous EH (e.g. catching SEGVs).
#| tag::asynch-doc[]
[[bbv2.builtin.features.asynch-exceptions]]`asynch-exceptions`::
*Allowed values:* `off`, `on`.
+
Selects whether there is support for asynchronous EH (e.g. catching SEGVs).
|# # end::asynch-doc[]
feature.feature asynch-exceptions
: off on
: propagated ;
# Whether all extern "C" functions are considered nothrow by default.
#| tag::doc[]
[[bbv2.builtin.features.extern-c-nothrow]]`extern-c-nothrow`::
*Allowed values:* `off`, `on`.
+
Selects whether all `extern "C"` functions are considered `nothrow` by default.
|# # end::doc[]
feature.feature extern-c-nothrow
: off on
: propagated ;

10
src/tools/features/fflags-feature.jam
View File

@@ -3,10 +3,16 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.fflags]]`fflags`::
The value of this feature is passed without modification to the tool when
compiling Fortran sources.
|# # end::doc[]
feature.feature fflags
:
: free ;

10
src/tools/features/file-feature.jam
View File

@@ -3,10 +3,16 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.file]]`file`::
When used in requirements of a prebuilt library target this feature specifies
the path to the library file. See <<Prebuilt targets>> for examples.
|# # end::doc[]
feature.feature file
:
: free dependency incidental ;

26
src/tools/features/find-lib-feature.jam
View File

@@ -3,18 +3,40 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.find-shared-library]]`find-shared-library`::
Adds a shared library to link to. Usually link:#bbv2.tasks.libraries[`lib`]
targets should be preferred over using this feature.
|# # end::doc[]
feature.feature find-shared-library
:
: free ; #order-sensitive ;
#| tag::doc[]
[[bbv2.builtin.features.find-static-library]]`find-static-library`::
Adds a static library to link to. Usually link:#bbv2.tasks.libraries[`lib`]
targets should be preferred over using this feature.
|# # end::doc[]
feature.feature find-static-library
:
: free ; #order-sensitive ;
#| tag::path-doc[]
[[bbv2.builtin.features.library-path]]`library-path`::
Adds to the list of directories which will be used by the linker to search for
libraries.
|# # end::path-doc[]
feature.feature library-path
:
: free path ; #order-sensitive ;

11
src/tools/features/flags-feature.jam
View File

@@ -3,10 +3,17 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# Generic, i.e. non-language specific, flags for tools.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.flags]]`flags`::
This feature is used for generic, i.e. non-language specific, flags for tools.
The value of this feature is passed without modification to the tool that will
build the target.
|# # end::doc[]
feature.feature flags
:
: free ;

10
src/tools/features/include-feature.jam
View File

@@ -3,10 +3,16 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.include]]`include`::
Specifies an additional include path that is to be passed to C and {CPP}
compilers.
|# # end::doc[]
feature.feature "include"
:
: free path #order-sensitive

23
src/tools/features/instruction-set-feature.jam
View File

@@ -3,10 +3,23 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# The specific instruction set in an architecture to compile.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.instruction-set]]`instruction-set`::
*Allowed values:* depends on the used toolset.
+
Specifies for which specific instruction set the code should be generated. The
code in general might not run on processors with older/different instruction
sets.
+
While Boost.Build allows a large set of possible values for this features,
whether a given value works depends on which compiler you use. Please see
the section <<C++ Compilers>> for details.
|# # end::doc[]
feature.feature instruction-set
:
# x86 and x86-64
@@ -42,9 +55,9 @@ feature.feature instruction-set
# Advanced RISC Machines
armv2 armv2a armv3 armv3m armv4 armv4t armv5 armv5t armv5te armv6 armv6j iwmmxt ep9312
armv7 armv7s
# z Systems (aka s390x)
z196 zEC12 z13 z14 z15
# z Systems (aka s390x)
z196 zEC12 z13 z14 z15
:
propagated optional

14
src/tools/features/library-feature.jam
View File

@@ -3,10 +3,20 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.library]]`library`::
This feature is almost equivalent to the
<<bbv2.builtin.features.library,`<source>`>> feature, except that it takes
effect only for linking. When you want to link all targets in a Jamfile to
certain library, the `<library>` feature is preferred over `<source>X` -- the
latter will add the library to all targets, even those that have nothing to do
with libraries.
|# # end::doc[]
feature.feature library
:
: free dependency incidental ;

11
src/tools/features/link-feature.jam
View File

@@ -3,10 +3,17 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.link]]`link`::
*Allowed values:* `shared`, `static`
+
Controls how libraries are built.
|# # end::doc[]
feature.feature link
: shared static
: propagated ;

9
src/tools/features/linkflags-feature.jam
View File

@@ -3,10 +3,15 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.linkflags]]`linkflags`::
See <<bbv2.builtin.features.cflags,`<cflags>`>>.
|# # end::doc[]
feature.feature linkflags
:
: free ;

17
src/tools/features/local-visibility-feature.jam
View File

@@ -5,6 +5,23 @@
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.local-visibility]]`local-visibility`::
*Allowed values:* `global`, `protected`, `hidden`.
+
This feature has the same effect as the
<<bbv2.builtin.features.visibility,`visibility`>> feature but is intended
to be used by targets that require a particular symbol visibility. Unlike the
`visibility` feature, `local-visibility` is not inherited by the target
dependencies and only affects the target to which it is applied.
+
The `local-visibility` feature supports the same values with the same meaning
as the `visibility` feature. By default, if `local-visibility` is not specified
for a target, the value of the `visibility` feature is used.
|# # end::doc[]
feature.feature local-visibility
: global protected hidden
: optional ;

10
src/tools/features/location-feature.jam
View File

@@ -3,10 +3,16 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.location]]`location`::
Specifies the build directory for a target. The feature is used primarily with
<<bbv2.tasks.installing,`<install>`>> rule.
|# # end::doc[]
feature.feature location
:
: free path ;

10
src/tools/features/location-prefix-feature.jam
View File

@@ -3,10 +3,16 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.location-prefix]]`location-prefix`::
Sets the build directory for a target as the project’s build directory prefixed
with the value of this feature. See section <<Target Paths>> for an example.
|# # end::doc[]
feature.feature location-prefix
:
: free ;

14
src/tools/features/name-feature.jam
View File

@@ -3,10 +3,20 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.name]]`name`::
When used in requirements of a prebuilt library target this feature specifies
the name of the library (the name of the library file without any
platform-specific suffixes or prefixes). See <<Prebuilt targets>> for examples.
+
When used in requirements of an `<install>` target it specifies the name of the
target file.
|# # end::doc[]
feature.feature name
:
: free ;

20
src/tools/features/objcflags-feature.jam
View File

@@ -3,14 +3,30 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.mflags]]`mflags`::
The value of this feature is passed without modification to the tool when
compiling Objective C sources.
|# # end::doc[]
feature.feature mflags
:
: free ;
#| tag::doc[]
[[bbv2.builtin.features.mmflags]]`mmflags`::
The value of this feature is passed without modification to the tool when
compiling Objective {CPP} sources.
|# # end::doc[]
feature.feature mmflags
:
: free ;

30
src/tools/features/optimization-feature.jam
View File

@@ -3,18 +3,44 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.optimization]]`optimization`::
*Allowed values:* `off`, `speed`, `space`.
+
Enables optimization. `speed` optimizes for faster code, `space` optimizes for
smaller binary.
|# # end::doc[]
feature.feature optimization
: off speed space
: propagated ;
#| tag::inline-doc[]
[[bbv2.builtin.features.inlining]]`inlining`::
*Allowed values:* `off`, `on`, `full`.
+
Enables inlining.
|# # end::inline-doc[]
feature.feature inlining
: off on full
: propagated ;
#| tag::vector-doc[]
[[bbv2.builtin.features.vectorize]]`vectorize`::
*Allowed values:* `off`, `on`, `full`.
+
Enables vectorization.
|# # end::vector-doc[]
feature.feature vectorize
: off on full
: propagated ;

22
src/tools/features/os-feature.jam
View File

@@ -3,8 +3,6 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
import modules ;
import os ;
@@ -13,7 +11,7 @@ import os ;
aix android appletv bsd cygwin darwin freebsd haiku hpux iphone linux
netbsd openbsd osf qnx qnxnto sgi solaris unix unixware windows vms vxworks
freertos
# Not actually an OS -- used for targeting bare metal where object
# format is ELF. This catches both -elf and -eabi gcc targets as well
# as other compilers targeting ELF. It is not clear how often we need
@@ -75,5 +73,23 @@ local rule default-host-os ( )
feature.feature host-os : $(.os-names) ;
feature.set-default host-os : [ default-host-os ] ;
#| tag::doc[]
[[bbv2.builtin.features.target-os]]`target-os`::
*Allowed values:* `aix`, `android`, `appletv`, `bsd`, `cygwin`, `darwin`,
`freebsd`, `haiku`, `hpux`, `iphone`, `linux`, `netbsd`, `openbsd`, `osf`,
`qnx`, `qnxnto`, `sgi`, `solaris`, `unix`, `unixware`, `windows`, `vms`,
`vxworks`, `freertos`.
+
Specifies the operating system for which the code is to be generated. The
compiler you used should be the compiler for that operating system. This option
causes Boost.Build to use naming conventions suitable for that operating
system, and adjust build process accordingly. For example, with gcc, it
controls if import libraries are produced for shared libraries or not.
+
See the section <<Cross-compilation>> for details of cross-compilation.
|# # end::doc[]
feature.feature target-os : $(.os-names) : propagated link-incompatible ;
feature.set-default target-os : [ default-host-os ] ;

42
src/tools/features/relevant-feature.jam
View File

@@ -3,8 +3,46 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# Identifies relevant features.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.relevant]]`relevant`::
*Allowed values:* the name of any feature.
+
Indicates which other features are relevant for a given target. It is usually
not necessary to manage it explicitly, as Boost.Build can deduce it in most
cases. Features which are not relevant will not affect target paths, and will
not cause conflicts.
+
* A feature will be considered relevant if any of the following are true
+
** It is referenced by `toolset.flags` or `toolset.uses-features`
** It is used by the requirements of a generator
** It is a sub-feature of a relevant feature
** It has a sub-feature which is relevant
** It is a composite feature, and any composed feature is relevant
** It affects target alternative selection for a main target
** It is a propagated feature and is relevant for any dependency
** It is relevant for any dependency created by the same main target
** It is used in the condition of a conditional property and the corresponding
value is relevant
** It is explicitly named as relevant
+
* Relevant features cannot be automatically deduced in the following cases:
+
** Indirect conditionals. Solution: return properties of the form
`<relevant>result-feature:<relevant>condition-feature`
+
NOTE: This isn't really a conditional, although for most purposes it functions
like one. In particular, it does not support multiple comma-separated elements
in the condition, and it does work correctly even in contexts where conditional
properties are not allowed
** Action rules that read properties. Solution: add toolset.uses-features to
tell Boost.Build that the feature is actually used.
** Generators and targets that manipulate property-sets directly. Solution:
set <relevant> manually.
|# # end::doc[]
feature.feature relevant : : incidental free ;

11
src/tools/features/rtti-feature.jam
View File

@@ -3,10 +3,17 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.rtti]]`rtti`::
*Allowed values:* `on`, `off`.
+
Disables run-time type information.
|# # end::doc[]
feature.feature rtti
: on off
: propagated ;

34
src/tools/features/runtime-feature.jam
View File

@@ -3,14 +3,38 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
feature.feature runtime-link
: shared static
: propagated ;
#| tag::doc[]
[[bbv2.builtin.features.runtime-debugging]]`runtime-debugging`::
*Allowed values:* `on`, `off`.
+
Specifies whether produced object files, executables, and libraries should
include behavior useful only for debugging, such as asserts. Typically, the
value of this feature is implicitly set by the `variant` feature, but it can be
explicitly specified by the user. The most common usage is to build release
variant with debugging output.
|# # end::doc[]
feature.feature runtime-debugging
: on off
: propagated ;
#| tag::doc[]
[[bbv2.builtin.features.runtime-link]]`runtime-link`::
*Allowed values:* `shared`, `static`
+
Controls if a static or shared C/{CPP} runtime should be used. There are some
restrictions how this feature can be used, for example on some compilers an
application using static runtime should not use shared libraries at all, and on
some compilers, mixing static and shared runtime requires extreme care. Check
your compiler documentation for more details.
|# # end::doc[]
feature.feature runtime-link
: shared static
: propagated ;

43
src/tools/features/sanitizers-feature.jam
View File

@@ -3,22 +3,61 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# Used to enable the use of sanitizers in gcc and clang.
import feature ;
#| tag::addr-doc[]
[[bbv2.builtin.features.address-sanitizer]]`address-sanitizer`::
*Allowed values:* `on`, `norecover`.
+
Enables address sanitizer. Value `norecover` disables recovery for the
sanitizer. The feature is optional, thus no sanitizer is enabled by default.
|# # end::addr-doc[]
feature.feature address-sanitizer
: on norecover
: propagated optional ;
#| tag::leak-doc[]
[[bbv2.builtin.features.leak-sanitizer]]`leak-sanitizer`::
*Allowed values:* `on`, `norecover`.
+
Enables leak sanitizer. Value `norecover` disables recovery for the
sanitizer. The feature is optional, thus no sanitizer is enabled by default.
|# # end::leak-doc[]
feature.feature leak-sanitizer
: on norecover
: propagated optional ;
#| tag::thread-doc[]
[[bbv2.builtin.features.thread-sanitizer]]`thread-sanitizer`::
*Allowed values:* `on`, `norecover`.
+
Enables thread sanitizer. Value `norecover` disables recovery for the
sanitizer. The feature is optional, thus no sanitizer is enabled by default.
|# # end::thread-doc[]
feature.feature thread-sanitizer
: on norecover
: propagated optional ;
#| tag::undef-doc[]
[[bbv2.builtin.features.undefined-sanitizer]]`undefined-sanitizer`::
*Allowed values:* `on`, `norecover`.
+
Enables undefined behavior sanitizer. Value `norecover` disables recovery for
the sanitizer. The feature is optional, thus no sanitizer is enabled by
default.
|# # end::undef-doc[]
feature.feature undefined-sanitizer
: on norecover
: propagated optional ;

11
src/tools/features/search-feature.jam
View File

@@ -3,10 +3,17 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.search]]`search`::
When used in requirements of a prebuilt library target this feature adds to the
list of directories to search for the library file. See <<Prebuilt targets>>
for examples.
|# # end::doc[]
feature.feature search
:
: free path #order-sensitive

14
src/tools/features/source-feature.jam
View File

@@ -3,10 +3,20 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.source]]`source`::
The `<source>X` property has the same effect on building a target as putting X
in the list of sources. It is useful when you want to add the same source to
all targets in the project (you can put `<source>` in requirements) or to
conditionally include a source (using conditional requirements, see
the section <<Conditions and alternatives>>. See also the
<<bbv2.builtin.features.library,`<library>`>> feature.
|# # end::doc[]
feature.feature source
:
: free dependency incidental ;

24
src/tools/features/strip-feature.jam
View File

@@ -3,17 +3,23 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# Controls whether the binary should be stripped -- that is have
# everything not necessary to running removed. This option should
# not be very often needed.
#
# NOTE: Also, this feature will show up in
# target paths of everything, not just binaries.
#
# TODO: Should fix that when implementing feature relevance.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.strip]]`strip`::
*Allowed values:* `off`, `on`.
+
Controls whether the binary should be stripped -- that is have everything not
necessary to running removed.
+
NOTE: This feature will show up in target paths of everything, not just
binaries.
|# # end::doc[]
# TODO: Should fix that when implementing feature relevance.
feature.feature strip
: off on
: propagated ;

31
src/tools/features/tag-feature.jam
View File

@@ -3,10 +3,37 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.tag]]`tag`::
Used to customize the name of the generated files. The value should have the
form:
+
----
@rulename
----
+
where _rulename_ should be a name of a rule with the following signature:
+
----
rule tag ( name : type ? : property-set )
----
+
The rule will be called for each target with the default name computed by
Boost.Build, the type of the target, and property set. The rule can either
return a string that must be used as the name of the target, or an empty
string, in which case the default name will be used.
+
Most typical use of the `tag` feature is to encode build properties, or library
version in library target names. You should take care to return non-empty
string from the tag rule only for types you care about -- otherwise, you might
end up modifying names of object files, generated header file and other targets
for which changing names does not make sense.
|# # end::doc[]
feature.feature tag
:
: free ;

12
src/tools/features/threadapi-feature.jam
View File

@@ -3,13 +3,21 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import property-set ;
import feature : feature ;
import toolset ;
import features/os-feature ;
#| tag::doc[]
[[bbv2.builtin.features.threadapi]]`threadapi`::
*Allowed values:* `pthread`, `win32`.
+
Selects threading implementation. The default is `win32` if `<target-os>` is
`windows` and `pthread` otherwise.
|# # end::doc[]
feature threadapi : pthread win32 : symmetric propagated ;
toolset.add-defaults <target-os>windows:<threadapi>win32 ;

16
src/tools/features/threading-feature.jam
View File

@@ -3,10 +3,22 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.threading]]`threading`::
*Allowed values:* `single`, `multi`
+
Controls if the project should be built in multi-threaded mode. This feature
does not necessary change code generation in the compiler, but it causes the
compiler to link to additional or different runtime libraries, and define
additional preprocessor symbols (for example, `_MT` on Windows and `_REENTRANT`
on Linux). How those symbols affect the compiled code depends on the code
itself.
|# # end::doc[]
feature.feature threading
: single multi
: propagated ;

12
src/tools/features/toolset-feature.jam
View File

@@ -3,10 +3,18 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.toolset]]`toolset`::
*Allowed values:* any of the toolset modules.
+
Selects the toolset that will be used to build binary targets. The full list of
toolset modules is in the <<Builtin tools>> section.
|# # end::doc[]
feature.feature toolset
:
: implicit propagated symmetric ;

21
src/tools/features/user-interface-feature.jam
View File

@@ -3,11 +3,26 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
# Windows-specific feature?
#| tag::doc[]
[[bbv2.builtin.features.user-interface]]`user-interface`::
*Allowed values:* `console`, `gui`, `wince`, `native`, `auto`.
+
Specifies the environment for the executable which affects the entry point
symbol (or entry point function) that the linker will select. This feature is
Windows-specific.
+
`console`::: console application.
`gui`::: application does not require a console (it is supposed to create its
own windows.
`wince`::: application is intended to run on a device that has a version of the
Windows CE kernel.
`native`::: application runs without a subsystem environment.
`auto`::: application runs in the POSIX subsystem in Windows.
|# # end::doc[]
feature.feature user-interface
: console gui wince native auto ;

36
src/tools/features/variant-feature.jam
View File

@@ -3,12 +3,44 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
import errors ;
import property ;
#| tag::doc[]
[[bbv2.builtin.features.variant]]`variant`::
*Allowed values:* `debug`, `release`, `profile`.
+
A feature combining several low-level features, making it easy to
request common build configurations.
+
The value `debug` expands to
+
----
<optimization>off <debug-symbols>on <inlining>off <runtime-debugging>on
----
+
The value `release` expands to
+
----
<optimization>speed <debug-symbols>off <inlining>full <runtime-debugging>off
----
+
The value `profile` expands to the same as `release`, plus:
+
----
<profiling>on <debug-symbols>on
----
+
Users can define their own build variants using the `variant` rule
from the `common` module.
+
NOTE: Runtime debugging is on in debug builds to suit the expectations of
people used to various IDEs.
|# # end::doc[]
feature.feature variant
:
: implicit composite propagated symmetric ;

11
src/tools/features/version-feature.jam
View File

@@ -3,10 +3,17 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.version]]`version`::
This feature isn't used by any of the builtin tools, but can be used, for
example, to adjust target's name via <<bbv2.builtin.features.tag,`<tag>`>>
feature.
|# # end::doc[]
feature.feature version
:
: free ;

32
src/tools/features/visibility-feature.jam
View File

@@ -5,6 +5,38 @@
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.visibility]]`visibility`::
*Allowed values:* `global`, `protected`, `hidden`.
+
Specifies the default symbol visibility in compiled binaries. Not all values
are supported on all platforms and on some platforms (for example, Windows)
symbol visibility is not supported at all.
+
The supported values have the following meaning:
+
`global`::: a.k.a. "default" in gcc documentation. Global symbols are
considered public, they are exported from shared libraries and can be
redefined by another shared library or executable.
`protected`::: a.k.a. "symbolic". Protected symbols are exported from shared
ibraries but cannot be redefined by another shared library or executable.
This mode is not supported on some platforms, for example OS X.
`hidden`::: Hidden symbols are not exported from shared libraries and cannot
be redefined by a different shared library or executable loaded in a process.
In this mode, public symbols have to be explicitly marked in the source code
to be exported from shared libraries. This is the recommended mode.
+
By default compiler default visibility mode is used (no compiler flags are
added).
+
NOTE: In Boost super-project Jamroot file this property is set to the default
value of `hidden`. This means that Boost libraries are built with hidden
visibility by default, unless the user overrides it with a different
`visibility` or a library sets a different `local-visibility` (see below).
|# # end::doc[]
feature.feature visibility
: global protected hidden
: optional composite propagated ;

40
src/tools/features/warnings-feature.jam
View File

@@ -3,21 +3,39 @@
# (See accompanying file LICENSE_1_0.txt or copy at
# http://www.boost.org/LICENSE_1_0.txt)
# TODO: Documentation.
import feature ;
#| tag::doc[]
[[bbv2.builtin.features.warnings]]`warnings`::
*Allowed values:* `on`, `all`, `extra`, `pedantic`, `off`.
+
Controls the warning level of compilers.
+
`on`::: enable default/"reasonable" warning level.
`all`::: enable most warnings.
`extra`::: enable extra, possibly conflicting, warnings.
`pedantic`::: enable likely inconsequential, and conflicting, warnings.
`off`::: disable all warnings.
+
Default value is `all`.
|# # end::doc[]
feature.feature warnings
:
on # Enable default/"reasonable" warning level for the tool.
all # Enable all possible warnings issued by the tool.
extra # Enable extra, possibly conflicting, warnings issued by the tool.
pedantic # Enable likely inconsequential, and conflicting, warnings.
off # Disable all warnings issued by the tool.
: on all extra pedantic off
: incidental propagated ;
#| tag::doc[]
[[bbv2.builtin.features.warnings-as-errors]]`warnings-as-errors`::
*Allowed values:* `off`, `on`.
+
Makes it possible to treat warnings as errors and abort compilation on a
warning.
|# # end::doc[]
feature.feature warnings-as-errors
:
off # Do not fail the compilation if there are warnings.
on # Fail the compilation if there are warnings.
: off on
: incidental propagated ;

26
src/tools/msvc.jam
View File

@@ -231,7 +231,33 @@ import virtual-target ;
type.register MANIFEST : manifest ;
#| tag::embed-doc[]
[[bbv2.builtin.features.embed-manifest]]`embed-manifest`::
*Allowed values:* `on`, `off`.
+
This feature is specific to the `msvc` toolset (see <<Microsoft Visual C++>>),
and controls whether the manifest files should be embedded inside executables
and shared libraries, or placed alongside them. This feature corresponds to the
IDE option found in the project settings dialog, under Configuration Properties
-> Manifest Tool -> Input and Output -> Embed manifest.
|# # end::embed-doc[]
feature.feature embed-manifest : on off : incidental propagated ;
#| tag::embed-doc[]
[[bbv2.builtin.features.embed-manifest-file]]`embed-manifest-file`::
This feature is specific to the `msvc` toolset (see <<Microsoft Visual C++>>),
and controls which manifest files should be embedded inside executables and
shared libraries. This feature corresponds to the IDE option found in the
project settings dialog, under Configuration Properties -> Manifest Tool ->
Input and Output -> Additional Manifest Files.
|# # end::embed-doc[]
feature.feature embed-manifest-file : : free dependency ;
type.register PDB : pdb ;