diff --git a/v2/doc/src/advanced.xml b/v2/doc/src/advanced.xml index ac7fb615c..b6377858c 100644 --- a/v2/doc/src/advanced.xml +++ b/v2/doc/src/advanced.xml @@ -766,6 +766,34 @@ rule my-rule ( properties * ) requirements can be easier to write and understand. + Requirements explicitly specified for a target are usually + combined with the requirements specified for the containing project. You + can cause a target to completely ignore specific project's requirement + using the syntax by adding minus sign before a property, for example: + +exe main : main.cpp : -<define>UNNECESSARY_DEFINE ; + + This syntax is the only way to ignore free properties from parent, + such as defines. It can be also useful for ordinary properties. Consider + this example: + +project test : requirements <threading;>multi ; +exe test1 : test1.cpp ; +exe test2 : test2.cpp : <threading;>single ; +exe test3 : test3.cpp : -<threading;>multi ; + + Here, test1 inherits project requirements and will always + be built in multi-threaded mode. The test2 target + overrides project's requirements and will + always be built in single-threaded mode. In contrast, the + test3 target removes a property + from project requirements and will be built either in single-threaded or + multi-threaded mode depending on which variant is requested by the + user. + + Note that removing of requirements is completely textual: + you need to specify exactly the same property to remove it. +
diff --git a/v2/doc/src/tasks.xml b/v2/doc/src/tasks.xml index d92ec2ebf..f9e6e444f 100644 --- a/v2/doc/src/tasks.xml +++ b/v2/doc/src/tasks.xml @@ -458,6 +458,63 @@ actions echo
+
+ Precompiled headers + + Precompiled headers is a mechanism to speed up compilation + by creating a partially processed version of some header files, + and then using that version during compilations rather then + repeatedly parsing the original headers. Boost.Build supports + precompiled headers with gcc and msvc toolsets. + + To use precompiled headers, follow these steps: + + Create a header that includes big headers used by your project. + It's better to include only headers that are sufficiently stable — + like headers from the compiler, and external libraries. Please wrap + the header in #ifdef BOOST_BUILD_PCH_ENABLED, so that + the potentially expensive inclusion of headers is not done + when PCH is not enabled. Include the new header at the top of your + source files. + + Declare new Boost.Build target for the precompiled header + and add that precompiled header to sources of the target whose compilation + you want to speed up: + +cpp-pch pch : header.hpp ; +exe main : main.cpp pch ; + You can use the c-pch if you want to use the precompiled + header in C programs. + + + + The pch example in Boost.Build distribution + can be used as reference. + + Please note the following: + + The inclusion of the precompiled header must be the + first thing in a source file, before any code or preprocessor directives. + + + The build properties used to build the sources and the + preprocessed must be the same. Consider using project requirements to + assure this. + + + Precompiled headers must be used purely as a way to + improve compilation time, not to save the number of include statements. + If a source file needs to include some header, explicitly include + it in the source file, even if the same header is included from + the precompiled header. This makes sure that your project will build + even if precompiled headers are not supported. + + + + +
+ +
Generated headers @@ -720,7 +777,29 @@ exe app : app.cpp : <implicit-dependency>parser ; + 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 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. + + +