build/v2/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">

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

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

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

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

    <section>
      <title>Libraries</title>

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

      <para>The difference between using the <varname>file</varname> feature as
        opposed to the <varname>name</varname> feature together with the
        <varname>search</varname> feature is that <varname>file</varname> is more
        precise. A specific file will be used. On the other hand, the
        <varname>search</varname> feature only adds a library path, and the
        <varname>name</varname> feature gives the basic name of the library. The
        search rules are specific to the linker. For example, given these
        definition:
<programlisting>
lib a : : &lt;variant&gt;release &lt;file&gt;/pool/release/a.so ;
lib a : : &lt;variant&gt;debug &lt;file&gt;/pool/debug/a.so ;
lib b : : &lt;variant&gt;release &lt;file&gt;/pool/release/b.so ;
lib b : : &lt;variant&gt;debug &lt;file&gt;/pool/debug/b.so ;
</programlisting>
        It's possible to use release version of <code>a</code> and debug
        version of <code>b</code>. Had we used the <varname>name</varname> and
        <varname>search</varname> features, the linker would always pick either
        release or debug versions.
        <!-- explain -->
      </para>
      
      <para>
        For convenience, the following syntax is allowed:
<programlisting>
lib z ;
lib gui db aux ;
</programlisting>
          and is does exactly the same as:
<programlisting>
lib z : : &lt;name&gt;z ;            
lib gui : : &lt;name&gt;gui ;            
lib db : : &lt;name&gt;db ;            
lib aux : : &lt;name&gt;aux ;            
</programlisting>
      </para>
          
      <para>When a library uses another library you should put that other
        library in the list of sources. This will do the right thing in all
        cases. For portability, you should specify library dependencies even
        for searched and prebuilt libraries, othewise, static linking on
        Unix won't work. For example:
<programlisting>
lib z ;
lib png : z : &lt;name&gt;png ;
</programlisting>
        </para>

      <note>
        <para>When a library (say, <code>a</code>), that has another
          library, (say, <code>b</code>) 
          <!-- how can a library "have" a library? -->
          is linked dynamically, the <code>b</code>
          library will be incorporated 
          <!-- Incorporated?  Be precise. -->
          in <code>a</code>. (If <code>b</code>
          is dynamic library as well, then <code>a</code> will only refer to
          it, and not include any extra code.) 
          <!-- Don't parenthesize a whole sentence. -->
          When the <code>a</code>
          library is linked statically, Boost.Build will assure that all
          executables that link to <code>a</code> will also link to
          <code>b</code>.
        </para>
      </note>
         
      <para>One feature of Boost.Build that is very important for libraries
        is usage requirements. 
        <!-- Rephrase that.  But then, it's much too late for an
             introduction of usage requirements - you've already
             discussed them many times. -->
        For example, if you write:
<programlisting>
lib helpers : helpers.cpp : : : &lt;include&gt;. ;
</programlisting>
        then the compiler include path for all targets that use
        <code>helpers</code> will contain the directory 
        <!-- The rest of this sentence is unintelligible -->
        where the target is defined.path to "helpers.cpp". The user
        only needs to add <code>helpers</code> to the list of sources,
        and needn't consider the requirements its use imposes on a
        dependent target. This feature greatly simplifies Jamfiles.
        <!-- You can't say “allows to”—you need a noun.  This error is
             repeated throughout. -->
      </para>

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

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

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

      </para>


      <para>
        Another use of the <code>alias</code> rule is to change build
        properties. For example, if you always want static linking for a
        specific C++ Boost library, you can write the following:
<programlisting>
alias threads : /boost/thread//boost_thread : &lt;link&gt;static ;
</programlisting>
        and use only the <code>threads</code> alias in your Jamfiles.
        <!-- changed name for clarity -->
      </para>              

      <para>
        You can also specify usage requirements for the
        <code>alias</code> target. If you write the following:
<programlisting>
alias header_only_library : : : :  &lt;include&gt;/usr/include/header_only_library ; 
</programlisting>
        then using <code>header_only_library</code> in sources will only add an
        include path. Also note that when there are some sources, their usage
        requirements are propagated, too. For example:
<programlisting>
lib lib : lib.cpp : : : &lt;include&gt;. ;
alias lib_alias ; <!-- This line can't possibly be correct!?? -->
exe main : main.cpp lib_alias ;
</programlisting>
        will compile <filename>main.cpp</filename> with the additional include.
      </para>
 
    </section>

    <section id="bbv2.builtins.stage">
      <title>Installing</title>

      <para>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>

      <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>
            
      <bridgehead>Installing into Several Directories</bridgehead>

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

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

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

    </section>

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

      <title>Testing</title>

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

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

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

      <para>There are rules for more elaborate testing: <code>compile</code>,
        <code>compile-fail</code>, <code>run</code> and
        <code>run-fail</code>. They are more suitable for automated testing, and
        are not covered here.
      </para>        
    </section>

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

      <title>Raw commands: 'make' and 'notfile'</title>

      <para>Sometimes, the builtin target types are not enough, and you
      want Boost.Build to just run specific commands. There are two main
      target rules that make it possible: <functionname>make</functionname>
      and <functionname>notfile</functionname>.
      </para>

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

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

      <note>
        <para>
          The <functionname>make</functionname> rule is useful to express custom
          transformation that are used just once or twice in your project. For
          transformations that are used often, you are advised to declare
          new generator, as described in <xref linkend="bbv2.extending.tools"/>.
        </para>
      </note>

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

    <section id="bbv2.reference.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 these steps:</para>
      <orderedlist>
        <listitem><para>Create a header that includes big headers used by your project.
        It's 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 new Boost.Build target for the precompiled header
        and add that precompiled header to sources of the target whose compilation
        you want to speed up:
        <programlisting>
