diff options
| author | Douglas Gregor <doug.gregor@gmail.com> | 2005-07-31 16:48:16 +0000 |
|---|---|---|
| committer | Douglas Gregor <doug.gregor@gmail.com> | 2005-07-31 16:48:16 +0000 |
| commit | 6c009ef3685caff213316319b827264c5c1489e5 (patch) | |
| tree | c1305562bc74292e8daefff2313c18d081ba408a /doc/html/bbv2/reference.html | |
| parent | ed6bc8f4c0884495823b25c470838d8094b12446 (diff) | |
| download | boost-6c009ef3685caff213316319b827264c5c1489e5.tar.gz | |
Move 1.33.0 docs over to the branch
[SVN r30340]
Diffstat (limited to 'doc/html/bbv2/reference.html')
| -rw-r--r-- | doc/html/bbv2/reference.html | 337 |
1 files changed, 337 insertions, 0 deletions
diff --git a/doc/html/bbv2/reference.html b/doc/html/bbv2/reference.html new file mode 100644 index 0000000000..5905678b32 --- /dev/null +++ b/doc/html/bbv2/reference.html @@ -0,0 +1,337 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Chapter 26. Detailed reference</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.68.1"> +<style type="text/css"> +body { background-image: url('http://docbook.sourceforge.net/release/images/draft.png'); + background-repeat: no-repeat; + background-position: top left; + /* The following properties make the watermark "fixed" on the page. */ + /* I think that's just a bit too distracting for the reader... */ + /* background-attachment: fixed; */ + /* background-position: center center; */ + }</style> +<link rel="start" href="../index.html" title="The Boost C++ Libraries"> +<link rel="up" href="../bbv2.html" title="Part III. Boost.Build v2 User Manual"> +<link rel="prev" href="extending/toolset_modules.html" title="Toolset modules"> +<link rel="next" href="reference/jamfiles.html" title="Writing Jamfiles"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"> +<td valign="top"><img alt="boost.png (6897 bytes)" width="277" height="86" src="../../../boost.png"></td> +<td align="center"><a href="../../../index.htm">Home</a></td> +<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="../../../people/people.htm">People</a></td> +<td align="center"><a href="../../../more/faq.htm">FAQ</a></td> +<td align="center"><a href="../../../more/index.htm">More</a></td> +</table> +<hr> +<div class="spirit-nav"> +<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> +</div> +<div class="chapter" lang="en"> +<div class="titlepage"><div><div><h2 class="title"> +<a name="bbv2.reference"></a>Chapter 26. Detailed reference</h2></div></div></div> +<div class="toc"> +<p><b>Table of Contents</b></p> +<dl> +<dt><span class="section"><a href="reference.html#bbv2.reference.general">General information</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="reference.html#bbv2.reference.init">Initialization</a></span></dt> +<dt><span class="section"><a href="reference.html#bbv2.reference.commandline">Command line</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="reference/jamfiles.html">Writing Jamfiles</a></span></dt> +<dd><dl><dt><span class="section"><a href="reference/jamfiles.html#bbv2.reference.headers">Generated headers</a></span></dt></dl></dd> +<dt><span class="section"><a href="reference/buildprocess.html">Build process</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="reference/buildprocess.html#bbv2.reference.buildprocess.alternatives">Alternative selection</a></span></dt> +<dt><span class="section"><a href="reference/buildprocess.html#bbv2.reference.buildprocess.common">Determining common properties</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="reference/definitions.html">Definitions</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="reference/definitions.html#bbv2.reference.features">Features and properties</a></span></dt> +<dt><span class="section"><a href="reference/definitions.html#bbv2.reference.variants">Build Variants</a></span></dt> +<dt><span class="section"><a href="reference/definitions.html#bbv2.reference.variants.proprefine">Property refinement</a></span></dt> +<dt><span class="section"><a href="reference/definitions.html#bbv2.reference.variants.propcond">Conditional properties</a></span></dt> +<dt><span class="section"><a href="reference/definitions.html#bbv2.reference.ids">Target identifiers and references</a></span></dt> +</dl></dd> +<dt><span class="section"><a href="reference/generators.html">Generators</a></span></dt> +<dd><dl> +<dt><span class="section"><a href="reference/generators.html#id1708734">Selecting and ranking viable generators</a></span></dt> +<dt><span class="section"><a href="reference/generators.html#id1708774">Running generators</a></span></dt> +<dt><span class="section"><a href="reference/generators.html#id1708800">Selecting dependency graph</a></span></dt> +<dt><span class="section"><a href="reference/generators.html#id1708811">Property adjustment</a></span></dt> +<dt><span class="section"><a href="reference/generators.html#id1708854">Transformations cache</a></span></dt> +</dl></dd> +</dl> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bbv2.reference.general"></a>General information</h2></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="reference.html#bbv2.reference.init">Initialization</a></span></dt> +<dt><span class="section"><a href="reference.html#bbv2.reference.commandline">Command line</a></span></dt> +</dl></div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bbv2.reference.init"></a>Initialization</h3></div></div></div> +<p>bjam's first job upon startup is to load the Jam code that + implements the build system. To do this, it searches for a file + called <code class="filename">boost-build.jam</code>, first in the invocation directory, then + in its parent and so forth up to the filesystem root, and finally + in the directories specified by the environment variable + BOOST_BUILD_PATH. When found, the file is interpreted, and should + specify the build system location by calling the boost-build + rule:</p> +<pre class="programlisting"> +rule boost-build ( location ? ) +</pre> +<p> + If location is a relative path, it is treated as relative to + the directory of <code class="filename">boost-build.jam</code>. The directory specified by + that location and the directories in BOOST_BUILD_PATH are then searched for + a file called <code class="filename">bootstrap.jam</code>, which is expected to + bootstrap the build system. This arrangement allows the build + system to work without any command-line or environment variable + settings. For example, if the build system files were located in a + directory "build-system/" at your project root, you might place a + <code class="filename">boost-build.jam</code> at the project root containing: + +</p> +<pre class="programlisting"> +boost-build build-system ; +</pre> +<p> + + In this case, running bjam anywhere in the project tree will + automatically find the build system.</p> +<p>The default <code class="filename">bootstrap.jam</code>, after loading some standard + definitions, loads two files, which can be provided/customised by + user: <code class="filename">site-config.jam</code> and <code class="filename">user-config.jam</code>.</p> +<p>Locations where those files a search are summarized below:</p> +<div class="table"> +<a name="bbv2.reference.init.config"></a><p class="title"><b>Table 26.1. Search paths for configuration files</b></p> +<table class="table" summary="Search paths for configuration files"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th> </th> +<th>site-config.jam</th> +<th>user-config.jam</th> +</tr></thead> +<tbody> +<tr> +<td>Linux</td> +<td> +<p><code class="computeroutput">/etc</code></p> +<p><code class="computeroutput">$HOME</code></p> +<p><code class="computeroutput">$BOOST_BUILD_PATH</code></p> +</td> +<td> +<p><code class="computeroutput">$HOME</code></p> +<p><code class="computeroutput">$BOOST_BUILD_PATH</code></p> +</td> +</tr> +<tr> +<td>Windows</td> +<td> +<p><code class="computeroutput">%SystemRoot%</code></p> +<p><code class="computeroutput">%HOMEDRIVE%%HOMEPATH%</code></p> +<p><code class="computeroutput">%HOME%</code></p> +<p><code class="computeroutput">%BOOST_BUILD_PATH%</code></p> +</td> +<td> +<p><code class="computeroutput">%HOMEDRIVE%%HOMEPATH%</code></p> +<p><code class="computeroutput">%HOME%</code></p> +<p><code class="computeroutput">%BOOST_BUILD_PATH%</code></p> +</td> +</tr> +</tbody> +</table> +</div> +<p> + Boost.Build comes with default versions of those files, + + which can serve as templates for customized versions. + </p> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bbv2.reference.commandline"></a>Command line</h3></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="reference.html#bbv2.reference.init.args">Command line arguments</a></span></dt> +<dt><span class="section"><a href="reference.html#bbv2.reference.init.options">Command line options</a></span></dt> +</dl></div> +<p>The command line may contain:</p> +<div class="itemizedlist"><ul type="disc"> +<li>Jam options,</li> +<li>Boost.Build <a href="reference.html#bbv2.reference.init.options" title="Command line options">options</a>,</li> +<li>Command line arguments</li> +</ul></div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="bbv2.reference.init.args"></a>Command line arguments</h4></div></div></div> +<p> + Command line arguments specify targets and build + request using the following rules. + </p> +<div class="itemizedlist"><ul type="disc"> +<li> + An argument that does not contain slashes or the <code class="computeroutput">=</code> + symbol is either a value of an implicit feature or of a target to + be built. It is taken to be value of a feature if an appropriate + 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 + special target name “clean” has the same effect as + using the <code class="computeroutput">--clean</code> option. + </li> +<li> +<p> + An argument containing either slashes or + the <code class="computeroutput">=</code> symbol specifies a number of build + request elements (see ???). In its simplest + form, it's just a set of properties, separated by + slashes, which become a single build request element, + for example: + +</p> +<pre class="programlisting"> +borland/<runtime-link>static +</pre> +<p> + + A more complex form can be used to save typing. For example, + instead of + +</p> +<pre class="programlisting"> +borland/runtime-link=static borland/runtime-link=dynamic +</pre> +<p> + + one can use + +</p> +<pre class="programlisting"> +borland/runtime-link=static,dynamic +</pre> +<p> + + Exactly, the conversion from argument to build request + elements is performed by (1) splitting the argument at each slash, + (2) converting each split part into a set of properties and (3) + taking all possible combinations + + of the property sets. Each split + part should have the either the form + +</p> +<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>]* +</pre> +<p> + + or, in case of implicit features + +</p> +<pre class="programlisting"><span class="emphasis"><em>feature-value1</em></span>[","<span class="emphasis"><em>feature-valueN</em></span>;]* +</pre> +<p> + + will be converted into the property set + +</p> +<pre class="programlisting"> +<feature-name>feature-value1 .... <feature-name>feature-valueN +</pre> +</li> +</ul></div> +<p> + For example, the command line + +</p> +<pre class="programlisting"> +target1 debug gcc/runtime-link=dynamic,static +</pre> +<p> + + would cause target called <code class="literal">target1</code> to be rebuilt in + debug mode, except that for gcc, both dynamically and statically + linked binaries would be created. + </p> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="bbv2.reference.init.options"></a>Command line options</h4></div></div></div> +<p>All of the Boost.Build options start with the "--" prefix. + They are described in the following table.</p> +<div class="table"> +<a name="id1707672"></a><p class="title"><b>Table 26.2. Command line options</b></p> +<table class="table" summary="Command line options"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th>Option</th> +<th>Description</th> +</tr></thead> +<tbody> +<tr> +<td><code class="literal">--version</code></td> +<td>Prints information on Boost.Build and Boost.Jam + versions.</td> +</tr> +<tr> +<td> +<a name="bbv2.reference.init.options.help"></a><code class="literal">--help</code> +</td> +<td>Access to the online help system. This prints general + information on how to use the help system with additional + --help* options.</td> +</tr> +<tr> +<td><code class="literal">--clean</code></td> +<td>Removes everything instead of building. Unlike + <code class="literal">clean</code> target in make, it is possible to clean only + some targets.</td> +</tr> +<tr> +<td><code class="literal">--debug</code></td> +<td>Enables internal checks.</td> +</tr> +<tr> +<td><code class="literal">--dump-projects</code></td> +<td>Cause the project structure to be output.</td> +</tr> +<tr> +<td><code class="literal">--no-error-backtrace</code></td> +<td>Don't print backtrace on errors. Primary useful for + testing.</td> +</tr> +<tr> +<td><code class="literal">--ignore-config</code></td> +<td>Do not load <code class="literal">site-config.jam</code> and + <code class="literal">user-config.jam</code> +</td> +</tr> +</tbody> +</table> +</div> +</div> +</div> +</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="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> +</div> +</body> +</html> |