1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Libraries</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
<link rel="start" href="../../index.html" title="Boost.Build V2 User Manual">
<link rel="up" href="../tasks.html" title="Chapter5.Common tasks">
<link rel="prev" href="../tasks.html" title="Chapter5.Common tasks">
<link rel="next" href="alias.html" title="Alias">
</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></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../tasks.html"><img src="../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tasks.html"><img src="../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="alias.html"><img src="../../../../doc/html/images/next.png" alt="Next"></a>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="bbv2.tasks.libraries"></a>Libraries</h2></div></div></div>
<p>Libraries are created using the <code class="computeroutput">lib</code> rule, which
follows the <a href="../advanced/targets.html#bbv2.main-target-rule-syntax">common
syntax</a>. For example:
</p>
<pre class="programlisting">
lib helpers : helpers.cpp : <include>boost : : <include>. ;
</pre>
<p>
</p>
<p>In the most common case, the <code class="computeroutput">lib</code> creates a library
from the specified sources. Depending on the value of
<link> feature the library will be either static or
shared. There are two other cases. First is when the library is
installed somewhere in compiler's search paths, and should be
searched by the compiler (typically, using the <code class="option">-l</code>
option). The second case is where the library is available as a
prebuilt file and the full path is known.
</p>
<p>
The syntax for these case is given below:
</p>
<pre class="programlisting">
lib z : : <name>z <search>/home/ghost ;
lib compress : : <file>/opt/libs/compress.a ;
</pre>
<p>
The <code class="computeroutput">name</code> property specifies the name that should be
passed to the <code class="option">-l</code> option, and the <code class="computeroutput">file</code>
property specifies the file location. The <code class="varname">search</code> feature
specifies paths in which to search for the library. That feature can
be specified several times, or it can be omitted, in which case only
default compiler paths will be searched.
</p>
<p>The difference between using the <code class="varname">file</code> feature as
opposed to the <code class="varname">name</code> feature together with the
<code class="varname">search</code> feature is that <code class="varname">file</code> is more
precise. A specific file will be used. On the other hand, the
<code class="varname">search</code> feature only adds a library path, and the
<code class="varname">name</code> feature gives the basic name of the library. The
search rules are specific to the linker. For example, given these
definition:
</p>
<pre class="programlisting">
lib a : : <variant>release <file>/pool/release/a.so ;
lib a : : <variant>debug <file>/pool/debug/a.so ;
lib b : : <variant>release <file>/pool/release/b.so ;
lib b : : <variant>debug <file>/pool/debug/b.so ;
</pre>
<p>
It's possible to use release version of <code class="computeroutput">a</code> and debug
version of <code class="computeroutput">b</code>. Had we used the <code class="varname">name</code> and
<code class="varname">search</code> features, the linker would always pick either
release or debug versions.
</p>
<p>
For convenience, the following syntax is allowed:
</p>
<pre class="programlisting">
lib z ;
lib gui db aux ;
</pre>
<p>
and is does exactly the same as:
</p>
<pre class="programlisting">
lib z : : <name>z ;
lib gui : : <name>gui ;
lib db : : <name>db ;
lib aux : : <name>aux ;
</pre>
<p>
</p>
<p>When a library uses another library you should put that other
library in the list of sources. This will do the right thing in all
cases. For portability, you should specify library dependencies even
for searched and prebuilt libraries, othewise, static linking on
Unix won't work. For example:
</p>
<pre class="programlisting">
lib z ;
lib png : z : <name>png ;
</pre>
<p>
</p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/html/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>When a library (say, <code class="computeroutput">a</code>), that has another
library, (say, <code class="computeroutput">b</code>)
is linked dynamically, the <code class="computeroutput">b</code>
library will be incorporated
in <code class="computeroutput">a</code>. (If <code class="computeroutput">b</code>
is dynamic library as well, then <code class="computeroutput">a</code> will only refer to
it, and not include any extra code.)
When the <code class="computeroutput">a</code>
library is linked statically, Boost.Build will assure that all
executables that link to <code class="computeroutput">a</code> will also link to
<code class="computeroutput">b</code>.
</p></td></tr>
</table></div>
<p>One feature of Boost.Build that is very important for libraries
is usage requirements.
For example, if you write:
</p>
<pre class="programlisting">
lib helpers : helpers.cpp : : : <include>. ;
</pre>
<p>
then the compiler include path for all targets that use
<code class="computeroutput">helpers</code> will contain the directory
where the target is defined.path to "helpers.cpp". The user
only needs to add <code class="computeroutput">helpers</code> to the list of sources,
and needn't consider the requirements its use imposes on a
dependent target. This feature greatly simplifies Jamfiles.
</p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../doc/html/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top">
<p>If you don't want shared libraries to include all libraries
that are specified in sources (especially statically linked ones),
you'd need to use the following:
</p>
<pre class="programlisting">
lib b : a.cpp ;
lib a : a.cpp : <use>b : : <library>b ;
</pre>
<p>
This specifies that <code class="computeroutput">a</code> uses <code class="computeroutput">b</code>, and causes
all executables that link to <code class="computeroutput">a</code> also link to
<code class="computeroutput">b</code>. In this case, even for shared linking, the
<code class="computeroutput">a</code> library won't even refer to <code class="computeroutput">b</code>.
</p>
</td></tr>
</table></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"><small></small></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../tasks.html"><img src="../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tasks.html"><img src="../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="alias.html"><img src="../../../../doc/html/images/next.png" alt="Next"></a>
</div>
</body>
</html>
|