cpp-pch pch : header.hpp ;
exe main : main.cpp pch ;</programlisting>
        You can use the <code>c-pch</code> 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 build the sources and the
        preprocessed 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 include 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>
        
      </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>

    
  <section id="bbv2.advanced.builtins.features">
    <title>Builtin features</title> 
        
    <variablelist>
      <varlistentry><term><literal>variant</literal></term>
        
        <listitem>
          <para>
            A feature that combines several low-level features, making
            it easy to request common build configurations.
          </para>
          
          <para><emphasis role="bold">Allowed values:</emphasis> <literal>debug</literal>, <literal>release</literal>,
            <literal>profile</literal>.</para>
          
          <para>The value <literal>debug</literal> expands to</para>
          
<programlisting>
&lt;optimization&gt;off &lt;debug-symbols&gt;on &lt;inlining&gt;off &lt;runtime-debugging&gt;on
</programlisting>
          
          <para>The value <literal>release</literal> expands to</para>
          
<programlisting>
&lt;optimization&gt;speed &lt;debug-symbols&gt;off &lt;inlining&gt;full &lt;runtime-debugging&gt;off
</programlisting>
          
          <para>The value <literal>profile</literal> expands to the same as
          <literal>release</literal>, plus:</para>
          
<programlisting>
&lt;profiling&gt;on &lt;debug-symbols&gt;on
</programlisting>

          <para>User can define his own build variants using the <code>variant</code> rule from the <code>common</code>
          module.</para>
          
          <para><emphasis role="bold">Notee:</emphasis> Runtime
          debugging is on in debug builds to suit the expectations of
          people used to various IDEs. 
          <!-- Define "runtime debugging." Why will those people expect it to be on in debug builds? -->
          </para>
        </listitem></varlistentry>
      
      <varlistentry id="bbv2.advanced.builtins.features.link">
        <term><literal>link</literal></term>
        
        <listitem>
          <simpara>
            A feature that controls how libraries are built.
          </simpara>
          
          <para><emphasis role="bold">Allowed values:</emphasis> <literal>shared</literal>,
            <literal>static</literal></para>
        </listitem></varlistentry>
      
      <varlistentry><term><literal>source</literal></term>
        
        <listitem>
          <simpara>
            The <code>&lt;source&gt;X</code> feature has the same effect on 
            building a target as putting X in the list of sources. 
            It's useful when you want to add
            the same source to all targets in the project 
            (you can put &lt;source&gt; in requirements) or to conditionally
            include a source (using conditional requirements, see <xref linkend="bbv2.tutorial.conditions"/>)
            See also the <code>&lt;library&gt;</code> feature.
          </simpara>
        </listitem>
      </varlistentry>
      
      <varlistentry><term><literal>library</literal></term>
        
        <listitem>
          <simpara>
            This feature is almost equivalent to the <code>&lt;source&gt;</code> feature, 
            except that it takes effect only for linking. When you want to 
            link all targets in a Jamfile to certain library, the 
            <code>&lt;library&gt;</code> feature is preferred over 
            <code>&lt;source&gt;X</code> -- the latter will add the library to
            all targets, even those that have nothing to do with libraries.
          </simpara>
        </listitem>
      </varlistentry>

      <varlistentry><term><anchor id="bbv2.builtin.features.dependency"/>
          <literal>dependency</literal></term>
        
        <listitem>
          <simpara>
            Introduces a dependency on the target named by the
            value of this feature (so it will be brought
            up-to-date whenever the target being declared is).
            The dependency is not used in any other way. For example, in
            application with plugins, the plugins are not used when linking
            the application, 
            application might have dependency on its plugins, even though 


            , and
            adds its usage requirements to the build properties 
            of the target being declared.  

 The primary use case is when you want
            the usage requirements (such as <code>#include</code> paths) of some
            library to be applied, but don't want to link to it.
            <!-- It's hard to picture why anyone would want to do
                 that.  Please flesh out this motivation -->
          </simpara>
        </listitem>
      </varlistentry>

            
      <varlistentry><term><anchor id="bbv2.builtin.features.use"/>
          <literal>use</literal></term>
        
        <listitem>
          <simpara>
            Introduces a dependency on the target named by the
            value of this feature (so it will be brought
            up-to-date whenever the target being declared is), and
            adds its usage requirements to the build properties 
            <!-- Do you really mean "to the requirements?" -->
            of the target being declared.  The dependency is not used
            in any other way. The primary use case is when you want
            the usage requirements (such as <code>#include</code> paths) of some
            library to be applied, but don't want to link to it.
            <!-- It's hard to picture why anyone would want to do
                 that.  Please flesh out this motivation -->
          </simpara>
        </listitem>
      </varlistentry>
      
      <varlistentry><term><anchor id="bbv2.builtin.features.dll-path"/>
      <literal>dll-path</literal></term>
        
        <listitem>
          <simpara>
            Specify an additional directory where the system should
            look for shared libraries when the executable or shared
            library is run. This feature only affects Unix
            compilers. Plase see <xref linkend="bbv2.faq.dll-path"/>
            in <xref linkend="bbv2.faq"/> for details.
          </simpara>
        </listitem></varlistentry>
      
      <varlistentry><term><literal>hardcode-dll-paths</literal></term>
        
        <listitem>
          <simpara>
            Controls automatic generation of dll-path properties.
          </simpara>
          
          <para><emphasis role="bold">Allowed values:</emphasis>
            <literal>true</literal>, <literal>false</literal>.  This property
            is specific to Unix systems. If an executable is built with
            <code>&lt;hardcode-dll-paths&gt;true</code>, the generated binary
            will contain the list of all the paths to the used shared
            libraries. As the result, the executable can be run without
            changing system paths to shared libraries or installing the
            libraries to system paths. This 
            <!-- you need an antecedent.  This _what_? -->
            is very convenient during
            development. Plase see the <link
            linkend="bbv2.faq.dll-path">FAQ entry</link> for details.
            Note that on Mac OSX, the paths are unconditionally hardcoded by
            the linker, and it's not possible to disable that behaviour.
          </para>
        </listitem></varlistentry>

      <varlistentry>
        <term><literal>cflags</literal></term>
        <term><literal>cxxflags</literal></term>
        <term><literal>linkflags</literal></term>
        
        <listitem>
          <simpara>
            The value of those features is passed without modification to the
            corresponding tools. For <code>cflags</code> that's both the C and C++
            compilers, for <code>cxxflags</code> that's the C++ compiler and for
            <code>linkflags</code> that's the linker. The features are handy when
            you're trying to do something special that cannot be achieved by
            higher-level feature in Boost.Build.
          </simpara>
        </listitem>
      </varlistentry>

      <varlistentry><term><literal>warnings</literal></term>
        
        <listitem>
          <simpara>
            The <code>&lt;warnings&gt;</code> feature controls the warning level of compilers. It has the following values:
            <itemizedlist>
              <listitem><para><code>off</code> - disables all warnings.</para></listitem>
              <listitem><para><code>on</code> - enables default warning level for the tool.</para></listitem>
              <listitem><para><code>all</code> - enables all warnings.</para></listitem>
            </itemizedlist>
            Default value is <code>all</code>.
          </simpara>
        </listitem>
      </varlistentry>

      <varlistentry><term><literal>warnings-as-errors</literal></term>
        
        <listitem>
          <simpara>
            The <code>&lt;warnings-as-errors&gt;</code> makes it possible to treat warnings as errors and abort
            compilation on a warning. The value <code>on</code> enables this behaviour. The default value is
            <code>off</code>.
          </simpara>
        </listitem>
      </varlistentry>

      <varlistentry><term><literal>build</literal></term>
        
        <listitem>
          <para><emphasis role="bold">Allowed values:</emphasis> <literal>no</literal></para>

          <para>
            The <code>build</code> feature is used to conditionally disable build of a target. If <code>&lt;build&gt;no</code>
            is in properties when building a target, build of that target is skipped. Combined with conditional requirements this
            allows to skip building some target in configurations where the build is known to fail. 
          </para>
        </listitem>
      </varlistentry>

      <varlistentry><term><literal>tag</literal></term>

        <listitem><para>The <literal>tag</literal> feature is used to customize
        the name of the generated files. The value should have the form:
<programlisting>@<replaceable>rulename</replaceable></programlisting> where
        <replaceable>rulename</replaceable> should be a name of a rule with
        the following signature:
<programlisting>rule tag ( name : type ? : property-set )</programlisting>
        The rule will be called for each target with the default name computed
        by Boost.Build, the type of the target, and property set. The rule
        can either return a string that must be used as the name of the
        target, or empty string, in which case the default name will be used.
        </para>

        <para>Most typical use of the <literal>tag</literal> feature is
        to encode build properties, or library version in library target names.
        You should take care to return non-empty string from the tag rule
        only for types you care about &#x2014; otherwise, you might
        end up modifying names of object files, generated header file and
        other targets for which changing names does not make sense.</para>
        </listitem>

      </varlistentry>



    </variablelist>
  </section>
</chapter>


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