<?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.advanced.targets"/>.
  </para>

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

      <indexterm><primary>exe</primary></indexterm>
      <para>Programs are created using the <code>exe</code> rule, which follows
        the <link linkend="bbv2.main-target-rule-syntax">common syntax</link>.
        For example:
<programlisting>
exe hello : hello.cpp some_library.lib /some_project//library
          : &lt;threading&gt;multi
          ;
</programlisting>
        This will create an executable file from the sources -- in this case,
        one C++ file, one library file present in the same directory, and
        another library that is created by Boost.Build. Generally, sources
        can include C and C++ files, object files and libraries. Boost.Build
        will automatically try to convert targets of other types.
      </para>

      <tip>
        <para>
          On Windows, if an application uses dynamic libraries, and both
          the application and the libraries are built by Boost.Build, its not
          possible to immediately run the application, because the
          <literal>PATH</literal> environment variable should include the path
          to the libraries. It means you have to either add the paths
          manually, or place the application and the libraries to the same
          directory. See <xref linkend="bbv2.tasks.installing"/>.
        </para>
        <!-- We should be emphasizing the use of the built-in testing rules
             rather than continually discussing these quirks of running programs
             with dynamic libraries. -->
      </tip>
    </section>

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

      <para>Libraries are created using the <code>lib</code> rule, which
        follows the <link linkend="bbv2.main-target-rule-syntax">common
        syntax</link>. For example:
<programlisting>
lib helpers : helpers.cpp : &lt;include&gt;boost : : &lt;include&gt;. ;
</programlisting>
      </para>
      <!-- Add one sentence that says what the above does. -->
      <para>
        In the most common case, the <code>lib</code> creates a library from the
        specified sources. Depending on the value of &lt;link&gt; feature the
        library will be either static or shared. There are two other cases.
        First is when the library is installed somewhere in compiler's search
        paths, and should be searched by the compiler (typically, using the
        <option>-l</option> option). The second case is where the library is
        available as a prebuilt file and the full path is known.
        <!-- But the first case is also prebuilt.  This is confusingly phrased. -->
      </para>

      <para>
        The syntax for these case is given below:
<programlisting>
lib z : : &lt;name&gt;z &lt;search&gt;/home/ghost ;
lib compress : : &lt;file&gt;/opt/libs/compress.a ;
</programlisting>
        The <code>name</code> property specifies the name that should be
        passed to the <option>-l</option> option, and the <code>file</code>
        property specifies the file location. The <varname>search</varname> feature
        specifies paths in which to search for the library. That feature can
        be specified several times, or it can be omitted, in which case only
        default compiler paths will be searched.
      </para>

      <para>The difference between using the <varname>file</varname> feature as
        opposed to the <varname>name</varname> feature together with the
        <varname>search</varname> feature is that <varname>file</varname> is more
        precise. A specific file will be used. On the other hand, the
        <varname>search</varname> feature only adds a library path, and the
        <varname>name</varname> feature gives the basic name of the library. The
        search rules are specific to the linker. For example, given these
        definition:
<programlisting>
lib a : : &lt;variant&gt;release &lt;file&gt;/pool/release/a.so ;
lib a : : &lt;variant&gt;debug &lt;file&gt;/pool/debug/a.so ;
lib b : : &lt;variant&gt;release &lt;file&gt;/pool/release/b.so ;
lib b : : &lt;variant&gt;debug &lt;file&gt;/pool/debug/b.so ;
</programlisting>
        It's possible to use release version of <code>a</code> and debug
        version of <code>b</code>. Had we used the <varname>name</varname> and
        <varname>search</varname> features, the linker would always pick either
        release or debug versions.
        <!-- explain -->
      </para>

      <para>
        For convenience, the following syntax is allowed:
<programlisting>
lib z ;
lib gui db aux ;
</programlisting>
          and is does exactly the same as:
<programlisting>
lib z : : &lt;name&gt;z ;
lib gui : : &lt;name&gt;gui ;
lib db : : &lt;name&gt;db ;
lib aux : : &lt;name&gt;aux ;
</programlisting>
      </para>

      <para>
        When a library uses another library you should put that other library in
        the list of sources. This will do the right thing in all cases. For
        portability, you should specify library dependencies even for searched
        and prebuilt libraries, othewise, static linking on Unix will not work.
        For example:
