Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/doc/html/bbv2/advanced.html @ 47

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

updated boost from 1_33_1 to 1_34_1
File size: 52.0 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Overview</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="tutorial.html" title="Tutorial">
10<link rel="next" href="tasks.html" title="Common tasks">
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="tutorial.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="tasks.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.advanced"></a>Overview</h2></div></div></div>
28<div class="toc"><dl>
29<dt><span class="section"><a href="advanced.html#bbv2.advanced.jam_language">Boost.Jam Language</a></span></dt>
30<dt><span class="section"><a href="advanced.html#bbv2.advanced.configuration">Configuration</a></span></dt>
31<dt><span class="section"><a href="advanced.html#bbv2.advanced.invocation">Invocation</a></span></dt>
32<dt><span class="section"><a href="advanced.html#bbv2.advanced.targets">Declaring Targets</a></span></dt>
33<dt><span class="section"><a href="advanced.html#bbv2.advanced.projects">Projects</a></span></dt>
34<dt><span class="section"><a href="advanced.html#bbv2.advanced.build_process">The Build Process</a></span></dt>
35</dl></div>
36<p>This section will provide the information necessary to create your own
37  projects using Boost.Build. The information provided here is relatively
38  high-level, and <a href="reference.html" title="Detailed reference">the section called &#8220;Detailed reference&#8221;</a> as
39  well as the on-line help system must be used to obtain
40  low-level documentation (see <a href="advanced.html#bbv2.reference.init.options.help"><code class="option">--help</code></a>).</p>
41<p>Boost.Build actually consists of two parts - Boost.Jam, a
42  build engine with its own interpreted language, and Boost.Build itself,
43  implemented in Boost.Jam's language. The chain of events when
44  you type <span><strong class="command">bjam</strong></span> on the command line is:
45      </p>
46<div class="orderedlist"><ol type="1">
47<li><p>Boost.Jam tries to find Boost.Build and loads the top-level
48          module. The exact process is described in <a href="reference.html#bbv2.reference.init" title="Initialization">the section called &#8220;Initialization&#8221;</a></p></li>
49<li><p>The top-level module loads user-defined configuration
50          files, <code class="filename">user-config.jam</code> and <code class="filename">site-config.jam</code>, which define
51          available toolsets.</p></li>
52<li><p>The Jamfile in the current directory is read. That in turn
53          might cause reading of further Jamfiles. As a result, a tree of
54          projects is created, with targets inside projects.</p></li>
55<li><p>Finally, using the build request specified on the command line,
56          Boost.Build decides which targets should be built, and how. That
57          information is passed back to Boost.Jam, which takes care of
58          actually running commands.</p></li>
59</ol></div>
60<p>
61    </p>
62<p>So, to be able to successfully use Boost.Build, you need to know only
63      four things:
64      </p>
65<div class="itemizedlist"><ul type="disc">
66<li><p><a href="advanced.html#bbv2.advanced.configuration" title="Configuration">
67              How to configure Boost.Build</a></p></li>
68<li><p><a href="advanced.html#bbv2.advanced.targets" title="Declaring Targets">
69              How to write declares targets in Jamfiles</a></p></li>
70<li><p><a href="advanced.html#bbv2.advanced.build_process" title="The Build Process">
71              How the build process works</a></p></li>
72<li><p>Some Basics about the Boost.Jam language. See
73          <a href="advanced.html#bbv2.advanced.jam_language" title="Boost.Jam Language">the section called &#8220;Boost.Jam Language&#8221;</a>.
74          </p></li>
75</ul></div>
76<p>
77    </p>
78<div class="section" lang="en">
79<div class="titlepage"><div><div><h3 class="title">
80<a name="bbv2.advanced.jam_language"></a>Boost.Jam Language</h3></div></div></div>
81<p>This section will describe the basics of the Boost.Jam
82      language&#8212;just enough for writing Jamfiles. For more information,
83      please see the <a href="../">Boost.Jam</a>
84      documentation.</p>
85<p>Boost.Jam has an interpreted, procedural language.
86      On the lowest level, a Boost.Jam program consists of variables and
87      <a class="indexterm" name="id2119697"></a>
88      <em class="firstterm">rules</em> (the Jam term for function). They are grouped
89      in modules&#8212;there's one global module and a number of named
90      modules. Besides that, a Boost.Jam program contains classes and class
91      instances.     
92      </p>
93<p>Syntantically, a Boost.Jam program consists of two kind of
94      elements&#8212;keywords (which have a special meaning to Boost.Jam) and
95      literals.
96
97      Consider this code:
98      </p>
99<pre class="programlisting">
100a = b ;</pre>
101<p>
102      which assigns the value <code class="literal">b</code> to the variable
103      <code class="literal">a</code>. Here, <code class="literal">=</code> and
104      <code class="literal">;</code> are keywords, while <code class="literal">a</code> and
105      <code class="literal">b</code> are literals.
106      </p>
107<div class="warning"><table border="0" summary="Warning">
108<tr>
109<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../images/warning.png"></td>
110<th align="left">Warning</th>
111</tr>
112<tr><td align="left" valign="top"><p>All syntax elements, even keywords, must be separated by
113        spaces. For example, omitting the space character before
114        <code class="literal">;</code> will lead to a syntax error.
115        </p></td></tr>
116</table></div>
117<p>
118      If you want to use a literal value that is the same as some keyword, the
119      value can be quoted:
120      </p>
121<pre class="programlisting">
122a = "=" ;</pre>
123<p>
124      </p>
125<p>All variables in Boost.Jam have the same type&#8212;list of
126      strings. To define a variable one assigns a value to it, like in the
127      previous example. An undefined variable is the same as a variable with
128      an empty value. Variables can be accessed with the
129      <code class="computeroutput">$(<em class="replaceable"><code>variable</code></em>)</code> syntax. For example:
130      </p>
131<pre class="programlisting">
132a = $(b) $(c) ;</pre>
133<p>
134      </p>
135<p>
136        Rules are defined by specifying the rule name, the parameter names,
137        and the allowed size of the list value for each parameter.
138        </p>
139<pre class="programlisting">
140rule <em class="replaceable"><code>example</code></em> 
141     (
142         <em class="replaceable"><code>parameter1</code></em> :
143         <em class="replaceable"><code>parameter2 ?</code></em> :
144         <em class="replaceable"><code>parameter3 +</code></em> :
145         <em class="replaceable"><code>parameter4 *</code></em> 
146     )
147     {
148        // body
149     }</pre>
150<p>
151        When this rule is called, the list passed as the first argument must
152        have exactly one value. The list passed as the second argument can
153        either have one value of be empty. The two remaining arguments can
154        be arbitrary long, but the third argument may not be empty.
155      </p>
156<p>The overview of Boost.Jam language statements is given below:
157      </p>
158<pre class="programlisting">
159helper 1 : 2 : 3 ;
160x = [ helper 1 : 2 : 3 ] ;</pre>
161<p>
162      This code calls the named rule with the specified arguments. When the
163      result of the call must be used inside some expression, you need to add
164      brackets around the call, like shown on the second line.
165      </p>
166<pre class="programlisting">
167if cond { statements } [ else { statements } ]</pre>
168<p>
169      This is a regular if-statement. The condition is composed of:
170      </p>
171<div class="itemizedlist"><ul type="disc">
172<li><p>Literals (true if at least one string is not empty)</p></li>
173<li><p>Comparisons: <code class="computeroutput">a
174        <em class="replaceable"><code>operator</code></em> b</code> where
175        <em class="replaceable"><code>operator</code></em> is one of <code class="computeroutput">=</code>,
176        <code class="computeroutput">!=</code>, <code class="computeroutput">&lt;</code>, <code class="computeroutput">&gt;</code>,
177        <code class="computeroutput">&lt;=</code>, <code class="computeroutput">&gt;=</code>. The comparison is done
178        pairwise between each string in the left and the right arguments.
179        </p></li>
180<li><p>Logical operations: <code class="computeroutput">! a</code>, <code class="computeroutput">a &amp;&amp;
181        b</code>, <code class="computeroutput">a || b</code></p></li>
182<li><p>Grouping: <code class="computeroutput">( cond )</code></p></li>
183</ul></div>
184<p>
185      </p>
186<pre class="programlisting">
187for var in list { statements }</pre>
188<p>
189      Executes statements for each element in list, setting the variable
190      <code class="varname">var</code> to the element value.
191      </p>
192<pre class="programlisting">
193while cond { statements }</pre>
194<p>
195      Repeatedly execute statements while cond remains true upon entry.
196      </p>
197<pre class="programlisting">
198return values ;
199      </pre>
200<p>This statement should be used only inside a
201      rule and assigns <code class="computeroutput">values</code> to the return value of the
202      rule.
203      </p>
204<div class="warning"><table border="0" summary="Warning">
205<tr>
206<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../images/warning.png"></td>
207<th align="left">Warning</th>
208</tr>
209<tr><td align="left" valign="top">
210<p>
211        The <code class="computeroutput">return</code> statement does not exit the rule. For example:
212        </p>
213<pre class="programlisting">
214rule test ( )
215{
216   if 1 = 1 {
217      return "reasonable" ;
218   }
219   return "strange" ;
220}</pre>
221<p> will return <code class="literal">strange</code>, not
222<code class="literal">reasonable</code>.
223      </p>
224</td></tr>
225</table></div>
226<p>
227
228        </p>
229<pre class="programlisting">
230import <em class="replaceable"><code>module</code></em> ;
231import <em class="replaceable"><code>module</code></em> : <em class="replaceable"><code>rule</code></em> ;</pre>
232<p>
233      The first form imports the specified bjam module. All rules from
234      that module are made available using the qualified name:
235      <code class="computeroutput"><em class="replaceable"><code>module</code></em>.<em class="replaceable"><code>rule</code></em></code>.
236      The second form imports the specified rules only, and they can be called
237      using unqualified names.
238      </p>
239<p><a name="bbv2.advanced.jam_language.actions"></a>
240        Sometimes, you'd need to specify the actual command lines to be used
241        when creating targets. In jam language, you use named actions to do this.
242        For example:
243</p>
244<pre class="programlisting">
245actions create-file-from-another
246{
247    create-file-from-another $(&lt;) $(&gt;)
248}
249</pre>
250<p>
251        This specifies a named action called
252        <code class="literal">create-file-from-another</code>. The text inside braces is the
253        command to invoke. The <code class="literal">$(&lt;)</code> variable will be expanded to list of
254        generated files, and the <code class="literal">$(&gt;)</code> variable will be expanded
255        to the list of source files.
256      </p>
257<p>To flexibly adjust command line, you can define a rule with the
258      same name as the action, and taking three parameters -- targets, sources
259      and properties. For example:
260</p>
261<pre class="programlisting">
262rule create-file-from-another ( targets * : sources * : properties * )
263{
264   if &lt;variant&gt;debug in $(properties)
265   {
266       OPTIONS on $(targets) = --debug ;
267   }
268}
269actions create-file-from-another
270{
271    create-file-from-another $(OPTIONS) $(&lt;) $(&gt;)
272}
273</pre>
274<p>
275      In this example, the rule checks if certain build property is specified.
276      If so, it sets variable <code class="varname">OPIONS</code> that's used inside
277      action. Note that the variable is set "on targets" -- the value will
278      be only visible inside action, not globally. Were it set globally,
279      using variable named <code class="varname">OPTIONS</code> in two unrelated
280      actions would be impossible.
281      </p>
282<p>More details can be found in Jam reference, <a href="../jam/language.html#jam.language.rules" title=" Rules">the section called &#8220; Rules&#8221;</a>
283      </p>
284</div>
285<div class="section" lang="en">
286<div class="titlepage"><div><div><h3 class="title">
287<a name="bbv2.advanced.configuration"></a>Configuration</h3></div></div></div>
288<p>The Boost.Build configuration is specified in the file
289    <code class="filename">user-config.jam</code>. You can edit the one in the top-level
290    directory of Boost.Build installation or create a copy in your home directory
291    and edit that. (See <a href="reference.html#bbv2.reference.init.config" title="Table 25.2. Search paths for configuration files">Table 25.2, &#8220;Search paths for configuration files&#8221;</a>  for the
292    exact search paths.) The primary function of that file is to declare which
293    compilers and other tools are available. The simplest syntax to configure
294    a tool is:
295
296</p>
297<pre class="programlisting">
298using <em class="replaceable"><code>tool-name</code></em> ;       
299</pre>
300<p>
301      The <code class="computeroutput">using</code> rule is given a name of tool, and will make that tool
302      available to Boost.Build. For example, <code class="computeroutput">using gcc ;</code> will make the gcc compiler
303      available.     
304    </p>
305<p>
306      Since nothing but a tool name is specified, Boost.Build will
307      pick some default settings.  For example, it will use the
308      <span><strong class="command">gcc</strong></span> executable found in the
309      <code class="envar">PATH</code>, or look in some known installation
310      locations. In most cases, this strategy works automatically. In
311      case you have several versions of a compiler, it's installed in
312      some unusual location, or you need to tweak its configuration,
313      you'll need to pass additional parameters to the
314      <code class="computeroutput">using</code> rule.  The parameters to
315      <code class="computeroutput">using</code> can be different for each
316      tool.  You can obtain specific documentation for any tool's
317      configuration parameters by invoking
318</p>
319<pre class="programlisting">
320bjam --help <em class="replaceable"><code>tool-name</code></em>.init         
321</pre>
322<p>
323    </p>
324<p>
325      That said, for all the compiler toolsets Boost.Build supports
326      out-of-the-box, the list of parameters to
327      <code class="computeroutput">using</code> is the same: <em class="parameter"><code>toolset-name</code></em>, <em class="parameter"><code>version</code></em>, <em class="parameter"><code>invocation-command</code></em>, and <em class="parameter"><code>options</code></em>.
328     
329    </p>
330<p>The <em class="parameter"><code>version</code></em>
331    parameter identifies the toolset version, in case you have
332    several installed. It can have any form you like, but
333    it's recommended that you use a numeric identifier like
334    <code class="literal">7.1</code>.
335    </p>
336<p>
337      The <em class="parameter"><code>invocation-command</code></em>
338      parameter is the command that must be executed to run the
339      compiler. This parameter can usually be omitted if the compiler
340      executable
341      </p>
342<div class="itemizedlist"><ul type="disc">
343<li><p>has its &#8220;usual
344      name&#8221; and is in the <code class="envar">PATH</code>,
345      or</p></li>
346<li><p>was installed in a standard
347      &#8220;installation directory&#8221;,
348      or</p></li>
349<li><p>can be found through a global mechanism like the
350      Windows registry.</p></li>
351</ul></div>
352<p>
353
354      For example:
355</p>
356<pre class="programlisting">
357using msvc : 7.1 ;
358using gcc ;
359</pre>
360<p>
361If the compiler can be found in the <code class="envar">PATH</code> but only by a
362nonstandard name, you can just supply that name:
363</p>
364<pre class="programlisting">
365using gcc : : g++-3.2 ;
366</pre>
367<p>
368Otherwise, it might be necessary to supply the complete path to the
369compiler executable:
370</p>
371<pre class="programlisting">
372using msvc : : "Z:/Programs/Microsoft Visual Studio/vc98/bin/cl" ;
373</pre>
374<p>
375Some Boost.Build toolsets will use that path to take additional
376actions required before invoking the compiler, such as calling
377vendor-supplied scripts to set up its required environment variables.
378When compiler executables for C and C++ are different, path to the C++
379compiler executable must be specified. The &#8220;invocation command&#8221;
380can be any command allowed by the operating system. For example:
381</p>
382<pre class="programlisting">
383using msvc : : echo Compiling &amp;&amp; foo/bar/baz/cl ;
384</pre>
385<p>
386will work.
387    </p>
388<p>To configure several versions of a toolset, simply invoke
389    the <code class="computeroutput">using</code> rule multiple times:
390</p>
391<pre class="programlisting">
392using gcc : 3.3 ;
393using gcc : 3.4 : g++-3.4 ;
394using gcc : 3.2 : g++-3.2 ;
395</pre>
396<p>
397        Note that in the first call to
398        <code class="computeroutput">using</code>, the compiler found in the
399        <code class="envar">PATH</code> will be used, and there's no need to
400        explicitly specify the command.
401    </p>
402<p>As shown above, both the <em class="parameter"><code>version</code></em> and <em class="parameter"><code>invocation-command</code></em> parameters are
403    optional, but there's an important restriction: if you configure
404    the same toolset more than once, you must pass the <em class="parameter"><code>version</code></em>
405    parameter every time. For example, the following is not allowed:
406</p>
407<pre class="programlisting">
408using gcc ;
409using gcc : 3.4 : g++-3.4 ;
410</pre>
411<p>
412      because the first <code class="computeroutput">using</code> call does
413      not specify a <em class="parameter"><code>version</code></em>.
414    </p>
415<p>The <em class="parameter"><code>options</code></em>
416    parameter is used to fine-tune the configuration. All of
417    Boost.Build's standard compiler toolsets accept properties of the
418    four builtin features <code class="varname">cflags</code>,
419    <code class="varname">cxxflags</code>, <code class="varname">compileflags</code> and
420    <code class="varname">linkflags</code> as <em class="parameter"><code>options</code></em> specifying flags that will be
421    always passed to the corresponding tools. Values of the
422    <code class="varname">cflags</code> feature are passed directly to the C
423    compiler, values of the <code class="varname">cxxflags</code> feature are
424    passed directly to the C++ compiler, and values of the
425    <code class="varname">compileflags</code> feature are passed to both. For
426    example, to configure a <span><strong class="command">gcc</strong></span> toolset so that it
427    always generates 64-bit code you could write:
428</p>
429<pre class="programlisting">
430using gcc : 3.4 : : &lt;compileflags&gt;-m64 &lt;linkflags&gt;-m64 ;
431</pre>
432<p>
433    </p>
434</div>
435<div class="section" lang="en">
436<div class="titlepage"><div><div><h3 class="title">
437<a name="bbv2.advanced.invocation"></a>Invocation</h3></div></div></div>
438<p>This section describes how invoke Boost.Build from the command line</p>
439<p>To build all targets defined in Jamfile in the current directory with default properties, run:
440</p>
441<pre class="screen">
442bjam
443</pre>
444<p>To build specific targets, specify them on the command line:
445</p>
446<pre class="screen">
447bjam lib1 subproject//lib2
448</pre>
449<p>
450      </p>
451<p>To request a certain value for some property, add <code class="literal">
452      <em class="replaceable"><code>property</code></em>=<em class="replaceable"><code>value</code></em></code> to the command line:
453</p>
454<pre class="screen">
455bjam toolset=gcc variant=debug optimization=space
456</pre>
457<p>
458       For often used features, like <code class="literal">toolset</code> and <code class="literal">variant</code> you can
459       omit the feature name, so the above can be written as:
460</p>
461<pre class="screen">
462bjam optimization=space
463</pre>
464<p>
465      </p>
466<p>Boost.Build recognizes the following command line options.</p>
467<div class="variablelist"><dl>
468<dt><span class="term"><code class="option">--clean</code></span></dt>
469<dd><p>Cleans all targets in the current directory and
470            in any subprojects. Note that unlike the <code class="literal">clean</code> 
471            target in make, you can use <code class="literal">--clean</code>
472            together with target names to clean specific targets.</p></dd>
473<dt><span class="term"><code class="option">--clean-all</code></span></dt>
474<dd><p>Cleans all targets,
475            no matter where they are defined. In particular, it will clean targets
476            in parent Jamfiles, and targets defined under other project roots.
477            </p></dd>
478<dt><span class="term"><code class="option">--build-dir</code></span></dt>
479<dd>
480<p>Changes build directories for all project roots being built. When
481            this option is specified, all Jamroot files should declare project name.
482            The build directory for the project root will be computed by concatanating
483            the value of the <code class="option">--build-dir</code> option, the project name
484            specified in Jamroot, and the build dir specified in Jamroot
485            (or <code class="literal">bin</code>, if none is specified).
486            </p>
487<p>The option is primarily useful when building from read-only
488            media, when you can't modify Jamroot.
489            </p>
490</dd>
491<dt><span class="term"><code class="option">--version</code></span></dt>
492<dd><p>Prints information on Boost.Build and Boost.Jam
493                  versions.
494            </p></dd>
495<dt>
496<a name="bbv2.reference.init.options.help"></a><span class="term"><code class="option">--help</code></span>
497</dt>
498<dd><p>Invokes the online help system. This prints general
499                  information on how to use the help system with additional
500                  --help* options.
501            </p></dd>
502<dt><span class="term"><code class="option">--debug-configuration</code></span></dt>
503<dd><p>Produces debug information about loading of Boost.Build
504            and toolset files.</p></dd>
505<dt><span class="term"><code class="option">--debug-building</code></span></dt>
506<dd><p>Prints what targets are being built and with what properties.
507            </p></dd>
508<dt><span class="term"><code class="option">--debug-generators</code></span></dt>
509<dd><p>Produces debug output from generator search process.
510            Useful for debugging custom generators.
511            </p></dd>
512<dt><span class="term"><code class="option">--ignore-config</code></span></dt>
513<dd><p>Do not load <code class="literal">site-config.jam</code> and
514                  <code class="literal">user-config.jam</code> configuration files.
515            </p></dd>
516<dt><span class="term"><code class="option">--debug</code></span></dt>
517<dd><p>Enables internal checks.
518            </p></dd>
519</dl></div>
520<p>For complete specification of command line syntax, see
521      <a href="reference.html#bbv2.reference.init.args" title="Command line arguments">the section called &#8220;Command line arguments&#8221;</a>
522      </p>
523</div>
524<div class="section" lang="en">
525<div class="titlepage"><div><div><h3 class="title">
526<a name="bbv2.advanced.targets"></a>Declaring Targets</h3></div></div></div>
527<div class="toc"><dl>
528<dt><span class="section"><a href="advanced.html#id2120913">Name</a></span></dt>
529<dt><span class="section"><a href="advanced.html#id2121069">Sources</a></span></dt>
530<dt><span class="section"><a href="advanced.html#bbv2.advanced.targets.requirements">Requirements</a></span></dt>
531<dt><span class="section"><a href="advanced.html#id2121380">Default Build</a></span></dt>
532<dt><span class="section"><a href="advanced.html#id2121408">Additional Information</a></span></dt>
533</dl></div>
534<p><a name="bbv2.advanced.targets.main"></a>
535        A <em class="firstterm">Main target</em> is a user-defined named
536        entity that can be built, for example an executable file.
537        Declaring a main target is usually done using one of the main
538        target rules described in <a href="reference.html#bbv2.reference.rules" title="Builtin rules">the section called &#8220;Builtin rules&#8221;</a>.  The user can also declare
539        custom main target rules as shown in <a href="extender.html#bbv2.extending.rules" title="Main target rules">the section called &#8220;Main target rules&#8221;</a>.
540      </p>
541<a class="indexterm" name="id2120861"></a><p>Most main target rules in Boost.Build have the same common
542      signature:</p>
543<a class="indexterm" name="id2120874"></a><a name="bbv2.main-target-rule-syntax"></a><pre class="programlisting">
544rule <em class="replaceable"><code>rule-name</code></em> (
545     main-target-name :
546     sources + :
547     requirements * :
548     default-build * :
549     usage-requirements * )
550</pre>
551<div class="itemizedlist"><ul type="disc">
552<li>
553            <em class="parameter"><code>main-target-name</code></em> is the name used
554            to request the target on command line and to use it from
555            other main targets. A main target name may contain
556            alphanumeric characters, dashes
557            (&#8216;<code class="computeroutput">-</code>&#8217;), and underscores
558            (&#8216;<code class="computeroutput">_</code>&#8217;).
559          </li>
560<li>
561            <em class="parameter"><code>sources</code></em> is the list of source files and other main
562            targets that must be combined.
563          </li>
564<li>
565            <em class="parameter"><code>requirements</code></em> is the list of properties that must always
566            be present when this main target is built.
567          </li>
568<li>
569            <em class="parameter"><code>default-build</code></em> is the list of properties that will be used
570            unless some other value of the same feature is already
571            specified, e.g. on the command line or by propagation from a dependent target.
572          </li>
573<li>
574            <em class="parameter"><code>usage-requirements</code></em> is the list of properties that will be
575            propagated to all main targets that use this one, i.e. to all its
576            dependents.
577          </li>
578</ul></div>
579<p>         
580        Some main target rules have a different list of parameters as explicitly
581        stated in their documentation.
582      </p>
583<p>The actual requirements for a target are obtained by refining
584      requirements of the project where a target is declared with the
585      explicitly specified requirements. The same is true for
586      usage-requirements. More details can be found in
587      <a href="reference.html#bbv2.reference.variants.proprefine" title="Property refinement">the section called &#8220;Property refinement&#8221;</a>
588      </p>
589<div class="section" lang="en">
590<div class="titlepage"><div><div><h4 class="title">
591<a name="id2120913"></a>Name</h4></div></div></div>
592<p>The name of main target has two purposes. First, it's used to refer to this target from
593        other targets and from command line. Second, it's used to compute the names of the generated files.
594        Typically, filenames are obtained from main target name by appending system-dependent suffixes and
595        prefixes.
596        </p>
597<p>The name of a main target can contain alphanumeric characters,
598        dashes, undescores and dots. The entire
599        name is significant when resolving references from other targets. For determining filenames, only the
600        part before the first dot is taken. For example:</p>
601<pre class="programlisting">
602obj test.release : test.cpp : &lt;variant&gt;release ;
603obj test.debug : test.cpp : &lt;variant&gt;debug ;
604</pre>
605<p>will generate two files named <code class="filename">test.obj</code> (in two different directories), not
606        two files named <code class="filename">test.release.obj</code> and <code class="filename">test.debug.obj</code>.
607        </p>
608</div>
609<div class="section" lang="en">
610<div class="titlepage"><div><div><h4 class="title">
611<a name="id2121069"></a>Sources</h4></div></div></div>
612<p>The list of sources specifies what should be processed to
613        get the resulting targets. Most of the time, it's just a list of
614        files. Sometimes, you'll want to automatically construct the
615        list of source files rather than having to spell it out
616        manually, in which case you can use the
617        <code class="computeroutput">glob</code> rule. Here are two examples:</p>
618<pre class="programlisting">
619exe a : a.cpp ;           # a.cpp is the only source file
620exe b : [ glob *.cpp ] ;  # all .cpp files in this directory are sources
621</pre>
622<p>
623        Unless you specify a file with an absolute path, the name is
624        considered relative to the source directory&#8202;&#8212;&#8202;which is typically
625        the directory where the Jamfile is located, but can be changed as
626        described in <a href="advanced.html#bbv2.advanced.projects.attributes.projectrule" title="">the section called &#8220;Projects&#8221;</a>.
627        </p>
628<p>
629         
630          The list of sources can also refer to other main targets.
631          Targets in the same project can be referred to by name, while
632          targets in other projects must be qualified with a directory or a
633          symbolic project name. The directory/project name is separated from
634          the target name by a double forward slash. There's no special syntax to
635          distinguish the directory name from the project name&#8212;the part before
636          the double slash is first looked up as project name, and then as directory
637          name. For example:
638        </p>
639<pre class="programlisting">
640lib helper : helper.cpp ;
641exe a : a.cpp helper ;
642# Since all project ids start with slash, ".." is directory name.
643exe b : b.cpp ..//utils ;
644exe c : c.cpp /boost/program_options//program_options ;
645</pre>
646<p>
647          The first exe uses the library defined in the same
648          project. The second one uses some target (most likely library)
649          defined by Jamfile one level higher. Finally, the third target
650          uses some <a href="http://boost.org" target="_top">C++ Boost</a>
651          library, referring to it by absolute symbolic name. More
652          information about target references can be found in <a href="tutorial.html#bbv2.tutorial.libs" title="Dependent Targets">the section called &#8220;Dependent Targets&#8221;</a> and <a href="reference.html#bbv2.reference.ids" title="Target identifiers and references">the section called &#8220;Target identifiers and references&#8221;</a>.
653        </p>
654</div>
655<div class="section" lang="en">
656<div class="titlepage"><div><div><h4 class="title">
657<a name="bbv2.advanced.targets.requirements"></a>Requirements</h4></div></div></div>
658<p>Requirements are the properties that should always be present when
659        building a target. Typically, they are includes and defines:
660</p>
661<pre class="programlisting">
662exe hello : hello.cpp : &lt;include&gt;/opt/boost &lt;define&gt;MY_DEBUG ;
663</pre>
664<p>
665        There is a number of other features, listed in
666        <a href="reference.html#bbv2.advanced.builtins.features" title="Builtin features">the section called &#8220;Builtin features&#8221;</a>. For example if
667        a library can only be built statically, or a file can't be compiled
668        with optimization due to a compiler bug, one can use
669</p>
670<pre class="programlisting">
671lib util : util.cpp : &lt;link&gt;static ;
672obj main : main.cpp : &lt;optimization&gt;off ;
673</pre>
674<p>               
675        </p>
676<p><a name="bbv2.advanced.targets.requirements.conditional"></a>Sometimes, particular relationships need to be maintained
677        among a target's build properties. This can be achieved with
678        <em class="firstterm">conditional
679        requirements</em>. For example, you might want to set
680        specific <code class="computeroutput">#defines</code> when a library is built as shared,
681        or when a target's <code class="computeroutput">release</code> variant is built in
682        release mode.
683</p>
684<pre class="programlisting">
685lib network : network.cpp
686    : <span class="bold"><strong>&lt;link&gt;shared:&lt;define&gt;NEWORK_LIB_SHARED</strong></span>
687     &lt;variant&gt;release:&lt;define&gt;EXTRA_FAST
688    ;
689</pre>
690<p>
691
692        In the example above, whenever <code class="filename">network</code> is
693        built with <code class="computeroutput">&lt;link&gt;shared</code>,
694        <code class="computeroutput">&lt;define&gt;NEWORK_LIB_SHARED</code> will be in its
695        properties, too.     
696        </p>
697<p>You can use several properties in the condition, for example:
698</p>
699<pre class="programlisting">
700lib network : network.cpp
701    : &lt;toolset&gt;gcc,&lt;optimization&gt;speed:&lt;define&gt;USE_INLINE_ASSEMBLER
702    ;
703</pre>
704<p>
705        </p>
706<p><a name="bbv2.advanced.targets.requirements.indirect"></a>
707          A more powerful variant of conditional requirements
708          is <em class="firstterm">indirect conditional requirements</em>.
709          You can provide a rule that will be called with the current build properties and can compute additional properties
710          to be added. For example:
711</p>
712<pre class="programlisting">
713lib network : network.cpp
714    : &lt;conditional&gt;@my-rule
715    ;
716rule my-rule ( properties * )
717{
718    local result ;
719    if &lt;toolset&gt;gcc &lt;optimization&gt;speed in $(properties)
720    {
721        result += &lt;define&gt;USE_INLINE_ASSEMBLER ;
722    }
723    return $(result) ;
724} 
725</pre>
726<p>
727        This example is equivalent to the previous one, but for complex cases, indirect conditional
728        requirements can be easier to write and understand.
729        </p>
730<p>Requirements explicitly specified for a target are usually
731        combined with the requirements specified for the containing project. You
732        can cause a target to completely ignore specific project's requirement
733        using the syntax by adding a minus sign before a property, for example:
734</p>
735<pre class="programlisting">
736exe main : main.cpp : <span class="bold"><strong>-&lt;define&gt;UNNECESSARY_DEFINE</strong></span> ;
737</pre>
738<p>
739        This syntax is the only way to ignore free properties from a parent,
740        such as defines. It can be also useful for ordinary properties. Consider
741        this example:
742</p>
743<pre class="programlisting">
744project test : requirements &lt;threading;&gt;multi ;
745exe test1 : test1.cpp ;
746exe test2 : test2.cpp : &lt;threading;&gt;single ;
747exe test3 : test3.cpp : -&lt;threading;&gt;multi ;
748</pre>
749<p>
750        Here, <code class="computeroutput">test1</code> inherits project requirements and will always
751        be built in multi-threaded mode. The <code class="computeroutput">test2</code> target
752        <span class="emphasis"><em>overrides</em></span> project's requirements and will
753        always be built in single-threaded mode. In contrast, the
754        <code class="computeroutput">test3</code> target <span class="emphasis"><em>removes</em></span> a property
755        from project requirements and will be built either in single-threaded or
756        multi-threaded mode depending on which variant is requested by the
757        user.</p>
758<p>Note that the removal of requirements is completely textual:
759        you need to specify exactly the same property to remove it.</p>
760</div>
761<div class="section" lang="en">
762<div class="titlepage"><div><div><h4 class="title">
763<a name="id2121380"></a>Default Build</h4></div></div></div>
764<p>The <code class="varname">default-build</code> parameter
765        is a set of properties to be used if the build request does
766        not otherwise specify a value for features in the set. For example:
767</p>
768<pre class="programlisting">
769exe hello : hello.cpp : : &lt;threading&gt;multi ;
770</pre>
771<p>
772        would build a multi-threaded target unless the user
773        explicitly requests a single-threaded version. The difference between
774        requirements and default-build is that requirements cannot be
775        overridden in any way.
776        </p>
777</div>
778<div class="section" lang="en">
779<div class="titlepage"><div><div><h4 class="title">
780<a name="id2121408"></a>Additional Information</h4></div></div></div>
781<p>
782          The ways a target is built can be so different that
783          describing them using conditional requirements would be
784          hard. For example, imagine that a library actually uses
785          different source files depending on the toolset used to build
786          it. We can express this situation using <em class="firstterm">target
787          alternatives</em>:
788</p>
789<pre class="programlisting">
790lib demangler : dummy_demangler.cpp ;                      # alternative 1
791lib demangler : demangler_gcc.cpp : &lt;toolset&gt;gcc ;   # alternative 2
792lib demangler : demangler_msvc.cpp : &lt;toolset&gt;msvc ; # alternative 3
793</pre>
794<p>
795          In the example above, when built with <code class="literal">gcc</code>
796          or <code class="literal">msvc</code>, <code class="filename">demangler</code>
797          will use a source file specific to the toolset.  Otherwise, it
798          will use a generic source file,
799          <code class="filename">dummy_demangler.cpp</code>.
800        </p>
801<p>It is possible to declare a target inline, i.e. the "sources"
802        parameter may include calls to other main rules. For example:</p>
803<pre class="programlisting">
804exe hello : hello.cpp
805    [ obj helpers : helpers.cpp : &lt;optimization&gt;off ] ;</pre>
806<p>
807           Will cause "helpers.cpp" to be always compiled without
808           optimization. When referring to an inline main target, its declared
809           name must be prefixed by its parent target's name and two dots. In
810           the example above, to build only helpers, one should run
811           <code class="computeroutput">bjam hello..helpers</code>.
812         </p>
813<p>When no target is requested on the command line, all targets in the
814         current project will be built. If a target should be built only by
815         explicit request, this can be expressed by the
816         <code class="computeroutput">explicit</code> rule:
817         </p>
818<pre class="programlisting">
819explicit install_programs ;</pre>
820<p>
821         </p>
822</div>
823</div>
824<div class="section" lang="en">
825<div class="titlepage"><div><div><h3 class="title">
826<a name="bbv2.advanced.projects"></a>Projects</h3></div></div></div>
827<p>As mentioned before, targets are grouped into projects,
828      and each Jamfile is a separate project. Projects are useful
829      because they allow us to group related targets together, define
830      properties common to all those targets, and assign a symbolic
831      name to the project that can be used in referring to its
832      targets.
833      </p>
834<p>Projects are named using the
835      <code class="computeroutput">project</code> rule, which has the
836      following syntax:
837</p>
838<pre class="programlisting">
839project <em class="replaceable"><code>id</code></em> : <em class="replaceable"><code>attributes</code></em> ;
840</pre>
841<p>
842        Here, <em class="replaceable"><code>attributes</code></em> is a sequence of
843        rule arguments, each of which begins with an attribute-name
844        and is followed by any number of build properties. The list
845        of attribute names along with its handling is also shown in
846        the table below. For example, it is possible to write:
847</p>
848<pre class="programlisting">
849project tennis
850    : requirements &lt;threading&gt;multi
851    : default-build release
852    ;
853</pre>
854<p>   
855      </p>
856<p>The possible attributes are listed below.</p>
857<p><span class="emphasis"><em>Project id</em></span> is a short way to denote a project, as
858        opposed to the Jamfile's pathname. It is a hierarchical path,
859        unrelated to filesystem, such as "boost/thread". <a href="reference.html#bbv2.reference.ids" title="Target identifiers and references">Target references</a> make use of project ids to
860        specify a target.</p>
861<p><span class="emphasis"><em>Source location</em></span> specifies the directory where sources
862        for the project are located.</p>
863<p><span class="emphasis"><em>Project requirements</em></span> are requirements that apply to
864        all the targets in the projects as well as all subprojects.</p>
865<p><span class="emphasis"><em>Default build</em></span> is the build request that should be
866        used when no build request is specified explicitly.</p>
867<p><a name="bbv2.advanced.projects.attributes.projectrule"></a>
868        The default values for those attributes are
869        given in the table below.
870
871        </p>
872<div class="table">
873<a name="id2121622"></a><p class="title"><b>Table 25.1. </b></p>
874<table class="table" summary="">
875<colgroup>
876<col>
877<col>
878<col>
879<col>
880</colgroup>
881<thead><tr>
882<th>Attribute</th>
883<th>Name</th>
884<th>Default value</th>
885<th>Handling by the <code class="computeroutput">project</code>
886                rule</th>
887</tr></thead>
888<tbody>
889<tr>
890<td>Project id</td>
891<td>none</td>
892<td>none</td>
893<td>Assigned from the first parameter of the 'project' rule.
894                  It is assumed to denote absolute project id.</td>
895</tr>
896<tr>
897<td>Source location</td>
898<td><code class="literal">source-location</code></td>
899<td>The location of jamfile for the project</td>
900<td>Sets to the passed value</td>
901</tr>
902<tr>
903<td>Requirements</td>
904<td><code class="literal">requirements</code></td>
905<td>The parent's requirements</td>
906<td>The parent's requirements are refined with the passed
907                  requirement and the result is used as the project
908                  requirements.</td>
909</tr>
910<tr>
911<td>Default build</td>
912<td><code class="literal">default-build</code></td>
913<td>none</td>
914<td>Sets to the passed value</td>
915</tr>
916<tr>
917<td>Build directory</td>
918<td><code class="literal">build-dir</code></td>
919<td>Empty if the parent has no build directory set.
920                Otherwise, the parent's build directory with the
921                relative path from parent to the current project
922                appended to it.
923                </td>
924<td>Sets to the passed value, interpreted as relative to the
925                  project's location.</td>
926</tr>
927</tbody>
928</table>
929</div>
930<p>
931        </p>
932<p>Besides defining projects and main targets, Jamfiles
933      often invoke various utility rules. For the full list of rules
934      that can be directly used in Jamfile see
935      <a href="reference.html#bbv2.reference.rules" title="Builtin rules">the section called &#8220;Builtin rules&#8221;</a>.
936      </p>
937<p>Each subproject inherits attributes, constants and rules
938      from its parent project, which is defined by the nearest
939      Jamfile in an ancestor directory above
940      the subproject.  The top-level project is declared in a file
941      called <code class="filename">Jamroot</code> rather than
942      <code class="filename">Jamfile</code>.  When loading a project,
943      Boost.Build looks for either <code class="filename">Jamroot</code> or
944      <code class="computeroutput">Jamfile</code>.  They are handled identically, except
945      that if the file is called <code class="filename">Jamroot</code>, the
946      search for a parent project is not performed.
947      </p>
948<p>Even when building in a subproject directory, parent
949      project files are always loaded before those of their
950      subprojects, so that every definition made in a parent project
951      is always available to its children. The loading order of any
952      other projects is unspecified.  Even if one project refers to
953      another via the <code class="computeroutput">use-project</code> or a target reference,
954      no specific order should be assumed.
955      </p>
956<div class="note"><table border="0" summary="Note">
957<tr>
958<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
959<th align="left">Note</th>
960</tr>
961<tr><td align="left" valign="top"><p>Giving the root project the special name
962        &#8220;<code class="filename">Jamroot</code>&#8221; ensures that
963        Boost.Build won't misinterpret a directory above it as the
964        project root just because the directory contains a Jamfile.
965       
966        </p></td></tr>
967</table></div>
968</div>
969<div class="section" lang="en">
970<div class="titlepage"><div><div><h3 class="title">
971<a name="bbv2.advanced.build_process"></a>The Build Process</h3></div></div></div>
972<div class="toc"><dl>
973<dt><span class="section"><a href="advanced.html#bbv2.advanced.build_request">Build Request</a></span></dt>
974<dt><span class="section"><a href="advanced.html#id2121940">Building a main target</a></span></dt>
975<dt><span class="section"><a href="advanced.html#id2122056">Building a Project</a></span></dt>
976</dl></div>
977<p>When you've described your targets, you want Boost.Build to run the
978      right tools and create the needed targets.
979     
980      This section will describe
981      two things: how you specify what to build, and how the main targets are
982      actually constructed.
983    </p>
984<p>The most important thing to note is that in Boost.Build, unlike
985      other build tools, the targets you declare do not correspond to specific
986      files. What you declare in a Jamfile is more like a &#8220;metatarget.&#8221; 
987     
988      Depending on the properties you specify on the command line,
989      each metatarget will produce a set of real targets corresponding
990      to the requested properties. It is quite possible that the same
991      metatarget is built several times with different properties,
992      producing different files.
993    </p>
994<div class="tip"><table border="0" summary="Tip">
995<tr>
996<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../images/tip.png"></td>
997<th align="left">Tip</th>
998</tr>
999<tr><td align="left" valign="top"><p>
1000        This means that for Boost.Build, you cannot directly obtain a build
1001        variant from a Jamfile. There could be several variants requested by the
1002        user, and each target can be built with different properties.
1003      </p></td></tr>
1004</table></div>
1005<div class="section" lang="en">
1006<div class="titlepage"><div><div><h4 class="title">
1007<a name="bbv2.advanced.build_request"></a>Build Request</h4></div></div></div>
1008<p>
1009        The command line specifies which targets to build and with which
1010        properties. For example:
1011</p>
1012<pre class="programlisting">
1013bjam app1 lib1//lib1 toolset=gcc variant=debug optimization=full
1014</pre>
1015<p>
1016        would build two targets, "app1" and "lib1//lib1" with the specified
1017        properties. You can refer to any targets, using
1018        <a href="reference.html#bbv2.reference.ids" title="Target identifiers and references">target id</a> and specify arbitrary
1019        properties. Some of the properties are very common, and for them the name
1020        of the property can be omitted. For example, the above can be written as:
1021</p>
1022<pre class="programlisting">
1023bjam app1 lib1//lib1 gcc debug optimization=full
1024</pre>
1025<p>
1026        The complete syntax, which has some additional shortcuts, is
1027        described in <a href="reference.html#bbv2.reference.commandline" title="Command line">the section called &#8220;Command line&#8221;</a>.
1028      </p>
1029</div>
1030<div class="section" lang="en">
1031<div class="titlepage"><div><div><h4 class="title">
1032<a name="id2121940"></a>Building a main target</h4></div></div></div>
1033<p>When you request, directly or indirectly, a build of a main target
1034        with specific requirements, the following steps are done. Some brief
1035        explanation is provided, and more details are given in <a href="reference.html#bbv2.reference.buildprocess" title="Build process">the section called &#8220;Build process&#8221;</a>.
1036        </p>
1037<div class="orderedlist"><ol type="1">
1038<li><p>Applying default build. If the default-build
1039          property of a target specifies a value of a feature that is not
1040          present in the build request, that value is added.</p></li>
1041<li><p>Selecting the main target alternative to use. For
1042              each alternative we look how many properties are present both in
1043              alternative's requirements, and in build request. The
1044              alternative with large number of matching properties is selected.
1045            </p></li>
1046<li><p>Determining "common" properties.
1047         
1048              The build request
1049              is <a href="reference.html#bbv2.reference.variants.proprefine" title="Property refinement">refined</a>
1050              with target's requirements.
1051             
1052              The conditional properties in
1053              requirements are handled as well. Finally, default values of
1054              features are added.
1055            </p></li>
1056<li><p>Building targets referred by the sources list and
1057              dependency properties. The list of sources and the properties
1058              can refer to other target using <a href="reference.html#bbv2.reference.ids" title="Target identifiers and references">target references</a>. For each
1059              reference, we take all <a href="reference.html#bbv2.reference.features.attributes.propagated">propagated</a>
1060              properties, refine them by explicit properties specified in the
1061              target reference, and pass the resulting properties as build
1062              request to the other target.             
1063            </p></li>
1064<li><p>Adding the usage requirements produced when building
1065              dependencies to the "common" properties. When dependencies are
1066              built in the previous step, they return
1067             
1068              both the set of created
1069              "real" targets, and usage requirements. The usage requirements
1070              are added to the common properties and the resulting property
1071              set will be used for building the current target.             
1072            </p></li>
1073<li><p>Building the target using generators. To convert the
1074              sources to the desired type, Boost.Build uses "generators" ---
1075              objects that correspond to tools like compilers and
1076              linkers. Each generator declares what type of targets it
1077             
1078              can
1079              produce and what type of sources it requires. Using this
1080              information, Boost.Build determines which generators must be run
1081              to produce a specific target from specific sources. When
1082              generators are run, they return the "real" targets.
1083            </p></li>
1084<li><p>Computing the usage requirements to be returned. The
1085          conditional properties in usage requirements are expanded
1086         
1087          and the
1088          result is returned.</p></li>
1089</ol></div>
1090<p>       
1091      </p>
1092</div>
1093<div class="section" lang="en">
1094<div class="titlepage"><div><div><h4 class="title">
1095<a name="id2122056"></a>Building a Project</h4></div></div></div>
1096<p>Often, a user builds a complete project, not just one main
1097      target. In fact, invoking <span><strong class="command">bjam</strong></span> without
1098      arguments
1099     
1100      builds the project defined in the current
1101      directory.</p>
1102<p>When a project is built, the build request is passed without
1103        modification to all main targets in that project.
1104       
1105        It's is possible to
1106        prevent implicit building of a target in a project with the
1107        <code class="computeroutput">explicit</code> rule:
1108</p>
1109<pre class="programlisting">
1110explicit hello_test ;
1111</pre>
1112<p>
1113        would cause the <code class="computeroutput">hello_test</code> target to be built only if
1114        explicitly requested by the user or by some other target.
1115      </p>
1116<p>The Jamfile for a project can include a number of
1117      <code class="computeroutput">build-project</code> rule calls
1118     
1119      that specify additional projects
1120      to be built.
1121      </p>
1122</div>
1123</div>
1124</div>
1125<table width="100%"><tr>
1126<td align="left"></td>
1127<td align="right"><small></small></td>
1128</tr></table>
1129<hr>
1130<div class="spirit-nav">
1131<a accesskey="p" href="tutorial.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="tasks.html"><img src="../images/next.png" alt="Next"></a>
1132</div>
1133</body>
1134</html>
Note: See TracBrowser for help on using the repository browser.