3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4 <title>Frequently Asked Questions</title>
5 <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
7 <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
8 <link rel="up" href="../bbv2.html" title="Chapter 43. Boost.Build V2 User Manual">
9 <link rel="prev" href="extender.html" title="Extender Manual">
11 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
12 <table cellpadding="2" width="100%"><tr>
13 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
14 <td align="center"><a href="../../../index.html">Home</a></td>
15 <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
16 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
17 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
18 <td align="center"><a href="../../../more/index.htm">More</a></td>
21 <div class="spirit-nav">
22 <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>
25 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
26 <a name="bbv2.faq"></a>Frequently Asked Questions</h2></div></div></div>
27 <div class="toc"><dl class="toc">
28 <dt><span class="section"><a href="faq.html#bbv2.faq.featurevalue">
29 How do I get the current value of feature in Jamfile?
31 <dt><span class="section"><a href="faq.html#bbv2.faq.duplicate">
32 I am getting a "Duplicate name of actual target" error. What does that
35 <dt><span class="section"><a href="faq.html#bbv2.faq.envar">
36 Accessing environment variables
38 <dt><span class="section"><a href="faq.html#bbv2.faq.proporder">
39 How to control properties order?
41 <dt><span class="section"><a href="faq.html#bbv2.faq.liborder">
42 How to control the library linking order on Unix?
44 <dt><span class="section"><a href="faq.html#bbv2.faq.external">
45 Can I get capture external program output using a Boost.Jam variable?
47 <dt><span class="section"><a href="faq.html#bbv2.faq.projectroot">
48 How to get the project root (a.k.a. Jamroot) location?
50 <dt><span class="section"><a href="faq.html#bbv2.faq.flags">
51 How to change compilation flags for one file?
53 <dt><span class="section"><a href="faq.html#bbv2.faq.dll-path">
54 Why are the <code class="literal">dll-path</code> and <code class="literal">hardcode-dll-paths
55 </code> properties useful?
57 <dt><span class="section"><a href="faq.html#bbv2.recipies.site-config">Targets in site-config.jam</a></span></dt>
58 <dt><span class="section"><a href="faq.html#bbv2.faq.header-only-libraries">Header-only libraries</a></span></dt>
59 <dt><span class="section"><a href="faq.html#bbv2.faq.names">
60 What is the difference between Boost.Build,
61 <code class="filename">b2</code>, <code class="filename">bjam</code> and Perforce Jam?
65 <div class="titlepage"><div><div><h3 class="title">
66 <a name="bbv2.faq.featurevalue"></a>
67 How do I get the current value of feature in Jamfile?
68 </h3></div></div></div>
70 This is not possible, since Jamfile does not have "current" value of any
71 feature, be it toolset, build variant or anything else. For a single
72 run of Boost.Build, any given main target can be
73 built with several property sets. For example, user can request two build
74 variants on the command line. Or one library is built as shared when used
75 from one application, and as static when used from another. Each Jamfile
76 is read only once so generally there is no single value of a feature you
77 can access in Jamfile.
80 A feature has a specific value only when building a target, and there are
81 two ways you can use that value:
83 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
85 Use conditional requirements or indirect conditional requirements. See
86 <a class="xref" href="overview.html#bbv2.overview.targets.requirements.conditional">the section called “Requirements”</a>.
89 Define a custom generator and a custom main target type. The custom
90 generator can do arbitrary processing or properties. See the <a class="xref" href="extender.html" title="Extender Manual">the section called “Extender Manual”</a>.
95 <div class="titlepage"><div><div><h3 class="title">
96 <a name="bbv2.faq.duplicate"></a>
97 I am getting a "Duplicate name of actual target" error. What does that
99 </h3></div></div></div>
101 The most likely case is that you are trying to compile the same file
102 twice, with almost the same, but differing properties. For example:
104 <pre class="programlisting">
105 exe a : a.cpp : <include>/usr/local/include ;
111 The above snippet requires two different compilations of
112 <code class="computeroutput">a.cpp</code>, which differ only in their <code class="literal">include</code>
113 property. Since the <code class="literal">include</code> feature is declared as
114 <code class="literal">free</code> Boost.Build does not create a separate build
115 directory for each of its values and those two builds would both produce
116 object files generated in the same build directory. Ignoring this and
117 compiling the file only once would be dangerous as different includes
118 could potentially cause completely different code to be compiled.
121 To solve this issue, you need to decide if the file should be compiled
124 <div class="orderedlist"><ol class="orderedlist" type="1">
125 <li class="listitem">
127 To compile the file only once, make sure that properties are the same
128 for both target requests:
130 <pre class="programlisting">
131 exe a : a.cpp : <include>/usr/local/include ;
132 exe b : a.cpp : <include>/usr/local/include ;
137 <pre class="programlisting">
138 alias a-with-include : a.cpp : <include>/usr/local/include ;
139 exe a : a-with-include ;
140 exe b : a-with-include ;
143 or if you want the <code class="literal">includes</code> property not to affect
144 how any other sources added for the built <code class="computeroutput">a</code> and
145 <code class="computeroutput">b</code> executables would be compiled:
147 <pre class="programlisting">
148 obj a-obj : a.cpp : <include>/usr/local/include ;
155 Note that in both of these cases the <code class="literal">include</code>
156 property will be applied only for building these object files and not
157 any other sources that might be added for targets <code class="computeroutput">a</code> and
158 <code class="computeroutput">b</code>.
161 <li class="listitem">
163 To compile the file twice, you can tell Boost.Build to compile it to
164 two separate object files like so:
166 <pre class="programlisting">
167 obj a_obj : a.cpp : <include>/usr/local/include ;
173 or you can make the object file targets local to the main target:
175 <pre class="programlisting">
176 exe a : [ obj a_obj : a.cpp : <include>/usr/local/include ] ;
177 exe b : [ obj a_obj : a.cpp ] ;
180 which will cause Boost.Build to actually change the generated object
181 file names a bit for you and thus avoid any conflicts.
184 Note that in both of these cases the <code class="literal">include</code>
185 property will be applied only for building these object files and not
186 any other sources that might be added for targets <code class="computeroutput">a</code> and
187 <code class="computeroutput">b</code>.
192 A good question is why Boost.Build can not use some of the above
193 approaches automatically. The problem is that such magic would only help
194 in half of the cases, while in the other half it would be silently doing
195 the wrong thing. It is simpler and safer to ask the user to clarify his
196 intention in such cases.
199 <div class="section">
200 <div class="titlepage"><div><div><h3 class="title">
201 <a name="bbv2.faq.envar"></a>
202 Accessing environment variables
203 </h3></div></div></div>
205 Many users would like to use environment variables in Jamfiles, for
206 example, to control the location of external libraries. In many cases it
207 is better to declare those external libraries in the site-config.jam file,
208 as documented in the <a class="link" href="faq.html#bbv2.recipies.site-config" title="Targets in site-config.jam">recipes
209 section</a>. However, if the users already have the environment
210 variables set up, it may not be convenient for them to set up their
211 site-config.jam files as well and using the environment variables might be
215 Boost.Jam automatically imports all environment variables into its
216 built-in .ENVIRON module so user can read them from there directly or by
217 using the helper os.environ rule. For example:
219 <pre class="programlisting">
221 local unga-unga = [ os.environ UNGA_UNGA ] ;
225 or a bit more realistic:
227 <pre class="programlisting">
229 local SOME_LIBRARY_PATH = [ os.environ SOME_LIBRARY_PATH ] ;
230 exe a : a.cpp : <include>$(SOME_LIBRARY_PATH) ;
235 <div class="section">
236 <div class="titlepage"><div><div><h3 class="title">
237 <a name="bbv2.faq.proporder"></a>
238 How to control properties order?
239 </h3></div></div></div>
241 For internal reasons, Boost.Build sorts all the properties alphabetically.
242 This means that if you write:
244 <pre class="programlisting">
245 exe a : a.cpp : <include>b <include>a ;
248 then the command line with first mention the <code class="computeroutput">a</code> include
249 directory, and then <code class="computeroutput">b</code>, even though they are specified in the
250 opposite order. In most cases, the user does not care. But sometimes the
251 order of includes, or other properties, is important. For such cases, a
252 special syntax is provided:
254 <pre class="programlisting">
255 exe a : a.cpp : <include>a&&b ;
260 The <code class="computeroutput">&&</code> symbols separate property values and specify
261 that their order should be preserved. You are advised to use this feature
262 only when the order of properties really matters and not as a convenient
263 shortcut. Using it everywhere might negatively affect performance.
266 <div class="section">
267 <div class="titlepage"><div><div><h3 class="title">
268 <a name="bbv2.faq.liborder"></a>
269 How to control the library linking order on Unix?
270 </h3></div></div></div>
272 On Unix-like operating systems, the order in which static libraries are
273 specified when invoking the linker is important, because by default, the
274 linker uses one pass though the libraries list. Passing the libraries in
275 the incorrect order will lead to a link error. Further, this behaviour is
276 often used to make one library override symbols from another. So,
277 sometimes it is necessary to force specific library linking order.
280 Boost.Build tries to automatically compute the right order. The primary
281 rule is that if library <code class="computeroutput">a</code> "uses" library <code class="computeroutput">b</code>, then
282 library <code class="computeroutput">a</code> will appear on the command line before library
283 <code class="computeroutput">b</code>. Library <code class="computeroutput">a</code> is considered to use <code class="computeroutput">b</code>
284 if <code class="computeroutput">b</code> is present either in the <code class="computeroutput">a</code> library's
285 sources or its usage is listed in its requirements. To explicitly specify
286 the <code class="literal">use</code> relationship one can use the
287 <code class="literal"><use></code> feature. For example, both of the following
288 lines will cause <code class="computeroutput">a</code> to appear before <code class="computeroutput">b</code> on the
291 <pre class="programlisting">
293 lib a : a.cpp : <use>b ;
298 The same approach works for searched libraries as well:
300 <pre class="programlisting">
302 lib png : : <use>z ;
303 exe viewer : viewer png z ;
308 <div class="section">
309 <div class="titlepage"><div><div><h3 class="title">
310 <a name="bbv2.faq.external"></a>
311 Can I get capture external program output using a Boost.Jam variable?
312 </h3></div></div></div>
314 The <code class="literal">SHELL</code> builtin rule may be used for this purpose:
316 <pre class="programlisting">
317 local gtk_includes = [ SHELL "gtk-config --cflags" ] ;
322 <div class="section">
323 <div class="titlepage"><div><div><h3 class="title">
324 <a name="bbv2.faq.projectroot"></a>
325 How to get the project root (a.k.a. Jamroot) location?
326 </h3></div></div></div>
328 You might want to use your project's root location in your Jamfiles. To
329 access it just declare a path constant in your Jamroot.jam file using:
331 <pre class="programlisting">
332 path-constant TOP : . ;
335 After that, the <code class="computeroutput">TOP</code> variable can be used in every Jamfile.
338 <div class="section">
339 <div class="titlepage"><div><div><h3 class="title">
340 <a name="bbv2.faq.flags"></a>
341 How to change compilation flags for one file?
342 </h3></div></div></div>
344 If one file must be compiled with special options, you need to explicitly
345 declare an <code class="computeroutput">obj</code> target for that file and then use that target
346 in your <code class="computeroutput">exe</code> or <code class="computeroutput">lib</code> target:
348 <pre class="programlisting">
350 obj b : b.cpp : <optimization>off ;
353 Of course you can use other properties, for example to specify specific
354 C/C++ compiler options:
356 <pre class="programlisting">
358 obj b : b.cpp : <cflags>-g ;
361 You can also use <a class="link" href="tutorial.html#bbv2.tutorial.conditions" title="Conditions and alternatives">conditional
362 properties</a> for finer control:
364 <pre class="programlisting">
366 obj b : b.cpp : <variant>release:<optimization>off ;
371 <div class="section">
372 <div class="titlepage"><div><div><h3 class="title">
373 <a name="bbv2.faq.dll-path"></a>
374 Why are the <code class="literal">dll-path</code> and <code class="literal">hardcode-dll-paths
375 </code> properties useful?
376 </h3></div></div></div>
377 <div class="note"><table border="0" summary="Note">
379 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td>
380 <th align="left">Note</th>
382 <tr><td align="left" valign="top"><p>
383 This entry is specific to Unix systems.
387 Before answering the questions, let us recall a few points about shared
388 libraries. Shared libraries can be used by several applications, or other
389 libraries, without physically including the library in the application
390 which can greatly decrease the total application size. It is also possible
391 to upgrade a shared library when the application is already installed.
394 However, in order for application depending on shared libraries to be
395 started the OS may need to find the shared library when the application is
396 started. The dynamic linker will search in a system-defined list of paths,
397 load the library and resolve the symbols. Which means that you should
398 either change the system-defined list, given by the <code class="envar">LD_LIBRARY_PATH
399 </code> environment variable, or install the libraries to a system
400 location. This can be inconvenient when developing, since the libraries
401 are not yet ready to be installed, and cluttering system paths may be
402 undesirable. Luckily, on Unix there is another way.
405 An executable can include a list of additional library paths, which will
406 be searched before system paths. This is excellent for development because
407 the build system knows the paths to all libraries and can include them in
408 the executables. That is done when the <code class="literal">hardcode-dll-paths
409 </code> feature has the <code class="literal">true</code> value, which is the
410 default. When the executables should be installed, the story is different.
413 Obviously, installed executable should not contain hardcoded paths to your
414 development tree. (The <code class="literal">install</code> rule explicitly disables the
415 <code class="literal">hardcode-dll-paths</code> feature for that reason.) However,
416 you can use the <code class="literal">dll-path</code> feature to add explicit paths
417 manually. For example:
419 <pre class="programlisting">
420 install installed : application : <dll-path>/usr/lib/snake
421 <location>/usr/bin ;
424 will allow the application to find libraries placed in the <code class="filename">
425 /usr/lib/snake</code> directory.
428 If you install libraries to a nonstandard location and add an explicit
429 path, you get more control over libraries which will be used. A library of
430 the same name in a system location will not be inadvertently used. If you
431 install libraries to a system location and do not add any paths, the
432 system administrator will have more control. Each library can be
433 individually upgraded, and all applications will use the new library.
436 Which approach is best depends on your situation. If the libraries are
437 relatively standalone and can be used by third party applications, they
438 should be installed in the system location. If you have lots of libraries
439 which can be used only by your application, it makes sense to install them
440 to a nonstandard directory and add an explicit path, like the example
441 above shows. Please also note that guidelines for different systems differ
442 in this respect. For example, the Debian GNU guidelines prohibit any
443 additional search paths while Solaris guidelines suggest that they should
447 <div class="section">
448 <div class="titlepage"><div><div><h3 class="title">
449 <a name="bbv2.recipies.site-config"></a>Targets in site-config.jam</h3></div></div></div>
451 It is desirable to declare standard libraries available on a given system.
452 Putting target declaration in a specific project's Jamfile is not really
453 good, since locations of the libraries can vary between different
454 development machines and then such declarations would need to be
455 duplicated in different projects. The solution is to declare the targets
456 in Boost.Build's <code class="filename">site-config.jam</code> configuration file:
458 <pre class="programlisting">
459 project site-config ;
460 lib zlib : : <name>z ;
465 Recall that both <code class="filename">site-config.jam</code> and
466 <code class="filename">user-config.jam</code> are projects, and everything you can
467 do in a Jamfile you can do in those files as well. So, you declare a
468 project id and a target. Now, one can write:
470 <pre class="programlisting">
471 exe hello : hello.cpp /site-config//zlib ;
477 <div class="section">
478 <div class="titlepage"><div><div><h3 class="title">
479 <a name="bbv2.faq.header-only-libraries"></a>Header-only libraries</h3></div></div></div>
481 In modern C++, libraries often consist of just header files, without any
482 source files to compile. To use such libraries, you need to add proper
483 includes and possibly defines to your project. But with a large number of
484 external libraries it becomes problematic to remember which libraries are
485 header only, and which ones you have to link to. However, with Boost.Build
486 a header-only library can be declared as Boost.Build target and all
487 dependents can use such library without having to remeber whether it is a
488 header-only library or not.
491 Header-only libraries may be declared using the <code class="computeroutput">alias</code> rule,
492 specifying their include path as a part of its usage requirements, for
495 <pre class="programlisting">
498 : # no build requirements
500 : <include>whatever ;
503 The includes specified in usage requirements of <code class="computeroutput">my-lib</code> are
504 automatically added to all of its dependants' build properties. The
505 dependants need not care if <code class="computeroutput">my-lib</code> is a header-only or not,
506 and it is possible to later make <code class="computeroutput">my-lib</code> into a regular
507 compiled library without having to that its dependants' declarations.
510 If you already have proper usage requirements declared for a project where
511 a header-only library is defined, you do not need to duplicate them for
512 the <code class="computeroutput">alias</code> target:
514 <pre class="programlisting">
515 project my : usage-requirements <include>whatever ;
521 <div class="section">
522 <div class="titlepage"><div><div><h3 class="title">
523 <a name="bbv2.faq.names"></a>
524 What is the difference between Boost.Build,
525 <code class="filename">b2</code>, <code class="filename">bjam</code> and Perforce Jam?
526 </h3></div></div></div>
528 Boost.Build is the name of the complete build system. The executable that runs
529 it is <code class="filename">b2</code>. That executable is written in C and implements
530 performance-critical algorithms, like traversal of dependency graph and executing
531 commands. It also implements an interpreted language used to implement the rest of
532 Boost.Build. This executable is formally called "Boost.Build engine".
535 The Boost.Build engine is derived from an earlier build tool called Perforce Jam. Originally,
536 there were just minor changes, and the filename was <code class="filename">bjam</code>. Later on,
537 with more and more changes, the similarity of names because a disservice to users, and as of
538 Boost 1.47.0, the official name of the executable was changed to <code class="filename">b2</code>.
539 A copy named <code class="filename">bjam</code> is still created for compatibility,
540 but you are encouraged to use the new name in all cases.
543 Perforce Jam was an important foundation, and we gratefully acknowledge its influence,
544 but for users today, these tools share only some basics of the interpreted language.
548 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
549 <td align="left"></td>
550 <td align="right"><div class="copyright-footer">Copyright © 2006-2009, 2014 Vladimir Prus<p>Distributed under the Boost Software License, Version 1.0.
551 (See accompanying file <code class="filename">LICENSE_1_0.txt</code> or copy at
552 <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
557 <div class="spirit-nav">
558 <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>