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
|
<!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>Frequently Asked Questions</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 48. Boost.Build User Manual">
<link rel="prev" href="extender.html" title="Extender Manual">
<link rel="next" href="../jam.html" title="Chapter 49. Boost.Jam : 3.1.19">
</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="extender.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="../jam.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.faq"></a>Frequently Asked Questions</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="faq.html#bbv2.faq.featurevalue">
How do I get the current value of feature in Jamfile?
</a></span></dt>
<dt><span class="section"><a href="faq.html#bbv2.faq.duplicate">
I am getting a "Duplicate name of actual target" error. What does that
mean?
</a></span></dt>
<dt><span class="section"><a href="faq.html#bbv2.faq.envar">
Accessing environment variables
</a></span></dt>
<dt><span class="section"><a href="faq.html#bbv2.faq.proporder">
How to control properties order?
</a></span></dt>
<dt><span class="section"><a href="faq.html#bbv2.faq.liborder">
How to control the library linking order on Unix?
</a></span></dt>
<dt><span class="section"><a href="faq.html#bbv2.faq.external">
Can I get capture external program output using a Boost.Jam variable?
</a></span></dt>
<dt><span class="section"><a href="faq.html#bbv2.faq.projectroot">
How to get the project root (a.k.a. Jamroot) location?
</a></span></dt>
<dt><span class="section"><a href="faq.html#bbv2.faq.flags">
How to change compilation flags for one file?
</a></span></dt>
<dt><span class="section"><a href="faq.html#bbv2.faq.dll-path">
Why are the <code class="literal">dll-path</code> and <code class="literal">hardcode-dll-paths
</code> properties useful?
</a></span></dt>
<dt><span class="section"><a href="faq.html#bbv2.recipies.site-config">Targets in site-config.jam</a></span></dt>
<dt><span class="section"><a href="faq.html#bbv2.faq.header-only-libraries">Header-only libraries</a></span></dt>
<dt><span class="section"><a href="faq.html#bbv2.faq.names">
What is the difference between Boost.Build,
<code class="filename">b2</code>, <code class="filename">bjam</code> and Perforce Jam?
</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.faq.featurevalue"></a>
How do I get the current value of feature in Jamfile?
</h3></div></div></div>
<p>
This is not possible, since Jamfile does not have "current" value of any
feature, be it toolset, build variant or anything else. For a single
run of Boost.Build, any given main target can be
built with several property sets. For example, user can request two build
variants on the command line. Or one library is built as shared when used
from one application, and as static when used from another. Each Jamfile
is read only once so generally there is no single value of a feature you
can access in Jamfile.
</p>
<p>
A feature has a specific value only when building a target, and there are
two ways you can use that value:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
Use conditional requirements or indirect conditional requirements. See
<a class="xref" href="overview.html#bbv2.overview.targets.requirements.conditional">the section called “Requirements”</a>.
</li>
<li class="listitem">
Define a custom generator and a custom main target type. The custom
generator can do arbitrary processing or properties. See the <a class="xref" href="extender.html" title="Extender Manual">the section called “Extender Manual”</a>.
</li>
</ul></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.faq.duplicate"></a>
I am getting a "Duplicate name of actual target" error. What does that
mean?
</h3></div></div></div>
<p>
The most likely case is that you are trying to compile the same file
twice, with almost the same, but differing properties. For example:
</p>
<pre class="programlisting">
exe a : a.cpp : <include>/usr/local/include ;
exe b : a.cpp ;
</pre>
<p>
</p>
<p>
The above snippet requires two different compilations of
<code class="computeroutput">a.cpp</code>, which differ only in their <code class="literal">include</code>
property. Since the <code class="literal">include</code> feature is declared as
<code class="literal">free</code> Boost.Build does not create a separate build
directory for each of its values and those two builds would both produce
object files generated in the same build directory. Ignoring this and
compiling the file only once would be dangerous as different includes
could potentially cause completely different code to be compiled.
</p>
<p>
To solve this issue, you need to decide if the file should be compiled
once or twice.
</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
<p>
To compile the file only once, make sure that properties are the same
for both target requests:
</p>
<pre class="programlisting">
exe a : a.cpp : <include>/usr/local/include ;
exe b : a.cpp : <include>/usr/local/include ;
</pre>
<p>
or:
</p>
<pre class="programlisting">
alias a-with-include : a.cpp : <include>/usr/local/include ;
exe a : a-with-include ;
exe b : a-with-include ;
</pre>
<p>
or if you want the <code class="literal">includes</code> property not to affect
how any other sources added for the built <code class="computeroutput">a</code> and
<code class="computeroutput">b</code> executables would be compiled:
</p>
<pre class="programlisting">
obj a-obj : a.cpp : <include>/usr/local/include ;
exe a : a-obj ;
exe b : a-obj ;
</pre>
<p>
</p>
<p>
Note that in both of these cases the <code class="literal">include</code>
property will be applied only for building these object files and not
any other sources that might be added for targets <code class="computeroutput">a</code> and
<code class="computeroutput">b</code>.
</p>
</li>
<li class="listitem">
<p>
To compile the file twice, you can tell Boost.Build to compile it to
two separate object files like so:
</p>
<pre class="programlisting">
obj a_obj : a.cpp : <include>/usr/local/include ;
obj b_obj : a.cpp ;
exe a : a_obj ;
exe b : b_obj ;
</pre>
<p>
or you can make the object file targets local to the main target:
</p>
<pre class="programlisting">
exe a : [ obj a_obj : a.cpp : <include>/usr/local/include ] ;
exe b : [ obj a_obj : a.cpp ] ;
</pre>
<p>
which will cause Boost.Build to actually change the generated object
file names a bit for you and thus avoid any conflicts.
</p>
<p>
Note that in both of these cases the <code class="literal">include</code>
property will be applied only for building these object files and not
any other sources that might be added for targets <code class="computeroutput">a</code> and
<code class="computeroutput">b</code>.
</p>
</li>
</ol></div>
<p>
A good question is why Boost.Build can not use some of the above
approaches automatically. The problem is that such magic would only help
in half of the cases, while in the other half it would be silently doing
the wrong thing. It is simpler and safer to ask the user to clarify his
intention in such cases.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.faq.envar"></a>
Accessing environment variables
</h3></div></div></div>
<p>
Many users would like to use environment variables in Jamfiles, for
example, to control the location of external libraries. In many cases it
is better to declare those external libraries in the site-config.jam file,
as documented in the <a class="link" href="faq.html#bbv2.recipies.site-config" title="Targets in site-config.jam">recipes
section</a>. However, if the users already have the environment
variables set up, it may not be convenient for them to set up their
site-config.jam files as well and using the environment variables might be
reasonable.
</p>
<p>
Boost.Jam automatically imports all environment variables into its
built-in .ENVIRON module so user can read them from there directly or by
using the helper os.environ rule. For example:
</p>
<pre class="programlisting">
import os ;
local unga-unga = [ os.environ UNGA_UNGA ] ;
ECHO $(unga-unga) ;
</pre>
<p>
or a bit more realistic:
</p>
<pre class="programlisting">
import os ;
local SOME_LIBRARY_PATH = [ os.environ SOME_LIBRARY_PATH ] ;
exe a : a.cpp : <include>$(SOME_LIBRARY_PATH) ;
</pre>
<p>
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.faq.proporder"></a>
How to control properties order?
</h3></div></div></div>
<p>
For internal reasons, Boost.Build sorts all the properties alphabetically.
This means that if you write:
</p>
<pre class="programlisting">
exe a : a.cpp : <include>b <include>a ;
</pre>
<p>
then the command line with first mention the <code class="computeroutput">a</code> include
directory, and then <code class="computeroutput">b</code>, even though they are specified in the
opposite order. In most cases, the user does not care. But sometimes the
order of includes, or other properties, is important. For such cases, a
special syntax is provided:
</p>
<pre class="programlisting">
exe a : a.cpp : <include>a&&b ;
</pre>
<p>
</p>
<p>
The <code class="computeroutput">&&</code> symbols separate property values and specify
that their order should be preserved. You are advised to use this feature
only when the order of properties really matters and not as a convenient
shortcut. Using it everywhere might negatively affect performance.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.faq.liborder"></a>
How to control the library linking order on Unix?
</h3></div></div></div>
<p>
On Unix-like operating systems, the order in which static libraries are
specified when invoking the linker is important, because by default, the
linker uses one pass though the libraries list. Passing the libraries in
the incorrect order will lead to a link error. Further, this behaviour is
often used to make one library override symbols from another. So,
sometimes it is necessary to force specific library linking order.
</p>
<p>
Boost.Build tries to automatically compute the right order. The primary
rule is that if library <code class="computeroutput">a</code> "uses" library <code class="computeroutput">b</code>, then
library <code class="computeroutput">a</code> will appear on the command line before library
<code class="computeroutput">b</code>. Library <code class="computeroutput">a</code> is considered to use <code class="computeroutput">b</code>
if <code class="computeroutput">b</code> is present either in the <code class="computeroutput">a</code> library's
sources or its usage is listed in its requirements. To explicitly specify
the <code class="literal">use</code> relationship one can use the
<code class="literal"><use></code> feature. For example, both of the following
lines will cause <code class="computeroutput">a</code> to appear before <code class="computeroutput">b</code> on the
command line:
</p>
<pre class="programlisting">
lib a : a.cpp b ;
lib a : a.cpp : <use>b ;
</pre>
<p>
</p>
<p>
The same approach works for searched libraries as well:
</p>
<pre class="programlisting">
lib z ;
lib png : : <use>z ;
exe viewer : viewer png z ;
</pre>
<p>
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.faq.external"></a>
Can I get capture external program output using a Boost.Jam variable?
</h3></div></div></div>
<p>
The <code class="literal">SHELL</code> builtin rule may be used for this purpose:
</p>
<pre class="programlisting">
local gtk_includes = [ SHELL "gtk-config --cflags" ] ;
</pre>
<p>
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.faq.projectroot"></a>
How to get the project root (a.k.a. Jamroot) location?
</h3></div></div></div>
<p>
You might want to use your project's root location in your Jamfiles. To
access it just declare a path constant in your Jamroot.jam file using:
</p>
<pre class="programlisting">
path-constant TOP : . ;
</pre>
<p>
After that, the <code class="computeroutput">TOP</code> variable can be used in every Jamfile.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.faq.flags"></a>
How to change compilation flags for one file?
</h3></div></div></div>
<p>
If one file must be compiled with special options, you need to explicitly
declare an <code class="computeroutput">obj</code> target for that file and then use that target
in your <code class="computeroutput">exe</code> or <code class="computeroutput">lib</code> target:
</p>
<pre class="programlisting">
exe a : a.cpp b ;
obj b : b.cpp : <optimization>off ;
</pre>
<p>
Of course you can use other properties, for example to specify specific
C/C++ compiler options:
</p>
<pre class="programlisting">
exe a : a.cpp b ;
obj b : b.cpp : <cflags>-g ;
</pre>
<p>
You can also use <a class="link" href="tutorial.html#bbv2.tutorial.conditions" title="Conditions and alternatives">conditional
properties</a> for finer control:
</p>
<pre class="programlisting">
exe a : a.cpp b ;
obj b : b.cpp : <variant>release:<optimization>off ;
</pre>
<p>
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.faq.dll-path"></a>
Why are the <code class="literal">dll-path</code> and <code class="literal">hardcode-dll-paths
</code> properties useful?
</h3></div></div></div>
<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>
This entry is specific to Unix systems.
</p></td></tr>
</table></div>
<p>
Before answering the questions, let us recall a few points about shared
libraries. Shared libraries can be used by several applications, or other
libraries, without physically including the library in the application
which can greatly decrease the total application size. It is also possible
to upgrade a shared library when the application is already installed.
</p>
<p>
However, in order for application depending on shared libraries to be
started the OS may need to find the shared library when the application is
started. The dynamic linker will search in a system-defined list of paths,
load the library and resolve the symbols. Which means that you should
either change the system-defined list, given by the <code class="envar">LD_LIBRARY_PATH
</code> environment variable, or install the libraries to a system
location. This can be inconvenient when developing, since the libraries
are not yet ready to be installed, and cluttering system paths may be
undesirable. Luckily, on Unix there is another way.
</p>
<p>
An executable can include a list of additional library paths, which will
be searched before system paths. This is excellent for development because
the build system knows the paths to all libraries and can include them in
the executables. That is done when the <code class="literal">hardcode-dll-paths
</code> feature has the <code class="literal">true</code> value, which is the
default. When the executables should be installed, the story is different.
</p>
<p>
Obviously, installed executable should not contain hardcoded paths to your
development tree. (The <code class="literal">install</code> rule explicitly disables the
<code class="literal">hardcode-dll-paths</code> feature for that reason.) However,
you can use the <code class="literal">dll-path</code> feature to add explicit paths
manually. For example:
</p>
<pre class="programlisting">
install installed : application : <dll-path>/usr/lib/snake
<location>/usr/bin ;
</pre>
<p>
will allow the application to find libraries placed in the <code class="filename">
/usr/lib/snake</code> directory.
</p>
<p>
If you install libraries to a nonstandard location and add an explicit
path, you get more control over libraries which will be used. A library of
the same name in a system location will not be inadvertently used. If you
install libraries to a system location and do not add any paths, the
system administrator will have more control. Each library can be
individually upgraded, and all applications will use the new library.
</p>
<p>
Which approach is best depends on your situation. If the libraries are
relatively standalone and can be used by third party applications, they
should be installed in the system location. If you have lots of libraries
which can be used only by your application, it makes sense to install them
to a nonstandard directory and add an explicit path, like the example
above shows. Please also note that guidelines for different systems differ
in this respect. For example, the Debian GNU guidelines prohibit any
additional search paths while Solaris guidelines suggest that they should
always be used.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.recipies.site-config"></a>Targets in site-config.jam</h3></div></div></div>
<p>
It is desirable to declare standard libraries available on a given system.
Putting target declaration in a specific project's Jamfile is not really
good, since locations of the libraries can vary between different
development machines and then such declarations would need to be
duplicated in different projects. The solution is to declare the targets
in Boost.Build's <code class="filename">site-config.jam</code> configuration file:
</p>
<pre class="programlisting">
project site-config ;
lib zlib : : <name>z ;
</pre>
<p>
</p>
<p>
Recall that both <code class="filename">site-config.jam</code> and
<code class="filename">user-config.jam</code> are projects, and everything you can
do in a Jamfile you can do in those files as well. So, you declare a
project id and a target. Now, one can write:
</p>
<pre class="programlisting">
exe hello : hello.cpp /site-config//zlib ;
</pre>
<p>
in any Jamfile.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.faq.header-only-libraries"></a>Header-only libraries</h3></div></div></div>
<p>
In modern C++, libraries often consist of just header files, without any
source files to compile. To use such libraries, you need to add proper
includes and possibly defines to your project. But with a large number of
external libraries it becomes problematic to remember which libraries are
header only, and which ones you have to link to. However, with Boost.Build
a header-only library can be declared as Boost.Build target and all
dependents can use such library without having to remember whether it is a
header-only library or not.
</p>
<p>
Header-only libraries may be declared using the <code class="computeroutput">alias</code> rule,
specifying their include path as a part of its usage requirements, for
example:
</p>
<pre class="programlisting">
alias my-lib
: # no sources
: # no build requirements
: # no default build
: <include>whatever ;
</pre>
<p>
The includes specified in usage requirements of <code class="computeroutput">my-lib</code> are
automatically added to all of its dependants' build properties. The
dependants need not care if <code class="computeroutput">my-lib</code> is a header-only or not,
and it is possible to later make <code class="computeroutput">my-lib</code> into a regular
compiled library without having to that its dependants' declarations.
</p>
<p>
If you already have proper usage requirements declared for a project where
a header-only library is defined, you do not need to duplicate them for
the <code class="computeroutput">alias</code> target:
</p>
<pre class="programlisting">
project my : usage-requirements <include>whatever ;
alias mylib ;
</pre>
<p>
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="bbv2.faq.names"></a>
What is the difference between Boost.Build,
<code class="filename">b2</code>, <code class="filename">bjam</code> and Perforce Jam?
</h3></div></div></div>
<p>
Boost.Build is the name of the complete build system. The executable that runs
it is <code class="filename">b2</code>. That executable is written in C and implements
performance-critical algorithms, like traversal of dependency graph and executing
commands. It also implements an interpreted language used to implement the rest of
Boost.Build. This executable is formally called "Boost.Build engine".
</p>
<p>
The Boost.Build engine is derived from an earlier build tool called Perforce Jam. Originally,
there were just minor changes, and the filename was <code class="filename">bjam</code>. Later on,
with more and more changes, the similarity of names because a disservice to users, and as of
Boost 1.47.0, the official name of the executable was changed to <code class="filename">b2</code>.
A copy named <code class="filename">bjam</code> is still created for compatibility,
but you are encouraged to use the new name in all cases.
</p>
<p>
Perforce Jam was an important foundation, and we gratefully acknowledge its influence,
but for users today, these tools share only some basics of the interpreted language.
</p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="extender.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="../jam.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
|