<programlisting>
lib z ;
lib png : z : &lt;name&gt;png ;
</programlisting>
        </para>

      <note>
        <para>
          When a library (say, <code>a</code>), that has another library, (say,
          <code>b</code>)
          <!-- how can a library "have" a library? -->
          is linked dynamically, the <code>b</code>
          library will be incorporated
          <!-- Incorporated?  Be precise. -->
          in <code>a</code>. (If <code>b</code>
          is dynamic library as well, then <code>a</code> will only refer to it,
          and not include any extra code.)
          <!-- Don't parenthesize a whole sentence. -->
          When the <code>a</code>
          library is linked statically, Boost.Build will assure that all
          executables that link to <code>a</code> will also link to
          <code>b</code>.
        </para>
      </note>

      <para>
        One feature of Boost.Build that is very important for libraries is usage
        requirements.
        <!-- Rephrase that.  But then, it's much too late for an
             introduction of usage requirements - you've already
             discussed them many times. -->
        For example, if you write:
<programlisting>
lib helpers : helpers.cpp : : : &lt;include&gt;. ;
</programlisting>
        then the compiler include path for all targets that use
        <code>helpers</code> will contain the directory
        <!-- The rest of this sentence is unintelligible -->
        where the target is defined.path to "helpers.cpp". The user
        only needs to add <code>helpers</code> to the list of sources,
        and needn't consider the requirements its use imposes on a
        dependent target. This feature greatly simplifies Jamfiles.
        <!-- You can't say “allows to”—you need a noun.  This error is
             repeated throughout. -->
      </para>

      <note>
        <para>If you don't want shared libraries to include all libraries
          that are specified in sources (especially statically linked ones),
          you'd need to use the following:
<programlisting>
lib b : a.cpp ;
lib a : a.cpp : &lt;use&gt;b : : &lt;library&gt;b ;
</programlisting>
          This specifies that <code>a</code> uses <code>b</code>, and causes
          all executables that link to <code>a</code> also link to
          <code>b</code>. In this case, even for shared linking, the
          <code>a</code> library won't even refer to <code>b</code>.
        </para>
      </note>

    </section>

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

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


      <para>
        Another use of the <code>alias</code> rule is to change build
        properties. For example, if you always want static linking for a
        specific C++ Boost library, you can write the following:
<programlisting>
alias threads : /boost/thread//boost_thread : &lt;link&gt;static ;
</programlisting>
        and use only the <code>threads</code> alias in your Jamfiles.
      </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
        Jamfile's directory. The directory can
        be changed with the <code>location</code> property:
<programlisting>
install dist : hello helpers : &lt;location&gt;/usr/bin ;
</programlisting>
        While you can achieve the same effect by changing the target name to
        <filename>/usr/bin</filename>, using the <code>location</code>
        property is better, because it allows you to use a mnemonic target
        name.
      </para>

      <para>The <code>location</code> property is especially handy when the location
        is not fixed, but depends on build variant or environment variables:
<programlisting>
install dist : hello helpers : &lt;variant&gt;release:&lt;location&gt;dist/release
                             &lt;variant&gt;debug:&lt;location&gt;dist/debug ;
install dist2 : hello helpers : &lt;location&gt;$(DIST) ;
</programlisting>
        See also <link linkend="bbv2.reference.variants.propcond">conditional
          properties</link> and <link linkend="bbv2.faq.envar">environment variables</link>
      </para>

      <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, because that feature is typically used to refer to
        header-only libraries.
        If the set of target types is specified, only targets of that type
        will be installed, otherwise, all found target will be installed.
      </para>

      <bridgehead>Preserving Directory Hierarchy</bridgehead>

      <indexterm><primary>install-source-root</primary></indexterm>
      <para>By default, the <code>install</code> rules will stip paths from
      it's sources. So, if sources include <filename>a/b/c.hpp</filename>,
      the <filename>a/b</filename> part will be ignored. To make the
      <code>install</code> rule preserve the directory hierarchy you need
      to use the <code>install-source-root</code> feature to specify the
      root of the hierarchy you are installing. Relative paths from that
      root will be preserved. For example, if you write:

<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 entire directory tree.</para>

      <bridgehead>Installing into Several Directories</bridgehead>

      <para>The <link linkend="bbv2.tasks.alias"><code>alias</code></link>
      rule can be used when targets must be installed into several
      directories:
