Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/doc/html/bbv2/tutorial/libs.html @ 12

Last change on this file since 12 was 12, checked in by landauf, 18 years ago

added boost
File size: 7.8 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Dependent Targets</title>
5<link rel="stylesheet" href="../../boostbook.css" type="text/css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
7<style type="text/css">
8body { background-image: url('http://docbook.sourceforge.net/release/images/draft.png');
9       background-repeat: no-repeat;
10       background-position: top left;
11       /* The following properties make the watermark "fixed" on the page. */
12       /* I think that's just a bit too distracting for the reader... */
13       /* background-attachment: fixed; */
14       /* background-position: center center; */
15     }</style>
16<link rel="start" href="../../index.html" title="The Boost C++ Libraries">
17<link rel="up" href="../tutorial.html" title="Chapter 23. Tutorial">
18<link rel="prev" href="hierarchy.html" title="Project Hierarchies">
19<link rel="next" href="linkage.html" title="Static and shared libaries">
20</head>
21<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
22<table cellpadding="2" width="100%">
23<td valign="top"><img alt="boost.png (6897 bytes)" width="277" height="86" src="../../../../boost.png"></td>
24<td align="center"><a href="../../../../index.htm">Home</a></td>
25<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
26<td align="center"><a href="../../../../people/people.htm">People</a></td>
27<td align="center"><a href="../../../../more/faq.htm">FAQ</a></td>
28<td align="center"><a href="../../../../more/index.htm">More</a></td>
29</table>
30<hr>
31<div class="spirit-nav">
32<a accesskey="p" href="hierarchy.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="linkage.html"><img src="../../images/next.png" alt="Next"></a>
33</div>
34<div class="section" lang="en">
35<div class="titlepage"><div><div><h2 class="title" style="clear: both">
36<a name="bbv2.tutorial.libs"></a>Dependent Targets</h2></div></div></div>
37<p>
38      Targets that are &#8220;needed&#8221; by other targets are called
39      <em class="firstterm">dependencies</em> of those other targets.  The
40      targets that need the other targets are called
41      <em class="firstterm">dependent</em> targets.
42    </p>
43<p>To get a feeling of target dependencies, let's continue the
44      above example and see how <code class="filename">top/app/Jamfile</code> can
45      use libraries from <code class="filename">top/util/foo</code>.  If
46      <code class="filename">top/util/foo/Jamfile</code> contains
47
48</p>
49<pre class="programlisting">
50lib bar : bar.cpp ;
51</pre>
52<p>
53
54      then to use this library in <code class="filename">top/app/Jamfile</code>, we can
55      write:
56
57</p>
58<pre class="programlisting">
59exe app : app.cpp ../util/foo//bar ;
60</pre>
61<p>
62
63      While <code class="computeroutput">app.cpp</code> refers to a regular source file,
64      <code class="computeroutput">../util/foo//bar</code> is a reference to another target:
65      a library <code class="filename">bar</code> declared in the Jamfile at
66      <code class="filename">../util/foo</code>.
67    </p>
68<div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;">
69<h3 class="title">Tip</h3>
70<p>Some other build system have special syntax for listing dependent
71      libraries, for example <code class="varname">LIBS</code> variable. In Boost.Build,
72      you just add the library to the list of sources.
73      </p>
74</div>
75<p>Suppose we build <code class="filename">app</code> with:
76    </p>
77<pre class="screen">
78bjam app optimization=full define=USE_ASM
79    </pre>
80<p>
81    Which properties will be used to build <code class="computeroutput">foo</code>? The answer is
82    that some features are
83    <em class="firstterm">propagated</em>&#8212;Boost.Build attempts to use
84    dependencies with the same value of propagated features. The
85    <code class="varname">&lt;optimization&gt;</code> feature is propagated, so both
86    <code class="filename">app</code> and <code class="filename">foo</code> will be compiled
87    with full optimization. But <code class="varname">&lt;define&gt;</code> is not
88    propagated: its value will be added as-is to the compiler flags for
89    <code class="filename">a.cpp</code>, but won't affect <code class="filename">foo</code>.
90    </p>
91<p>Let's improve this project further.
92      The library
93      probably has some headers that must be used when compiling
94      <code class="filename">app.cpp</code>. We could manually add the necessary
95      <code class="computeroutput">#include</code> paths to <code class="filename">app</code>'s
96      requirements as values of the
97      <code class="varname">&lt;include&gt;</code> feature, but then this work will
98      be repeated for all programs
99      that use <code class="filename">foo</code>. A better solution is to modify
100      <code class="filename">util/foo/Jamfile</code> in this way:
101
102</p>
103<pre class="programlisting">
104project
105    : usage-requirements &lt;include&gt;.
106    ;
107
108lib foo : foo.cpp ;
109</pre>
110<p>
111
112      Usage requirements are applied not to the target being declared
113      but to its
114      dependents. In this case, <code class="literal">&lt;include&gt;.</code> will be applied to all
115      targets that directly depend on <code class="filename">foo</code>.
116    </p>
117<p>Another improvement is using symbolic identifiers to refer to
118      the library, as opposed to <code class="filename">Jamfile</code> location.
119      In a large project, a library can be used by many targets, and if
120      they all use <code class="filename">Jamfile</code> location,
121      a change in directory organization entails much work.
122      The solution is to use project ids&#8212;symbolic names
123      not tied to directory layout. First, we need to assign a project id by
124      adding this code to
125      <code class="filename">Jamroot</code>:</p>
126<pre class="programlisting">
127use-project /library-example/foo : util/foo ;
128      </pre>
129<p>Second, we modify <code class="filename">app/Jamfile</code> to use the
130      project id:
131
132</p>
133<pre class="programlisting">
134exe app : app.cpp /library-example/foo//bar ;
135</pre>
136<p>
137The <code class="filename">/library-example/foo//bar</code> syntax is used
138      to refer to the target <code class="filename">bar</code> in
139      the project with id <code class="filename">/library-example/foo</code>.
140      We've achieved our goal&#8212;if the library is moved to a different
141      directory, only <code class="filename">Jamroot</code> must be modified.
142      Note that project ids are global&#8212;two Jamfiles are not
143      allowed to assign the same project id to different directories.
144           
145    </p>
146<div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;">
147<h3 class="title">Tip</h3>
148<p>If you want all applications in some project to link
149      to a certain library, you can avoid having to specify it directly the sources of every
150      target by using the
151      <code class="varname">&lt;source&gt;</code> property. For example, if <code class="filename">/boost/filesystem//fs</code>
152      should be linked to all applications in your project, you can add
153      <code class="computeroutput">&lt;source&gt;/boost/filesystem//fs</code> to the project's requirements, like this:</p>
154<pre class="programlisting">
155project
156   : requirements &lt;source&gt;/boost/filesystem//fs
157   ;   
158      </pre>
159</div>
160</div>
161<table width="100%"><tr>
162<td align="left"></td>
163<td align="right"><small></small></td>
164</tr></table>
165<hr>
166<div class="spirit-nav">
167<a accesskey="p" href="hierarchy.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="linkage.html"><img src="../../images/next.png" alt="Next"></a>
168</div>
169</body>
170</html>
Note: See TracBrowser for help on using the repository browser.