boost/build
2
0
Fork 0
mirror of https://github.com/boostorg/build.git synced 2026-02-15 13:02:11 +00:00
Code Issues Projects Releases Wiki Activity

Rearrange docs a bit

Browse Source 
[SVN r35521]
This commit is contained in:
Vladimir Prus
2006-10-07 20:09:22 +00:00
parent dffc92138b
commit 618a4bfdf2
6 changed files with 917 additions and 895 deletions
Download Patch File Download Diff File Expand all files Collapse all files

857
v2/doc/src/advanced.xml
View File

@@ -3,7 +3,7 @@
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<chapter id="bbv2.advanced">
<title>User documentation</title>
<title>Overview</title>
<para>This section will provide the information necessary to create your own
projects using Boost.Build. The information provided here is relatively
@@ -73,7 +73,7 @@
</para>
<section id="bbv2.advanced.jam_language">
<title>Boost.Jam language</title>
<title>Boost.Jam Language</title>
<para>This section will describe the basics of the Boost.Jam
language&#x2014;just enough for writing Jamfiles. For more information,
@@ -536,7 +536,7 @@ bjam optimization=space
</section>
<section id="bbv2.advanced.targets">
<title>Declaring targets</title>
<title>Declaring Targets</title>
<para id="bbv2.advanced.targets.main">
A <firstterm>Main target</firstterm> is a user-defined named
@@ -769,7 +769,7 @@ rule my-rule ( properties * )
</section>
<section>
<title>Default build</title>
<title>Default Build</title>
<para>The <varname>default-build</varname> parameter
is a set of properties to be used if the build request does
@@ -785,7 +785,7 @@ exe hello : hello.cpp : : &lt;threading&gt;multi ;
</section>
<section>
<title>Additional information</title>
<title>Additional Information</title>
<para>
The ways a target is built can be so different that
@@ -826,7 +826,7 @@ exe hello : hello.cpp
explicit request, this can be expressed by the
<functionname>explicit</functionname> rule:
<programlisting>
explicit install_programs ;</programlisting>
explicit install_programs ;</programlisting>
</para>
</section>
@@ -1028,90 +1028,6 @@ project tennis
perfectly appropriate to start a user guide with that kind
of material. -->
</section>
<section id="bbv2.advanced.other-rules">
<title>Jamfile Utility Rules</title>
<para>The following table describes utility rules that can be
used in Jamfiles. Detailed information for any of these rules can
be obtained by running:
<screen>
bjam --help project.<replaceable>rulename</replaceable>
</screen>
</para>
<table>
<title/>
<tgroup cols="2">
<thead>
<row>
<entry>Rule</entry>
<entry>Semantics</entry>
</row>
</thead>
<tbody>
<row>
<entry><link linkend=
"bbv2.advanced.projects.attributes.projectrule">project</link>
</entry>
<entry>Define this project's symbolic ID or attributes.</entry>
</row>
<row>
<entry><xref linkend=
"bbv2.advanced.projects.relationships.useprojectrule">use-project</xref></entry>
<entry>Make another project known so that it can be referred to by symbolic ID.</entry>
</row>
<row>
<entry><xref linkend=
"bbv2.advanced.projects.relationships.buildprojectrule">build-project</xref></entry>
<entry>Cause another project to be built when this one is built.</entry>
</row>
<row>
<entry><xref linkend=
"bbv2.reference.buildprocess.explict">explicit</xref></entry>
<entry>State that a target should be built only by explicit
request.</entry>
</row>
<row>
<entry>glob</entry>
<entry>Translate a list of shell-style wildcards into a
corresponding list of files.</entry>
</row>
<row>
<entry>constant</entry>
<entry>Injects a variable setting into this project's
Jamfile module and those of all its subprojects.</entry>
</row>
<row>
<entry>path-constant</entry>
<entry>Injects a variable set to a path value into
this project's Jamfile module and those of all its subprojects.
If the value is a relative path it will be adjusted for
each subproject so that it refers to the same
directory.</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section id="bbv2.advanced.build_process">
<title>The Build Process</title>
@@ -1147,7 +1063,7 @@ bjam --help project.<replaceable>rulename</replaceable>
</tip>
<section>
<title>Build request</title>
<title>Build Request</title>
<para>
The command line specifies which targets to build and with which
@@ -1253,7 +1169,7 @@ bjam app1 lib1//lib1 gcc debug optimization=full
</para>
</section>
<section><title>Building a project</title>
<section><title>Building a Project</title>
<para>Often, a user builds a complete project, not just one main
target. In fact, invoking <command>bjam</command> without
@@ -1287,763 +1203,6 @@ explicit hello_test ;
</section>
</section>
<section id="bbv2.advanced.builtins.targets">
<title>Builtin target types</title>
<para>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 <xref
linkend="bbv2.main-target-rule-syntax"/>.
</para>
<section>
<title>Programs</title>
<indexterm><primary>Builtin
rules</primary><secondary>exe</secondary></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
: &lt;threading&gt;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>
<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, for example using the <link linkend="bbv2.builtins.stage">
stage</link> rule.
</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>
<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:
<programlisting>
lib helpers : helpers.cpp : &lt;include&gt;boost : : &lt;include&gt;. ;
</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
&lt;link&gt; 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>
<para>
The syntax for these case is given below:
<programlisting>
lib z : : &lt;name&gt;z &lt;search&gt;/home/ghost ;
lib compress : : &lt;file&gt;/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>
<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:
<programlisting>
lib a : : &lt;variant&gt;release &lt;file&gt;/pool/release/a.so ;
lib a : : &lt;variant&gt;debug &lt;file&gt;/pool/debug/a.so ;
lib b : : &lt;variant&gt;release &lt;file&gt;/pool/release/b.so ;
lib b : : &lt;variant&gt;debug &lt;file&gt;/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>
<para>
For convenience, the following syntax is allowed:
<programlisting>
lib z ;
lib gui db aux ;
</programlisting>
and is does exactly the same as:
<programlisting>
lib z : : &lt;name&gt;z ;
lib gui : : &lt;name&gt;gui ;
lib db : : &lt;name&gt;db ;
lib aux : : &lt;name&gt;aux ;
</programlisting>
</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 won't work. For example:
<programlisting>
lib z ;
lib png : z : &lt;name&gt;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>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 : : : &lt;include&gt;. ;
</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. -->
</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:
<programlisting>
lib b : a.cpp ;
lib a : a.cpp : &lt;use&gt;b : : &lt;library&gt;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>
<section id="bbv2.builtins.alias">
<title>Alias</title>
<para>
The <functionname>alias</functionname> rule gives 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>
<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:
<programlisting>
alias threads : /boost/thread//boost_thread : &lt;link&gt;static ;
</programlisting>
and use only the <code>threads</code> alias in your Jamfiles.
<!-- changed name for clarity -->
</para>
<para>
You can also specify usage requirements for the
<code>alias</code> target. If you write the following:
<programlisting>
alias header_only_library : : : : &lt;include&gt;/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 there are some sources, their usage
requirements are propagated, too. For example:
<programlisting>
lib lib : lib.cpp : : : &lt;include&gt;. ;
alias lib_alias ; <!-- This line can't possibly be correct!?? -->
exe main : main.cpp lib_alias ;
</programlisting>
will compile <filename>main.cpp</filename> with the additional include.
</para>
</section>
<section id="bbv2.builtins.stage">
<title>Installing</title>
<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:
<programlisting>
install dist : hello helpers : &lt;location&gt;/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>
<para>The <code>location</code> property is especially handy when the location
is not fixed, but depends on build variant or environment variables:
<programlisting>
install dist : hello helpers : &lt;variant&gt;release:&lt;location&gt;dist/release
&lt;variant&gt;debug:&lt;location&gt;dist/debug ;
install dist2 : hello helpers : &lt;location&gt;$(DIST) ;
</programlisting>
See also <link linkend="bbv2.reference.variants.propcond">conditional
properties</link> and <link linkend="bbv2.faq.envar">environment variables</link>
</para>
<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
: &lt;install-dependencies&gt;on &lt;install-type&gt;EXE
&lt;install-type&gt;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>
<para>The <link linkend="bbv2.builtins.alias"><code>alias</code></link>
rule can be used when targets must be installed into several
directories:
<programlisting>
alias install : install-bin install-lib ;
install install-bin : applications : /usr/bin ;
install install-lib : helper : /usr/lib ;
</programlisting>
</para>
<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.builtin.feature.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, 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.
</para>
</note>
</section>
<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:
<programlisting>
unit-test helpers_test : helpers_test.cpp helpers ;
</programlisting>
</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>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>
<programlisting>
unit-test helpers_test
: helpers_test.cpp helpers
: <emphasis role="bold">&lt;testing.launcher&gt;valgrind</emphasis>
;
</programlisting>
<para>The command used to run the executable will be:</para>
<screen>
<emphasis role="bold">valgrind</emphasis> bin/$toolset/debug/helpers_test
</screen>
<para>There are rules for more elaborate testing: <code>compile</code>,
<code>compile-fail</code>, <code>run</code> and
<code>run-fail</code>. They are more suitable for automated testing, and
are not covered here.
</para>
</section>
<section id="bbv2.builtins.raw">
<title>Raw commands: 'make' and 'notfile'</title>
<para>Sometimes, the builtin target types are not enough, and you
want Boost.Build to just run specific commands. There are two main
target rules that make it possible: <functionname>make</functionname>
and <functionname>notfile</functionname>.
</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>
Suppose you want to create file <filename>file.out</filename> from
file <filename>file.in</filename> by running command
<command>in2out</command>. Here's how you'd do this in Boost.Build:
<programlisting>
actions in2out
{
in2out $(&lt;) $(&gt;)
}
make file.out : file.in : @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>
<note>
<para>
The <functionname>make</functionname> rule is useful to express custom
transformation that are used just once or twice in your project. For
transformations that are used often, you are advised to declare
new generator, as described in <xref linkend="bbv2.extending.tools"/>.
</para>
</note>
<para>
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
the <functionname>notfile</functionname> rule. For example:
<programlisting>
notfile echo_something : @echo ;
actions echo
{
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>
</section>
</section>
<section id="bbv2.advanced.builtins.features">
<title>Builtin features</title>
<variablelist>
<varlistentry><term><literal>variant</literal></term>
<listitem>
<para>
A feature that combines several low-level features, making
it easy to request common build configurations.
</para>
<para><emphasis role="bold">Allowed values:</emphasis> <literal>debug</literal>, <literal>release</literal>,
<literal>profile</literal>.</para>
<para>The value <literal>debug</literal> expands to</para>
<programlisting>
&lt;optimization&gt;off &lt;debug-symbols&gt;on &lt;inlining&gt;off &lt;runtime-debugging&gt;on
</programlisting>
<para>The value <literal>release</literal> expands to</para>
<programlisting>
&lt;optimization&gt;speed &lt;debug-symbols&gt;off &lt;inlining&gt;full &lt;runtime-debugging&gt;off
</programlisting>
<para>The value <literal>profile</literal> expands to the same as
<literal>release</literal>, plus:</para>
<programlisting>
&lt;profiling&gt;on &lt;debug-symbols&gt;on
</programlisting>
<para>User can define his own build variants using the <code>variant</code> rule from the <code>common</code>
module.</para>
<para><emphasis role="bold">Notee:</emphasis> Runtime
debugging is on in debug builds to suit the expectations of
people used to various IDEs.
<!-- Define "runtime debugging." Why will those people expect it to be on in debug builds? -->
</para>
</listitem></varlistentry>
<varlistentry id="bbv2.advanced.builtins.features.link">
<term><literal>link</literal></term>
<listitem>
<simpara>
A feature that controls how libraries are built.
</simpara>
<para><emphasis role="bold">Allowed values:</emphasis> <literal>shared</literal>,
<literal>static</literal></para>
</listitem></varlistentry>
<varlistentry><term><literal>source</literal></term>
<listitem>
<simpara>
The <code>&lt;source&gt;X</code> feature has the same effect on
building a target as putting X in the list of sources.
It's useful when you want to add
the same source to all targets in the project
(you can put &lt;source&gt; in requirements) or to conditionally
include a source (using conditional requirements, see <xref linkend="bbv2.tutorial.conditions"/>)
See also the <code>&lt;library&gt;</code> feature.
</simpara>
</listitem>
</varlistentry>
<varlistentry><term><literal>library</literal></term>
<listitem>
<simpara>
This feature is almost equivalent to the <code>&lt;source&gt;</code> feature,
except that it takes effect only for linking. When you want to
link all targets in a Jamfile to certain library, the
<code>&lt;library&gt;</code> feature is preferred over
<code>&lt;source&gt;X</code> -- the latter will add the library to
all targets, even those that have nothing to do with libraries.
</simpara>
</listitem>
</varlistentry>
<varlistentry><term><anchor id="bbv2.builtin.features.dependency"/>
<literal>dependency</literal></term>
<listitem>
<simpara>
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. For example, in
application with plugins, the plugins are not used when linking
the application,
application might have dependency on its plugins, even though
, and
adds its usage requirements to the build properties
of the target being declared.
The primary use case is when you want
the usage requirements (such as <code>#include</code> paths) of some
library to be applied, but don't want to link to it.
<!-- It's hard to picture why anyone would want to do
that. Please flesh out this motivation -->
</simpara>
</listitem>
</varlistentry>
<varlistentry><term><anchor id="bbv2.builtin.features.use"/>
<literal>use</literal></term>
<listitem>
<simpara>
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
<!-- Do you really mean "to the requirements?" -->
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 <code>#include</code> paths) of some
library to be applied, but don't want to link to it.
<!-- It's hard to picture why anyone would want to do
that. Please flesh out this motivation -->
</simpara>
</listitem>
</varlistentry>
<varlistentry><term><anchor id="bbv2.builtin.features.dll-path"/>
<literal>dll-path</literal></term>
<listitem>
<simpara>
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. Plase see <xref linkend="bbv2.faq.dll-path"/>
in <xref linkend="bbv2.faq"/> for details.
</simpara>
</listitem></varlistentry>
<varlistentry><term><literal>hardcode-dll-paths</literal></term>
<listitem>
<simpara>
Controls automatic generation of dll-path properties.
</simpara>
<para><emphasis role="bold">Allowed values:</emphasis>
<literal>true</literal>, <literal>false</literal>. This property
is specific to Unix systems. If an executable is built with
<code>&lt;hardcode-dll-paths&gt;true</code>, 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
<!-- you need an antecedent. This _what_? -->
is very convenient during
development. Plase see the <link
linkend="bbv2.faq.dll-path">FAQ entry</link> for details.
Note that on Mac OSX, the paths are unconditionally hardcoded by
the linker, and it's not possible to disable that behaviour.
</para>
</listitem></varlistentry>
<varlistentry>
<term><literal>cflags</literal></term>
<term><literal>cxxflags</literal></term>
<term><literal>linkflags</literal></term>
<listitem>
<simpara>
The value of those features is passed without modification to the
corresponding tools. For <code>cflags</code> that's both the C and C++
compilers, for <code>cxxflags</code> that's the C++ compiler and for
<code>linkflags</code> that's the linker. The features are handy when
you're trying to do something special that cannot be achieved by
higher-level feature in Boost.Build.
</simpara>
</listitem>
</varlistentry>
<varlistentry><term><literal>warnings</literal></term>
<listitem>
<simpara>
The <code>&lt;warnings&gt;</code> feature controls the warning level of compilers. It has the following values:
<itemizedlist>
<listitem><para><code>off</code> - disables all warnings.</para></listitem>
<listitem><para><code>on</code> - enables default warning level for the tool.</para></listitem>
<listitem><para><code>all</code> - enables all warnings.</para></listitem>
</itemizedlist>
Default value is <code>all</code>.
</simpara>
</listitem>
</varlistentry>
<varlistentry><term><literal>warnings-as-errors</literal></term>
<listitem>
<simpara>
The <code>&lt;warnings-as-errors&gt;</code> makes it possible to treat warnings as errors and abort
compilation on a warning. The value <code>on</code> enables this behaviour. The default value is
<code>off</code>.
</simpara>
</listitem>
</varlistentry>
<varlistentry><term><literal>build</literal></term>
<listitem>
<para><emphasis role="bold">Allowed values:</emphasis> <literal>no</literal></para>
<para>
The <code>build</code> feature is used to conditionally disable build of a target. If <code>&lt;build&gt;no</code>
is in properties when building a target, build of that target is skipped. Combined with conditional requirements this
allows to skip building some target in configurations where the build is known to fail.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section id="bbv2.advanced.differences_to_v1">
<title>Differences to Boost.Build V1</title>
<!-- "Differences to" is the British English usage. American
English is "differences from." You can use the former but be
sure you know what you're doing -->
<para>While Boost.Build V2 is based on the same ideas as Boost.Build V1,
some of the syntax was changed, and some new important features were
added. This chapter describes most of the changes.</para>
<section id="bbv2.advanced.differences_to_v1.configuration">
<title>Configuration</title>
<para>In V1, toolsets were configured by environment variables. If you
wanted to use two versions of the same toolset, you had to create a new
toolset module that would set the variables and then invoke the base
toolset. In V2, toolsets are configured by the
<functionname>using</functionname>, and you can easily configure several
versions of a toolset. See <xref
linkend="bbv2.advanced.configuration"/> for details.
</para>
</section>
<section id="bbv2.advanced.differences_to_v1.jamfiles">
<title>Writing Jamfiles</title>
<para>Probably one of the most important differences in V2 Jamfiles is
the use of project requirements. In V1, if several targets had the same
requirements (for example, a common <code>#include</code> path), it was necessary to
manually write the requirements or use a helper rule or template target. In V2, the
common properties can be specified with the <code>requirements</code> project
attribute, as documented in <xref linkend="bbv2.advanced.projects"/>.
</para>
<para><link linkend="bbv2.tutorial.libs">Usage requirements</link>
also help to simplify Jamfiles.
<!-- Simplify, simplify, simplify! You could go through the
entire document several times and make changes like that
one -->
If a library requires
all clients to use specific <code>#include</code> paths or macros when compiling
code that depends on the library, that information can be cleanly
represented.</para>
<para>The difference between <code>lib</code> and <code>dll</code> targets in V1 is completely
eliminated in V2. There's only one library target type, <code>lib</code>, which can create
either static or shared libraries depending on the value of the
<link linkend="bbv2.advanced.builtins.features.link"><varname>&lt;link&gt;</varname>
feature</link>. If your target should be only built in one way<!--"variant" has a different meaning here-->, you
can add <code>&lt;link&gt;shared</code> or <code>&lt;link&gt;static</code> to its requirements.
</para>
<para>The syntax for referring to other targets was changed a bit. While
in V1 one would use:
<programlisting>
exe a : a.cpp &lt;lib&gt;../foo/bar ;
</programlisting>
the V2 syntax is:
<programlisting>
exe a : a.cpp ../foo//bar ;
</programlisting>
Note that you don't need to specify the type of other target, but the
last element should be separated from the others by a double slash to indicate that
you're referring to target <filename>bar</filename> in project <filename>../foo</filename>, and not to
project <filename>../foo/bar</filename>.
</para>
</section>
<section id="bbv2.advanced.differences_to_v1.build_process">
<title>Build process</title>
<para>The command line syntax in V2 is completely different. For example
<programlisting>
bjam -sTOOLS=msvc -sBUILD=release some_target
</programlisting>
now becomes:
<programlisting>
bjam toolset=msvc variant=release some_target
</programlisting>
or, using implicit features, just:
<programlisting>
bjam msvc release some_target
</programlisting>
See <link linkend="bbv2.reference.commandline">the reference</link> for a
complete description of the syntax.
</para>
</section>
</section>
</chapter>

117
v2/doc/src/reference.xml
View File

@@ -228,49 +228,90 @@ target1 debug gcc/runtime-link=dynamic,static
</section>
<section id="bbv2.reference.jamfiles">
<title>Writing Jamfiles</title>
<section id="bbv2.advanced.other-rules">
<title>Jamfile Utility Rules</title>
<para>This section describes specific information about writing Jamfiles.</para>
<section id="bbv2.reference.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's implicit dependency on files from other main targets, the
<literal>&lt;implicit-dependency&gt;</literal> [ link ] feature must
be used, for example:</para>
<programlisting>
lib parser : parser.y ;
exe app : app.cpp : &lt;implicit-dependency&gt;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>The following table describes utility rules that can be
used in Jamfiles. Detailed information for any of these rules can
be obtained by running:
<screen>
bjam --help project.<replaceable>rulename</replaceable>
</screen>
</para>
<table>
<title/>
<tgroup cols="2">
<thead>
<row>
<entry>Rule</entry>
<entry>Semantics</entry>
</row>
</thead>
<tbody>
<row>
<entry><link linkend=
"bbv2.advanced.projects.attributes.projectrule">project</link>
</entry>
<entry>Define this project's symbolic ID or attributes.</entry>
</row>
<row>
<entry><xref linkend=
"bbv2.advanced.projects.relationships.useprojectrule">use-project</xref></entry>
<entry>Make another project known so that it can be referred to by symbolic ID.</entry>
</row>
<row>
<entry><xref linkend=
"bbv2.advanced.projects.relationships.buildprojectrule">build-project</xref></entry>
<entry>Cause another project to be built when this one is built.</entry>
</row>
<row>
<entry><xref linkend=
"bbv2.reference.buildprocess.explict">explicit</xref></entry>
<entry>State that a target should be built only by explicit
request.</entry>
</row>
<row>
<entry>glob</entry>
<entry>Translate a list of shell-style wildcards into a
corresponding list of files.</entry>
</row>
<row>
<entry>constant</entry>
<entry>Injects a variable setting into this project's
Jamfile module and those of all its subprojects.</entry>
</row>
<row>
<entry>path-constant</entry>
<entry>Injects a variable set to a path value into
this project's Jamfile module and those of all its subprojects.
If the value is a relative path it will be adjusted for
each subproject so that it refers to the same
directory.</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</section>
<section id="bbv2.reference.buildprocess">
<title>Build process</title>

15
v2/doc/src/standalone.xml
View File

@@ -1,27 +1,30 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE part PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
<!DOCTYPE book PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<part xmlns:xi="http://www.w3.org/2001/XInclude"
<book xmlns:xi="http://www.w3.org/2001/XInclude"
id="bbv2" last-revision="$Date$">
<title>Boost.Build v2 User Manual</title>
<title>Boost.Build V2 User Manual</title>
<!-- Chapters -->
<xi:include href="howto.xml"/>
<xi:include href="install.xml"/>
<xi:include href="tutorial.xml"/>
<xi:include href="advanced.xml"/>
<xi:include href="tasks.xml"/>
<xi:include href="extending.xml"/>
<xi:include href="reference.xml"/>
<xi:include href="faq.xml"/>
<!-- Appendicies -->
<xi:include href="architecture.xml"/>
<!-- <xi:include href="architecture.xml"/> -->
<appendix id="bbv2.jam">
<title>Boost.Jam documentation</title>
<title>Boost.Jam Documentation</title>
<xi:include href="jam_docs.xml" parse="xml"
xpointer="xpointer(id('jam.intro')|id('jam.intro')/following-sibling::*)"/>
</appendix>
</part>
<xi:include href="v1_vs_v2.xml"/>
</book>

710
v2/doc/src/tasks.xml Normal file
View File

@@ -0,0 +1,710 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<chapter id="bbv2.tasks">
<title>Common tasks</title>
<para>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 <xref
linkend="bbv2.main-target-rule-syntax"/>.
</para>
<section>
<title>Programs</title>
<indexterm><primary>Builtin
rules</primary><secondary>exe</secondary></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
: &lt;threading&gt;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>
<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, for example using the <link linkend="bbv2.builtins.stage">
stage</link> rule.
</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>
<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:
<programlisting>
lib helpers : helpers.cpp : &lt;include&gt;boost : : &lt;include&gt;. ;
</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
&lt;link&gt; 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>
<para>
The syntax for these case is given below:
<programlisting>
lib z : : &lt;name&gt;z &lt;search&gt;/home/ghost ;
lib compress : : &lt;file&gt;/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>
<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:
<programlisting>
lib a : : &lt;variant&gt;release &lt;file&gt;/pool/release/a.so ;
lib a : : &lt;variant&gt;debug &lt;file&gt;/pool/debug/a.so ;
lib b : : &lt;variant&gt;release &lt;file&gt;/pool/release/b.so ;
lib b : : &lt;variant&gt;debug &lt;file&gt;/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>
<para>
For convenience, the following syntax is allowed:
<programlisting>
lib z ;
lib gui db aux ;
</programlisting>
and is does exactly the same as:
<programlisting>
lib z : : &lt;name&gt;z ;
lib gui : : &lt;name&gt;gui ;
lib db : : &lt;name&gt;db ;
lib aux : : &lt;name&gt;aux ;
</programlisting>
</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 won't work. For example:
<programlisting>
lib z ;
lib png : z : &lt;name&gt;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>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 : : : &lt;include&gt;. ;
</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. -->
</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:
<programlisting>
lib b : a.cpp ;
lib a : a.cpp : &lt;use&gt;b : : &lt;library&gt;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>
<section id="bbv2.builtins.alias">
<title>Alias</title>
<para>
The <functionname>alias</functionname> rule gives 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>
<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:
<programlisting>
alias threads : /boost/thread//boost_thread : &lt;link&gt;static ;
</programlisting>
and use only the <code>threads</code> alias in your Jamfiles.
<!-- changed name for clarity -->
</para>
<para>
You can also specify usage requirements for the
<code>alias</code> target. If you write the following:
<programlisting>
alias header_only_library : : : : &lt;include&gt;/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 there are some sources, their usage
requirements are propagated, too. For example:
<programlisting>
lib lib : lib.cpp : : : &lt;include&gt;. ;
alias lib_alias ; <!-- This line can't possibly be correct!?? -->
exe main : main.cpp lib_alias ;
</programlisting>
will compile <filename>main.cpp</filename> with the additional include.
</para>
</section>
<section id="bbv2.builtins.stage">
<title>Installing</title>
<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:
<programlisting>
install dist : hello helpers : &lt;location&gt;/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>
<para>The <code>location</code> property is especially handy when the location
is not fixed, but depends on build variant or environment variables:
<programlisting>
install dist : hello helpers : &lt;variant&gt;release:&lt;location&gt;dist/release
&lt;variant&gt;debug:&lt;location&gt;dist/debug ;
install dist2 : hello helpers : &lt;location&gt;$(DIST) ;
</programlisting>
See also <link linkend="bbv2.reference.variants.propcond">conditional
properties</link> and <link linkend="bbv2.faq.envar">environment variables</link>
</para>
<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
: &lt;install-dependencies&gt;on &lt;install-type&gt;EXE
&lt;install-type&gt;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>
<para>The <link linkend="bbv2.builtins.alias"><code>alias</code></link>
rule can be used when targets must be installed into several
directories:
<programlisting>
alias install : install-bin install-lib ;
install install-bin : applications : /usr/bin ;
install install-lib : helper : /usr/lib ;
</programlisting>
</para>
<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.builtin.feature.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, 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.
</para>
</note>
</section>
<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:
<programlisting>
unit-test helpers_test : helpers_test.cpp helpers ;
</programlisting>
</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>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>
<programlisting>
unit-test helpers_test
: helpers_test.cpp helpers
: <emphasis role="bold">&lt;testing.launcher&gt;valgrind</emphasis>
;
</programlisting>
<para>The command used to run the executable will be:</para>
<screen>
<emphasis role="bold">valgrind</emphasis> bin/$toolset/debug/helpers_test
</screen>
<para>There are rules for more elaborate testing: <code>compile</code>,
<code>compile-fail</code>, <code>run</code> and
<code>run-fail</code>. They are more suitable for automated testing, and
are not covered here.
</para>
</section>
<section id="bbv2.builtins.raw">
<title>Raw commands: 'make' and 'notfile'</title>
<para>Sometimes, the builtin target types are not enough, and you
want Boost.Build to just run specific commands. There are two main
target rules that make it possible: <functionname>make</functionname>
and <functionname>notfile</functionname>.
</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>
Suppose you want to create file <filename>file.out</filename> from
file <filename>file.in</filename> by running command
<command>in2out</command>. Here's how you'd do this in Boost.Build:
<programlisting>
actions in2out
{
in2out $(&lt;) $(&gt;)
}
make file.out : file.in : @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>
<note>
<para>
The <functionname>make</functionname> rule is useful to express custom
transformation that are used just once or twice in your project. For
transformations that are used often, you are advised to declare
new generator, as described in <xref linkend="bbv2.extending.tools"/>.
</para>
</note>
<para>
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
the <functionname>notfile</functionname> rule. For example:
<programlisting>
notfile echo_something : @echo ;
actions echo
{
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>
</section>
<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's implicit dependency on files from other main targets, the
<literal>&lt;implicit-dependency&gt;</literal> [ link ] feature must
be used, for example:</para>
<programlisting>
lib parser : parser.y ;
exe app : app.cpp : &lt;implicit-dependency&gt;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>
<section id="bbv2.advanced.builtins.features">
<title>Builtin features</title>
<variablelist>
<varlistentry><term><literal>variant</literal></term>
<listitem>
<para>
A feature that combines several low-level features, making
it easy to request common build configurations.
</para>
<para><emphasis role="bold">Allowed values:</emphasis> <literal>debug</literal>, <literal>release</literal>,
<literal>profile</literal>.</para>
<para>The value <literal>debug</literal> expands to</para>
<programlisting>
&lt;optimization&gt;off &lt;debug-symbols&gt;on &lt;inlining&gt;off &lt;runtime-debugging&gt;on
</programlisting>
<para>The value <literal>release</literal> expands to</para>
<programlisting>
&lt;optimization&gt;speed &lt;debug-symbols&gt;off &lt;inlining&gt;full &lt;runtime-debugging&gt;off
</programlisting>
<para>The value <literal>profile</literal> expands to the same as
<literal>release</literal>, plus:</para>
<programlisting>
&lt;profiling&gt;on &lt;debug-symbols&gt;on
</programlisting>
<para>User can define his own build variants using the <code>variant</code> rule from the <code>common</code>
module.</para>
<para><emphasis role="bold">Notee:</emphasis> Runtime
debugging is on in debug builds to suit the expectations of
people used to various IDEs.
<!-- Define "runtime debugging." Why will those people expect it to be on in debug builds? -->
</para>
</listitem></varlistentry>
<varlistentry id="bbv2.advanced.builtins.features.link">
<term><literal>link</literal></term>
<listitem>
<simpara>
A feature that controls how libraries are built.
</simpara>
<para><emphasis role="bold">Allowed values:</emphasis> <literal>shared</literal>,
<literal>static</literal></para>
</listitem></varlistentry>
<varlistentry><term><literal>source</literal></term>
<listitem>
<simpara>
The <code>&lt;source&gt;X</code> feature has the same effect on
building a target as putting X in the list of sources.
It's useful when you want to add
the same source to all targets in the project
(you can put &lt;source&gt; in requirements) or to conditionally
include a source (using conditional requirements, see <xref linkend="bbv2.tutorial.conditions"/>)
See also the <code>&lt;library&gt;</code> feature.
</simpara>
</listitem>
</varlistentry>
<varlistentry><term><literal>library</literal></term>
<listitem>
<simpara>
This feature is almost equivalent to the <code>&lt;source&gt;</code> feature,
except that it takes effect only for linking. When you want to
link all targets in a Jamfile to certain library, the
<code>&lt;library&gt;</code> feature is preferred over
<code>&lt;source&gt;X</code> -- the latter will add the library to
all targets, even those that have nothing to do with libraries.
</simpara>
</listitem>
</varlistentry>
<varlistentry><term><anchor id="bbv2.builtin.features.dependency"/>
<literal>dependency</literal></term>
<listitem>
<simpara>
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. For example, in
application with plugins, the plugins are not used when linking
the application,
application might have dependency on its plugins, even though
, and
adds its usage requirements to the build properties
of the target being declared.
The primary use case is when you want
the usage requirements (such as <code>#include</code> paths) of some
library to be applied, but don't want to link to it.
<!-- It's hard to picture why anyone would want to do
that. Please flesh out this motivation -->
</simpara>
</listitem>
</varlistentry>
<varlistentry><term><anchor id="bbv2.builtin.features.use"/>
<literal>use</literal></term>
<listitem>
<simpara>
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
<!-- Do you really mean "to the requirements?" -->
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 <code>#include</code> paths) of some
library to be applied, but don't want to link to it.
<!-- It's hard to picture why anyone would want to do
that. Please flesh out this motivation -->
</simpara>
</listitem>
</varlistentry>
<varlistentry><term><anchor id="bbv2.builtin.features.dll-path"/>
<literal>dll-path</literal></term>
<listitem>
<simpara>
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. Plase see <xref linkend="bbv2.faq.dll-path"/>
in <xref linkend="bbv2.faq"/> for details.
</simpara>
</listitem></varlistentry>
<varlistentry><term><literal>hardcode-dll-paths</literal></term>
<listitem>
<simpara>
Controls automatic generation of dll-path properties.
</simpara>
<para><emphasis role="bold">Allowed values:</emphasis>
<literal>true</literal>, <literal>false</literal>. This property
is specific to Unix systems. If an executable is built with
<code>&lt;hardcode-dll-paths&gt;true</code>, 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
<!-- you need an antecedent. This _what_? -->
is very convenient during
development. Plase see the <link
linkend="bbv2.faq.dll-path">FAQ entry</link> for details.
Note that on Mac OSX, the paths are unconditionally hardcoded by
the linker, and it's not possible to disable that behaviour.
</para>
</listitem></varlistentry>
<varlistentry>
<term><literal>cflags</literal></term>
<term><literal>cxxflags</literal></term>
<term><literal>linkflags</literal></term>
<listitem>
<simpara>
The value of those features is passed without modification to the
corresponding tools. For <code>cflags</code> that's both the C and C++
compilers, for <code>cxxflags</code> that's the C++ compiler and for
<code>linkflags</code> that's the linker. The features are handy when
you're trying to do something special that cannot be achieved by
higher-level feature in Boost.Build.
</simpara>
</listitem>
</varlistentry>
<varlistentry><term><literal>warnings</literal></term>
<listitem>
<simpara>
The <code>&lt;warnings&gt;</code> feature controls the warning level of compilers. It has the following values:
<itemizedlist>
<listitem><para><code>off</code> - disables all warnings.</para></listitem>
<listitem><para><code>on</code> - enables default warning level for the tool.</para></listitem>
<listitem><para><code>all</code> - enables all warnings.</para></listitem>
</itemizedlist>
Default value is <code>all</code>.
</simpara>
</listitem>
</varlistentry>
<varlistentry><term><literal>warnings-as-errors</literal></term>
<listitem>
<simpara>
The <code>&lt;warnings-as-errors&gt;</code> makes it possible to treat warnings as errors and abort
compilation on a warning. The value <code>on</code> enables this behaviour. The default value is
<code>off</code>.
</simpara>
</listitem>
</varlistentry>
<varlistentry><term><literal>build</literal></term>
<listitem>
<para><emphasis role="bold">Allowed values:</emphasis> <literal>no</literal></para>
<para>
The <code>build</code> feature is used to conditionally disable build of a target. If <code>&lt;build&gt;no</code>
is in properties when building a target, build of that target is skipped. Combined with conditional requirements this
allows to skip building some target in configurations where the build is known to fail.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</chapter>
<!--
Local Variables:
mode: xml
sgml-indent-data: t
sgml-parent-document: ("userman.xml" "chapter")
sgml-set-face: t
End:
-->

6
v2/doc/src/userman.xml
View File

@@ -5,18 +5,20 @@
<part xmlns:xi="http://www.w3.org/2001/XInclude"
id="bbv2" last-revision="$Date$">
<title>Boost.Build v2 User Manual</title>
<title>Boost.Build V2 User Manual</title>
<!-- Chapters -->
<xi:include href="howto.xml"/>
<xi:include href="install.xml"/>
<xi:include href="tutorial.xml"/>
<xi:include href="advanced.xml"/>
<xi:include href="tasks.xml"/>
<xi:include href="extending.xml"/>
<xi:include href="reference.xml"/>
<xi:include href="faq.xml"/>
<!-- Appendicies -->
<xi:include href="architecture.xml"/>
<!-- <xi:include href="architecture.xml"/> -->
<xi:include href="v1_vs_v2.xml"/>
</part>

107
v2/doc/src/v1_vs_v2.xml Normal file
View File

@@ -0,0 +1,107 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE appendix PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<appendix id="bbv2.vs_v1">
<title>Differences to Boost.Build V1</title>
<!-- "Differences to" is the British English usage. American
English is "differences from." You can use the former but be
sure you know what you're doing -->
<para>While Boost.Build V2 is based on the same ideas as Boost.Build V1,
some of the syntax was changed, and some new important features were
added. This chapter describes most of the changes.</para>
<section id="bbv2.advanced.differences_to_v1.configuration">
<title>Configuration</title>
<para>In V1, toolsets were configured by environment variables. If you
wanted to use two versions of the same toolset, you had to create a new
toolset module that would set the variables and then invoke the base
toolset. In V2, toolsets are configured by the
<functionname>using</functionname>, and you can easily configure several
versions of a toolset. See <xref
linkend="bbv2.advanced.configuration"/> for details.
</para>
</section>
<section id="bbv2.advanced.differences_to_v1.jamfiles">
<title>Writing Jamfiles</title>
<para>Probably one of the most important differences in V2 Jamfiles is
the use of project requirements. In V1, if several targets had the same
requirements (for example, a common <code>#include</code> path), it was necessary to
manually write the requirements or use a helper rule or template target. In V2, the
common properties can be specified with the <code>requirements</code> project
attribute, as documented in <xref linkend="bbv2.advanced.projects"/>.
</para>
<para><link linkend="bbv2.tutorial.libs">Usage requirements</link>
also help to simplify Jamfiles.
<!-- Simplify, simplify, simplify! You could go through the
entire document several times and make changes like that
one -->
If a library requires
all clients to use specific <code>#include</code> paths or macros when compiling
code that depends on the library, that information can be cleanly
represented.</para>
<para>The difference between <code>lib</code> and <code>dll</code> targets in V1 is completely
eliminated in V2. There's only one library target type, <code>lib</code>, which can create
either static or shared libraries depending on the value of the
<link linkend="bbv2.advanced.builtins.features.link"><varname>&lt;link&gt;</varname>
feature</link>. If your target should be only built in one way<!--"variant" has a different meaning here-->, you
can add <code>&lt;link&gt;shared</code> or <code>&lt;link&gt;static</code> to its requirements.
</para>
<para>The syntax for referring to other targets was changed a bit. While
in V1 one would use:
<programlisting>
exe a : a.cpp &lt;lib&gt;../foo/bar ;
</programlisting>
the V2 syntax is:
<programlisting>
exe a : a.cpp ../foo//bar ;
</programlisting>
Note that you don't need to specify the type of other target, but the
last element should be separated from the others by a double slash to indicate that
you're referring to target <filename>bar</filename> in project <filename>../foo</filename>, and not to
project <filename>../foo/bar</filename>.
</para>
</section>
<section id="bbv2.advanced.differences_to_v1.build_process">
<title>Build process</title>
<para>The command line syntax in V2 is completely different. For example
<programlisting>
bjam -sTOOLS=msvc -sBUILD=release some_target
</programlisting>
now becomes:
<programlisting>
bjam toolset=msvc variant=release some_target
</programlisting>
or, using implicit features, just:
<programlisting>
bjam msvc release some_target
</programlisting>
See <link linkend="bbv2.reference.commandline">the reference</link> for a
complete description of the syntax.
</para>
</section>
</appendix>
<!--
Local Variables:
mode: xml
sgml-indent-data: t
sgml-parent-document: ("userman.xml" "chapter")
sgml-set-face: t
End:
-->