diff options
| author | Anas Nashif <anas.nashif@intel.com> | 2012-10-30 12:57:26 -0700 |
|---|---|---|
| committer | Anas Nashif <anas.nashif@intel.com> | 2012-10-30 12:57:26 -0700 |
| commit | 1a78a62555be32868418fe52f8e330c9d0f95d5a (patch) | |
| tree | d3765a80e7d3b9640ec2e930743630cd6b9fce2b /doc/html/bbv2/faq.html | |
| download | boost-1a78a62555be32868418fe52f8e330c9d0f95d5a.tar.gz boost-1a78a62555be32868418fe52f8e330c9d0f95d5a.tar.bz2 boost-1a78a62555be32868418fe52f8e330c9d0f95d5a.zip | |
Imported Upstream version 1.49.0upstream/1.49.0
Diffstat (limited to 'doc/html/bbv2/faq.html')
| -rwxr-xr-x | doc/html/bbv2/faq.html | 531 |
1 files changed, 531 insertions, 0 deletions
diff --git a/doc/html/bbv2/faq.html b/doc/html/bbv2/faq.html new file mode 100755 index 0000000000..36b118e56e --- /dev/null +++ b/doc/html/bbv2/faq.html @@ -0,0 +1,531 @@ +<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.76.1"> +<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> +<link rel="up" href="../bbv2.html" title="Chapter 39. Boost.Build V2 User Manual"> +<link rel="prev" href="extender.html" title="Extender Manual"> +</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> +</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#id3908656"> + How do I get the current value of feature in Jamfile? + </a></span></dt> +<dt><span class="section"><a href="faq.html#id3908718"> + 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#id3908985"> + How to control properties order? + </a></span></dt> +<dt><span class="section"><a href="faq.html#id3909040"> + 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#id3909184"> + How to get the project root (a.k.a. Jamroot) location? + </a></span></dt> +<dt><span class="section"><a href="faq.html#id3909210"> + 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="id3908656"></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="id3908718"></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="id3908985"></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="id3909040"></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="id3909184"></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="id3909210"></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> +</div> +</body> +</html> |