diff --git a/doc/src/reference.adoc b/doc/src/reference.adoc index 688bcae11..18ca34507 100644 --- a/doc/src/reference.adoc +++ b/doc/src/reference.adoc @@ -206,365 +206,72 @@ 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. +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] -[[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/lto-feature.jam[tag=doc] [[bbv2.reference.tools]] == Builtin tools diff --git a/src/tools/clang-darwin.jam b/src/tools/clang-darwin.jam index d18ea4274..eb1ebce6a 100644 --- a/src/tools/clang-darwin.jam +++ b/src/tools/clang-darwin.jam @@ -16,9 +16,9 @@ import generators ; feature.extend-subfeature toolset clang : platform : darwin ; -toolset.inherit-generators clang-darwin - clang darwin - : gcc +toolset.inherit-generators clang-darwin + clang darwin + : gcc # Don't inherit PCH generators. They were not tested, and probably # don't work for this compiler. : gcc.mingw.link gcc.mingw.link.dll gcc.compile.c.pch gcc.compile.c++.pch @@ -32,30 +32,32 @@ generators.register-c-compiler clang-darwin.compile.m : OBJECTIVE_C : OBJ : clang darwin ; toolset.inherit-rules clang-darwin : gcc ; -toolset.inherit-flags clang-darwin : gcc +toolset.inherit-flags clang-darwin : gcc : full x86/32 x86/64 + on/full + on/fat ; - + if [ MATCH (--debug-configuration) : [ modules.peek : ARGV ] ] { .debug-configuration = true ; } - + # Initializes the clang-darwin toolset # version in optional # name (default clang++) is used to invoke the specified clang compiler # compile and link options allow you to specify addition command line options for each version rule init ( version ? : command * : options * ) { - command = [ common.get-invocation-command clang-darwin : clang++ + command = [ common.get-invocation-command clang-darwin : clang++ : $(command) : /usr/bin /usr/local/bin ] ; # Determine the version local command-string = $(command:J=" ") ; if $(command) - { + { version ?= [ MATCH "version ([0-9]+[.][0-9]+)" : [ SHELL "$(command-string) --version" ] ] ; } @@ -90,6 +92,13 @@ toolset.flags clang-darwin.compile OPTIONS full : -Wno-inline ; # shouldn't this be handled by the common gcc? toolset.flags clang-darwin.compile OPTIONS ; +# LTO +toolset.flags clang-darwin.compile OPTIONS on/thin : -flto=thin ; +toolset.flags clang-darwin.link OPTIONS on/thin : -flto=thin ; + +toolset.flags clang-darwin.compile OPTIONS on/full : -flto=full ; +toolset.flags clang-darwin.link OPTIONS on/full : -flto=full ; + actions compile.c { "$(CONFIG_COMMAND)" -x c $(OPTIONS) $(USER_OPTIONS) -D$(DEFINES) -I"$(INCLUDES)" -c -o "$(<)" "$(>)" @@ -123,11 +132,11 @@ rule archive ( targets * : sources * : properties * ) # Always remove archive and start again. Here's rationale from # Andre Hentz: # - # I had a file, say a1.c, that was included into liba.a. - # I moved a1.c to a2.c, updated my Jamfiles and rebuilt. - # My program was crashing with absurd errors. - # After some debugging I traced it back to the fact that a1.o was *still* - # in liba.a + # I had a file, say a1.c, that was included into liba.a. + # I moved a1.c to a2.c, updated my Jamfiles and rebuilt. + # My program was crashing with absurd errors. + # After some debugging I traced it back to the fact that a1.o was *still* + # in liba.a # # Rene Rivera: # diff --git a/src/tools/clang-linux.jam b/src/tools/clang-linux.jam index 75b3e631f..8314ff3b6 100644 --- a/src/tools/clang-linux.jam +++ b/src/tools/clang-linux.jam @@ -20,7 +20,7 @@ import numbers ; feature.extend-subfeature toolset clang : platform : linux ; -toolset.inherit-generators clang-linux +toolset.inherit-generators clang-linux clang linux : gcc : gcc.mingw.link gcc.mingw.link.dll gcc.cygwin.link gcc.cygwin.link.dll ; generators.override clang-linux.prebuilt : builtin.lib-generator ; @@ -30,26 +30,28 @@ generators.override clang-linux.searched-lib-generator : searched-lib-generator # Override default do-nothing generators. generators.override clang-linux.compile.c.pch : pch.default-c-pch-generator ; generators.override clang-linux.compile.c++.pch : pch.default-cpp-pch-generator ; - + type.set-generated-target-suffix PCH : clang linux : pth ; toolset.inherit-rules clang-linux : gcc ; -toolset.inherit-flags clang-linux : gcc +toolset.inherit-flags clang-linux : gcc : full multi/windows + on/full + on/fat ; - + if [ MATCH (--debug-configuration) : [ modules.peek : ARGV ] ] { .debug-configuration = true ; } - + rule init ( version ? : command * : options * ) { - command = [ common.get-invocation-command clang-linux : clang++ + command = [ common.get-invocation-command clang-linux : clang++ : $(command) ] ; - + # Determine the version - if $(command) { + if $(command) { local command-string = \"$(command)\" ; command-string = $(command-string:J=" ") ; version ?= [ MATCH "version ([0-9.]+)" @@ -58,7 +60,7 @@ rule init ( version ? : command * : options * ) { local condition = [ common.check-init-parameters clang-linux : version $(version) ] ; - + common.handle-options clang-linux : $(condition) : $(command) : $(options) ; clang.init-cxxstd-flags clang-linux : $(condition) : $(version) ; @@ -69,9 +71,9 @@ rule init ( version ? : command * : options * ) { # can be found at runtime, while the $(command) can be a script that sets the # PATH for both the clang directory and the backende gcc directory # before calling clang++ when compiling/linking. - + local root = [ feature.get-values : $(options) ] ; - + if $(root) { # On multilib 64-bit boxes, there are both 32-bit and 64-bit libraries @@ -86,7 +88,7 @@ rule init ( version ? : command * : options * ) { } toolset.flags clang-linux.link RUN_PATH $(condition) : $(lib_path) ; } - + # - Ranlib. local ranlib = [ feature.get-values : $(options) ] ; if ( ! $(ranlib) ) && $(root) @@ -114,6 +116,13 @@ toolset.flags clang-linux.compile OPTIONS full : -Wno-inline ; toolset.flags clang-linux.compile OPTIONS multi/windows : -pthread ; toolset.flags clang-linux.link OPTIONS multi/windows : -pthread ; +# LTO +toolset.flags clang-linux.compile OPTIONS on/thin : -flto=thin ; +toolset.flags clang-linux.link OPTIONS on/thin : -flto=thin ; + +toolset.flags clang-linux.compile OPTIONS on/full : -flto=full ; +toolset.flags clang-linux.link OPTIONS on/full : -flto=full ; + ############################################################################### # C and C++ compilation 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/lto-feature.jam b/src/tools/features/lto-feature.jam new file mode 100644 index 000000000..99ca7bdcc --- /dev/null +++ b/src/tools/features/lto-feature.jam @@ -0,0 +1,46 @@ +# Copyright 2019 Dmitry Arkhipov +# Distributed under the Boost Software License, Version 1.0. +# (See accompanying file LICENSE_1_0.txt or copy at +# http://www.boost.org/LICENSE_1_0.txt) + +import feature ; + +#| tag::doc[] + +[[bbv2.builtin.features.lto]]`lto`:: +*Allowed values:* `on`. ++ +Enables link time optimizations (also known as interprocedural optimizations or +whole-program optimizations). Currently supported toolsets are <>, +clang and <>. The feature is optional. + +|# # end::doc[] + +feature.feature lto + : on + : optional propagated ; + +#| tag::doc[] + +[[bbv2.builtin.features.lto-mode]]`lto-mode`:: +*Subfeature of* `lto` ++ +*Allowed values:* `full`, `thin`, `fat`. ++ +Specifies the type of LTO to use. ++ +`full`::: Use the monolithic LTO: on linking all input is merged into a single + module. +`thin`::: Use clang's ThinLTO: each compiled file contains a summary of the + module, these summaries are merged into a single index. This allows to avoid + merging all modules together, which greatly reduces linking time. +`fat`::: Produce gcc's fat LTO objects: compiled files contain both the + intermidiate language suitable for LTO and object code suitable for regular + linking. + +|# # end::doc[] + +feature.subfeature lto + : mode + : full thin fat + : propagated ; 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/gcc.jam b/src/tools/gcc.jam index d2bb06b29..47de21f89 100644 --- a/src/tools/gcc.jam +++ b/src/tools/gcc.jam @@ -748,6 +748,14 @@ toolset.flags gcc.compile.c++ OPTIONS on : --coverage ; toolset.flags gcc.compile.c++ DEFINES off/vxworks : _NO_RTTI ; toolset.flags gcc.compile.c++ DEFINES off/vxworks : _NO_EX=1 ; +# LTO +toolset.flags gcc.compile OPTIONS on/full : -flto ; +toolset.flags gcc.link OPTIONS on/full : -flto ; + +toolset.flags gcc.compile OPTIONS on/fat : -flto -ffat-lto-objects ; +toolset.flags gcc.link OPTIONS on/fat : -flto ; + + ### ### User free feature options. ### diff --git a/src/tools/generators/archive-generator.jam b/src/tools/generators/archive-generator.jam index 1b8721802..6afc8e7aa 100644 --- a/src/tools/generators/archive-generator.jam +++ b/src/tools/generators/archive-generator.jam @@ -52,7 +52,7 @@ class archive-generator : generator { for local t in $(sources) { - if [ type.is-derived [ $(t).type ] LIB ] + if [ $(t).type ] && [ type.is-derived [ $(t).type ] LIB ] { usage-requirements += $(t) ; } diff --git a/src/tools/generators/linking-generator.jam b/src/tools/generators/linking-generator.jam index 23d0c1e8c..37277a0b2 100644 --- a/src/tools/generators/linking-generator.jam +++ b/src/tools/generators/linking-generator.jam @@ -53,7 +53,7 @@ class linking-generator : generator local extra-xdll-paths ; for local s in $(sources) { - if [ type.is-derived [ $(s).type ] SHARED_LIB ] && ! [ $(s).action ] + if [ $(s).type ] && [ type.is-derived [ $(s).type ] SHARED_LIB ] && ! [ $(s).action ] { local location = [ path.root [ $(s).name ] [ $(s).path ] ] ; @@ -143,7 +143,7 @@ class linking-generator : generator local fst ; for local s in $(sources) { - if [ type.is-derived [ $(s).type ] SEARCHED_LIB ] + if [ $(s).type ] && [ type.is-derived [ $(s).type ] SEARCHED_LIB ] { local name = [ $(s).name ] ; if [ $(s).shared ] diff --git a/src/tools/msvc.jam b/src/tools/msvc.jam index 9bc51d862..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 ; @@ -480,9 +506,9 @@ rule configure-version-specific ( toolset : version : conditions ) # Feature for handling targeting different Windows API sets. feature.feature windows-api : desktop store phone : propagated composite link-incompatible ; -feature.compose store : WINAPI_FAMILY=WINAPI_FAMILY_APP _WIN32_WINNT=0x0602 +feature.compose store : WINAPI_FAMILY=WINAPI_FAMILY_APP _WIN32_WINNT=0x0602 /APPCONTAINER ; -feature.compose phone : WINAPI_FAMILY=WINAPI_FAMILY_PHONE_APP _WIN32_WINNT=0x0602 +feature.compose phone : WINAPI_FAMILY=WINAPI_FAMILY_PHONE_APP _WIN32_WINNT=0x0602 /APPCONTAINER "/NODEFAULTLIB:ole32.lib" "/NODEFAULTLIB:kernel32.lib" WindowsPhoneCore.lib ; feature.set-default windows-api : desktop ; @@ -729,7 +755,7 @@ rule link ( targets + : sources * : properties * ) DEPENDS $(<) : [ on $(<) return $(EMBED_MANIFEST_FILE) ] ; msvc.manifest.user $(targets) $(EMBED_MANIFEST_FILE) : $(sources) : $(properties) ; } - else + else { msvc.manifest $(targets) : $(sources) : $(properties) ; } @@ -763,7 +789,7 @@ rule link.dll ( targets + : sources * : properties * ) DEPENDS $(<) : [ on $(<) return $(EMBED_MANIFEST_FILE) ] ; msvc.manifest.dll.user $(targets) $(EMBED_MANIFEST_FILE) : $(sources) : $(properties) ; } - else + else { msvc.manifest.dll $(targets) : $(sources) : $(properties) ; } @@ -1003,13 +1029,13 @@ local rule generate-setup-cmd ( version : command : parent : options * : cpu : g { local setup-options ; local setup = [ feature.get-values : $(options) ] ; - + if ! $(setup)-is-defined { if $(global-setup)-is-defined { setup = $(global-setup) ; - + # If needed we can easily add using configuration flags # here for overriding which options get passed to the # global setup command for which target platform: @@ -1038,7 +1064,7 @@ local rule generate-setup-cmd ( version : command : parent : options * : cpu : g setup ?= [ path.join $(parent) "vcvarsall.bat" ] ; } } - + return $(setup) "$(setup-options:J= )" ; } @@ -1081,7 +1107,7 @@ IMPORT msvc : rewrite-setup : : msvc.rewrite-setup ; # Helper rule to generate a faster alternative to MSVC setup scripts. # We used to call MSVC setup scripts directly in every action, however in -# newer MSVC versions (10.0+) they make long-lasting registry queries +# newer MSVC versions (10.0+) they make long-lasting registry queries # which have a significant impact on build time. local rule set-setup-command ( targets * : properties * ) { @@ -1282,7 +1308,7 @@ local rule configure-really ( version ? : options * ) local below-8.0 = [ MATCH "^([67]\\.)" : $(version) ] ; local below-11.0 = [ MATCH "^([6789]\\.|10\\.)" : $(version) ] ; - + local cpu = i386 amd64 ia64 arm arm64 ; if $(below-8.0) { @@ -1292,7 +1318,7 @@ local rule configure-really ( version ? : options * ) { cpu = i386 amd64 ia64 ; } - + local setup-amd64 ; local setup-i386 ; local setup-ia64 ; @@ -1403,7 +1429,7 @@ local rule configure-really ( version ? : options * ) exact-version ?= $(version) ; setup-$(c) = [ generate-setup-cmd $(exact-version) : $(command) : $(parent) : $(options) : $(c) : $(global-setup) : $(default-global-setup-options-$(c)) : $(default-setup-$(c)) ] ; } - + # Windows phone has different setup scripts, located in a different directory hierarchy. # The 11.0 toolset can target Windows Phone 8.0 and the 12.0 toolset can target Windows Phone 8.1, # each of which have a different directory for their vcvars setup scripts. @@ -1418,7 +1444,7 @@ local rule configure-really ( version ? : options * ) phone-directory = [ path.native [ path.join $(phone-directory) WP81 ] ] ; } global-setup-phone ?= [ locate-default-setup $(phone-directory) : $(phone-parent) : vcvarsphoneall.bat ] ; - + # If can't locate default phone setup script then this VS version doesn't support Windows Phone. if $(global-setup-phone)-is-defined { @@ -1492,7 +1518,7 @@ local rule configure-really ( version ? : options * ) if always in $(options) { - toolset.flags msvc .REWRITE-SETUP $(api)/$(cpu-conditions) : true ; + toolset.flags msvc .REWRITE-SETUP $(api)/$(cpu-conditions) : true ; } if ! $(setup-script) @@ -1543,6 +1569,10 @@ local rule configure-really ( version ? : options * ) toolset.flags msvc.link LINKPATH $(conditions)/store/$(.cpu-arch-arm) : [ path.native [ path.join $(storeLibPath) "arm" ] ] ; } + # LTO + toolset.flags msvc.compile OPTIONS $(conditions)/on : /GL ; + toolset.flags msvc.link OPTIONS $(conditions)/on : /LTCG ; + # Set version-specific flags. configure-version-specific msvc : $(version) : $(conditions) ; } @@ -1863,7 +1893,7 @@ local rule register-toolset-really ( ) toolset.flags msvc.link FINDLIBS_SA ; toolset.flags msvc.link LIBRARY_OPTION msvc : "" : unchecked ; toolset.flags msvc.link LIBRARIES_MENTIONED_BY_FILE : ; - + toolset.flags msvc.link.dll LINKFLAGS true : /NOENTRY ; }