<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Declaring Targets</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
<link rel="start" href="../../index.html" title="Boost.Build V2 User Manual">
<link rel="up" href="../advanced.html" title="Chapter 4. Overview">
<link rel="prev" href="invocation.html" title="Invocation">
<link rel="next" href="projects.html" title="Projects">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="invocation.html"><img src="../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../advanced.html"><img src="../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="projects.html"><img src="../../../../doc/html/images/next.png" alt="Next"></a>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="bbv2.advanced.targets"></a>Declaring Targets</h2></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="targets.html#id2588492">Name</a></span></dt>
<dt><span class="section"><a href="targets.html#id2588549">Sources</a></span></dt>
<dt><span class="section"><a href="targets.html#bbv2.advanced.targets.requirements">Requirements</a></span></dt>
<dt><span class="section"><a href="targets.html#id2588910">Default Build</a></span></dt>
<dt><span class="section"><a href="targets.html#id2588939">Additional Information</a></span></dt>
</dl></div>
<p><a name="bbv2.advanced.targets.main"></a>
        A <em class="firstterm">Main target</em> is a user-defined named
        entity that can be built, for example an executable file.
        Declaring a main target is usually done using one of the main
        target rules described in <a href="../reference/rules.html" title="Builtin rules">the section called &#8220;Builtin rules&#8221;</a>.  The user can also declare
        custom main target rules as shown in <a href="../extending/rules.html" title="Main target rules">the section called &#8220;Main target rules&#8221;</a>.
      </p>
<a class="indexterm" name="id2588334"></a><p>Most main target rules in Boost.Build have the same common
      signature:</p>
<a class="indexterm" name="id2588348"></a><a name="bbv2.main-target-rule-syntax"></a><pre class="programlisting">
rule <em class="replaceable"><code>rule-name</code></em> (
     main-target-name :
     sources + :
     requirements * :
     default-build * :
     usage-requirements * )
