Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/doc/html/bbv2/reference.html @ 29

Last change on this file since 29 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 90.4 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Detailed reference</title>
5<link rel="stylesheet" href="../boostbook.css" type="text/css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
7<link rel="start" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
8<link rel="up" href="../bbv2.html" title="Chapter 25. Boost.Build V2 User Manual">
9<link rel="prev" href="extender.html" title="Extender Manual">
10<link rel="next" href="faq.html" title="Frequently Asked Questions">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13<table cellpadding="2" width="100%">
14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
15<td align="center"><a href="../../../index.htm">Home</a></td>
16<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
17<td align="center"><a href="../../../people/people.htm">People</a></td>
18<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
19<td align="center"><a href="../../../more/index.htm">More</a></td>
20</table>
21<hr>
22<div class="spirit-nav">
23<a accesskey="p" href="extender.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../bbv2.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="faq.html"><img src="../images/next.png" alt="Next"></a>
24</div>
25<div class="section" lang="en">
26<div class="titlepage"><div><div><h2 class="title" style="clear: both">
27<a name="bbv2.reference"></a>Detailed reference</h2></div></div></div>
28<div class="toc"><dl>
29<dt><span class="section"><a href="reference.html#bbv2.reference.general">General information</a></span></dt>
30<dt><span class="section"><a href="reference.html#bbv2.reference.rules">Builtin rules</a></span></dt>
31<dt><span class="section"><a href="reference.html#bbv2.advanced.builtins.features">Builtin features</a></span></dt>
32<dt><span class="section"><a href="reference.html#bbv2.reference.tools">Builtin tools</a></span></dt>
33<dt><span class="section"><a href="reference.html#bbv2.reference.buildprocess">Build process</a></span></dt>
34<dt><span class="section"><a href="reference.html#bbv2.reference.definitions">Definitions</a></span></dt>
35<dt><span class="section"><a href="reference.html#bbv2.reference.generators">Generators</a></span></dt>
36</dl></div>
37<div class="section" lang="en">
38<div class="titlepage"><div><div><h3 class="title">
39<a name="bbv2.reference.general"></a>General information</h3></div></div></div>
40<div class="toc"><dl>
41<dt><span class="section"><a href="reference.html#bbv2.reference.init">Initialization</a></span></dt>
42<dt><span class="section"><a href="reference.html#bbv2.reference.commandline">Command line</a></span></dt>
43</dl></div>
44<div class="section" lang="en">
45<div class="titlepage"><div><div><h4 class="title">
46<a name="bbv2.reference.init"></a>Initialization</h4></div></div></div>
47<p>bjam's first job upon startup is to load the Jam code that
48        implements the build system. To do this, it searches for a file
49        called <code class="filename">boost-build.jam</code>, first in the invocation directory, then
50        in its parent and so forth up to the filesystem root, and finally
51        in the directories specified by the environment variable
52        BOOST_BUILD_PATH. When found, the file is interpreted, and should
53        specify the build system location by calling the boost-build
54        rule:</p>
55<pre class="programlisting">
56rule boost-build ( location ? )
57</pre>
58<p>
59        If location is a relative path, it is treated as relative to
60        the directory of <code class="filename">boost-build.jam</code>. The directory specified by
61        that location and the directories in BOOST_BUILD_PATH are then searched for
62        a file called <code class="filename">bootstrap.jam</code>, which is expected to
63        bootstrap the build system. This arrangement allows the build
64        system to work without any command-line or environment variable
65        settings. For example, if the build system files were located in a
66        directory "build-system/" at your project root, you might place a
67        <code class="filename">boost-build.jam</code> at the project root containing:
68
69</p>
70<pre class="programlisting">
71boost-build build-system ;
72</pre>
73<p>
74
75        In this case, running bjam anywhere in the project tree will
76        automatically find the build system.</p>
77<p>The default <code class="filename">bootstrap.jam</code>, after loading some standard
78        definitions, loads two files, which can be provided/customised by
79        user: <code class="filename">site-config.jam</code> and <code class="filename">user-config.jam</code>.</p>
80<p>Locations where those files are searched are summarized below:</p>
81<div class="table">
82<a name="bbv2.reference.init.config"></a><p class="title"><b>Table 25.2. Search paths for configuration files</b></p>
83<table class="table" summary="Search paths for configuration files">
84<colgroup>
85<col>
86<col>
87<col>
88</colgroup>
89<thead><tr>
90<th> </th>
91<th>site-config.jam</th>
92<th>user-config.jam</th>
93</tr></thead>
94<tbody>
95<tr>
96<td>Linux</td>
97<td>
98                <p><code class="computeroutput">/etc</code></p>
99                <p><code class="computeroutput">$HOME</code></p>
100                <p><code class="computeroutput">$BOOST_BUILD_PATH</code></p>
101              </td>
102<td>
103                <p><code class="computeroutput">$HOME</code></p>
104                <p><code class="computeroutput">$BOOST_BUILD_PATH</code></p>
105              </td>
106</tr>
107<tr>
108<td>Windows</td>
109<td>
110                <p><code class="computeroutput">%SystemRoot%</code></p>
111                <p><code class="computeroutput">%HOMEDRIVE%%HOMEPATH%</code></p>
112                <p><code class="computeroutput">%HOME%</code></p>
113                <p><code class="computeroutput">%BOOST_BUILD_PATH%</code></p>
114              </td>
115<td>
116                <p><code class="computeroutput">%HOMEDRIVE%%HOMEPATH%</code></p>
117                <p><code class="computeroutput">%HOME%</code></p>
118                <p><code class="computeroutput">%BOOST_BUILD_PATH%</code></p>
119              </td>
120</tr>
121</tbody>
122</table>
123</div>
124<p>
125        Boost.Build comes with default versions of those files,
126       
127        which can serve as templates for customized versions.
128      </p>
129</div>
130<div class="section" lang="en">
131<div class="titlepage"><div><div><h4 class="title">
132<a name="bbv2.reference.commandline"></a>Command line</h4></div></div></div>
133<div class="toc"><dl>
134<dt><span class="section"><a href="reference.html#bbv2.reference.init.args">Command line arguments</a></span></dt>
135<dt><span class="section"><a href="reference.html#bbv2.reference.init.options">Command line options</a></span></dt>
136</dl></div>
137<p>The command line may contain:</p>
138<div class="itemizedlist"><ul type="disc">
139<li>Jam options,</li>
140<li>Boost.Build <a href="reference.html#bbv2.reference.init.options" title="Command line options">options</a>,</li>
141<li>Command line arguments</li>
142</ul></div>
143<div class="section" lang="en">
144<div class="titlepage"><div><div><h5 class="title">
145<a name="bbv2.reference.init.args"></a>Command line arguments</h5></div></div></div>
146<p>
147          Command line arguments specify targets and build
148          request using the following rules.
149        </p>
150<div class="itemizedlist"><ul type="disc">
151<li>
152              An argument that does not contain slashes or the <code class="computeroutput">=</code>
153              symbol is either a value of an implicit feature or of a target to
154              be built. It is taken to be value of a feature if an appropriate
155              feature exists. Otherwise, it is considered a <a href="reference.html#bbv2.reference.ids" title="Target identifiers and references">target id</a>. Building the
156              special target name &#8220;clean&#8221; has the same effect as
157              using the <code class="computeroutput">--clean</code> option.
158            </li>
159<li>
160<p>
161              An argument containing either slashes or
162              the <code class="computeroutput">=</code> symbol specifies a number of build
163              request elements (see <a href="advanced.html#bbv2.advanced.build_request" title="Build Request">the section called &#8220;Build Request&#8221;</a>). In its simplest
164              form, it's just a set of properties, separated by
165              slashes, which become a single build request element,
166              for example:
167
168</p>
169<pre class="programlisting">
170borland/&lt;runtime-link&gt;static
171</pre>
172<p>
173
174              A more complex form can be used to save typing. For example,
175              instead of
176
177</p>
178<pre class="programlisting">
179borland/runtime-link=static borland/runtime-link=dynamic
180</pre>
181<p>
182
183              one can use
184
185</p>
186<pre class="programlisting">
187borland/runtime-link=static,dynamic
188</pre>
189<p>
190
191              Exactly, the conversion from argument to build request
192              elements is performed by (1) splitting the argument at each slash,
193              (2) converting each split part into a set of properties and (3)
194              taking all possible combinations
195               
196              of the property sets. Each split
197              part should have either the form
198
199</p>
200<pre class="programlisting">
201<span class="emphasis"><em>feature-name</em></span>=<span class="emphasis"><em>feature-value1</em></span>[","<span class="emphasis"><em>feature-valueN</em></span>]*   
202</pre>
203<p>
204
205              or, in case of implicit features
206
207</p>
208<pre class="programlisting">
209<span class="emphasis"><em>feature-value1</em></span>[","<span class="emphasis"><em>feature-valueN</em></span>;]*   
210</pre>
211<p>
212
213              will be converted into the property set
214
215</p>
216<pre class="programlisting">
217&lt;feature-name&gt;feature-value1 .... &lt;feature-name&gt;feature-valueN
218</pre>
219<p>
220
221
222
223            </p>
224</li>
225</ul></div>
226<p>
227          For example, the command line
228
229</p>
230<pre class="programlisting">
231target1 debug gcc/runtime-link=dynamic,static
232</pre>
233<p>
234
235          would cause target called <code class="literal">target1</code> to be rebuilt in
236          debug mode, except that for gcc, both dynamically and statically
237          linked binaries would be created.
238        </p>
239</div>
240<div class="section" lang="en">
241<div class="titlepage"><div><div><h5 class="title">
242<a name="bbv2.reference.init.options"></a>Command line options</h5></div></div></div>
243<p>All of the Boost.Build options start with the "--" prefix.
244          They are described in the following table.</p>
245<p>FIXME: That table has moved into "User documentation" section
246        and there's nothing we can add here. Remove this part?</p>
247</div>
248</div>
249</div>
250<div class="section" lang="en">
251<div class="titlepage"><div><div><h3 class="title">
252<a name="bbv2.reference.rules"></a>Builtin rules</h3></div></div></div>
253<p>This section contains the list of all rules that
254    can be used in Jamfile&#8212;both rules that define new
255    targets and auxiliary rules.</p>
256<div class="variablelist"><dl>
257<dt><span class="term"><code class="literal">exe</code></span></dt>
258<dd><p>Creates an executable file. See
259        <a href="tasks.html#bbv2.tasks.programs" title="Programs">the section called &#8220;Programs&#8221;</a>.</p></dd>
260<dt><span class="term"><code class="literal">lib</code></span></dt>
261<dd><p>Creates an library file. See
262        <a href="tasks.html#bbv2.tasks.libraries" title="Libraries">the section called &#8220;Libraries&#8221;</a>.</p></dd>
263<dt><span class="term"><code class="literal">install</code></span></dt>
264<dd><p>Installs built targets and other files. See
265        <a href="tasks.html#bbv2.tasks.installing" title="Installing">the section called &#8220;Installing&#8221;</a>.</p></dd>
266<dt><span class="term"><code class="literal">alias</code></span></dt>
267<dd><p>Creates an alias for other targets. See
268        <a href="tasks.html#bbv2.tasks.alias" title="Alias">the section called &#8220;Alias&#8221;</a>.</p></dd>
269<dt><span class="term"><code class="literal">unit-test</code></span></dt>
270<dd><p>Creates an executable that will be automatically run. See
271        <a href="tutorial.html#bbv2.tutorial.testing" title="Testing">the section called &#8220;Testing&#8221;</a>.</p></dd>
272<dt>
273<span class="term"><code class="literal">compile</code>, </span><span class="term"><code class="literal">compile-fail</code>, </span><span class="term"><code class="literal">link</code>, </span><span class="term"><code class="literal">link-fail</code>, </span><span class="term"><code class="literal">run</code>, </span><span class="term"><code class="literal">run-fail</code></span>
274</dt>
275<dd><p>Specialized rules for testing. See
276        <a href="tutorial.html#bbv2.tutorial.testing" title="Testing">the section called &#8220;Testing&#8221;</a>.</p></dd>
277<dt><span class="term"><code class="literal">obj</code></span></dt>
278<dd><p>Creates an object file. Useful when a single source
279        file must be compiled with special properties.</p></dd>
280<dt><span class="term"><code class="literal">glob</code></span></dt>
281<dd>
282<p>The <code class="computeroutput">glob</code> rule takes a list shell pattern
283        and returns the list of files in the project's source directory that
284        match the pattern. For example:
285        </p>
286<pre class="programlisting">
287lib tools : [ glob *.cpp ] ;
288        </pre>
289<p>
290        It is possible to also pass a second argument&#8212;the list of
291        exclude patterns. The result will then include the list of
292        files patching any of include patterns, and not matching any
293        of the exclude patterns. For example:
294        </p>
295<pre class="programlisting">
296lib tools : [ glob *.cpp : file_to_exclude.cpp bad*.cpp ] ;
297        </pre>
298<p>
299        </p>
300</dd>
301<dt><span class="term"><code class="literal">glob-tree</code></span></dt>
302<dd>
303<p>The <code class="computeroutput">glob-tree</code> is similar to the
304        <code class="computeroutput">glob</code> except that it operates recursively from
305        the directory of the containing Jamfile. For example:
306        </p>
307<pre class="programlisting">
308ECHO [ glob-tree *.cpp : .svn ] ;
309        </pre>
310<p>
311        will print the names of all C++ files in your project. The
312        <code class="literal">.svn</code> exclude pattern prevents the
313        <code class="computeroutput">glob-tree</code> rule from entering administrative
314        directories of the Subverion version control system.
315        </p>
316</dd>
317<dt><span class="term"><code class="literal">project</code></span></dt>
318<dd><p>Declares project id and attributes, including
319        project requirements. See <a href="advanced.html#bbv2.advanced.projects" title="Projects">the section called &#8220;Projects&#8221;</a>.
320        </p></dd>
321<dt><span class="term"><code class="literal">use-project</code></span></dt>
322<dd><p>Assigns a symbolic project ID to a project at
323        a given path. This rule must be better documented!
324        </p></dd>
325<dt><span class="term"><code class="literal">explicit</code></span></dt>
326<dd><p>The <code class="literal">explicit</code> rule takes a single
327        parameter&#8212;a list of target names. The named targets will
328        be marked explicit, and will be built only if they are explicitly
329        requested on the command line, or if their dependents are built.
330        Compare this to ordinary targets, that are built implicitly when
331        their containing project is built.</p></dd>
332<dt><span class="term"><code class="literal">constant</code></span></dt>
333<dd>
334<p>Sets project-wide constant. Takes two
335        parameters: variable name and a value and makes the specified
336        variable name accessible in this Jamfile and any child Jamfiles.
337        For example:
338        </p>
339<pre class="programlisting">
340constant VERSION : 1.34.0 ;
341        </pre>
342<p>
343        </p>
344</dd>
345<dt><span class="term"><code class="literal">path-constant</code></span></dt>
346<dd>
347<p>Same as <code class="literal">constant</code> except that
348        the value is treated as path relative to Jamfile location. For example,
349        if <span><strong class="command">bjam</strong></span> is invoked in the current directory,
350        and Jamfile in <code class="filename">helper</code> subdirectory has:
351        </p>
352<pre class="programlisting">
353path-constant DATA : data/a.txt ;
354        </pre>
355<p>
356        then the variable <code class="varname">DATA</code> will be set to
357        <code class="literal">helper/data/a.txt</code>, and if <span><strong class="command">bjam</strong></span>
358        is invoked from the <code class="filename">helper</code> directory, then
359        the variable <code class="varname">DATA</code> will be set to
360        <code class="literal">data/a.txt</code>.
361        </p>
362</dd>
363<dt><span class="term"><code class="literal">build-project</code></span></dt>
364<dd><p>Cause some other project to be built. This rule
365        takes a single parameter&#8212;a directory name relative to
366        the containing Jamfile. When the containing Jamfile is built,
367        the project located at that directory will be built as well.
368        At the moment, the parameter to this rule should be a directory
369        name. Project ID or general target references are not allowed.
370        </p></dd>
371<dt><span class="term"><code class="literal">test-suite</code></span></dt>
372<dd><p>This rule is deprecated and equivalent to
373        <code class="computeroutput">alias</code>.</p></dd>
374</dl></div>
375</div>
376<div class="section" lang="en">
377<div class="titlepage"><div><div><h3 class="title">
378<a name="bbv2.advanced.builtins.features"></a>Builtin features</h3></div></div></div>
379<div class="variablelist"><dl>
380<dt><span class="term"><code class="literal">variant</code></span></dt>
381<dd>
382<p>
383            A feature that combines several low-level features, making
384            it easy to request common build configurations.
385          </p>
386<p><span class="bold"><strong>Allowed values:</strong></span> <code class="literal">debug</code>, <code class="literal">release</code>,
387            <code class="literal">profile</code>.</p>
388<p>The value <code class="literal">debug</code> expands to</p>
389<pre class="programlisting">
390&lt;optimization&gt;off &lt;debug-symbols&gt;on &lt;inlining&gt;off &lt;runtime-debugging&gt;on
391</pre>
392<p>The value <code class="literal">release</code> expands to</p>
393<pre class="programlisting">
394&lt;optimization&gt;speed &lt;debug-symbols&gt;off &lt;inlining&gt;full &lt;runtime-debugging&gt;off
395</pre>
396<p>The value <code class="literal">profile</code> expands to the same as
397          <code class="literal">release</code>, plus:</p>
398<pre class="programlisting">
399&lt;profiling&gt;on &lt;debug-symbols&gt;on
400</pre>
401<p>User can define his own build variants using the <code class="computeroutput">variant</code> rule from the <code class="computeroutput">common</code>
402          module.</p>
403<p><span class="bold"><strong>Notee:</strong></span> Runtime
404          debugging is on in debug builds to suit the expectations of
405          people used to various IDEs.
406         
407          </p>
408</dd>
409<dt>
410<a name="bbv2.advanced.builtins.features.link"></a><span class="term"><code class="literal">link</code></span>
411</dt>
412<dd>
413<p>
414            A feature that controls how libraries are built.
415          </p>
416<p><span class="bold"><strong>Allowed values:</strong></span> <code class="literal">shared</code>,
417            <code class="literal">static</code></p>
418</dd>
419<dt><span class="term"><code class="literal">source</code></span></dt>
420<dd>
421            The <code class="computeroutput">&lt;source&gt;X</code> feature has the same effect on
422            building a target as putting X in the list of sources.
423            It's useful when you want to add
424            the same source to all targets in the project
425            (you can put &lt;source&gt; in requirements) or to conditionally
426            include a source (using conditional requirements, see <a href="tutorial.html#bbv2.tutorial.conditions" title="Conditions and alternatives">the section called &#8220;Conditions and alternatives&#8221;</a>)
427            See also the <code class="computeroutput">&lt;library&gt;</code> feature.
428          </dd>
429<dt><span class="term"><code class="literal">library</code></span></dt>
430<dd>
431            This feature is almost equivalent to the <code class="computeroutput">&lt;source&gt;</code> feature,
432            except that it takes effect only for linking. When you want to
433            link all targets in a Jamfile to certain library, the
434            <code class="computeroutput">&lt;library&gt;</code> feature is preferred over
435            <code class="computeroutput">&lt;source&gt;X</code> -- the latter will add the library to
436            all targets, even those that have nothing to do with libraries.
437          </dd>
438<dt><span class="term"><a name="bbv2.builtin.features.dependency"></a>
439          <code class="literal">dependency</code></span></dt>
440<dd>
441            Introduces a dependency on the target named by the
442            value of this feature (so it will be brought
443            up-to-date whenever the target being declared is).
444            The dependency is not used in any other way. For example, in
445            application with plugins, the plugins are not used when linking
446            the application,
447            application might have dependency on its plugins, even though
448
449
450            , and
451            adds its usage requirements to the build properties
452            of the target being declared. 
453
454 The primary use case is when you want
455            the usage requirements (such as <code class="computeroutput">#include</code> paths) of some
456            library to be applied, but don't want to link to it.
457           
458          </dd>
459<dt><span class="term"><a name="bbv2.builtin.features.use"></a>
460          <code class="literal">use</code></span></dt>
461<dd>
462            Introduces a dependency on the target named by the
463            value of this feature (so it will be brought
464            up-to-date whenever the target being declared is), and
465            adds its usage requirements to the build properties
466           
467            of the target being declared.  The dependency is not used
468            in any other way. The primary use case is when you want
469            the usage requirements (such as <code class="computeroutput">#include</code> paths) of some
470            library to be applied, but don't want to link to it.
471           
472          </dd>
473<dt><span class="term"><a name="bbv2.reference.features.dll-path"></a>
474      <code class="literal">dll-path</code></span></dt>
475<dd>
476            Specify an additional directory where the system should
477            look for shared libraries when the executable or shared
478            library is run. This feature only affects Unix
479            compilers. Plase see <a href="faq.html#bbv2.faq.dll-path" title="Why are the dll-path and
480    hardcode-dll-paths properties useful?
481    ">the section called &#8220;Why are the <code class="computeroutput">dll-path</code> and
482    <code class="computeroutput">hardcode-dll-paths</code> properties useful?
483    &#8221;</a>
484            in <a href="faq.html" title="Frequently Asked Questions">the section called &#8220;Frequently Asked Questions&#8221;</a> for details.
485          </dd>
486<dt><span class="term"><code class="literal">hardcode-dll-paths</code></span></dt>
487<dd>
488<p>
489            Controls automatic generation of dll-path properties.
490          </p>
491<p><span class="bold"><strong>Allowed values:</strong></span>
492            <code class="literal">true</code>, <code class="literal">false</code>.  This property
493            is specific to Unix systems. If an executable is built with
494            <code class="computeroutput">&lt;hardcode-dll-paths&gt;true</code>, the generated binary
495            will contain the list of all the paths to the used shared
496            libraries. As the result, the executable can be run without
497            changing system paths to shared libraries or installing the
498            libraries to system paths. This
499           
500            is very convenient during
501            development. Plase see the <a href="faq.html#bbv2.faq.dll-path" title="Why are the dll-path and
502    hardcode-dll-paths properties useful?
503    ">FAQ entry</a> for details.
504            Note that on Mac OSX, the paths are unconditionally hardcoded by
505            the linker, and it's not possible to disable that behaviour.
506          </p>
507</dd>
508<dt>
509<span class="term"><code class="literal">cflags</code>, </span><span class="term"><code class="literal">cxxflags</code>, </span><span class="term"><code class="literal">linkflags</code></span>
510</dt>
511<dd>
512            The value of those features is passed without modification to the
513            corresponding tools. For <code class="computeroutput">cflags</code> that's both the C and C++
514            compilers, for <code class="computeroutput">cxxflags</code> that's the C++ compiler and for
515            <code class="computeroutput">linkflags</code> that's the linker. The features are handy when
516            you're trying to do something special that cannot be achieved by
517            higher-level feature in Boost.Build.
518          </dd>
519<dt><span class="term"><code class="literal">warnings</code></span></dt>
520<dd>
521            The <code class="computeroutput">&lt;warnings&gt;</code> feature controls the warning level of compilers. It has the following values:
522            <div class="itemizedlist"><ul type="disc">
523<li><p><code class="computeroutput">off</code> - disables all warnings.</p></li>
524<li><p><code class="computeroutput">on</code> - enables default warning level for the tool.</p></li>
525<li><p><code class="computeroutput">all</code> - enables all warnings.</p></li>
526</ul></div>
527            Default value is <code class="computeroutput">all</code>.
528          </dd>
529<dt><span class="term"><code class="literal">warnings-as-errors</code></span></dt>
530<dd>
531            The <code class="computeroutput">&lt;warnings-as-errors&gt;</code> makes it possible to treat warnings as errors and abort
532            compilation on a warning. The value <code class="computeroutput">on</code> enables this behaviour. The default value is
533            <code class="computeroutput">off</code>.
534          </dd>
535<dt><span class="term"><code class="literal">build</code></span></dt>
536<dd>
537<p><span class="bold"><strong>Allowed values:</strong></span> <code class="literal">no</code></p>
538<p>
539            The <code class="computeroutput">build</code> feature is used to conditionally disable build of a target. If <code class="computeroutput">&lt;build&gt;no</code>
540            is in properties when building a target, build of that target is skipped. Combined with conditional requirements this
541            allows to skip building some target in configurations where the build is known to fail.
542          </p>
543</dd>
544<dt><span class="term"><code class="literal">tag</code></span></dt>
545<dd>
546<p>The <code class="literal">tag</code> feature is used to customize
547        the name of the generated files. The value should have the form:
548</p>
549<pre class="programlisting">@<em class="replaceable"><code>rulename</code></em></pre>
550<p> where
551        <em class="replaceable"><code>rulename</code></em> should be a name of a rule with
552        the following signature:
553</p>
554<pre class="programlisting">rule tag ( name : type ? : property-set )</pre>
555<p>
556        The rule will be called for each target with the default name computed
557        by Boost.Build, the type of the target, and property set. The rule
558        can either return a string that must be used as the name of the
559        target, or empty string, in which case the default name will be used.
560        </p>
561<p>Most typical use of the <code class="literal">tag</code> feature is
562        to encode build properties, or library version in library target names.
563        You should take care to return non-empty string from the tag rule
564        only for types you care about &#8212; otherwise, you might
565        end up modifying names of object files, generated header file and
566        other targets for which changing names does not make sense.</p>
567</dd>
568<dt><span class="term"><code class="literal">debug-symbols</code></span></dt>
569<dd>
570<p><span class="bold"><strong>Allowed values:</strong></span> <code class="literal">on</code>, <code class="literal">off</code>.</p>
571<p>The <code class="literal">debug-symbols</code> feature specifies if
572          produced object files, executables and libraries should include
573          debug information.
574          Typically, the value of this feature is implicitly set by the
575          <code class="literal">variant</code> feature, but it can be explicitly
576          specified by the user. The most common usage is to build
577          release variant with debugging information.</p>
578</dd>
579</dl></div>
580</div>
581<div class="section" lang="en">
582<div class="titlepage"><div><div><h3 class="title">
583<a name="bbv2.reference.tools"></a>Builtin tools</h3></div></div></div>
584<div class="toc"><dl><dt><span class="section"><a href="reference.html#bbv2.reference.tools.compilers">C++ Compilers</a></span></dt></dl></div>
585<p>Boost.Build comes with support for a large number of C++ compilers,
586      and other tools. This section documents how to use those tools.</p>
587<p>Before using any tool, you must declare your intention, and possibly
588      specify additional information about tool's configuration. This is done
589      with the <code class="computeroutput">using</code> rule, for example:
590</p>
591<pre class="programlisting">
592using gcc ;
593</pre>
594<p>
595      additional parameters can be passed just like for other rules, for example:
596</p>
597<pre class="programlisting">
598using gcc : 4.0 : g++-4.0 ;
599</pre>
600<p>
601      The options that can be passed to each tool will be documented in the
602      subsequent sections.</p>
603<div class="section" lang="en">
604<div class="titlepage"><div><div><h4 class="title">
605<a name="bbv2.reference.tools.compilers"></a>C++ Compilers</h4></div></div></div>
606<div class="toc"><dl>
607<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.gcc">GNU C++</a></span></dt>
608<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.msvc">Microsoft Visual C++</a></span></dt>
609<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.intel">Intel C++</a></span></dt>
610<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.acc">HP aC++ compiler</a></span></dt>
611<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.borland">Borland C++ Compiler</a></span></dt>
612<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.como">Comeau C/C++ Compiler</a></span></dt>
613<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.cw">Code Warrior</a></span></dt>
614<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.dmc">Digital Mars C/C++ Compiler</a></span></dt>
615<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.hp_cxx">HP C++ Compiler for Tru64 Unix</a></span></dt>
616<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.sun">Sun Studio</a></span></dt>
617<dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.vacpp">IBM Visual Age</a></span></dt>
618</dl></div>
619<p>This section lists all Boost.Build modules that support C++
620        compilers and documents how each one can be initialized.</p>
621<div class="section" lang="en">
622<div class="titlepage"><div><div><h5 class="title">
623<a name="bbv2.reference.tools.compiler.gcc"></a>GNU C++</h5></div></div></div>
624<p>The <code class="computeroutput">gcc</code> module supports the
625          <a href="http://gcc.gnu.org" target="_top">GNU C++ compiler</a> 
626          on Linux, a number of Unix-like system including MacOS X, SunOS and
627          BeOS, and on Windows (either <a href="http://www.cygwin.com" target="_top">Cygwin</a>
628          or <a href="http://www.mingw.org" target="_top">MinGW</a>).
629          </p>
630<p>The <code class="computeroutput">gcc</code> module is initialized using the following
631          syntax:</p>
632<pre class="programlisting">
633using gcc : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre>
634<p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p>
635<p>
636          If the version is not explicitly specified, it will be
637          automatically detected by running the compiler with the <code class="computeroutput">-v</code>
638          option. If the command is not specified, the <span><strong class="command">g++</strong></span>
639          binary will be searched in <code class="envar">PATH</code>.</p>
640<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
641<div class="variablelist"><dl>
642<dt><span class="term"><code class="literal">cflags</code></span></dt>
643<dd><p>Specifies additional compiler flags that
644      will be used when compiling C sources.</p></dd>
645<dt><span class="term"><code class="literal">cxxflags</code></span></dt>
646<dd><p>Specifies additional compiler flags that
647      will be used when compiling C++ sources.</p></dd>
648<dt><span class="term"><code class="literal">compileflags</code></span></dt>
649<dd><p>Specifies additional compiler flags that
650      will be used when compiling both C and C++ sources.</p></dd>
651<dt><span class="term"><code class="literal">linkflags</code></span></dt>
652<dd><p>Specifies additional command line options
653      that will be passed to the linker.</p></dd>
654<dt><span class="term"><code class="literal">root</code></span></dt>
655<dd><p>Specifies root directory of the compiler
656      installation. This option is necessary only if it's not possible
657      to detect this information from the compiler command&#8212;for
658      example if the specified compiler command is a user script. </p></dd>
659<dt><span class="term"><code class="literal">rc</code></span></dt>
660<dd><p>Specifies the resource compiler command
661                that will be used with the version of gcc that is being
662                configured. This setting makes sense only for Windows and only
663                if you plan to use resource files. By
664                default <span><strong class="command">windres</strong></span> will be used.</p></dd>
665<dt><span class="term"><code class="literal">rc-type</code></span></dt>
666<dd><p>Specifies the type of resource compiler. The value can
667                be either <code class="computeroutput">windres</code> for msvc resource compiler,
668                or <code class="computeroutput">rc</code> for borland's resource compiler.</p></dd>
669</dl></div>
670</div>
671<div class="section" lang="en">
672<div class="titlepage"><div><div><h5 class="title">
673<a name="bbv2.reference.tools.compiler.msvc"></a>Microsoft Visual C++</h5></div></div></div>
674<p>The <code class="computeroutput">msvc</code> module supports the 
675          <a href="http://msdn.microsoft.com/visualc/" target="_top">Microsoft Visual
676          C++</a> command-line tools on Microsoft Windows. The supported
677          products and versions of command line tools are listed below:</p>
678<div class="itemizedlist"><ul type="disc">
679<li><p>Visual Studio 2005&#8212;8.0</p></li>
680<li><p>Visual Studio .NET 2003&#8212;7.1</p></li>
681<li><p>Visual Studio .NET&#8212;7.0</p></li>
682<li><p>Visual Studio 6.0, Service Pack 5&#8212;6.5</p></li>
683</ul></div>
684<p>The <code class="computeroutput">msvc</code> module is initialized using the following
685          syntax:</p>
686<pre class="programlisting">
687using msvc : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;
688          </pre>
689<p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p>
690<p>If the version is not explicitly specified, the most recent
691          version found in the registry will be used instead.  If the
692          special value <code class="computeroutput">all</code> is passed as the version, all
693          versions found in the registry will be configured. If a version is
694          specified, but the command is not, the compiler binary will be
695          searched in standard installation paths for that version, followed
696          by <code class="envar">PATH</code>.
697          </p>
698<p>The compiler command should be specified using forward slashes,
699          and quoted.</p>
700<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
701<div class="variablelist"><dl>
702<dt><span class="term"><code class="literal">cflags</code></span></dt>
703<dd><p>Specifies additional compiler flags that
704      will be used when compiling C sources.</p></dd>
705<dt><span class="term"><code class="literal">cxxflags</code></span></dt>
706<dd><p>Specifies additional compiler flags that
707      will be used when compiling C++ sources.</p></dd>
708<dt><span class="term"><code class="literal">compileflags</code></span></dt>
709<dd><p>Specifies additional compiler flags that
710      will be used when compiling both C and C++ sources.</p></dd>
711<dt><span class="term"><code class="literal">linkflags</code></span></dt>
712<dd><p>Specifies additional command line options
713      that will be passed to the linker.</p></dd>
714<dt><span class="term"><code class="literal">setup</code></span></dt>
715<dd><p>The filename of the environment setup scripts
716              to run before invoking the compiler. If not specified,
717              <span><strong class="command">vcvars32.bat</strong></span> alongside the compiler binary
718              will be used.</p></dd>
719<dt><span class="term"><code class="literal">compiler</code></span></dt>
720<dd><p>The command that compiles C and C++ sources.
721              If not specified, <span><strong class="command">cl</strong></span> will be used. The
722              command will be invoked after the setup script was
723              executed and adjusted the <code class="envar">PATH</code> variable.</p></dd>
724<dt><span class="term"><code class="literal">linker</code></span></dt>
725<dd><p>The command that links executables and dynamic
726              libraries.
727              If not specified, <span><strong class="command">link</strong></span> will be used. The
728              command will be invoked after the setup script was
729              executed and adjusted the <code class="envar">PATH</code> variable.</p></dd>
730<dt><span class="term"><code class="literal">assembler</code></span></dt>
731<dd><p>The command that compiles assember files.
732              If not specified, <span><strong class="command">cl</strong></span> will be used. The
733              command will be invoked after the setup script was
734              executed and adjusted the <code class="envar">PATH</code> variable.</p></dd>
735<dt><span class="term"><code class="literal">resource-compiler</code></span></dt>
736<dd><p>The command that compiles resource files.
737              If not specified, <span><strong class="command">rc</strong></span> will be used. The
738              command will be invoked after the setup script was
739              executed and adjusted the <code class="envar">PATH</code> variable.</p></dd>
740<dt><span class="term"><code class="literal">idl-compiler</code></span></dt>
741<dd><p>The command that compiles Microsoft COM
742              interface definition files.
743              If not specified, <span><strong class="command">midl</strong></span> will be used. The
744              command will be invoked after the setup script was
745              executed and adjusted the <code class="envar">PATH</code> variable.</p></dd>
746<dt><span class="term"><code class="literal">mc-compiler</code></span></dt>
747<dd><p>The command that compiles Microsoft message
748              catalog files.
749              If not specified, <span><strong class="command">mt</strong></span> will be used. The
750              command will be invoked after the setup script was
751              executed and adjusted the <code class="envar">PATH</code> variable.</p></dd>
752</dl></div>
753</div>
754<div class="section" lang="en">
755<div class="titlepage"><div><div><h5 class="title">
756<a name="bbv2.reference.tools.compiler.intel"></a>Intel C++</h5></div></div></div>
757<p>The <code class="computeroutput">intel-linux</code> and <code class="computeroutput">intel-win</code> modules
758          support the Intel C++ command-line compiler&#8212;the <a href="http://www.intel.com/software/products/compilers/clin/index.htm" target="_top">Linux</a>
759          and <a href="http://www.intel.com/cd/software/products/asmo-na/eng/compilers/284527.htm" target="_top">
760          Windows</a> versions respectively.</p>
761<p>The module is initialized using the following syntax:</p>
762<pre class="programlisting">
763using intel-linux : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre>
764<p>or</p>
765<pre class="programlisting">
766using intel-win : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre>
767<p>respectively.</p>
768<p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p>
769<p>
770          If compiler command is not specified, then Boost.Build will
771          look in <code class="envar">PATH</code> for an executable <span><strong class="command">icpc</strong></span>
772          (on Linux), or <span><strong class="command">icc.exe</strong></span> (on Windows).
773          </p>
774<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
775<div class="variablelist"><dl>
776<dt><span class="term"><code class="literal">cflags</code></span></dt>
777<dd><p>Specifies additional compiler flags that
778      will be used when compiling C sources.</p></dd>
779<dt><span class="term"><code class="literal">cxxflags</code></span></dt>
780<dd><p>Specifies additional compiler flags that
781      will be used when compiling C++ sources.</p></dd>
782<dt><span class="term"><code class="literal">compileflags</code></span></dt>
783<dd><p>Specifies additional compiler flags that
784      will be used when compiling both C and C++ sources.</p></dd>
785<dt><span class="term"><code class="literal">linkflags</code></span></dt>
786<dd><p>Specifies additional command line options
787      that will be passed to the linker.</p></dd>
788</dl></div>
789<p>The Linux version supports the following additional options:</p>
790<div class="variablelist"><dl>
791<dt><span class="term"><code class="literal">root</code></span></dt>
792<dd><p>Specifies root directory of the compiler
793      installation. This option is necessary only if it's not possible
794      to detect this information from the compiler command&#8212;for
795      example if the specified compiler command is a user script. </p></dd>
796</dl></div>
797</div>
798<div class="section" lang="en">
799<div class="titlepage"><div><div><h5 class="title">
800<a name="bbv2.reference.tools.compiler.acc"></a>HP aC++ compiler</h5></div></div></div>
801<p>The <code class="computeroutput">acc</code> module supports the
802<a href="http://h21007.www2.hp.com/dspp/tech/tech_TechSoftwareDetailPage_IDX/1,1703,1740,00.html" target="_top">HP aC++ compiler</a>
803          for the HP-UX operating system.</p>
804<p>The module is initialized using the following
805          syntax:</p>
806<pre class="programlisting">
807using acc ;</pre>
808<p>There are no configuration options. The
809          compiler will always be invoked as <span><strong class="command">aCC</strong></span> and should
810          be in <code class="envar">PATH</code>.</p>
811</div>
812<div class="section" lang="en">
813<div class="titlepage"><div><div><h5 class="title">
814<a name="bbv2.reference.tools.compiler.borland"></a>Borland C++ Compiler</h5></div></div></div>
815<p>The <code class="computeroutput">borland</code> module supports the command line
816          C++ compiler included in
817          <a href="http://www.borland.com/us/products/cbuilder/index.html" target="_top">C++ Builder 2006</a>
818          product and earlier version of it, running on Microsoft Windows.</p>
819<p>The supported products are listed below. The version reported
820          by the command lines tools is also listed for reference.:</p>
821<div class="itemizedlist"><ul type="disc">
822<li><p>C++ Builder 2006&#8212;5.8.2</p></li>
823<li><p>CBuilderX&#8212;5.6.5, 5.6.4 (depending on release)</p></li>
824<li><p>CBuilder6&#8212;5.6.4</p></li>
825<li><p>Free command line tools&#8212;5.5.1</p></li>
826</ul></div>
827<p>The module is initialized using the following syntax:</p>
828<pre class="programlisting">
829using borland : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre>
830<p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p>
831<p>If the command is not specified, Boost.Build will search for
832          a binary named <span><strong class="command">bcc32</strong></span> in <code class="envar">PATH</code>.</p>
833<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
834<div class="variablelist"><dl>
835<dt><span class="term"><code class="literal">cflags</code></span></dt>
836<dd><p>Specifies additional compiler flags that
837      will be used when compiling C sources.</p></dd>
838<dt><span class="term"><code class="literal">cxxflags</code></span></dt>
839<dd><p>Specifies additional compiler flags that
840      will be used when compiling C++ sources.</p></dd>
841<dt><span class="term"><code class="literal">compileflags</code></span></dt>
842<dd><p>Specifies additional compiler flags that
843      will be used when compiling both C and C++ sources.</p></dd>
844<dt><span class="term"><code class="literal">linkflags</code></span></dt>
845<dd><p>Specifies additional command line options
846      that will be passed to the linker.</p></dd>
847</dl></div>
848</div>
849<div class="section" lang="en">
850<div class="titlepage"><div><div><h5 class="title">
851<a name="bbv2.reference.tools.compiler.como"></a>Comeau C/C++ Compiler</h5></div></div></div>
852<p>The <code class="computeroutput">como-linux</code> and the <code class="computeroutput">como-win</code>
853          modules supports the
854          <a href="http://www.comeaucomputing.com/" target="_top">Comeau C/C++ Compiler</a>
855          on Linux and Windows respectively.</p>
856<p>The module is initialized using the following syntax:</p>
857<pre class="programlisting">
858using como-linux : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre>
859<p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p>
860<p>If the command is not specified, Boost.Build will search for
861          a binary named <span><strong class="command">como</strong></span> in
862          <code class="envar">PATH</code>.</p>
863<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
864<div class="variablelist"><dl>
865<dt><span class="term"><code class="literal">cflags</code></span></dt>
866<dd><p>Specifies additional compiler flags that
867      will be used when compiling C sources.</p></dd>
868<dt><span class="term"><code class="literal">cxxflags</code></span></dt>
869<dd><p>Specifies additional compiler flags that
870      will be used when compiling C++ sources.</p></dd>
871<dt><span class="term"><code class="literal">compileflags</code></span></dt>
872<dd><p>Specifies additional compiler flags that
873      will be used when compiling both C and C++ sources.</p></dd>
874<dt><span class="term"><code class="literal">linkflags</code></span></dt>
875<dd><p>Specifies additional command line options
876      that will be passed to the linker.</p></dd>
877</dl></div>
878<p>Before using the windows version of the compiler,
879          you need to setup necessary environment variables per compiler's
880          documentation. In particular, the <code class="envar">COMO_XXX_INCLUDE</code>
881          variable should be set, where <code class="envar">XXX</code> corresponds to the
882          used backend C compiler.</p>
883</div>
884<div class="section" lang="en">
885<div class="titlepage"><div><div><h5 class="title">
886<a name="bbv2.reference.tools.compiler.cw"></a>Code Warrior</h5></div></div></div>
887<p>The <code class="computeroutput">cw</code> module support CodeWarrior compiler,
888          originally produced by Metrowerks and presently developed
889          by Freescale. Boost.Build supports only the versions of the compiler
890          that target x86 processors. All such versions were released by
891          Metrowerks before aquisition and are not sold any longer.
892          The last version known to work is 9.4</p>
893<p>The module is initialized using the following syntax:</p>
894<pre class="programlisting">
895using cw : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre>
896<p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p>
897<p>If the command is not specified, Boost.Build will search for
898          a binary named <span><strong class="command">mwcc</strong></span> in default installation
899          paths and in <code class="envar">PATH</code>.</p>
900<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
901<div class="variablelist"><dl>
902<dt><span class="term"><code class="literal">cflags</code></span></dt>
903<dd><p>Specifies additional compiler flags that
904      will be used when compiling C sources.</p></dd>
905<dt><span class="term"><code class="literal">cxxflags</code></span></dt>
906<dd><p>Specifies additional compiler flags that
907      will be used when compiling C++ sources.</p></dd>
908<dt><span class="term"><code class="literal">compileflags</code></span></dt>
909<dd><p>Specifies additional compiler flags that
910      will be used when compiling both C and C++ sources.</p></dd>
911<dt><span class="term"><code class="literal">linkflags</code></span></dt>
912<dd><p>Specifies additional command line options
913      that will be passed to the linker.</p></dd>
914<dt><span class="term"><code class="literal">root</code></span></dt>
915<dd><p>Specifies root directory of the compiler
916      installation. This option is necessary only if it's not possible
917      to detect this information from the compiler command&#8212;for
918      example if the specified compiler command is a user script. </p></dd>
919<dt><span class="term"><code class="literal">setup</code></span></dt>
920<dd><p>The command that sets up environment variables
921              prior to invoking the compiler. If not specified,
922              <span><strong class="command">cwenv.bat</strong></span> alongside the compiler binary
923              will be used.</p></dd>
924<dt><span class="term"><code class="literal">compiler</code></span></dt>
925<dd><p>The command that compiles C and C++ sources.
926              If not specified, <span><strong class="command">mwcc</strong></span> will be used. The
927              command will be invoked after the setup script was
928              executed and adjusted the <code class="envar">PATH</code> variable.</p></dd>
929<dt><span class="term"><code class="literal">linker</code></span></dt>
930<dd><p>The command that links executables and dynamic
931              libraries.
932              If not specified, <span><strong class="command">mwld</strong></span> will be used. The
933              command will be invoked after the setup script was
934              executed and adjusted the <code class="envar">PATH</code> variable.</p></dd>
935</dl></div>
936</div>
937<div class="section" lang="en">
938<div class="titlepage"><div><div><h5 class="title">
939<a name="bbv2.reference.tools.compiler.dmc"></a>Digital Mars C/C++ Compiler</h5></div></div></div>
940<p>The <code class="computeroutput">dmc</code> module supports the
941          <a href="http://www.digitalmars.com/" target="_top">Digital Mars C++ compiler.</a>
942          </p>
943<p>The module is initialized using the following syntax:</p>
944<pre class="programlisting">
945using dmc : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre>
946<p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p>
947<p>If the command is not specified, Boost.Build will search for
948          a binary named <span><strong class="command">como</strong></span> in
949          <code class="envar">PATH</code>.</p>
950<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
951<div class="variablelist"><dl>
952<dt><span class="term"><code class="literal">cflags</code></span></dt>
953<dd><p>Specifies additional compiler flags that
954      will be used when compiling C sources.</p></dd>
955<dt><span class="term"><code class="literal">cxxflags</code></span></dt>
956<dd><p>Specifies additional compiler flags that
957      will be used when compiling C++ sources.</p></dd>
958<dt><span class="term"><code class="literal">compileflags</code></span></dt>
959<dd><p>Specifies additional compiler flags that
960      will be used when compiling both C and C++ sources.</p></dd>
961<dt><span class="term"><code class="literal">linkflags</code></span></dt>
962<dd><p>Specifies additional command line options
963      that will be passed to the linker.</p></dd>
964</dl></div>
965</div>
966<div class="section" lang="en">
967<div class="titlepage"><div><div><h5 class="title">
968<a name="bbv2.reference.tools.compiler.hp_cxx"></a>HP C++ Compiler for Tru64 Unix</h5></div></div></div>
969<p>The <code class="computeroutput">hp_cxx</code> modules supports the
970          <a href="http://h30097.www3.hp.com/cplus/?jumpid=reg_R1002_USEN" target="_top">
971            HP C++ Compiler</a> for Tru64 Unix.</p>
972<p>The module is initialized using the following syntax:</p>
973<pre class="programlisting">
974using hp_cxx : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre>
975<p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p>
976<p>If the command is not specified, Boost.Build will search for
977          a binary named <span><strong class="command">hp_cxx</strong></span> in <code class="envar">PATH</code>.</p>
978<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
979<div class="variablelist"><dl>
980<dt><span class="term"><code class="literal">cflags</code></span></dt>
981<dd><p>Specifies additional compiler flags that
982      will be used when compiling C sources.</p></dd>
983<dt><span class="term"><code class="literal">cxxflags</code></span></dt>
984<dd><p>Specifies additional compiler flags that
985      will be used when compiling C++ sources.</p></dd>
986<dt><span class="term"><code class="literal">compileflags</code></span></dt>
987<dd><p>Specifies additional compiler flags that
988      will be used when compiling both C and C++ sources.</p></dd>
989<dt><span class="term"><code class="literal">linkflags</code></span></dt>
990<dd><p>Specifies additional command line options
991      that will be passed to the linker.</p></dd>
992</dl></div>
993</div>
994<div class="section" lang="en">
995<div class="titlepage"><div><div><h5 class="title">
996<a name="bbv2.reference.tools.compiler.sun"></a>Sun Studio</h5></div></div></div>
997<p>The <code class="computeroutput">sun</code> module supports the
998          <a href="http://developers.sun.com/sunstudio/index.jsp" target="_top">
999          Sun Studio</a> C++ compilers for the Solaris OS.</p>
1000<p>The module is initialized using the following syntax:</p>
1001<pre class="programlisting">
1002using sun : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre>
1003<p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p>
1004<p>If the command is not specified, Boost.Build will search for
1005          a binary named <span><strong class="command">CC</strong></span>
1006          in <code class="filename">/opt/SUNWspro/bin</code> and in
1007          <code class="envar">PATH</code>.</p>
1008<p>When using this compiler on complex C++ code, such as the
1009          <a href="http://boost.org" target="_top">Boost C++ library</a>, it is
1010          recommended to specify the following options when intializing the
1011          <code class="computeroutput">sun</code> module:
1012          </p>
1013<pre class="screen">
1014-library=stlport4 -features=tmplife -features=tmplrefstatic
1015          </pre>
1016<p> See the <a href="http://blogs.sun.com/sga/entry/command_line_options" target="_top">
1017          Sun C++ Frontend Tales</a> for details.</p>
1018<p>The following options can be provided, using <code class="literal">&lt;<em class="replaceable"><code>option-name</code></em>&gt;<em class="replaceable"><code>option-value</code></em></code> syntax:</p>
1019<div class="variablelist"><dl>
1020<dt><span class="term"><code class="literal">cflags</code></span></dt>
1021<dd><p>Specifies additional compiler flags that
1022      will be used when compiling C sources.</p></dd>
1023<dt><span class="term"><code class="literal">cxxflags</code></span></dt>
1024<dd><p>Specifies additional compiler flags that
1025      will be used when compiling C++ sources.</p></dd>
1026<dt><span class="term"><code class="literal">compileflags</code></span></dt>
1027<dd><p>Specifies additional compiler flags that
1028      will be used when compiling both C and C++ sources.</p></dd>
1029<dt><span class="term"><code class="literal">linkflags</code></span></dt>
1030<dd><p>Specifies additional command line options
1031      that will be passed to the linker.</p></dd>
1032</dl></div>
1033</div>
1034<div class="section" lang="en">
1035<div class="titlepage"><div><div><h5 class="title">
1036<a name="bbv2.reference.tools.compiler.vacpp"></a>IBM Visual Age</h5></div></div></div>
1037<p>The <code class="computeroutput">vacpp</code> module supports the
1038          <a href="http://www.ibm.com/software/ad/vacpp" target="_top">IBM Visual
1039          Age</a> C++ Compiler, for the AIX operating system. Versions
1040          7.1 and 8.0 are known to work.</p>
1041<p>The module is initialized using the following
1042          syntax:</p>
1043<pre class="programlisting">
1044using vacpp ;</pre>
1045<p>The module does not accept any initialization options. The
1046          compiler should be installed in the <code class="filename">/usr/vacpp/bin</code>
1047          directory.</p>
1048<p>Later versions of Visual Age are known as XL C/C++. They
1049          were not tested with the the <code class="computeroutput">vacpp</code> module.</p>
1050</div>
1051</div>
1052</div>
1053<div class="section" lang="en">
1054<div class="titlepage"><div><div><h3 class="title">
1055<a name="bbv2.reference.buildprocess"></a>Build process</h3></div></div></div>
1056<div class="toc"><dl>
1057<dt><span class="section"><a href="reference.html#bbv2.reference.buildprocess.alternatives">Alternative selection</a></span></dt>
1058<dt><span class="section"><a href="reference.html#bbv2.reference.buildprocess.common">Determining common properties</a></span></dt>
1059</dl></div>
1060<p>The general overview of the build process was given in the
1061      <a href="advanced.html#bbv2.advanced.build_process" title="The Build Process">user documentation</a>.
1062      This section provides additional details, and some specific rules.
1063    </p>
1064<p>To recap, building a target with specific properties includes the
1065      following steps:
1066      </p>
1067<div class="orderedlist"><ol type="1">
1068<li><p>applying default build,</p></li>
1069<li><p>selecting the main target alternative to use,
1070          </p></li>
1071<li><p>determining "common" properties,</p></li>
1072<li><p>building targets referred by the sources list and
1073            dependency properties,</p></li>
1074<li><p>adding the usage requirements produces when building
1075            dependencies to the "common" properties,</p></li>
1076<li><p>building the target using generators,</p></li>
1077<li><p>computing the usage requirements to be returned.</p></li>
1078</ol></div>
1079<p>
1080    </p>
1081<div class="section" lang="en">
1082<div class="titlepage"><div><div><h4 class="title">
1083<a name="bbv2.reference.buildprocess.alternatives"></a>Alternative selection</h4></div></div></div>
1084<p>When there are several alternatives, one of them must be
1085        selected. The process is as follows:</p>
1086<div class="orderedlist"><ol type="1">
1087<li>
1088            For each alternative <span class="emphasis"><em>condition</em></span> is defined
1089            as the set of base properies in requirements. [Note: it might be
1090            better to specify the condition explicitly, as in
1091            conditional requirements].
1092          </li>
1093<li>
1094            An alternative is viable only if all properties in condition
1095            are present in build request.
1096          </li>
1097<li>
1098            If there's one viable alternative, it's choosen. Otherwise,
1099            an attempt is made to find one best alternative. An alternative
1100            a is better than another alternative b, iff the set of properties
1101            in b's condition is a strict subset of the set of properities of
1102            'a's condition. If there's one viable alternative, which is
1103            better than all others, it's selected. Otherwise, an error is
1104            reported.
1105          </li>
1106</ol></div>
1107</div>
1108<div class="section" lang="en">
1109<div class="titlepage"><div><div><h4 class="title">
1110<a name="bbv2.reference.buildprocess.common"></a>Determining common properties</h4></div></div></div>
1111<p>The "common" properties is a somewhat artificial term. Those are
1112        the intermediate property set from which both the build request for
1113        dependencies and properties for building the target are derived.
1114      </p>
1115<p>Since default build and alternatives are already handled, we have
1116        only two inputs: build requests and requirements. Here are the rules
1117        about common properties.
1118      </p>
1119<div class="orderedlist"><ol type="1">
1120<li><p>Non-free feature can have only one
1121            value</p></li>
1122<li><p>A non-conditional property in requirement in always
1123            present in common properties.</p></li>
1124<li><p>A property in build request is present in
1125            common properties, unless (2) tells otherwise.</p></li>
1126<li><p>If either build request, or requirements (non-conditional
1127            or conditional) include an expandable property (either composite,
1128            or property with specified subfeature value), the behaviour is
1129            equivalent to explicitly adding all expanded properties to build
1130            request or requirements.</p></li>
1131<li><p>If requirements include a conditional property, and
1132            condiiton of this property is true in context of common
1133            properties, then the conditional property should be in common
1134            properties as well.</p></li>
1135<li><p>If no value for a feature is given by other rules
1136            here, it has default value in common properties.</p></li>
1137</ol></div>
1138<p>Those rules are declarative, they don't specify how to compute the
1139        common properties. However, they provide enough information for the
1140        user. The important point is the handling of conditional
1141        requirements. The condition can be satisfied either by property in
1142        build request, by non-conditional requirements, or even by another
1143        conditional property. For example, the following example works as
1144        expected:
1145</p>
1146<pre class="programlisting">
1147exe a : a.cpp
1148      : &lt;toolset&gt;gcc:&lt;variant&gt;release
1149        &lt;variant&gt;release:&lt;define&gt;FOO ;
1150</pre>
1151<p>
1152      </p>
1153</div>
1154</div>
1155<div class="section" lang="en">
1156<div class="titlepage"><div><div><h3 class="title">
1157<a name="bbv2.reference.definitions"></a>Definitions</h3></div></div></div>
1158<div class="toc"><dl>
1159<dt><span class="section"><a href="reference.html#bbv2.reference.features">Features and properties</a></span></dt>
1160<dt><span class="section"><a href="reference.html#bbv2.reference.variants">Build Variants</a></span></dt>
1161<dt><span class="section"><a href="reference.html#bbv2.reference.variants.proprefine">Property refinement</a></span></dt>
1162<dt><span class="section"><a href="reference.html#bbv2.reference.variants.propcond">Conditional properties</a></span></dt>
1163<dt><span class="section"><a href="reference.html#bbv2.reference.ids">Target identifiers and references</a></span></dt>
1164</dl></div>
1165<div class="section" lang="en">
1166<div class="titlepage"><div><div><h4 class="title">
1167<a name="bbv2.reference.features"></a>Features and properties</h4></div></div></div>
1168<div class="toc"><dl>
1169<dt><span class="section"><a href="reference.html#bbv2.reference.features.validity">Property Validity</a></span></dt>
1170<dt><span class="section"><a href="reference.html#bbv2.reference.features.attributes">Feature Attributes</a></span></dt>
1171<dt><span class="section"><a href="reference.html#bbv2.reference.features.declaration">Feature Declaration</a></span></dt>
1172</dl></div>
1173<p>A <span class="emphasis"><em>feature</em></span> is a normalized (toolset-independent)
1174        aspect of a build configuration, such as whether inlining is
1175        enabled. Feature names may not contain the '<code class="literal">&gt;</code>'
1176        character.</p>
1177<p>Each feature in a build configuration has one or more
1178        associated <span class="emphasis"><em>value</em></span>s. Feature values for non-free features
1179        may not contain the '<code class="literal">&lt;</code>', '<code class="literal">:</code>', or
1180        '<code class="literal">=</code>' characters. Feature values for free features may not
1181        contain the '<code class="literal">&lt;</code>' character.</p>
1182<p>A <span class="emphasis"><em>property</em></span> is a (feature,value) pair, expressed as
1183        &lt;feature&gt;value.</p>
1184<p>A <span class="emphasis"><em>subfeature</em></span> is a feature that only exists in the
1185        presence of its parent feature, and whose identity can be derived
1186        (in the context of its parent) from its value. A subfeature's
1187        parent can never be another subfeature. Thus, features and their
1188        subfeatures form a two-level hierarchy.</p>
1189<p>A <span class="emphasis"><em>value-string</em></span> for a feature <span class="bold"><strong>F</strong></span> is a string of
1190        the form
1191        <code class="literal">value-subvalue1-subvalue2</code>...<code class="literal">-subvalueN</code>, where
1192        <code class="literal">value</code> is a legal value for <span class="bold"><strong>F</strong></span> and
1193        <code class="literal">subvalue1</code>...<code class="literal">subvalueN</code> are legal values of some
1194        of <span class="bold"><strong>F</strong></span>'s subfeatures. For example, the properties
1195        <code class="literal">&lt;toolset&gt;gcc &lt;toolset-version&gt;3.0.1</code> can be
1196        expressed more conscisely using a value-string, as
1197        <code class="literal">&lt;toolset&gt;gcc-3.0.1</code>.</p>
1198<p>A <span class="emphasis"><em>property set</em></span> is a set of properties (i.e. a
1199        collection without duplicates), for instance:
1200        <code class="literal">&lt;toolset&gt;gcc &lt;runtime-link&gt;static</code>.</p>
1201<p>A <span class="emphasis"><em>property path</em></span> is a property set whose elements have
1202        been joined into a single string separated by slashes. A property
1203        path representation of the previous example would be
1204        <code class="literal">&lt;toolset&gt;gcc/&lt;runtime-link&gt;static</code>.</p>
1205<p>A <span class="emphasis"><em>build specification</em></span> is a property set that fully
1206        describes the set of features used to build a target.</p>
1207<div class="section" lang="en">
1208<div class="titlepage"><div><div><h5 class="title">
1209<a name="bbv2.reference.features.validity"></a>Property Validity</h5></div></div></div>
1210<p>
1211          For <a href="reference.html#bbv2.reference.features.attributes.free">free</a>
1212            features, all values are valid. For all other features,
1213          the valid values are explicitly specified, and the build
1214          system will report an error for the use of an invalid
1215          feature-value. Subproperty validity may be restricted so
1216          that certain values are valid only in the presence of
1217          certain other subproperties. For example, it is possible
1218          to specify that the <code class="computeroutput">&lt;gcc-target&gt;mingw</code>
1219          property is only valid in the presence of
1220          <code class="computeroutput">&lt;gcc-version&gt;2.95.2</code>.
1221        </p>
1222</div>
1223<div class="section" lang="en">
1224<div class="titlepage"><div><div><h5 class="title">
1225<a name="bbv2.reference.features.attributes"></a>Feature Attributes</h5></div></div></div>
1226<p>Each feature has a collection of zero or more of the following
1227          attributes. Feature attributes are low-level descriptions of how the
1228          build system should interpret a feature's values when they appear in
1229          a build request. We also refer to the attributes of properties, so
1230          that an <span class="emphasis"><em>incidental</em></span> property, for example, is
1231          one whose feature has the <span class="emphasis"><em>incidental</em></span>
1232          attribute.</p>
1233<div class="itemizedlist"><ul type="disc">
1234<li>
1235<p><span class="emphasis"><em>incidental</em></span></p>
1236<p>Incidental features are assumed not to affect build
1237              products at all. As a consequence, the build system may use
1238              the same file for targets whose build specification differs
1239              only in incidental features. A feature that controls a
1240              compiler's warning level is one example of a likely
1241              incidental feature.</p>
1242<p>Non-incidental features are assumed to affect build
1243              products, so the files for targets whose build specification
1244              differs in non-incidental features are placed in different
1245              directories as described in "target paths" below. [ where? ]
1246            </p>
1247</li>
1248<li>
1249<p>
1250              <a name="bbv2.reference.features.attributes.propagated"></a>
1251              <span class="emphasis"><em>propagated</em></span>
1252            </p>
1253<p>Features of this kind are
1254              propagated to dependencies. That is, if a <a href="advanced.html#bbv2.advanced.targets.main">main target</a> is built using a
1255              propagated
1256              property, the build systems attempts to use the same property
1257              when building any of its dependencies as part of that main
1258              target. For instance, when an optimized exectuable is
1259              requested, one usually wants it to be linked with optimized
1260              libraries. Thus, the <code class="literal">&lt;optimization&gt;</code> feature is
1261              propagated.</p>
1262</li>
1263<li>
1264<p>
1265              <a name="bbv2.reference.features.attributes.free"></a>
1266              <span class="emphasis"><em>free</em></span>
1267            </p>
1268<p>Most features have a finite set of allowed values, and can
1269              only take on a single value from that set in a given build
1270              specification. Free features, on the other hand, can have
1271              several values at a time and each value can be an arbitrary
1272              string. For example, it is possible to have several
1273              preprocessor symbols defined simultaneously:</p>
1274<pre class="programlisting">
1275&lt;define&gt;NDEBUG=1 &lt;define&gt;HAS_CONFIG_H=1
1276</pre>
1277</li>
1278<li>
1279<p><span class="emphasis"><em>optional</em></span></p>
1280<p>An optional feature is a feature that is not required to
1281              appear in a build specification. Every non-optional non-free
1282              feature has a default value that is used when a value for
1283              the feature is not otherwise specified, either in a target's
1284              requirements or in the user's build request. [A feature's
1285              default value is given by the first value listed in the
1286              feature's declaration. -- move this elsewhere - dwa]</p>
1287</li>
1288<li>
1289<p><span class="emphasis"><em>symmetric</em></span></p>
1290<p>A symmetric feature's default value is not automatically
1291              included in <a href="reference.html#bbv2.reference.variants" title="Build Variants">build variants</a>.  Normally
1292              a feature only generates a subvariant directory when its
1293              value differs from the value specified by the build variant,
1294              leading to an assymmetric subvariant directory structure for
1295              certain values of the feature. A symmetric feature, when
1296              relevant to the toolset, always generates a corresponding
1297              subvariant directory.</p>
1298</li>
1299<li>
1300<p><span class="emphasis"><em>path</em></span></p>
1301<p>The value of a path feature specifies a path. The path is
1302              treated as relative to the directory of Jamfile where path
1303              feature is used and is translated appropriately by the build
1304              system when the build is invoked from a different
1305              directory</p>
1306</li>
1307<li>
1308<p><span class="emphasis"><em>implicit</em></span></p>
1309<p>Values of implicit features alone identify the feature.
1310              For example, a user is not required to write
1311              "&lt;toolset&gt;gcc", but can simply write "gcc". Implicit
1312              feature names also don't appear in variant paths, although
1313              the values do. Thus: bin/gcc/... as opposed to
1314              bin/toolset-gcc/.... There should typically be only a few
1315              such features, to avoid possible name clashes.</p>
1316</li>
1317<li>
1318<p><span class="emphasis"><em>composite</em></span></p>
1319<p>Composite features actually correspond to groups of
1320              properties. For example, a build variant is a composite
1321              feature. When generating targets from a set of build
1322              properties, composite features are recursively expanded and
1323              <span class="emphasis"><em>added</em></span> to the build property set, so rules can find
1324              them if necessary. Non-composite non-free features override
1325              components of composite features in a build property set.</p>
1326</li>
1327<li>
1328<p><span class="emphasis"><em>dependency</em></span></p>
1329<p>The value of dependency feature if a target reference.
1330              When used for building of a main target, the value of
1331              dependency feature is treated as additional dependency.</p>
1332<p>For example, dependency features allow to state that
1333              library A depends on library B. As the result, whenever an
1334              application will link to A, it will also link to B.
1335              Specifying B as dependency of A is different from adding B to
1336              the sources of A. </p>
1337</li>
1338</ul></div>
1339<p>Features that are neither free nor incidental are called
1340          <span class="emphasis"><em>base</em></span> features.</p>
1341</div>
1342<div class="section" lang="en">
1343<div class="titlepage"><div><div><h5 class="title">
1344<a name="bbv2.reference.features.declaration"></a>Feature Declaration</h5></div></div></div>
1345<p>The low-level feature declaration interface is the
1346          <code class="literal">feature</code> rule from the
1347          <code class="literal">feature</code> module:
1348         
1349</p>
1350<pre class="programlisting">
1351rule feature ( name : allowed-values * : attributes * )
1352</pre>
1353<p>
1354         
1355          A feature's allowed-values may be extended with the
1356          <code class="computeroutput">feature.extend</code> rule.
1357        </p>
1358</div>
1359</div>
1360<div class="section" lang="en">
1361<div class="titlepage"><div><div><h4 class="title">
1362<a name="bbv2.reference.variants"></a>Build Variants</h4></div></div></div>
1363<p>
1364        A build variant, or (simply variant) is a special kind of composite
1365        feature that automatically incorporates the default values of
1366        features that . Typically you'll want at least two separate
1367        variants: one for debugging, and one for your release code. [
1368        Volodya says: "Yea, we'd need to mention that it's a composite
1369        feature and describe how they are declared, in pacticular that
1370        default values of non-optional features are incorporated into
1371        build variant automagically. Also, do we wan't some variant
1372        inheritance/extension/templates. I don't remember how it works in
1373        V1, so can't document this for V2.". Will clean up soon -DWA ]
1374      </p>
1375</div>
1376<div class="section" lang="en">
1377<div class="titlepage"><div><div><h4 class="title">
1378<a name="bbv2.reference.variants.proprefine"></a>Property refinement</h4></div></div></div>
1379<p>When a target with certain properties is requested, and that
1380        target requires some set of properties, it is needed to find the
1381        set of properties to use for building. This process is called
1382        <span class="emphasis"><em>property refinement</em></span> and is performed by these rules</p>
1383<div class="orderedlist"><ol type="1">
1384<li>
1385            Each property in the required set is added to the original
1386            property set
1387          </li>
1388<li>
1389            If the original property set includes property with a different
1390            value of non free feature, that property is removed.
1391          </li>
1392</ol></div>
1393</div>
1394<div class="section" lang="en">
1395<div class="titlepage"><div><div><h4 class="title">
1396<a name="bbv2.reference.variants.propcond"></a>Conditional properties</h4></div></div></div>
1397<p>Sometime it's desirable to apply certain requirements only for
1398        a specific combination of other properties. For example, one of
1399        compilers that you use issues a pointless warning that you want to
1400        suppress by passing a command line option to it. You would not
1401        want to pass that option to other compilers. Conditional
1402        properties allow you to do just that. Their syntax is:</p>
1403<pre class="programlisting">
1404        property ( "," property ) * ":" property
1405      </pre>
1406<p>
1407        For example, the problem above would be solved by:
1408
1409</p>
1410<pre class="programlisting">
1411exe hello : hello.cpp : &lt;toolset&gt;yfc:&lt;cxxflags&gt;-disable-pointless-warning ;
1412</pre>
1413<p>
1414      </p>
1415<p>The syntax also allows several properties in the condition, for
1416        example:
1417</p>
1418<pre class="programlisting">
1419exe hello : hello.cpp : &lt;os&gt;NT,&lt;toolset&gt;gcc:&lt;link&gt;static ;
1420</pre>
1421<p>
1422      </p>
1423</div>
1424<div class="section" lang="en">
1425<div class="titlepage"><div><div><h4 class="title">
1426<a name="bbv2.reference.ids"></a>Target identifiers and references</h4></div></div></div>
1427<p><span class="emphasis"><em>Target identifier</em></span> is used to denote a
1428        target. The syntax is:</p>
1429<pre class="programlisting">
1430target-id -&gt; (project-id | target-name | file-name )
1431              | (project-id | directory-name) "//" target-name   
1432project-id -&gt; path
1433target-name -&gt; path
1434file-name -&gt; path
1435directory-name -&gt; path                 
1436</pre>
1437<p>
1438        This grammar allows some elements to be recognized as either
1439       
1440        </p>
1441<div class="itemizedlist"><ul type="disc">
1442<li>
1443              project id (at this point, all project ids start with slash).
1444            </li>
1445<li>
1446              name of target declared in current Jamfile (note that target
1447              names may include slash).
1448            </li>
1449<li>
1450              a regular file, denoted by absolute name or name relative to
1451              project's sources location.
1452            </li>
1453</ul></div>
1454<p>
1455
1456        To determine the real meaning a check is made if project-id
1457        by the specified name exists, and then if main target of that
1458        name exists. For example, valid target ids might be:
1459
1460</p>
1461<pre class="screen">
1462a                                    -- target in current project
1463lib/b.cpp                            -- regular file
1464/boost/thread                        -- project "/boost/thread"
1465/home/ghost/build/lr_library//parser -- target in specific project
1466</pre>
1467<p>
1468
1469      </p>
1470<p><span class="bold"><strong>Rationale:</strong></span>Target is separated from project by special
1471        separator (not just slash), because:</p>
1472<div class="itemizedlist"><ul type="disc">
1473<li>
1474            It emphasises that projects and targets are different things.
1475          </li>
1476<li>
1477            It allows to have main target names with slashes.
1478
1479           
1480          </li>
1481</ul></div>
1482<p><a name="bbv2.reference.targets.references"></a>
1483        <span class="emphasis"><em>Target reference</em></span> is used to
1484        specify a source target, and may additionally specify desired
1485        properties for that target. It has this syntax:</p>
1486<pre class="programlisting">
1487target-reference -&gt; target-id [ "/" requested-properties ]
1488requested-properties -&gt; property-path
1489</pre>
1490<p>
1491        For example,
1492
1493        </p>
1494<pre class="programlisting">
1495          exe compiler : compiler.cpp libs/cmdline/&lt;optimization&gt;space ;
1496        </pre>
1497<p>
1498       
1499        would cause the version of <code class="literal">cmdline</code> library,
1500        optimized for space, to be linked in even if the
1501        <code class="literal">compiler</code> executable is build with optimization for
1502        speed.
1503      </p>
1504</div>
1505</div>
1506<div class="section" lang="en">
1507<div class="titlepage"><div><div><h3 class="title">
1508<a name="bbv2.reference.generators"></a>Generators</h3></div></div></div>
1509<div class="toc"><dl>
1510<dt><span class="section"><a href="reference.html#id2130252">Selecting and ranking viable generators</a></span></dt>
1511<dt><span class="section"><a href="reference.html#id2130307">Running generators</a></span></dt>
1512<dt><span class="section"><a href="reference.html#id2130338">Selecting dependency graph</a></span></dt>
1513<dt><span class="section"><a href="reference.html#id2130354">Property adjustment</a></span></dt>
1514<dt><span class="section"><a href="reference.html#id2130412">Transformations cache</a></span></dt>
1515</dl></div>
1516<div class="warning"><table border="0" summary="Warning">
1517<tr>
1518<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../images/warning.png"></td>
1519<th align="left">Warning</th>
1520</tr>
1521<tr><td align="left" valign="top"><p>The information is this section is likely to be outdated
1522        and misleading.
1523      </p></td></tr>
1524</table></div>
1525<p>To construct a main target with given properties from sources,
1526      it is required to create a dependency graph for that main target,
1527      which will also include actions to be run. The algorithm for
1528      creating the dependency graph is described here.</p>
1529<p>The fundamental concept is <span class="emphasis"><em>generator</em></span>. If encapsulates
1530      the notion of build tool and is capable to converting a set of
1531      input targets into a set of output targets, with some properties.
1532      Generator matches a build tool as closely as possible: it works
1533      only when the tool can work with requested properties (for
1534      example, msvc compiler can't work when requested toolset is gcc),
1535      and should produce exactly the same targets as the tool (for
1536      example, if Borland's linker produces additional files with debug
1537      information, generator should also).</p>
1538<p>Given a set of generators, the fundamental operation is to
1539      construct a target of a given type, with given properties, from a
1540      set of targets. That operation is performed by rule
1541      <code class="literal">generators.construct</code> and the used algorithm is described
1542      below.</p>
1543<div class="section" lang="en">
1544<div class="titlepage"><div><div><h4 class="title">
1545<a name="id2130252"></a>Selecting and ranking viable generators</h4></div></div></div>
1546<p>Each generator, in addition to target types that it can
1547        produce, have attribute that affects its applicability in
1548        particular sitiation. Those attributes are:</p>
1549<div class="orderedlist"><ol type="1">
1550<li>
1551            Required properties, which are properties absolutely
1552            necessary for the generator to work. For example, generator
1553            encapsulating the gcc compiler would have &lt;toolset&gt;gcc as
1554            required property.
1555          </li>
1556<li>
1557            Optional properties, which increase the generators
1558            suitability for a particual build.
1559          </li>
1560</ol></div>
1561<p>
1562        Generator's required and optional properties may not include
1563        either free or incidental properties. (Allowing this would
1564        greatly complicate caching targets).
1565      </p>
1566<p>When trying to construct a target, the first step is to select
1567        all possible generators for the requested target type, which
1568        required properties are a subset of requested properties.
1569        Generators that were already selected up the call stack are
1570        excluded. In addition, if any composing generators were selected
1571        up the call stack, all other composing generators are ignored
1572        (TODO: define composing generators). The found generators
1573        are assigned a rank, which is the number of optional properties
1574        present in requested properties. Finally, generators with highest
1575        rank are selected for futher processing.</p>
1576</div>
1577<div class="section" lang="en">
1578<div class="titlepage"><div><div><h4 class="title">
1579<a name="id2130307"></a>Running generators</h4></div></div></div>
1580<p>When generators are selected, each is run to produce a list of
1581        created targets. This list might include targets that are not of
1582        requested types, because generators create the same targets as
1583        some tool, and tool's behaviour is fixed. (Note: should specify
1584        that in some cases we actually want extra targets). If generator
1585        fails, it returns an empty list. Generator is free to call
1586        'construct' again, to convert sources to the types it can handle.
1587        It also can pass modified properties to 'construct'. However, a
1588        generator is not allowed to modify any propagated properties,
1589        otherwise when actually consuming properties we might discover
1590        that the set of propagated properties is different from what was
1591        used for building sources.</p>
1592<p>For all targets that are not of requested types, we try to
1593        convert them to requested type, using a second call to
1594        <code class="literal">construct</code>. This is done in order to support
1595        transformation sequences where single source file expands to
1596        several later. See <a href="http://groups.yahoo.com/group/jamboost/message/1667" target="_top">this
1597          message</a> for details.</p>
1598</div>
1599<div class="section" lang="en">
1600<div class="titlepage"><div><div><h4 class="title">
1601<a name="id2130338"></a>Selecting dependency graph</h4></div></div></div>
1602<p>
1603        After all generators are run,
1604        it is necessary to decide which of successfull invocation will be
1605        taken as final result. At the moment, this is not done. Instead,
1606        it is checked whether all successfull generator invocation
1607        returned the same target list. Error is issued otherwise.
1608      </p>
1609</div>
1610<div class="section" lang="en">
1611<div class="titlepage"><div><div><h4 class="title">
1612<a name="id2130354"></a>Property adjustment</h4></div></div></div>
1613<p>Because target location is determined by the build system, it
1614        is sometimes necessary to adjust properties, in order to not
1615        break actions. For example, if there's an action that generates
1616        a header, say "a_parser.h", and a source file "a.cpp" which
1617        includes that file, we must make everything work as if a_parser.h
1618        is generated in the same directory where it would be generated
1619        without any subvariants.</p>
1620<p>Correct property adjustment can be done only after all targets
1621        are created, so the approach taken is:</p>
1622<div class="orderedlist"><ol type="1">
1623<li><p>
1624            When dependency graph is constructed, each action can be
1625            assigned a rule for property adjustment.
1626          </p></li>
1627<li><p>
1628            When virtual target is actualized, that rule is run and
1629            return the final set of properties. At this stage it can use
1630            information of all created virtual targets.
1631          </p></li>
1632</ol></div>
1633<p>In case of quoted includes, no adjustment can give 100% correct
1634        results. If target dirs are not changed by build system, quoted
1635        includes are searched in "." and then in include path, while angle
1636        includes are searched only in include path. When target dirs are
1637        changed, we'd want to make quoted includes to be search in "." then in
1638        additional dirs and then in the include path and make angle includes
1639        be searched in include path, probably with additional paths added at
1640        some position. Unless, include path already has "." as the first
1641        element, this is not possible. So, either generated headers should not
1642        be included with quotes, or first element of include path should be
1643        ".", which essentially erases the difference between quoted and angle
1644        includes. <span class="bold"><strong>Note:</strong></span> the only way to get
1645        "." as include path into compiler command line is via verbatim
1646        compiler option. In all other case, Boost.Build will convert "." into
1647        directory where it occurs.</p>
1648</div>
1649<div class="section" lang="en">
1650<div class="titlepage"><div><div><h4 class="title">
1651<a name="id2130412"></a>Transformations cache</h4></div></div></div>
1652<p>
1653        Under certain conditions, an
1654        attempt is made to cache results of transformation search. First,
1655        the sources are replaced with targets with special name and the
1656        found target list is stored. Later, when properties, requested
1657        type, and source type are the same, the store target list is
1658        retrieved and cloned, with appropriate change in names.
1659      </p>
1660</div>
1661</div>
1662</div>
1663<table width="100%"><tr>
1664<td align="left"></td>
1665<td align="right"><small></small></td>
1666</tr></table>
1667<hr>
1668<div class="spirit-nav">
1669<a accesskey="p" href="extender.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../bbv2.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="faq.html"><img src="../images/next.png" alt="Next"></a>
1670</div>
1671</body>
1672</html>
Note: See TracBrowser for help on using the repository browser.