doc/html/bbv2/faq.html

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