|
|
Boost-Commit : |
From: jurko.gospodnetic_at_[hidden]
Date: 2008-08-23 11:15:41
Author: jurko
Date: 2008-08-23 11:15:40 EDT (Sat, 23 Aug 2008)
New Revision: 48320
URL: http://svn.boost.org/trac/boost/changeset/48320
Log:
Minor stylistic changes made to the Boost Build task.xml documentation. Cleaned up the wording in a few places.
Text files modified:
trunk/tools/build/v2/doc/src/tasks.xml | 939 ++++++++++++++++++++-------------------
1 files changed, 481 insertions(+), 458 deletions(-)
Modified: trunk/tools/build/v2/doc/src/tasks.xml
==============================================================================
--- trunk/tools/build/v2/doc/src/tasks.xml (original)
+++ trunk/tools/build/v2/doc/src/tasks.xml 2008-08-23 11:15:40 EDT (Sat, 23 Aug 2008)
@@ -9,328 +9,339 @@
<chapter id="bbv2.tasks">
<title>Common tasks</title>
- <para>This section describes main targets types that Boost.Build supports
- out-of-the-box. Unless otherwise noted, all mentioned main target rules have
- the common signature, described in <xref linkend="bbv2.advanced.targets"/>.
+ <para>
+ This section describes main targets types that Boost.Build supports
+ out-of-the-box. Unless otherwise noted, all mentioned main target rules have
+ the common signature, described in <xref linkend="bbv2.advanced.targets"/>.
</para>
<section id="bbv2.tasks.programs">
<title>Programs</title>
- <indexterm><primary>exe</primary></indexterm>
- <para>Programs are created using the <code>exe</code> rule, which follows
- the <link linkend="bbv2.main-target-rule-syntax">common syntax</link>.
- For example:
+ <indexterm><primary>exe</primary></indexterm>
+ <para>
+ Programs are created using the <code>exe</code> rule, which follows the
+ <link linkend="bbv2.main-target-rule-syntax">common syntax</link>. For
+ example:
<programlisting>
exe hello : hello.cpp some_library.lib /some_project//library
: <threading>multi
;
</programlisting>
- This will create an executable file from the sources -- in this case,
- one C++ file, one library file present in the same directory, and
- another library that is created by Boost.Build. Generally, sources
- can include C and C++ files, object files and libraries. Boost.Build
- will automatically try to convert targets of other types.
- </para>
+ This will create an executable file from the sources -- in this case, one
+ C++ file, one library file present in the same directory, and another
+ library that is created by Boost.Build. Generally, sources can include C
+ and C++ files, object files and libraries. Boost.Build will automatically
+ try to convert targets of other types.
+ </para>
- <tip>
- <para>
- 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
- <literal>PATH</literal> environment variable should include the path
- to the libraries. It means you have to either add the paths
- manually, or place the application and the libraries to the same
- directory. See <xref linkend="bbv2.tasks.installing"/>.
- </para>
- <!-- We should be emphasizing the use of the built-in testing rules
- rather than continually discussing these quirks of running programs
- with dynamic libraries. -->
- </tip>
- </section>
-
- <section id="bbv2.tasks.libraries">
- <title>Libraries</title>
-
- <para>Libraries are created using the <code>lib</code> rule, which
- follows the <link linkend="bbv2.main-target-rule-syntax">common
- syntax</link>. For example:
+ <tip>
+ <para>
+ On Windows, if an application uses shared libraries, and both the
+ application and the libraries are built using Boost.Build, it is not
+ possible to immediately run the application, because the <literal>PATH
+ </literal> environment variable should include the path to the
+ libraries. It means you have to either add the paths manually, or have
+ the build place the application and the libraries into the same
+ directory. See <xref linkend="bbv2.tasks.installing"/>.
+ </para>
+ <!-- We should be emphasizing the use of the built-in testing rules
+ rather than continually discussing these quirks of running programs
+ with shared libraries. -->
+ </tip>
+ </section>
+
+ <section id="bbv2.tasks.libraries">
+ <title>Libraries</title>
+
+ <para>
+ Library targets are created using the <code>lib</code> rule, which
+ follows the <link linkend="bbv2.main-target-rule-syntax">common syntax
+ </link>. For example:
<programlisting>
-lib helpers : helpers.cpp : <include>boost : : <include>. ;
+lib helpers : helpers.cpp ;
</programlisting>
- </para>
- <!-- Add one sentence that says what the above does. -->
- <para>
- In the most common case, the <code>lib</code> 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>-l</option> option). The second case is where the library is
- available as a prebuilt file and the full path is known.
- <!-- But the first case is also prebuilt. This is confusingly phrased. -->
- </para>
+ This will define a library target named <code>helpers</code> built from
+ the <code>helpers.cpp</code> source file.
+ </para>
+ <para>
+ Depending on the given <link> feature value the library will be
+ either static or shared.
+ </para>
+ <para>
+ Library targets may be used to represent:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <term>Built libraries</term> that get built from specified sources,
+ as is the one in the example above. <!-- add link -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <term>Prebuilt libraries</term> which already exist on the system
+ and are just supposed to be used by the build system. Such
+ libraries may be searched for by the tools using them (typically
+ linkers referencing the library using the <option>-l</option>
+ option) or their path may be known in advance by the build system.
+ <!-- We need examples for this. -->
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
- <para>
- The syntax for these case is given below:
+ <para>
+ The syntax for these case is given below:
<programlisting>
lib z : : <name>z <search>/home/ghost ;
lib compress : : <file>/opt/libs/compress.a ;
</programlisting>
- The <code>name</code> property specifies the name that should be
- passed to the <option>-l</option> option, and the <code>file</code>
- property specifies the file location. The <varname>search</varname> feature
- specifies paths in which to search for the library. That feature can
- be specified several times, or it can be omitted, in which case only
- default compiler paths will be searched.
- </para>
+ The <code>name</code> property specifies the name that should be passed to
+ the <option>-l</option> option, and the <code>file</code> property
+ specifies the file location. The <varname>search</varname> feature
+ specifies paths in which to search for the library. That feature can be
+ specified several times or it can be omitted, in which case only the
+ default compiler paths will be searched.
+ </para>
- <para>The difference between using the <varname>file</varname> feature as
- opposed to the <varname>name</varname> feature together with the
- <varname>search</varname> feature is that <varname>file</varname> is more
- precise. A specific file will be used. On the other hand, the
- <varname>search</varname> feature only adds a library path, and the
- <varname>name</varname> feature gives the basic name of the library. The
- search rules are specific to the linker. For example, given these
- definition:
+ <para>
+ The difference between using the <varname>file</varname> feature as
+ opposed to the <varname>name</varname> feature together with the <varname>
+ search</varname> feature is that <varname>file</varname> is more precise.
+ A specific file will be used as opposed to the <varname>search</varname>
+ feature only adding a library path, or the <varname>name</varname> feature
+ giving only the basic name of the library. The search rules are specific
+ to the linker used. For example, given these definition:
<programlisting>
lib a : : <variant>release <file>/pool/release/a.so ;
lib a : : <variant>debug <file>/pool/debug/a.so ;
lib b : : <variant>release <file>/pool/release/b.so ;
lib b : : <variant>debug <file>/pool/debug/b.so ;
</programlisting>
- It's possible to use release version of <code>a</code> and debug
- version of <code>b</code>. Had we used the <varname>name</varname> and
- <varname>search</varname> features, the linker would always pick either
- release or debug versions.
- <!-- explain -->
- </para>
+ It is possible to use a release version of <code>a</code> and debug
+ version of <code>b</code>. Had we used the <varname>name</varname> and
+ <varname>search</varname> features, the linker would have always picked
+ either the release or the debug versions.
+ <!-- explain -->
+ </para>
- <para>
- For convenience, the following syntax is allowed:
+ <para>
+ For convenience, the following syntax is allowed:
<programlisting>
lib z ;
lib gui db aux ;
</programlisting>
- and is does exactly the same as:
+ which has exactly the same effect as:
<programlisting>
lib z : : <name>z ;
lib gui : : <name>gui ;
lib db : : <name>db ;
lib aux : : <name>aux ;
</programlisting>
- </para>
+ </para>
- <para>
- 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:
+ <para>
+ When a library references another library you should put that other
+ library in its list of sources. This will do the right thing in all cases.
+ <!--Add a link to the notes below. --> For portability, you should specify
+ library dependencies even for searched and prebuilt libraries, othewise,
+ static linking on Unix will not work. For example:
<programlisting>
lib z ;
lib png : z : <name>png ;
</programlisting>
- </para>
-
- <note>
- <para>
- When a library (say, <code>a</code>), that has another library, (say,
- <code>b</code>)
- <!-- how can a library "have" a library? -->
- is linked dynamically, the <code>b</code>
- library will be incorporated
- <!-- Incorporated? Be precise. -->
- in <code>a</code>. (If <code>b</code>
- is dynamic library as well, then <code>a</code> will only refer to it,
- and not include any extra code.)
- <!-- Don't parenthesize a whole sentence. -->
- When the <code>a</code>
- library is linked statically, Boost.Build will assure that all
- executables that link to <code>a</code> will also link to
- <code>b</code>.
- </para>
- </note>
+ </para>
+ <note>
<para>
- One feature of Boost.Build that is very important for libraries is usage
- requirements.
- <!-- Rephrase that. But then, it's much too late for an
- introduction of usage requirements - you've already
- discussed them many times. -->
- For example, if you write:
-<programlisting>
-lib helpers : helpers.cpp : : : <include>. ;
-</programlisting>
- then the compiler include path for all targets that use
- <code>helpers</code> will contain the directory
- <!-- The rest of this sentence is unintelligible -->
- where the target is defined.path to "helpers.cpp". The user
- only needs to add <code>helpers</code> to the list of sources,
- and needn't consider the requirements its use imposes on a
- dependent target. This feature greatly simplifies Jamfiles.
- <!-- You can't say “allows toâ€â€”you need a noun. This error is
- repeated throughout. -->
+ When a library has a shared library defined as its source, or a static
+ library has another static library defined as its source then any target
+ linking to the first library with automatically link to its source
+ library as well.
</para>
-
- <note>
- <para>If you don't want shared libraries to include all libraries
- that are specified in sources (especially statically linked ones),
- you'd need to use the following:
+ <para>
+ On the other hand, when a shared library has a static library defined as
+ its source then the first library will be built so that it completely
+ includes the second one.
+ </para>
+ <para>
+ If you do not want shared libraries to include all libraries specified
+ in its sources (especially statically linked ones), you would need to
+ use the following:
<programlisting>
lib b : a.cpp ;
lib a : a.cpp : <use>b : : <library>b ;
</programlisting>
- This specifies that <code>a</code> uses <code>b</code>, and causes
- all executables that link to <code>a</code> also link to
- <code>b</code>. In this case, even for shared linking, the
- <code>a</code> library won't even refer to <code>b</code>.
- </para>
- </note>
-
- </section>
+ This specifies that library <code>a</code> uses library <code>b</code>,
+ and causes all executables that link to <code>a</code> also link to
+ <code>b</code>. In this case, even for shared linking, the
+ <code>a</code> library will not even refer to <code>b</code>.
+ </para>
+ </note>
- <section id="bbv2.tasks.alias">
- <title>Alias</title>
+ <para>
+ One feature of Boost.Build that is very important for libraries is usage
+ requirements. <!-- Rephrase that. But then, it is much too late for an
+ introduction of usage requirements - you have already discussed them many
+ times. Also, add references to the sections describing requirements and
+ usage-requirements here. --> For example, imagine that you want you build
+ a <code>helpers</code> library and its interface is described in its
+ <code>helpers.hpp</code> header file located in the same directory as the
+ <code>helpers.cpp</code> source file. Then you could add the following to
+ the Jamfile located in that same directory:
+<programlisting>
+lib helpers : helpers.cpp : : : <include>. ;
+</programlisting>
+ which would automatically add the directory where the target has been
+ defined (and where the library's header file is located) to the compiler's
+ include path for all targets using the <code>helpers</code> library. This
+ feature greatly simplifies Jamfiles.
+ </para>
+ </section>
- <para>
- The <functionname>alias</functionname> rule gives an alternative name to
- a group of targets. For example, to give the name
- <filename>core</filename> to a group of three other targets with the
- following code:
- <programlisting>
-alias core : im reader writer ;</programlisting>
- Using <filename>core</filename> on the command line, or in the source
- list of any other target is the same as explicitly using
- <filename>im</filename>, <filename>reader</filename>, and
- <filename>writer</filename>, but it is just more convenient.
- </para>
+ <section id="bbv2.tasks.alias">
+ <title>Alias</title>
+ <para>
+ The <functionname>alias</functionname> rule gives an alternative name to a
+ group of targets. For example, to give the name <filename>core</filename>
+ to a group of three other targets with the following code:
+<programlisting>
+alias core : im reader writer ;
+</programlisting>
+ Using <filename>core</filename> on the command line, or in the source list
+ of any other target is the same as explicitly using <filename>im
+ </filename>, <filename>reader</filename>, and <filename>writer</filename>.
+ </para>
- <para>
- Another use of the <code>alias</code> rule is to change build
- properties. For example, if you always want static linking for a
- specific C++ Boost library, you can write the following:
+ <para>
+ Another use of the <code>alias</code> rule is to change build properties.
+ For example, if you want to use link statically to the Boost Threads
+ library, you can write the following:
<programlisting>
alias threads : /boost/thread//boost_thread : <link>static ;
</programlisting>
- and use only the <code>threads</code> alias in your Jamfiles.
- </para>
+ and use only the <code>threads</code> alias in your Jamfiles.
+ </para>
- <para>
- You can also specify usage requirements for the
- <code>alias</code> target. If you write the following:
+ <para>
+ You can also specify usage requirements for the <code>alias</code> target.
+ If you write the following:
<programlisting>
alias header_only_library : : : : <include>/usr/include/header_only_library ;
</programlisting>
- then using <code>header_only_library</code> in sources will only add an
- include path. Also note that when an alias has sources, their usage
- requirements are propagated as well. For example:
+ then using <code>header_only_library</code> in sources will only add an
+ include path. Also note that when an alias has sources, their usage
+ requirements are propagated as well. For example:
<programlisting>
lib library1 : library1.cpp : : : <include>/library/include1 ;
lib library2 : library2.cpp : : : <include>/library/include2 ;
alias static_libraries : library1 library2 : <link>static ;
exe main : main.cpp static_libraries ;
</programlisting>
- will compile <filename>main.cpp</filename> with additional includes
- required for using the specified static libraries.
- </para>
-
- </section>
+ will compile <filename>main.cpp</filename> with additional includes
+ required for using the specified static libraries.
+ </para>
+ </section>
- <section id="bbv2.tasks.installing">
- <title>Installing</title>
+ <section id="bbv2.tasks.installing">
+ <title>Installing</title>
- <para>This section describes various ways to install built target
- and arbitrary files.</para>
+ <para>
+ This section describes various ways to install built target and
+ arbitrary files.
+ </para>
- <bridgehead>Basic install</bridgehead>
+ <bridgehead>Basic install</bridgehead>
- <para>For installing a built target you should use the
- <code>install</code> rule, which follows the <link
- linkend="bbv2.main-target-rule-syntax">common syntax</link>. For
- example:
+ <para>
+ For installing a built target you should use the <code>install</code>
+ rule, which follows the <link linkend="bbv2.main-target-rule-syntax">
+ common syntax</link>. For example:
<programlisting>
install dist : hello helpers ;
</programlisting>
- will cause the targets <code>hello</code> and <code>helpers</code> to
- be moved to the <filename>dist</filename> directory, relative to
- Jamfile's directory. The directory can
- be changed with the <code>location</code> property:
+ will cause the targets <code>hello</code> and <code>helpers</code> to be
+ moved to the <filename>dist</filename> directory, relative to the
+ Jamfile's directory. The directory can be changed using the
+ <code>location</code> property:
<programlisting>
install dist : hello helpers : <location>/usr/bin ;
</programlisting>
- While you can achieve the same effect by changing the target name to
- <filename>/usr/bin</filename>, using the <code>location</code>
- property is better, because it allows you to use a mnemonic target
- name.
- </para>
+ While you can achieve the same effect by changing the target name to
+ <filename>/usr/bin</filename>, using the <code>location</code> property is
+ better as it allows you to use a mnemonic target name.
+ </para>
- <para>The <code>location</code> property is especially handy when the location
- is not fixed, but depends on build variant or environment variables:
+ <para>
+ The <code>location</code> property is especially handy when the location
+ is not fixed, but depends on the build variant or environment variables:
<programlisting>
-install dist : hello helpers : <variant>release:<location>dist/release
- <variant>debug:<location>dist/debug ;
+install dist : hello helpers :
+ <variant>release:<location>dist/release
+ <variant>debug:<location>dist/debug ;
install dist2 : hello helpers : <location>$(DIST) ;
</programlisting>
- See also <link linkend="bbv2.reference.variants.propcond">conditional
- properties</link> and <link linkend="bbv2.faq.envar">environment variables</link>
- </para>
+ See also <link linkend="bbv2.reference.variants.propcond">conditional
+ properties</link> and <link linkend="bbv2.faq.envar">environment
+ variables</link>
+ </para>
- <bridgehead>Installing with all dependencies</bridgehead>
+ <bridgehead>Installing with all dependencies</bridgehead>
- <para>
- Specifying the names of all libraries to install can be boring. The
- <code>install</code> allows you to specify only the top-level executable
- targets to install, and automatically install all dependencies:
+ <para>
+ Specifying the names of all libraries to install can be boring. The
+ <code>install</code> allows you to specify only the top-level executable
+ targets to install, and automatically install all dependencies:
<programlisting>
install dist : hello
: <install-dependencies>on <install-type>EXE
<install-type>LIB
;
</programlisting>
- will find all targets that <code>hello</code> depends on, and install
- all of those which are either executables or libraries. More
- specifically, for each target, other targets that were specified as
- sources or as dependency properties, will be recursively found. One
- exception is that targets referred with the <link
- linkend="bbv2.builtin.features.use"><code>use</code></link> feature
- are not considered, because that feature is typically used to refer to
- header-only libraries.
- If the set of target types is specified, only targets of that type
- will be installed, otherwise, all found target will be installed.
- </para>
+ will find all targets that <code>hello</code> depends on, and install all
+ of those which are either executables or libraries. More specifically, for
+ each target, other targets that were specified as sources or as dependency
+ properties, will be recursively found. One exception is that targets
+ referred with the <link linkend="bbv2.builtin.features.use">
+ <code>use</code></link> feature are not considered, as that feature is
+ typically used to refer to header-only libraries. If the set of target
+ types is specified, only targets of that type will be installed,
+ otherwise, all found target will be installed.
+ </para>
- <bridgehead>Preserving Directory Hierarchy</bridgehead>
+ <bridgehead>Preserving Directory Hierarchy</bridgehead>
- <indexterm><primary>install-source-root</primary></indexterm>
- <para>By default, the <code>install</code> rules will stip paths from
- it's sources. So, if sources include <filename>a/b/c.hpp</filename>,
- the <filename>a/b</filename> part will be ignored. To make the
- <code>install</code> rule preserve the directory hierarchy you need
- to use the <code>install-source-root</code> feature to specify the
- root of the hierarchy you are installing. Relative paths from that
- root will be preserved. For example, if you write:
+ <indexterm><primary>install-source-root</primary></indexterm>
+ <para>
+ By default, the <code>install</code> rules will strip paths from its
+ sources. So, if sources include <filename>a/b/c.hpp</filename>, the
+ <filename>a/b</filename> part will be ignored. To make the
+ <code>install</code> rule preserve the directory hierarchy you need to
+ use the <code>install-source-root</code> feature to specify the root of
+ the hierarchy you are installing. Relative paths from that root will be
+ preserved. For example, if you write:
<programlisting>
install headers
: a/b/c.h
: <location>/tmp <install-source-root>a
;
</programlisting>
-
the a file named <filename>/tmp/b/c.h</filename> will be created.
- </para>
+ </para>
+
+ <para>
+ The <link linkend="bbv2.reference.glob-tree">glob-tree</link> rule can be
+ used to find all files below a given directory, making it easy to install
+ an entire directory tree.
+ </para>
+
+ <bridgehead>Installing into Several Directories</bridgehead>
- <para>The <link linkend="bbv2.reference.glob-tree">glob-tree</link> rule
- can be used to find all files below a given directory, making
- it easy to install entire directory tree.</para>
-
- <bridgehead>Installing into Several Directories</bridgehead>
-
- <para>The <link linkend="bbv2.tasks.alias"><code>alias</code></link>
- rule can be used when targets must be installed into several
- directories:
+ <para>
+ The <link linkend="bbv2.tasks.alias"><code>alias</code></link> rule can be
+ used when targets need to be installed into several directories:
<programlisting>
alias install : install-bin install-lib ;
install install-bin : applications : /usr/bin ;
@@ -340,178 +351,180 @@
<para>
Because the <code>install</code> rule just copies targets, most free
- features <footnote><para>see the definition of "free" in
- <xref linkend="bbv2.reference.features.attributes"/>.</para></footnote>
- have no effect when used in requirements of the <code>install</code> rule.
- The only two which matter are <link
- linkend="bbv2.builtin.features.dependency"><varname>dependency</varname>
- </link> and, on Unix, <link linkend="bbv2.reference.features.dll-path">
- <varname>dll-path</varname></link>.
+ features <footnote><para>see the definition of "free" in <xref
+ linkend="bbv2.reference.features.attributes"/>.</para></footnote> have no
+ effect when used in requirements of the <code>install</code> rule. The
+ only two that matter are <link linkend="bbv2.builtin.features.dependency">
+ <varname>dependency</varname></link> and, on Unix, <link
+ linkend="bbv2.reference.features.dll-path"><varname>dll-path</varname>
+ </link>.
</para>
<note>
<para>
- (Unix specific). On Unix, executables built with Boost.Build typically
- contain the list of paths to all used dynamic libraries. For installing,
+ (Unix specific) On Unix, executables built using Boost.Build typically
+ contain the list of paths to all used shared 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 <varname>dll-path</varname> feature.
+ executables using the <varname>dll-path</varname> feature.
</para>
</note>
+ </section>
- </section>
-
- <section id="bbv2.builtins.testing">
-
- <title>Testing</title>
+ <section id="bbv2.builtins.testing">
+ <title>Testing</title>
- <para>
- Boost.Build has convenient support for running unit tests. The simplest
- way is the <code>unit-test</code> rule, which follows the <link
- linkend="bbv2.main-target-rule-syntax">common syntax</link>. For
- example:
+ <para>
+ Boost.Build has convenient support for running unit tests. The simplest
+ way is the <code>unit-test</code> rule, which follows the <link
+ linkend="bbv2.main-target-rule-syntax">common syntax</link>. For example:
<programlisting>
unit-test helpers_test : helpers_test.cpp helpers ;
</programlisting>
- </para>
+ </para>
- <para>The <functionname>unit-test</functionname> rule behaves like the
- <functionname>exe</functionname> rule, but after the executable is created it is
- run. If the executable returns an error code, the build system will also
- return an error and will try running the executable on the next
- invocation until it runs successfully. This behaviour ensures that you
- can't miss a unit test failure.
- </para>
+ <para>
+ The <functionname>unit-test</functionname> rule behaves like the
+ <functionname>exe</functionname> rule, but after the executable is created
+ it is also run. If the executable returns an error code, the build system
+ will also return an error and will try running the executable on the next
+ invocation until it runs successfully. This behaviour ensures that you can
+ not miss a unit test failure.
+ </para>
- <para>By default, the executable is run directly. Sometimes, it's
- desirable to run the executable using some helper command. You should use the
- <literal>testing.launcher</literal> property to specify the name of the
- helper command. For example, if you write:
- </para>
+ <para>
+ By default, the executable is run directly. Sometimes, it is desirable to
+ run the executable using some helper command. You should use the <literal>
+ testing.launcher</literal> property to specify the name of the helper
+ command. For example, if you write:
<programlisting>
unit-test helpers_test
: helpers_test.cpp helpers
: <emphasis role="bold"><testing.launcher>valgrind</emphasis>
;
</programlisting>
- <para>The command used to run the executable will be:</para>
+ The command used to run the executable will be:
<screen>
<emphasis role="bold">valgrind</emphasis> bin/$toolset/debug/helpers_test
</screen>
+ </para>
- <para>There are few specialized testing rules, listed below:
- <programlisting>
+ <para>
+ There are few specialized testing rules, listed below:
+<programlisting>
rule compile ( sources : requirements * : target-name ? )
rule compile-fail ( sources : requirements * : target-name ? )
rule link ( sources + : requirements * : target-name ? )
rule link-fail ( sources + : requirements * : target-name ? )
- </programlisting>
- 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 <literal>compile*</literal>
- tests try to compile the passed source. The <literal>link*</literal>
- rules try to compile and link an application from all the passed sources.
- The <literal>compile</literal> and <literal>link</literal> rules expect
- that compilation/linking succeeds. The <literal>compile-fail</literal>
- and <literal>link-fail</literal> rules, on the opposite, expect that
+</programlisting>
+ They 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
+ <literal>compile*</literal> tests try to compile the passed source. The
+ <literal>link*</literal> rules try to compile and link an application from
+ all the passed sources. The <literal>compile</literal> and <literal>link
+ </literal> rules expect that compilation/linking succeeds. The <literal>
+ compile-fail</literal> and <literal>link-fail</literal> rules expect that
the compilation/linking fails.
- </para>
+ </para>
- <para>There are two specialized rules for running applications, which
- are more powerful than the <code>unit-test</code> rule. The
- <code>run</code> rule has the following signature:
- <programlisting>
+ <para>
+ There are two specialized rules for running applications, which are more
+ powerful than the <code>unit-test</code> rule. The <code>run</code> rule
+ has the following signature:
+<programlisting>
rule run ( sources + : args * : input-files * : requirements * : target-name ?
: default-build * )
- </programlisting>
- The rule builds application from the provided sources and runs it,
- passing <varname>args</varname> and <varname>input-files</varname>
- as command-line arguments. The <varname>args</varname> parameter
- is passed verbatim and the values of the <varname>input-files</varname>
- parameter are treated as paths relative to containing Jamfile, and are
- adjusted if <command>bjam</command> is invoked from a different
- directory. The <code>run-fail</code> rule is identical to the
- <code>run</code> rule, except that it expects that the run fails.
- </para>
+</programlisting>
+ The rule builds application from the provided sources and runs it, passing
+ <varname>args</varname> and <varname>input-files</varname> as command-line
+ arguments. The <varname>args</varname> parameter is passed verbatim and
+ the values of the <varname>input-files</varname> parameter are treated as
+ paths relative to containing Jamfile, and are adjusted if <command>bjam
+ </command> is invoked from a different directory. The
+ <code>run-fail</code> rule is identical to the <code>run</code> rule,
+ except that it expects that the run fails.
+ </para>
- <para>All rules described in this section, if executed successfully,
- create a special manifest file to indicate that the test passed.
- For the <code>unit-test</code> rule the files is named
- <filename><replaceable>target-name</replaceable>.passed</filename> and
- for the other rules it is called
- <filename><replaceable>target-name</replaceable>.test</filename>.
- The <code>run*</code> rules also capture all output from the program,
- and store it in a file named
- <filename><replaceable>target-name</replaceable>.output</filename>.</para>
-
- <para>The <code>run</code> and the <code>run-fail</code> rules, if
- the test passes, automatically delete the linked executable, to
- save space. This behaviour can be suppressed by passing the
- <literal>--preserve-test-targets</literal> command line option.</para>
-
- <para>It is possible to print the list of all test targets (except for
- <code>unit-test</code>) declared in your project, by passing
- the <literal>--dump-tests</literal> command-line option. The output
- will consist of lines of the form:
- <screen>
-boost-test(<replaceable>test-type</replaceable>) <replaceable>path</replaceable> : <replaceable>sources</replaceable>
- </screen>
- </para>
+ <para>
+ All rules described in this section, if executed successfully, create a
+ special manifest file to indicate that the test passed. For the
+ <code>unit-test</code> rule the files is named <filename><replaceable>
+ target-name</replaceable>.passed</filename> and for the other rules it is
+ called <filename><replaceable>target-name</replaceable>.test</filename>.
+ The <code>run*</code> rules also capture all output from the program, and
+ store it in a file named <filename><replaceable>
+ target-name</replaceable>.output</filename>.
+ </para>
- <para>It is possible to process the list of tests, the output of
- bjam during command run, and the presense/absense of the
- <filename>*.test</filename> files created when test passes into
- human-readable status table of tests. Such processing utilities
- are not included in Boost.Build.</para>
+ <para>
+ The <code>run</code> and the <code>run-fail</code> rules, if the test
+ passes, automatically delete the linked executable, to save space. This
+ behaviour can be suppressed by passing the <literal>
+ --preserve-test-targets</literal> command line option.
+ </para>
- </section>
+ <para>
+ It is possible to print the list of all test targets (except for
+ <code>unit-test</code>) declared in your project, by passing the <literal>
+ --dump-tests</literal> command-line option. The output will consist of
+ lines of the form:
+<screen>
+boost-test(<replaceable>test-type</replaceable>) <replaceable>path</replaceable> : <replaceable>sources</replaceable>
+</screen>
+ </para>
- <section id="bbv2.builtins.raw">
+ <para>
+ It is possible to process the list of tests, the output of bjam during
+ command run, and the presense/absense of the <filename>*.test</filename>
+ files created when test passes into human-readable status table of tests.
+ Such processing utilities are not included in Boost.Build.
+ </para>
+ </section>
- <title>Custom commands</title>
+ <section id="bbv2.builtins.raw">
+ <title>Custom commands</title>
- <para>
- 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
- <xref linkend="bbv2.extender"/>. 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.
- </para>
+ <para>
+ 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 <xref linkend="bbv2.extender"/>.
+ However, if there is only a single place where the new tool is used, it
+ might be easier to just explicitly specify the commands to run.
+ </para>
- <para>
- <!-- This paragraph requires links to where the terms 'virtual target'
- & 'target' are defined. -->
- Three main target rules can be used for that. The <functionname>make
- </functionname> rule allows you to construct a single file from any
- number of source file, by running a command you specify. The
- <functionname>notfile</functionname> rule allows you to run an arbitrary
- command, without creating any files. And finaly, the <functionname>
- generate</functionname> rule allows you to describe transformation using
- Boost.Build's virtual targets. This is higher-level than file names that
- the <functionname>make</functionname> 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.
- </para>
+ <para>
+ <!-- This paragraph requires links to where the terms 'virtual target' &
+ 'target' are defined. -->
+ Three main target rules can be used for that. The <functionname>make
+ </functionname> rule allows you to construct a single file from any number
+ of source file, by running a command you specify. The <functionname>
+ notfile</functionname> rule allows you to run an arbitrary command,
+ without creating any files. And finaly, the <functionname>generate
+ </functionname> rule allows you to describe transformation using
+ Boost.Build's virtual targets. This is higher-level than file names that
+ the <functionname>make</functionname> 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.
+ </para>
- <para>
- The <functionname>make</functionname> rule is used when you want to
- create one file from a number of sources using some specific command.
- The <functionname>notfile</functionname> is used to unconditionally run
- a command.
- </para>
+ <para>
+ The <functionname>make</functionname> rule is used when you want to create
+ one file from a number of sources using some specific command. The
+ <functionname>notfile</functionname> is used to unconditionally run a
+ command.
+ </para>
- <!-- We need to specify somewhere that the user can get rules like make,
- notfile & generate defined in his Jamfiles by importing an appropriate
- Boost.Build module. Also, each of those rules should get a separate
- documentation page explicitly listing which module needs to be imported
- for them to become accessible. -->
+ <!-- We need to specify somewhere that the user can get rules like make,
+ notfile & generate defined in his Jamfiles by importing an appropriate
+ Boost.Build module. Also, each of those rules should get a separate
+ documentation page explicitly listing which module needs to be imported for
+ them to become accessible. -->
- <para>
- Suppose you want to create file <filename>file.out</filename> from file
- <filename>file.in</filename> by running command
- <command>in2out</command>. Here is how you would do this in Boost.Build:
+ <para>
+ Suppose you want to create file <filename>file.out</filename> from file
+ <filename>file.in</filename> by running command <command>
+ in2out</command>. Here is how you would do this in Boost.Build:
<programlisting>
make file.out : file.in : @in2out ;
actions in2out
@@ -519,16 +532,16 @@
in2out $(<) $(>)
}
</programlisting>
- If you run <command>bjam</command> and <filename>file.out</filename>
- does not exist, Boost.Build will run the <command>in2out</command>
- command to create that file. For more details on specifying actions, see
- <xref linkend="bbv2.advanced.jam_language.actions"/>.
- </para>
+ If you run <command>bjam</command> and <filename>file.out</filename> does
+ not exist, Boost.Build will run the <command>in2out</command> command to
+ create that file. For more details on specifying actions, see <xref
+ linkend="bbv2.advanced.jam_language.actions"/>.
+ </para>
- <para>
- 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 <functionname>notfile</functionname> rule. For example:
+ <para>
+ 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
+ <functionname>notfile</functionname> rule. For example:
<programlisting>
notfile echo_something : @echo ;
actions echo
@@ -536,56 +549,56 @@
echo "something"
}
</programlisting>
- The only difference from the <functionname>make</functionname> rule is
- that the name of the target is not considered a name of a file, so
- Boost.Build will unconditionally run the action.
- </para>
+ The only difference from the <functionname>make</functionname> rule is
+ that the name of the target is not considered a name of a file, so
+ Boost.Build will unconditionally run the action.
+ </para>
- <para>
- <!-- This paragraph requires links to where terms like 'virtual target',
- 'target', 'project-target' & 'property-set' are defined. -->
- The <functionname>generate</functionname> rule is used when you want to
- express transformations using Boost.Build's virtual targets, as opposed
- to just filenames. The <functionname>generate</functionname> rule has
- the standard main target rule signature, but you are required to specify
- the <literal>generating-rule</literal> property. The value of the
- property should be in the form
- <literal>@<replaceable>rule-name</replaceable></literal>, the named rule
- should have the following signature:
+ <para>
+ <!-- This paragraph requires links to where terms like 'virtual target',
+ 'target', 'project-target' & 'property-set' are defined. -->
+ The <functionname>generate</functionname> rule is used when you want to
+ express transformations using Boost.Build's virtual targets, as opposed to
+ just filenames. The <functionname>generate</functionname> rule has the
+ standard main target rule signature, but you are required to specify the
+ <literal>generating-rule</literal> property. The value of the property
+ should be in the form <literal>
+ @<replaceable>rule-name</replaceable></literal>, the named rule should
+ have the following signature:
<programlisting>
rule generating-rule ( project name : property-set : sources * )
</programlisting>
- and will be called with an instance of the <code>project-target</code>
- class, the name of the main target, an instance of the
- <code>property-set</code> class containing build properties, and the
- list of instances of the <code>virtual-target</code> class corresponding
- to sources. The rule must return a list of <code>virtual-target</code>
- instances. The interface of the <code>virtual-target</code> class can be
- learned by looking at the <filename>build/virtual-target.jam</filename>
- file. The <filename>generate</filename> example contained in the
- Boost.Build distribution illustrates how the <literal>generate</literal>
- rule can be used.
- </para>
-
- </section>
+ and will be called with an instance of the <code>project-target</code>
+ class, the name of the main target, an instance of the
+ <code>property-set</code> class containing build properties, and the list
+ of instances of the <code>virtual-target</code> class corresponding to
+ sources. The rule must return a list of <code>virtual-target</code>
+ instances. The interface of the <code>virtual-target</code> class can be
+ learned by looking at the <filename>build/virtual-target.jam</filename>
+ file. The <filename>generate</filename> example contained in the
+ Boost.Build distribution illustrates how the <literal>generate</literal>
+ rule can be used.
+ </para>
+ </section>
- <section id="bbv2.reference.precompiled_headers">
- <title>Precompiled Headers</title>
+ <section id="bbv2.reference.precompiled_headers">
+ <title>Precompiled Headers</title>
- <para>
- 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.
- </para>
+ <para>
+ 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.
+ </para>
- <para>
- To use precompiled headers, follow the following steps:
- </para>
+ <para>
+ To use precompiled headers, follow the following steps:
+ </para>
- <orderedlist>
- <listitem><para>
+ <orderedlist>
+ <listitem>
+ <para>
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
@@ -593,9 +606,11 @@
BOOST_BUILD_PCH_ENABLED</code>, 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.
- </para></listitem>
+ </para>
+ </listitem>
- <listitem><para>
+ <listitem>
+ <para>
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:
@@ -606,91 +621,99 @@
You can use the <functionname>c-pch</functionname> rule if you want to
use the precompiled header in C programs.
</para></listitem>
- </orderedlist>
+ </orderedlist>
- <para>
- The <filename>pch</filename> example in Boost.Build distribution can be
- used as reference.
- </para>
+ <para>
+ The <filename>pch</filename> example in Boost.Build distribution can be
+ used as reference.
+ </para>
- <para>
- Please note the following:
- </para>
+ <para>
+ Please note the following:
+ </para>
- <itemizedlist>
- <listitem><para>
+ <itemizedlist>
+ <listitem>
+ <para>
The inclusion of the precompiled header must be the first thing in a
source file, before any code or preprocessor directives.
- </para></listitem>
+ </para>
+ </listitem>
- <listitem><para>
+ <listitem>
+ <para>
The build properties used to compile the source files and the
precompiled header must be the same. Consider using project
requirements to assure this.
- </para></listitem>
+ </para>
+ </listitem>
- <listitem><para>
+ <listitem>
+ <para>
Precompiled headers must be used purely as a way to improve
compilation time, not to save the number of <code>#include</code>
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.
- </para></listitem>
+ </para>
+ </listitem>
- <listitem><para>
+ <listitem>
+ <para>
On the gcc compiler, the name of the header being precompiled must be
equal to the name of the <code>cpp-pch</code> target. This is a gcc
requirement.
- </para></listitem>
+ </para>
+ </listitem>
- <listitem><para>
+ <listitem>
+ <para>
Prior to version 4.2, the gcc compiler did not allow anonymous
namespaces in precompiled headers, which limits their utility. See the
- <ulink url="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=29085">bug
+ <ulink url="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=29085"> bug
report</ulink> for details.
- </para></listitem>
- </itemizedlist>
- </section>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
- <section id="bbv2.reference.generated_headers">
- <title>Generated headers</title>
+ <section id="bbv2.reference.generated_headers">
+ <title>Generated headers</title>
- <para>Usually, Boost.Build handles implicit dependendies completely
- automatically. For example, for C++ files, all
- <literal>#include</literal> statements are found and handled. The only
- aspect where user help might be needed is implicit dependency on
- generated files.</para>
-
- <para>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 into "parser.c"
- and "parser.h". Then, if "app.cpp" includes "parser.h", Boost.Build will
- detect this dependency. Moreover, since "parser.h" will be generated
- into a build directory, the path to that directory will automatically
- added to include path.</para>
-
- <para>Making this mechanism work across main target boundaries is
- possible, but imposes certain overhead. For that reason, if there is
- implicit dependency on files from other main targets, the
- <literal><implicit-dependency></literal> [ link ] feature must be
- used, for example:</para>
+ <para>
+ Usually, Boost.Build handles implicit dependendies completely
+ automatically. For example, for C++ files, all <literal>#include</literal>
+ statements are found and handled. The only aspect where user help might be
+ needed is implicit dependency on generated files.
+ </para>
+
+ <para>
+ 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 into "parser.c" and "parser.h".
+ Then, if "app.cpp" includes "parser.h", Boost.Build will detect this
+ dependency. Moreover, since "parser.h" will be generated into a build
+ directory, the path to that directory will automatically added to include
+ path.
+ </para>
+ <para>
+ Making this mechanism work across main target boundaries is possible, but
+ imposes certain overhead. For that reason, if there is implicit dependency
+ on files from other main targets, the <literal><implicit-dependency>
+ </literal> [ link ] feature must be used, for example:
<programlisting>
lib parser : parser.y ;
exe app : app.cpp : <implicit-dependency>parser ;
</programlisting>
-
- <para>
- The above example tells the build system that when scanning all sources
- of "app" for implicit-dependencies, it should consider targets from
- "parser" as potential dependencies.
- </para>
-</section>
-
+ The above example tells the build system that when scanning all sources of
+ "app" for implicit-dependencies, it should consider targets from "parser"
+ as potential dependencies.
+ </para>
+ </section>
</chapter>
-
<!--
Local Variables:
mode: xml
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk