Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/doc/html/bbv2/faq.html @ 29

Last change on this file since 29 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 19.5 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Frequently Asked Questions</title>
5<link rel="stylesheet" href="../boostbook.css" type="text/css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
7<link rel="start" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
8<link rel="up" href="../bbv2.html" title="Chapter 25. Boost.Build V2 User Manual">
9<link rel="prev" href="reference.html" title="Detailed reference">
10<link rel="next" href="vs_v1.html" title="Appendix B. Differences to Boost.Build V1">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13<table cellpadding="2" width="100%">
14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
15<td align="center"><a href="../../../index.htm">Home</a></td>
16<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
17<td align="center"><a href="../../../people/people.htm">People</a></td>
18<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
19<td align="center"><a href="../../../more/index.htm">More</a></td>
20</table>
21<hr>
22<div class="spirit-nav">
23<a accesskey="p" href="reference.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../bbv2.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="vs_v1.html"><img src="../images/next.png" alt="Next"></a>
24</div>
25<div class="section" lang="en">
26<div class="titlepage"><div><div><h2 class="title" style="clear: both">
27<a name="bbv2.faq"></a>Frequently Asked Questions</h2></div></div></div>
28<div class="toc"><dl>
29<dt><span class="section"><a href="faq.html#id2130440">
30        How do I get the current value of feature in Jamfile?
31      </a></span></dt>
32<dt><span class="section"><a href="faq.html#id2130502">
33        I'm getting "Duplicate name of actual target" error. What
34        does it mean?
35      </a></span></dt>
36<dt><span class="section"><a href="faq.html#bbv2.faq.envar">
37      Accessing environment variables
38      </a></span></dt>
39<dt><span class="section"><a href="faq.html#id2130646">
40        How to control properties order?
41      </a></span></dt>
42<dt><span class="section"><a href="faq.html#id2130685">
43      How to control the library order on Unix?
44    </a></span></dt>
45<dt><span class="section"><a href="faq.html#bbv2.faq.external">Can I get output of external program as a variable in a Jamfile?
46    </a></span></dt>
47<dt><span class="section"><a href="faq.html#id2130754">How to get the project-root location?
48    </a></span></dt>
49<dt><span class="section"><a href="faq.html#id2130779">How to change compilation flags for one file?
50    </a></span></dt>
51<dt><span class="section"><a href="faq.html#bbv2.faq.dll-path">Why are the <code class="computeroutput">dll-path</code> and
52    <code class="computeroutput">hardcode-dll-paths</code> properties useful?
53    </a></span></dt>
54<dt><span class="section"><a href="faq.html#bbv2.recipies.site-config">Targets in site-config.jam</a></span></dt>
55<dt><span class="section"><a href="faq.html#bbv2.faq.header-only-libraries">Header-only libraries</a></span></dt>
56</dl></div>
57<div class="section" lang="en">
58<div class="titlepage"><div><div><h3 class="title">
59<a name="id2130440"></a>
60        How do I get the current value of feature in Jamfile?
61      </h3></div></div></div>
62<p>
63        This is not possible, since Jamfile does not have "current" value of any
64        feature, be it toolset, build variant or anything else. For a single invocation of
65        <code class="filename">bjam</code>, any given main target can be built with several property sets.
66        For example, user can request two build variants on the command line. Or one library
67        is built as shared when used from one application, and as static when used from another.
68        Obviously, Jamfile is read only once, so generally, there's no single value of a feature
69        you can access in Jamfile.               
70      </p>
71<p>A feature has a specific value only when building a target, and there are two ways how you
72      can use that value:</p>
73<div class="itemizedlist"><ul type="disc">
74<li>Use conditional requirements or indirect conditional requirements. See
75        <a href="advanced.html#bbv2.advanced.targets.requirements.conditional">the section called &#8220;Requirements&#8221;</a>.</li>
76<li>Define a custom generator and a custom main target type. The custom generator can do arbitrary processing
77        or properties. See the <a href="extender.html" title="Extender Manual">the section called &#8220;Extender Manual&#8221;</a>.
78        </li>
79</ul></div>
80</div>
81<div class="section" lang="en">
82<div class="titlepage"><div><div><h3 class="title">
83<a name="id2130502"></a>
84        I'm getting "Duplicate name of actual target" error. What
85        does it mean?
86      </h3></div></div></div>
87<p>   
88    The most likely case is that you're trying to
89    compile the same file twice, with almost the same,
90    but differing properties. For example:
91
92</p>
93<pre class="programlisting">
94exe a : a.cpp : &lt;include&gt;/usr/local/include ;
95exe b : a.cpp ;
96</pre>
97<p>   
98
99    </p>
100<p>
101    The above snippet requires two different compilations
102    of 'a.cpp', which differ only in 'include' property.
103    Since the 'include' property is free, Boost.Build
104    can't generate two objects files into different directories.
105    On the other hand, it's dangerous to compile the file only
106    once -- maybe you really want to compile with different
107    includes.
108    </p>
109<p>
110    To solve this issue, you need to decide if file should
111    be compiled once or twice.</p>
112<div class="orderedlist"><ol type="1">
113<li>
114<p>Two compile file only once, make sure that properties
115      are the same:
116
117</p>
118<pre class="programlisting">
119exe a : a.cpp : &lt;include&gt;/usr/local/include ;
120exe b : a.cpp : &lt;include&gt;/usr/local/include ;
121</pre>
122</li>
123<li>
124<p>
125      If changing the properties is not desirable, for example
126      if 'a' and 'b' target have other sources which need
127      specific properties, separate 'a.cpp' into it's own target:
128
129</p>
130<pre class="programlisting">
131obj a_obj : a.cpp : &lt;include&gt;/usr/local/include ;
132exe a : a_obj ;
133</pre>
134</li>
135<li>
136<p>
137      To compile file twice, you can make the object file local
138      to the main target:
139
140</p>
141<pre class="programlisting">
142      exe a : [ obj a_obj : a.cpp ] : &lt;include&gt;/usr/local/include ;
143      exe b : [ obj a_obj : a.cpp ] ;
144</pre>
145</li>
146</ol></div>
147<p>
148   A good question is why Boost.Build can't use some of the above
149   approaches automatically. The problem is that such magic would
150   require additional implementation complexities and would only
151   help in half of the cases, while in other half we'd be silently
152   doing the wrong thing. It's simpler and safe to ask user to
153   clarify his intention in such cases.
154   </p>
155</div>
156<div class="section" lang="en">
157<div class="titlepage"><div><div><h3 class="title">
158<a name="bbv2.faq.envar"></a>
159      Accessing environment variables
160      </h3></div></div></div>
161<p>   
162      Many users would like to use environment variables in Jamfiles, for
163      example, to control location of external libraries. In many cases you
164      better declare those external libraries in the site-config.jam file, as
165      documented in the <a href="faq.html#bbv2.recipies.site-config" title="Targets in site-config.jam">recipes
166      section</a>. However, if the users already have the environment variables set
167      up, it's not convenient to ask them to set up site-config.jam files as
168      well, and using environment variables might be reasonable.
169    </p>
170<p>In Boost.Build V2, each Jamfile is a separate namespace, and the
171    variables defined in environment is imported into the global
172    namespace. Therefore, to access environment variable from Jamfile, you'd
173    need the following code:
174</p>
175<pre class="programlisting">
176import os ;
177local SOME_LIBRARY_PATH = [ os.environ SOME_LIBRARY_PATH ] ;
178exe a : a.cpp : &lt;include&gt;$(SOME_LIBRARY_PATH) ;
179</pre>
180<p>
181    </p>
182</div>
183<div class="section" lang="en">
184<div class="titlepage"><div><div><h3 class="title">
185<a name="id2130646"></a>
186        How to control properties order?
187      </h3></div></div></div>
188<p>For internal reasons, Boost.Build sorts all the properties
189    alphabetically. This means that if you write:
190</p>
191<pre class="programlisting">
192exe a : a.cpp : &lt;include&gt;b &lt;include&gt;a ;
193</pre>
194<p>
195      then the command line with first mention the "a" include directory, and
196      then "b", even though they are specified in the opposite order. In most
197      cases, the user doesn't care. But sometimes the order of includes, or
198      other properties, is important. For example, if one uses both the C++
199      Boost library and the "boost-sandbox" (libraries in development), then
200      include path for boost-sandbox must come first, because some headers may
201      override ones in C++ Boost. For such cases, a special syntax is
202      provided:
203</p>
204<pre class="programlisting">
205exe a : a.cpp : &lt;include&gt;a&amp;&amp;b ;       
206</pre>
207<p>
208    </p>
209<p>The <code class="computeroutput">&amp;&amp;</code> symbols separate values of an
210      property, and specify that the order of the values should be preserved. You
211      are advised to use this feature only when the order of properties really
212      matters, and not as a convenient shortcut. Using it everywhere might
213      negatively affect performance.
214    </p>
215</div>
216<div class="section" lang="en">
217<div class="titlepage"><div><div><h3 class="title">
218<a name="id2130685"></a>
219      How to control the library order on Unix?
220    </h3></div></div></div>
221<p>On the Unix-like operating systems, the order in which static
222      libraries are specified when invoking the linker is important, because by
223      default, the linker uses one pass though the libraries list. Passing the
224      libraries in the incorrect order will lead to a link error. Further, this
225      behaviour is often used to make one library override symbols from
226      another. So, sometimes it's necessary to force specific order of
227      libraries.   
228    </p>
229<p>Boost.Build tries to automatically compute the right order.  The
230      primary rule is that if library a "uses" library b, then library a will
231      appear on the command line before library b. Library a is considered to
232      use b is b is present either in the sources of a or in its
233      requirements. To explicitly specify the use relationship one can use the
234      &lt;use&gt; feature. For example, both of the following lines will cause
235      a to appear before b on the command line:
236</p>
237<pre class="programlisting">
238lib a : a.cpp b ;
239lib a : a.cpp : &lt;use&gt;b ;
240</pre>
241<p>
242    </p>
243<p>
244      The same approach works for searched libraries, too:
245</p>
246<pre class="programlisting">
247lib z ;
248lib png : : &lt;use&gt;z ;
249exe viewer : viewer png z ;
250</pre>
251<p>
252    </p>
253</div>
254<div class="section" lang="en">
255<div class="titlepage"><div><div><h3 class="title">
256<a name="bbv2.faq.external"></a>Can I get output of external program as a variable in a Jamfile?
257    </h3></div></div></div>
258<p>The <code class="computeroutput">SHELL</code> builtin can be used for the purpose:
259</p>
260<pre class="programlisting">
261local gtk_includes = [ SHELL "gtk-config --cflags" ] ;
262</pre>
263<p>
264    </p>
265</div>
266<div class="section" lang="en">
267<div class="titlepage"><div><div><h3 class="title">
268<a name="id2130754"></a>How to get the project-root location?
269    </h3></div></div></div>
270<p>You might want to use the location of the project-root in your
271      Jamfiles. To do it, you'd need to declare path constant in your
272      project-root.jam:
273</p>
274<pre class="programlisting">
275path-constant TOP : . ;
276</pre>
277<p>
278      After that, the <code class="computeroutput">TOP</code> variable can be used in every Jamfile.
279    </p>
280</div>
281<div class="section" lang="en">
282<div class="titlepage"><div><div><h3 class="title">
283<a name="id2130779"></a>How to change compilation flags for one file?
284    </h3></div></div></div>
285<p>If one file must be compiled with special options, you need to
286      explicitly declare an <code class="computeroutput">obj</code> target for that file and then use
287      that target in your <code class="computeroutput">exe</code> or <code class="computeroutput">lib</code> target:
288</p>
289<pre class="programlisting">
290exe a : a.cpp b ;
291obj b : b.cpp : &lt;optimization&gt;off ;
292</pre>
293<p>
294      Of course you can use other properties, for example to specify specific
295      compiler options:
296</p>
297<pre class="programlisting">
298exe a : a.cpp b ;
299obj b : b.cpp : &lt;cflags&gt;-g ;
300</pre>
301<p>
302      You can also use <a href="tutorial.html#bbv2.tutorial.conditions" title="Conditions and alternatives">conditional
303      properties</a> for finer control:
304</p>
305<pre class="programlisting">
306exe a : a.cpp b ;
307obj b : b.cpp : &lt;variant&gt;release:&lt;optimization&gt;off ;
308</pre>
309<p>
310
311    </p>
312</div>
313<div class="section" lang="en">
314<div class="titlepage"><div><div><h3 class="title">
315<a name="bbv2.faq.dll-path"></a>Why are the <code class="computeroutput">dll-path</code> and
316    <code class="computeroutput">hardcode-dll-paths</code> properties useful?
317    </h3></div></div></div>
318<p>(This entry is specific to Unix system.)Before answering the
319      questions, let's recall a few points about shared libraries. Shared
320      libraries can be used by several applications, or other libraries,
321      without phisycally including the library in the application. This can
322      greatly decrease the total size of applications. It's also possible to
323      upgrade a shared library when the application is already
324      installed. Finally, shared linking can be faster.
325    </p>
326<p>However, the shared library must be found when the application is
327      started. The dynamic linker will search in a system-defined list of
328      paths, load the library and resolve the symbols. Which means that you
329      should either change the system-defined list, given by the
330      <code class="envar">LD_LIBRARY_PATH</code> environment variable, or install the
331      libraries to a system location. This can be inconvenient when
332      developing, since the libraries are not yet ready to be installed, and
333      cluttering system paths is undesirable. Luckily, on Unix there's another
334      way.
335    </p>
336<p>An executable can include a list of additional library paths, which
337      will be searched before system paths. This is excellent for development,
338      because the build system knows the paths to all libraries and can include
339      them in executables. That's done when the <code class="computeroutput">hardcode-dll-paths</code>
340      feature has the <code class="literal">true</code> value, which is the
341      default. When the executables should be installed, the story is
342      different.
343    </p>
344<p>
345      Obviously, installed executable should not hardcode paths to your
346      development tree. (The <code class="computeroutput">stage</code> rule explicitly disables the
347      <code class="computeroutput">hardcode-dll-paths</code> feature for that reason.) However, you
348      can use the <code class="computeroutput">dll-path</code> feature to add explicit paths
349      manually. For example:
350</p>
351<pre class="programlisting">
352stage installed : application : &lt;dll-path&gt;/usr/lib/snake
353                                &lt;location&gt;/usr/bin ;         
354</pre>
355<p>
356      will allow the application to find libraries placed to
357      <code class="filename">/usr/lib/snake</code>.
358    </p>
359<p>If you install libraries to a nonstandard location and add an
360      explicit path, you get more control over libraries which will be used. A
361      library of the same name in a system location will not be inadvertently
362      used.  If you install libraries to a system location and do not add any
363      paths, the system administrator will have more control. Each library can
364      be individually upgraded, and all applications will use the new library.
365    </p>
366<p>Which approach is best depends on your situation. If the libraries
367      are relatively standalone and can be used by third party applications,
368      they should be installed in the system location. If you have lots of
369      libraries which can be used only by your application, it makes sense to
370      install it to a nonstandard directory and add an explicit path, like the
371      example above shows. Please also note that guidelines for different
372      systems differ in this respect. The Debian guidelines prohibit any
373      additional search paths, and Solaris guidelines suggest that they should
374      always be used.
375    </p>
376</div>
377<div class="section" lang="en">
378<div class="titlepage"><div><div><h3 class="title">
379<a name="bbv2.recipies.site-config"></a>Targets in site-config.jam</h3></div></div></div>
380<p>It is desirable to declare standard libraries available on a
381      given system. Putting target declaration in Jamfile is not really
382      good, since locations of the libraries can vary. The solution is
383      to put the following to site-config.jam.</p>
384<pre class="programlisting">
385import project ;
386project.initialize $(__name__) ;
387project site-config ;
388lib zlib : : &lt;name&gt;z ;
389</pre>
390<p>The second line allows this module to act as project. The
391      third line gives id to this project &#8212; it really has no location
392      and cannot be used otherwise. The fourth line just declares a
393      target. Now, one can write:
394</p>
395<pre class="programlisting">
396exe hello : hello.cpp /site-config//zlib ;
397</pre>
398<p>
399      in any Jamfile.</p>
400</div>
401<div class="section" lang="en">
402<div class="titlepage"><div><div><h3 class="title">
403<a name="bbv2.faq.header-only-libraries"></a>Header-only libraries</h3></div></div></div>
404<p>In modern C++, libraries often consist of just header files, without
405    any source files to compile. To use such libraries, you need to add proper
406    includes and, maybe, defines, to your project. But with large number of
407    external libraries it becomes problematic to remember which libraries are
408    header only, and which are "real" ones. However, with Boost.Build a
409    header-only library can be declared as Boost.Build target and all
410    dependents can use such library without remebering if it's header-only or not.
411    </p>
412<p>Header-only libraries are declared using the <code class="computeroutput">alias</code> rule,
413    that specifies only usage requirements, for example:
414</p>
415<pre class="programlisting">
416alias mylib
417    : # no sources
418    : # no build requirements
419    : # no default build
420    : &lt;include&gt;whatever
421    ;
422</pre>
423<p>
424    The includes specified in usage requirements of <code class="computeroutput">mylib</code> are
425    automatically added to build properties of all dependents. The dependents
426    need not care if <code class="computeroutput">mylib</code> is header-only or not, and it's possible
427    to later make <code class="computeroutput">mylib</code> into a regular compiled library.
428    </p>
429<p>
430      If you already have proper usage requirements declared for project where
431      header-only library is defined, you don't need to duplicate them for
432      the <code class="computeroutput">alias</code> target:
433</p>
434<pre class="programlisting">
435project my : usage-requirements &lt;include&gt;whatever ;
436alias mylib ;
437</pre>
438<p>     
439    </p>
440</div>
441</div>
442<table width="100%"><tr>
443<td align="left"></td>
444<td align="right"><small></small></td>
445</tr></table>
446<hr>
447<div class="spirit-nav">
448<a accesskey="p" href="reference.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../bbv2.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="vs_v1.html"><img src="../images/next.png" alt="Next"></a>
449</div>
450</body>
451</html>
Note: See TracBrowser for help on using the repository browser.