Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/doc/html/bbv2/reference.html @ 25

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

added boost
File size: 14.2 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Chapter 26. Detailed reference</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="../bbv2.html" title="Part III. Boost.Build v2 User Manual">
18<link rel="prev" href="extending/toolset_modules.html" title="Toolset modules">
19<link rel="next" href="reference/jamfiles.html" title="Writing Jamfiles">
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="extending/toolset_modules.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../bbv2.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="reference/jamfiles.html"><img src="../images/next.png" alt="Next"></a>
33</div>
34<div class="chapter" lang="en">
35<div class="titlepage"><div><div><h2 class="title">
36<a name="bbv2.reference"></a>Chapter 26. Detailed reference</h2></div></div></div>
37<div class="toc">
38<p><b>Table of Contents</b></p>
39<dl>
40<dt><span class="section"><a href="reference.html#bbv2.reference.general">General information</a></span></dt>
41<dd><dl>
42<dt><span class="section"><a href="reference.html#bbv2.reference.init">Initialization</a></span></dt>
43<dt><span class="section"><a href="reference.html#bbv2.reference.commandline">Command line</a></span></dt>
44</dl></dd>
45<dt><span class="section"><a href="reference/jamfiles.html">Writing Jamfiles</a></span></dt>
46<dd><dl><dt><span class="section"><a href="reference/jamfiles.html#bbv2.reference.headers">Generated headers</a></span></dt></dl></dd>
47<dt><span class="section"><a href="reference/buildprocess.html">Build process</a></span></dt>
48<dd><dl>
49<dt><span class="section"><a href="reference/buildprocess.html#bbv2.reference.buildprocess.alternatives">Alternative selection</a></span></dt>
50<dt><span class="section"><a href="reference/buildprocess.html#bbv2.reference.buildprocess.common">Determining common properties</a></span></dt>
51</dl></dd>
52<dt><span class="section"><a href="reference/definitions.html">Definitions</a></span></dt>
53<dd><dl>
54<dt><span class="section"><a href="reference/definitions.html#bbv2.reference.features">Features and properties</a></span></dt>
55<dt><span class="section"><a href="reference/definitions.html#bbv2.reference.variants">Build Variants</a></span></dt>
56<dt><span class="section"><a href="reference/definitions.html#bbv2.reference.variants.proprefine">Property refinement</a></span></dt>
57<dt><span class="section"><a href="reference/definitions.html#bbv2.reference.variants.propcond">Conditional properties</a></span></dt>
58<dt><span class="section"><a href="reference/definitions.html#bbv2.reference.ids">Target identifiers and references</a></span></dt>
59</dl></dd>
60<dt><span class="section"><a href="reference/generators.html">Generators</a></span></dt>
61<dd><dl>
62<dt><span class="section"><a href="reference/generators.html#id2861414">Selecting and ranking viable generators</a></span></dt>
63<dt><span class="section"><a href="reference/generators.html#id2861462">Running generators</a></span></dt>
64<dt><span class="section"><a href="reference/generators.html#id2861501">Selecting dependency graph</a></span></dt>
65<dt><span class="section"><a href="reference/generators.html#id2861512">Property adjustment</a></span></dt>
66<dt><span class="section"><a href="reference/generators.html#id2861573">Transformations cache</a></span></dt>
67</dl></dd>
68</dl>
69</div>
70<div class="section" lang="en">
71<div class="titlepage"><div><div><h2 class="title" style="clear: both">
72<a name="bbv2.reference.general"></a>General information</h2></div></div></div>
73<div class="toc"><dl>
74<dt><span class="section"><a href="reference.html#bbv2.reference.init">Initialization</a></span></dt>
75<dt><span class="section"><a href="reference.html#bbv2.reference.commandline">Command line</a></span></dt>
76</dl></div>
77<div class="section" lang="en">
78<div class="titlepage"><div><div><h3 class="title">
79<a name="bbv2.reference.init"></a>Initialization</h3></div></div></div>
80<p>bjam's first job upon startup is to load the Jam code that
81        implements the build system. To do this, it searches for a file
82        called <code class="filename">boost-build.jam</code>, first in the invocation directory, then
83        in its parent and so forth up to the filesystem root, and finally
84        in the directories specified by the environment variable
85        BOOST_BUILD_PATH. When found, the file is interpreted, and should
86        specify the build system location by calling the boost-build
87        rule:</p>
88<pre class="programlisting">
89rule boost-build ( location ? )
90</pre>
91<p>
92        If location is a relative path, it is treated as relative to
93        the directory of <code class="filename">boost-build.jam</code>. The directory specified by
94        that location and the directories in BOOST_BUILD_PATH are then searched for
95        a file called <code class="filename">bootstrap.jam</code>, which is expected to
96        bootstrap the build system. This arrangement allows the build
97        system to work without any command-line or environment variable
98        settings. For example, if the build system files were located in a
99        directory "build-system/" at your project root, you might place a
100        <code class="filename">boost-build.jam</code> at the project root containing:
101
102</p>
103<pre class="programlisting">
104boost-build build-system ;
105</pre>
106<p>
107
108        In this case, running bjam anywhere in the project tree will
109        automatically find the build system.</p>
110<p>The default <code class="filename">bootstrap.jam</code>, after loading some standard
111        definitions, loads two files, which can be provided/customised by
112        user: <code class="filename">site-config.jam</code> and <code class="filename">user-config.jam</code>.</p>
113<p>Locations where those files a search are summarized below:</p>
114<div class="table">
115<a name="bbv2.reference.init.config"></a><p class="title"><b>Table 26.1. Search paths for configuration files</b></p>
116<table class="table" summary="Search paths for configuration files">
117<colgroup>
118<col>
119<col>
120<col>
121</colgroup>
122<thead><tr>
123<th> </th>
124<th>site-config.jam</th>
125<th>user-config.jam</th>
126</tr></thead>
127<tbody>
128<tr>
129<td>Linux</td>
130<td>
131<p><code class="computeroutput">/etc</code></p>
132<p><code class="computeroutput">$HOME</code></p>
133<p><code class="computeroutput">$BOOST_BUILD_PATH</code></p>
134</td>
135<td>
136<p><code class="computeroutput">$HOME</code></p>
137<p><code class="computeroutput">$BOOST_BUILD_PATH</code></p>
138</td>
139</tr>
140<tr>
141<td>Windows</td>
142<td>
143<p><code class="computeroutput">%SystemRoot%</code></p>
144<p><code class="computeroutput">%HOMEDRIVE%%HOMEPATH%</code></p>
145<p><code class="computeroutput">%HOME%</code></p>
146<p><code class="computeroutput">%BOOST_BUILD_PATH%</code></p>
147</td>
148<td>
149<p><code class="computeroutput">%HOMEDRIVE%%HOMEPATH%</code></p>
150<p><code class="computeroutput">%HOME%</code></p>
151<p><code class="computeroutput">%BOOST_BUILD_PATH%</code></p>
152</td>
153</tr>
154</tbody>
155</table>
156</div>
157<p>
158        Boost.Build comes with default versions of those files,
159       
160        which can serve as templates for customized versions.
161      </p>
162</div>
163<div class="section" lang="en">
164<div class="titlepage"><div><div><h3 class="title">
165<a name="bbv2.reference.commandline"></a>Command line</h3></div></div></div>
166<div class="toc"><dl>
167<dt><span class="section"><a href="reference.html#bbv2.reference.init.args">Command line arguments</a></span></dt>
168<dt><span class="section"><a href="reference.html#bbv2.reference.init.options">Command line options</a></span></dt>
169</dl></div>
170<p>The command line may contain:</p>
171<div class="itemizedlist"><ul type="disc">
172<li>Jam options,</li>
173<li>Boost.Build <a href="reference.html#bbv2.reference.init.options" title="Command line options">options</a>,</li>
174<li>Command line arguments</li>
175</ul></div>
176<div class="section" lang="en">
177<div class="titlepage"><div><div><h4 class="title">
178<a name="bbv2.reference.init.args"></a>Command line arguments</h4></div></div></div>
179<p>
180          Command line arguments specify targets and build
181          request using the following rules.
182        </p>
183<div class="itemizedlist"><ul type="disc">
184<li>
185              An argument that does not contain slashes or the <code class="computeroutput">=</code>
186              symbol is either a value of an implicit feature or of a target to
187              be built. It is taken to be value of a feature if an appropriate
188              feature exists. Otherwise, it is considered a <a href="reference/definitions.html#bbv2.reference.ids" title="Target identifiers and references">target id</a>. Building the
189              special target name &#8220;clean&#8221; has the same effect as
190              using the <code class="computeroutput">--clean</code> option.
191            </li>
192<li>
193<p>
194              An argument containing either slashes or
195              the <code class="computeroutput">=</code> symbol specifies a number of build
196              request elements (see ???). In its simplest
197              form, it's just a set of properties, separated by
198              slashes, which become a single build request element,
199              for example:
200
201</p>
202<pre class="programlisting">
203borland/&lt;runtime-link&gt;static
204</pre>
205<p>
206
207              A more complex form can be used to save typing. For example,
208              instead of
209
210</p>
211<pre class="programlisting">
212borland/runtime-link=static borland/runtime-link=dynamic
213</pre>
214<p>
215
216              one can use
217
218</p>
219<pre class="programlisting">
220borland/runtime-link=static,dynamic
221</pre>
222<p>
223
224              Exactly, the conversion from argument to build request
225              elements is performed by (1) splitting the argument at each slash,
226              (2) converting each split part into a set of properties and (3)
227              taking all possible combinations
228               
229              of the property sets. Each split
230              part should have the either the form
231
232</p>
233<pre class="programlisting"><span class="emphasis"><em>feature-name</em></span>=<span class="emphasis"><em>feature-value1</em></span>[","<span class="emphasis"><em>feature-valueN</em></span>]*   
234</pre>
235<p>
236
237              or, in case of implicit features
238
239</p>
240<pre class="programlisting"><span class="emphasis"><em>feature-value1</em></span>[","<span class="emphasis"><em>feature-valueN</em></span>;]*   
241</pre>
242<p>
243
244              will be converted into the property set
245
246</p>
247<pre class="programlisting">
248&lt;feature-name&gt;feature-value1 .... &lt;feature-name&gt;feature-valueN
249</pre>
250</li>
251</ul></div>
252<p>
253          For example, the command line
254
255</p>
256<pre class="programlisting">
257target1 debug gcc/runtime-link=dynamic,static
258</pre>
259<p>
260
261          would cause target called <code class="literal">target1</code> to be rebuilt in
262          debug mode, except that for gcc, both dynamically and statically
263          linked binaries would be created.
264        </p>
265</div>
266<div class="section" lang="en">
267<div class="titlepage"><div><div><h4 class="title">
268<a name="bbv2.reference.init.options"></a>Command line options</h4></div></div></div>
269<p>All of the Boost.Build options start with the "--" prefix.
270          They are described in the following table.</p>
271<div class="table">
272<a name="id2860280"></a><p class="title"><b>Table 26.2. Command line options</b></p>
273<table class="table" summary="Command line options">
274<colgroup>
275<col>
276<col>
277</colgroup>
278<thead><tr>
279<th>Option</th>
280<th>Description</th>
281</tr></thead>
282<tbody>
283<tr>
284<td><code class="literal">--version</code></td>
285<td>Prints information on Boost.Build and Boost.Jam
286                  versions.</td>
287</tr>
288<tr>
289<td>
290<a name="bbv2.reference.init.options.help"></a><code class="literal">--help</code>
291</td>
292<td>Access to the online help system. This prints general
293                  information on how to use the help system with additional
294                  --help* options.</td>
295</tr>
296<tr>
297<td><code class="literal">--clean</code></td>
298<td>Removes everything instead of building. Unlike
299                  <code class="literal">clean</code> target in make, it is possible to clean only
300                  some targets.</td>
301</tr>
302<tr>
303<td><code class="literal">--debug</code></td>
304<td>Enables internal checks.</td>
305</tr>
306<tr>
307<td><code class="literal">--dump-projects</code></td>
308<td>Cause the project structure to be output.</td>
309</tr>
310<tr>
311<td><code class="literal">--no-error-backtrace</code></td>
312<td>Don't print backtrace on errors. Primary useful for
313                  testing.</td>
314</tr>
315<tr>
316<td><code class="literal">--ignore-config</code></td>
317<td>Do not load <code class="literal">site-config.jam</code> and
318                  <code class="literal">user-config.jam</code>
319</td>
320</tr>
321</tbody>
322</table>
323</div>
324</div>
325</div>
326</div>
327</div>
328<table width="100%"><tr>
329<td align="left"></td>
330<td align="right"><small></small></td>
331</tr></table>
332<hr>
333<div class="spirit-nav">
334<a accesskey="p" href="extending/toolset_modules.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../bbv2.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="reference/jamfiles.html"><img src="../images/next.png" alt="Next"></a>
335</div>
336</body>
337</html>
Note: See TracBrowser for help on using the repository browser.