| <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> |