WSJT-X/boost/tools/build/doc/src/tasks.xml

<?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">

<!-- Copyright 2006 Vladimir Prus -->
<!-- Distributed under the Boost Software License, Version 1.0. -->
<!-- (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt) -->

<chapter id="bbv2.tasks">
  <title>Common tasks</title>

  <para>
    This section describes main targets types that Boost.Build supports
    out-of-the-box. Unless otherwise noted, all mentioned main target rules have
    the common signature, described in <xref linkend="bbv2.overview.targets"/>.
  </para>

  <section id="bbv2.tasks.programs">
    <title>Programs</title>

    <indexterm><primary>exe</primary></indexterm>
    <para>
      Programs are created using the <code>exe</code> rule, which follows the
      <link linkend="bbv2.main-target-rule-syntax">common syntax</link>. For
      example:
<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&mdash;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 shared libraries, and both the
        application and the libraries are built using Boost.Build, it is not
        possible to immediately run the application, because the <literal>PATH
        </literal> environment variable should include the path to the
        libraries. It means you have to either add the paths manually, or have
        the build place the application and the libraries into the same
        directory. See <xref linkend="bbv2.tasks.installing"/>.
      </para>
      <!-- We should be emphasizing the use of the built-in testing rules
           rather than continually discussing these quirks of running programs
           with shared libraries. -->
    </tip>
  </section>

  <section id="bbv2.tasks.libraries">
    <title>Libraries</title>

    <indexterm>
      <primary>library</primary>
      <secondary>target</secondary>
    </indexterm>

    <para>
      Library targets are created using the <code>lib</code> rule, which
      follows the <link linkend="bbv2.main-target-rule-syntax">common syntax
      </link>. For example:
