From b54f53ccbca07548df52c3a3ea63af678858569d Mon Sep 17 00:00:00 2001 From: Dmitry Date: Mon, 28 Oct 2019 15:22:42 +0300 Subject: [PATCH] Document features (#498) * move feature documentation into each feature's source file * sort features in the docs * updated docs for features --- doc/src/reference.adoc | 423 +++--------------- src/tools/features/address-model-feature.jam | 15 +- src/tools/features/allow-feature.jam | 13 +- src/tools/features/architecture-feature.jam | 13 +- src/tools/features/archiveflags-feature.jam | 10 +- src/tools/features/asmflags-feature.jam | 9 +- src/tools/features/build-feature.jam | 14 +- src/tools/features/cflags-feature.jam | 13 +- src/tools/features/conditional-feature.jam | 23 +- src/tools/features/coverage-feature.jam | 9 + .../features/cxx-template-depth-feature.jam | 34 +- src/tools/features/cxxabi-feature.jam | 10 +- src/tools/features/cxxflags-feature.jam | 9 +- src/tools/features/cxxstd-feature.jam | 53 ++- src/tools/features/debug-feature.jam | 22 +- src/tools/features/define-feature.jam | 18 +- src/tools/features/dependency-feature.jam | 36 +- src/tools/features/dll-feature.jam | 46 +- src/tools/features/exception-feature.jam | 29 +- src/tools/features/fflags-feature.jam | 10 +- src/tools/features/file-feature.jam | 10 +- src/tools/features/find-lib-feature.jam | 26 +- src/tools/features/flags-feature.jam | 11 +- src/tools/features/include-feature.jam | 10 +- .../features/instruction-set-feature.jam | 23 +- src/tools/features/library-feature.jam | 14 +- src/tools/features/link-feature.jam | 11 +- src/tools/features/linkflags-feature.jam | 9 +- .../features/local-visibility-feature.jam | 17 + src/tools/features/location-feature.jam | 10 +- .../features/location-prefix-feature.jam | 10 +- src/tools/features/name-feature.jam | 14 +- src/tools/features/objcflags-feature.jam | 20 +- src/tools/features/optimization-feature.jam | 30 +- src/tools/features/os-feature.jam | 22 +- src/tools/features/relevant-feature.jam | 42 +- src/tools/features/rtti-feature.jam | 11 +- src/tools/features/runtime-feature.jam | 34 +- src/tools/features/sanitizers-feature.jam | 43 +- src/tools/features/search-feature.jam | 11 +- src/tools/features/source-feature.jam | 14 +- src/tools/features/strip-feature.jam | 24 +- src/tools/features/tag-feature.jam | 31 +- src/tools/features/threadapi-feature.jam | 12 +- src/tools/features/threading-feature.jam | 16 +- src/tools/features/toolset-feature.jam | 12 +- src/tools/features/user-interface-feature.jam | 21 +- src/tools/features/variant-feature.jam | 36 +- src/tools/features/version-feature.jam | 11 +- src/tools/features/visibility-feature.jam | 32 ++ src/tools/features/warnings-feature.jam | 40 +- src/tools/msvc.jam | 26 ++ 52 files changed, 952 insertions(+), 510 deletions(-) diff --git a/doc/src/reference.adoc b/doc/src/reference.adoc index f1534036c..18ca34507 100644 --- a/doc/src/reference.adoc +++ b/doc/src/reference.adoc @@ -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 -+ ----- -off on off on ----- -+ -The value `release` expands to -+ ----- -speed off full off ----- -+ -The value `profile` expands to the same as `release`, plus: -+ ----- -on 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 `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 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 `` feature. - -[[bbv2.builtin.features.library]]`library`:: -This feature is almost equivalent to the `` feature, except -that it takes effect only for linking. When you want to link all -targets in a Jamfile to certain library, the `` feature is -preferred over `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 -`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 `` 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 `` 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 `` 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 `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 -`result-feature: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 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] diff --git a/src/tools/features/address-model-feature.jam b/src/tools/features/address-model-feature.jam index de7e736f4..479c89298 100644 --- a/src/tools/features/address-model-feature.jam +++ b/src/tools/features/address-model-feature.jam @@ -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 <> for details. + +|# # end::doc[] + feature.feature address-model : 16 32 64 32_64 : propagated optional ; diff --git a/src/tools/features/allow-feature.jam b/src/tools/features/allow-feature.jam index bf5697764..bcee55796 100644 --- a/src/tools/features/allow-feature.jam +++ b/src/tools/features/allow-feature.jam @@ -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, 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, `qt` will be +in usage requirement of the library. + +|# # end::doc[] + feature.feature allow : : free ; diff --git a/src/tools/features/architecture-feature.jam b/src/tools/features/architecture-feature.jam index 9f0e0b53b..3e3ca382f 100644 --- a/src/tools/features/architecture-feature.jam +++ b/src/tools/features/architecture-feature.jam @@ -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 diff --git a/src/tools/features/archiveflags-feature.jam b/src/tools/features/archiveflags-feature.jam index d4ebc3a8d..c645d8c7a 100644 --- a/src/tools/features/archiveflags-feature.jam +++ b/src/tools/features/archiveflags-feature.jam @@ -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 ; diff --git a/src/tools/features/asmflags-feature.jam b/src/tools/features/asmflags-feature.jam index 45d8ee126..00626958e 100644 --- a/src/tools/features/asmflags-feature.jam +++ b/src/tools/features/asmflags-feature.jam @@ -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 ; diff --git a/src/tools/features/build-feature.jam b/src/tools/features/build-feature.jam index 6cafeda0d..64c7713c8 100644 --- a/src/tools/features/build-feature.jam +++ b/src/tools/features/build-feature.jam @@ -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 `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 ; diff --git a/src/tools/features/cflags-feature.jam b/src/tools/features/cflags-feature.jam index 37bb54bb9..6b1fb1b9a 100644 --- a/src/tools/features/cflags-feature.jam +++ b/src/tools/features/cflags-feature.jam @@ -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 ; diff --git a/src/tools/features/conditional-feature.jam b/src/tools/features/conditional-feature.jam index 35c05ef26..368ad232f 100644 --- a/src/tools/features/conditional-feature.jam +++ b/src/tools/features/conditional-feature.jam @@ -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 <> for an example. + +|# # end::doc[] + feature.feature conditional : : incidental free ; diff --git a/src/tools/features/coverage-feature.jam b/src/tools/features/coverage-feature.jam index f0d8ccdfe..517c6d5b9 100644 --- a/src/tools/features/coverage-feature.jam +++ b/src/tools/features/coverage-feature.jam @@ -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). diff --git a/src/tools/features/cxx-template-depth-feature.jam b/src/tools/features/cxx-template-depth-feature.jam index b1cd54b2d..cc0fea010 100644 --- a/src/tools/features/cxx-template-depth-feature.jam +++ b/src/tools/features/cxx-template-depth-feature.jam @@ -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 : diff --git a/src/tools/features/cxxabi-feature.jam b/src/tools/features/cxxabi-feature.jam index 3ff16f563..9b6cd4fd4 100644 --- a/src/tools/features/cxxabi-feature.jam +++ b/src/tools/features/cxxabi-feature.jam @@ -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 ; diff --git a/src/tools/features/cxxflags-feature.jam b/src/tools/features/cxxflags-feature.jam index 0aa0ff744..6db7a7ce6 100644 --- a/src/tools/features/cxxflags-feature.jam +++ b/src/tools/features/cxxflags-feature.jam @@ -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 <`>>. + +|# # end::doc[] + feature.feature cxxflags : : free ; diff --git a/src/tools/features/cxxstd-feature.jam b/src/tools/features/cxxstd-feature.jam index 04d4061a4..dfddf5bb7 100644 --- a/src/tools/features/cxxstd-feature.jam +++ b/src/tools/features/cxxstd-feature.jam @@ -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 diff --git a/src/tools/features/debug-feature.jam b/src/tools/features/debug-feature.jam index 04958f9a5..f98177e39 100644 --- a/src/tools/features/debug-feature.jam +++ b/src/tools/features/debug-feature.jam @@ -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 ; diff --git a/src/tools/features/define-feature.jam b/src/tools/features/define-feature.jam index 9208136ee..680afdd94 100644 --- a/src/tools/features/define-feature.jam +++ b/src/tools/features/define-feature.jam @@ -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 ; diff --git a/src/tools/features/dependency-feature.jam b/src/tools/features/dependency-feature.jam index 7c95dbd8c..d866fb21c 100644 --- a/src/tools/features/dependency-feature.jam +++ b/src/tools/features/dependency-feature.jam @@ -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 +<> 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 ; diff --git a/src/tools/features/dll-feature.jam b/src/tools/features/dll-feature.jam index fc59cc173..3c7ed0d65 100644 --- a/src/tools/features/dll-feature.jam +++ b/src/tools/features/dll-feature.jam @@ -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 +<> +in <> 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 +`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 <> 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 ; diff --git a/src/tools/features/exception-feature.jam b/src/tools/features/exception-feature.jam index d5161ef96..9db3834b2 100644 --- a/src/tools/features/exception-feature.jam +++ b/src/tools/features/exception-feature.jam @@ -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 ; diff --git a/src/tools/features/fflags-feature.jam b/src/tools/features/fflags-feature.jam index 7f080d037..fe89d6e63 100644 --- a/src/tools/features/fflags-feature.jam +++ b/src/tools/features/fflags-feature.jam @@ -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 ; diff --git a/src/tools/features/file-feature.jam b/src/tools/features/file-feature.jam index 00f19e1b0..a16d8d754 100644 --- a/src/tools/features/file-feature.jam +++ b/src/tools/features/file-feature.jam @@ -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 <> for examples. + +|# # end::doc[] + feature.feature file : : free dependency incidental ; diff --git a/src/tools/features/find-lib-feature.jam b/src/tools/features/find-lib-feature.jam index f75740393..e00f40397 100644 --- a/src/tools/features/find-lib-feature.jam +++ b/src/tools/features/find-lib-feature.jam @@ -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 ; diff --git a/src/tools/features/flags-feature.jam b/src/tools/features/flags-feature.jam index f38b5fca3..a0c416609 100644 --- a/src/tools/features/flags-feature.jam +++ b/src/tools/features/flags-feature.jam @@ -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 ; diff --git a/src/tools/features/include-feature.jam b/src/tools/features/include-feature.jam index 094af2425..25d8ad8c4 100644 --- a/src/tools/features/include-feature.jam +++ b/src/tools/features/include-feature.jam @@ -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 diff --git a/src/tools/features/instruction-set-feature.jam b/src/tools/features/instruction-set-feature.jam index 0cd482ae9..09b445bbc 100644 --- a/src/tools/features/instruction-set-feature.jam +++ b/src/tools/features/instruction-set-feature.jam @@ -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 <> 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 diff --git a/src/tools/features/library-feature.jam b/src/tools/features/library-feature.jam index 97338e5c8..86772c0e9 100644 --- a/src/tools/features/library-feature.jam +++ b/src/tools/features/library-feature.jam @@ -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 +<`>> feature, except that it takes +effect only for linking. When you want to link all targets in a Jamfile to +certain library, the `` feature is preferred over `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 ; diff --git a/src/tools/features/link-feature.jam b/src/tools/features/link-feature.jam index 2032b921b..f697341a8 100644 --- a/src/tools/features/link-feature.jam +++ b/src/tools/features/link-feature.jam @@ -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 ; diff --git a/src/tools/features/linkflags-feature.jam b/src/tools/features/linkflags-feature.jam index 9ce44e005..4e157f399 100644 --- a/src/tools/features/linkflags-feature.jam +++ b/src/tools/features/linkflags-feature.jam @@ -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 <`>>. + +|# # end::doc[] + feature.feature linkflags : : free ; diff --git a/src/tools/features/local-visibility-feature.jam b/src/tools/features/local-visibility-feature.jam index ff07dc92f..d1792fd06 100644 --- a/src/tools/features/local-visibility-feature.jam +++ b/src/tools/features/local-visibility-feature.jam @@ -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 +<> 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 ; diff --git a/src/tools/features/location-feature.jam b/src/tools/features/location-feature.jam index dd49c5d72..1581d3392 100644 --- a/src/tools/features/location-feature.jam +++ b/src/tools/features/location-feature.jam @@ -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 +<`>> rule. + +|# # end::doc[] + feature.feature location : : free path ; diff --git a/src/tools/features/location-prefix-feature.jam b/src/tools/features/location-prefix-feature.jam index 61789f218..11582fd20 100644 --- a/src/tools/features/location-prefix-feature.jam +++ b/src/tools/features/location-prefix-feature.jam @@ -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 <> for an example. + +|# # end::doc[] + feature.feature location-prefix : : free ; diff --git a/src/tools/features/name-feature.jam b/src/tools/features/name-feature.jam index 13f6d52cd..e134fc422 100644 --- a/src/tools/features/name-feature.jam +++ b/src/tools/features/name-feature.jam @@ -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 <> for examples. ++ +When used in requirements of an `` target it specifies the name of the +target file. + +|# # end::doc[] + feature.feature name : : free ; diff --git a/src/tools/features/objcflags-feature.jam b/src/tools/features/objcflags-feature.jam index e4f026bf3..b69c6b661 100644 --- a/src/tools/features/objcflags-feature.jam +++ b/src/tools/features/objcflags-feature.jam @@ -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 ; diff --git a/src/tools/features/optimization-feature.jam b/src/tools/features/optimization-feature.jam index 761f76f1e..f02183622 100644 --- a/src/tools/features/optimization-feature.jam +++ b/src/tools/features/optimization-feature.jam @@ -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 ; diff --git a/src/tools/features/os-feature.jam b/src/tools/features/os-feature.jam index d8c384941..6a2c62790 100644 --- a/src/tools/features/os-feature.jam +++ b/src/tools/features/os-feature.jam @@ -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 <> for details of cross-compilation. + +|# # end::doc[] + feature.feature target-os : $(.os-names) : propagated link-incompatible ; feature.set-default target-os : [ default-host-os ] ; diff --git a/src/tools/features/relevant-feature.jam b/src/tools/features/relevant-feature.jam index f55bd7f4c..8069c9f00 100644 --- a/src/tools/features/relevant-feature.jam +++ b/src/tools/features/relevant-feature.jam @@ -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 +`result-feature: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 manually. + +|# # end::doc[] + feature.feature relevant : : incidental free ; diff --git a/src/tools/features/rtti-feature.jam b/src/tools/features/rtti-feature.jam index c271d977f..5943412e4 100644 --- a/src/tools/features/rtti-feature.jam +++ b/src/tools/features/rtti-feature.jam @@ -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 ; diff --git a/src/tools/features/runtime-feature.jam b/src/tools/features/runtime-feature.jam index c4bf9b2ad..f25c178ea 100644 --- a/src/tools/features/runtime-feature.jam +++ b/src/tools/features/runtime-feature.jam @@ -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 ; diff --git a/src/tools/features/sanitizers-feature.jam b/src/tools/features/sanitizers-feature.jam index a02265705..8affd57a9 100644 --- a/src/tools/features/sanitizers-feature.jam +++ b/src/tools/features/sanitizers-feature.jam @@ -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 ; diff --git a/src/tools/features/search-feature.jam b/src/tools/features/search-feature.jam index 618e37263..cbcf2a176 100644 --- a/src/tools/features/search-feature.jam +++ b/src/tools/features/search-feature.jam @@ -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 <> +for examples. + +|# # end::doc[] + feature.feature search : : free path #order-sensitive diff --git a/src/tools/features/source-feature.jam b/src/tools/features/source-feature.jam index 2d6b936d4..7cc1ab8d3 100644 --- a/src/tools/features/source-feature.jam +++ b/src/tools/features/source-feature.jam @@ -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 `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 `` in requirements) or to +conditionally include a source (using conditional requirements, see +the section <>. See also the +<`>> feature. + +|# # end::doc[] + feature.feature source : : free dependency incidental ; diff --git a/src/tools/features/strip-feature.jam b/src/tools/features/strip-feature.jam index 7e13e0d5d..0bb9221af 100644 --- a/src/tools/features/strip-feature.jam +++ b/src/tools/features/strip-feature.jam @@ -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 ; diff --git a/src/tools/features/tag-feature.jam b/src/tools/features/tag-feature.jam index 854a9a70e..1376c6791 100644 --- a/src/tools/features/tag-feature.jam +++ b/src/tools/features/tag-feature.jam @@ -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 ; diff --git a/src/tools/features/threadapi-feature.jam b/src/tools/features/threadapi-feature.jam index 20d52a161..ae320678d 100644 --- a/src/tools/features/threadapi-feature.jam +++ b/src/tools/features/threadapi-feature.jam @@ -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 `` is +`windows` and `pthread` otherwise. + +|# # end::doc[] + feature threadapi : pthread win32 : symmetric propagated ; toolset.add-defaults windows:win32 ; diff --git a/src/tools/features/threading-feature.jam b/src/tools/features/threading-feature.jam index 826c1577d..8d7a8f7c3 100644 --- a/src/tools/features/threading-feature.jam +++ b/src/tools/features/threading-feature.jam @@ -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 ; diff --git a/src/tools/features/toolset-feature.jam b/src/tools/features/toolset-feature.jam index 1e3e371f8..fbd0baba8 100644 --- a/src/tools/features/toolset-feature.jam +++ b/src/tools/features/toolset-feature.jam @@ -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 <> section. + +|# # end::doc[] + feature.feature toolset : : implicit propagated symmetric ; diff --git a/src/tools/features/user-interface-feature.jam b/src/tools/features/user-interface-feature.jam index cbb714a91..d4631ead4 100644 --- a/src/tools/features/user-interface-feature.jam +++ b/src/tools/features/user-interface-feature.jam @@ -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 ; diff --git a/src/tools/features/variant-feature.jam b/src/tools/features/variant-feature.jam index b1e6544df..ced88cebe 100644 --- a/src/tools/features/variant-feature.jam +++ b/src/tools/features/variant-feature.jam @@ -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 ++ +---- +off on off on +---- ++ +The value `release` expands to ++ +---- +speed off full off +---- ++ +The value `profile` expands to the same as `release`, plus: ++ +---- +on 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 ; diff --git a/src/tools/features/version-feature.jam b/src/tools/features/version-feature.jam index cc87eef30..10f7fa7d2 100644 --- a/src/tools/features/version-feature.jam +++ b/src/tools/features/version-feature.jam @@ -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 <`>> +feature. + +|# # end::doc[] + feature.feature version : : free ; diff --git a/src/tools/features/visibility-feature.jam b/src/tools/features/visibility-feature.jam index 957a7220c..443dc89ef 100644 --- a/src/tools/features/visibility-feature.jam +++ b/src/tools/features/visibility-feature.jam @@ -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 ; diff --git a/src/tools/features/warnings-feature.jam b/src/tools/features/warnings-feature.jam index 577a77282..b64bda648 100644 --- a/src/tools/features/warnings-feature.jam +++ b/src/tools/features/warnings-feature.jam @@ -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 ; diff --git a/src/tools/msvc.jam b/src/tools/msvc.jam index 80eb44eb7..988556a9f 100644 --- a/src/tools/msvc.jam +++ b/src/tools/msvc.jam @@ -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 <>), +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 <>), +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 ;