<programlisting>
alias install : install-bin install-lib ;
install install-bin : applications : /usr/bin ;
install install-lib : helper : /usr/lib ;
</programlisting>
    </para>

    <para>
      Because the <code>install</code> rule just copies targets, most free
      features <footnote><para>see the definition of "free" in
      <xref linkend="bbv2.reference.features.attributes"/>.</para></footnote>
      have no effect when used in requirements of the <code>install</code> rule.
      The only two which matter are <link
      linkend="bbv2.builtin.features.dependency"><varname>dependency</varname>
      </link> and, on Unix, <link linkend="bbv2.reference.features.dll-path">
      <varname>dll-path</varname></link>.
    </para>

    <note>
      <para>
        (Unix specific). On Unix, executables built with Boost.Build typically
        contain the list of paths to all used dynamic libraries. For installing,
        this is not desired, so Boost.Build relinks the executable with an empty
        list of paths. You can also specify additional paths for installed
        executables with the <varname>dll-path</varname> feature.
      </para>
    </note>

    </section>

    <section id="bbv2.builtins.testing">

      <title>Testing</title>

      <para>
        Boost.Build has convenient support for running unit tests. The simplest
        way is the <code>unit-test</code> rule, which follows the <link
        linkend="bbv2.main-target-rule-syntax">common syntax</link>. For
        example:
<programlisting>
unit-test helpers_test : helpers_test.cpp helpers ;
</programlisting>
      </para>

      <para>The <functionname>unit-test</functionname> rule behaves like the
        <functionname>exe</functionname> rule, but after the executable is created it is
        run. If the executable returns an error code, the build system will also
        return an error and will try running the executable on the next
        invocation until it runs successfully. This behaviour ensures that you
        can't miss a unit test failure.
      </para>

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

      <para>There are few specialized testing rules, listed below:
      <programlisting>
rule compile ( sources : requirements * : target-name ? )
rule compile-fail ( sources : requirements * : target-name ? )
rule link ( sources + : requirements * : target-name ? )
rule link-fail ( sources + : requirements * : target-name ? )
      </programlisting>
      They are are given a list of sources and requirements.
      If the target name is not provided, the name of the first
      source file is used instead. The <literal>compile*</literal>
      tests try to compile the passed source. The <literal>link*</literal>
      rules try to compile and link an application from all the passed sources.
      The <literal>compile</literal> and <literal>link</literal> rules expect
      that compilation/linking succeeds. The <literal>compile-fail</literal>
      and <literal>link-fail</literal> rules, on the opposite, expect that
      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>bjam</command> is invoked from a different
      directory. The <code>run-fail</code> rule is identical to the
      <code>run</code> rule, except that it expects that the run fails.
      </para>

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

      <para>The <code>run</code> and the <code>run-fail</code> rules, if
      the test passes, automatically delete the linked executable, to
      save space. This behaviour can be suppressed by passing the
      <literal>--preserve-test-targets</literal> command line option.</para>

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

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

    </section>

    <section id="bbv2.builtins.raw">

      <title>Custom commands</title>

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

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

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

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

      <para>
        Suppose you want to create file <filename>file.out</filename> from file
        <filename>file.in</filename> by running command
        <command>in2out</command>. Here is how you would do this in Boost.Build:
<programlisting>
make file.out : file.in : @in2out ;
actions in2out
{
    in2out $(&lt;) $(&gt;)
}
</programlisting>
        If you run <command>bjam</command> and <filename>file.out</filename>
        does not exist, Boost.Build will run the <command>in2out</command>
        command to create that file. For more details on specifying actions, see
        <xref linkend="bbv2.advanced.jam_language.actions"/>.
      </para>

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

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

    </section>

    <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 <functionname>c-pch</functionname> 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 added to include
        path.</para>

      <para>Making this mechanism work across main target boundaries is
        possible, but imposes certain overhead. For that reason, if
        there's implicit dependency on files from other main targets, the
        <literal>&lt;implicit-dependency&gt;</literal> [ link ] feature must
        be used, for example:</para>

<programlisting>
lib parser : parser.y ;
exe app : app.cpp : &lt;implicit-dependency&gt;parser ;
</programlisting>

      <para>
        The above example tells the build system that when scanning
        all sources of "app" for implicit-dependencies, it should consider
        targets from "parser" as potential dependencies.
      </para>
</section>

</chapter>


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