Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/doc/html/bbv2/tasks.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: 33.6 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Common tasks</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="advanced.html" title="Overview">
10<link rel="next" href="extender.html" title="Extender Manual">
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="advanced.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="extender.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.tasks"></a>Common tasks</h2></div></div></div>
28<div class="toc"><dl>
29<dt><span class="section"><a href="tasks.html#bbv2.tasks.programs">Programs</a></span></dt>
30<dt><span class="section"><a href="tasks.html#bbv2.tasks.libraries">Libraries</a></span></dt>
31<dt><span class="section"><a href="tasks.html#bbv2.tasks.alias">Alias</a></span></dt>
32<dt><span class="section"><a href="tasks.html#bbv2.tasks.installing">Installing</a></span></dt>
33<dt><span class="section"><a href="tasks.html#bbv2.builtins.testing">Testing</a></span></dt>
34<dt><span class="section"><a href="tasks.html#bbv2.builtins.raw">Custom commands</a></span></dt>
35<dt><span class="section"><a href="tasks.html#bbv2.reference.precompiled_headers">Precompiled Headers</a></span></dt>
36<dt><span class="section"><a href="tasks.html#bbv2.reference.generated_headers">Generated headers</a></span></dt>
37</dl></div>
38<p>This section describes main targets types that Boost.Build supports
39  of-of-the-box. Unless otherwise noted, all mentioned main target rules
40  have the common signature, described in <a href="advanced.html#bbv2.advanced.targets" title="Declaring Targets">the section called &#8220;Declaring Targets&#8221;</a>.
41  </p>
42<div class="section" lang="en">
43<div class="titlepage"><div><div><h3 class="title">
44<a name="bbv2.tasks.programs"></a>Programs</h3></div></div></div>
45<a class="indexterm" name="id2122146"></a><p>Programs are created using the <code class="computeroutput">exe</code> rule, which
46        follows the <a href="advanced.html#bbv2.main-target-rule-syntax">common
47          syntax</a>. For example:
48</p>
49<pre class="programlisting">
50exe hello : hello.cpp some_library.lib /some_project//library
51          : &lt;threading&gt;multi
52          ;
53</pre>
54<p>
55        This will create an executable file from the sources -- in this case,
56        one C++ file, one library file present in the same directory, and
57        another library that is created by Boost.Build. Generally, sources
58        can include C and C++ files, object files and libraries. Boost.Build
59        will automatically try to convert targets of other types.
60      </p>
61<div class="tip"><table border="0" summary="Tip">
62<tr>
63<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../images/tip.png"></td>
64<th align="left">Tip</th>
65</tr>
66<tr><td align="left" valign="top"><p>         
67          On Windows, if an application uses dynamic libraries, and both
68          the application and the libraries are built by Boost.Build, its not
69          possible to immediately run the application, because the
70          <code class="literal">PATH</code> environment variable should include the path
71          to the libraries. It means you have to either add the paths
72          manually, or place the application and the libraries to the same
73          directory. See <a href="tasks.html#bbv2.tasks.installing" title="Installing">the section called &#8220;Installing&#8221;</a>.
74        </p></td></tr>
75</table></div>
76</div>
77<div class="section" lang="en">
78<div class="titlepage"><div><div><h3 class="title">
79<a name="bbv2.tasks.libraries"></a>Libraries</h3></div></div></div>
80<p>Libraries are created using the <code class="computeroutput">lib</code> rule, which
81        follows the <a href="advanced.html#bbv2.main-target-rule-syntax">common
82          syntax</a>. For example:
83</p>
84<pre class="programlisting">
85lib helpers : helpers.cpp : &lt;include&gt;boost : : &lt;include&gt;. ;
86</pre>
87<p>
88      </p>
89<p>In the most common case, the <code class="computeroutput">lib</code> creates a library
90        from the specified sources. Depending on the value of
91        &lt;link&gt; feature the library will be either static or
92        shared. There are two other cases. First is when the library is
93        installed somewhere in compiler's search paths, and should be
94        searched by the compiler (typically, using the <code class="option">-l</code>
95        option). The second case is where the library is available as a
96        prebuilt file and the full path is known.         
97       
98        </p>
99<p>
100        The syntax for these case is given below:
101</p>
102<pre class="programlisting">
103lib z : : &lt;name&gt;z &lt;search&gt;/home/ghost ;           
104lib compress : : &lt;file&gt;/opt/libs/compress.a ;
105</pre>
106<p>
107        The <code class="computeroutput">name</code> property specifies the name that should be
108        passed to the <code class="option">-l</code> option, and the <code class="computeroutput">file</code>
109        property specifies the file location. The <code class="varname">search</code> feature
110        specifies paths in which to search for the library. That feature can
111        be specified several times, or it can be omitted, in which case only
112        default compiler paths will be searched.
113      </p>
114<p>The difference between using the <code class="varname">file</code> feature as
115        opposed to the <code class="varname">name</code> feature together with the
116        <code class="varname">search</code> feature is that <code class="varname">file</code> is more
117        precise. A specific file will be used. On the other hand, the
118        <code class="varname">search</code> feature only adds a library path, and the
119        <code class="varname">name</code> feature gives the basic name of the library. The
120        search rules are specific to the linker. For example, given these
121        definition:
122</p>
123<pre class="programlisting">
124lib a : : &lt;variant&gt;release &lt;file&gt;/pool/release/a.so ;
125lib a : : &lt;variant&gt;debug &lt;file&gt;/pool/debug/a.so ;
126lib b : : &lt;variant&gt;release &lt;file&gt;/pool/release/b.so ;
127lib b : : &lt;variant&gt;debug &lt;file&gt;/pool/debug/b.so ;
128</pre>
129<p>
130        It's possible to use release version of <code class="computeroutput">a</code> and debug
131        version of <code class="computeroutput">b</code>. Had we used the <code class="varname">name</code> and
132        <code class="varname">search</code> features, the linker would always pick either
133        release or debug versions.
134       
135      </p>
136<p>
137        For convenience, the following syntax is allowed:
138</p>
139<pre class="programlisting">
140lib z ;
141lib gui db aux ;
142</pre>
143<p>
144          and is does exactly the same as:
145</p>
146<pre class="programlisting">
147lib z : : &lt;name&gt;z ;           
148lib gui : : &lt;name&gt;gui ;           
149lib db : : &lt;name&gt;db ;           
150lib aux : : &lt;name&gt;aux ;           
151</pre>
152<p>
153      </p>
154<p>When a library uses another library you should put that other
155        library in the list of sources. This will do the right thing in all
156        cases. For portability, you should specify library dependencies even
157        for searched and prebuilt libraries, othewise, static linking on
158        Unix won't work. For example:
159</p>
160<pre class="programlisting">
161lib z ;
162lib png : z : &lt;name&gt;png ;
163</pre>
164<p>
165        </p>
166<div class="note"><table border="0" summary="Note">
167<tr>
168<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
169<th align="left">Note</th>
170</tr>
171<tr><td align="left" valign="top"><p>When a library (say, <code class="computeroutput">a</code>), that has another
172          library, (say, <code class="computeroutput">b</code>)
173         
174          is linked dynamically, the <code class="computeroutput">b</code>
175          library will be incorporated
176         
177          in <code class="computeroutput">a</code>. (If <code class="computeroutput">b</code>
178          is dynamic library as well, then <code class="computeroutput">a</code> will only refer to
179          it, and not include any extra code.)
180         
181          When the <code class="computeroutput">a</code>
182          library is linked statically, Boost.Build will assure that all
183          executables that link to <code class="computeroutput">a</code> will also link to
184          <code class="computeroutput">b</code>.
185        </p></td></tr>
186</table></div>
187<p>One feature of Boost.Build that is very important for libraries
188        is usage requirements.
189       
190        For example, if you write:
191</p>
192<pre class="programlisting">
193lib helpers : helpers.cpp : : : &lt;include&gt;. ;
194</pre>
195<p>
196        then the compiler include path for all targets that use
197        <code class="computeroutput">helpers</code> will contain the directory
198       
199        where the target is defined.path to "helpers.cpp". The user
200        only needs to add <code class="computeroutput">helpers</code> to the list of sources,
201        and needn't consider the requirements its use imposes on a
202        dependent target. This feature greatly simplifies Jamfiles.
203       
204      </p>
205<div class="note"><table border="0" summary="Note">
206<tr>
207<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
208<th align="left">Note</th>
209</tr>
210<tr><td align="left" valign="top">
211<p>If you don't want shared libraries to include all libraries
212          that are specified in sources (especially statically linked ones),
213          you'd need to use the following:
214</p>
215<pre class="programlisting">
216lib b : a.cpp ;
217lib a : a.cpp : &lt;use&gt;b : : &lt;library&gt;b ;
218</pre>
219<p>
220          This specifies that <code class="computeroutput">a</code> uses <code class="computeroutput">b</code>, and causes
221          all executables that link to <code class="computeroutput">a</code> also link to
222          <code class="computeroutput">b</code>. In this case, even for shared linking, the
223          <code class="computeroutput">a</code> library won't even refer to <code class="computeroutput">b</code>.
224        </p>
225</td></tr>
226</table></div>
227</div>
228<div class="section" lang="en">
229<div class="titlepage"><div><div><h3 class="title">
230<a name="bbv2.tasks.alias"></a>Alias</h3></div></div></div>
231<p>
232        The <code class="computeroutput">alias</code> rule gives alternative name to
233        a group of targets. For example, to give the name
234        <code class="filename">core</code> to a group of three other targets with the
235        following code:
236        </p>
237<pre class="programlisting">
238alias core : im reader writer ;</pre>
239<p>
240        Using <code class="filename">core</code> on the command line, or in the source list
241        of any other target is the same as explicitly using
242        <code class="filename">im</code>, <code class="filename">reader</code>, and
243        <code class="filename">writer</code>, but it is just more convenient.
244
245      </p>
246<p>
247        Another use of the <code class="computeroutput">alias</code> rule is to change build
248        properties. For example, if you always want static linking for a
249        specific C++ Boost library, you can write the following:
250</p>
251<pre class="programlisting">
252alias threads : /boost/thread//boost_thread : &lt;link&gt;static ;
253</pre>
254<p>
255        and use only the <code class="computeroutput">threads</code> alias in your Jamfiles.
256       
257      </p>
258<p>
259        You can also specify usage requirements for the
260        <code class="computeroutput">alias</code> target. If you write the following:
261</p>
262<pre class="programlisting">
263alias header_only_library : : : :  &lt;include&gt;/usr/include/header_only_library ;
264</pre>
265<p>
266        then using <code class="computeroutput">header_only_library</code> in sources will only add an
267        include path. Also note that when there are some sources, their usage
268        requirements are propagated, too. For example:
269</p>
270<pre class="programlisting">
271lib lib : lib.cpp : : : &lt;include&gt;. ;
272alias lib_alias ;
273exe main : main.cpp lib_alias ;
274</pre>
275<p>
276        will compile <code class="filename">main.cpp</code> with the additional include.
277      </p>
278</div>
279<div class="section" lang="en">
280<div class="titlepage"><div><div><h3 class="title">
281<a name="bbv2.tasks.installing"></a>Installing</h3></div></div></div>
282<p>This section describes various ways to install built target
283      and arbitrary files.</p>
284<h4>
285<a name="id2122699"></a>Basic install</h4>
286<p>For installing a built target you should use the
287        <code class="computeroutput">install</code> rule, which follows the <a href="advanced.html#bbv2.main-target-rule-syntax">common syntax</a>. For
288        example:
289</p>
290<pre class="programlisting">
291install dist : hello helpers ;
292</pre>
293<p>
294        will cause the targets <code class="computeroutput">hello</code> and <code class="computeroutput">helpers</code> to
295        be moved to the <code class="filename">dist</code> directory, relative to
296        Jamfile's directory. The directory can
297        be changed with the <code class="computeroutput">location</code> property:
298</p>
299<pre class="programlisting">
300install dist : hello helpers : &lt;location&gt;/usr/bin ;
301</pre>
302<p>
303        While you can achieve the same effect by changing the target name to
304        <code class="filename">/usr/bin</code>, using the <code class="computeroutput">location</code>
305        property is better, because it allows you to use a mnemonic target
306        name.
307      </p>
308<p>The <code class="computeroutput">location</code> property is especially handy when the location
309        is not fixed, but depends on build variant or environment variables:
310</p>
311<pre class="programlisting">
312install dist : hello helpers : &lt;variant&gt;release:&lt;location&gt;dist/release
313                             &lt;variant&gt;debug:&lt;location&gt;dist/debug ;
314install dist2 : hello helpers : &lt;location&gt;$(DIST) ;
315</pre>
316<p> 
317        See also <a href="reference.html#bbv2.reference.variants.propcond" title="Conditional properties">conditional
318          properties</a> and <a href="faq.html#bbv2.faq.envar" title="
319      Accessing environment variables
320      ">environment variables</a>
321      </p>
322<h4>
323<a name="id2122813"></a>Installing with all dependencies</h4>
324<p>
325        Specifying the names of all libraries to install can be boring. The
326        <code class="computeroutput">install</code> allows you to specify only the top-level executable
327        targets to install, and automatically install all dependencies:
328</p>
329<pre class="programlisting">
330install dist : hello
331           : &lt;install-dependencies&gt;on &lt;install-type&gt;EXE
332             &lt;install-type&gt;LIB
333           ;
334</pre>
335<p>
336        will find all targets that <code class="computeroutput">hello</code> depends on, and install
337        all of those which are either executables or libraries. More
338        specifically, for each target, other targets that were specified as
339        sources or as dependency properties, will be recursively found.  One
340        exception is that targets referred with the <a href="reference.html#bbv2.builtin.features.use"><code class="computeroutput">use</code></a> feature
341        are not considered, because that feature is typically used to refer to
342        header-only libraries.
343        If the set of target types is specified, only targets of that type
344        will be installed, otherwise, all found target will be installed.
345      </p>
346<h4>
347<a name="id2122866"></a>Preserving Directory Hierarchy</h4>
348<p>By default, the <code class="computeroutput">install</code> rules will stip paths from
349      it's sources. So, if sources include <code class="filename">a/b/c.hpp</code>,
350      the <code class="filename">a/b</code> part will be ignored. To make the
351      <code class="computeroutput">install</code> rule preserve the directory hierarchy you need
352      to use the <code class="computeroutput">install-source-root</code> feature to specify the
353      root of the hierarchy you are installing. Relative paths from that
354      root will be preserved. For example, if you write:
355
356</p>
357<pre class="programlisting">
358install headers
359    : a/b/c.h
360    : &lt;location&gt;/tmp &lt;install-source-root&gt;a
361    ;
362</pre>
363<p>
364
365      the a file named <code class="filename">/tmp/b/c.h</code> will be created.
366      </p>
367<h4>
368<a name="id2122924"></a>Installing into Several Directories</h4>
369<p>The <a href="tasks.html#bbv2.tasks.alias" title="Alias"><code class="computeroutput">alias</code></a>
370      rule can be used when targets must be installed into several
371      directories:
372</p>
373<pre class="programlisting">
374alias install : install-bin install-lib ;
375install install-bin : applications : /usr/bin ;
376install install-lib : helper : /usr/lib ;
377</pre>
378<p>
379    </p>
380<p>Because the <code class="computeroutput">install</code> rule just copies targets, most
381    free features <sup>[<a name="id2122959" href="#ftn.id2122959">7</a>]</sup>
382    have no effect when used in requirements of the <code class="computeroutput">install</code> rule.
383    The only two which matter are 
384    <a href="reference.html#bbv2.builtin.features.dependency">
385    <code class="varname">dependency</code></a> and, on Unix,
386    <a href="reference.html#bbv2.reference.features.dll-path"><code class="varname">dll-path</code></a>.
387    </p>
388<div class="note"><table border="0" summary="Note">
389<tr>
390<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
391<th align="left">Note</th>
392</tr>
393<tr><td align="left" valign="top"><p>
394        (Unix specific). On Unix, executables built with Boost.Build typically
395        contain the list of paths to all used dynamic libraries. For
396        installing, this is not desired, so Boost.Build relinks the executable
397        with an empty list of paths. You can also specify additional paths for
398        installed executables with the <code class="varname">dll-path</code> feature.
399      </p></td></tr>
400</table></div>
401</div>
402<div class="section" lang="en">
403<div class="titlepage"><div><div><h3 class="title">
404<a name="bbv2.builtins.testing"></a>Testing</h3></div></div></div>
405<p>Boost.Build has convenient support for running unit tests. The
406        simplest way is the <code class="computeroutput">unit-test</code> rule, which follows the
407        <a href="advanced.html#bbv2.main-target-rule-syntax">common syntax</a>. For
408        example:
409</p>
410<pre class="programlisting">
411unit-test helpers_test : helpers_test.cpp helpers ;
412</pre>
413<p>
414      </p>
415<p>The <code class="computeroutput">unit-test</code> rule behaves like the
416        <code class="computeroutput">exe</code> rule, but after the executable is created it is
417        run. If the executable returns an error code, the build system will also
418        return an error and will try running the executable on the next
419        invocation until it runs successfully. This behaviour ensures that you
420        can't miss a unit test failure.
421      </p>
422<p>By default, the executable is run directly. Sometimes, it's
423      desirable to run the executable using some helper command. You should use the
424      <code class="literal">testing.launcher</code> property to specify the name of the
425      helper command. For example, if you write:
426      </p>
427<pre class="programlisting">
428unit-test helpers_test
429   : helpers_test.cpp helpers
430   : <span class="bold"><strong>&lt;testing.launcher&gt;valgrind</strong></span>
431   ; 
432</pre>
433<p>The command used to run the executable will be:</p>
434<pre class="screen">
435<span class="bold"><strong>valgrind</strong></span> bin/$toolset/debug/helpers_test
436</pre>
437<p>There are few specialized testing rules, listed below:
438      </p>
439<pre class="programlisting">
440rule compile ( sources : requirements * : target-name ? )
441rule compile-fail ( sources : requirements * : target-name ? )
442rule link ( sources + : requirements * : target-name ? )
443rule link-fail ( sources + : requirements * : target-name ? )
444      </pre>
445<p>
446      They are are given a list of sources and requirements.
447      If the target name is not provided, the name of the first
448      source file is used instead. The <code class="literal">compile*</code>
449      tests try to compile the passed source. The <code class="literal">link*</code>
450      rules try to compile and link an application from all the passed sources.
451      The <code class="literal">compile</code> and <code class="literal">link</code> rules expect
452      that compilation/linking succeeds. The <code class="literal">compile-fail</code>
453      and <code class="literal">link-fail</code> rules, on the opposite, expect that
454      the compilation/linking fails.
455      </p>
456<p>There are two specialized rules for running applications, which
457      are more powerful than the <code class="computeroutput">unit-test</code> rule. The
458      <code class="computeroutput">run</code> rule has the following signature:
459      </p>
460<pre class="programlisting">
461rule run ( sources + : args * : input-files * : requirements * : target-name ?
462    : default-build * )
463      </pre>
464<p>
465      The rule builds application from the provided sources and runs it,
466      passing <code class="varname">args</code> and <code class="varname">input-files</code>
467      as command-line arguments. The <code class="varname">args</code> parameter
468      is passed verbatim and the values of the <code class="varname">input-files</code>
469      parameter are treated as paths relative to containing Jamfile, and are
470      adjusted if <span><strong class="command">bjam</strong></span> is invoked from a different
471      directory. The <code class="computeroutput">run-fail</code> rule is identical to the
472      <code class="computeroutput">run</code> rule, except that it expects that the run fails.
473      </p>
474<p>All rules described in this section, if executed successfully,
475      create a special manifest file to indicate that the test passed.
476      For the <code class="computeroutput">unit-test</code> rule the files is named
477      <code class="filename"><em class="replaceable"><code>target-name</code></em>.passed</code> and
478      for the other rules it is called
479      <code class="filename"><em class="replaceable"><code>target-name</code></em>.test</code>.
480      The <code class="computeroutput">run*</code> rules also capture all output from the program,
481      and store it in a file named
482      <code class="filename"><em class="replaceable"><code>target-name</code></em>.output</code>.</p>
483<p>The <code class="computeroutput">run</code> and the <code class="computeroutput">run-fail</code> rules, if
484      the test passes, automatically delete the linked executable, to
485      save space. This behaviour can be suppressed by passing the
486      <code class="literal">--preserve-test-targets</code> command line option.</p>
487<p>It is possible to print the list of all test targets (except for
488      <code class="computeroutput">unit-test</code>) declared in your project, by passing
489      the <code class="literal">--dump-tests</code> command-line option. The output
490      will consist of lines of the form:
491      </p>
492<pre class="screen">
493boost-test(<em class="replaceable"><code>test-type</code></em>) <em class="replaceable"><code>path</code></em> : <em class="replaceable"><code>sources</code></em> 
494      </pre>
495<p>     
496      </p>
497<p>It is possible to process the list of tests, the output of
498      bjam during command run, and the presense/absense of the
499      <code class="filename">*.test</code> files created when test passes into
500      human-readable status table of tests. Such processing utilities
501      are not included in Boost.Build.</p>
502</div>
503<div class="section" lang="en">
504<div class="titlepage"><div><div><h3 class="title">
505<a name="bbv2.builtins.raw"></a>Custom commands</h3></div></div></div>
506<p>When you use most of main target rules, Boost.Build automatically
507      figures what commands to run and it what order. As soon as you want
508      to use new file types, or support new tools, one approach is to
509      extend Boost.Build to smoothly support them, as documented in
510      <a href="extender.html" title="Extender Manual">the section called &#8220;Extender Manual&#8221;</a>. However, if there's a single
511      place where the new tool is used, it might be easier to just
512      explicitly specify the commands to run.</p>
513<p>Three main target rules can be used for that. The
514      <code class="computeroutput">make</code> rule allows you to construct
515      a single file from any number of source file, by running a
516      command you specify. The <code class="computeroutput">notfile</code> rule
517      allows you to run an arbitrary command, without creating any files.
518      Finaly, the <code class="computeroutput">generate</code> rule allows you
519      to describe transformation using Boost.Build's virtual targets.
520      This is higher-level than file names that the make rule operates with,
521      and allows you to create more than one target, or create differently
522      named targets depending on properties, or use more than one
523      tool.</p>
524<p>The <code class="computeroutput">make</code> rule is used when you want to
525      create one file from a number of sources using some specific command.
526      The <code class="computeroutput">notfile</code> is used to unconditionally run
527      a command.
528      </p>
529<p>
530        Suppose you want to create file <code class="filename">file.out</code> from
531        file <code class="filename">file.in</code> by running command
532        <span><strong class="command">in2out</strong></span>. Here's how you'd do this in Boost.Build:
533</p>
534<pre class="programlisting">
535actions in2out
536{
537    in2out $(&lt;) $(&gt;)
538}
539make file.out : file.in : @in2out ;
540</pre>
541<p>
542        If you run <span><strong class="command">bjam</strong></span> and <code class="filename">file.out</code> 
543        does not exist, Boost.Build will run the <span><strong class="command">in2out</strong></span>
544        command to create that file. For more details on specifying actions,
545        see <a href="advanced.html#bbv2.advanced.jam_language.actions">the section called &#8220;Boost.Jam Language&#8221;</a>.
546      </p>
547<p>
548        It could be that you just want to run some command unconditionally,
549        and that command does not create any specific files. The, you can use
550        the <code class="computeroutput">notfile</code> rule. For example:
551</p>
552<pre class="programlisting">
553notfile echo_something : @echo ;
554actions echo
555{
556    echo "something"
557}
558</pre>
559<p>
560        The only difference from the <code class="computeroutput">make</code> rule is
561        that the name of the target is not considered a name of a file, so
562        Boost.Build will unconditionally run the action.
563      </p>
564<p>The <code class="computeroutput">generate</code> rule is used when
565      you want to express transformations using Boost.Build's virtual targets,
566      as opposed to just filenames. The <code class="computeroutput">generate</code>
567      rule has the standard main target rule signature, but you are required
568      to specify the <code class="literal">generating-rule</code> property. The value
569      of the property should be in the form
570      <code class="literal">@<em class="replaceable"><code>rule-name</code></em></code> and the named
571      rule should have the following signature:
572      </p>
573<pre class="programlisting">
574rule generating-rule ( project name : property-set : sources * )
575      </pre>
576<p>
577      and will be called with an instance of the <code class="computeroutput">project-target</code> 
578      class, the name of the main target, an instance of the
579      <code class="computeroutput">property-set</code> class containing build properties,
580      and the list of instances of the <code class="computeroutput">virtual-target</code> class
581      corresponding to sources.
582      The rule must return a list of <code class="computeroutput">virtual-target</code> instances.
583      The interface of the <code class="computeroutput">virtual-target</code> class can be learned
584      by looking at the <code class="filename">build/virtual-target.jam</code> file.
585      The <code class="filename">generate</code> example in Boost.Build distribution
586      illustrates how the <code class="literal">generate</code> rule can be used.
587      </p>
588</div>
589<div class="section" lang="en">
590<div class="titlepage"><div><div><h3 class="title">
591<a name="bbv2.reference.precompiled_headers"></a>Precompiled Headers</h3></div></div></div>
592<p>Precompiled headers is a mechanism to speed up compilation
593      by creating a partially processed version of some header files,
594      and then using that version during compilations rather then
595      repeatedly parsing the original headers. Boost.Build supports
596      precompiled headers with gcc and msvc toolsets.</p>
597<p>To use precompiled headers, follow these steps:</p>
598<div class="orderedlist"><ol type="1">
599<li><p>Create a header that includes big headers used by your project.
600        It's better to include only headers that are sufficiently stable &#8212;
601        like headers from the compiler, and external libraries. Please wrap
602        the header in <code class="computeroutput">#ifdef BOOST_BUILD_PCH_ENABLED</code>, so that
603        the potentially expensive inclusion of headers is not done
604        when PCH is not enabled. Include the new header at the top of your
605        source files.</p></li>
606<li>
607<p>Declare a new Boost.Build target for the precompiled header
608        and add that precompiled header to the sources of the target whose compilation
609        you want to speed up:
610        </p>
611<pre class="programlisting">
612cpp-pch pch : header.hpp ;
613exe main : main.cpp pch ;</pre>
614<p>
615        You can use the <code class="computeroutput">c-pch</code> if you want to use the precompiled
616        header in C programs.
617        </p>
618</li>
619</ol></div>
620<p>The <code class="filename">pch</code> example in Boost.Build distribution
621      can be used as reference.</p>
622<p>Please note the following:</p>
623<div class="itemizedlist"><ul type="disc">
624<li><p>The inclusion of the precompiled header must be the
625        first thing in a source file, before any code or preprocessor directives.
626        </p></li>
627<li><p>The build properties used to compile the source files
628        and  the precompiled header must be the same. Consider using
629        project requirements to assure this.
630        </p></li>
631<li><p>Precompiled headers must be used purely as a way to
632        improve compilation time, not to save the number of <code class="computeroutput">#include</code>
633        statements. If a source file needs to include some header, explicitly include
634        it in the source file, even if the same header is included from
635        the precompiled header. This makes sure that your project will build
636        even if precompiled headers are not supported.</p></li>
637</ul></div>
638</div>
639<div class="section" lang="en">
640<div class="titlepage"><div><div><h3 class="title">
641<a name="bbv2.reference.generated_headers"></a>Generated headers</h3></div></div></div>
642<p>Usually, Boost.Build handles implicit dependendies completely
643        automatically. For example, for C++ files, all <code class="literal">#include</code>
644        statements are found and handled. The only aspect where user help
645        might be needed is implicit dependency on generated files.</p>
646<p>By default, Boost.Build handles such dependencies within one
647        main target. For example, assume that main target "app" has two
648        sources, "app.cpp" and "parser.y". The latter source is converted
649        into "parser.c" and "parser.h". Then, if "app.cpp" includes
650        "parser.h", Boost.Build will detect this dependency. Moreover,
651        since "parser.h" will be generated into a build directory, the
652        path to that directory will automatically added to include
653        path.</p>
654<p>Making this mechanism work across main target boundaries is
655        possible, but imposes certain overhead. For that reason, if
656        there's implicit dependency on files from other main targets, the
657        <code class="literal">&lt;implicit-dependency&gt;</code> [ link ] feature must
658        be used, for example:</p>
659<pre class="programlisting">
660lib parser : parser.y ;
661exe app : app.cpp : &lt;implicit-dependency&gt;parser ;
662</pre>
663<p>
664        The above example tells the build system that when scanning
665        all sources of "app" for implicit-dependencies, it should consider
666        targets from "parser" as potential dependencies.
667      </p>
668</div>
669<div class="footnotes">
670<br><hr width="100" align="left">
671<div class="footnote"><p><sup>[<a name="ftn.id2122959" href="#id2122959">7</a>] </sup>see the definition of "free" in <a href="reference.html#bbv2.reference.features.attributes" title="Feature Attributes">the section called &#8220;Feature Attributes&#8221;</a>.</p></div>
672</div>
673</div>
674<table width="100%"><tr>
675<td align="left"></td>
676<td align="right"><small></small></td>
677</tr></table>
678<hr>
679<div class="spirit-nav">
680<a accesskey="p" href="advanced.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="extender.html"><img src="../images/next.png" alt="Next"></a>
681</div>
682</body>
683</html>
Note: See TracBrowser for help on using the repository browser.