Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

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

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

added boost
File size: 13.6 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Chapter 24. User documentation</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="tutorial/prebuilt.html" title="Prebuilt targets">
19<link rel="next" href="advanced/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="tutorial/prebuilt.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="advanced/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.advanced"></a>Chapter 24. User documentation</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="advanced.html#bbv2.advanced.configuration">Configuration</a></span></dt>
41<dt><span class="section"><a href="advanced/jamfiles.html">Writing Jamfiles</a></span></dt>
42<dd><dl>
43<dt><span class="section"><a href="advanced/jamfiles.html#bbv2.advanced.overview">Overview</a></span></dt>
44<dt><span class="section"><a href="advanced/jamfiles.html#bbv2.advanced.targets">Main targets</a></span></dt>
45<dt><span class="section"><a href="advanced/jamfiles.html#bbv2.advanced.projects">Projects</a></span></dt>
46<dt><span class="section"><a href="advanced/jamfiles.html#bbv2.advanced.other-rules">Jamfile Utility Rules</a></span></dt>
47</dl></dd>
48<dt><span class="section"><a href="advanced/build_process.html">The Build Process</a></span></dt>
49<dd><dl>
50<dt><span class="section"><a href="advanced/build_process.html#id2856769">Build request</a></span></dt>
51<dt><span class="section"><a href="advanced/build_process.html#id2856811">Building a main target</a></span></dt>
52<dt><span class="section"><a href="advanced/build_process.html#id2856924">Building a project</a></span></dt>
53</dl></dd>
54<dt><span class="section"><a href="advanced/builtins/targets.html">Builtin target types</a></span></dt>
55<dd><dl>
56<dt><span class="section"><a href="advanced/builtins/targets.html#id2856983">Programs</a></span></dt>
57<dt><span class="section"><a href="advanced/builtins/targets.html#id2857046">Libraries</a></span></dt>
58<dt><span class="section"><a href="advanced/builtins/targets.html#bbv2.builtins.alias">Alias</a></span></dt>
59<dt><span class="section"><a href="advanced/builtins/targets.html#bbv2.builtins.stage">Installing</a></span></dt>
60<dt><span class="section"><a href="advanced/builtins/targets.html#bbv2.builtins.testing">Testing</a></span></dt>
61</dl></dd>
62<dt><span class="section"><a href="advanced/builtins/features.html">Builtin features</a></span></dt>
63<dt><span class="section"><a href="advanced/differences_to_v1.html">Differences to Boost.Build V1</a></span></dt>
64<dd><dl>
65<dt><span class="section"><a href="advanced/differences_to_v1.html#bbv2.advanced.differences_to_v1.configuration">Configuration</a></span></dt>
66<dt><span class="section"><a href="advanced/differences_to_v1.html#bbv2.advanced.differences_to_v1.jamfiles">Writing Jamfiles</a></span></dt>
67<dt><span class="section"><a href="advanced/differences_to_v1.html#bbv2.advanced.differences_to_v1.build_process">Build process</a></span></dt>
68</dl></dd>
69</dl>
70</div>
71<p>This section will provide the information necessary to create your own
72  projects using Boost.Build. The information provided here is relatively
73  high-level, and <a href="reference.html" title="Chapter 26. Detailed reference">Chapter 26, <i>Detailed reference</i></a> as
74  well as the on-line help system must be used to obtain
75  low-level documentation (see <a href="reference.html#bbv2.reference.init.options.help">???</a>).</p>
76<p>Boost.Build actually consists of two parts - Boost.Jam, a
77  build engine with its own interpreted language, and Boost.Build itself,
78  implemented in Boost.Jam's language. The chain of events when
79  you type <span><strong class="command">bjam</strong></span> on the command line is:
80      </p>
81<div class="orderedlist"><ol type="1">
82<li><p>Boost.Jam tries to find Boost.Build and loads the top-level
83          module. The exact process is described in <a href="reference.html#bbv2.reference.init" title="Initialization">the section called &#8220;Initialization&#8221;</a></p></li>
84<li><p>The top-level module loads user-defined configuration
85          files, <code class="filename">user-config.jam</code> and <code class="filename">site-config.jam</code>, which define
86          available toolsets.</p></li>
87<li><p>The Jamfile in the current directory is read. That in turn
88          might cause reading of further Jamfiles. As a result, a tree of
89          projects is created, with targets inside projects.</p></li>
90<li><p>Finally, using the build request specified on the command line,
91          Boost.Build decides which targets should be built, and how. That
92          information is passed back to Boost.Jam, which takes care of
93          actually running commands.</p></li>
94</ol></div>
95<p>So, to be able to successfully use Boost.Build, you need to know only
96      three things:
97      </p>
98<div class="itemizedlist"><ul type="disc">
99<li><p><a href="advanced.html#bbv2.advanced.configuration" title="Configuration">
100              How to configure Boost.Build</a></p></li>
101<li><p><a href="advanced/jamfiles.html" title="Writing Jamfiles">
102              How to write Jamfiles</a></p></li>
103<li><p><a href="advanced/build_process.html" title="The Build Process">
104              How the build process works</a></p></li>
105<li><p>Some Basics about the Boost.Jam language. See the
106          <a href="http://www.boost.org/tools/build/jam_src/index.html#jam_fundamentals" target="_top">Boost.Jam</a>
107          and <a href="http://www.boost.org/tools/build/jam_src/jam.html" target="_top">Classic
108          Jam</a> documentation.
109          </p></li>
110</ul></div>
111<div class="section" lang="en">
112<div class="titlepage"><div><div><h2 class="title" style="clear: both">
113<a name="bbv2.advanced.configuration"></a>Configuration</h2></div></div></div>
114<p>The Boost.Build configuration is specified in the file
115    <code class="filename">user-config.jam</code>. You can edit the one that comes with Boost.Build, or
116   
117    create a copy in your home directory and edit that. (See the <a href="reference.html#bbv2.reference.init.config" title="Table 26.1. Search paths for configuration files">reference</a> for the exact search
118    paths.) The primary function of that file is to declare which compilers
119    and other tools are available. The simplest syntax to configure a tool is:
120</p>
121<pre class="programlisting">
122using <em class="replaceable"><code>tool-name</code></em> ;       
123</pre>
124<p>
125      The <code class="computeroutput">using</code> rule is given a name of tool, and will make that tool
126      available to Boost.Build. For example, <code class="computeroutput">using gcc ;</code> will make the gcc compiler
127      available.     
128    </p>
129<p>
130      Since nothing but a tool name is specified, Boost.Build will
131      pick some default settings.  For example, it will use the
132      <span><strong class="command">gcc</strong></span> executable found in the
133      <code class="envar">PATH</code>, or look in some known installation
134      locations. In most cases, this strategy works automatically. In
135      case you have several versions of a compiler, it's installed in
136      some unusual location, or you need to tweak its configuration,
137      you'll need to pass additional parameters to the
138      <code class="computeroutput">using</code> rule.  The parameters to
139      <code class="computeroutput">using</code> can be different for each
140      tool.  You can obtain specific documentation for any tool's
141      configuration parameters by invoking
142</p>
143<pre class="programlisting">
144bjam --help <em class="replaceable"><code>tool-name</code></em>.init         
145</pre>
146<p>
147      That said, for all the compiler toolsets Boost.Build supports
148      out-of-the-box, the list of parameters to
149      <code class="computeroutput">using</code> is the same: <em class="parameter"><code>toolset-name</code></em>, <em class="parameter"><code>version</code></em>, <em class="parameter"><code>invocation-command</code></em>, and <em class="parameter"><code>options</code></em>.
150      </p>
151<p>The <em class="parameter"><code>version</code></em>
152    parameter identifies the toolset version, in case you have
153    several installed. It can have any form you like, but
154    it's recommended that you use a numeric identifier like
155    <code class="literal">7.1</code>.
156    </p>
157<p>
158      The <em class="parameter"><code>invocation-command</code></em>
159      parameter is the command that must be executed to run the
160      compiler. This parameter can usually be omitted if the compiler
161      executable
162      </p>
163<div class="itemizedlist"><ul type="disc">
164<li><p>has its &#8220;usual
165      name&#8221; and is in the <code class="envar">PATH</code>,
166      or</p></li>
167<li><p>was installed in a standard
168      &#8220;installation directory&#8221;,
169      or</p></li>
170<li><p>can be found through a global mechanism like the
171      Windows registry.</p></li>
172</ul></div>
173<p>
174
175      For example:
176</p>
177<pre class="programlisting">
178using msvc : 7.1 ;
179using gcc ;
180</pre>
181<p>
182If the compiler can be found in the <code class="envar">PATH</code> but only by a
183nonstandard name, you can just supply that name:
184</p>
185<pre class="programlisting">
186using gcc : : g++-3.2 ;
187</pre>
188<p>
189Otherwise, it might be necessary to supply the complete path to the
190compiler executable:
191</p>
192<pre class="programlisting">
193using msvc : : Z:/Programs/Microsoft Visual Studio/vc98/bin/cl ;
194</pre>
195<p>
196Some Boost.Build toolsets will use that path to take additional
197actions required before invoking the compiler, such as calling
198vendor-supplied scripts to set up its required environment variables.
199</p>
200<p>To configure several versions of a toolset, simply invoke
201    the <code class="computeroutput">using</code> rule multiple times:
202</p>
203<pre class="programlisting">
204using gcc : 3.3 ;
205using gcc : 3.4 : g++-3.4 ;
206using gcc : 3.2 : g++-3.2 ;
207</pre>
208<p>
209        Note that in the first call to
210        <code class="computeroutput">using</code>, the compiler found in the
211        <code class="envar">PATH</code> will be used, and there's no need to
212        explicitly specify the command.
213    </p>
214<p>As shown above, both the <em class="parameter"><code>version</code></em> and <em class="parameter"><code>invocation-command</code></em> parameters are
215    optional, but there's an important restriction: if you configure
216    the same toolset more than once, you must pass the <em class="parameter"><code>version</code></em>
217    parameter every time. For example, the following is not allowed:
218</p>
219<pre class="programlisting">
220using gcc ;
221using gcc : 3.4 : g++-3.4 ;
222</pre>
223<p>
224      because the first <code class="computeroutput">using</code> call does
225      not specify a <em class="parameter"><code>version</code></em>.
226    </p>
227<p>The <em class="parameter"><code>options</code></em>
228    parameter is used to fine-tune the configuration. All of
229    Boost.Build's standard compiler toolsets accept properties of the
230    four builtin features <code class="varname">cflags</code>,
231    <code class="varname">cxxflags</code>, <code class="varname">compileflags</code> and
232    <code class="varname">linkflags</code> as <em class="parameter"><code>options</code></em> specifying flags that will be
233    always passed to the corresponding tools. Values of the
234    <code class="varname">cflags</code> feature are passed directly to the C
235    compiler, values of the <code class="varname">cxxflags</code> feature are
236    passed directly to the C++ compiler, and values of the
237    <code class="varname">compileflags</code> feature are passed to both. For
238    example, to configure a <span><strong class="command">gcc</strong></span> toolset so that it
239    always generates 64-bit code you could write:
240</p>
241<pre class="programlisting">
242using gcc : 3.4 : : &lt;compileflags&gt;-m64 &lt;linkflags&gt;-m64 ;
243</pre>
244</div>
245</div>
246<table width="100%"><tr>
247<td align="left"></td>
248<td align="right"><small></small></td>
249</tr></table>
250<hr>
251<div class="spirit-nav">
252<a accesskey="p" href="tutorial/prebuilt.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="advanced/jamfiles.html"><img src="../images/next.png" alt="Next"></a>
253</div>
254</body>
255</html>
Note: See TracBrowser for help on using the repository browser.