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