<programlisting>
lib helpers : helpers.cpp ;
</programlisting>
      This will define a library target named <code>helpers</code> built from
      the <code>helpers.cpp</code> source file.
      It can be either a static library or a shared library,
      depending on the value of the <link linkend="bbv2.overview.builtins.features.link">&lt;link&gt;</link> feature.
    </para>
    <para>
      Library targets can represent:
      <itemizedlist>
        <listitem>
          <para>
            Libraries that should be built from source,
            as in the example above.
          </para>
        </listitem>
        <listitem>
          <para>
            Prebuilt libraries which already exist on the system.
            Such libraries can be searched for by the tools using them (typically
            with the linker's <option>-l</option> option) or their paths can be
            known in advance by the build system.
          </para>
        </listitem>
      </itemizedlist>
    </para>

    <para>
      The syntax for prebuilt libraries 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 of the library
      without the standard prefixes and suffixes.  For example, depending
      on the system, <code>z</code> could refer to a file called
      z.so, libz.a, or z.lib, etc.  The <code>search</code> feature
      specifies paths in which to search for the library in addition
      to the default compiler paths. <code>search</code> can be specified
      several times or it can be omitted, in which case only the default
      compiler paths will be searched. The <code>file</code> property
      specifies the file location.
    </para>

    <para>
      The difference between using the <code>file</code> feature and
      using a combination of the <code>name</code> and <code>search</code>
      features is that <code>file</code> is more precise.
      
      <warning>
        <para>
          The value of the <code>search</code> feature is just added to the
          linker search path.  When linking to multiple libraries,
          the paths specified by <code>search</code> are combined without
          regard to which <code>lib</code> target each path came from.
          Thus, given
<programlisting>
lib a : : &lt;name&gt;a &lt;search&gt;/pool/release ;
lib b : : &lt;name&gt;b &lt;search&gt;/pool/debug ;
</programlisting>
          If /pool/release/a.so, /pool/release/b.so, /pool/debug/a.so,
          and /pool/release/b.so all exist, the linker will probably
          take both <code>a</code> and <code>b</code> from the same
          directory, instead of finding <code>a</code> in /pool/release
          and <code>b</code> in /pool/debug.  If you need to distinguish
          between multiple libraries with the same name, it's safer
          to use <code>file</code>.
        </para>
      </warning>
    </para>

    <para>
      For convenience, the following syntax is allowed:
<programlisting>
lib z ;
lib gui db aux ;
</programlisting>
      which has exactly the same effect 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 references another library you should put that other
      library in its list of sources. This will do the right thing in all cases.
      <!--Add a link to the notes below. --> For portability, you should specify
      library dependencies even for searched and prebuilt libraries, othewise,
      static linking on Unix will not work. For example:
<programlisting>
lib z ;
lib png : z : &lt;name&gt;png ;
</programlisting>
    </para>

    <note>
      <para>
        When a library has a shared library as a source, or a static
        library has another static library as a source then any target
        linking to the first library with automatically link to its source
        library as well.
      </para>
      <para>
        On the other hand, when a shared library has a static library as
        a source then the first library will be built so that it completely
        includes the second one.
      </para>
      <para>
        If you do not want a shared library to include all the libraries specified
        in its sources (especially statically linked ones), you would need to
        use the following:
<programlisting>
lib b : a.cpp ;
lib a : a.cpp : &lt;use&gt;b : : &lt;library&gt;b ;
</programlisting>
        This specifies that library <code>a</code> uses library <code>b</code>,
        and causes all executables that link to <code>a</code> to link to
        <code>b</code> also. In this case, even for shared linking, the
        <code>a</code> library will not refer to <code>b</code>.
      </para>
    </note>

    <para>
      <!-- FIXME: After adding a full subsection on usage requirements, link to it  -->
      <link linkend="bbv2.overview.targets">Usage requirements</link> are often
      very useful for defining library targets. For example, imagine that
      you want you build a <code>helpers</code> library and its interface is
      described in its <code>helpers.hpp</code> header file located in the same
      directory as the <code>helpers.cpp</code> source file. Then you could add
      the following to the Jamfile located in that same directory:
<programlisting>
lib helpers : helpers.cpp : : : &lt;include&gt;. ;
</programlisting>
      which would automatically add the directory where the target has been
      defined (and where the library's header file is located) to the compiler's
      include path for all targets using the <code>helpers</code> library. This
      feature greatly simplifies Jamfiles.
    </para>
  </section>

  <section id="bbv2.tasks.alias">
    <title>Alias</title>

    <para>
      The <code language="jam">alias</code> rule gives an alternative name to a
      group of targets. For example, to give the name <filename>core</filename>
      to a group of three other targets with the following code:
<programlisting>
alias core : im reader writer ;
</programlisting>
      Using <filename>core</filename> on the command line, or in the source list
      of any other target is the same as explicitly using <filename>im
      </filename>, <filename>reader</filename>, and <filename>writer</filename>.
    </para>

    <para>
      Another use of the <code>alias</code> rule is to change build properties.
      For example, if you want to use link statically to the Boost Threads
      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.
    </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 an alias has sources, their usage
      requirements are propagated as well. For example:
<programlisting>
lib library1 : library1.cpp : : : &lt;include&gt;/library/include1 ;
lib library2 : library2.cpp : : : &lt;include&gt;/library/include2 ;
alias static_libraries : library1 library2 : &lt;link&gt;static ;
exe main : main.cpp static_libraries ;
</programlisting>
      will compile <filename>main.cpp</filename> with additional includes
      required for using the specified static libraries.
    </para>
  </section>

  <section id="bbv2.tasks.installing">
    <title>Installing</title>

    <para>
      This section describes various ways to install built target and arbitrary
      files.
    </para>

    <bridgehead>Basic install</bridgehead>

    <para>
      For installing a built target you should use the <code>install</code>
      rule, which follows the <link linkend="bbv2.main-target-rule-syntax">
      common syntax</link>. For example:
<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 the
      Jamfile's directory. The directory can be changed using 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 as it allows you to use a mnemonic target name.
    </para>

    <para>
      The <code>location</code> property is especially handy when the location
      is not fixed, but depends on the 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>

    <bridgehead>Installing with all dependencies</bridgehead>

    <para>
      Specifying the names of all libraries to install can be boring. The
      <code>install</code> allows you to specify only the top-level executable
      targets to install, and automatically install all dependencies:
<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, as that feature is
      typically used to refer to header-only libraries. If the set of target
      types is specified, only targets of that type will be installed,
      otherwise, all found target will be installed.
    </para>

    <bridgehead>Preserving Directory Hierarchy</bridgehead>

    <indexterm><primary>install-source-root</primary></indexterm>

    <para>
      By default, the <code>install</code> rule will strip paths from its
      sources. So, if sources include <filename>a/b/c.hpp</filename>, the
      <filename>a/b</filename> part will be ignored. To make the
      <code>install</code> rule preserve the directory hierarchy you need to
      use the <literal>&lt;install-source-root&gt;</literal> feature to specify
      the root of the hierarchy you are installing. Relative paths from that
      root will be preserved. For example, if you write:
<programlisting>
install headers
    : a/b/c.h
    : &lt;location&gt;/tmp &lt;install-source-root&gt;a
    ;
</programlisting>
      the a file named <filename>/tmp/b/c.h</filename> will be created.
    </para>

    <para>
      The <link linkend="bbv2.reference.glob-tree">glob-tree</link> rule can be
      used to find all files below a given directory, making it easy to install
      an entire directory tree.
    </para>

    <bridgehead>Installing into Several Directories</bridgehead>

    <para>
      The <link linkend="bbv2.tasks.alias"><code>alias</code></link> rule can be
      used when targets need to be installed into several directories:
<programlisting>
alias install : install-bin install-lib ;
install install-bin : applications : /usr/bin ;
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 that matter are <link linkend="bbv2.builtin.features.dependency">
      <varname>dependency</varname></link> and, on Unix, <link
      linkend="bbv2.reference.features.dll-path"><varname>dll-path</varname>
      </link>.
    </para>

    <note>
      <para>
        (Unix specific) On Unix, executables built using Boost.Build typically
        contain the list of paths to all used shared libraries. For installing,
        this is not desired, so Boost.Build relinks the executable with an empty
        list of paths. You can also specify additional paths for installed
        executables using 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 <code language="jam">unit-test</code> rule behaves like the
      <link linkend="bbv2.tasks.programs">exe</link> rule, but after the executable is created
      it is also run. If the executable returns an error code, the build system
      will also return an error and will try running the executable on the next
      invocation until it runs successfully. This behaviour ensures that you can
      not miss a unit test failure.
    </para>


    <para>
       There are few specialized testing rules, listed below:
<programlisting>
rule compile ( sources : requirements * : target-name ? )
rule compile-fail ( sources : requirements * : target-name ? )
rule link ( sources + : requirements * : target-name ? )
rule link-fail ( sources + : requirements * : target-name ? )
</programlisting>
      They are given a list of sources and requirements. If the target name is
      not provided, the name of the first source file is used instead. The
      <literal>compile*</literal> tests try to compile the passed source. The
      <literal>link*</literal> rules try to compile and link an application from
      all the passed sources. The <literal>compile</literal> and <literal>link
      </literal> rules expect that compilation/linking succeeds. The <literal>
      compile-fail</literal> and <literal>link-fail</literal> rules expect that
      the compilation/linking fails.
    </para>

    <para>
      There are two specialized rules for running applications, which are more
      powerful than the <code>unit-test</code> rule. The <code>run</code> rule
      has the following signature:
<programlisting>
rule run ( sources + : args * : input-files * : requirements * : target-name ?
    : default-build * )
</programlisting>
      The rule builds application from the provided sources and runs it, passing
      <varname>args</varname> and <varname>input-files</varname> as command-line
      arguments. The <varname>args</varname> parameter is passed verbatim and
      the values of the <varname>input-files</varname> parameter are treated as
      paths relative to containing Jamfile, and are adjusted if <command>b2</command> 
      is invoked from a different directory. The
      <code>run-fail</code> rule is identical to the <code>run</code> rule,
      except that it expects that the run fails.
    </para>

    <para>
      All rules described in this section, if executed successfully, create a
      special manifest file to indicate that the test passed. For the
      <code>unit-test</code> rule the files is named <filename><replaceable>
      target-name</replaceable>.passed</filename> and for the other rules it is
      called <filename><replaceable>target-name</replaceable>.test</filename>.
      The <code>run*</code> rules also capture all output from the program, and
      store it in a file named <filename><replaceable>
      target-name</replaceable>.output</filename>.
    </para>

    <para>
      <indexterm><primary>preserve-test-targets</primary></indexterm>
      If the <literal>preserve-test-targets</literal> feature has the value
      <literal>off</literal>, then <code>run</code> and the <code>run-fail</code>
      rules will remove the executable after running it.  This somewhat decreases
      disk space requirements for continuous testing environments. The default 
      value of <literal>preserve-test-targets</literal> feature is <literal>on</literal>.      
    </para>

    <para>
      It is possible to print the list of all test targets (except for
      <code>unit-test</code>) declared in your project, by passing the <literal>
      --dump-tests</literal> command-line option. The output will consist of
      lines of the form:
<screen>
boost-test(<replaceable>test-type</replaceable>) <replaceable>path</replaceable> : <replaceable>sources</replaceable>
</screen>
    </para>

    <para>
      It is possible to process the list of tests, Boost.Build output
      and the presense/absense of the <filename>*.test</filename>
      files created when test passes into human-readable status table of tests.
      Such processing utilities are not included in Boost.Build.
    </para>

    <para>The following features adjust behaviour of the testing metatargets.</para>

    <variablelist>
      <varlistentry>
        <term><literal>testing.arg</literal></term>
        <indexterm><primary>testing.arg</primary></indexterm>

        <listitem>
          <para>
            Defines an argument to be passed to the target when it is executed
            before the list of input files.
          </para>

          <para>
<programlisting>
unit-test helpers_test
  : helpers_test.cpp helpers
  : <emphasis role="bold">&lt;testing.arg&gt;"--foo bar"</emphasis>
  ;
</programlisting>
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>testing.input-file</literal></term>
        <indexterm><primary>testing.input-file</primary></indexterm>

        <listitem>
          <para>
            Specifies a file to be passed to the executable on the command line
            after the arguments. All files must be specified in alphabetical
            order due to constrainsts in the current implementation.
          </para>

        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>testing.launcher</literal></term>
        <indexterm><primary>testing.launcher</primary></indexterm>

        <listitem>
          <para>
            By default, the executable is run directly. Sometimes, it is
            desirable to run the executable using some helper command. You
            should use this property to specify the name of the helper
            command. For example, if you write:
<programlisting>
unit-test helpers_test
  : helpers_test.cpp helpers
  : <emphasis role="bold">&lt;testing.launcher&gt;valgrind</emphasis>
  ;
</programlisting>
            The command used to run the executable will be:
<screen>
<emphasis role="bold">valgrind</emphasis> bin/$toolset/debug/helpers_test
</screen>
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>test-info</literal></term>
        <indexterm><primary>test-info</primary></indexterm>

        <listitem>
          <para>
            A description of the test. This is displayed as part of the
            <literal>--dump-tests</literal> command-line option.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>
  </section>

  <section id="bbv2.builtins.raw">
    <title>Custom commands</title>

    <para>
      For most main target rules, Boost.Build automatically figures out
      the commands to run.  When you want to use new
      file types or support new tools, one approach is to extend Boost.Build to
      support them smoothly, as documented in <xref linkend="bbv2.extender"/>.
      However, if the new tool is only used in a single place, it
      might be easier just to specify the commands to run explicitly.
    </para>

    <para>
      <!-- This paragraph requires links to where the terms 'virtual target' &
      'target' are defined. -->
      Three main target rules can be used for that. The <code language="jam">make
      </code> rule allows you to construct a single file from any number
      of source file, by running a command you specify. The <code language="jam">
      notfile</code> rule allows you to run an arbitrary command,
      without creating any files. And finaly, the <code language="jam">generate
      </code> rule allows you to describe a transformation using
      Boost.Build's virtual targets. This is higher-level than the file names that
      the <code language="jam">make</code> rule operates with and allows you to
      create more than one target, create differently named targets depending on
      properties, or use more than one tool.
    </para>

    <para>
      The <code language="jam">make</code> rule is used when you want to create
      one file from a number of sources using some specific command. The
      <code language="jam">notfile</code> is used to unconditionally run a
      command.
    </para>

    <!-- We need to specify somewhere that the user can get rules like make,
    notfile & generate defined in his Jamfiles by importing an appropriate
    Boost.Build module. Also, each of those rules should get a separate
    documentation page explicitly listing which module needs to be imported for
    them to become accessible. -->

    <para>
      Suppose you want to create the file <filename>file.out</filename> from
      the file <filename>file.in</filename> by running the command <command>
      in2out</command>. Here is how you would do this in Boost.Build:
<programlisting>
make file.out : file.in : @in2out ;
actions in2out
{
    in2out $(&lt;) $(&gt;)
}
</programlisting>
      If you run <command>b2</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.overview.jam_language.actions"/>.
    </para>

    <para>
      It could be that you just want to run some command unconditionally, and
      that command does not create any specific files. For that you can use the
      <code language="jam">notfile</code> rule. For example:
<programlisting>
notfile echo_something : @echo ;
actions echo
{
    echo "something"
}
</programlisting>
      The only difference from the <code language="jam">make</code> rule is
      that the name of the target is not considered a name of a file, so
      Boost.Build will unconditionally run the action.
    </para>

    <para>
      <!-- This paragraph requires links to where terms like 'virtual target',
      'target', 'project-target' & 'property-set' are defined. -->
      The <code language="jam">generate</code> rule is used when you want to
      express transformations using Boost.Build's virtual targets, as opposed to
      just filenames. The <code language="jam">generate</code> rule has the
      standard main target rule signature, but you are required to specify the
      <literal>generating-rule</literal> property. The value of the property
      should be in the form <literal>
      @<replaceable>rule-name</replaceable></literal>, the named rule should
      have the following signature:
<programlisting>
rule generating-rule ( project name : property-set : sources * )
</programlisting>
      and will be called with an instance of the <code>project-target</code>
      class, the name of the main target, an instance of the
      <code>property-set</code> class containing build properties, and the list
      of instances of the <code>virtual-target</code> class corresponding to
      sources. The rule must return a list of <code>virtual-target</code>
      instances. The interface of the <code>virtual-target</code> class can be
      learned by looking at the <filename>build/virtual-target.jam</filename>
      file. The <filename>generate</filename> example contained in the
      Boost.Build distribution illustrates how the <literal>generate</literal>
      rule can be used.
    </para>
  </section>

  <section id="bbv2.reference.precompiled_headers">
    <title>Precompiled Headers</title>

    <para>
      Precompiled headers is a mechanism to speed up compilation by creating a
      partially processed version of some header files, and then using that
      version during compilations rather then repeatedly parsing the original
      headers. Boost.Build supports precompiled headers with gcc and msvc
      toolsets.
    </para>

    <para>
      To use precompiled headers, follow the following steps:
    </para>

    <orderedlist>
      <listitem>
        <para>
          Create a header that includes headers used by your project that you
          want precompiled. It is better to include only headers that are
          sufficiently stable &#x2014; like headers from the compiler and
          external libraries. Please wrap the header in <code>#ifdef
          BOOST_BUILD_PCH_ENABLED</code>, so that the potentially expensive
          inclusion of headers is not done when PCH is not enabled. Include the
          new header at the top of your source files.
        </para>
      </listitem>

      <listitem>
        <para>
          Declare a new Boost.Build target for the precompiled header and add
          that precompiled header to the sources of the target whose compilation
          you want to speed up:
<programlisting>
cpp-pch pch : pch.hpp ;
exe main : main.cpp pch ;
</programlisting>
          You can use the <code language="jam">c-pch</code> rule if you want to
          use the precompiled header in C programs.
        </para></listitem>
    </orderedlist>

    <para>
      The <filename>pch</filename> example in Boost.Build distribution can be
      used as reference.
    </para>

    <para>
      Please note the following:
    </para>

    <itemizedlist>
      <listitem>
        <para>
          The inclusion of the precompiled header must be the first thing in a
          source file, before any code or preprocessor directives.
        </para>
      </listitem>

      <listitem>
        <para>
          The build properties used to compile the source files and the
          precompiled header must be the same. Consider using project
          requirements to assure this.
        </para>
      </listitem>

      <listitem>
        <para>
          Precompiled headers must be used purely as a way to improve
          compilation time, not to save the number of <code>#include</code>
          statements. If a source file needs to include some header, explicitly
          include it in the source file, even if the same header is included
          from the precompiled header. This makes sure that your project will
          build even if precompiled headers are not supported.
        </para>
      </listitem>

      <listitem>
        <para>
          On the gcc compiler, the name of the header being precompiled must be
          equal to the name of the <code>cpp-pch</code> target. This is a gcc
          requirement.
        </para>
      </listitem>

      <listitem>
        <para>
          Prior to version 4.2, the gcc compiler did not allow anonymous
          namespaces in precompiled headers, which limits their utility. See the
          <ulink url="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=29085"> bug
          report</ulink> for details.
        </para>
      </listitem>
    </itemizedlist>
  </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 be added to the include
      path.
    </para>

    <para>
      Making this mechanism work across main target boundaries is possible, but
      imposes certain overhead. For that reason, if there is implicit dependency
      on files from other main targets, the <literal>&lt;implicit-dependency&gt;
      </literal> feature must be used, for example:
<programlisting>
lib parser : parser.y ;
exe app : app.cpp : &lt;implicit-dependency&gt;parser ;
</programlisting>
      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.tasks.crosscompile">
    <title>Cross-compilation</title>

    <indexterm><primary>cross compilation</primary></indexterm>

    <para>Boost.Build supports cross compilation with the gcc and msvc
    toolsets.</para>
    
    <para>
      When using gcc, you first need to specify your cross compiler
      in <filename>user-config.jam</filename> (see <xref linkend="bbv2.overview.configuration"/>), 
      for example:</para>
<programlisting>
using gcc : arm : arm-none-linux-gnueabi-g++ ;
</programlisting>
    <para>
      After that, if the host and target os are the same, for example Linux, you can
      just request that this compiler version be used:
    </para>
<screen>
b2 toolset=gcc-arm
</screen>

    <para>
      If you want to target a different operating system from the host, you need
      to additionally specify the value for the <code>target-os</code> feature, for
      example:
    </para>
<screen>
# On windows box
b2 toolset=gcc-arm <emphasis role="bold">target-os=linux</emphasis>
# On Linux box
b2 toolset=gcc-mingw <emphasis role="bold">target-os=windows</emphasis>
</screen>
    <para>
      For the complete list of allowed opeating system names, please see the documentation for 
      <link linkend="bbv2.reference.features.target-os">target-os feature</link>.
    </para>

    <para>
      When using the msvc compiler, it's only possible to cross-compile to a 64-bit system
      on a 32-bit host. Please see <xref linkend="v2.reference.tools.compiler.msvc.64"/> for
      details.
    </para>
         
  </section>

</chapter>

<!--
     Local Variables:
     mode: nxml
     sgml-indent-data: t
     sgml-parent-document: ("userman.xml" "chapter")
     sgml-set-face: t
     End:
-->