Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

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

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

added boost
File size: 20.6 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Writing Jamfiles</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="../advanced.html" title="Chapter 24. User documentation">
19<link rel="next" href="build_process.html" title="The Build Process">
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="../advanced.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="build_process.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.jamfiles"></a>Writing Jamfiles</h2></div></div></div>
37<div class="toc"><dl>
38<dt><span class="section"><a href="jamfiles.html#bbv2.advanced.overview">Overview</a></span></dt>
39<dt><span class="section"><a href="jamfiles.html#bbv2.advanced.targets">Main targets</a></span></dt>
40<dt><span class="section"><a href="jamfiles.html#bbv2.advanced.projects">Projects</a></span></dt>
41<dt><span class="section"><a href="jamfiles.html#bbv2.advanced.other-rules">Jamfile Utility Rules</a></span></dt>
42</dl></div>
43<div class="section" lang="en">
44<div class="titlepage"><div><div><h3 class="title">
45<a name="bbv2.advanced.overview"></a>Overview</h3></div></div></div>
46<p>Jamfiles are the thing that is most important to the user,
47     
48      bacause they declare the targets that should be built.
49     
50      Jamfiles are also used for organizing targets&#8212;
51     
52      each Jamfile is a separate project
53     
54      that can be built independently from the other projects.
55      </p>
56<p>Jamfiles mostly contain calls to Boost.Build functions that do
57        all the work, specifically:
58        </p>
59<div class="itemizedlist"><ul type="disc">
60<li><p><a href="jamfiles.html#bbv2.advanced.targets" title="Main targets">declare main
61                targets</a></p></li>
62<li><p><a href="jamfiles.html#bbv2.advanced.projects" title="Projects">define
63            project properties</a></p></li>
64<li><p><a href="jamfiles.html#bbv2.advanced.other-rules" title="Jamfile Utility Rules">do various other
65            things</a></p></li>
66</ul></div>
67</div>
68<div class="section" lang="en">
69<div class="titlepage"><div><div><h3 class="title">
70<a name="bbv2.advanced.targets"></a>Main targets</h3></div></div></div>
71<p><a name="bbv2.advanced.targets.main"></a>
72        A <em class="firstterm">Main target</em> is a user-defined named
73        entity that can be built, for example an  executable file.
74       
75        Declaring a main target is usually done using one of the main
76        target rules described in <a href="builtins/targets.html" title="Builtin target types">the section called &#8220;Builtin target types&#8221;</a>.  The user can also declare
77        custom main target rules as shown in <a href="../extending/rules.html" title="Main target rules">the section called &#8220;Main target rules&#8221;</a>.
78</p>
79<p>Most main target rules in Boost.Build can be invoked with
80      a common syntax:</p>
81<a name="bbv2.main-target-rule-syntax"></a><pre class="programlisting"><em class="replaceable"><code>rule-name</code></em>&#8194;<em class="replaceable"><code>main-target-name</code></em>
82    : <em class="replaceable"><code>sources...</code></em>
83    : <em class="replaceable"><code>requirements...</code></em> 
84    : <em class="replaceable"><code>default-build...</code></em>
85    : <em class="replaceable"><code>usage-requirements...</code></em>
86    ;
87</pre>
88<div class="itemizedlist"><ul type="disc">
89<li>
90<em class="parameter"><code>main-target-name</code></em> is the name used
91            to request the target on command line and to use it from
92            other main targets. A main target name may contain
93            alphanumeric characters, dashes
94            (&#8216;<code class="computeroutput">-</code>&#8217;), and underscores
95            (&#8216;<code class="computeroutput">_</code>&#8217;).
96          </li>
97<li>
98<em class="parameter"><code>sources</code></em> is the list of source files and other main
99            targets that must be combined.
100          </li>
101<li>
102<em class="parameter"><code>requirements</code></em> is the list of properties that must always
103            be present when this main target is built.
104          </li>
105<li>
106<em class="parameter"><code>default-build</code></em> is the list of properties that will be used
107            unless some other value of the same feature is already
108            specified, e.g. on the command line or by propogation from a dependent target.
109          </li>
110<li>
111<em class="parameter"><code>usage-requirements</code></em> is the list of properties that will be
112            propagated to all main targets that use this one, i.e. to all its
113            dependents.
114          </li>
115</ul></div>
116<p>         
117        Some main target rules have a shorter list of parameters;
118        consult their documentation for details.
119      </p>
120<p>Note that the actual requirements, default-build and
121      usage-requirements attributes for a target are obtained by
122      combining the explicitly specified ones with those specified for
123      the project where a target is declared.
124      </p>
125<p>The list of sources specifies what should be processed to
126      get the resulting targets. Most of the time, it's just a list of
127      files. Sometimes, you'll want to automatically construct the
128      list of source files rather than having to spell it out
129      manually, in which case you can use the
130      <code class="computeroutput">glob</code> rule. Here are two examples:
131</p>
132<pre class="programlisting">
133exe a : a.cpp ;           # a.cpp is the only source file
134exe b : [ glob *.cpp ] ;  # all .cpp files in this directory are sources
135</pre>
136<p>
137        Unless you specify a files with absolute path, the name is
138        considered relative to the source directory -- which is typically
139        the directory where the Jamfile is located, but can be changed as
140        described in <a href="jamfiles.html#bbv2.advanced.projects.attributes.projectrule" title="">the section called &#8220;Projects&#8221;</a>.
141      </p>
142<p>
143        The list of sources can also refer to other main targets.
144        Targets in the same project can be referred to by name, while
145        targets in other projects need to be qualified with a directory or a symbolic
146        project name. For example:
147</p>
148<pre class="programlisting">
149lib helper : helper.cpp ;
150exe a : a.cpp helper ;
151exe b : b.cpp ..//utils ;
152exe c : c.cpp /boost/program_options//program_options ;
153</pre>
154<p>
155        The first exe uses the library defined in the same
156        project. The second one uses some target (most likely library)
157        defined by Jamfile one level higher. Finally, the third target
158        uses some <a href="http://boost.org" target="_top">C++ Boost</a>
159        library, referring to it by its absolute symbolic name. More
160        information about it can be found in <a href="../tutorial/libs.html" title="Dependent Targets">the section called &#8220;Dependent Targets&#8221;</a> and <a href="../reference/definitions.html#bbv2.reference.ids" title="Target identifiers and references">the section called &#8220;Target identifiers and references&#8221;</a>.
161      </p>
162<p>Requirements are the properties that should always be present when
163        building a target. Typically, they are includes and defines:
164</p>
165<pre class="programlisting">
166exe hello : hello.cpp : &lt;include&gt;/opt/boost &lt;define&gt;MY_DEBUG ;
167</pre>
168<p>
169        In special circumstances,
170       
171        other properties can be used, for example if
172        a library can only be built statically, or a file can't be compiled
173        with optimization due to a compiler bug, one can use
174</p>
175<pre class="programlisting">
176lib util : util.cpp : &lt;link&gt;static ;
177obj main : main.cpp : &lt;optimization&gt;off ;
178</pre>
179<p>Sometimes requirements are necessary only for a specific
180      compiler or build variant.  <a href="../reference/definitions.html#bbv2.reference.variants.propcond" title="Conditional properties">Conditional
181      properties</a> can be used in that case:
182      </p>
183<pre class="programlisting">
184lib util : util.cpp : &lt;toolset&gt;msvc:&lt;link&gt;static ;
185</pre>
186<p>
187        Whenever <code class="computeroutput">&lt;toolset&gt;msvc</code> property is
188        in build properties, the <code class="computeroutput">&lt;link&gt;static</code> property will
189        be included as well. Conditional requirements can be &#8220;chained&#8221;:
190</p>
191<pre class="programlisting">
192lib util : util.cpp : &lt;toolset&gt;msvc:&lt;link&gt;static
193                      &lt;link&gt;static:&lt;define&gt;STATIC_LINK ;
194</pre>
195<p>
196        will set of static link
197       
198        and the <code class="computeroutput">STATIC_LINK</code> define on the
199        <code class="computeroutput">msvc</code> toolset.
200        </p>
201<p>The <code class="varname">default-build</code> parameter
202     
203      is a set of properties to be used if the build request does
204      not otherwise specify a value for features in the set. For example:
205</p>
206<pre class="programlisting">
207exe hello : hello.cpp : : &lt;threading&gt;multi ;
208</pre>
209<p>
210        would build a multi-threaded target in unless the user
211        explicitly requests a single-threaded version. The difference between
212        requirements and default-build is that requirements cannot be
213        overriden in any way.</p>
214<p>A target of the same name can be declared several times,  in which
215        case each declaration is called an
216        <em class="firstterm">alternative</em>. When the target is built, one of
217        the alternatives will be selected and used.  Alternatives need not be
218        defined by the same main target rule.  For example,
219</p>
220<pre class="programlisting">
221lib helpers : helpers.hpp ;                 # a header-only library
222alias helpers : helpers.lib : &lt;toolset&gt;msvc ; # except on msvc
223</pre>
224<p>The actual commands used to build any given main target can differ greatly from
225        platform to platform. For example, you might have different lists
226        of sources for different compilers, or different options for those
227        compilers. Two approaches to this are explained in the
228        <a href="../tutorial/conditions.html" title="Conditions and alternatives">tutorial</a>.
229        </p>
230<p>Sometimes a main target is really needed only by some other main
231        target. For example, a rule that declares a test-suite uses a main
232        target
233       
234        that represent test, but those main targets are rarely needed
235        by themselves.
236        </p>
237<p>It is possible to declare a target inline, i.e. the "sources"
238        parameter may include calls to other main rules. For example:</p>
239<pre class="programlisting">
240exe hello : hello.cpp
241    [ obj helpers : helpers.cpp : &lt;optimization&gt;off ] ;
242</pre>
243<p>
244        Will cause "helpers.cpp" to be always compiled without
245        optimization.
246       
247        When referring to an inline main target, its declared name
248        must be prefixed by its parent target's name and two dots. In
249        the example above, to build only helpers, one should run
250        <code class="computeroutput">bjam hello..helpers</code>.
251      </p>
252</div>
253<div class="section" lang="en">
254<div class="titlepage"><div><div><h3 class="title">
255<a name="bbv2.advanced.projects"></a>Projects</h3></div></div></div>
256<p>As mentioned before, targets are grouped into projects,
257      and each Jamfile is a separate project. Projects are useful
258      because they allow us to group related targets together, define
259      properties common to all those targets, and assign a symbolic
260      name to the project that can be used in referring to its
261      targets.
262      </p>
263<p>Projects are named using the
264      <code class="computeroutput">project</code> rule, which has the
265      following syntax:
266</p>
267<pre class="programlisting">
268project <em class="replaceable"><code>id</code></em> : <em class="replaceable"><code>attributes</code></em> ;
269</pre>
270<p>
271        Here, <em class="replaceable"><code>attributes</code></em> is a sequence of
272        rule arguments, each of which begins with an attribute-name
273        and is followed by any number of build properties. 
274        The list
275        of attribute names along with its handling is also shown in
276        the table below. For example, it is possible to write:
277</p>
278<pre class="programlisting">
279project tennis
280    : requirements &lt;threading&gt;multi
281    : default-build release
282    ;
283</pre>
284<p>The possible attributes are listed below.</p>
285<p><span class="emphasis"><em>Project id</em></span> is a short way to denote a project, as
286        opposed to the Jamfile's pathname. It is a hierarchical path,
287        unrelated to filesystem, such as "boost/thread". <a href="../reference/definitions.html#bbv2.reference.ids" title="Target identifiers and references">Target references</a> make use of project ids to
288        specify a target.</p>
289<p><span class="emphasis"><em>Source location</em></span> specifies the directory where sources
290        for the project are located.</p>
291<p><span class="emphasis"><em>Project requirements</em></span> are requirements that apply to
292        all the targets in the projects as well as all subprojects.</p>
293<p><span class="emphasis"><em>Default build</em></span> is the build request that should be
294        used when no build request is specified explicitly.</p>
295<p><a name="bbv2.advanced.projects.attributes.projectrule"></a>
296        The default values for those attributes are
297        given in the table below.
298
299        </p>
300<div class="table">
301<a name="id2856417"></a><p class="title"><b>Table 24.1. </b></p>
302<table class="table" summary="">
303<colgroup>
304<col>
305<col>
306<col>
307<col>
308</colgroup>
309<thead><tr>
310<th>Attribute</th>
311<th>Name for the 'project' rule</th>
312<th>Default value</th>
313<th>Handling by the 'project' rule</th>
314</tr></thead>
315<tbody>
316<tr>
317<td>Project id</td>
318<td>none</td>
319<td>none</td>
320<td>Assigned from the first parameter of the 'project' rule.
321                  It is assumed to denote absolute project id.</td>
322</tr>
323<tr>
324<td>Source location</td>
325<td><code class="literal">source-location</code></td>
326<td>The location of jamfile for the project</td>
327<td>Sets to the passed value</td>
328</tr>
329<tr>
330<td>Requirements</td>
331<td><code class="literal">requirements</code></td>
332<td>The parent's requirements</td>
333<td>The parent's requirements are refined with the passed
334                  requirement and the result is used as the project
335                  requirements.</td>
336</tr>
337<tr>
338<td>Default build</td>
339<td><code class="literal">default-build</code></td>
340<td>none</td>
341<td>Sets to the passed value</td>
342</tr>
343<tr>
344<td>Build directory</td>
345<td><code class="literal">build-dir</code></td>
346<td>Empty if the parent has no build directory set.
347                Otherwise, the parent's build directory with with the
348                relative path from parent to the current project
349                appended to it.
350                </td>
351<td>Sets to the passed value, interpreted as relative to the
352                  project's location.</td>
353</tr>
354</tbody>
355</table>
356</div>
357<p>Besides defining projects and main targets, Jamfiles
358      commonly invoke utility rules such as
359      <code class="computeroutput">constant</code> and
360      <code class="computeroutput">path-constant</code>, which inject a
361      specified Boost.Jam variable setting into this project's Jamfile
362      module and those of all its subprojects.  See <a href="jamfiles.html#bbv2.advanced.other-rules" title="Jamfile Utility Rules">the section called &#8220;Jamfile Utility Rules&#8221;</a> for a complete description
363      of these utility rules.  Jamfiles are regular Boost.Jam source
364      files and Boost.Build modules, so naturally they can contain any kind of Boost.Jam code,
365      including rule definitions.
366      </p>
367<p>Each subproject inherits attributes, constants and rules
368      from its parent project, which is defined by the nearest
369      Jamfile in an ancestor directory above
370      the subproject.  The top-level project is declared in a file
371      called <code class="filename">Jamroot</code> rather than
372      <code class="filename">Jamfile</code>.  When loading a project,
373      Boost.Build looks for either <code class="filename">Jamroot</code> or
374      <code class="computeroutput">Jamfile</code>.  They are handled indentically, except
375      that if the file is called <code class="filename">Jamroot</code>, the
376      search for a parent project is not performed.
377      </p>
378<p>Even when building in a subproject directory, parent
379      project files are always loaded before those of their
380      subprojects, so that every definition made in a parent project
381      is always available to its children. The loading order of any
382      other projects is unspecified.  Even if one project refers to
383      another via ???,
384      or a target reference, no specific order should be assumed.
385      </p>
386<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
387<h3 class="title">Note</h3>
388<p>Giving the root project the special name
389        &#8220;<code class="filename">Jamroot</code>&#8221; ensures that
390        Boost.Build won't misinterpret a directory above it as the
391        project root just because the directory contains a Jamfile.
392        </p>
393</div>
394</div>
395<div class="section" lang="en">
396<div class="titlepage"><div><div><h3 class="title">
397<a name="bbv2.advanced.other-rules"></a>Jamfile Utility Rules</h3></div></div></div>
398<p>The following table describes utility rules that can be
399      used in Jamfiles. Detailed information for any of these rules can
400      be obtained by running:
401</p>
402<pre class="screen">
403bjam --help project.<em class="replaceable"><code>rulename</code></em></pre>
404<div class="table">
405<a name="id2856637"></a><p class="title"><b>Table 24.2. </b></p>
406<table class="table" summary="">
407<colgroup>
408<col>
409<col>
410</colgroup>
411<thead><tr>
412<th>Rule</th>
413<th>Semantics</th>
414</tr></thead>
415<tbody>
416<tr>
417<td><a href="jamfiles.html#bbv2.advanced.projects.attributes.projectrule">project</a></td>
418<td>Define this project's symbolic ID or attributes.</td>
419</tr>
420<tr>
421<td>???</td>
422<td>Make another project known so that it can be referred to by symbolic ID.</td>
423</tr>
424<tr>
425<td>???</td>
426<td>Cause another project to be built when this one is built.</td>
427</tr>
428<tr>
429<td>???</td>
430<td>State that a target should be built only by explicit
431                request.</td>
432</tr>
433<tr>
434<td>glob</td>
435<td>Translate a list of shell-style wildcards into a
436              corresponding list of files.</td>
437</tr>
438<tr>
439<td>constant</td>
440<td>Injects a variable setting into this project's
441              Jamfile module and those of all its subprojects.</td>
442</tr>
443<tr>
444<td>path-constant</td>
445<td>Injects a variable set to a path value into
446              this project's Jamfile module and those of all its subprojects.
447              If the value is a relative path it will be adjusted for
448              each subproject so that it refers to the same
449              directory.</td>
450</tr>
451</tbody>
452</table>
453</div>
454</div>
455</div>
456<table width="100%"><tr>
457<td align="left"></td>
458<td align="right"><small></small></td>
459</tr></table>
460<hr>
461<div class="spirit-nav">
462<a accesskey="p" href="../advanced.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="build_process.html"><img src="../../images/next.png" alt="Next"></a>
463</div>
464</body>
465</html>
Note: See TracBrowser for help on using the repository browser.