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