Subject: [Boost-commit] svn:boost r55715 - trunk/tools/build/v2/doc/src
From: ghost_at_[hidden]
Date: 2009-08-22 04:42:36
Author: vladimir_prus
Date: 2009-08-22 04:42:34 EDT (Sat, 22 Aug 2009)
New Revision: 55715
URL: http://svn.boost.org/trac/boost/changeset/55715
Log:
Rename advanced.xml to overview.xml, to reduce confusion.
Added:
trunk/tools/build/v2/doc/src/overview.xml
- copied, changed from r55714, /trunk/tools/build/v2/doc/src/advanced.xml
Removed:
trunk/tools/build/v2/doc/src/advanced.xml
Deleted: trunk/tools/build/v2/doc/src/advanced.xml
==============================================================================
--- trunk/tools/build/v2/doc/src/advanced.xml 2009-08-22 04:42:34 EDT (Sat, 22 Aug 2009)
+++ (empty file)
@@ -1,1553 +0,0 @@
-<?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.advanced">
- <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
- high-level, and <xref linkend="bbv2.reference"/> as well as the on-line
- help system must be used to obtain low-level documentation (see <xref
- linkend="bbv2.reference.init.options.help"/>).
- </para>
-
- <para>
- Boost.Build actually consists of two parts - Boost.Jam, a build engine
- with its own interpreted language, and Boost.Build itself, implemented in
- Boost.Jam's language. The chain of events when you type
- <command>bjam</command> on the command line is as follows:
- <orderedlist>
- <listitem>
- <para>
- Boost.Jam tries to find Boost.Build and loads the top-level module.
- The exact process is described in <xref linkend=
- "bbv2.reference.init"/>
- </para>
- </listitem>
- <listitem>
- <para>
- The top-level module loads user-defined configuration files,
- <filename>user-config.jam</filename> and <filename>site-config.jam
- </filename>, which define available toolsets.
- </para>
- </listitem>
- <listitem>
- <para>
- The Jamfile in the current directory is read. That in turn might
- cause reading of further Jamfiles. As a result, a tree of projects
- is created, with targets inside projects.
- </para>
- </listitem>
- <listitem>
- <para>
- Finally, using the build request specified on the command line,
- Boost.Build decides which targets should be built and how. That
- information is passed back to Boost.Jam, which takes care of
- actually running the scheduled build action commands.
- </para>
- </listitem>
- </orderedlist>
- </para>
-
- <para>
- So, to be able to successfully use Boost.Build, you need to know only four
- things:
- <itemizedlist>
- <listitem>
- <para>
- <link linkend="bbv2.advanced.configuration">How to configure
- Boost.Build</link>
- </para>
- </listitem>
- <listitem>
- <para>
- <link linkend="bbv2.advanced.targets">How to declare targets in
- Jamfiles</link>
- </para>
- </listitem>
- <listitem>
- <para>
- <link linkend="bbv2.advanced.build_process">How the build process
- works</link>
- </para>
- </listitem>
- <listitem>
- <para>
- Some Basics about the Boost.Jam language. See <xref linkend=
- "bbv2.advanced.jam_language"/>.
- </para>
- </listitem>
- </itemizedlist>
- </para>
-
- <section id="bbv2.advanced.jam_language">
- <title>Boost.Jam Language</title>
-
- <para>
- This section will describe the basics of the Boost.Jam language—
- just enough for writing Jamfiles. For more information, please see the
- <link linkend="bbv2.jam">Boost.Jam</link> documentation.
- </para>
-
- <para>
- <link linkend="bbv2.jam">Boost.Jam</link> has an interpreted, procedural
- language. On the lowest level, a <link linkend="bbv2.jam">Boost.Jam
- </link> program consists of variables and <indexterm><primary>rule
- </primary></indexterm> <firstterm>rules</firstterm> (Jam term for
- function). They are grouped into modules—there is one global
- module and a number of named modules. Besides that, a <link linkend=
- "bbv2.jam">Boost.Jam</link> program contains classes and class
- instances.
- </para>
-
- <para>
- Syntantically, a <link linkend="bbv2.jam">Boost.Jam</link> program
- consists of two kind of elements—keywords (which have a special
- meaning to <link linkend="bbv2.jam">Boost.Jam</link>) and literals.
- Consider this code:
-<programlisting>
-a = b ;
-</programlisting>
- which assigns the value <literal>b</literal> to the variable <literal>a
- </literal>. Here, <literal>=</literal> and <literal>;</literal> are
- keywords, while <literal>a</literal> and <literal>b</literal> are
- literals.
- <warning>
- <para>
- All syntax elements, even keywords, must be separated by spaces. For
- example, omitting the space character before <literal>;</literal>
- will lead to a syntax error.
- </para>
- </warning>
- If you want to use a literal value that is the same as some keyword, the
- value can be quoted:
-<programlisting>
-a = "=" ;
-</programlisting>
- </para>
-
- <para>
- All variables in <link linkend="bbv2.jam">Boost.Jam</link> have the same
- type—list of strings. To define a variable one assigns a value to
- it, like in the previous example. An undefined variable is the same as a
- variable with an empty value. Variables can be accessed using the
- <code>$(<replaceable>variable</replaceable>)</code> syntax. For example:
-<programlisting>
-a = $(b) $(c) ;
-</programlisting>
- </para>
-
- <para>
- Rules are defined by specifying the rule name, the parameter names, and
- the allowed value list size for each parameter.
-<programlisting>
-rule <replaceable>example</replaceable>
- (
- <replaceable>parameter1</replaceable> :
- <replaceable>parameter2 ?</replaceable> :
- <replaceable>parameter3 +</replaceable> :
- <replaceable>parameter4 *</replaceable>
- )
- {
- # rule body
- }
- </programlisting>
- When this rule is called, the list passed as the first argument must
- have exactly one value. The list passed as the second argument can
- either have one value of be empty. The two remaining arguments can be
- arbitrarily long, but the third argument may not be empty.
- </para>
-
- <para>
- The overview of <link linkend="bbv2.jam">Boost.Jam</link> language
- statements is given below:
-<programlisting>
-helper 1 : 2 : 3 ;
-x = [ helper 1 : 2 : 3 ] ;
-</programlisting>
- This code calls the named rule with the specified arguments. When the
- result of the call must be used inside some expression, you need to add
- brackets around the call, like shown on the second line.
-<programlisting>
-if cond { statements } [ else { statements } ]
-</programlisting>
- This is a regular if-statement. The condition is composed of:
- <itemizedlist>
- <listitem>
- <para>
- Literals (true if at least one string is not empty)
- </para>
- </listitem>
- <listitem>
- <para>
- Comparisons: <code>a <replaceable>operator</replaceable> b</code>
- where <replaceable>operator</replaceable> is one of
- <code>=</code>, <code>!=</code>, <code><</code>,
- <code>></code>, <code><=</code> or <code>>=</code>. The
- comparison is done pairwise between each string in the left and
- the right arguments.
- </para>
- </listitem>
- <listitem>
- <para>
- Logical operations: <code>! a</code>, <code>a && b</code>,
- <code>a || b</code>
- </para>
- </listitem>
- <listitem>
- <para>
- Grouping: <code>( cond )</code>
- </para>
- </listitem>
- </itemizedlist>
-<programlisting>
-for var in list { statements }
-</programlisting>
- Executes statements for each element in list, setting the variable
- <varname>var</varname> to the element value.
-<programlisting>
-while cond { statements }
-</programlisting>
- Repeatedly execute statements while cond remains true upon entry.
-<programlisting>
-return values ;
-</programlisting>
- This statement should be used only inside a rule and assigns
- <code>values</code> to the return value of the rule.
- <warning>
- <para>
- The <code>return</code> statement does not exit the rule. For
- example:
-<programlisting>
-rule test ( )
-{
- if 1 = 1
- {
- return "reasonable" ;
- }
- return "strange" ;
-}
-</programlisting>
- will return <literal>strange</literal>, not
- <literal>reasonable</literal>.
- </para>
- </warning>
-<programlisting>
-import <replaceable>module</replaceable> ;
-import <replaceable>module</replaceable> : <replaceable>rule</replaceable> ;
-</programlisting>
- The first form imports the specified bjam module. All rules from that
- module are made available using the qualified name: <code><replaceable>
- module</replaceable>.<replaceable>rule</replaceable></code>. The second
- form imports the specified rules only, and they can be called using
- unqualified names.
- </para>
-
- <para id="bbv2.advanced.jam_language.actions">
- Sometimes, you'd need to specify the actual command lines to be used
- when creating targets. In jam language, you use named actions to do
- this. For example:
-<programlisting>
-actions create-file-from-another
-{
- create-file-from-another $(<) $(>)
-}
-</programlisting>
- This specifies a named action called <literal>
- create-file-from-another</literal>. The text inside braces is the
- command to invoke. The <literal>$(<)</literal> variable will be
- expanded to a list of generated files, and the <literal>$(>)
- </literal> variable will be expanded to a list of source files.
- </para>
-
- <para>
- To flexibly adjust the command line, you can define a rule with the same
- name as the action and taking three parameters -- targets, sources and
- properties. For example:
-<programlisting>
-rule create-file-from-another ( targets * : sources * : properties * )
-{
- if <variant>debug in $(properties)
- {
- OPTIONS on $(targets) = --debug ;
- }
-}
-actions create-file-from-another
-{
- create-file-from-another $(OPTIONS) $(<) $(>)
-}
-</programlisting>
- In this example, the rule checks if certain build property is specified.
- If so, it sets variable <varname>OPIONS</varname> that is then used
- inside the action. Note that the variables set "on a target" will be
- visible only inside actions building that target, not globally. Were
- they set globally, using variable named <varname>OPTIONS</varname> in
- two unrelated actions would be impossible.
- </para>
-
- <para>
- More details can be found in Jam reference, <xref
- linkend="jam.language.rules"/>.
- </para>
- </section>
-
- <section id="bbv2.advanced.configuration">
- <title>Configuration</title>
-
- <para>
- On startup, Boost.Build searches and reads two configuration files:
- <filename>site-config.jam</filename> and <filename>user-config.jam</filename>.
- The first one is usually installed and maintained by system administrator, and
- the second is for user to modify. You can edit the one in the top-level
- directory of Boost.Build installation or create a copy in your home
- directory and edit the copy. The following table explains where both files
- are searched.
- </para>
-
- <table id="bbv2.reference.init.config">
- <title>Search paths for configuration files</title>
-
- <tgroup cols="3">
- <thead>
-
- <row>
- <entry></entry>
-
- <entry>site-config.jam</entry>
-
- <entry>user-config.jam</entry>
- </row>
-
- </thead>
- <tbody>
-
- <row>
- <entry>Linux</entry>
-
- <entry>
- <simpara><code>/etc</code></simpara>
- <simpara><code>$HOME</code></simpara>
- <simpara><code>$BOOST_BUILD_PATH</code></simpara>
- </entry>
-
- <entry>
- <simpara><code>$HOME</code></simpara>
- <simpara><code>$BOOST_BUILD_PATH</code></simpara>
- </entry>
- </row>
-
- <row>
- <entry>Windows</entry>
-
- <entry>
- <simpara><code>%SystemRoot%</code></simpara>
- <simpara><code>%HOMEDRIVE%%HOMEPATH%</code></simpara>
- <simpara><code>%HOME%</code></simpara>
- <simpara><code>%BOOST_BUILD_PATH%</code></simpara>
- </entry>
-
- <entry>
- <simpara><code>%HOMEDRIVE%%HOMEPATH%</code></simpara>
- <simpara><code>%HOME%</code></simpara>
- <simpara><code>%BOOST_BUILD_PATH%</code></simpara>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <tip>
- <para>
- You can use the <command>--debug-configuration</command> option to
- find which configuration files are actually loaded.
- </para>
- </tip>
-
- <para>
- Usually, <filename>user-config.jam</filename> just defines available compilers
- and other tools (see <xref linkend="bbv2.recipies.site-config"/> for more advanced
- usage). A tool is configured using the following syntax:
- </para>
-
-<programlisting>
-using <replaceable>tool-name</replaceable> : ... ;
-</programlisting>
-<para>
- The <functionname>using</functionname> rule is given a name of tool, and
- will make that tool available to Boost.Build. For example,
-<programlisting>
-using gcc ;
-</programlisting> will make the <ulink url="http://gcc.gnu.org">GCC</ulink> compiler available.
- </para>
-
- <para>
- All the supported tools are documented in <xref linkend="bbv2.reference.tools"/>,
- including the specific options they take. Some general notes that apply to most
- C++ compilers are below.
- </para>
-
- <para>
- For all the C++ compiler toolsets Boost.Build supports
- out-of-the-box, the list of parameters to
- <functionname>using</functionname> is the same: <parameter
- class="function">toolset-name</parameter>, <parameter
- class="function">version</parameter>, <parameter
- class="function">invocation-command</parameter>, and <parameter
- class="function">options</parameter>.
- </para>
-
- <para>If you have a single compiler, and the compiler executable
- <itemizedlist>
- <listitem><para>has its “usual name” and is in the
- <envar>PATH</envar>, or</para></listitem>
- <listitem><para>was installed in a standard “installation
- directory”, or</para></listitem>
- <listitem><para>can be found using a global system like the Windows
- registry.</para></listitem>
- </itemizedlist>
- it can be configured by simply:</para>
-<programlisting>
-using <replaceable>tool-name</replaceable> ;
-</programlisting>
- <!-- TODO: mention auto-configuration? -->
-
- <para>If the compiler is installed in a custom directory, you should provide the
- command that invokes the compiler, for example:</para>
-<programlisting>
-using gcc : : g++-3.2 ;
-using msvc : : "Z:/Programs/Microsoft Visual Studio/vc98/bin/cl" ;
-</programlisting>
- <para>
- Some Boost.Build toolsets will use that path to take additional actions
- required before invoking the compiler, such as calling vendor-supplied
- scripts to set up its required environment variables. When compiler
- executables for C and C++ are different, path to the C++ compiler
- executable must be specified. The command can
- be any command allowed by the operating system. For example:
-<programlisting>
-using msvc : : echo Compiling && foo/bar/baz/cl ;
-</programlisting>
- will work.
- </para>
-
- <para>
- To configure several versions of a toolset, simply invoke the
- <functionname>using</functionname> rule multiple times:
-<programlisting>
-using gcc : 3.3 ;
-using gcc : 3.4 : g++-3.4 ;
-using gcc : 3.2 : g++-3.2 ;
-</programlisting>
- Note that in the first call to <functionname>using</functionname>, the
- compiler found in the <envar>PATH</envar> will be used, and there is no
- need to explicitly specify the command.
- </para>
-
-<!-- TODO: This is not actually relevant for gcc now, and we need to rethink this
- <para>As shown above, both the <parameter
- class="function">version</parameter> and <parameter
- class="function">invocation-command</parameter> parameters are
- optional, but there's an important restriction: if you configure
- the same toolset more than once, you must pass the <parameter
- class="function">version</parameter>
- parameter every time. For example, the following is not allowed:
-<programlisting>
-using gcc ;
-using gcc : 3.4 : g++-3.4 ;
-</programlisting>
- because the first <functionname>using</functionname> call does
- not specify a <parameter class="function">version</parameter>.
- </para> -->
-
- <para>
- Many of toolsets have an <parameter class="function">options</parameter>
- parameter to fine-tune the configuration. All of
- Boost.Build's standard compiler toolsets accept four options
- <varname>cflags</varname>, <varname>cxxflags</varname>,
- <varname>compileflags</varname> and <varname>linkflags</varname> as <parameter
- class="function">options</parameter> specifying flags that will be
- always passed to the corresponding tools. Values of the
- <varname>cflags</varname> feature are passed directly to the C
- compiler, values of the <varname>cxxflags</varname> feature are
- passed directly to the C++ compiler, and values of the
- <varname>compileflags</varname> feature are passed to both. For
- example, to configure a <command>gcc</command> toolset so that it
- always generates 64-bit code you could write:
-<programlisting>
- using gcc : 3.4 : : <compileflags>-m64 <linkflags>-m64 ;
-</programlisting>
- </para>
-
- <warning>
- <para>
- Although the syntax used to specify toolset options is very similar
- to syntax used to specify requirements in Jamfiles, the toolset options
- are not the same as features. Don't try to specify a feature value
- in toolset initialization.
- </para>
- </warning>
-
- </section>
-
- <section id="bbv2.advanced.invocation">
- <title>Invocation</title>
-
- <para>To invoke Boost.Build, type <command>bjam</command> on the command line. Three kinds
- of command-line tokens are accepted, in any order:</para>
- <variablelist>
- <varlistentry>
- <term>options</term>
-
- <listitem><para>Options start with either dash, or two dashes. The standard options
- are listed below, and each project may add additional options</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>properties</term>
-
- <listitem><para>Properties specify details of what you want to build (e.g. debug
- or release variant). Syntactically, all command line tokens with equal sign in them
- are considered to specify properties. In the simplest form, property looks like
- <command><replaceable>feature</replaceable>=<replaceable>value</replaceable></command>
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>target</term>
-
- <listitem><para>All tokens that are neither options nor properties specify
- what targets to build. The available targets entirely depend on the project
- you are building.</para></listitem>
- </varlistentry>
- </variablelist>
-
- <section id="bbv2.advanced.invocation.examples">
- <title>Examples</title>
-
- <para>To build all targets defined in Jamfile in the current directory with default properties, run:
-<screen>
-bjam
-</screen>
- </para>
-
- <para>To build specific targets, specify them on the command line:
-<screen>
-bjam lib1 subproject//lib2
-</screen>
- </para>
-
- <para>To request a certain value for some property, add <literal>
- <replaceable>property</replaceable>=<replaceable>value</replaceable></literal> to the command line:
-<screen>
-bjam toolset=gcc variant=debug optimization=space
-</screen>
- </para>
- </section>
-
- <section id="bbv2.advanced.invocation.options">
- <title>Options</title>
-
- <para>Boost.Build recognizes the following command line options.</para>
-
- <variablelist>
-
- <varlistentry id="bbv2.reference.init.options.help">
- <term><option>--help</option></term>
- <listitem>
- <para>Invokes the online help system. This prints general
- information on how to use the help system with additional
- --help* options.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--clean</option></term>
- <listitem>
- <para>Cleans all targets in the current directory and
- in any subprojects. Note that unlike the <literal>clean</literal>
- target in make, you can use <literal>--clean</literal>
- together with target names to clean specific targets.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--clean-all</option></term>
- <listitem>
- <para>Cleans all targets,
- no matter where they are defined. In particular, it will clean targets
- in parent Jamfiles, and targets defined under other project roots.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--build-dir</option></term>
- <listitem>
- <para>Changes build directories for all project roots being built. When
- this option is specified, all Jamroot files should declare project name.
- The build directory for the project root will be computed by concatanating
- the value of the <option>--build-dir</option> option, the project name
- specified in Jamroot, and the build dir specified in Jamroot
- (or <literal>bin</literal>, if none is specified).
- </para>
-
- <para>The option is primarily useful when building from read-only
- media, when you can't modify Jamroot.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--version</option></term>
- <listitem>
- <para>Prints information on Boost.Build and Boost.Jam
- versions.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-a</option></term>
- <listitem>
- <para>Causes all files to be rebuilt.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-n</option></term>
- <listitem>
- <para>Do no execute the commands, only print them.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-d+2</option></term>
- <listitem>
- <para>Show commands as they are executed.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-d0</option></term>
- <listitem>
- <para>Supress all informational messages.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-q</option></term>
- <listitem>
- <para>Stop at first error, as opposed to continuing to build targets
- that don't depend on the failed ones.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-j <replaceable>N</replaceable></option></term>
- <listitem>
- <para>Run up to <replaceable>N</replaceable> commands in parallel.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--debug-configuration</option></term>
- <listitem>
- <para>Produces debug information about loading of Boost.Build
- and toolset files.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--debug-building</option></term>
- <listitem>
- <para>Prints what targets are being built and with what properties.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--debug-generators</option></term>
- <listitem>
- <para>Produces debug output from generator search process.
- Useful for debugging custom generators.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--ignore-config</option></term>
- <listitem>
- <para>Do not load <literal>site-config.jam</literal> and
- <literal>user-config.jam</literal> configuration files.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section id="bbv2.advanced.invocation.properties">
- <title>Properties</title>
-
- <para>In the simplest case, the build is performed with a single set of properties,
- that you specify on the command line with elements in the form
- <command><replaceable>feature</replaceable>=<replaceable>value</replaceable></command>.
- The complete list of features can be found in <xref linkend="bbv2.advanced.builtins.features"/>.
- The most common features are summarized below.</para>
-
- <table>
- <tgroup cols="3">
- <thead>
-
- <row>
- <entry>Feature</entry>
-
- <entry>Allowed values</entry>
-
- <entry>Notes</entry>
- </row>
-
- </thead>
- <tbody>
-
- <row>
- <entry>variant</entry>
-
- <entry>debug,release</entry>
-
- <entry></entry>
- </row>
-
- <row>
- <entry>link</entry>
-
- <entry>shared,static</entry>
-
- <entry>Determines if Boost.Build creates shared or static libraries</entry>
- </row>
-
- <row>
- <entry>threading</entry>
-
- <entry>single,multi</entry>
-
- <entry>Cause the produced binaries to be thread-safe. This requires proper support in the source code itself.</entry>
- </row>
-
- <row>
- <entry>address-model</entry>
-
- <entry>32,64</entry>
-
- <entry>Explicitly request either 32-bit or 64-bit code generation. This typically
- requires that your compiler is appropriately configured. Please refer to
- <xref linkend="bbv2.reference.tools.compilers"/> and your compiler documentation
- in case of problems.</entry>
- </row>
-
- <row>
- <entry>toolset</entry>
-
- <entry>(Depends on configuration)</entry>
-
- <entry>The C++ compiler to use. See <xref linkend="bbv2.reference.tools.compilers"/> for a detailed list.</entry>
- </row>
-
- <row>
- <entry>include</entry>
-
- <entry>(Arbitrary string)</entry>
-
- <entry>Additional include paths for C and C++ compilers.</entry>
- </row>
-
- <row>
- <entry>define</entry>
-
- <entry>(Arbitrary string)</entry>
-
- <entry>Additional macro definitions for C and C++ compilers. The string should be either
- <code>SYMBOL</code> or <code>SYMBOL=VALUE</code></entry>
- </row>
-
- <row>
- <entry>cxxflags</entry>
-
- <entry>(Arbitrary string)</entry>
-
- <entry>Custom options to pass to the C++ compiler.</entry>
- </row>
-
- <row>
- <entry>cflags</entry>
-
- <entry>(Arbitrary string)</entry>
-
- <entry>Custom options to pass to the C compiler.</entry>
- </row>
-
- <row>
- <entry>linkflags</entry>
-
- <entry>(Arbitrary string)</entry>
-
- <entry>Custom options to pass to the C++ linker.</entry>
- </row>
-
- <row>
- <entry>runtime-link</entry>
-
- <entry>shared,static</entry>
-
- <entry>Determines if shared or static version of C and C++ runtimes should be used.</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- If you have more than one version of a given C++ toolset (e.g. configured in
- <filename>user-config.jam</filename>, or autodetected, as happens with msvc), you can
- request the specific version by passing
- <code><replaceable>toolset</replaceable>-<replaceable>version</replaceable></code> as
- the value of the <code>toolset</code> feature, for example <code>toolset=msvc-8.0</code>.
-
-
- <para>
- If a feature has a fixed set of values it can be specified more than
- once on the command line. <!-- define 'base' and link to it -->
- In which case, everything will be built several times --
- once for each specified value of a feature. For example, if you use
- </para>
-<screen>
-bjam link=static link=shared threading=single threading=multi
-</screen>
- <para>
- Then a total of 4 builds will be performed. For convenience,
- instead of specifying all requested values of a feature in separate command line elements,
- you can separate the values with commands, for example:
- </para>
-<screen>
-bjam link=static,shared threading=single,multi
-</screen>
- <para>
- The comma has special meaning only if the feature has a fixed set of values, so
- </para>
-<screen>
-bjam include=static,shared
-</screen>
- <para>is not treated specially.</para>
-
- </section>
-
- <section id="bbv2.advanced.invocation.targets">
- <title>Targets</title>
-
- <para>All command line elements that are neither options nor properties are the names of the
- targets to build. See <xref linkend="bbv2.reference.ids"/>. If no target is specified,
- the project in the current directory is built.</para>
- </section>
-
- </section>
-
- <section id="bbv2.advanced.targets">
- <title>Declaring Targets</title>
-
- <para id="bbv2.advanced.targets.main">
- A <firstterm>Main target</firstterm> is a user-defined named
- entity that can be built, for example an executable file.
- Declaring a main target is usually done using one of the main
- target rules described in <xref linkend=
- "bbv2.reference.rules"/>. The user can also declare
- custom main target rules as shown in <xref
- linkend="bbv2.extending.rules"/>.
- </para>
-
- <indexterm><primary>main target</primary><secondary>declaration
- syntax</secondary></indexterm>
- <para>Most main target rules in Boost.Build have the same common
- signature:</para>
-
- <!-- I think we maybe ought to be talking about a common
- _signature_ here, having already explained Boost.Jam function
- signatures at the beginning of this chapter. Then we could show
- ( main-target-name : sources * : requirements * : default-build * : usage-requirements * )
- instead. More precise.
-
- Also, I suggest replacing "default-build" by "default-properties" everywhere.
- -->
-
-<indexterm><primary>common signature</primary></indexterm>
-<anchor id="bbv2.main-target-rule-syntax"/>
-<programlisting>
-rule <replaceable>rule-name</replaceable> (
- main-target-name :
- sources + :
- requirements * :
- default-build * :
- usage-requirements * )
-</programlisting>
-
- <itemizedlist>
- <listitem>
- <simpara>
- <parameter>main-target-name</parameter> is the name used
- to request the target on command line and to use it from
- other main targets. A main target name may contain
- alphanumeric characters, dashes
- (‘<code>-</code>’), and underscores
- (‘<code>_</code>’).
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>
- <parameter>sources</parameter> is the list of source files and other main
- targets that must be combined.
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>
- <parameter>requirements</parameter> is the list of properties that must always
- be present when this main target is built.
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>
- <parameter>default-build</parameter> is the list of properties that will be used
- unless some other value of the same feature is already
- specified, e.g. on the command line or by propagation from a dependent target.
- </simpara>
- </listitem>
-
- <listitem>
- <simpara>
- <parameter>usage-requirements</parameter> is the list of properties that will be
- propagated to all main targets that use this one, i.e. to all its
- dependents.
- </simpara>
- </listitem>
- </itemizedlist>
-
- <para>
- Some main target rules have a different list of parameters as explicitly
- stated in their documentation.
- </para>
-
- <para>The actual requirements for a target are obtained by refining
- requirements of the project where a target is declared with the
- explicitly specified requirements. The same is true for
- usage-requirements. More details can be found in
- <xref linkend="bbv2.reference.variants.proprefine"/>
- </para>
-
- <section>
- <title>Name</title>
-
- <!-- perphaps we should use 'name-target-name' to closer
- bind this description to the rule's signature. Here, and for
- other parameters. -->
- <para>The name of main target has two purposes. First, it's used to refer to this target from
- other targets and from command line. Second, it's used to compute the names of the generated files.
- Typically, filenames are obtained from main target name by appending system-dependent suffixes and
- prefixes.
- </para>
-
- <para>The name of a main target can contain alphanumeric characters,
- dashes, undescores and dots. The entire
- name is significant when resolving references from other targets. For determining filenames, only the
- part before the first dot is taken. For example:</para>
-<programlisting>
-obj test.release : test.cpp : <variant>release ;
-obj test.debug : test.cpp : <variant>debug ;
-</programlisting>
- <para>will generate two files named <filename>test.obj</filename> (in two different directories), not
- two files named <filename>test.release.obj</filename> and <filename>test.debug.obj</filename>.
- </para>
-
- </section>
-
- <section>
- <title>Sources</title>
-
- <para>The list of sources specifies what should be processed to
- get the resulting targets. Most of the time, it's just a list of
- files. Sometimes, you'll want to automatically construct the
- list of source files rather than having to spell it out
- manually, in which case you can use the
- <functionname>glob</functionname> rule. Here are two examples:</para>
-<programlisting>
-exe a : a.cpp ; # a.cpp is the only source file
-exe b : [ glob *.cpp ] ; # all .cpp files in this directory are sources
-</programlisting>
- <para>
- Unless you specify a file with an absolute path, the name is
- considered relative to the source directory — which is typically
- the directory where the Jamfile is located, but can be changed as
- described in <xref linkend=
- "bbv2.advanced.projects.attributes.projectrule"/>.
- </para>
-
- <para>
- <!-- use "project-id" here? -->
- The list of sources can also refer to other main targets. Targets in
- the same project can be referred to by name, while targets in other
- projects must be qualified with a directory or a symbolic project
- name. The directory/project name is separated from the target name by
- a double forward slash. There is no special syntax to distinguish the
- directory name from the project name—the part before the double
- slash is first looked up as project name, and then as directory name.
- For example:
- </para>
-<programlisting>
-lib helper : helper.cpp ;
-exe a : a.cpp helper ;
-# Since all project ids start with slash, ".." is a directory name.
-exe b : b.cpp ..//utils ;
-exe c : c.cpp /boost/program_options//program_options ;
-</programlisting>
- <para>
- The first exe uses the library defined in the same project. The second
- one uses some target (most likely a library) defined by a Jamfile one
- level higher. Finally, the third target uses a <ulink url=
- "http://boost.org">C++ Boost</ulink> library, referring to it using
- its absolute symbolic name. More information about target references
- can be found in <xref linkend="bbv2.tutorial.libs"/> and <xref
- linkend="bbv2.reference.ids"/>.
- </para>
- </section>
-
- <section id="bbv2.advanced.targets.requirements">
- <title>Requirements</title>
- <indexterm><primary>requirements</primary></indexterm>
- <para>Requirements are the properties that should always be present when
- building a target. Typically, they are includes and defines:
-<programlisting>
-exe hello : hello.cpp : <include>/opt/boost <define>MY_DEBUG ;
-</programlisting>
- There is a number of other features, listed in
- <xref linkend="bbv2.advanced.builtins.features"/>. For example if
- a library can only be built statically, or a file can't be compiled
- with optimization due to a compiler bug, one can use
-<programlisting>
-lib util : util.cpp : <link>static ;
-obj main : main.cpp : <optimization>off ;
-</programlisting>
- </para>
-
- <para id="bbv2.advanced.targets.requirements.conditional">Sometimes, particular relationships need to be maintained
- among a target's build properties. This can be achieved with
- <firstterm>conditional
- requirements</firstterm>. For example, you might want to set
- specific <code>#defines</code> when a library is built as shared,
- or when a target's <code>release</code> variant is built in
- release mode.
-<programlisting>
-lib network : network.cpp
- : <emphasis role="bold"><link>shared:<define>NEWORK_LIB_SHARED</emphasis>
- <variant>release:<define>EXTRA_FAST
- ;
-</programlisting>
-
- In the example above, whenever <filename>network</filename> is
- built with <code><link>shared</code>,
- <code><define>NEWORK_LIB_SHARED</code> will be in its
- properties, too.
- </para>
-
- <para>You can use several properties in the condition, for example:
-<programlisting>
-lib network : network.cpp
- : <toolset>gcc,<optimization>speed:<define>USE_INLINE_ASSEMBLER
- ;
-</programlisting>
- </para>
-
- <para id="bbv2.advanced.targets.requirements.indirect">
- A more powerful variant of conditional requirements
- is <firstterm>indirect conditional requirements</firstterm>.
- You can provide a rule that will be called with the current build properties and can compute additional properties
- to be added. For example:
-<programlisting>
-lib network : network.cpp
- : <conditional>@my-rule
- ;
-rule my-rule ( properties * )
-{
- local result ;
- if <toolset>gcc <optimization>speed in $(properties)
- {
- result += <define>USE_INLINE_ASSEMBLER ;
- }
- return $(result) ;
-}
-</programlisting>
- This example is equivalent to the previous one, but for complex cases, indirect conditional
- requirements can be easier to write and understand.
- </para>
-
- <para>Requirements explicitly specified for a target are usually
- combined with the requirements specified for the containing project. You
- can cause a target to completely ignore specific project's requirement
- using the syntax by adding a minus sign before a property, for example:
-<programlisting>
-exe main : main.cpp : <emphasis role="bold">-<define>UNNECESSARY_DEFINE</emphasis> ;
-</programlisting>
- This syntax is the only way to ignore free properties from a parent,
- such as defines. It can be also useful for ordinary properties. Consider
- this example:
-<programlisting>
-project test : requirements <threading>multi ;
-exe test1 : test1.cpp ;
-exe test2 : test2.cpp : <threading>single ;
-exe test3 : test3.cpp : -<threading>multi ;
-</programlisting>
- Here, <code>test1</code> inherits project requirements and will always
- be built in multi-threaded mode. The <code>test2</code> target
- <emphasis>overrides</emphasis> project's requirements and will
- always be built in single-threaded mode. In contrast, the
- <code>test3</code> target <emphasis>removes</emphasis> a property
- from project requirements and will be built either in single-threaded or
- multi-threaded mode depending on which variant is requested by the
- user.</para>
-
- <para>Note that the removal of requirements is completely textual:
- you need to specify exactly the same property to remove it.</para>
-
- </section>
-
- <section>
- <title>Default Build</title>
-
- <para>The <varname>default-build</varname> parameter
- is a set of properties to be used if the build request does
- not otherwise specify a value for features in the set. For example:
-<programlisting>
-exe hello : hello.cpp : : <threading>multi ;
-</programlisting>
- would build a multi-threaded target unless the user
- explicitly requests a single-threaded version. The difference between
- requirements and default-build is that requirements cannot be
- overridden in any way.
- </para>
- </section>
-
- <section>
- <title>Additional Information</title>
-
- <para>
- The ways a target is built can be so different that
- describing them using conditional requirements would be
- hard. For example, imagine that a library actually uses
- different source files depending on the toolset used to build
- it. We can express this situation using <firstterm>target
- alternatives</firstterm>:
-<programlisting>
-lib demangler : dummy_demangler.cpp ; # alternative 1
-lib demangler : demangler_gcc.cpp : <toolset>gcc ; # alternative 2
-lib demangler : demangler_msvc.cpp : <toolset>msvc ; # alternative 3
-</programlisting>
- In the example above, when built with <literal>gcc</literal>
- or <literal>msvc</literal>, <filename>demangler</filename>
- will use a source file specific to the toolset. Otherwise, it
- will use a generic source file,
- <filename>dummy_demangler.cpp</filename>.
- </para>
-
- <para>It is possible to declare a target inline, i.e. the "sources"
- parameter may include calls to other main rules. For example:</para>
-
-<programlisting>
-exe hello : hello.cpp
- [ obj helpers : helpers.cpp : <optimization>off ] ;</programlisting>
-
- <para>
- Will cause "helpers.cpp" to be always compiled without
- optimization. When referring to an inline main target, its declared
- name must be prefixed by its parent target's name and two dots. In
- the example above, to build only helpers, one should run
- <code>bjam hello..helpers</code>.
- </para>
-
- <para>When no target is requested on the command line, all targets in the
- current project will be built. If a target should be built only by
- explicit request, this can be expressed by the
- <functionname>explicit</functionname> rule:
- <programlisting>
-explicit install_programs ;</programlisting>
- </para>
-
- </section>
- </section>
-
- <section id="bbv2.advanced.projects">
- <title>Projects</title>
-
- <para>As mentioned before, targets are grouped into projects,
- and each Jamfile is a separate project. Projects are useful
- because they allow us to group related targets together, define
- properties common to all those targets, and assign a symbolic
- name to the project that can be used in referring to its
- targets.
- </para>
-
- <para>Projects are named using the
- <functionname>project</functionname> rule, which has the
- following syntax:
-<programlisting>
-project <replaceable>id</replaceable> : <replaceable>attributes</replaceable> ;
-</programlisting>
- Here, <replaceable>attributes</replaceable> is a sequence of
- rule arguments, each of which begins with an attribute-name
- and is followed by any number of build properties. The list
- of attribute names along with its handling is also shown in
- the table below. For example, it is possible to write:
-<programlisting>
-project tennis
- : requirements <threading>multi
- : default-build release
- ;
-</programlisting>
- </para>
-
- <para>The possible attributes are listed below.</para>
-
- <para><emphasis>Project id</emphasis> is a short way to denote a project, as
- opposed to the Jamfile's pathname. It is a hierarchical path,
- unrelated to filesystem, such as "boost/thread". <link linkend=
- "bbv2.reference.ids">Target references</link> make use of project ids to
- specify a target.</para>
- <!--
- This is actually spelled "project-id," isn't it? You
- have to fix all of these and use a code font. Also below
- in the table.
- -->
-
- <para><emphasis>Source location</emphasis> specifies the directory where sources
- for the project are located.</para>
-
- <para><emphasis>Project requirements</emphasis> are requirements that apply to
- all the targets in the projects as well as all subprojects.</para>
-
- <para><emphasis>Default build</emphasis> is the build request that should be
- used when no build request is specified explicitly.</para>
- <!--
- This contradicts your earlier description of default
- build and I believe it is incorrect. Specifying a build
- request does not neccessarily render default build
- ineffective, because it may cover different features.
- This description is repeated too many times in the
- documentation; you almost *had* to get it wrong once.
- -->
-
- <para id="bbv2.advanced.projects.attributes.projectrule">
- The default values for those attributes are
- given in the table below.
-
- <table>
- <title/>
- <tgroup cols="4">
- <thead>
- <row>
- <entry>Attribute</entry>
-
- <entry>Name</entry>
-
- <entry>Default value</entry>
-
- <entry>Handling by the <functionname>project</functionname>
- rule</entry>
-
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>Project id</entry>
-
- <entry>none</entry>
-
- <entry>none</entry>
-
- <entry>Assigned from the first parameter of the 'project' rule.
- It is assumed to denote absolute project id.</entry>
- </row>
-
- <row>
- <entry>Source location</entry>
-
- <entry><literal>source-location</literal></entry>
-
- <entry>The location of jamfile for the project</entry>
-
- <entry>Sets to the passed value</entry>
- </row>
-
- <row>
- <entry>Requirements</entry>
-
- <entry><literal>requirements</literal></entry>
-
- <entry>The parent's requirements</entry>
-
- <entry>The parent's requirements are refined with the passed
- requirement and the result is used as the project
- requirements.</entry>
- </row>
-
- <row>
- <entry>Default build</entry>
-
- <entry><literal>default-build</literal></entry>
-
- <entry>none</entry>
-
- <entry>Sets to the passed value</entry>
- </row>
-
- <row>
- <entry>Build directory</entry>
-
- <entry><literal>build-dir</literal></entry>
-
- <entry>Empty if the parent has no build directory set.
- Otherwise, the parent's build directory with the
- relative path from parent to the current project
- appended to it.
- </entry>
-
- <entry>Sets to the passed value, interpreted as relative to the
- project's location.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
-
- <para>Besides defining projects and main targets, Jamfiles
- often invoke various utility rules. For the full list of rules
- that can be directly used in Jamfile see
- <xref linkend="bbv2.reference.rules"/>.
- </para>
-
- <para>Each subproject inherits attributes, constants and rules
- from its parent project, which is defined by the nearest
- Jamfile in an ancestor directory above
- the subproject. The top-level project is declared in a file
- called <filename>Jamroot</filename> rather than
- <filename>Jamfile</filename>. When loading a project,
- Boost.Build looks for either <filename>Jamroot</filename> or
- <code>Jamfile</code>. They are handled identically, except
- that if the file is called <filename>Jamroot</filename>, the
- search for a parent project is not performed.
- </para>
-
- <para>Even when building in a subproject directory, parent
- project files are always loaded before those of their
- subprojects, so that every definition made in a parent project
- is always available to its children. The loading order of any
- other projects is unspecified. Even if one project refers to
- another via the <code>use-project</code> or a target reference,
- no specific order should be assumed.
- </para>
-
- <note>
- <para>Giving the root project the special name
- “<filename>Jamroot</filename>” ensures that
- Boost.Build won't misinterpret a directory above it as the
- project root just because the directory contains a Jamfile.
- <!-- The logic of the previous reasoning didn't hang together -->
- </para>
- </note>
-
- <!-- All this redundancy with the tutorial is bad. The tutorial
- should just be made into the introductory sections of this
- document, which should be called the "User Guide." It's
- perfectly appropriate to start a user guide with that kind
- of material. -->
- </section>
-
- <section id="bbv2.advanced.build_process">
- <title>The Build Process</title>
-
- <para>When you've described your targets, you want Boost.Build to run the
- right tools and create the needed targets.
- <!-- That sentence is awkward and doesn't add much. -->
- This section will describe
- two things: how you specify what to build, and how the main targets are
- actually constructed.
- </para>
-
- <para>The most important thing to note is that in Boost.Build, unlike
- other build tools, the targets you declare do not correspond to specific
- files. What you declare in a Jamfile is more like a “metatarget.â€
- <!-- Do we need a new word? We already have “main target.†If
- you're going to introduce “metatarget†you should at least
- tie it together with the main target concept. It's too
- strange to have been saying “main target†all along and now
- suddenly start saying “what you declare in a jamfile†-->
- Depending on the properties you specify on the command line,
- each metatarget will produce a set of real targets corresponding
- to the requested properties. It is quite possible that the same
- metatarget is built several times with different properties,
- producing different files.
- </para>
- <tip>
- <para>
- This means that for Boost.Build, you cannot directly obtain a build
- variant from a Jamfile. There could be several variants requested by the
- user, and each target can be built with different properties.
- </para>
- </tip>
-
- <section id="bbv2.advanced.build_request">
- <title>Build Request</title>
-
- <para>
- The command line specifies which targets to build and with which
- properties. For example:
-<programlisting>
-bjam app1 lib1//lib1 toolset=gcc variant=debug optimization=full
-</programlisting>
- would build two targets, "app1" and "lib1//lib1" with the specified
- properties. You can refer to any targets, using
- <link linkend="bbv2.reference.ids">target id</link> and specify arbitrary
- properties. Some of the properties are very common, and for them the name
- of the property can be omitted. For example, the above can be written as:
-<programlisting>
-bjam app1 lib1//lib1 gcc debug optimization=full
-</programlisting>
- The complete syntax, which has some additional shortcuts, is
- described in <xref linkend="bbv2.advanced.invocation"/>.
- </para>
- </section>
-
- <section><title>Building a main target</title>
-
- <para>When you request, directly or indirectly, a build of a main target
- with specific requirements, the following steps are done. Some brief
- explanation is provided, and more details are given in <xref
- linkend="bbv2.reference.buildprocess"/>.
- <orderedlist>
-
- <listitem><para>Applying default build. If the default-build
- property of a target specifies a value of a feature that is not
- present in the build request, that value is added.</para>
- <!--
- Added to what? Don't say “the build request!†The
- request is what was requested; if its meaning changes
- the reader will be confused.
- -->
- </listitem>
-
- <listitem><para>Selecting the main target alternative to use. For
- each alternative we look how many properties are present both in
- alternative's requirements, and in build request. The
- alternative with large number of matching properties is selected.
- </para></listitem>
-
- <listitem><para>Determining "common" properties.
- <!-- It would be nice to have a better name for this. But
- even more importantly, unless you say something about
- the reason for choosing whatever term you use, the
- reader is going to wonder what it means. -->
- The build request
- is <link linkend="bbv2.reference.variants.proprefine">refined</link>
- with target's requirements.
- <!-- It's good that you have the links here and below,
- but I'm concerned that it doesn't communicate well
- in print and there's not enough information for the
- print reader. Maybe we need separate XSL for PDF
- printing that generates a readable footnote. -->
- The conditional properties in
- requirements are handled as well. Finally, default values of
- features are added.
- </para></listitem>
-
- <listitem><para>Building targets referred by the sources list and
- dependency properties. The list of sources and the properties
- can refer to other target using <link
- linkend="bbv2.reference.ids">target references</link>. For each
- reference, we take all <link
- linkend="bbv2.reference.features.attributes.propagated">propagated</link>
- properties, refine them by explicit properties specified in the
- target reference, and pass the resulting properties as build
- request to the other target.
- </para></listitem>
-
- <listitem><para>Adding the usage requirements produced when building
- dependencies to the "common" properties. When dependencies are
- built in the previous step, they return
- <!-- don't assume reader has a mental model for BB internals! -->
- both the set of created
- "real" targets, and usage requirements. The usage requirements
- are added to the common properties and the resulting property
- set will be used for building the current target.
- </para></listitem>
-
- <listitem><para>Building the target using generators. To convert the
- sources to the desired type, Boost.Build uses "generators" ---
- objects that correspond to tools like compilers and linkers. Each
- generator declares what type of targets it can produce and what
- type of sources it requires. Using this information, Boost.Build
- determines which generators must be run to produce a specific
- target from specific sources. When generators are run, they return
- the "real" targets.
- </para></listitem>
-
- <listitem><para>Computing the usage requirements to be returned. The
- conditional properties in usage requirements are expanded
- <!-- what does "expanded" mean? -->
- and the result is returned.</para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <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
- arguments
- <!-- do you know the difference between parameters and
- arguments? I only learned this year -->
- builds the project defined in the current
- directory.</para>
-
- <para>When a project is built, the build request is passed without
- modification to all main targets in that project.
- <!-- What does it mean to pass a build request to a target?
- -->
- It's is possible to
- prevent implicit building of a target in a project with the
- <code>explicit</code> rule:
-<programlisting>
-explicit hello_test ;
-</programlisting>
- would cause the <code>hello_test</code> target to be built only if
- explicitly requested by the user or by some other target.
- </para>
-
- <para>The Jamfile for a project can include a number of
- <code>build-project</code> rule calls that specify additional projects to
- be built.
- </para>
-
- </section>
-
- </section>
-
- </chapter>
-
-<!--
- Local Variables:
- mode: nxml
- sgml-indent-data: t
- sgml-parent-document: ("userman.xml" "chapter")
- sgml-set-face: t
- End:
--->
Modified: trunk/tools/build/v2/doc/src/faq.xml
==============================================================================
--- trunk/tools/build/v2/doc/src/faq.xml (original)
+++ trunk/tools/build/v2/doc/src/faq.xml 2009-08-22 04:42:34 EDT (Sat, 22 Aug 2009)
@@ -30,7 +30,7 @@
<listitem>
<simpara>
Use conditional requirements or indirect conditional requirements. See
- <xref linkend="bbv2.advanced.targets.requirements.conditional"/>.
+ <xref linkend="bbv2.overview.targets.requirements.conditional"/>.
</simpara>
</listitem>
<listitem>
Modified: trunk/tools/build/v2/doc/src/howto.xml
==============================================================================
--- trunk/tools/build/v2/doc/src/howto.xml (original)
+++ trunk/tools/build/v2/doc/src/howto.xml 2009-08-22 04:42:34 EDT (Sat, 22 Aug 2009)
@@ -9,20 +9,20 @@
If you've just found out about Boost.Build V2 and want to know
if it will work for you, start with <xref linkend=
"bbv2.tutorial" />. You can continue with <xref
- linkend="bbv2.advanced" />. When you're ready to try Boost.Build
+ linkend="bbv2.overview" />. When you're ready to try Boost.Build
in practice, go to <xref linkend="bbv2.installation"/>.
</para>
<para>
If you are about to use Boost.Build on your project, or already
using it and have a problem, look at <xref linkend=
- "bbv2.advanced"/>.
+ "bbv2.overview"/>.
</para>
<para>
If you're trying to build a project which uses Boost.Build,
see <xref linkend="bbv2.installation"/> and then read about
- <xref linkend="bbv2.advanced.invocation"/>.
+ <xref linkend="bbv2.overview.invocation"/>.
</para>
<para>
Copied: trunk/tools/build/v2/doc/src/overview.xml (from r55714, /trunk/tools/build/v2/doc/src/advanced.xml)
==============================================================================
--- /trunk/tools/build/v2/doc/src/advanced.xml (original)
+++ trunk/tools/build/v2/doc/src/overview.xml 2009-08-22 04:42:34 EDT (Sat, 22 Aug 2009)
@@ -2,7 +2,7 @@
<!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
- <chapter id="bbv2.advanced">
+ <chapter id="bbv2.overview">
<title>Overview</title>
<para>
@@ -57,32 +57,32 @@
<itemizedlist>
<listitem>
<para>
- <link linkend="bbv2.advanced.configuration">How to configure
+ <link linkend="bbv2.overview.configuration">How to configure
Boost.Build</link>
</para>
</listitem>
<listitem>
<para>
- <link linkend="bbv2.advanced.targets">How to declare targets in
+ <link linkend="bbv2.overview.targets">How to declare targets in
Jamfiles</link>
</para>
</listitem>
<listitem>
<para>
- <link linkend="bbv2.advanced.build_process">How the build process
+ <link linkend="bbv2.overview.build_process">How the build process
works</link>
</para>
</listitem>
<listitem>
<para>
Some Basics about the Boost.Jam language. See <xref linkend=
- "bbv2.advanced.jam_language"/>.
+ "bbv2.overview.jam_language"/>.
</para>
</listitem>
</itemizedlist>
</para>
- <section id="bbv2.advanced.jam_language">
+ <section id="bbv2.overview.jam_language">
<title>Boost.Jam Language</title>
<para>
@@ -245,7 +245,7 @@
unqualified names.
</para>
- <para id="bbv2.advanced.jam_language.actions">
+ <para id="bbv2.overview.jam_language.actions">
Sometimes, you'd need to specify the actual command lines to be used
when creating targets. In jam language, you use named actions to do
this. For example:
@@ -293,7 +293,7 @@
</para>
</section>
- <section id="bbv2.advanced.configuration">
+ <section id="bbv2.overview.configuration">
<title>Configuration</title>
<para>
@@ -491,7 +491,7 @@
</section>
- <section id="bbv2.advanced.invocation">
+ <section id="bbv2.overview.invocation">
<title>Invocation</title>
<para>To invoke Boost.Build, type <command>bjam</command> on the command line. Three kinds
@@ -523,7 +523,7 @@
</varlistentry>
</variablelist>
- <section id="bbv2.advanced.invocation.examples">
+ <section id="bbv2.overview.invocation.examples">
<title>Examples</title>
<para>To build all targets defined in Jamfile in the current directory with default properties, run:
@@ -546,7 +546,7 @@
</para>
</section>
- <section id="bbv2.advanced.invocation.options">
+ <section id="bbv2.overview.invocation.options">
<title>Options</title>
<para>Boost.Build recognizes the following command line options.</para>
@@ -688,13 +688,13 @@
</variablelist>
</section>
- <section id="bbv2.advanced.invocation.properties">
+ <section id="bbv2.overview.invocation.properties">
<title>Properties</title>
<para>In the simplest case, the build is performed with a single set of properties,
that you specify on the command line with elements in the form
<command><replaceable>feature</replaceable>=<replaceable>value</replaceable></command>.
- The complete list of features can be found in <xref linkend="bbv2.advanced.builtins.features"/>.
+ The complete list of features can be found in <xref linkend="bbv2.overview.builtins.features"/>.
The most common features are summarized below.</para>
<table>
@@ -842,7 +842,7 @@
</section>
- <section id="bbv2.advanced.invocation.targets">
+ <section id="bbv2.overview.invocation.targets">
<title>Targets</title>
<para>All command line elements that are neither options nor properties are the names of the
@@ -852,10 +852,10 @@
</section>
- <section id="bbv2.advanced.targets">
+ <section id="bbv2.overview.targets">
<title>Declaring Targets</title>
- <para id="bbv2.advanced.targets.main">
+ <para id="bbv2.overview.targets.main">
A <firstterm>Main target</firstterm> is a user-defined named
entity that can be built, for example an executable file.
Declaring a main target is usually done using one of the main
@@ -989,7 +989,7 @@
considered relative to the source directory — which is typically
the directory where the Jamfile is located, but can be changed as
described in <xref linkend=
- "bbv2.advanced.projects.attributes.projectrule"/>.
+ "bbv2.overview.projects.attributes.projectrule"/>.
</para>
<para>
@@ -1021,7 +1021,7 @@
</para>
</section>
- <section id="bbv2.advanced.targets.requirements">
+ <section id="bbv2.overview.targets.requirements">
<title>Requirements</title>
<indexterm><primary>requirements</primary></indexterm>
<para>Requirements are the properties that should always be present when
@@ -1030,7 +1030,7 @@
exe hello : hello.cpp : <include>/opt/boost <define>MY_DEBUG ;
</programlisting>
There is a number of other features, listed in
- <xref linkend="bbv2.advanced.builtins.features"/>. For example if
+ <xref linkend="bbv2.overview.builtins.features"/>. For example if
a library can only be built statically, or a file can't be compiled
with optimization due to a compiler bug, one can use
<programlisting>
@@ -1039,7 +1039,7 @@
</programlisting>
</para>
- <para id="bbv2.advanced.targets.requirements.conditional">Sometimes, particular relationships need to be maintained
+ <para id="bbv2.overview.targets.requirements.conditional">Sometimes, particular relationships need to be maintained
among a target's build properties. This can be achieved with
<firstterm>conditional
requirements</firstterm>. For example, you might want to set
@@ -1067,7 +1067,7 @@
</programlisting>
</para>
- <para id="bbv2.advanced.targets.requirements.indirect">
+ <para id="bbv2.overview.targets.requirements.indirect">
A more powerful variant of conditional requirements
is <firstterm>indirect conditional requirements</firstterm>.
You can provide a rule that will be called with the current build properties and can compute additional properties
@@ -1184,7 +1184,7 @@
</section>
</section>
- <section id="bbv2.advanced.projects">
+ <section id="bbv2.overview.projects">
<title>Projects</title>
<para>As mentioned before, targets are grouped into projects,
@@ -1244,7 +1244,7 @@
documentation; you almost *had* to get it wrong once.
-->
- <para id="bbv2.advanced.projects.attributes.projectrule">
+ <para id="bbv2.overview.projects.attributes.projectrule">
The default values for those attributes are
given in the table below.
@@ -1372,7 +1372,7 @@
of material. -->
</section>
- <section id="bbv2.advanced.build_process">
+ <section id="bbv2.overview.build_process">
<title>The Build Process</title>
<para>When you've described your targets, you want Boost.Build to run the
@@ -1405,7 +1405,7 @@
</para>
</tip>
- <section id="bbv2.advanced.build_request">
+ <section id="bbv2.overview.build_request">
<title>Build Request</title>
<para>
@@ -1423,7 +1423,7 @@
bjam app1 lib1//lib1 gcc debug optimization=full
</programlisting>
The complete syntax, which has some additional shortcuts, is
- described in <xref linkend="bbv2.advanced.invocation"/>.
+ described in <xref linkend="bbv2.overview.invocation"/>.
</para>
</section>
Modified: trunk/tools/build/v2/doc/src/reference.xml
==============================================================================
--- trunk/tools/build/v2/doc/src/reference.xml (original)
+++ trunk/tools/build/v2/doc/src/reference.xml 2009-08-22 04:42:34 EDT (Sat, 22 Aug 2009)
@@ -158,7 +158,7 @@
<term><literal>project</literal></term>
<listitem><para>Declares project id and attributes, including
- project requirements. See <xref linkend="bbv2.advanced.projects"/>.
+ project requirements. See <xref linkend="bbv2.overview.projects"/>.
</para></listitem>
</varlistentry>
@@ -235,7 +235,7 @@
</section>
- <section id="bbv2.advanced.builtins.features">
+ <section id="bbv2.overview.builtins.features">
<title>Builtin features</title>
<para>This section documents the features that are built-in into
@@ -299,7 +299,7 @@
</listitem>
</varlistentry>
- <varlistentry id="bbv2.advanced.builtins.features.link">
+ <varlistentry id="bbv2.overview.builtins.features.link">
<term><literal>link</literal></term>
<listitem>
@@ -314,7 +314,7 @@
</listitem>
</varlistentry>
- <varlistentry id="bbv2.advanced.builtins.features.runtime-link">
+ <varlistentry id="bbv2.overview.builtins.features.runtime-link">
<indexterm><primary>runtime linking</primary></indexterm>
<term><literal>runtime-link</literal></term>
@@ -1399,7 +1399,7 @@
<title>Build process</title>
<para>The general overview of the build process was given in the
- <link linkend="bbv2.advanced.build_process">user documentation</link>.
+ <link linkend="bbv2.overview.build_process">user documentation</link>.
This section provides additional details, and some specific rules.
</para>
@@ -1631,7 +1631,7 @@
<para>Features of this kind are
propagated to dependencies. That is, if a <link linkend=
- "bbv2.advanced.targets.main">main target</link> is built using a
+ "bbv2.overview.targets.main">main target</link> is built using a
propagated
property, the build systems attempts to use the same property
when building any of its dependencies as part of that main
Modified: trunk/tools/build/v2/doc/src/standalone.xml
==============================================================================
--- trunk/tools/build/v2/doc/src/standalone.xml (original)
+++ trunk/tools/build/v2/doc/src/standalone.xml 2009-08-22 04:42:34 EDT (Sat, 22 Aug 2009)
@@ -11,7 +11,7 @@
<xi:include href="howto.xml"/>
<xi:include href="install.xml"/>
<xi:include href="tutorial.xml"/>
- <xi:include href="advanced.xml"/>
+ <xi:include href="overview.xml"/>
<xi:include href="tasks.xml"/>
<xi:include href="reference.xml"/>
<xi:include href="extending.xml"/>
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 2009-08-22 04:42:34 EDT (Sat, 22 Aug 2009)
@@ -12,7 +12,7 @@
<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"/>.
+ the common signature, described in <xref linkend="bbv2.overview.targets"/>.
</para>
<section id="bbv2.tasks.programs">
@@ -537,7 +537,7 @@
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"/>.
+ linkend="bbv2.overview.jam_language.actions"/>.
</para>
<para>
@@ -725,7 +725,7 @@
<para>
When using gcc, you first need to specify your cross compiler
- in <filename>user-config.jam</filename> (see <xref linkend="bbv2.advanced.configuration"/>),
+ in <filename>user-config.jam</filename> (see <xref linkend="bbv2.overview.configuration"/>),
for example:</para>
<programlisting>
using gcc : arm : arm-none-linux-gnueabi-g++ ;
Modified: trunk/tools/build/v2/doc/src/tutorial.xml
==============================================================================
--- trunk/tools/build/v2/doc/src/tutorial.xml (original)
+++ trunk/tools/build/v2/doc/src/tutorial.xml 2009-08-22 04:42:34 EDT (Sat, 22 Aug 2009)
@@ -285,7 +285,7 @@
information</para>
</footnote>
More details can be found in
- <xref linkend= "bbv2.advanced.projects"/>.
+ <xref linkend= "bbv2.overview.projects"/>.
</para>
<para>
Modified: trunk/tools/build/v2/doc/src/userman.xml
==============================================================================
--- trunk/tools/build/v2/doc/src/userman.xml (original)
+++ trunk/tools/build/v2/doc/src/userman.xml 2009-08-22 04:42:34 EDT (Sat, 22 Aug 2009)
@@ -11,7 +11,7 @@
<xi:include href="howto.xml"/>
<xi:include href="install.xml"/>
<xi:include href="tutorial.xml"/>
- <xi:include href="advanced.xml"/>
+ <xi:include href="overview.xml"/>
<xi:include href="tasks.xml"/>
<xi:include href="reference.xml"/>
<xi:include href="extending.xml"/>
Modified: trunk/tools/build/v2/doc/src/v1_vs_v2.xml
==============================================================================
--- trunk/tools/build/v2/doc/src/v1_vs_v2.xml (original)
+++ trunk/tools/build/v2/doc/src/v1_vs_v2.xml 2009-08-22 04:42:34 EDT (Sat, 22 Aug 2009)
@@ -16,7 +16,7 @@
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">
+ <section id="bbv2.overview.differences_to_v1.configuration">
<title>Configuration</title>
<para>In V1, toolsets were configured by environment variables. If you
@@ -25,12 +25,12 @@
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.
+ linkend="bbv2.overview.configuration"/> for details.
</para>
</section>
- <section id="bbv2.advanced.differences_to_v1.jamfiles">
+ <section id="bbv2.overview.differences_to_v1.jamfiles">
<title>Writing Jamfiles</title>
<para>Probably one of the most important differences in V2 Jamfiles is
@@ -38,7 +38,7 @@
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"/>.
+ attribute, as documented in <xref linkend="bbv2.overview.projects"/>.
</para>
<para><link linkend="bbv2.tutorial.libs">Usage requirements</link>
@@ -54,7 +54,7 @@
<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><link></varname>
+ <link linkend="bbv2.overview.builtins.features.link"><varname><link></varname>
feature</link>. If your target should be only built in one way<!--"variant" has a different meaning here-->, you
can add <code><link>shared</code> or <code><link>static</code> to its requirements.
</para>
@@ -77,7 +77,7 @@
</section>
- <section id="bbv2.advanced.differences_to_v1.build_process">
+ <section id="bbv2.overview.differences_to_v1.build_process">
<title>Build process</title>
<para>The command line syntax in V2 is completely different. For example
@@ -92,7 +92,7 @@
<programlisting>
bjam msvc release some_target
</programlisting>
- See <link linkend="bbv2.advanced.invocation">the reference</link> for a
+ See <link linkend="bbv2.overview.invocation">the reference</link> for a
complete description of the syntax.
</para>