</pre>
<div class="itemizedlist"><ul type="disc">
<li>
            <em class="parameter"><code>main-target-name</code></em> is the name used
            to request the target on command line and to use it from
            other main targets. A main target name may contain
            alphanumeric characters, dashes
            (&#8216;<code class="computeroutput">-</code>&#8217;), and underscores
            (&#8216;<code class="computeroutput">_</code>&#8217;).
          </li>
<li>
            <em class="parameter"><code>sources</code></em> is the list of source files and other main
            targets that must be combined. 
          </li>
<li>
            <em class="parameter"><code>requirements</code></em> is the list of properties that must always
            be present when this main target is built.
          </li>
<li>
            <em class="parameter"><code>default-build</code></em> is the list of properties that will be used
            unless some other value of the same feature is already
            specified, e.g. on the command line or by propagation from a dependent target.
          </li>
<li>
            <em class="parameter"><code>usage-requirements</code></em> is the list of properties that will be
            propagated to all main targets that use this one, i.e. to all its
            dependents.
          </li>
</ul></div>
<p>          
        Some main target rules have a different list of parameters as explicitly
        stated in their documentation.
      </p>
<p>The actual requirements for a target are obtained by refining
      requirements of the project where a target is declared with the
      explicitly specified requirements. The same is true for
      usage-requirements. More details can be found in 
      <a href="../reference/definitions.html#bbv2.reference.variants.proprefine" title="Property refinement">the section called &#8220;Property refinement&#8221;</a>
      </p>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id2588492"></a>Name</h3></div></div></div>
<p>The name of main target has two purposes. First, it's used to refer to this target from
        other targets and from command line. Second, it's used to compute the names of the generated files.
        Typically, filenames are obtained from main target name by appending system-dependent suffixes and
        prefixes.
        </p>
<p>The name of a main target can contain alphanumeric characters, 
        dashes, undescores and dots. The entire
        name is significant when resolving references from other targets. For determining filenames, only the
        part before the first dot is taken. For example:</p>
<pre class="programlisting">
obj test.release : test.cpp : &lt;variant&gt;release ;
obj test.debug : test.cpp : &lt;variant&gt;debug ;
</pre>
<p>will generate two files named <code class="filename">test.obj</code> (in two different directories), not
        two files named <code class="filename">test.release.obj</code> and <code class="filename">test.debug.obj</code>.
        </p>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id2588549"></a>Sources</h3></div></div></div>
<p>The list of sources specifies what should be processed to
        get the resulting targets. Most of the time, it's just a list of
        files. Sometimes, you'll want to automatically construct the
        list of source files rather than having to spell it out
        manually, in which case you can use the
        <code class="computeroutput">glob</code> rule. Here are two examples:</p>
<pre class="programlisting">
exe a : a.cpp ;           # a.cpp is the only source file
exe b : [ glob *.cpp ] ;  # all .cpp files in this directory are sources 
</pre>
<p>
        Unless you specify a file with an absolute path, the name is
        considered relative to the source directory&#8202;&#8212;&#8202;which is typically
        the directory where the Jamfile is located, but can be changed as
        described in <a href="projects.html#bbv2.advanced.projects.attributes.projectrule" title="">the section called &#8220;Projects&#8221;</a>.
        </p>
<p>
          
          The list of sources can also refer to other main targets.
          Targets in the same project can be referred to by name, while
          targets in other projects must be qualified with a directory or a
          symbolic project name. The directory/project name is separated from
          the target name by a double forward slash. There's no special syntax to
          distinguish the directory name from the project name&#8212;the part before
          the double slash is first looked up as project name, and then as directory
          name. For example:
        </p>
<pre class="programlisting">
lib helper : helper.cpp ;
exe a : a.cpp helper ;
# Since all project ids start with slash, ".." is directory name.
exe b : b.cpp ..//utils ;
exe c : c.cpp /boost/program_options//program_options ;
</pre>
<p>
          The first exe uses the library defined in the same
          project. The second one uses some target (most likely library)
          defined by Jamfile one level higher. Finally, the third target
          uses some <a href="http://boost.org" target="_top">C++ Boost</a>
          library, referring to it by absolute symbolic name. More
          information about target references can be found in <a href="../tutorial/libs.html" title="Dependent Targets">the section called &#8220;Dependent Targets&#8221;</a> and <a href="../reference/definitions.html#bbv2.reference.ids" title="Target identifiers and references">the section called &#8220;Target identifiers and references&#8221;</a>.
        </p>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.advanced.targets.requirements"></a>Requirements</h3></div></div></div>
<p>Requirements are the properties that should always be present when
        building a target. Typically, they are includes and defines:
</p>
<pre class="programlisting">
exe hello : hello.cpp : &lt;include&gt;/opt/boost &lt;define&gt;MY_DEBUG ;
</pre>
<p>
        There is a number of other features, listed in
        <a href="builtins/features.html" title="Builtin features">the section called &#8220;Builtin features&#8221;</a>. For example if
        a library can only be built statically, or a file can't be compiled
        with optimization due to a compiler bug, one can use
</p>
<pre class="programlisting">
lib util : util.cpp : &lt;link&gt;static ;
obj main : main.cpp : &lt;optimization&gt;off ;
</pre>
<p>                
        </p>
<p><a name="bbv2.advanced.targets.requirements.conditional"></a>Sometimes, particular relationships need to be maintained
        among a target's build properties. This can be achieved with 
        <em class="firstterm">conditional
        requirements</em>. For example, you might want to set
        specific <code class="computeroutput">#defines</code> when a library is built as shared,
        or when a target's <code class="computeroutput">release</code> variant is built in
        release mode.
</p>
<pre class="programlisting">
lib network : network.cpp 
    : <span class="bold"><strong>&lt;link&gt;shared:&lt;define&gt;NEWORK_LIB_SHARED</strong></span>
     &lt;variant&gt;release:&lt;define&gt;EXTRA_FAST
    ;
</pre>
<p>

        In the example above, whenever <code class="filename">network</code> is
        built with <code class="computeroutput">&lt;link&gt;shared</code>,
        <code class="computeroutput">&lt;define&gt;NEWORK_LIB_SHARED</code> will be in its
        properties, too.      
        </p>
<p>You can use several properties in the condition, for example:
</p>
<pre class="programlisting">
lib network : network.cpp
    : &lt;toolset&gt;gcc,&lt;optimization&gt;speed:&lt;define&gt;USE_INLINE_ASSEMBLER
    ;
</pre>
<p>
        </p>
<p><a name="bbv2.advanced.targets.requirements.indirect"></a>
          A more powerful variant of conditional requirements 
          is <em class="firstterm">indirect conditional requirements</em>.
          You can provide a rule that will be called with the current build properties and can compute additional properties
          to be added. For example:
</p>
<pre class="programlisting">
lib network : network.cpp 
    : &lt;conditional&gt;@my-rule
    ;
rule my-rule ( properties * )
{
    local result ;
    if &lt;toolset&gt;gcc &lt;optimization&gt;speed in $(properties)
    {
        result += &lt;define&gt;USE_INLINE_ASSEMBLER ;
    }
    return $(result) ;
}  
</pre>
<p>
        This example is equivalent to the previous one, but for complex cases, indirect conditional
        requirements can be easier to write and understand.
        </p>
<p>Requirements explicitly specified for a target are usually
        combined with the requirements specified for the containing project. You
        can cause a target to completely ignore specific project's requirement
        using the syntax by adding a minus sign before a property, for example:
</p>
<pre class="programlisting">
exe main : main.cpp : <span class="bold"><strong>-&lt;define&gt;UNNECESSARY_DEFINE</strong></span> ;
</pre>
<p>
        This syntax is the only way to ignore free properties from a parent,
        such as defines. It can be also useful for ordinary properties. Consider
        this example:
</p>
<pre class="programlisting">
project test : requirements &lt;threading;&gt;multi ;
exe test1 : test1.cpp ;
exe test2 : test2.cpp : &lt;threading;&gt;single ;
exe test3 : test3.cpp : -&lt;threading;&gt;multi ;
</pre>
<p>
        Here, <code class="computeroutput">test1</code> inherits project requirements and will always
        be built in multi-threaded mode. The <code class="computeroutput">test2</code> target
        <span class="emphasis"><em>overrides</em></span> project's requirements and will
        always be built in single-threaded mode. In contrast, the 
        <code class="computeroutput">test3</code> target <span class="emphasis"><em>removes</em></span> a property
        from project requirements and will be built either in single-threaded or
        multi-threaded mode depending on which variant is requested by the
        user.</p>
<p>Note that the removal of requirements is completely textual: 
        you need to specify exactly the same property to remove it.</p>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id2588910"></a>Default Build</h3></div></div></div>
<p>The <code class="varname">default-build</code> parameter
        is a set of properties to be used if the build request does
        not otherwise specify a value for features in the set. For example:
</p>
<pre class="programlisting">
exe hello : hello.cpp : : &lt;threading&gt;multi ;
</pre>
<p>
        would build a multi-threaded target unless the user
        explicitly requests a single-threaded version. The difference between
        requirements and default-build is that requirements cannot be
        overridden in any way.
        </p>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id2588939"></a>Additional Information</h3></div></div></div>
<p>
          The ways a target is built can be so different that
          describing them using conditional requirements would be
          hard. For example, imagine that a library actually uses
          different source files depending on the toolset used to build
          it. We can express this situation using <em class="firstterm">target
          alternatives</em>:
</p>
<pre class="programlisting">
lib demangler : dummy_demangler.cpp ;                      # alternative 1
lib demangler : demangler_gcc.cpp : &lt;toolset&gt;gcc ;   # alternative 2
lib demangler : demangler_msvc.cpp : &lt;toolset&gt;msvc ; # alternative 3
</pre>
<p>
          In the example above, when built with <code class="literal">gcc</code>
          or <code class="literal">msvc</code>, <code class="filename">demangler</code>
          will use a source file specific to the toolset.  Otherwise, it
          will use a generic source file,
          <code class="filename">dummy_demangler.cpp</code>.
        </p>
<p>It is possible to declare a target inline, i.e. the "sources"
        parameter may include calls to other main rules. For example:</p>
<pre class="programlisting">
exe hello : hello.cpp 
    [ obj helpers : helpers.cpp : &lt;optimization&gt;off ] ;</pre>
<p>
           Will cause "helpers.cpp" to be always compiled without
           optimization. When referring to an inline main target, its declared
           name must be prefixed by its parent target's name and two dots. In
           the example above, to build only helpers, one should run
           <code class="computeroutput">bjam hello..helpers</code>.
         </p>
<p>When no target is requested on the command line, all targets in the
         current project will be built. If a target should be built only by
         explicit request, this can be expressed by the
         <code class="computeroutput">explicit</code> rule:
         </p>
<pre class="programlisting">
explicit install_programs ;</pre>
<p>
         </p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><small></small></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="invocation.html"><img src="../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../advanced.html"><img src="../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="projects.html"><img src="../../../../doc/html/images/next.png" alt="Next"></a>
</div>
</body>
</html>
