1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Common tasks</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../bbv2.html" title="Chapter 49. Boost.Build User Manual">
<link rel="prev" href="overview.html" title="Overview">
<link rel="next" href="util.html" title="Utilities">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
<td align="center"><a href="../../../index.html">Home</a></td>
<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="overview.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../bbv2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="util.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="bbv2.tasks"></a>Common tasks</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="tasks.html#bbv2.tasks.programs">Programs</a></span></dt>
<dt><span class="section"><a href="tasks.html#bbv2.tasks.libraries">Libraries</a></span></dt>
<dt><span class="section"><a href="tasks.html#bbv2.tasks.alias">Alias</a></span></dt>
<dt><span class="section"><a href="tasks.html#bbv2.tasks.installing">Installing</a></span></dt>
<dt><span class="section"><a href="tasks.html#bbv2.builtins.testing">Testing</a></span></dt>
<dt><span class="section"><a href="tasks.html#bbv2.builtins.raw">Custom commands</a></span></dt>
<dt><span class="section"><a href="tasks.html#bbv2.reference.precompiled_headers">Precompiled Headers</a></span></dt>
<dt><span class="section"><a href="tasks.html#bbv2.reference.generated_headers">Generated headers</a></span></dt>
<dt><span class="section"><a href="tasks.html#bbv2.tasks.crosscompile">Cross-compilation</a></span></dt>
</dl></div>
<p>
This section describes main targets types that Boost.Build supports
out-of-the-box. Unless otherwise noted, all mentioned main target rules have
the common signature, described in <a class="xref" href="overview.html#bbv2.overview.targets" title="Declaring Targets">the section called “Declaring Targets”</a>.
</p>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.tasks.programs"></a>Programs</h3></div></div></div>
<a class="indexterm" name="idp617949776"></a><p>
Programs are created using the <code class="computeroutput">exe</code> rule, which follows the
<a class="link" href="overview.html#bbv2.main-target-rule-syntax">common syntax</a>. For
example:
</p>
<pre class="programlisting">
exe hello : hello.cpp some_library.lib /some_project//library
: <threading>multi
;
</pre>
<p>
This will create an executable file from the sources—in this case, one
C++ file, one library file present in the same directory, and another
library that is created by Boost.Build. Generally, sources can include C
and C++ files, object files and libraries. Boost.Build will automatically
try to convert targets of other types.
</p>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../doc/src/images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top"><p>
On Windows, if an application uses shared libraries, and both the
application and the libraries are built using Boost.Build, it is not
possible to immediately run the application, because the <code class="literal">PATH
</code> environment variable should include the path to the
libraries. It means you have to either add the paths manually, or have
the build place the application and the libraries into the same
directory. See <a class="xref" href="tasks.html#bbv2.tasks.installing" title="Installing">the section called “Installing”</a>.
</p></td></tr>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.tasks.libraries"></a>Libraries</h3></div></div></div>
<a class="indexterm" name="idp617958256"></a><p>
Library targets are created using the <code class="computeroutput">lib</code> rule, which
follows the <a class="link" href="overview.html#bbv2.main-target-rule-syntax">common syntax
</a>. For example:
</p>
<pre class="programlisting">
lib helpers : helpers.cpp ;
</pre>
<p>
This will define a library target named <code class="computeroutput">helpers</code> built from
the <code class="computeroutput">helpers.cpp</code> source file.
It can be either a static library or a shared library,
depending on the value of the <a class="link" href="reference.html#bbv2.overview.builtins.features.link"><link></a> feature.
</p>
<p>
Library targets can represent:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>
Libraries that should be built from source,
as in the example above.
</p></li>
<li class="listitem"><p>
Prebuilt libraries which already exist on the system.
Such libraries can be searched for by the tools using them (typically
with the linker's <code class="option">-l</code> option) or their paths can be
known in advance by the build system.
</p></li>
</ul></div>
<p>
</p>
<p>
The syntax for prebuilt libraries is given below:
</p>
<pre class="programlisting">
lib z : : <name>z <search>/home/ghost ;
lib compress : : <file>/opt/libs/compress.a ;
</pre>
<p>
The <code class="computeroutput">name</code> property specifies the name of the library
without the standard prefixes and suffixes. For example, depending
on the system, <code class="computeroutput">z</code> could refer to a file called
z.so, libz.a, or z.lib, etc. The <code class="computeroutput">search</code> feature
specifies paths in which to search for the library in addition
to the default compiler paths. <code class="computeroutput">search</code> can be specified
several times or it can be omitted, in which case only the default
compiler paths will be searched. The <code class="computeroutput">file</code> property
specifies the file location.
</p>
<p>
The difference between using the <code class="computeroutput">file</code> feature and
using a combination of the <code class="computeroutput">name</code> and <code class="computeroutput">search</code>
features is that <code class="computeroutput">file</code> is more precise.
</p>
<div class="warning"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/src/images/warning.png"></td>
<th align="left">Warning</th>
</tr>
<tr><td align="left" valign="top">
<p>
The value of the <code class="computeroutput">search</code> feature is just added to the
linker search path. When linking to multiple libraries,
the paths specified by <code class="computeroutput">search</code> are combined without
regard to which <code class="computeroutput">lib</code> target each path came from.
Thus, given
</p>
<pre class="programlisting">
lib a : : <name>a <search>/pool/release ;
lib b : : <name>b <search>/pool/debug ;
</pre>
<p>
If /pool/release/a.so, /pool/release/b.so, /pool/debug/a.so,
and /pool/release/b.so all exist, the linker will probably
take both <code class="computeroutput">a</code> and <code class="computeroutput">b</code> from the same
directory, instead of finding <code class="computeroutput">a</code> in /pool/release
and <code class="computeroutput">b</code> in /pool/debug. If you need to distinguish
between multiple libraries with the same name, it's safer
to use <code class="computeroutput">file</code>.
</p>
</td></tr>
</table></div>
<p>
</p>
<p>
For convenience, the following syntax is allowed:
</p>
<pre class="programlisting">
lib z ;
lib gui db aux ;
</pre>
<p>
which has exactly the same effect as:
</p>
<pre class="programlisting">
lib z : : <name>z ;
lib gui : : <name>gui ;
lib db : : <name>db ;
lib aux : : <name>aux ;
</pre>
<p>
</p>
<p>
When a library references another library you should put that other
library in its list of sources. This will do the right thing in all cases.
For portability, you should specify
library dependencies even for searched and prebuilt libraries, othewise,
static linking on Unix will not work. For example:
</p>
<pre class="programlisting">
lib z ;
lib png : z : <name>png ;
</pre>
<p>
</p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top">
<p>
When a library has a shared library as a source, or a static
library has another static library as a source then any target
linking to the first library with automatically link to its source
library as well.
</p>
<p>
On the other hand, when a shared library has a static library as
a source then the first library will be built so that it completely
includes the second one.
</p>
<p>
If you do not want a shared library to include all the libraries specified
in its sources (especially statically linked ones), you would need to
use the following:
</p>
<pre class="programlisting">
lib b : a.cpp ;
lib a : a.cpp : <use>b : : <library>b ;
</pre>
<p>
This specifies that library <code class="computeroutput">a</code> uses library <code class="computeroutput">b</code>,
and causes all executables that link to <code class="computeroutput">a</code> to link to
<code class="computeroutput">b</code> also. In this case, even for shared linking, the
<code class="computeroutput">a</code> library will not refer to <code class="computeroutput">b</code>.
</p>
</td></tr>
</table></div>
<p>
<a class="link" href="overview.html#bbv2.overview.targets" title="Declaring Targets">Usage requirements</a> are often
very useful for defining library targets. For example, imagine that
you want you build a <code class="computeroutput">helpers</code> library and its interface is
described in its <code class="computeroutput">helpers.hpp</code> header file located in the same
directory as the <code class="computeroutput">helpers.cpp</code> source file. Then you could add
the following to the Jamfile located in that same directory:
</p>
<pre class="programlisting">
lib helpers : helpers.cpp : : : <include>. ;
</pre>
<p>
which would automatically add the directory where the target has been
defined (and where the library's header file is located) to the compiler's
include path for all targets using the <code class="computeroutput">helpers</code> library. This
feature greatly simplifies Jamfiles.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.tasks.alias"></a>Alias</h3></div></div></div>
<p>
The <code class="computeroutput">alias</code> rule gives an alternative name to a
group of targets. For example, to give the name <code class="filename">core</code>
to a group of three other targets with the following code:
</p>
<pre class="programlisting">
alias core : im reader writer ;
</pre>
<p>
Using <code class="filename">core</code> on the command line, or in the source list
of any other target is the same as explicitly using <code class="filename">im
</code>, <code class="filename">reader</code>, and <code class="filename">writer</code>.
</p>
<p>
Another use of the <code class="computeroutput">alias</code> rule is to change build properties.
For example, if you want to use link statically to the Boost Threads
library, you can write the following:
</p>
<pre class="programlisting">
alias threads : /boost/thread//boost_thread : <link>static ;
</pre>
<p>
and use only the <code class="computeroutput">threads</code> alias in your Jamfiles.
</p>
<p>
You can also specify usage requirements for the <code class="computeroutput">alias</code> target.
If you write the following:
</p>
<pre class="programlisting">
alias header_only_library : : : : <include>/usr/include/header_only_library ;
</pre>
<p>
then using <code class="computeroutput">header_only_library</code> in sources will only add an
include path. Also note that when an alias has sources, their usage
requirements are propagated as well. For example:
</p>
<pre class="programlisting">
lib library1 : library1.cpp : : : <include>/library/include1 ;
lib library2 : library2.cpp : : : <include>/library/include2 ;
alias static_libraries : library1 library2 : <link>static ;
exe main : main.cpp static_libraries ;
</pre>
<p>
will compile <code class="filename">main.cpp</code> with additional includes
required for using the specified static libraries.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.tasks.installing"></a>Installing</h3></div></div></div>
<p>
This section describes various ways to install built target and arbitrary
files.
</p>
<h4>
<a name="idp618016992"></a>Basic install</h4>
<p>
For installing a built target you should use the <code class="computeroutput">install</code>
rule, which follows the <a class="link" href="overview.html#bbv2.main-target-rule-syntax">
common syntax</a>. For example:
</p>
<pre class="programlisting">
install dist : hello helpers ;
</pre>
<p>
will cause the targets <code class="computeroutput">hello</code> and <code class="computeroutput">helpers</code> to be
moved to the <code class="filename">dist</code> directory, relative to the
Jamfile's directory. The directory can be changed using the
<code class="computeroutput">location</code> property:
</p>
<pre class="programlisting">
install dist : hello helpers : <location>/usr/bin ;
</pre>
<p>
While you can achieve the same effect by changing the target name to
<code class="filename">/usr/bin</code>, using the <code class="computeroutput">location</code> property is
better as it allows you to use a mnemonic target name.
</p>
<p>
The <code class="computeroutput">location</code> property is especially handy when the location
is not fixed, but depends on the build variant or environment variables:
</p>
<pre class="programlisting">
install dist : hello helpers :
<variant>release:<location>dist/release
<variant>debug:<location>dist/debug ;
install dist2 : hello helpers : <location>$(DIST) ;
</pre>
<p>
See also <a class="link" href="reference.html#bbv2.reference.variants.propcond" title="Conditional properties">conditional
properties</a> and <a class="link" href="faq.html#bbv2.faq.envar" title="Accessing environment variables">environment
variables</a>
</p>
<h4>
<a name="idp618029632"></a>Installing with all dependencies</h4>
<p>
Specifying the names of all libraries to install can be boring. The
<code class="computeroutput">install</code> allows you to specify only the top-level executable
targets to install, and automatically install all dependencies:
</p>
<pre class="programlisting">
install dist : hello
: <install-dependencies>on <install-type>EXE
<install-type>LIB
;
</pre>
<p>
will find all targets that <code class="computeroutput">hello</code> depends on, and install all
of those which are either executables or libraries. More specifically, for
each target, other targets that were specified as sources or as dependency
properties, will be recursively found. One exception is that targets
referred with the <a class="link" href="reference.html#bbv2.builtin.features.use">
<code class="computeroutput">use</code></a> feature are not considered, as that feature is
typically used to refer to header-only libraries. If the set of target
types is specified, only targets of that type will be installed,
otherwise, all found target will be installed.
</p>
<h4>
<a name="idp618034960"></a>Preserving Directory Hierarchy</h4>
<a class="indexterm" name="idp618035344"></a><p>
By default, the <code class="computeroutput">install</code> rule will strip paths from its
sources. So, if sources include <code class="filename">a/b/c.hpp</code>, the
<code class="filename">a/b</code> part will be ignored. To make the
<code class="computeroutput">install</code> rule preserve the directory hierarchy you need to
use the <code class="literal"><install-source-root></code> feature to specify
the root of the hierarchy you are installing. Relative paths from that
root will be preserved. For example, if you write:
</p>
<pre class="programlisting">
install headers
: a/b/c.h
: <location>/tmp <install-source-root>a
;
</pre>
<p>
the a file named <code class="filename">/tmp/b/c.h</code> will be created.
</p>
<p>
The <a class="link" href="reference.html#bbv2.reference.glob-tree">glob-tree</a> rule can be
used to find all files below a given directory, making it easy to install
an entire directory tree.
</p>
<h4>
<a name="idp618043728"></a>Installing into Several Directories</h4>
<p>
The <a class="link" href="tasks.html#bbv2.tasks.alias" title="Alias"><code class="computeroutput">alias</code></a> rule can be
used when targets need to be installed into several directories:
</p>
<pre class="programlisting">
alias install : install-bin install-lib ;
install install-bin : applications : /usr/bin ;
install install-lib : helper : /usr/lib ;
</pre>
<p>
</p>
<p>
Because the <code class="computeroutput">install</code> rule just copies targets, most free
features <a href="#ftn.idp618047664" class="footnote" name="idp618047664"><sup class="footnote">[34]</sup></a> have no
effect when used in requirements of the <code class="computeroutput">install</code> rule. The
only two that matter are <a class="link" href="reference.html#bbv2.builtin.features.dependency">
<code class="varname">dependency</code></a> and, on Unix, <a class="link" href="reference.html#bbv2.reference.features.dll-path"><code class="varname">dll-path</code>
</a>.
</p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
(Unix specific) On Unix, executables built using Boost.Build typically
contain the list of paths to all used shared libraries. For installing,
this is not desired, so Boost.Build relinks the executable with an empty
list of paths. You can also specify additional paths for installed
executables using the <code class="varname">dll-path</code> feature.
</p></td></tr>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.builtins.testing"></a>Testing</h3></div></div></div>
<p>
Boost.Build has convenient support for running unit tests. The simplest
way is the <code class="computeroutput">unit-test</code> rule, which follows the <a class="link" href="overview.html#bbv2.main-target-rule-syntax">common syntax</a>. For example:
</p>
<pre class="programlisting">
unit-test helpers_test : helpers_test.cpp helpers ;
</pre>
<p>
</p>
<p>
The <code class="computeroutput">unit-test</code> rule behaves like the
<a class="link" href="tasks.html#bbv2.tasks.programs" title="Programs">exe</a> rule, but after the executable is created
it is also run. If the executable returns an error code, the build system
will also return an error and will try running the executable on the next
invocation until it runs successfully. This behaviour ensures that you can
not miss a unit test failure.
</p>
<p>
There are few specialized testing rules, listed below:
</p>
<pre class="programlisting">
rule compile ( sources : requirements * : target-name ? )
rule compile-fail ( sources : requirements * : target-name ? )
rule link ( sources + : requirements * : target-name ? )
rule link-fail ( sources + : requirements * : target-name ? )
</pre>
<p>
They are given a list of sources and requirements. If the target name is
not provided, the name of the first source file is used instead. The
<code class="literal">compile*</code> tests try to compile the passed source. The
<code class="literal">link*</code> rules try to compile and link an application from
all the passed sources. The <code class="literal">compile</code> and <code class="literal">link
</code> rules expect that compilation/linking succeeds. The <code class="literal">
compile-fail</code> and <code class="literal">link-fail</code> rules expect that
the compilation/linking fails.
</p>
<p>
There are two specialized rules for running applications, which are more
powerful than the <code class="computeroutput">unit-test</code> rule. The <code class="computeroutput">run</code> rule
has the following signature:
</p>
<pre class="programlisting">
rule run ( sources + : args * : input-files * : requirements * : target-name ?
: default-build * )
</pre>
<p>
The rule builds application from the provided sources and runs it, passing
<code class="varname">args</code> and <code class="varname">input-files</code> as command-line
arguments. The <code class="varname">args</code> parameter is passed verbatim and
the values of the <code class="varname">input-files</code> parameter are treated as
paths relative to containing Jamfile, and are adjusted if <span class="command"><strong>b2</strong></span>
is invoked from a different directory. The
<code class="computeroutput">run-fail</code> rule is identical to the <code class="computeroutput">run</code> rule,
except that it expects that the run fails.
</p>
<p>
All rules described in this section, if executed successfully, create a
special manifest file to indicate that the test passed. For the
<code class="computeroutput">unit-test</code> rule the files is named <code class="filename"><em class="replaceable"><code>
target-name</code></em>.passed</code> and for the other rules it is
called <code class="filename"><em class="replaceable"><code>target-name</code></em>.test</code>.
The <code class="computeroutput">run*</code> rules also capture all output from the program, and
store it in a file named <code class="filename"><em class="replaceable"><code>
target-name</code></em>.output</code>.
</p>
<p>
<a class="indexterm" name="idp618078800"></a>
If the <code class="literal">preserve-test-targets</code> feature has the value
<code class="literal">off</code>, then <code class="computeroutput">run</code> and the <code class="computeroutput">run-fail</code>
rules will remove the executable after running it. This somewhat decreases
disk space requirements for continuous testing environments. The default
value of <code class="literal">preserve-test-targets</code> feature is <code class="literal">on</code>.
</p>
<p>
It is possible to print the list of all test targets (except for
<code class="computeroutput">unit-test</code>) declared in your project, by passing the <code class="literal">
--dump-tests</code> command-line option. The output will consist of
lines of the form:
</p>
<pre class="screen">
boost-test(<em class="replaceable"><code>test-type</code></em>) <em class="replaceable"><code>path</code></em> : <em class="replaceable"><code>sources</code></em>
</pre>
<p>
</p>
<p>
It is possible to process the list of tests, Boost.Build output
and the presense/absense of the <code class="filename">*.test</code>
files created when test passes into human-readable status table of tests.
Such processing utilities are not included in Boost.Build.
</p>
<p>The following features adjust behaviour of the testing metatargets.</p>
<div class="variablelist"><dl class="variablelist">
<dt><span class="term"><code class="literal">testing.arg</code></span></dt>
<dd>
<p>
Defines an argument to be passed to the target when it is executed
before the list of input files.
</p>
<p>
</p>
<pre class="programlisting">
unit-test helpers_test
: helpers_test.cpp helpers
: <span class="bold"><strong><testing.arg>"--foo bar"</strong></span>
;
</pre>
<p>
</p>
</dd>
<dt><span class="term"><code class="literal">testing.input-file</code></span></dt>
<dd><p>
Specifies a file to be passed to the executable on the command line
after the arguments. All files must be specified in alphabetical
order due to constrainsts in the current implementation.
</p></dd>
<dt><span class="term"><code class="literal">testing.launcher</code></span></dt>
<dd>
<p>
By default, the executable is run directly. Sometimes, it is
desirable to run the executable using some helper command. You
should use this property to specify the name of the helper
command. For example, if you write:
</p>
<pre class="programlisting">
unit-test helpers_test
: helpers_test.cpp helpers
: <span class="bold"><strong><testing.launcher>valgrind</strong></span>
;
</pre>
<p>
The command used to run the executable will be:
</p>
<pre class="screen">
<span class="bold"><strong>valgrind</strong></span> bin/$toolset/debug/helpers_test
</pre>
<p>
</p>
</dd>
<dt><span class="term"><code class="literal">test-info</code></span></dt>
<dd><p>
A description of the test. This is displayed as part of the
<code class="literal">--dump-tests</code> command-line option.
</p></dd>
</dl></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.builtins.raw"></a>Custom commands</h3></div></div></div>
<p>
For most main target rules, Boost.Build automatically figures out
the commands to run. When you want to use new
file types or support new tools, one approach is to extend Boost.Build to
support them smoothly, as documented in <a class="xref" href="extender.html" title="Extender Manual">the section called “Extender Manual”</a>.
However, if the new tool is only used in a single place, it
might be easier just to specify the commands to run explicitly.
</p>
<p>
Three main target rules can be used for that. The <code class="computeroutput">make
</code> rule allows you to construct a single file from any number
of source file, by running a command you specify. The <code class="computeroutput">
notfile</code> rule allows you to run an arbitrary command,
without creating any files. And finaly, the <code class="computeroutput">generate
</code> rule allows you to describe a transformation using
Boost.Build's virtual targets. This is higher-level than the file names that
the <code class="computeroutput">make</code> rule operates with and allows you to
create more than one target, create differently named targets depending on
properties, or use more than one tool.
</p>
<p>
The <code class="computeroutput">make</code> rule is used when you want to create
one file from a number of sources using some specific command. The
<code class="computeroutput">notfile</code> is used to unconditionally run a
command.
</p>
<p>
Suppose you want to create the file <code class="filename">file.out</code> from
the file <code class="filename">file.in</code> by running the command <span class="command"><strong>
in2out</strong></span>. Here is how you would do this in Boost.Build:
</p>
<pre class="programlisting">
make file.out : file.in : @in2out ;
actions in2out
{
in2out $(<) $(>)
}
</pre>
<p>
If you run <span class="command"><strong>b2</strong></span> and <code class="filename">file.out</code> does
not exist, Boost.Build will run the <span class="command"><strong>in2out</strong></span> command to
create that file. For more details on specifying actions, see <a class="xref" href="overview.html#bbv2.overview.jam_language.actions">the section called “Boost.Jam Language”</a>.
</p>
<p>
It could be that you just want to run some command unconditionally, and
that command does not create any specific files. For that you can use the
<code class="computeroutput">notfile</code> rule. For example:
</p>
<pre class="programlisting">
notfile echo_something : @echo ;
actions echo
{
echo "something"
}
</pre>
<p>
The only difference from the <code class="computeroutput">make</code> rule is
that the name of the target is not considered a name of a file, so
Boost.Build will unconditionally run the action.
</p>
<p>
The <code class="computeroutput">generate</code> rule is used when you want to
express transformations using Boost.Build's virtual targets, as opposed to
just filenames. The <code class="computeroutput">generate</code> rule has the
standard main target rule signature, but you are required to specify the
<code class="literal">generating-rule</code> property. The value of the property
should be in the form <code class="literal">
@<em class="replaceable"><code>rule-name</code></em></code>, the named rule should
have the following signature:
</p>
<pre class="programlisting">
rule generating-rule ( project name : property-set : sources * )
</pre>
<p>
and will be called with an instance of the <code class="computeroutput">project-target</code>
class, the name of the main target, an instance of the
<code class="computeroutput">property-set</code> class containing build properties, and the list
of instances of the <code class="computeroutput">virtual-target</code> class corresponding to
sources. The rule must return a list of <code class="computeroutput">virtual-target</code>
instances. The interface of the <code class="computeroutput">virtual-target</code> class can be
learned by looking at the <code class="filename">build/virtual-target.jam</code>
file. The <code class="filename">generate</code> example contained in the
Boost.Build distribution illustrates how the <code class="literal">generate</code>
rule can be used.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.reference.precompiled_headers"></a>Precompiled Headers</h3></div></div></div>
<p>
Precompiled headers is a mechanism to speed up compilation by creating a
partially processed version of some header files, and then using that
version during compilations rather then repeatedly parsing the original
headers. Boost.Build supports precompiled headers with gcc and msvc
toolsets.
</p>
<p>
To use precompiled headers, follow the following steps:
</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem"><p>
Create a header that includes headers used by your project that you
want precompiled. It is better to include only headers that are
sufficiently stable — like headers from the compiler and
external libraries. Please wrap the header in <code class="computeroutput">#ifdef
BOOST_BUILD_PCH_ENABLED</code>, so that the potentially expensive
inclusion of headers is not done when PCH is not enabled. Include the
new header at the top of your source files.
</p></li>
<li class="listitem">
<p>
Declare a new Boost.Build target for the precompiled header and add
that precompiled header to the sources of the target whose compilation
you want to speed up:
</p>
<pre class="programlisting">
cpp-pch pch : pch.hpp ;
exe main : main.cpp pch ;
</pre>
<p>
You can use the <code class="computeroutput">c-pch</code> rule if you want to
use the precompiled header in C programs.
</p>
</li>
</ol></div>
<p>
The <code class="filename">pch</code> example in Boost.Build distribution can be
used as reference.
</p>
<p>
Please note the following:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>
The inclusion of the precompiled header must be the first thing in a
source file, before any code or preprocessor directives.
</p></li>
<li class="listitem"><p>
The build properties used to compile the source files and the
precompiled header must be the same. Consider using project
requirements to assure this.
</p></li>
<li class="listitem"><p>
Precompiled headers must be used purely as a way to improve
compilation time, not to save the number of <code class="computeroutput">#include</code>
statements. If a source file needs to include some header, explicitly
include it in the source file, even if the same header is included
from the precompiled header. This makes sure that your project will
build even if precompiled headers are not supported.
</p></li>
<li class="listitem"><p>
On the gcc compiler, the name of the header being precompiled must be
equal to the name of the <code class="computeroutput">cpp-pch</code> target. This is a gcc
requirement.
</p></li>
<li class="listitem"><p>
Prior to version 4.2, the gcc compiler did not allow anonymous
namespaces in precompiled headers, which limits their utility. See the
<a href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=29085" target="_top"> bug
report</a> for details.
</p></li>
</ul></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.reference.generated_headers"></a>Generated headers</h3></div></div></div>
<p>
Usually, Boost.Build handles implicit dependendies completely
automatically. For example, for C++ files, all <code class="literal">#include</code>
statements are found and handled. The only aspect where user help might be
needed is implicit dependency on generated files.
</p>
<p>
By default, Boost.Build handles such dependencies within one main target.
For example, assume that main target "app" has two sources, "app.cpp" and
"parser.y". The latter source is converted into "parser.c" and "parser.h".
Then, if "app.cpp" includes "parser.h", Boost.Build will detect this
dependency. Moreover, since "parser.h" will be generated into a build
directory, the path to that directory will automatically be added to the include
path.
</p>
<p>
Making this mechanism work across main target boundaries is possible, but
imposes certain overhead. For that reason, if there is implicit dependency
on files from other main targets, the <code class="literal"><implicit-dependency>
</code> feature must be used, for example:
</p>
<pre class="programlisting">
lib parser : parser.y ;
exe app : app.cpp : <implicit-dependency>parser ;
</pre>
<p>
The above example tells the build system that when scanning all sources of
"app" for implicit-dependencies, it should consider targets from "parser"
as potential dependencies.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.tasks.crosscompile"></a>Cross-compilation</h3></div></div></div>
<a class="indexterm" name="idp618160912"></a><p>Boost.Build supports cross compilation with the gcc and msvc
toolsets.</p>
<p>
When using gcc, you first need to specify your cross compiler
in <code class="filename">user-config.jam</code> (see <a class="xref" href="overview.html#bbv2.overview.configuration" title="Configuration">the section called “Configuration”</a>),
for example:</p>
<pre class="programlisting">
using gcc : arm : arm-none-linux-gnueabi-g++ ;
</pre>
<p>
After that, if the host and target os are the same, for example Linux, you can
just request that this compiler version be used:
</p>
<pre class="screen">
b2 toolset=gcc-arm
</pre>
<p>
If you want to target a different operating system from the host, you need
to additionally specify the value for the <code class="computeroutput">target-os</code> feature, for
example:
</p>
<pre class="screen">
# On windows box
b2 toolset=gcc-arm <span class="bold"><strong>target-os=linux</strong></span>
# On Linux box
b2 toolset=gcc-mingw <span class="bold"><strong>target-os=windows</strong></span>
</pre>
<p>
For the complete list of allowed opeating system names, please see the documentation for
<a class="link" href="reference.html#bbv2.reference.features.target-os">target-os feature</a>.
</p>
<p>
When using the msvc compiler, it's only possible to cross-compile to a 64-bit system
on a 32-bit host. Please see <a class="xref" href="reference.html#v2.reference.tools.compiler.msvc.64" title="64-bit support">the section called “64-bit support”</a> for
details.
</p>
</div>
<div class="footnotes">
<br><hr style="width:100; text-align:left;margin-left: 0">
<div id="ftn.idp618047664" class="footnote"><p><a href="#idp618047664" class="para"><sup class="para">[34] </sup></a>see the definition of "free" in <a class="xref" href="reference.html#bbv2.reference.features.attributes" title="Feature Attributes">the section called “Feature Attributes”</a>.</p></div>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="overview.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../bbv2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="util.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
|
