From 5f6d845eed98145f135e6a26d864dfb2ece296e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jurko=20Gospodneti=C4=87?= Date: Thu, 22 May 2008 16:57:52 +0000 Subject: [PATCH] Minor Boost Build documentation changes. [SVN r45662] --- v2/doc/src/tasks.xml | 423 +++++++++++++++++++++++-------------------- 1 file changed, 229 insertions(+), 194 deletions(-) diff --git a/v2/doc/src/tasks.xml b/v2/doc/src/tasks.xml index c2657487b..c6889b49e 100644 --- a/v2/doc/src/tasks.xml +++ b/v2/doc/src/tasks.xml @@ -10,21 +10,20 @@ Common tasks This section describes main targets types that Boost.Build supports - of-of-the-box. Unless otherwise noted, all mentioned main target rules - have the common signature, described in . + out-of-the-box. Unless otherwise noted, all mentioned main target rules have + the common signature, described in . - +
Programs exe - Programs are created using the exe rule, which - follows the common - syntax. For example: + Programs are created using the exe rule, which follows + the common syntax. + For example: -exe hello : hello.cpp some_library.lib /some_project//library - : <threading>multi +exe hello : hello.cpp some_library.lib /some_project//library + : <threading>multi ; This will create an executable file from the sources -- in this case, @@ -35,7 +34,7 @@ exe hello : hello.cpp some_library.lib /some_project//library - + On Windows, if an application uses dynamic libraries, and both the application and the libraries are built by Boost.Build, its not possible to immediately run the application, because the @@ -44,9 +43,9 @@ exe hello : hello.cpp some_library.lib /some_project//library manually, or place the application and the libraries to the same directory. See . - +
@@ -55,27 +54,27 @@ exe hello : hello.cpp some_library.lib /some_project//library Libraries are created using the lib rule, which follows the common - syntax. For example: + syntax. For example: lib helpers : helpers.cpp : <include>boost : : <include>. ; - In the most common case, the lib creates a library - from the specified sources. Depending on the value of - <link> feature the library will be either static or - shared. There are two other cases. First is when the library is - installed somewhere in compiler's search paths, and should be - searched by the compiler (typically, using the - option). The second case is where the library is available as a - prebuilt file and the full path is known. + + In the most common case, the lib creates a library from the + specified sources. Depending on the value of <link> feature the + library will be either static or shared. There are two other cases. + First is when the library is installed somewhere in compiler's search + paths, and should be searched by the compiler (typically, using the + option). The second case is where the library is + available as a prebuilt file and the full path is known. - - + + The syntax for these case is given below: -lib z : : <name>z <search>/home/ghost ; +lib z : : <name>z <search>/home/ghost ; lib compress : : <file>/opt/libs/compress.a ; The name property specifies the name that should be @@ -106,7 +105,7 @@ lib b : : <variant>debug <file>/pool/debug/b.so ; release or debug versions. - + For convenience, the following syntax is allowed: @@ -115,18 +114,19 @@ lib gui db aux ; and is does exactly the same as: -lib z : : <name>z ; -lib gui : : <name>gui ; -lib db : : <name>db ; -lib aux : : <name>aux ; +lib z : : <name>z ; +lib gui : : <name>gui ; +lib db : : <name>db ; +lib aux : : <name>aux ; - - When a library uses another library you should put that other - library in the list of sources. This will do the right thing in all - cases. For portability, you should specify library dependencies even - for searched and prebuilt libraries, othewise, static linking on - Unix won't work. For example: + + + When a library uses another library you should put that other library in + the list of sources. This will do the right thing in all cases. For + portability, you should specify library dependencies even for searched + and prebuilt libraries, othewise, static linking on Unix will not work. + For example: lib z ; lib png : z : <name>png ; @@ -134,15 +134,16 @@ lib png : z : <name>png ; - When a library (say, a), that has another - library, (say, b) + + When a library (say, a), that has another library, (say, + b) is linked dynamically, the b - library will be incorporated + library will be incorporated in a. (If b - is dynamic library as well, then a will only refer to - it, and not include any extra code.) + is dynamic library as well, then a will only refer to it, + and not include any extra code.) When the a library is linked statically, Boost.Build will assure that all @@ -150,9 +151,10 @@ lib png : z : <name>png ; b. - - One feature of Boost.Build that is very important for libraries - is usage requirements. + + + One feature of Boost.Build that is very important for libraries is usage + requirements. @@ -161,7 +163,7 @@ lib png : z : <name>png ; lib helpers : helpers.cpp : : : <include>. ; then the compiler include path for all targets that use - helpers will contain the directory + helpers will contain the directory where the target is defined.path to "helpers.cpp". The user only needs to add helpers to the list of sources, @@ -185,7 +187,7 @@ lib a : a.cpp : <use>b : : <library>b ; a library won't even refer to b. - +
@@ -213,13 +215,13 @@ alias core : im reader writer ; alias threads : /boost/thread//boost_thread : <link>static ; and use only the threads alias in your Jamfiles. - + You can also specify usage requirements for the alias target. If you write the following: -alias header_only_library : : : : <include>/usr/include/header_only_library ; +alias header_only_library : : : : <include>/usr/include/header_only_library ; then using header_only_library in sources will only add an include path. Also note that when an alias has sources, their usage @@ -233,7 +235,7 @@ exe main : main.cpp static_libraries ; will compile main.cpp with additional includes required for using the specified static libraries. - +
@@ -270,19 +272,19 @@ install dist : hello helpers : <location>/usr/bin ; install dist : hello helpers : <variant>release:<location>dist/release <variant>debug:<location>dist/debug ; install dist2 : hello helpers : <location>$(DIST) ; - + See also conditional properties and environment variables Installing with all dependencies - + Specifying the names of all libraries to install can be boring. The install allows you to specify only the top-level executable targets to install, and automatically install all dependencies: -install dist : hello +install dist : hello : <install-dependencies>on <install-type>EXE <install-type>LIB ; @@ -304,16 +306,16 @@ install dist : hello install-source-root By default, the install rules will stip paths from it's sources. So, if sources include a/b/c.hpp, - the a/b part will be ignored. To make the + the a/b part will be ignored. To make the install rule preserve the directory hierarchy you need to use the install-source-root feature to specify the root of the hierarchy you are installing. Relative paths from that root will be preserved. For example, if you write: -install headers - : a/b/c.h - : <location>/tmp <install-source-root>a +install headers + : a/b/c.h + : <location>/tmp <install-source-root>a ; @@ -323,7 +325,7 @@ install headers The glob-tree rule can be used to find all files below a given directory, making it easy to install entire directory tree. - + Installing into Several Directories The alias @@ -336,26 +338,26 @@ install install-lib : helper : /usr/lib ; - Because the install rule just copies targets, most - free features see the definition of "free" in . - have no effect when used in requirements of the install rule. - The only two which matter are - - dependency and, on Unix, - dll-path. + + Because the install rule just copies targets, most free + features see the definition of "free" in + . + have no effect when used in requirements of the install rule. + The only two which matter are dependency + and, on Unix, + dll-path. (Unix specific). On Unix, executables built with Boost.Build typically - contain the list of paths to all used dynamic libraries. For - installing, this is not desired, so Boost.Build relinks the executable - with an empty list of paths. You can also specify additional paths for - installed executables with the dll-path feature. + contain the list of paths to all used dynamic libraries. For installing, + this is not desired, so Boost.Build relinks the executable with an empty + list of paths. You can also specify additional paths for installed + executables with the dll-path feature. -
@@ -363,9 +365,10 @@ install install-lib : helper : /usr/lib ; Testing - Boost.Build has convenient support for running unit tests. The - simplest way is the unit-test rule, which follows the - common syntax. For + + Boost.Build has convenient support for running unit tests. The simplest + way is the unit-test rule, which follows the common syntax. For example: unit-test helpers_test : helpers_test.cpp helpers ; @@ -380,22 +383,22 @@ unit-test helpers_test : helpers_test.cpp helpers ; can't miss a unit test failure. - By default, the executable is run directly. Sometimes, it's + By default, the executable is run directly. Sometimes, it's desirable to run the executable using some helper command. You should use the testing.launcher property to specify the name of the helper command. For example, if you write: -unit-test helpers_test - : helpers_test.cpp helpers +unit-test helpers_test + : helpers_test.cpp helpers : <testing.launcher>valgrind - ; + ; The command used to run the executable will be: -valgrind bin/$toolset/debug/helpers_test +valgrind bin/$toolset/debug/helpers_test - + There are few specialized testing rules, listed below: rule compile ( sources : requirements * : target-name ? ) @@ -403,7 +406,7 @@ rule compile-fail ( sources : requirements * : target-name ? ) rule link ( sources + : requirements * : target-name ? ) rule link-fail ( sources + : requirements * : target-name ? ) - They are are given a list of sources and requirements. + They are are given a list of sources and requirements. If the target name is not provided, the name of the first source file is used instead. The compile* tests try to compile the passed source. The link* @@ -415,10 +418,10 @@ rule link-fail ( sources + : requirements * : target-name ? ) There are two specialized rules for running applications, which - are more powerful than the unit-test rule. The + are more powerful than the unit-test rule. The run rule has the following signature: -rule run ( sources + : args * : input-files * : requirements * : target-name ? +rule run ( sources + : args * : input-files * : requirements * : target-name ? : default-build * ) The rule builds application from the provided sources and runs it, @@ -430,15 +433,15 @@ rule run ( sources + : args * : input-files * : requirements * : target-name ? directory. The run-fail rule is identical to the run rule, except that it expects that the run fails. - + All rules described in this section, if executed successfully, create a special manifest file to indicate that the test passed. For the unit-test rule the files is named target-name.passed and - for the other rules it is called + for the other rules it is called target-name.test. The run* rules also capture all output from the program, - and store it in a file named + and store it in a file named target-name.output. The run and the run-fail rules, if @@ -451,12 +454,12 @@ rule run ( sources + : args * : input-files * : requirements * : target-name ? the --dump-tests command-line option. The output will consist of lines of the form: -boost-test(test-type) path : sources - +boost-test(test-type) path : sources + It is possible to process the list of tests, the output of - bjam during command run, and the presense/absense of the + bjam during command run, and the presense/absense of the *.test files created when test passes into human-readable status table of tests. Such processing utilities are not included in Boost.Build. @@ -467,53 +470,64 @@ boost-test(test-type) path Custom commands - When you use most of main target rules, Boost.Build automatically - figures what commands to run and it what order. As soon as you want - to use new file types, or support new tools, one approach is to - extend Boost.Build to smoothly support them, as documented in - . However, if there's a single - place where the new tool is used, it might be easier to just - explicitly specify the commands to run. - - Three main target rules can be used for that. The - make rule allows you to construct - a single file from any number of source file, by running a - command you specify. The notfile rule - allows you to run an arbitrary command, without creating any files. - Finaly, the generate rule allows you - to describe transformation using Boost.Build's virtual targets. - This is higher-level than file names that the make rule operates with, - and allows you to create more than one target, or create differently - named targets depending on properties, or use more than one - tool. - - The make rule is used when you want to - create one file from a number of sources using some specific command. - The notfile is used to unconditionally run - a command. + + When you use most of main target rules, Boost.Build automatically + figures what commands to run and it what order. As soon as you want to + use new file types, or support new tools, one approach is to extend + Boost.Build to smoothly support them, as documented in + . However, if there's a single place + where the new tool is used, it might be easier to just explicitly + specify the commands to run. - Suppose you want to create file file.out from - file file.in by running command - in2out. Here's how you'd do this in Boost.Build: + + Three main target rules can be used for that. The make + rule allows you to construct a single file from any + number of source file, by running a command you specify. The + notfile rule allows you to run an arbitrary + command, without creating any files. And finaly, the + generate rule allows you to describe transformation using + Boost.Build's virtual targets. This is higher-level than file names that + the make rule operates with and allows you + to create more than one target, create differently named targets + depending on properties or use more than one tool. + + + + The make rule is used when you want to + create one file from a number of sources using some specific command. + The notfile is used to unconditionally run + a command. + + + + + + Suppose you want to create file file.out from file + file.in by running command + in2out. Here is how you would do this in Boost.Build: +make file.out : file.in : @in2out ; actions in2out { in2out $(<) $(>) } -make file.out : file.in : @in2out ; - If you run bjam and file.out + If you run bjam and file.out does not exist, Boost.Build will run the in2out - command to create that file. For more details on specifying actions, - see . + command to create that file. For more details on specifying actions, see + . - - It could be that you just want to run some command unconditionally, - and that command does not create any specific files. The, you can use + It could be that you just want to run some command unconditionally, and + that command does not create any specific files. For that you can use the notfile rule. For example: notfile echo_something : @echo ; @@ -527,97 +541,118 @@ actions echo Boost.Build will unconditionally run the action. - The generate rule is used when - you want to express transformations using Boost.Build's virtual targets, - as opposed to just filenames. The generate - rule has the standard main target rule signature, but you are required - to specify the generating-rule property. The value - of the property should be in the form - @rule-name and the named - rule should have the following signature: - + + + The generate rule is used when you want to + express transformations using Boost.Build's virtual targets, as opposed + to just filenames. The generate rule has + the standard main target rule signature, but you are required to specify + the generating-rule property. The value of the + property should be in the form + @rule-name, the named rule + should have the following signature: + rule generating-rule ( project name : property-set : sources * ) - - and will be called with an instance of the project-target - class, the name of the main target, an instance of the - property-set class containing build properties, - and the list of instances of the virtual-target class - corresponding to sources. - The rule must return a list of virtual-target instances. - The interface of the virtual-target class can be learned - by looking at the build/virtual-target.jam file. - The generate example in Boost.Build distribution - illustrates how the generate rule can be used. + + and will be called with an instance of the project-target + class, the name of the main target, an instance of the + property-set class containing build properties, and the + list of instances of the virtual-target class corresponding + to sources. The rule must return a list of virtual-target + instances. The interface of the virtual-target class can be + learned by looking at the build/virtual-target.jam + file. The generate example contained in the + Boost.Build distribution illustrates how the generate + rule can be used. - +
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. + + 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 the following steps: + - 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. + + Create a header that includes headers used by your project that you + want precompiled. It is 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 a new Boost.Build target for the precompiled header - and add that precompiled header to the sources of the target whose compilation - you want to speed up: - + + Declare a new Boost.Build target for the precompiled header and add + that precompiled header to the sources of the target whose compilation + you want to speed up: + cpp-pch pch : pch.hpp ; -exe main : main.cpp pch ; - You can use the c-pch if you want to use the precompiled - header in C programs. +exe main : main.cpp pch ; + + You can use the c-pch rule 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 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 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 compile the source files - and the precompiled header must be the same. Consider using - project requirements to assure this. + + The build properties used to compile the source files and the + precompiled header 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. + + 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. + - On the gcc compiler, the name of the header being - precompiled must be equal to the name of the cpp-pch - target. This is gcc requirement. + + On the gcc compiler, the name of the header being precompiled must be + equal to the name of the cpp-pch target. This is a gcc + requirement. + - Prior to version 4.2, the gcc compiler did not - handle anonymous namespaces in precompiled headers, which - limit their utility. See the bug - report for details. - + + Prior to version 4.2, the gcc compiler did not allow anonymous + namespaces in precompiled headers, which limits their utility. See the + bug + report for details. + - -
-
Generated headers @@ -625,7 +660,7 @@ exe main : main.cpp pch ; automatically. For example, for C++ files, all #include statements are found and handled. The only aspect where user help might be needed is implicit dependency on generated files. - + By default, Boost.Build handles such dependencies within one main target. For example, assume that main target "app" has two sources, "app.cpp" and "parser.y". The latter source is converted @@ -634,13 +669,13 @@ exe main : main.cpp pch ; since "parser.h" will be generated into a build directory, the path to that directory will automatically added to include path. - + Making this mechanism work across main target boundaries is possible, but imposes certain overhead. For that reason, if there's implicit dependency on files from other main targets, the <implicit-dependency> [ link ] feature must be used, for example: - + lib parser : parser.y ; exe app : app.cpp : <implicit-dependency>parser ; @@ -652,14 +687,14 @@ exe app : app.cpp : <implicit-dependency>parser ; targets from "parser" as potential dependencies.
- +