Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/doc/html/bbv2/advanced/builtins/targets.html @ 12

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

added boost
File size: 18.8 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Builtin target types</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="../../advanced.html" title="Chapter 24. User documentation">
18<link rel="prev" href="../build_process.html" title="The Build Process">
19<link rel="next" href="features.html" title="Builtin features">
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="../build_process.html"><img src="../../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../../advanced.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="features.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.advanced.builtins.targets"></a>Builtin target types</h2></div></div></div>
37<div class="toc"><dl>
38<dt><span class="section"><a href="targets.html#id2856983">Programs</a></span></dt>
39<dt><span class="section"><a href="targets.html#id2857046">Libraries</a></span></dt>
40<dt><span class="section"><a href="targets.html#bbv2.builtins.alias">Alias</a></span></dt>
41<dt><span class="section"><a href="targets.html#bbv2.builtins.stage">Installing</a></span></dt>
42<dt><span class="section"><a href="targets.html#bbv2.builtins.testing">Testing</a></span></dt>
43</dl></div>
44<div class="section" lang="en">
45<div class="titlepage"><div><div><h3 class="title">
46<a name="id2856983"></a>Programs</h3></div></div></div>
47<p>Programs are created using the <code class="computeroutput">exe</code> rule, which
48        follows the <a href="../jamfiles.html#bbv2.main-target-rule-syntax">common
49          syntax</a>. For example:
50</p>
51<pre class="programlisting">
52exe hello : hello.cpp some_library.lib /some_project//library
53          : &lt;threading&gt;multi
54          ;
55</pre>
56<p>
57        This will create an executable file from the sources -- in this case,
58        one C++ file, one library file present in the same directory, and
59        another library that is created by Boost.Build. Generally, sources
60        can include C and C++ files, object files and libraries. Boost.Build
61        will automatically try to convert targets of other types.
62      </p>
63<div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;">
64<h3 class="title">Tip</h3>
65<p>         
66          On Windows, if an application uses dynamic libraries, and both
67          the application and the libraries are built by Boost.Build, its not
68          possible to immediately run the application, because the
69          <code class="literal">PATH</code> environment variable should include the path
70          to the libraries. It means you have to either add the paths
71          manually, or place the application and the libraries to the same
72          directory, for example using the <a href="targets.html#bbv2.builtins.stage" title="Installing">
73            stage</a> rule.
74        </p>
75</div>
76</div>
77<div class="section" lang="en">
78<div class="titlepage"><div><div><h3 class="title">
79<a name="id2857046"></a>Libraries</h3></div></div></div>
80<p>Libraries are created using the <code class="computeroutput">lib</code> rule, which
81        follows the <a href="../jamfiles.html#bbv2.main-target-rule-syntax">common
82          syntax</a>. For example:
83</p>
84<pre class="programlisting">
85lib helpers : helpers.cpp : &lt;include&gt;boost : : &lt;include&gt;. ;
86</pre>
87<p>In the most common case, the <code class="computeroutput">lib</code> creates a library
88        from the specified sources. Depending on the value of
89        &lt;link&gt; feature the library will be either static or
90        shared. There are two other cases. First is when the library is
91        installed somewhere in compiler's search paths, and should be
92        searched by the compiler (typically, using the <code class="option">-l</code>
93        option). The second case is where the library is available as a
94        prebuilt file and the full path is known.         
95        </p>
96<p>
97        The syntax for these case is given below:
98</p>
99<pre class="programlisting">
100lib z : : &lt;name&gt;z &lt;search&gt;/home/ghost ;           
101lib compress : : &lt;file&gt;/opt/libs/compress.a ;
102</pre>
103<p>
104        The <code class="computeroutput">name</code> property specifies the name that should be
105        passed to the <code class="option">-l</code> option, and the <code class="computeroutput">file</code>
106        property specifies the file location. The <code class="varname">search</code> feature
107        specifies paths in which to search for the library. That feature can
108        be specified several times, or it can be omitted, in which case only
109        default compiler paths will be searched.
110      </p>
111<p>The difference between using the <code class="varname">file</code> feature as
112        opposed to the <code class="varname">name</code> feature together with the
113        <code class="varname">search</code> feature is that <code class="varname">file</code> is more
114        precise. A specific file will be used. On the other hand, the
115        <code class="varname">search</code> feature only adds a library path, and the
116        <code class="varname">name</code> feature gives the basic name of the library. The
117        search rules are specific to the linker. For example, given these
118        definition:
119</p>
120<pre class="programlisting">
121lib a : : &lt;variant&gt;release &lt;file&gt;/pool/release/a.so ;
122lib a : : &lt;variant&gt;debug &lt;file&gt;/pool/debug/a.so ;
123lib b : : &lt;variant&gt;release &lt;file&gt;/pool/release/b.so ;
124lib b : : &lt;variant&gt;debug &lt;file&gt;/pool/debug/b.so ;
125</pre>
126<p>
127        It's possible to use release version of <code class="computeroutput">a</code> and debug
128        version of <code class="computeroutput">b</code>. Had we used the <code class="varname">name</code> and
129        <code class="varname">search</code> features, the linker would always pick either
130        release or debug versions.
131        </p>
132<p>
133        For convenience, the following syntax is allowed:
134</p>
135<pre class="programlisting">
136lib z ;
137lib gui db aux ;
138</pre>
139<p>
140          and is does exactly the same as:
141</p>
142<pre class="programlisting">
143lib z : : &lt;name&gt;z ;           
144lib gui : : &lt;name&gt;gui ;           
145lib db : : &lt;name&gt;db ;           
146lib aux : : &lt;name&gt;aux ;           
147</pre>
148<p>When a library uses another library you should put that another
149        library in the list of sources. This will do the right thing in all
150        cases. For portability, you should specify library dependencies even
151        for searched and prebuilt libraries, othewise, static linking on
152        Unix won't work. For example:
153</p>
154<pre class="programlisting">
155lib z ;
156lib png : z : &lt;name&gt;png ;
157</pre>
158<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
159<h3 class="title">Note</h3>
160<p>When a library (say, <code class="computeroutput">a</code>), that has another
161          library, (say, <code class="computeroutput">b</code>)
162         
163          is linked dynamically, the <code class="computeroutput">b</code>
164          library will be incorporated
165         
166          in <code class="computeroutput">a</code>. (If <code class="computeroutput">b</code>
167          is dynamic library as well, then <code class="computeroutput">a</code> will only refer to
168          it, and not include any extra code.)
169         
170          When the <code class="computeroutput">a</code>
171          library is linked statically, Boost.Build will assure that all
172          executables that link to <code class="computeroutput">a</code> will also link to
173          <code class="computeroutput">b</code>.
174        </p>
175</div>
176<p>One feature of Boost.Build that is very important for libraries
177        is usage requirements.
178       
179        For example, if you write:
180</p>
181<pre class="programlisting">
182lib helpers : helpers.cpp : : : &lt;include&gt;. ;
183</pre>
184<p>
185        then the compiler include path for all targets that use
186        <code class="computeroutput">helpers</code> will contain the directory
187       
188        where the target is defined.path to "helpers.cpp". The user
189        only needs to add <code class="computeroutput">helpers</code> to the list of sources,
190        and needn't consider the requirements its use imposes on a
191        dependent target. This feature greatly simplifies Jamfiles.
192        </p>
193<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
194<h3 class="title">Note</h3>
195<p>If you don't want shared libraries to include all libraries
196          that are specified in sources (especially statically linked ones),
197          you'd need to use the following:
198</p>
199<pre class="programlisting">
200lib b : a.cpp ;
201lib a : a.cpp : &lt;use&gt;b : : &lt;library&gt;b ;
202</pre>
203<p>
204          This specifies that <code class="computeroutput">a</code> uses <code class="computeroutput">b</code>, and causes
205          all executables that link to <code class="computeroutput">a</code> also link to
206          <code class="computeroutput">b</code>. In this case, even for shared linking, the
207          <code class="computeroutput">a</code> library won't even refer to <code class="computeroutput">b</code>.
208        </p>
209</div>
210</div>
211<div class="section" lang="en">
212<div class="titlepage"><div><div><h3 class="title">
213<a name="bbv2.builtins.alias"></a>Alias</h3></div></div></div>
214<p>The <code class="computeroutput">alias</code> rule follows the <a href="../jamfiles.html#bbv2.main-target-rule-syntax">common syntax</a>. For
215        example:
216</p>
217<pre class="programlisting">
218alias core : im reader writer ;
219</pre>
220<p>
221        will build the sources
222       
223        and return
224       
225        the generated source targets
226        without modification.
227      </p>
228<p>
229        The <code class="computeroutput">alias</code> rule is a convenience tool. If you often build
230        the same group of targets at the same time, you can define an alias
231        to save typing.       
232      </p>
233<p>
234        Another use of the <code class="computeroutput">alias</code> rule is to change build
235        properties. For example, if you always want static linking for a
236        specific C++ Boost library, you can write the following:
237</p>
238<pre class="programlisting">
239alias threads : /boost/thread//boost_thread : &lt;link&gt;static ;
240</pre>
241<p>
242        and use only the <code class="computeroutput">threads</code> alias in your Jamfiles.
243        </p>
244<p>
245        You can also specify usage requirements for the
246        <code class="computeroutput">alias</code> target. If you write the following:
247</p>
248<pre class="programlisting">
249alias header_only_library : : : :  &lt;include&gt;/usr/include/header_only_library ;
250</pre>
251<p>
252        then using <code class="computeroutput">header_only_library</code> in sources will only add an
253        include path. Also note that when there are some sources, their usage
254        requirements are propagated, too. For example:
255</p>
256<pre class="programlisting">
257lib lib : lib.cpp : : : &lt;include&gt;. ;
258alias lib_alias ;
259exe main : main.cpp lib_alias ;
260</pre>
261<p>
262        will compile <code class="filename">main.cpp</code> with the additional include.
263      </p>
264</div>
265<div class="section" lang="en">
266<div class="titlepage"><div><div><h3 class="title">
267<a name="bbv2.builtins.stage"></a>Installing</h3></div></div></div>
268<p>For installing a built target you should use the
269        <code class="computeroutput">install</code> rule, which follows the <a href="../jamfiles.html#bbv2.main-target-rule-syntax">common syntax</a>. For
270        example:
271</p>
272<pre class="programlisting">
273install dist : hello helpers ;
274</pre>
275<p>
276        will cause the targets <code class="computeroutput">hello</code> and <code class="computeroutput">helpers</code> to
277        be moved to the <code class="filename">dist</code> directory, relative to
278        Jamfile's directory. The directory can
279        be changed with the <code class="computeroutput">location</code> property:
280</p>
281<pre class="programlisting">
282install dist : hello helpers : &lt;location&gt;/usr/bin ;
283</pre>
284<p>
285        While you can achieve the same effect by changing the target name to
286        <code class="filename">/usr/bin</code>, using the <code class="computeroutput">location</code>
287        property is better, because it allows you to use a memnonic target
288        name.
289      </p>
290<p>The <code class="computeroutput">location</code> property is especially handy when the location
291        is not fixed, but depends on build variant or environment variables:
292</p>
293<pre class="programlisting">
294install dist : hello helpers : &lt;variant&gt;release:&lt;location&gt;dist/release
295                             &lt;variant&gt;debug:&lt;location&gt;dist/debug ;
296install dist2 : hello helpers : &lt;location&gt;$(DIST) ;
297</pre>
298<p> 
299        See also <a href="../../reference/definitions.html#bbv2.reference.variants.propcond" title="Conditional properties">conditional
300          properties</a> and <a href="../../faq/envar.html" title="
301      Accessing environment variables
302      ">environment variables</a></p>
303<p>
304        Specifying the names of all libraries to install can be boring. The
305        <code class="computeroutput">install</code> allows you to specify only the top-level executable
306        targets to install, and automatically install all dependencies:
307</p>
308<pre class="programlisting">
309install dist : hello
310           : &lt;install-dependencies&gt;on &lt;install-type&gt;EXE
311             &lt;install-type&gt;LIB
312           ;
313</pre>
314<p>
315        will find all targets that <code class="computeroutput">hello</code> depends on, and install
316        all of the which are either executables or libraries. More
317        specifically, for each target, other targets that were specified as
318        sources or as dependency properties, will be recursively found.  One
319        exception is that targets referred with the <a href="features.html#bbv2.builtin.features.use"><code class="computeroutput">use</code></a> feature
320        are not considered, because that feature is typically used to refer to
321        header-only libraries.
322        If the set of target types is specified, only targets of that type
323        will be installed, otherwise, all found target will be installed.
324      </p>
325<p>The <a href="targets.html#bbv2.builtins.alias" title="Alias"><code class="computeroutput">alias</code></a>
326      rule can be used when targets must be installed into several
327      directories:
328</p>
329<pre class="programlisting">
330install install : install-bin install-lib ;
331install install-bin : applications : /usr/bin ;
332install install-lib : helper : /usr/lib ;
333</pre>
334<p>Because the <code class="computeroutput">install</code> rule just copies targets, most
335    free features <sup>[<a name="id2857684" href="#ftn.id2857684">6</a>]</sup>
336    have no effect when used in requirements of the <code class="computeroutput">install</code>.
337    The only two which matter are 
338    <a href="features.html#bbv2.builtin.features.dependency"><code class="varname">dependency</code></a> and, on Unix,
339    <code class="varname">dll-path</code>.
340    </p>
341<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
342<h3 class="title">Note</h3>
343<p>
344        (Unix specific). On Unix, executables built with Boost.Build typically
345        contain the list of paths to all used dynamic libraries. For
346        installing, this is not desired, so Boost.Build relinks the executable
347        with an empty list of paths. You can also specify additional paths for
348        installed executables with the <code class="varname">dll-path</code> feature.
349      </p>
350</div>
351</div>
352<div class="section" lang="en">
353<div class="titlepage"><div><div><h3 class="title">
354<a name="bbv2.builtins.testing"></a>Testing</h3></div></div></div>
355<p>Boost.Build has convenient support for running unit tests. The
356        simplest way is the <code class="computeroutput">unit-test</code> rule, which follows the
357        <a href="../jamfiles.html#bbv2.main-target-rule-syntax">common syntax</a>. For
358        example:
359</p>
360<pre class="programlisting">
361unit-test helpers_test : helpers_test.cpp helpers ;
362</pre>
363<p>The <code class="computeroutput">unit-test</code> rule behaves like the
364        <code class="computeroutput">exe</code> rule, but after the executable is created it is
365        run. If the executable returns an error code, the build system will also
366        return an error and will try running the executable on the next
367        invocation until it runs successfully. This behaviour ensures that you
368        can't miss a unit test failure.
369      </p>
370<p>There are rules for more elaborate testing: <code class="computeroutput">compile</code>,
371        <code class="computeroutput">compile-fail</code>, <code class="computeroutput">run</code> and
372        <code class="computeroutput">run-fail</code>. They are more suitable for automated testing, and
373        are not covered here.
374      </p>
375</div>
376<div class="footnotes">
377<br><hr width="100" align="left">
378<div class="footnote"><p><sup>[<a name="ftn.id2857684" href="#id2857684">6</a>] </sup>see the definition of "free" in <a href="../../reference/definitions.html#bbv2.reference.features.attributes" title="Feature Attributes">the section called &#8220;Feature Attributes&#8221;</a>.</p></div>
379</div>
380</div>
381<table width="100%"><tr>
382<td align="left"></td>
383<td align="right"><small></small></td>
384</tr></table>
385<hr>
386<div class="spirit-nav">
387<a accesskey="p" href="../build_process.html"><img src="../../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../../advanced.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="features.html"><img src="../../../images/next.png" alt="Next"></a>
388</div>
389</body>
390</html>
Note: See TracBrowser for help on using the repository browser.