diff options
Diffstat (limited to 'doc/html/bbv2')
| -rw-r--r--[-rwxr-xr-x] | doc/html/bbv2/extender.html | 89 | ||||
| -rw-r--r--[-rwxr-xr-x] | doc/html/bbv2/faq.html | 26 | ||||
| -rw-r--r-- | doc/html/bbv2/installation.html | 8 | ||||
| -rw-r--r--[-rwxr-xr-x] | doc/html/bbv2/overview.html | 214 | ||||
| -rw-r--r--[-rwxr-xr-x] | doc/html/bbv2/reference.html | 1001 | ||||
| -rw-r--r--[-rwxr-xr-x] | doc/html/bbv2/tasks.html | 164 | ||||
| -rw-r--r--[-rwxr-xr-x] | doc/html/bbv2/tutorial.html | 163 |
7 files changed, 1298 insertions, 367 deletions
diff --git a/doc/html/bbv2/extender.html b/doc/html/bbv2/extender.html index 95749df283..955e87fd87 100755..100644 --- a/doc/html/bbv2/extender.html +++ b/doc/html/bbv2/extender.html @@ -93,15 +93,18 @@ in Jamfile, such as metatarget kind, name, sources and properties, and can be called with specific properties to generate concrete targets. At the code level it is represented by an instance of - class derived from <code class="computeroutput">abstract-target</code>. - <sup>[<a name="id3906715" href="#ftn.id3906715" class="footnote">13</a>]</sup> + class derived from <a class="link" href="reference.html#bbv2.reference.class.abstract-target" title="Class abstract-target">abstract-target</a>. + <sup>[<a name="id4013451" href="#ftn.id4013451" class="footnote">13</a>]</sup> </p> -<p>The <code class="computeroutput">generate</code> method takes the build properties - (as an instance of the <code class="computeroutput">property-set</code> class) and returns +<p>The <a class="link" href="reference.html#bbv2.reference.class.abstract-target.generate">generate</a> + method takes the build properties + (as an instance of the <a class="link" href="reference.html#bbv2.reference.class.property-set" title="Class property-set"> + property-set</a> class) and returns a list containing:</p> <div class="itemizedlist"><ul class="itemizedlist" type="disc"> <li class="listitem"><p>As front element—Usage-requirements from this invocation - (an instance of <code class="computeroutput">property-set</code>)</p></li> + (an instance of <a class="link" href="reference.html#bbv2.reference.class.property-set" title="Class property-set"> + property-set</a>)</p></li> <li class="listitem"><p>As subsequent elements—created concrete targets ( instances of the <code class="computeroutput">virtual-target</code> class.)</p></li> </ul></div> @@ -109,41 +112,46 @@ <code class="computeroutput">targets.resolve-reference</code> function, and the <code class="computeroutput">targets.generate-from-reference</code> function can both lookup and generate a metatarget.</p> -<p>The <code class="computeroutput">abstract-target</code> class has three immediate - derived classes:</p> +<p>The <a class="link" href="reference.html#bbv2.reference.class.abstract-target" title="Class abstract-target">abstract-target</a> + class has three immediate derived classes:</p> <div class="itemizedlist"><ul class="itemizedlist" type="disc"> -<li class="listitem"><p><code class="computeroutput">project-target</code> that +<li class="listitem"><p><a class="link" href="reference.html#bbv2.reference.class.project-target" title="Class project-target">project-target</a> that corresponds to a project and is not intended for further - subclassing. The <code class="computeroutput">generate</code> method of this + subclassing. The <a class="link" href="reference.html#bbv2.reference.class.project-target.generate"> + generate</a> method of this class builds all targets in the project that are not marked as explicit.</p></li> -<li class="listitem"><p><code class="computeroutput">main-target</code> corresponds to a target in a project +<li class="listitem"><p><a class="link" href="reference.html#bbv2.reference.class.main-target" title="Class main-target">main-target</a> + corresponds to a target in a project and contains one or more target alternatives. This class also should not be - subclassed. The <code class="computeroutput">generate</code> method of this class selects - an alternative to build, and calls the <code class="computeroutput">generate</code> method of that - alternative.</p></li> -<li class="listitem"><p><code class="computeroutput">basic-target</code> corresponds to a - specific target alternative. This is base class, with a number of - derived classes. The <code class="computeroutput">generate</code> method + subclassed. The <a class="link" href="reference.html#bbv2.reference.class.main-target.generate">generate</a> + method of this class selects an alternative to build, and calls the + <a class="link" href="reference.html#bbv2.reference.class.basic-target.generate">generate</a> + method of that alternative.</p></li> +<li class="listitem"><p><a class="link" href="reference.html#bbv2.reference.class.basic-target" title="Class basic-target">basic-target</a> + corresponds to a specific target alternative. This is base class, + with a number of derived classes. The + <a class="link" href="reference.html#bbv2.reference.class.basic-target.generate">generate</a> method processes the target requirements and requested build properties to determine final properties for the target, builds all sources, and - finally calls the abstract <code class="computeroutput">construct</code> method with the list - of source virtual targets, and the final properties. + finally calls the abstract + <a class="link" href="reference.html#bbv2.reference.class.basic-target.construct">construct</a> + method with the list of source virtual targets, and the final properties. </p></li> </ul></div> -<p>The instances of the <code class="computeroutput">project-target</code> and - <code class="computeroutput">main-target</code> classes are created +<p>The instances of the <a class="link" href="reference.html#bbv2.reference.class.project-target" title="Class project-target">project-target</a> and + <a class="link" href="reference.html#bbv2.reference.class.main-target" title="Class main-target">main-target</a> classes are created implicitly—when loading a new Jamfiles, or when a new target alternative with as-yet unknown name is created. The instances of the - classes derived from <code class="computeroutput">basic-target</code> are typically - created when Jamfile calls a <em class="firstterm">metatarget rule</em>, + classes derived from <a class="link" href="reference.html#bbv2.reference.class.basic-target" title="Class basic-target">basic-target</a> + are typically created when Jamfile calls a <em class="firstterm">metatarget rule</em>, such as such as <code class="computeroutput">exe</code>. </p> <p>It it permissible to create a custom class derived from - <code class="computeroutput">basic-target</code> and create new metatarget rule + <a class="link" href="reference.html#bbv2.reference.class.basic-target" title="Class basic-target">basic-target</a> and create new metatarget rule that creates instance of such target. However, in the majority - of cases, a specific subclass of <code class="computeroutput">basic-target</code>— - <code class="computeroutput">typed-target</code> is used. That class is associated + of cases, a specific subclass of <a class="link" href="reference.html#bbv2.reference.class.basic-target" title="Class basic-target">basic-target</a>— + <a class="link" href="reference.html#bbv2.reference.class.typed-target" title="Class typed-target">typed-target</a> is used. That class is associated with a <em class="firstterm">type</em> and relays to <em class="firstterm">generators</em> to construct concrete targets of that type. This process will be explained below. When a new type is declared, a new metatarget rule is automatically defined. @@ -158,8 +166,8 @@ subclass is <code class="computeroutput">file-target</code>. A file target is associated with an action that creates it— an instance of the <code class="computeroutput">action</code> class. The action, in turn, hold a list of source targets. It also holds the - <code class="computeroutput">property-set</code> instance with the build properties that - should be used for the action.</p> + <a class="link" href="reference.html#bbv2.reference.class.property-set" title="Class property-set">property-set</a> + instance with the build properties that should be used for the action.</p> <p>Here's an example of creating a target from another target, <code class="computeroutput">source</code></p> <pre class="programlisting"> local a = [ new action $(source) : common.copy : $(property-set) ] ; @@ -177,7 +185,7 @@ local t = [ new file-target $(name) : CPP : $(project) : $(a) ] ; that correspond to the same file clearly will result in problems. Therefore, whenever returning targets you should pass them via the <code class="computeroutput">virtual-target.register</code> function, that will replace targets with previously created identical ones, as - necessary.<sup>[<a name="id3907057" href="#ftn.id3907057" class="footnote">14</a>]</sup> + necessary.<sup>[<a name="id4013834" href="#ftn.id4013834" class="footnote">14</a>]</sup> Here are a couple of examples: </p> <pre class="programlisting"> @@ -199,13 +207,14 @@ return [ sequence.transform virtual-target.register : $(targets) ] ; <p>In practice, most files have specific types, and most tools consume and produce files of specific type. To take advantage of this fact, Boost.Build defines concept of target type and - <a class="indexterm" name="id3907117"></a> + <a class="indexterm" name="id4013893"></a> <em class="firstterm">generators</em>, and has special metatarget class - <code class="computeroutput">typed-target</code>. Target type is merely an + <a class="link" href="reference.html#bbv2.reference.class.typed-target" title="Class typed-target">typed-target</a>. Target type is merely an identifier. It is associated with a set of file extensions that correspond to that type. Generator is an abstraction of a tool. It advertises the types it produces and, if called with a set of input target, tries to construct - output targets of the advertised types. Finally, <code class="computeroutput">typed-target</code> + output targets of the advertised types. Finally, + <a class="link" href="reference.html#bbv2.reference.class.typed-target" title="Class typed-target">typed-target</a> is associated with specific target type, and relays the generator (or generators) for that type. </p> @@ -245,7 +254,7 @@ return [ sequence.transform virtual-target.register : $(targets) ] ; import type ; type.register VERBATIM : verbatim ; </pre> -<p>The first parameter to <code class="computeroutput">type.register</code> gives +<p>The first parameter to <a class="link" href="reference.html#bbv2.reference.modules.type.register">type.register</a> gives the name of the declared type. By convention, it's uppercase. The second parameter is the suffix for files of this type. So, if Boost.Build sees <code class="filename">code.verbatim</code> in a list of sources, it knows that it's of @@ -483,7 +492,7 @@ generators.register-composing mex.mex : CPP LIB : MEX ; </p> <p>(Need a note about UNIX)</p> <h4> -<a name="id3907794"></a>Custom generator classes</h4> +<a name="id4014577"></a>Custom generator classes</h4> <p>The standard generators allows you to specify source and target types, an action, and a set of flags. If you need anything more complex, @@ -691,7 +700,7 @@ actions inline-file <p> </p> <h4> -<a name="id3908076"></a>Steps for adding a feauture</h4> +<a name="id4014858"></a>Steps for adding a feauture</h4> <p>Adding a feature requires three steps: </p> @@ -732,7 +741,7 @@ actions inline-file <p> </p> <h4> -<a name="id3908175"></a>Another example</h4> +<a name="id4014957"></a>Another example</h4> <p>Here's another example. Let's see how we can make a feature that refers to a target. For example, when linking dynamic libraries on Windows, one sometimes needs to @@ -814,7 +823,7 @@ rule link </li> </ol></div> <h4> -<a name="id3908286"></a>Variants and composite features.</h4> +<a name="id4015068"></a>Variants and composite features.</h4> <p>Sometimes you want to create a shortcut for some set of features. For example, <code class="computeroutput">release</code> is a value of <code class="computeroutput"><variant></code> and is a shortcut for a set of features. @@ -857,8 +866,8 @@ feature.compose <parallelism>fake : <library>/mpi//fake/<parallel <div class="titlepage"><div><div><h3 class="title"> <a name="bbv2.extending.rules"></a>Main target rules</h3></div></div></div> <p> - A main target rule (e.g “<code class="computeroutput">exe</code>” - Or “<code class="computeroutput">lib</code>”) creates a top-level target. It's quite likely that you'll want to declare your own and + A main target rule (e.g “<a class="link" href="tasks.html#bbv2.tasks.programs" title="Programs">exe</a>” + Or “<a class="link" href="tasks.html#bbv2.tasks.libraries" title="Libraries">lib</a>”) creates a top-level target. It's quite likely that you'll want to declare your own and there are two ways to do that. </p> @@ -1012,9 +1021,9 @@ using yfc ; </div> <div class="footnotes"> <br><hr width="100" align="left"> -<div class="footnote"><p><sup>[<a id="ftn.id3906715" href="#id3906715" class="para">13</a>] </sup>This name is historic, and will be eventuall changed to +<div class="footnote"><p><sup>[<a id="ftn.id4013451" href="#id4013451" class="para">13</a>] </sup>This name is historic, and will be eventuall changed to <code class="computeroutput">metatarget</code></p></div> -<div class="footnote"><p><sup>[<a id="ftn.id3907057" href="#id3907057" class="para">14</a>] </sup>This create-then-register pattern is caused by limitations +<div class="footnote"><p><sup>[<a id="ftn.id4013834" href="#id4013834" class="para">14</a>] </sup>This create-then-register pattern is caused by limitations of the Boost.Jam language. Python port is likely to never create duplicate targets.</p></div> </div> </div> diff --git a/doc/html/bbv2/faq.html b/doc/html/bbv2/faq.html index 36b118e56e..be0aa5ee07 100755..100644 --- a/doc/html/bbv2/faq.html +++ b/doc/html/bbv2/faq.html @@ -25,29 +25,29 @@ <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="bbv2.faq"></a>Frequently Asked Questions</h2></div></div></div> <div class="toc"><dl> -<dt><span class="section"><a href="faq.html#id3908656"> +<dt><span class="section"><a href="faq.html#bbv2.faq.featurevalue"> How do I get the current value of feature in Jamfile? </a></span></dt> -<dt><span class="section"><a href="faq.html#id3908718"> +<dt><span class="section"><a href="faq.html#bbv2.faq.duplicate"> I am getting a "Duplicate name of actual target" error. What does that mean? </a></span></dt> <dt><span class="section"><a href="faq.html#bbv2.faq.envar"> Accessing environment variables </a></span></dt> -<dt><span class="section"><a href="faq.html#id3908985"> +<dt><span class="section"><a href="faq.html#bbv2.faq.proporder"> How to control properties order? </a></span></dt> -<dt><span class="section"><a href="faq.html#id3909040"> +<dt><span class="section"><a href="faq.html#bbv2.faq.liborder"> How to control the library linking order on Unix? </a></span></dt> <dt><span class="section"><a href="faq.html#bbv2.faq.external"> Can I get capture external program output using a Boost.Jam variable? </a></span></dt> -<dt><span class="section"><a href="faq.html#id3909184"> +<dt><span class="section"><a href="faq.html#bbv2.faq.projectroot"> How to get the project root (a.k.a. Jamroot) location? </a></span></dt> -<dt><span class="section"><a href="faq.html#id3909210"> +<dt><span class="section"><a href="faq.html#bbv2.faq.flags"> How to change compilation flags for one file? </a></span></dt> <dt><span class="section"><a href="faq.html#bbv2.faq.dll-path"> @@ -59,13 +59,13 @@ </dl></div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="id3908656"></a> +<a name="bbv2.faq.featurevalue"></a> How do I get the current value of feature in Jamfile? </h3></div></div></div> <p> This is not possible, since Jamfile does not have "current" value of any feature, be it toolset, build variant or anything else. For a single - invocation of <code class="filename">bjam</code>, any given main target can be + run of Boost.Build, any given main target can be built with several property sets. For example, user can request two build variants on the command line. Or one library is built as shared when used from one application, and as static when used from another. Each Jamfile @@ -89,7 +89,7 @@ </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="id3908718"></a> +<a name="bbv2.faq.duplicate"></a> I am getting a "Duplicate name of actual target" error. What does that mean? </h3></div></div></div> @@ -230,7 +230,7 @@ exe a : a.cpp : <include>$(SOME_LIBRARY_PATH) ; </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="id3908985"></a> +<a name="bbv2.faq.proporder"></a> How to control properties order? </h3></div></div></div> <p> @@ -261,7 +261,7 @@ exe a : a.cpp : <include>a&&b ; </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="id3909040"></a> +<a name="bbv2.faq.liborder"></a> How to control the library linking order on Unix? </h3></div></div></div> <p> @@ -317,7 +317,7 @@ local gtk_includes = [ SHELL "gtk-config --cflags" ] ; </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="id3909184"></a> +<a name="bbv2.faq.projectroot"></a> How to get the project root (a.k.a. Jamroot) location? </h3></div></div></div> <p> @@ -333,7 +333,7 @@ path-constant TOP : . ; </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> -<a name="id3909210"></a> +<a name="bbv2.faq.flags"></a> How to change compilation flags for one file? </h3></div></div></div> <p> diff --git a/doc/html/bbv2/installation.html b/doc/html/bbv2/installation.html index 83e7f004c0..507f39d195 100644 --- a/doc/html/bbv2/installation.html +++ b/doc/html/bbv2/installation.html @@ -41,7 +41,7 @@ </li> <li class="listitem"> Run - <pre class="screen">./bjam install --prefix=<em class="replaceable"><code>PREFIX</code></em></pre> + <pre class="screen">./b2 install --prefix=<em class="replaceable"><code>PREFIX</code></em></pre> where <em class="replaceable"><code>PREFIX</code></em> is a directory where you want Boost.Build to be installed. </li> @@ -50,15 +50,15 @@ to your <code class="envar">PATH</code> environment variable. </li> </ol></div> -<p>If you are not using Boost.Build package, but rather the version +<p>If you are not using a Boost.Build package, but rather the version bundled with the Boost C++ Libraries, the above commands should be run in the <code class="filename">tools/build/v2</code> directory.</p> <p> - Now that Boost.Build is installed, you can try some of examples. Copy + Now that Boost.Build is installed, you can try some of the examples. Copy <code class="filename"><em class="replaceable"><code>PREFIX</code></em>/share/boost-build/examples/hello</code> to a different directory, then change to that directory and run: </p> -<pre class="screen"><code class="filename"><em class="replaceable"><code>PREFIX</code></em>/bin/bjam</code></pre> +<pre class="screen"><code class="filename"><em class="replaceable"><code>PREFIX</code></em>/bin/b2</code></pre> <p> A simple executable should be built. </p> diff --git a/doc/html/bbv2/overview.html b/doc/html/bbv2/overview.html index 3bce75193a..89e5f54953 100755..100644 --- a/doc/html/bbv2/overview.html +++ b/doc/html/bbv2/overview.html @@ -44,17 +44,17 @@ Boost.Build actually consists of two parts - Boost.Jam, a build engine with its own interpreted language, and Boost.Build itself, implemented in Boost.Jam's language. The chain of events when you type - <span class="command"><strong>bjam</strong></span> on the command line is as follows: + <span class="command"><strong>b2</strong></span> on the command line is as follows: </p> <div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"><p> - Boost.Jam tries to find Boost.Build and loads the top-level module. - The exact process is described in <a class="xref" href="reference.html#bbv2.reference.init" title="Initialization">the section called “Initialization”</a> + The Boost.Build executable tries to find Boost.Build modules and + loads the top-level module. The exact process is described in <a class="xref" href="reference.html#bbv2.reference.init" title="Initialization">the section called “Initialization”</a> </p></li> <li class="listitem"><p> The top-level module loads user-defined configuration files, - <code class="filename">user-config.jam</code> and <code class="filename">site-config.jam - </code>, which define available toolsets. + <code class="filename">user-config.jam</code> and + <code class="filename">site-config.jam</code>, which define available toolsets. </p></li> <li class="listitem"><p> The Jamfile in the current directory is read. That in turn might @@ -109,8 +109,8 @@ a.o: a.c g++ -o a.o -g a.c </pre> <p> - This is rather low-level description mechanism and it's hard to adjust commands, options, - and sets of created targets depending on the used compiler and operating system. + This is a rather low-level description mechanism and it's hard to adjust commands, options, + and sets of created targets depending on the compiler and operating system used. </p> <p> To improve portability, most modern build system provide a set of higher-level @@ -120,19 +120,19 @@ a.o: a.c add_program ("a", "a.c") </pre> <p> - This is a function call that creates targets necessary to create executable file - from source file <code class="filename">a.c</code>. Depending on configured properties, - different commands line may be used. However, <code class="computeroutput">add_program</code> is higher-level, - but rather thin level. All targets are created immediately when build description + This is a function call that creates the targets necessary to create a executable file + from the source file <code class="filename">a.c</code>. Depending on configured properties, + different command lines may be used. However, <code class="computeroutput">add_program</code> is higher-level, + but rather thin level. All targets are created immediately when the build description is parsed, which makes it impossible to perform multi-variant builds. Often, change - in any build property requires complete reconfiguration of the build tree. + in any build property requires a complete reconfiguration of the build tree. </p> <p> - In order to support true multivariant builds, Boost.Build introduces the concept of - <a class="indexterm" name="id3894430"></a> - <a class="indexterm" name="id3894441"></a> - <em class="firstterm">metatarget</em>—object that is created when build description - is parsed and can be later called with specific build properties to generate + In order to support true multivariant builds, Boost.Build introduces the concept of a + <a class="indexterm" name="id3994348"></a> + <a class="indexterm" name="id3994361"></a> + <em class="firstterm">metatarget</em>—an object that is created when the build description + is parsed and can be called later with specific build properties to generate actual targets. </p> <p> @@ -143,12 +143,12 @@ exe a : a.cpp ; </pre> <p> When this declaration is parsed, Boost.Build creates a metatarget, but does not - yet decides what files must be created, or what commands must be used. After - all build files are parsed, Boost.Build considers properties requested on the + yet decide what files must be created, or what commands must be used. After + all build files are parsed, Boost.Build considers the properties requested on the command line. Supposed you have invoked Boost.Build with: </p> <pre class="screen"> -bjam toolset=gcc toolset=msvc +b2 toolset=gcc toolset=msvc </pre> <p> In that case, the metatarget will be called twice, once with <code class="computeroutput">toolset=gcc</code> @@ -156,26 +156,26 @@ bjam toolset=gcc toolset=msvc targets, that will have different extensions and use different command lines. </p> <p> - Another key concept is - <a class="indexterm" name="id3894500"></a> - <em class="firstterm">build property</em>. Build property is a variable + Another key concept is + <a class="indexterm" name="id3994420"></a> + <em class="firstterm">build property</em>. A build property is a variable that affects the build process. It can be specified on the command line, and is passed when calling a metatarget. While all build tools have a similar mechanism, Boost.Build differs by requiring that all build properties are declared in advance, and providing a large set of properties with portable semantics. </p> <p> - The final concept is <a class="indexterm" name="id3894523"></a> + The final concept is <a class="indexterm" name="id3994442"></a> <em class="firstterm">property propagation</em>. Boost.Build does not require that every metatarget is called with the same properties. Instead, the "top-level" metatargets are called with the properties specified on the command line. Each metatarget can elect to augment or override some properties (in particular, using the requirements mechanism, see <a class="xref" href="overview.html#bbv2.overview.targets.requirements" title="Requirements">the section called “Requirements”</a>). - Then, the dependency metatargets are called with modified properties and produce - concrete targets that are then used in build process. Of course, dependency metatargets + Then, the dependency metatargets are called with the modified properties and produce + concrete targets that are then used in the build process. Of course, dependency metatargets maybe in turn modify build properties and have dependencies of their own. </p> -<p>For more in-depth treatment of the requirements and concepts, you may refer +<p>For a more in-depth treatment of the requirements and concepts, you may refer to <a href="http://syrcose.ispras.ru/2009/files/04_paper.pdf" target="_top">SYRCoSE 2009 Boost.Build article</a>. </p> </div> @@ -183,15 +183,15 @@ bjam toolset=gcc toolset=msvc <div class="titlepage"><div><div><h3 class="title"> <a name="bbv2.overview.jam_language"></a>Boost.Jam Language</h3></div></div></div> <p> - This section will describe the basics of the Boost.Jam language— - just enough for writing Jamfiles. For more information, please see the + This section will describe the basics of the Boost.Jam language—just + enough for writing Jamfiles. For more information, please see the <a class="link" href="../">Boost.Jam</a> documentation. </p> <p> <a class="link" href="../">Boost.Jam</a> has an interpreted, procedural language. On the lowest level, a <a class="link" href="../">Boost.Jam - </a> program consists of variables and <a class="indexterm" name="id3894614"></a> <em class="firstterm">rules</em> (Jam term for - function). They are grouped into modules—there is one global + </a> program consists of variables and <a class="indexterm" name="id3994534"></a> <em class="firstterm">rules</em> (the Jam term for + functions). They are grouped into modules—there is one global module and a number of named modules. Besides that, a <a class="link" href="../">Boost.Jam</a> program contains classes and class instances. </p> @@ -358,15 +358,15 @@ import <em class="replaceable"><code>module</code></em> ; import <em class="replaceable"><code>module</code></em> : <em class="replaceable"><code>rule</code></em> ; </pre> <p> - The first form imports the specified bjam module. All rules from that + The first form imports the specified module. All rules from that module are made available using the qualified name: <code class="computeroutput"><em class="replaceable"><code> module</code></em>.<em class="replaceable"><code>rule</code></em></code>. The second form imports the specified rules only, and they can be called using unqualified names. </p> <p><a name="bbv2.overview.jam_language.actions"></a> - Sometimes, you'd need to specify the actual command lines to be used - when creating targets. In jam language, you use named actions to do + Sometimes, you need to specify the actual command lines to be used + when creating targets. In the jam language, you use named actions to do this. For example: </p> <pre class="programlisting"> @@ -383,8 +383,8 @@ actions create-file-from-another </code> variable will be expanded to a list of source files. </p> <p> - To flexibly adjust the command line, you can define a rule with the same - name as the action and taking three parameters -- targets, sources and + To adjust the command line flexibly, you can define a rule with the same + name as the action and taking three parameters—targets, sources and properties. For example: </p> <pre class="programlisting"> @@ -401,15 +401,15 @@ actions create-file-from-another } </pre> <p> - In this example, the rule checks if certain build property is specified. - If so, it sets variable <code class="varname">OPIONS</code> that is then used + In this example, the rule checks if a certain build property is specified. + If so, it sets the variable <code class="varname">OPIONS</code> that is then used inside the action. Note that the variables set "on a target" will be visible only inside actions building that target, not globally. Were they set globally, using variable named <code class="varname">OPTIONS</code> in two unrelated actions would be impossible. </p> <p> - More details can be found in Jam reference, <a class="xref" href="../jam/language.html#jam.language.rules" title="Rules">the section called “Rules”</a>. + More details can be found in the Jam reference, <a class="xref" href="../jam/language.html#jam.language.rules" title="Rules">the section called “Rules”</a>. </p> </div> <div class="section"> @@ -418,9 +418,9 @@ actions create-file-from-another <p> On startup, Boost.Build searches and reads two configuration files: <code class="filename">site-config.jam</code> and <code class="filename">user-config.jam</code>. - The first one is usually installed and maintained by system administrator, and - the second is for user to modify. You can edit the one in the top-level - directory of Boost.Build installation or create a copy in your home + The first one is usually installed and maintained by a system administrator, and + the second is for the user to modify. You can edit the one in the top-level + directory of your Boost.Build installation or create a copy in your home directory and edit the copy. The following table explains where both files are searched. </p> @@ -478,7 +478,7 @@ actions create-file-from-another </p></td></tr> </table></div> <p> - Usually, <code class="filename">user-config.jam</code> just defines available compilers + Usually, <code class="filename">user-config.jam</code> just defines the available compilers and other tools (see <a class="xref" href="faq.html#bbv2.recipies.site-config" title="Targets in site-config.jam">the section called “Targets in site-config.jam”</a> for more advanced usage). A tool is configured using the following syntax: </p> @@ -486,7 +486,7 @@ actions create-file-from-another using <em class="replaceable"><code>tool-name</code></em> : ... ; </pre> <p> - The <code class="computeroutput">using</code> rule is given a name of tool, and + The <code class="computeroutput">using</code> rule is given the name of tool, and will make that tool available to Boost.Build. For example, </p> <pre class="programlisting"> @@ -500,7 +500,7 @@ using gcc ; C++ compilers are below. </p> <p> - For all the C++ compiler toolsets Boost.Build supports + For all the C++ compiler toolsets that Boost.Build supports out-of-the-box, the list of parameters to <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>. </p> @@ -528,8 +528,8 @@ using msvc : : "Z:/Programs/Microsoft Visual Studio/vc98/bin/cl" ; <p> Some Boost.Build toolsets will use that path to take additional actions required before invoking the compiler, such as calling vendor-supplied - scripts to set up its required environment variables. When compiler - executables for C and C++ are different, path to the C++ compiler + scripts to set up its required environment variables. When the compiler + executables for C and C++ are different, the path to the C++ compiler executable must be specified. The command can be any command allowed by the operating system. For example: </p> @@ -594,16 +594,16 @@ using gcc : 3.2 : g++-3.2 ; <dt><span class="section"><a href="overview.html#bbv2.overview.invocation.properties">Properties</a></span></dt> <dt><span class="section"><a href="overview.html#bbv2.overview.invocation.targets">Targets</a></span></dt> </dl></div> -<p>To invoke Boost.Build, type <span class="command"><strong>bjam</strong></span> on the command line. Three kinds +<p>To invoke Boost.Build, type <span class="command"><strong>b2</strong></span> on the command line. Three kinds of command-line tokens are accepted, in any order:</p> <div class="variablelist"><dl> <dt><span class="term">options</span></dt> -<dd><p>Options start with either dash, or two dashes. The standard options +<dd><p>Options start with either one or two dashes. The standard options are listed below, and each project may add additional options</p></dd> <dt><span class="term">properties</span></dt> <dd><p>Properties specify details of what you want to build (e.g. debug - or release variant). Syntactically, all command line tokens with equal sign in them - are considered to specify properties. In the simplest form, property looks like + or release variant). Syntactically, all command line tokens with an equal sign in them + are considered to specify properties. In the simplest form, a property looks like <span class="command"><strong><em class="replaceable"><code>feature</code></em>=<em class="replaceable"><code>value</code></em></strong></span> </p></dd> <dt><span class="term">target</span></dt> @@ -614,17 +614,17 @@ using gcc : 3.2 : g++-3.2 ; <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="bbv2.overview.invocation.examples"></a>Examples</h4></div></div></div> -<p>To build all targets defined in Jamfile in the current directory with default properties, run: +<p>To build all targets defined in the Jamfile in the current directory with the default properties, run: </p> <pre class="screen"> -bjam +b2 </pre> <p> </p> <p>To build specific targets, specify them on the command line: </p> <pre class="screen"> -bjam lib1 subproject//lib2 +b2 lib1 subproject//lib2 </pre> <p> </p> @@ -632,7 +632,7 @@ bjam lib1 subproject//lib2 <em class="replaceable"><code>property</code></em>=<em class="replaceable"><code>value</code></em></code> to the command line: </p> <pre class="screen"> -bjam toolset=gcc variant=debug optimization=space +b2 toolset=gcc variant=debug optimization=space </pre> <p> </p> @@ -661,8 +661,8 @@ bjam toolset=gcc variant=debug optimization=space </p></dd> <dt><span class="term"><code class="option">--build-dir</code></span></dt> <dd> -<p>Changes build directories for all project roots being built. When - this option is specified, all Jamroot files should declare project name. +<p>Changes the build directories for all project roots being built. When + this option is specified, all Jamroot files must declare a project name. The build directory for the project root will be computed by concatanating the value of the <code class="option">--build-dir</code> option, the project name specified in Jamroot, and the build dir specified in Jamroot @@ -673,7 +673,7 @@ bjam toolset=gcc variant=debug optimization=space </p> </dd> <dt><span class="term"><code class="option">--version</code></span></dt> -<dd><p>Prints information on Boost.Build and Boost.Jam +<dd><p>Prints information on the Boost.Build and Boost.Jam versions. </p></dd> <dt><span class="term"><code class="option">-a</code></span></dt> @@ -681,23 +681,23 @@ bjam toolset=gcc variant=debug optimization=space <dt><span class="term"><code class="option">-n</code></span></dt> <dd><p>Do no execute the commands, only print them.</p></dd> <dt><span class="term"><code class="option">-q</code></span></dt> -<dd><p>Stop at first error, as opposed to continuing to build targets +<dd><p>Stop at the first error, as opposed to continuing to build targets that don't depend on the failed ones.</p></dd> <dt><span class="term"><code class="option">-j <em class="replaceable"><code>N</code></em></code></span></dt> <dd><p>Run up to <em class="replaceable"><code>N</code></em> commands in parallel.</p></dd> <dt><span class="term"><code class="option">--debug-configuration</code></span></dt> -<dd><p>Produces debug information about loading of Boost.Build +<dd><p>Produces debug information about the loading of Boost.Build and toolset files.</p></dd> <dt><span class="term"><code class="option">--debug-building</code></span></dt> <dd><p>Prints what targets are being built and with what properties. </p></dd> <dt><span class="term"><code class="option">--debug-generators</code></span></dt> -<dd><p>Produces debug output from generator search process. +<dd><p>Produces debug output from the generator search process. Useful for debugging custom generators. </p></dd> <dt><span class="term"><code class="option">--ignore-config</code></span></dt> -<dd><p>Do not load <code class="literal">site-config.jam</code> and - <code class="literal">user-config.jam</code> configuration files. +<dd><p>Do not load <code class="literal">site-config.jam</code> or + <code class="literal">user-config.jam</code>. </p></dd> <dt><span class="term"><code class="option">-d0</code></span></dt> <dd><p>Supress all informational messages.</p></dd> @@ -745,7 +745,7 @@ bjam toolset=gcc variant=debug optimization=space The complete list of features can be found in <a class="xref" href="reference.html#bbv2.overview.builtins.features" title="Builtin features">the section called “Builtin features”</a>. The most common features are summarized below.</p> <div class="table"> -<a name="id3896181"></a><p class="title"><b>Table 39.2. </b></p> +<a name="id3996105"></a><p class="title"><b>Table 39.2. </b></p> <div class="table-contents"><table class="table"> <colgroup> <col> @@ -821,37 +821,34 @@ bjam toolset=gcc variant=debug optimization=space </tbody> </table></div> </div> -<br class="table-break"> - - If you have more than one version of a given C++ toolset (e.g. configured in +<br class="table-break"><p>If you have more than one version of a given C++ toolset (e.g. configured in <code class="filename">user-config.jam</code>, or autodetected, as happens with msvc), you can request the specific version by passing <code class="computeroutput"><em class="replaceable"><code>toolset</code></em>-<em class="replaceable"><code>version</code></em></code> as the value of the <code class="computeroutput">toolset</code> feature, for example <code class="computeroutput">toolset=msvc-8.0</code>. - - - <p> + </p> +<p> If a feature has a fixed set of values it can be specified more than once on the command line. In which case, everything will be built several times -- once for each specified value of a feature. For example, if you use </p> <pre class="screen"> -bjam link=static link=shared threading=single threading=multi +b2 link=static link=shared threading=single threading=multi </pre> <p> Then a total of 4 builds will be performed. For convenience, instead of specifying all requested values of a feature in separate command line elements, - you can separate the values with commands, for example: + you can separate the values with commas, for example: </p> <pre class="screen"> -bjam link=static,shared threading=single,multi +b2 link=static,shared threading=single,multi </pre> <p> - The comma has special meaning only if the feature has a fixed set of values, so + The comma has this special meaning only if the feature has a fixed set of values, so </p> <pre class="screen"> -bjam include=static,shared +b2 include=static,shared </pre> <p>is not treated specially.</p> </div> @@ -867,11 +864,11 @@ bjam include=static,shared <div class="titlepage"><div><div><h3 class="title"> <a name="bbv2.overview.targets"></a>Declaring Targets</h3></div></div></div> <div class="toc"><dl> -<dt><span class="section"><a href="overview.html#id3896594">Name</a></span></dt> -<dt><span class="section"><a href="overview.html#id3896750">Sources</a></span></dt> +<dt><span class="section"><a href="overview.html#id3996520">Name</a></span></dt> +<dt><span class="section"><a href="overview.html#id3996676">Sources</a></span></dt> <dt><span class="section"><a href="overview.html#bbv2.overview.targets.requirements">Requirements</a></span></dt> -<dt><span class="section"><a href="overview.html#id3897336">Default Build</a></span></dt> -<dt><span class="section"><a href="overview.html#id3897364">Additional Information</a></span></dt> +<dt><span class="section"><a href="overview.html#id3996995">Default Build</a></span></dt> +<dt><span class="section"><a href="overview.html#id3997023">Additional Information</a></span></dt> </dl></div> <p><a name="bbv2.overview.targets.main"></a> A <em class="firstterm">Main target</em> is a user-defined named @@ -880,9 +877,9 @@ bjam include=static,shared target rules described in <a class="xref" href="reference.html#bbv2.reference.rules" title="Builtin rules">the section called “Builtin rules”</a>. The user can also declare custom main target rules as shown in <a class="xref" href="extender.html#bbv2.extending.rules" title="Main target rules">the section called “Main target rules”</a>. </p> -<a class="indexterm" name="id3896541"></a><p>Most main target rules in Boost.Build have the same common +<a class="indexterm" name="id3996468"></a><p>Most main target rules in Boost.Build have the same common signature:</p> -<a class="indexterm" name="id3896555"></a><a name="bbv2.main-target-rule-syntax"></a><pre class="programlisting"> +<a class="indexterm" name="id3996481"></a><a name="bbv2.main-target-rule-syntax"></a><pre class="programlisting"> rule <em class="replaceable"><code>rule-name</code></em> ( main-target-name : sources + : @@ -923,14 +920,14 @@ rule <em class="replaceable"><code>rule-name</code></em> ( stated in their documentation. </p> <p>The actual requirements for a target are obtained by refining - requirements of the project where a target is declared with the + the requirements of the project where the target is declared with the explicitly specified requirements. The same is true for usage-requirements. More details can be found in <a class="xref" href="reference.html#bbv2.reference.variants.proprefine" title="Property refinement">the section called “Property refinement”</a> </p> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> -<a name="id3896594"></a>Name</h4></div></div></div> +<a name="id3996520"></a>Name</h4></div></div></div> <p>The name of main target has two purposes. First, it's used to refer to this target from other targets and from command line. Second, it's used to compute the names of the generated files. Typically, filenames are obtained from main target name by appending system-dependent suffixes and @@ -950,13 +947,14 @@ obj test.debug : test.cpp : <variant>debug ; </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> -<a name="id3896750"></a>Sources</h4></div></div></div> +<a name="id3996676"></a>Sources</h4></div></div></div> <p>The list of sources specifies what should be processed to get the resulting targets. Most of the time, it's just a list of files. Sometimes, you'll want to automatically construct the list of source files rather than having to spell it out manually, in which case you can use the - <code class="computeroutput">glob</code> rule. Here are two examples:</p> + <a class="link" href="reference.html#bbv2.reference.rules.glob">glob</a> rule. + Here are two examples:</p> <pre class="programlisting"> exe a : a.cpp ; # a.cpp is the only source file exe b : [ glob *.cpp ] ; # all .cpp files in this directory are sources @@ -996,14 +994,14 @@ exe c : c.cpp /boost/program_options//program_options ; <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="bbv2.overview.targets.requirements"></a>Requirements</h4></div></div></div> -<a class="indexterm" name="id3896849"></a><p>Requirements are the properties that should always be present when +<a class="indexterm" name="id3996778"></a><p>Requirements are the properties that should always be present when building a target. Typically, they are includes and defines: </p> <pre class="programlisting"> exe hello : hello.cpp : <include>/opt/boost <define>MY_DEBUG ; </pre> <p> - There is a number of other features, listed in + There are a number of other features, listed in <a class="xref" href="reference.html#bbv2.overview.builtins.features" title="Builtin features">the section called “Builtin features”</a>. For example if a library can only be built statically, or a file can't be compiled with optimization due to a compiler bug, one can use @@ -1070,15 +1068,15 @@ rule my-rule ( properties * ) </p> <p>Requirements explicitly specified for a target are usually combined with the requirements specified for the containing project. You - can cause a target to completely ignore specific project's requirement - using the syntax by adding a minus sign before a property, for example: + can cause a target to completely ignore a specific project requirement + using the syntax by adding a minus sign before the property, for example: </p> <pre class="programlisting"> exe main : main.cpp : <span class="bold"><strong>-<define>UNNECESSARY_DEFINE</strong></span> ; </pre> <p> - This syntax is the only way to ignore free properties from a parent, - such as defines. It can be also useful for ordinary properties. Consider + This syntax is the only way to ignore free properties, such as defines, + from a parent. It can be also useful for ordinary properties. Consider this example: </p> <pre class="programlisting"> @@ -1088,12 +1086,12 @@ exe test2 : test2.cpp : <threading>single ; exe test3 : test3.cpp : -<threading>multi ; </pre> <p> - Here, <code class="computeroutput">test1</code> inherits project requirements and will always + Here, <code class="computeroutput">test1</code> inherits the project requirements and will always be built in multi-threaded mode. The <code class="computeroutput">test2</code> target - <span class="emphasis"><em>overrides</em></span> project's requirements and will + <span class="emphasis"><em>overrides</em></span> the project's requirements and will always be built in single-threaded mode. In contrast, the <code class="computeroutput">test3</code> target <span class="emphasis"><em>removes</em></span> a property - from project requirements and will be built either in single-threaded or + from the project requirements and will be built either in single-threaded or multi-threaded mode depending on which variant is requested by the user.</p> <p>Note that the removal of requirements is completely textual: @@ -1101,7 +1099,7 @@ exe test3 : test3.cpp : -<threading>multi ; </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> -<a name="id3897336"></a>Default Build</h4></div></div></div> +<a name="id3996995"></a>Default Build</h4></div></div></div> <p>The <code class="varname">default-build</code> parameter is a set of properties to be used if the build request does not otherwise specify a value for features in the set. For example: @@ -1112,13 +1110,13 @@ exe hello : hello.cpp : : <threading>multi ; <p> would build a multi-threaded target unless the user explicitly requests a single-threaded version. The difference between - requirements and default-build is that requirements cannot be + the requirements and the default-build is that the requirements cannot be overridden in any way. </p> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> -<a name="id3897364"></a>Additional Information</h4></div></div></div> +<a name="id3997023"></a>Additional Information</h4></div></div></div> <p> The ways a target is built can be so different that describing them using conditional requirements would be @@ -1128,7 +1126,7 @@ exe hello : hello.cpp : : <threading>multi ; alternatives</em>: </p> <pre class="programlisting"> -lib demangler : dummy_demangler.cpp ; # alternative 1 +lib demangler : dummy_demangler.cpp ; # alternative 1 lib demangler : demangler_gcc.cpp : <toolset>gcc ; # alternative 2 lib demangler : demangler_msvc.cpp : <toolset>msvc ; # alternative 3 </pre> @@ -1149,12 +1147,12 @@ exe hello : hello.cpp optimization. When referring to an inline main target, its declared name must be prefixed by its parent target's name and two dots. In the example above, to build only helpers, one should run - <code class="computeroutput">bjam hello..helpers</code>. + <code class="computeroutput">b2 hello..helpers</code>. </p> <p>When no target is requested on the command line, all targets in the current project will be built. If a target should be built only by explicit request, this can be expressed by the - <code class="computeroutput">explicit</code> rule: + <a class="link" href="reference.html#bbv2.reference.rules.explicit">explicit</a> rule: </p> <pre class="programlisting"> explicit install_programs ;</pre> @@ -1211,7 +1209,7 @@ project tennis </p> <div class="table"> -<a name="id3897577"></a><p class="title"><b>Table 39.3. </b></p> +<a name="id3997240"></a><p class="title"><b>Table 39.3. </b></p> <div class="table-contents"><table class="table" summary=""> <colgroup> <col> @@ -1312,8 +1310,8 @@ project tennis <a name="bbv2.overview.build_process"></a>The Build Process</h3></div></div></div> <div class="toc"><dl> <dt><span class="section"><a href="overview.html#bbv2.overview.build_request">Build Request</a></span></dt> -<dt><span class="section"><a href="overview.html#id3897894">Building a main target</a></span></dt> -<dt><span class="section"><a href="overview.html#id3898010">Building a Project</a></span></dt> +<dt><span class="section"><a href="overview.html#id3997557">Building a main target</a></span></dt> +<dt><span class="section"><a href="overview.html#id3997672">Building a Project</a></span></dt> </dl></div> <p>When you've described your targets, you want Boost.Build to run the right tools and create the needed targets. @@ -1351,7 +1349,7 @@ project tennis properties. For example: </p> <pre class="programlisting"> -bjam app1 lib1//lib1 toolset=gcc variant=debug optimization=full +b2 app1 lib1//lib1 toolset=gcc variant=debug optimization=full </pre> <p> would build two targets, "app1" and "lib1//lib1" with the specified @@ -1361,7 +1359,7 @@ bjam app1 lib1//lib1 toolset=gcc variant=debug optimization=full of the property can be omitted. For example, the above can be written as: </p> <pre class="programlisting"> -bjam app1 lib1//lib1 gcc debug optimization=full +b2 app1 lib1//lib1 gcc debug optimization=full </pre> <p> The complete syntax, which has some additional shortcuts, is @@ -1370,7 +1368,7 @@ bjam app1 lib1//lib1 gcc debug optimization=full </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> -<a name="id3897894"></a>Building a main target</h4></div></div></div> +<a name="id3997557"></a>Building a main target</h4></div></div></div> <p>When you request, directly or indirectly, a build of a main target with specific requirements, the following steps are done. Some brief explanation is provided, and more details are given in <a class="xref" href="reference.html#bbv2.reference.buildprocess" title="Build process">the section called “Build process”</a>. @@ -1430,9 +1428,9 @@ bjam app1 lib1//lib1 gcc debug optimization=full </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> -<a name="id3898010"></a>Building a Project</h4></div></div></div> +<a name="id3997672"></a>Building a Project</h4></div></div></div> <p>Often, a user builds a complete project, not just one main - target. In fact, invoking <span class="command"><strong>bjam</strong></span> without + target. In fact, invoking <span class="command"><strong>b2</strong></span> without arguments builds the project defined in the current diff --git a/doc/html/bbv2/reference.html b/doc/html/bbv2/reference.html index 8748c815c2..3bcb419c9f 100755..100644 --- a/doc/html/bbv2/reference.html +++ b/doc/html/bbv2/reference.html @@ -30,6 +30,8 @@ <dt><span class="section"><a href="reference.html#bbv2.reference.rules">Builtin rules</a></span></dt> <dt><span class="section"><a href="reference.html#bbv2.overview.builtins.features">Builtin features</a></span></dt> <dt><span class="section"><a href="reference.html#bbv2.reference.tools">Builtin tools</a></span></dt> +<dt><span class="section"><a href="reference.html#bbv2.reference.modules">Builtin modules</a></span></dt> +<dt><span class="section"><a href="reference.html#bbv2.reference.class">Builtin classes</a></span></dt> <dt><span class="section"><a href="reference.html#bbv2.reference.buildprocess">Build process</a></span></dt> <dt><span class="section"><a href="reference.html#bbv2.reference.definitions">Definitions</a></span></dt> </dl></div> @@ -68,7 +70,7 @@ boost-build build-system ; </pre> <p> - In this case, running bjam anywhere in the project tree will + In this case, running <span class="command"><strong>b2</strong></span> 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 <code class="filename">site-config.jam</code> and <code class="filename">user-config.jam</code>.</p> @@ -107,7 +109,9 @@ boost-build build-system ; <dt><span class="term"><code class="literal">preprocessed</code></span></dt> <dd><p>Creates an preprocessed source file. The arguments follow the <a class="link" href="overview.html#bbv2.main-target-rule-syntax">common syntax</a>.</p></dd> -<dt><span class="term"><code class="literal">glob</code></span></dt> +<dt> +<a name="bbv2.reference.rules.glob"></a><span class="term"><code class="literal">glob</code></span> +</dt> <dd> <p>The <code class="computeroutput">glob</code> rule takes a list shell pattern and returns the list of files in the project's source directory that @@ -154,7 +158,9 @@ ECHO [ glob-tree *.cpp : .svn ] ; <dd><p>Assigns a symbolic project ID to a project at a given path. This rule must be better documented! </p></dd> -<dt><span class="term"><code class="literal">explicit</code></span></dt> +<dt> +<a name="bbv2.reference.rules.explicit"></a><span class="term"><code class="literal">explicit</code></span> +</dt> <dd><p>The <code class="literal">explicit</code> rule takes a single parameter—a list of target names. The named targets will be marked explicit, and will be built only if they are explicitly @@ -195,7 +201,7 @@ constant VERSION : 1.34.0 ; <dd> <p>Same as <code class="literal">constant</code> except that the value is treated as path relative to Jamfile location. For example, - if <span class="command"><strong>bjam</strong></span> is invoked in the current directory, + if <span class="command"><strong>b2</strong></span> is invoked in the current directory, and Jamfile in <code class="filename">helper</code> subdirectory has: </p> <pre class="programlisting"> @@ -203,7 +209,7 @@ path-constant DATA : data/a.txt ; </pre> <p> then the variable <code class="varname">DATA</code> will be set to - <code class="literal">helper/data/a.txt</code>, and if <span class="command"><strong>bjam</strong></span> + <code class="literal">helper/data/a.txt</code>, and if <span class="command"><strong>b2</strong></span> is invoked from the <code class="filename">helper</code> directory, then the variable <code class="varname">DATA</code> will be set to <code class="literal">data/a.txt</code>. @@ -228,7 +234,7 @@ path-constant DATA : data/a.txt ; <p>This section documents the features that are built-in into Boost.Build. For features with a fixed set of values, that set is provided, with the default value listed first.</p> -<a class="indexterm" name="id3900672"></a><div class="variablelist"><dl> +<a class="indexterm" name="id4000384"></a><div class="variablelist"><dl> <dt><span class="term"><code class="literal">variant</code></span></dt> <dd> <p> @@ -322,7 +328,7 @@ path-constant DATA : data/a.txt ; feature, except that it takes effect only for linking. When you want to link all targets in a Jamfile to certain library, the <code class="computeroutput"><library></code> feature is preferred over - <code class="computeroutput"><source>X</code> -- the latter will add the library to + <code class="computeroutput"><source>X</code>—the latter will add the library to all targets, even those that have nothing to do with libraries. </dd> <dt><span class="term"><a name="bbv2.builtin.features.dependency"></a> @@ -334,6 +340,14 @@ path-constant DATA : data/a.txt ; </dd> +<dt><span class="term"><a name="bbv2.builtin.features.implicit-dependency"></a> + <code class="literal">implicit-dependency</code></span></dt> +<dd> + Indicates that the target named by the value of this feature + may produce files that are included by the sources of the + target being declared. See <a class="xref" href="tasks.html#bbv2.reference.generated_headers" title="Generated headers">the section called “Generated headers”</a> + for more information. + </dd> <dt><span class="term"><a name="bbv2.builtin.features.use"></a> <code class="literal">use</code></span></dt> <dd> @@ -534,7 +548,7 @@ path-constant DATA : data/a.txt ; </dd> <dt><span class="term"><code class="literal">embed-manifest</code></span></dt> <dd> -<a class="indexterm" name="id3901864"></a><a class="indexterm" name="id3901873"></a><p> +<a class="indexterm" name="id4001621"></a><a class="indexterm" name="id4001630"></a><p> <span class="bold"><strong>Allowed values:</strong></span> on, off. </p> <p>This feature is specific to the msvc toolset (see @@ -552,8 +566,8 @@ path-constant DATA : data/a.txt ; <a name="bbv2.reference.tools"></a>Builtin tools</h3></div></div></div> <div class="toc"><dl> <dt><span class="section"><a href="reference.html#bbv2.reference.tools.compilers">C++ Compilers</a></span></dt> -<dt><span class="section"><a href="reference.html#id3904546">Third-party libraries</a></span></dt> -<dt><span class="section"><a href="reference.html#id3904659">Documentation tools</a></span></dt> +<dt><span class="section"><a href="reference.html#id4004575">Third-party libraries</a></span></dt> +<dt><span class="section"><a href="reference.html#id4004688">Documentation tools</a></span></dt> </dl></div> <p>Boost.Build comes with support for a large number of C++ compilers, and other tools. This section documents how to use those tools.</p> @@ -642,7 +656,7 @@ using gcc : [<span class="optional"><em class="replaceable"><code>version</code> be either <code class="computeroutput">windres</code> for msvc resource compiler, or <code class="computeroutput">rc</code> for borland's resource compiler.</p></dd> </dl></div> -<a class="indexterm" name="id3902285"></a> +<a class="indexterm" name="id4002312"></a> In order to compile 64-bit applications, you have to specify <code class="computeroutput">address-model=64</code>, and the <code class="computeroutput">instruction-set</code> @@ -659,7 +673,7 @@ using gcc : [<span class="optional"><em class="replaceable"><code>version</code> to that of the gcc module. </p> <p> - <a class="indexterm" name="id3902356"></a> + <a class="indexterm" name="id4002383"></a> The darwin toolset can generate so called "fat" binaries—binaries that can run support more than one architecture, or address mode. To build a binary that can run both @@ -769,7 +783,7 @@ using msvc : [<span class="optional"><em class="replaceable"><code>version</code <div class="section"> <div class="titlepage"><div><div><h6 class="title"> <a name="v2.reference.tools.compiler.msvc.64"></a>64-bit support</h6></div></div></div> -<a class="indexterm" name="id3902833"></a><p>Starting with version 8.0, Microsoft Visual Studio can +<a class="indexterm" name="id4002860"></a><p>Starting with version 8.0, Microsoft Visual Studio can generate binaries for 64-bit processor, both 64-bit flavours of x86 (codenamed AMD64/EM64T), and Itanium (codenamed IA64). In addition, compilers that are itself run in 64-bit mode, for better @@ -1109,7 +1123,7 @@ using sun : [<span class="optional"><em class="replaceable"><code>version</code> <dd><p>Specifies additional command line options that will be passed to the linker.</p></dd> </dl></div> -<a class="indexterm" name="id3904464"></a> +<a class="indexterm" name="id4004493"></a> Starting with Sun Studio 12, you can create 64-bit applications by using the <code class="computeroutput">address-model=64</code> property. @@ -1134,14 +1148,14 @@ using vacpp ;</pre> </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> -<a name="id3904546"></a>Third-party libraries</h4></div></div></div> +<a name="id4004575"></a>Third-party libraries</h4></div></div></div> <div class="toc"><dl><dt><span class="section"><a href="reference.html#bbv2.reference.tools.libraries.stlport">STLport library</a></span></dt></dl></div> <p>Boost.Build provides special support for some third-party C++ libraries, documented below.</p> <div class="section"> <div class="titlepage"><div><div><h5 class="title"> <a name="bbv2.reference.tools.libraries.stlport"></a>STLport library</h5></div></div></div> -<a class="indexterm" name="id3904568"></a><p>The <a href="http://stlport.org" target="_top">STLport</a> library +<a class="indexterm" name="id4004597"></a><p>The <a href="http://stlport.org" target="_top">STLport</a> library is an alternative implementation of C++ runtime library. Boost.Build supports using that library on Windows platfrom. Linux is hampered by different naming of libraries in each STLport @@ -1170,7 +1184,7 @@ using stlport : [<span class="optional"><em class="replaceable"><code>version</c </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> -<a name="id3904659"></a>Documentation tools</h4></div></div></div> +<a name="id4004688"></a>Documentation tools</h4></div></div></div> <div class="toc"><dl> <dt><span class="section"><a href="reference.html#bbv2.reference.tools.doc.xsltproc">xsltproc</a></span></dt> <dt><span class="section"><a href="reference.html#bbv2.reference.tools.doc.boostbook">boostbook</a></span></dt> @@ -1184,7 +1198,7 @@ using stlport : [<span class="optional"><em class="replaceable"><code>version</c <div class="section"> <div class="titlepage"><div><div><h5 class="title"> <a name="bbv2.reference.tools.doc.xsltproc"></a>xsltproc</h5></div></div></div> -<a class="indexterm" name="id3904681"></a><p>To use xsltproc, you first need to configure it using the following syntax:</p> +<a class="indexterm" name="id4004709"></a><p>To use xsltproc, you first need to configure it using the following syntax:</p> <pre class="programlisting"> using xsltproc : [<span class="optional"><em class="replaceable"><code>xsltproc</code></em></span>] ; </pre> @@ -1232,7 +1246,7 @@ rule xslt-dir ( target : source stylesheet : properties * : dirname ) <div class="section"> <div class="titlepage"><div><div><h5 class="title"> <a name="bbv2.reference.tools.doc.boostbook"></a>boostbook</h5></div></div></div> -<a class="indexterm" name="id3904905"></a><p>To use boostbook, you first need to configure it using the following syntax:</p> +<a class="indexterm" name="id4004934"></a><p>To use boostbook, you first need to configure it using the following syntax:</p> <pre class="programlisting"> using boostbook : [<span class="optional"><em class="replaceable"><code>docbook-xsl-dir</code></em></span>] : [<span class="optional"><em class="replaceable"><code>docbook-dtd-dir</code></em></span>] : [<span class="optional"><em class="replaceable"><code>boostbook-dir</code></em></span>] ; </pre> @@ -1286,7 +1300,7 @@ rule boostbook ( target-name : sources * : requirements * : default-build * ) <div class="section"> <div class="titlepage"><div><div><h5 class="title"> <a name="bbv2.reference.tools.doc.doxygen"></a>doxygen</h5></div></div></div> -<a class="indexterm" name="id3905208"></a><p>To use doxygen, you first need to configure it using the following syntax:</p> +<a class="indexterm" name="id4005236"></a><p>To use doxygen, you first need to configure it using the following syntax:</p> <pre class="programlisting"> using doxygen : [<span class="optional"><em class="replaceable"><code>name</code></em></span>] ; </pre> @@ -1345,7 +1359,7 @@ rule doxygen ( target : sources * : requirements * : default-build * : usage-req <div class="section"> <div class="titlepage"><div><div><h5 class="title"> <a name="bbv2.reference.tools.doc.quickbook"></a>quickbook</h5></div></div></div> -<a class="indexterm" name="id3905432"></a><p>The quickbook module provides a generator to convert from +<a class="indexterm" name="id4005460"></a><p>The quickbook module provides a generator to convert from Quickbook to BoostBook XML.</p> <p>To use quickbook, you first need to configure it using the following syntax:</p> <pre class="programlisting"> @@ -1361,7 +1375,7 @@ using quickbook : [<span class="optional"><em class="replaceable"><code>command< <div class="section"> <div class="titlepage"><div><div><h5 class="title"> <a name="bbv2.reference.tools.doc.fop"></a>fop</h5></div></div></div> -<a class="indexterm" name="id3905480"></a><p>The fop module provides generators to convert from +<a class="indexterm" name="id4005507"></a><p>The fop module provides generators to convert from XSL formatting objects to Postscript and PDF.</p> <p>To use fop, you first need to configure it using the following syntax:</p> <pre class="programlisting"> @@ -1382,10 +1396,886 @@ using fop : [<span class="optional"><em class="replaceable"><code>fop-command</c </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> +<a name="bbv2.reference.modules"></a>Builtin modules</h3></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="reference.html#bbv2.reference.modules.modules">modules</a></span></dt> +<dt><span class="section"><a href="reference.html#bbv2.reference.modules.path">path</a></span></dt> +<dt><span class="section"><a href="reference.html#bbv2.reference.modules.type">type</a></span></dt> +</dl></div> +<p> + This section describes the modules that are provided + by Boost.Build. The import rule allows rules from + one module to be used in another module or Jamfile. + </p> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="bbv2.reference.modules.modules"></a>modules</h4></div></div></div> +<a class="indexterm" name="id4005594"></a><p> + The <code class="computeroutput">modules</code> module defines basic functionality + for handling modules. + </p> +<p> + A module defines a number of rules that can be used in other + modules. Modules can contain code at the top level to initialize + the module. This code is executed the first time the + module is loaded. + </p> +<div class="note"><table border="0" summary="Note"> +<tr> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> +<th align="left">Note</th> +</tr> +<tr><td align="left" valign="top"><p> + A Jamfile is a special kind of module which is managed by + the build system. Although they cannot be loaded directly + by users, the other features of modules are still useful + for Jamfiles. + </p></td></tr> +</table></div> +<p> + </p> +<p> + Each module has its own namespaces for variables and rules. If two + modules A and B both use a variable named X, each one gets its own + copy of X. They won't interfere with each other in any way. + Similarly, importing rules into one module has no effect on any other + module. + </p> +<p> + Every module has two special variables. + <code class="computeroutput">$(__file__)</code> contains the name of the file that + the module was loaded from and <code class="computeroutput">$(__name__)</code> + contains the name of the module. + </p> +<div class="note"><table border="0" summary="Note"> +<tr> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> +<th align="left">Note</th> +</tr> +<tr><td align="left" valign="top"><p><code class="computeroutput">$(__file__)</code> does not contain + the full path to the file. If you need this, use + <code class="computeroutput">modules.binding</code>.</p></td></tr> +</table></div> +<p> + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> +<a name="bbv2.reference.modules.modules.binding"></a><a class="indexterm" name="id4005686"></a><code class="computeroutput"><span class="keyword">rule</span> binding <span class="special">(</span> module-name <span class="special">)</span></code><p>Returns the filesystem binding of the given module.</p> +<p>For example, a module can get its own location with: + </p> +<pre class="programlisting">me <span class="special">=</span> <span class="special">[</span> modules.binding $(__name__) <span class="special">]</span> <span class="special">;</span></pre> +<p> + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.modules.poke"></a><a class="indexterm" name="id4005761"></a><code class="computeroutput"><span class="keyword">rule</span> poke <span class="special">(</span> module-name ? <span class="special">:</span> variables + <span class="special">:</span> value * <span class="special">)</span></code><p>Sets the module-local value of a variable.</p> +<p>For example, to set a variable in the global module: + </p> +<pre class="programlisting">modules.poke <span class="special">:</span> ZLIB_INCLUDE <span class="special">:</span> /usr/local/include <span class="special">;</span></pre> +<p> + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.modules.peek"></a><a class="indexterm" name="id4005842"></a><code class="computeroutput"><span class="keyword">rule</span> peek <span class="special">(</span> module-name ? <span class="special">:</span> variables + <span class="special">)</span></code><p>Returns the module-local value of a variable.</p> +<p> + For example, to read a variable from the global module: + </p> +<pre class="programlisting"><span class="keyword">local</span> ZLIB_INCLUDE <span class="special">=</span> <span class="special">[</span> modules.peek <span class="special">:</span> ZLIB_INCLUDE <span class="special">]</span> <span class="special">;</span></pre> +<p> + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.modules.call-in"></a><a class="indexterm" name="id4005932"></a><code class="computeroutput"><span class="keyword">rule</span> call-in <span class="special">(</span> module-name ? <span class="special">:</span> rule-name args * <span class="special">:</span> * <span class="special">)</span> </code><p>Call the given rule locally in the given module. Use + this for rules accepting rule names as arguments, so that + the passed rule may be invoked in the context of the rule's + caller (for example, if the rule accesses module globals or + is a local rule). + </p> +<div class="note"><table border="0" summary="Note"> +<tr> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> +<th align="left">Note</th> +</tr> +<tr><td align="left" valign="top"><p>rules called this way may accept at most + 8 parameters.</p></td></tr> +</table></div> +<p>Example: +</p> +<pre class="programlisting"> +<span class="keyword">rule</span> filter <span class="special">(</span> f <span class="special">:</span> values * <span class="special">)</span> +<span class="special">{</span> + <span class="keyword">local</span> m <span class="special">=</span> <span class="special">[</span> CALLER_MODULE <span class="special">]</span> <span class="special">;</span> + <span class="keyword">local</span> result <span class="special">;</span> + <span class="keyword">for</span> v <span class="keyword">in</span> $(values) + <span class="special">{</span> + <span class="keyword">if</span> <span class="special">[</span> modules.call-in $(m) <span class="special">:</span> $(f) $(v) <span class="special">]</span> + <span class="special">{</span> + result <span class="special">+=</span> $(v) <span class="special">;</span> + <span class="special">}</span> + <span class="special">}</span> + <span class="keyword">return</span> result <span class="special">;</span> +<span class="special">}</span> +</pre> +<p> + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.modules.load"></a><a class="indexterm" name="id4006156"></a><code class="computeroutput"><span class="keyword">rule</span> load <span class="special">(</span> module-name <span class="special">:</span> filename ? <span class="special">:</span> search * <span class="special">)</span></code><p>Load the indicated module if it is not already loaded.</p> +<div class="variablelist"><dl> +<dt><span class="term"><code class="literal">module-name</code></span></dt> +<dd><p>Name of module to load.</p></dd> +</dl></div> +<div class="variablelist"><dl> +<dt><span class="term"><code class="literal">filename</code></span></dt> +<dd><p>(partial) path to file; Defaults to <code class="computeroutput">$(module-name).jam</code></p></dd> +</dl></div> +<div class="variablelist"><dl> +<dt><span class="term"><code class="literal">search</code></span></dt> +<dd><p>Directories in which to search for filename. + Defaults to <code class="computeroutput">$(BOOST_BUILD_PATH)</code>.</p></dd> +</dl></div> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.modules.import"></a><a class="indexterm" name="id4006277"></a><code class="computeroutput"><span class="keyword">rule</span> import <span class="special">(</span> module-names + <span class="special">:</span> rules-opt * <span class="special">:</span> rename-opt * <span class="special">)</span></code><p>Load the indicated module and import rule names into the + current module. Any members of <code class="computeroutput">rules-opt</code> will be + available without qualification in the caller's module. Any + members of <code class="computeroutput">rename-opt</code> will be taken as the names + of the rules in the caller's module, in place of the names they + have in the imported module. If <code class="computeroutput">rules-opt = '*'</code>, + all rules from the indicated module are imported into the + caller's module. If <code class="computeroutput">rename-opt</code> is supplied, it must have the + same number of elements as <code class="computeroutput">rules-opt</code>.</p> +<div class="note"><table border="0" summary="Note"> +<tr> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> +<th align="left">Note</th> +</tr> +<tr><td align="left" valign="top"><p>The <code class="literal">import</code> rule is available + without qualification in all modules.</p></td></tr> +</table></div> +<p>Examples: +</p> +<pre class="programlisting"> +import path <span class="special">;</span> +import path <span class="special">:</span> * <span class="special">;</span> +import path <span class="special">:</span> join <span class="special">;</span> +import path <span class="special">:</span> native make <span class="special">:</span> native-path make-path <span class="special">;</span> +</pre> +<p> + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.modules.clone-rules"></a><a class="indexterm" name="id4006435"></a><code class="computeroutput"><span class="keyword">rule</span> clone-rules <span class="special">(</span> source-module target-module <span class="special">)</span></code><p>Define exported copies in <code class="computeroutput">$(target-module)</code> + of all rules exported from <code class="computeroutput">$(source-module)</code>. Also + make them available in the global module with qualification, + so that it is just as though the rules were defined originally + in <code class="computeroutput">$(target-module)</code>.</p> +</li> +</ol></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="bbv2.reference.modules.path"></a>path</h4></div></div></div> +<a class="indexterm" name="id4006505"></a><p> + Performs various path manipulations. Paths are always in a 'normalized' + representation. In it, a path may be either: + + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p><code class="computeroutput">'.'</code>, or</p></li> +<li class="listitem"><p> + <code class="computeroutput">['/'] [ ( '..' '/' )* (token '/')* token ]</code> + </p></li> +</ul></div> +<p> + + In plain english, a path can be rooted, <code class="computeroutput">'..'</code> + elements are allowed only at the beginning, and it never + ends in slash, except for the path consisting of slash only. + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> +<a name="bbv2.reference.modules.path.make"></a><a class="indexterm" name="id4006567"></a><code class="computeroutput"><span class="keyword">rule</span> make <span class="special">(</span> native <span class="special">)</span></code><p>Converts the native path into normalized form.</p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.path.native"></a><a class="indexterm" name="id4006617"></a><code class="computeroutput"><span class="keyword">rule</span> native <span class="special">(</span> path <span class="special">)</span></code><p>Builds the native representation of the path.</p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.path.is-rooted"></a><a class="indexterm" name="id4006662"></a><code class="computeroutput"><span class="keyword">rule</span> is-rooted <span class="special">(</span> path <span class="special">)</span></code><p>Tests if a path is rooted.</p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.path.has-parent"></a><a class="indexterm" name="id4006709"></a><code class="computeroutput"><span class="keyword">rule</span> has-parent <span class="special">(</span> path <span class="special">)</span></code><p>Tests if a path has a parent.</p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.path.basename"></a><a class="indexterm" name="id4006754"></a><code class="computeroutput"><span class="keyword">rule</span> basename <span class="special">(</span> path <span class="special">)</span></code><p>Returns the path without any directory components.</p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.path.parent"></a><a class="indexterm" name="id4006800"></a><code class="computeroutput"><span class="keyword">rule</span> parent <span class="special">(</span> path <span class="special">)</span></code><p>Returns the parent directory of the path. If no parent exists, an error is issued.</p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.path.reverse"></a><a class="indexterm" name="id4006847"></a><code class="computeroutput"><span class="keyword">rule</span> reverse <span class="special">(</span> path <span class="special">)</span></code><p> + Returns <code class="computeroutput">path2</code> such that + <code class="computeroutput"><span class="special">[</span> join path path2 <span class="special">]</span> <span class="special">=</span> "."</code>. + The path may not contain <code class="computeroutput">".."</code> + element or be rooted. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.path.join"></a><a class="indexterm" name="id4006926"></a><code class="computeroutput"><span class="keyword">rule</span> join <span class="special">(</span> elements + <span class="special">)</span></code><p> + Concatenates the passed path elements. Generates an error if any + element other than the first one is rooted. Skips any empty or + undefined path elements. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.path.root"></a><a class="indexterm" name="id4006975"></a><code class="computeroutput"><span class="keyword">rule</span> root <span class="special">(</span> path root <span class="special">)</span></code><p> + If <code class="computeroutput">path</code> is relative, it is rooted at + <code class="computeroutput">root</code>. Otherwise, it is unchanged. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.path.pwd"></a><a class="indexterm" name="id4007032"></a><code class="computeroutput"><span class="keyword">rule</span> pwd <span class="special">(</span> <span class="special">)</span></code><p>Returns the current working directory.</p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.path.glob"></a><a class="indexterm" name="id4007078"></a><code class="computeroutput"><span class="keyword">rule</span> glob <span class="special">(</span> dirs * <span class="special">:</span> patterns + <span class="special">:</span> exclude-patterns * <span class="special">)</span></code><p> + Returns the list of files matching the given pattern in the specified + directory. Both directories and patterns are supplied as portable paths. Each + pattern should be a non-absolute path, and can't contain "." or ".." elements. + Each slash separated element of a pattern can contain the following special + characters: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><p>'?' matches any character</p></li> +<li class="listitem"><p>'*' matches an arbitrary number of characters</p></li> +</ul></div> +<p> + A file $(d)/e1/e2/e3 (where 'd' is in $(dirs)) matches the pattern p1/p2/p3 if and + only if e1 matches p1, e2 matches p2 and so on. + + For example: +</p> +<pre class="programlisting"> +<span class="special">[</span> glob . <span class="special">:</span> *.cpp <span class="special">]</span> +<span class="special">[</span> glob . <span class="special">:</span> */build/Jamfile <span class="special">]</span> +</pre> +<p> + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.path.glob-tree"></a><a class="indexterm" name="id4007200"></a><code class="computeroutput"><span class="keyword">rule</span> glob-tree <span class="special">(</span> roots * <span class="special">:</span> patterns + <span class="special">:</span> exclude-patterns * <span class="special">)</span></code><p> + Recursive version of <a class="link" href="reference.html#bbv2.reference.modules.path.glob">glob</a>. + Builds the glob of files while also searching in + the subdirectories of the given roots. An optional set of exclusion patterns + will filter out the matching entries from the result. The exclusions also + apply to the subdirectory scanning, such that directories that match the + exclusion patterns will not be searched. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.path.exists"></a><a class="indexterm" name="id4007271"></a><code class="computeroutput"><span class="keyword">rule</span> exists <span class="special">(</span> file <span class="special">)</span></code><p>Returns true if the specified file exists.</p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.path.all-parents"></a><a class="indexterm" name="id4007317"></a><code class="computeroutput"><span class="keyword">rule</span> all-parents <span class="special">(</span> path <span class="special">:</span> upper_limit ? <span class="special">:</span> cwd ? <span class="special">)</span></code><p> + Find out the absolute name of path and return the list of all the parents, + starting with the immediate one. Parents are returned as relative names. If + <code class="computeroutput">upper_limit</code> is specified, directories above it + will be pruned. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.path.glob-in-parents"></a><a class="indexterm" name="id4007384"></a><code class="computeroutput"><span class="keyword">rule</span> glob-in-parents <span class="special">(</span> dir <span class="special">:</span> patterns + <span class="special">:</span> upper-limit ? <span class="special">)</span></code><p> + Search for <code class="computeroutput">patterns</code> in parent directories + of <code class="computeroutput">dir</code>, up to and including + <code class="computeroutput">upper_limit</code>, if it is specified, or + till the filesystem root otherwise. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.path.relative"></a><a class="indexterm" name="id4007461"></a><code class="computeroutput"><span class="keyword">rule</span> relative <span class="special">(</span> child parent <span class="special">:</span> no-error ? <span class="special">)</span></code><p> + Assuming <code class="computeroutput">child</code> is a subdirectory of + <code class="computeroutput">parent</code>, return the relative path from + <code class="computeroutput">parent</code> to <code class="computeroutput">child</code>. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.path.relative-to"></a><a class="indexterm" name="id4007537"></a><code class="computeroutput"><span class="keyword">rule</span> relative-to <span class="special">(</span> path1 path2 <span class="special">)</span></code><p>Returns the minimal path to path2 that is relative path1.</p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.path.programs-path"></a><a class="indexterm" name="id4007583"></a><code class="computeroutput"><span class="keyword">rule</span> programs-path <span class="special">(</span> <span class="special">)</span></code><p> + Returns the list of paths which are used by the operating system for + looking up programs. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.path.mkdirs"></a><a class="indexterm" name="id4007630"></a><code class="computeroutput"><span class="keyword">rule</span> makedirs <span class="special">(</span> path <span class="special">)</span></code><p> + Creates a directory and all parent directories that do not + already exist. + </p> +</li> +</ol></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="bbv2.reference.modules.type"></a>type</h4></div></div></div> +<a class="indexterm" name="id4007681"></a><p> + Deals with target type declaration and defines target class which supports + typed targets. + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> +<a name="bbv2.reference.modules.type.register"></a><a class="indexterm" name="id4007712"></a><code class="computeroutput"><span class="keyword">rule</span> register <span class="special">(</span> type <span class="special">:</span> suffixes * <span class="special">:</span> base-type ? <span class="special">)</span></code><p> + Registers a target type, possible derived from a + <code class="computeroutput">base-type</code>. Providing a list + of suffixes here is a shortcut for separately calling the + <a class="link" href="reference.html#bbv2.reference.modules.type.register-suffixes">register-suffixes</a> + rule with the given suffixes and the + <a class="link" href="reference.html#bbv2.reference.modules.type.set-generated-target-suffix">set-generated-target-suffix</a> + rule with the first given suffix. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.type.register-suffixes"></a><a class="indexterm" name="id4007800"></a><code class="computeroutput"><span class="keyword">rule</span> register-suffixes <span class="special">(</span> suffixes + <span class="special">:</span> type <span class="special">)</span></code><p> + Specifies that files with suffix from <code class="computeroutput">suffixes</code> + be recognized as targets of type <code class="computeroutput">type</code>. + Issues an error if a different type is already specified for any + of the suffixes. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.type.registered"></a><a class="indexterm" name="id4007865"></a><code class="computeroutput"><span class="keyword">rule</span> registered <span class="special">(</span> type <span class="special">)</span></code><p>Returns true iff type has been registered.</p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.type.validate"></a><a class="indexterm" name="id4007912"></a><code class="computeroutput"><span class="keyword">rule</span> validate <span class="special">(</span> type <span class="special">)</span></code><p>Issues an error if <code class="computeroutput">type</code> is unknown.</p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.type.set-scanner"></a><a class="indexterm" name="id4007964"></a><code class="computeroutput"><span class="keyword">rule</span> set-scanner <span class="special">(</span> type <span class="special">:</span> scanner <span class="special">)</span></code><p>Sets a scanner class that will be used for this type.</p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.type.get-scanner"></a><a class="indexterm" name="id4008016"></a><code class="computeroutput"><span class="keyword">rule</span> get-scanner <span class="special">(</span> type <span class="special">:</span> property-set <span class="special">)</span></code><p> + Returns a scanner instance appropriate to <code class="computeroutput">type</code> + and <code class="computeroutput">property-set</code>. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.type.base"></a><a class="indexterm" name="id4008080"></a><code class="computeroutput"><span class="keyword">rule</span> base <span class="special">(</span> type <span class="special">)</span></code><p> + Returns a base type for the given type or nothing in case the given + type is not derived. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.type.all-bases"></a><a class="indexterm" name="id4008127"></a><code class="computeroutput"><span class="keyword">rule</span> all-bases <span class="special">(</span> type <span class="special">)</span></code><p> + Returns the given type and all of its base types in order of + their distance from type. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.type.all-derived"></a><a class="indexterm" name="id4008174"></a><code class="computeroutput"><span class="keyword">rule</span> all-derived <span class="special">(</span> type <span class="special">)</span></code><p> + Returns the given type and all of its derived types in order + of their distance from type. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.type.is-derived"></a><a class="indexterm" name="id4008222"></a><code class="computeroutput"><span class="keyword">rule</span> is-derived <span class="special">(</span> type base <span class="special">)</span></code><p> + Returns true if <code class="computeroutput">type</code> is equal to + <code class="computeroutput">base</code> or has <code class="computeroutput">base</code> + as its direct or indirect base. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.type.set-generated-target-suffix"></a><a class="indexterm" name="id4008285"></a><code class="computeroutput"><span class="keyword">rule</span> set-generated-target-suffix <span class="special">(</span> type <span class="special">:</span> properties * <span class="special">:</span> suffix <span class="special">)</span></code><p> + Sets a file suffix to be used when generating a target of <code class="computeroutput">type</code> with the + specified properties. Can be called with no properties if no suffix has + already been specified for the <code class="computeroutput">type</code>. The <code class="computeroutput">suffix</code> parameter can be an empty + string (<code class="computeroutput">""</code>) to indicate that no suffix should be used. + </p> +<p> + Note that this does not cause files with <code class="computeroutput">suffix</code> + to be automatically recognized as being of <code class="computeroutput">type</code>. + Two different types can use the same suffix for their generated files + but only one type can be auto-detected for a file with that suffix. + User should explicitly specify which one using the + <a class="link" href="reference.html#bbv2.reference.modules.type.register-suffixes">register-suffixes</a> + rule. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.type.change-generated-target-suffix"></a><a class="indexterm" name="id4008399"></a><code class="computeroutput"><span class="keyword">rule</span> change-generated-target-suffix <span class="special">(</span> type <span class="special">:</span> properties * <span class="special">:</span> suffix <span class="special">)</span></code><p> + Change the suffix previously registered for this type/properties + combination. If suffix is not yet specified, sets it. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.type.generated-target-suffix"></a><a class="indexterm" name="id4008460"></a><code class="computeroutput"><span class="keyword">rule</span> generated-target-suffix <span class="special">(</span> type <span class="special">:</span> property-set <span class="special">)</span></code><p> + Returns the suffix used when generating a file of + <code class="computeroutput">type</code> with the given properties. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.type.set-generated-target-prefix"></a><a class="indexterm" name="id4008520"></a><code class="computeroutput"><span class="keyword">rule</span> set-generated-target-prefix <span class="special">(</span> type <span class="special">:</span> properties * <span class="special">:</span> prefix <span class="special">)</span></code><p> + Sets a target prefix that should be used when generating targets of + <code class="computeroutput">type</code> with the specified properties. Can + be called with empty properties if no prefix for + <code class="computeroutput">type</code> has been specified yet. + </p> +<p> + The <code class="computeroutput">prefix</code> parameter can be empty string + (<code class="computeroutput">""</code>) to indicate that no prefix + should be used. + </p> +<p> + Usage example: library names use the <code class="computeroutput">"lib"</code> + prefix on unix. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.type.change-generated-target-prefix"></a><a class="indexterm" name="id4008619"></a><code class="computeroutput"><span class="keyword">rule</span> change-generated-target-prefix <span class="special">(</span> type <span class="special">:</span> properties * <span class="special">:</span> prefix <span class="special">)</span></code><p> + Change the prefix previously registered for this type/properties + combination. If prefix is not yet specified, sets it. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.type.generated-target-prefix"></a><a class="indexterm" name="id4008680"></a><code class="computeroutput"><span class="keyword">rule</span> generated-target-prefix <span class="special">(</span> type <span class="special">:</span> property-set <span class="special">)</span></code><p> + Returns the prefix used when generating a file of + <code class="computeroutput">type</code> with the given properties. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.modules.type.type"></a><a class="indexterm" name="id4008740"></a><code class="computeroutput"><span class="keyword">rule</span> type <span class="special">(</span> filename <span class="special">)</span></code><p> + Returns file type given its name. If there are several + dots in filename, tries each suffix. E.g. for name of + "file.so.1.2" suffixes "2", "1", and "so" will be tried. + </p> +</li> +</ol></div> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="bbv2.reference.class"></a>Builtin classes</h3></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="reference.html#bbv2.reference.class.abstract-target">Class abstract-target</a></span></dt> +<dt><span class="section"><a href="reference.html#bbv2.reference.class.project-target">Class project-target</a></span></dt> +<dt><span class="section"><a href="reference.html#bbv2.reference.class.main-target">Class main-target</a></span></dt> +<dt><span class="section"><a href="reference.html#bbv2.reference.class.basic-target">Class basic-target</a></span></dt> +<dt><span class="section"><a href="reference.html#bbv2.reference.class.typed-target">Class typed-target</a></span></dt> +<dt><span class="section"><a href="reference.html#bbv2.reference.class.property-set">Class property-set</a></span></dt> +</dl></div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="bbv2.reference.class.abstract-target"></a>Class abstract-target</h4></div></div></div> +<a class="indexterm" name="id4008809"></a><p> + Base class for all abstract targets. + </p> +<pre class="programlisting"> +<span class="keyword">class</span> abstract-target <span class="special">{</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.__init__">__init__</a> <span class="special">(</span> name <span class="special">:</span> project <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.name">name</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.project">project</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.location">location</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.full-name">full-name</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.__init__">generate</a> <span class="special">(</span> property-set <span class="special">)</span> +<span class="special">}</span> +</pre> +<p> + Classes derived from <a class="link" href="reference.html#bbv2.reference.class.abstract-target" title="Class abstract-target">abstract-target</a>: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"><a class="link" href="reference.html#bbv2.reference.class.project-target" title="Class project-target">project-target</a></li> +<li class="listitem"><a class="link" href="reference.html#bbv2.reference.class.main-target" title="Class main-target">main-target</a></li> +<li class="listitem"><a class="link" href="reference.html#bbv2.reference.class.project-target" title="Class project-target">basic-target</a></li> +</ul></div> +<p> + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> +<a name="bbv2.reference.class.abstract-target.__init__"></a><code class="computeroutput"><span class="keyword">rule</span> __init__ <span class="special">(</span> name <span class="special">:</span> project <span class="special">)</span></code><p> + </p> +<div class="variablelist"><dl> +<dt><span class="term"><code class="literal">name</code></span></dt> +<dd><p>The name of the target in the Jamfile.</p></dd> +<dt><span class="term"><code class="literal">project</code></span></dt> +<dd><p>The <a class="link" href="reference.html#bbv2.reference.class.project-target" title="Class project-target">project</a> to which this target belongs.</p></dd> +</dl></div> +<p> + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.class.abstract-target.name"></a><a class="indexterm" name="id4009146"></a><code class="computeroutput"><span class="keyword">rule</span> name <span class="special">(</span> <span class="special">)</span></code><p>Returns the name of this target.</p> +</li> +<li class="listitem"> +<a name="bbv2.reference.class.abstract-target.project"></a><a class="indexterm" name="id4009194"></a><code class="computeroutput"><span class="keyword">rule</span> project <span class="special">(</span> <span class="special">)</span></code><p>Returns the <a class="link" href="reference.html#bbv2.reference.class.project-target" title="Class project-target">project</a> for this target.</p> +</li> +<li class="listitem"> +<a name="bbv2.reference.class.abstract-target.location"></a><a class="indexterm" name="id4009249"></a><code class="computeroutput"><span class="keyword">rule</span> location <span class="special">(</span> <span class="special">)</span></code><p>Returns the location where the target was declared.</p> +</li> +<li class="listitem"> +<a name="bbv2.reference.class.abstract-target.full-name"></a><a class="indexterm" name="id4009298"></a><code class="computeroutput"><span class="keyword">rule</span> full-name <span class="special">(</span> <span class="special">)</span></code><p>Returns a user-readable name for this target.</p> +</li> +<li class="listitem"> +<a name="bbv2.reference.class.abstract-target.generate"></a><a class="indexterm" name="id4009346"></a><code class="computeroutput"><span class="keyword">rule</span> generate <span class="special">(</span> property-set <span class="special">)</span></code><p> + Generates virtual targets for this abstract target using the specified + properties, unless a different value of some feature is required by the + target. This is an abstract method which must be overriden by derived + classes. + </p> +<p> + On success, returns: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem">a property-set with the usage requirements to be applied to dependents</li> +<li class="listitem">a list of produced virtual targets, which may be empty.</li> +</ul></div> +<p> + If <code class="computeroutput">property-set</code> is empty, performs the + default build of this target, in a way specific to the derived class. + </p> +</li> +</ol></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="bbv2.reference.class.project-target"></a>Class project-target</h4></div></div></div> +<a class="indexterm" name="id4009428"></a><pre class="programlisting"> +<span class="keyword">class</span> project-target <span class="special">:</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target" title="Class abstract-target">abstract-target</a> <span class="special">{</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.project-target.generate">generate</a> <span class="special">(</span> property-set <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.project-target.build-dir">build-dir</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.project-target.main-target">main-target</a> <span class="special">(</span> name <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.project-target.has-main-target">has-main-target</a> <span class="special">(</span> name <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.project-target.find">find</a> <span class="special">(</span> id <span class="special">:</span> no-error ? <span class="special">)</span> + + <span class="comment"># Methods inherited from </span><a class="link" href="reference.html#bbv2.reference.class.abstract-target" title="Class abstract-target">abstract-target</a> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.name">name</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.project">project</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.location">location</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.full-name">full-name</a> <span class="special">(</span> <span class="special">)</span> +<span class="special">}</span> +</pre> +<p> + This class has the following responsibilities: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + Maintaining a list of main targets in this project and building them. + </p></li></ul></div> +<p> + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> +<a name="bbv2.reference.class.project-target.generate"></a><a class="indexterm" name="id4009743"></a><code class="computeroutput"><span class="keyword">rule</span> generate <span class="special">(</span> property-set <span class="special">)</span></code><p> + Overrides + <a class="link" href="reference.html#bbv2.reference.class.abstract-target.generate">abstract-target.generate</a>. + + Generates virtual targets for all the targets contained in this project. + </p> +<p> + On success, returns: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem">a property-set with the usage requirements to be applied to dependents</li> +<li class="listitem">a list of produced virtual targets, which may be empty.</li> +</ul></div> +<p> + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.class.project-target.build-dir"></a><a class="indexterm" name="id4009817"></a><code class="computeroutput"><span class="keyword">rule</span> build-dir <span class="special">(</span> <span class="special">)</span></code><p> + Returns the root build directory of the project. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.class.project-target.main-target"></a><a class="indexterm" name="id4009865"></a><code class="computeroutput"><span class="keyword">rule</span> main-target <span class="special">(</span> name <span class="special">)</span></code><p> + Returns a <a class="link" href="reference.html#bbv2.reference.class.main-target" title="Class main-target">main-target</a> + class instance corresponding to <code class="literal">name</code>. + Can only be called after the project has been fully loaded. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.class.project-target.has-main-target"></a><a class="indexterm" name="id4009928"></a><code class="computeroutput"><span class="keyword">rule</span> has-main-target <span class="special">(</span> name <span class="special">)</span></code><p> + Returns whether a <a class="link" href="reference.html#bbv2.reference.class.main-target" title="Class main-target">main-target</a> + with the specified name exists. + Can only be called after the project has been fully loaded. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.class.project-target.find"></a><a class="indexterm" name="id4009988"></a><code class="computeroutput"><span class="keyword">rule</span> find <span class="special">(</span> id <span class="special">:</span> no-error ? <span class="special">)</span></code><p> + Find and return the target with the specified id, treated relative to + self. Id may specify either a target or a file name with the target taking + priority. May report an error or return nothing if the target is not found + depending on the <code class="literal">no-error</code> parameter. + </p> +</li> +</ol></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="bbv2.reference.class.main-target"></a>Class main-target</h4></div></div></div> +<a class="indexterm" name="id4010058"></a><pre class="programlisting"> +<span class="keyword">class</span> main-target <span class="special">:</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target" title="Class abstract-target">abstract-target</a> <span class="special">{</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.main-target.generate">generate</a> <span class="special">(</span> property-set <span class="special">)</span> + + <span class="comment"># Methods inherited from </span><a class="link" href="reference.html#bbv2.reference.class.abstract-target" title="Class abstract-target">abstract-target</a> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.name">name</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.project">project</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.location">location</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.full-name">full-name</a> <span class="special">(</span> <span class="special">)</span> +<span class="special">}</span> +</pre> +<p> + A <a class="link" href="reference.html#bbv2.reference.class.main-target" title="Class main-target">main-target</a> + represents a named top-level target in a Jamfile. + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> +<a name="bbv2.reference.class.main-target.generate"></a><a class="indexterm" name="id4010262"></a><code class="computeroutput"><span class="keyword">rule</span> generate <span class="special">(</span> property-set <span class="special">)</span></code><p> + Overrides + <a class="link" href="reference.html#bbv2.reference.class.abstract-target.generate">abstract-target.generate</a>. + + Select an alternative for this main target, by finding all alternatives + whose requirements are satisfied by <code class="literal">property-set</code> and + picking the one with the longest requirements set. Returns the result + of calling <a class="link" href="reference.html#bbv2.reference.class.basic-target.generate">generate</a> + on that alternative. + </p> +<p> + On success, returns: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem">a property-set with the usage requirements to be applied to dependents</li> +<li class="listitem">a list of produced virtual targets, which may be empty.</li> +</ul></div> +<p> + </p> +</li></ol></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="bbv2.reference.class.basic-target"></a>Class basic-target</h4></div></div></div> +<a class="indexterm" name="id4010361"></a><pre class="programlisting"> +<span class="keyword">class</span> basic-target <span class="special">:</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target" title="Class abstract-target">abstract-target</a> <span class="special">{</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.basic-target.__init__">__init__</a> <span class="special">(</span> name <span class="special">:</span> project <span class="special">:</span> sources * <span class="special">:</span> requirements * <span class="special">:</span> default-build * <span class="special">:</span> usage-requirements * <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.basic-target.generate">generate</a> <span class="special">(</span> property-set <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.basic-target.construct">construct</a> <span class="special">(</span> name <span class="special">:</span> source-targets * <span class="special">:</span> property-set <span class="special">)</span> + + <span class="comment"># Methods inherited from </span><a class="link" href="reference.html#bbv2.reference.class.abstract-target" title="Class abstract-target">abstract-target</a> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.name">name</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.project">project</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.location">location</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.full-name">full-name</a> <span class="special">(</span> <span class="special">)</span> +<span class="special">}</span> +</pre> +<p> + Implements the most standard way of constructing main target alternative from + sources. Allows sources to be either files or other main targets and handles + generation of those dependency targets. + + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> +<a name="bbv2.reference.class.basic-target.__init__"></a><code class="computeroutput"><span class="keyword">rule</span> __init__ <span class="special">(</span> name <span class="special">:</span> project <span class="special">:</span> sources * <span class="special">:</span> requirements * <span class="special">:</span> default-build * <span class="special">:</span> usage-requirements * <span class="special">)</span></code><p> + </p> +<div class="variablelist"><dl> +<dt><span class="term"><code class="literal">name</code></span></dt> +<dd><p>The name of the target</p></dd> +<dt><span class="term"><code class="literal">project</code></span></dt> +<dd><p> + The <a class="link" href="reference.html#bbv2.reference.class.project-target" title="Class project-target">project</a> + in which the target is declared. + </p></dd> +</dl></div> +<p> + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.class.basic-target.generate"></a><a class="indexterm" name="id4010752"></a><code class="computeroutput"><span class="keyword">rule</span> generate <span class="special">(</span> property-set <span class="special">)</span></code><p> + Overrides + <a class="link" href="reference.html#bbv2.reference.class.abstract-target.generate">abstract-target.generate</a>. + + Determines final build properties, generates sources, and calls + <a class="link" href="reference.html#bbv2.reference.class.basic-target.construct">construct</a>. + This method should not be overridden. + </p> +<p> + On success, returns: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem">a property-set with the usage requirements to be applied to dependents</li> +<li class="listitem">a list of produced virtual targets, which may be empty.</li> +</ul></div> +<p> + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.class.basic-target.construct"></a><a class="indexterm" name="id4010834"></a><code class="computeroutput"><span class="keyword">rule</span> construct <span class="special">(</span> name <span class="special">:</span> source-targets * <span class="special">:</span> property-set <span class="special">)</span></code><p> + Constructs virtual targets for this abstract target. Returns a + usage-requirements property-set and a list of virtual + targets. Should be overriden in derived classes. + </p> +</li> +</ol></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="bbv2.reference.class.typed-target"></a>Class typed-target</h4></div></div></div> +<a class="indexterm" name="id4010903"></a><pre class="programlisting"> +<span class="keyword">class</span> typed-target <span class="special">:</span> <a class="link" href="reference.html#bbv2.reference.class.basic-target" title="Class basic-target">basic-target</a> <span class="special">{</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.typed-target.__init__">__init__</a> <span class="special">(</span> name <span class="special">:</span> project <span class="special">:</span> type <span class="special">:</span> sources * <span class="special">:</span> requirements * <span class="special">:</span> default-build * <span class="special">:</span> usage-requirements * <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.typed-target.type">type</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.typed-target.construct">construct</a> <span class="special">(</span> name <span class="special">:</span> source-targets * <span class="special">:</span> property-set <span class="special">)</span> + + <span class="comment"># Methods inherited from </span><a class="link" href="reference.html#bbv2.reference.class.abstract-target" title="Class abstract-target">abstract-target</a> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.name">name</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.project">project</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.location">location</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.abstract-target.full-name">full-name</a> <span class="special">(</span> <span class="special">)</span> + + <span class="comment"># Methods inherited from </span><a class="link" href="reference.html#bbv2.reference.class.basic-target" title="Class basic-target">basic-target</a> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.basic-target.generate">generate</a> <span class="special">(</span> property-set <span class="special">)</span> + <span class="special">}</span> +</pre> +<p> + <a class="link" href="reference.html#bbv2.reference.class.typed-target" title="Class typed-target">typed-target</a> + is the most common kind of target alternative. Rules for creating + typed targets are defined automatically for each type. + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> +<a name="bbv2.reference.class.typed-target.__init__"></a><code class="computeroutput"><span class="keyword">rule</span> __init__ <span class="special">(</span> name <span class="special">:</span> project <span class="special">:</span> type <span class="special">:</span> sources * <span class="special">:</span> requirements * <span class="special">:</span> default-build * <span class="special">:</span> usage-requirements * <span class="special">)</span></code><p> + </p> +<div class="variablelist"><dl> +<dt><span class="term"><code class="literal">name</code></span></dt> +<dd><p>The name of the target</p></dd> +<dt><span class="term"><code class="literal">project</code></span></dt> +<dd><p> + The <a class="link" href="reference.html#bbv2.reference.class.project-target" title="Class project-target">project</a> + in which the target is declared. + </p></dd> +<dt><span class="term"><code class="literal">type</code></span></dt> +<dd><p> + The <a class="link" href="reference.html#bbv2.reference.modules.type" title="type">type</a> + of the target. + </p></dd> +</dl></div> +<p> + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.class.typed-target.type"></a><a class="indexterm" name="id4011377"></a><code class="computeroutput"><span class="keyword">rule</span> type <span class="special">(</span> <span class="special">)</span></code><p> + Returns the <a class="link" href="reference.html#bbv2.reference.modules.type" title="type">type</a> + of the target. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.class.typed-target.construct"></a><a class="indexterm" name="id4011433"></a><code class="computeroutput"><span class="keyword">rule</span> construct <span class="special">(</span> name <span class="special">:</span> source-targets * <span class="special">:</span> property-set <span class="special">)</span></code><p> + Implements <a class="link" href="reference.html#bbv2.reference.class.basic-target.construct"> + basic-target.construct</a>. Attempts to create a target of + the correct type using generators appropriate for the given + <a class="link" href="reference.html#bbv2.reference.class.property-set" title="Class property-set">property-set</a>. + Returns a <a class="link" href="reference.html#bbv2.reference.class.property-set" title="Class property-set"> + property-set</a> containing the usage requirements + and a list of virtual targets. + + </p> +<div class="note"><table border="0" summary="Note"> +<tr> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> +<th align="left">Note</th> +</tr> +<tr><td align="left" valign="top"><p> + This function is invoked automatically by + <a class="link" href="reference.html#bbv2.reference.class.basic-target.generate">basic-target.generate</a> + and should not be called directly by users. + </p></td></tr> +</table></div> +<p> + </p> +</li> +</ol></div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="bbv2.reference.class.property-set"></a>Class property-set</h4></div></div></div> +<a class="indexterm" name="id4011545"></a><p>Class for storing a set of properties.</p> +<pre class="programlisting"> +<span class="keyword">class</span> property-set <span class="special">{</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.property-set.raw">raw</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.property-set.str">str</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.property-set.propagated">propagated</a> <span class="special">(</span> <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.property-set.add">add</a> <span class="special">(</span> ps <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.property-set.add-raw">add-raw</a> <span class="special">(</span> properties * <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.property-set.refine">refine</a> <span class="special">(</span> ps <span class="special">)</span> + <span class="keyword">rule</span> <a class="link" href="reference.html#bbv2.reference.class.property-set.get">get</a> <span class="special">(</span> feature <span class="special">)</span> +<span class="special">}</span> +</pre> +<p> + There is 1<->1 correspondence between identity and value. No two instances + of the class are equal. To maintain this property, the 'property-set.create' + rule should be used to create new instances. Instances are immutable. + </p> +<div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"> +<a name="bbv2.reference.class.property-set.raw"></a><a class="indexterm" name="id4011774"></a><code class="computeroutput"><span class="keyword">rule</span> raw <span class="special">(</span> <span class="special">)</span></code><p>Returns a Jam list of the stored properties.</p> +</li> +<li class="listitem"> +<a name="bbv2.reference.class.property-set.str"></a><a class="indexterm" name="id4011822"></a><code class="computeroutput"><span class="keyword">rule</span> str <span class="special">(</span> <span class="special">)</span></code><p>Returns the string repesentation of the stored properties.</p> +</li> +<li class="listitem"> +<a name="bbv2.reference.class.property-set.propagated"></a><a class="indexterm" name="id4011870"></a><code class="computeroutput"><span class="keyword">rule</span> propagated <span class="special">(</span> <span class="special">)</span></code><p> + Returns a <a class="link" href="reference.html#bbv2.reference.class.property-set" title="Class property-set">property-set</a> + containing all the <a class="link" href="reference.html#bbv2.reference.features.attributes.propagated">propagated</a> + properties in this <a class="link" href="reference.html#bbv2.reference.class.property-set" title="Class property-set">property-set</a>. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.class.property-set.add"></a><a class="indexterm" name="id4011942"></a><code class="computeroutput"><span class="keyword">rule</span> add <span class="special">(</span> ps <span class="special">)</span></code><p> + Returns a new <a class="link" href="reference.html#bbv2.reference.class.property-set" title="Class property-set"> + property-set</a> containing the union of the properties + in this <a class="link" href="reference.html#bbv2.reference.class.property-set" title="Class property-set"> + property-set</a> and in <code class="literal">ps</code>. + </p> +<div class="note"><table border="0" summary="Note"> +<tr> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> +<th align="left">Note</th> +</tr> +<tr><td align="left" valign="top"><p> + If <code class="literal">ps</code> contains non-free properties + that should override the values in this object, use + <a class="link" href="reference.html#bbv2.reference.class.property-set.refine"> + refine</a> instead. + </p></td></tr> +</table></div> +<p> + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.class.property-set.add-raw"></a><a class="indexterm" name="id4012036"></a><code class="computeroutput"><span class="keyword">rule</span> add-raw <span class="special">(</span> properties * <span class="special">)</span></code><p> + Link <a class="link" href="reference.html#bbv2.reference.class.property-set.add"> + add</a>, except that it takes a list of properties + instead of a <a class="link" href="reference.html#bbv2.reference.class.property-set" title="Class property-set"> + property-set</a>. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.class.property-set.refine"></a><a class="indexterm" name="id4012101"></a><code class="computeroutput"><span class="keyword">rule</span> refine <span class="special">(</span> ps <span class="special">)</span></code><p> + Refines properties by overriding any non-free and non-conditional + properties for which a different value is specified in + <code class="literal">ps</code>. Returns the resulting + <a class="link" href="reference.html#bbv2.reference.class.property-set" title="Class property-set">property-set</a>. + </p> +</li> +<li class="listitem"> +<a name="bbv2.reference.class.property-set.get"></a><a class="indexterm" name="id4012165"></a><code class="computeroutput"><span class="keyword">rule</span> get <span class="special">(</span> feature <span class="special">)</span></code><p> + Returns all the values of <code class="literal">feature</code>. + </p> +</li> +</ol></div> +</div> +</div> +<div class="section"> +<div class="titlepage"><div><div><h3 class="title"> <a name="bbv2.reference.buildprocess"></a>Build process</h3></div></div></div> <div class="toc"><dl> <dt><span class="section"><a href="reference.html#bbv2.reference.buildprocess.alternatives">Alternative selection</a></span></dt> <dt><span class="section"><a href="reference.html#bbv2.reference.buildprocess.common">Determining common properties</a></span></dt> +<dt><span class="section"><a href="reference.html#bbv2.reference.buildprocess.targetpath">Target Paths</a></span></dt> </dl></div> <p>The general overview of the build process was given in the <a class="link" href="overview.html#bbv2.overview.build_process" title="The Build Process">user documentation</a>. @@ -1481,13 +2371,50 @@ exe a : a.cpp <p> </p> </div> +<div class="section"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="bbv2.reference.buildprocess.targetpath"></a>Target Paths</h4></div></div></div> +<p>Several factors determine the location of a concrete + file target. All files in a project are built under + the directory bin unless this is overriden by the build-dir project + attribute. Under bin is a path that depends on the properties + used to build each target. This path is uniquely determined by + all non-free, non-incidental properties. For example, + given a property set containing: + <code class="computeroutput"><toolset>gcc <toolset-gcc:version>4.6.1 <variant>debug + <warnings>all <define>_DEBUG <include>/usr/local/include + <link>static</code>, + the path will be gcc-4.6.1/debug/link-static. <warnings> is an + incidental feature and <define> and <include> are + free features, so they do not affect the path.</p> +<p>Sometimes the paths produced by Boost.Build can become excessively + long. There are a couple of command line options that can help with this. + --abbreviate-paths reduces each element to no more than five characters. + For example, link-static becomes lnk-sttc. The --hash option reduces the + path to a single directory using an MD5 hash.</p> +<p>There are two features that affect the build + directory. The <location> feature completely + overrides the default build directory. For example, + </p> +<pre class="programlisting">exe a : a.cpp : <location>. ;</pre> +<p> + builds all the files produced by <code class="computeroutput">a</code> + in the directory of the Jamfile. This is generally + discouraged, as it precludes variant builds.</p> +<p>The <location-prefix> feature adds a + prefix to the path, under the project's build + directory. For example, + </p> +<pre class="programlisting">exe a : a.cpp : <location-prefix>subdir ;</pre> +<p> + will create the files for <code class="computeroutput">a</code> in bin/subdir/gcc-4.6.1/debug</p> +</div> </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="bbv2.reference.definitions"></a>Definitions</h3></div></div></div> <div class="toc"><dl> <dt><span class="section"><a href="reference.html#bbv2.reference.features">Features and properties</a></span></dt> -<dt><span class="section"><a href="reference.html#bbv2.reference.variants">Build Variants</a></span></dt> <dt><span class="section"><a href="reference.html#bbv2.reference.variants.proprefine">Property refinement</a></span></dt> <dt><span class="section"><a href="reference.html#bbv2.reference.variants.propcond">Conditional properties</a></span></dt> <dt><span class="section"><a href="reference.html#bbv2.reference.ids">Target identifiers and references</a></span></dt> @@ -1572,7 +2499,7 @@ exe a : a.cpp <p>Non-incidental features are assumed to affect build products, so the files for targets whose build specification differs in non-incidental features are placed in different - directories as described in "target paths" below. [ where? ] + directories as described in <a class="xref" href="reference.html#bbv2.reference.buildprocess.targetpath" title="Target Paths">the section called “Target Paths”</a>. </p> </li> <li class="listitem"> @@ -1617,13 +2544,11 @@ exe a : a.cpp </li> <li class="listitem"> <p><span class="emphasis"><em>symmetric</em></span></p> -<p>A symmetric feature's default value is not automatically - included in <a class="link" href="reference.html#bbv2.reference.variants" title="Build Variants">build variants</a>. Normally - a feature only generates a subvariant directory when its - value differs from the value specified by the build variant, +<p>Normally a feature only generates a subvariant directory + when its value differs from its default value, leading to an assymmetric subvariant directory structure for - certain values of the feature. A symmetric feature, when - relevant to the toolset, always generates a corresponding + certain values of the feature. A symmetric feature + always generates a corresponding subvariant directory.</p> </li> <li class="listitem"> @@ -1689,22 +2614,6 @@ rule feature ( name : allowed-values * : attributes * ) </div> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> -<a name="bbv2.reference.variants"></a>Build Variants</h4></div></div></div> -<p> - A build variant, or (simply variant) is a special kind of composite - feature that automatically incorporates the default values of - features that . Typically you'll want at least two separate - variants: one for debugging, and one for your release code. [ - Volodya says: "Yea, we'd need to mention that it's a composite - feature and describe how they are declared, in pacticular that - default values of non-optional features are incorporated into - build variant automagically. Also, do we wan't some variant - inheritance/extension/templates. I don't remember how it works in - V1, so can't document this for V2.". Will clean up soon -DWA ] - </p> -</div> -<div class="section"> -<div class="titlepage"><div><div><h4 class="title"> <a name="bbv2.reference.variants.proprefine"></a>Property refinement</h4></div></div></div> <p>When a target with certain properties is requested, and that target requires some set of properties, it is needed to find the diff --git a/doc/html/bbv2/tasks.html b/doc/html/bbv2/tasks.html index 00e54f7b04..b8300bb4e0 100755..100644 --- a/doc/html/bbv2/tasks.html +++ b/doc/html/bbv2/tasks.html @@ -44,7 +44,7 @@ <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="bbv2.tasks.programs"></a>Programs</h3></div></div></div> -<a class="indexterm" name="id3898100"></a><p> +<a class="indexterm" name="id3997762"></a><p> Programs are created using the <code class="computeroutput">exe</code> rule, which follows the <a class="link" href="overview.html#bbv2.main-target-rule-syntax">common syntax</a>. For example: @@ -55,7 +55,7 @@ exe hello : hello.cpp some_library.lib /some_project//library ; </pre> <p> - This will create an executable file from the sources -- in this case, one + This will create an executable file from the sources—in this case, one C++ file, one library file present in the same directory, and another library that is created by Boost.Build. Generally, sources can include C and C++ files, object files and libraries. Boost.Build will automatically @@ -80,7 +80,7 @@ exe hello : hello.cpp some_library.lib /some_project//library <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="bbv2.tasks.libraries"></a>Libraries</h3></div></div></div> -<p> +<a class="indexterm" name="id3997834"></a><p> Library targets are created using the <code class="computeroutput">lib</code> rule, which follows the <a class="link" href="overview.html#bbv2.main-target-rule-syntax">common syntax </a>. For example: @@ -91,66 +91,79 @@ lib helpers : helpers.cpp ; <p> This will define a library target named <code class="computeroutput">helpers</code> built from the <code class="computeroutput">helpers.cpp</code> source file. + It can be either a static library or a shared library, + depending on the value of the <a class="link" href="reference.html#bbv2.overview.builtins.features.link"><link></a> feature. </p> <p> - Depending on the given <link> feature value the library will be - either static or shared. - </p> -<p> - Library targets may be used to represent: + Library targets can represent: </p> <div class="itemizedlist"><ul class="itemizedlist" type="disc"> <li class="listitem"><p> - <code class="computeroutput">Built libraries</code> that get built from specified sources, - as is the one in the example above. + Libraries that should be built from source, + as in the example above. </p></li> <li class="listitem"><p> - <code class="computeroutput">Prebuilt libraries</code> which already exist on the system - and are just supposed to be used by the build system. Such - libraries may be searched for by the tools using them (typically - linkers referencing the library using the <code class="option">-l</code> - option) or their path may be known in advance by the build system. - + Prebuilt libraries which already exist on the system. + Such libraries can be searched for by the tools using them (typically + with the linker's <code class="option">-l</code> option) or their paths can be + known in advance by the build system. </p></li> </ul></div> <p> </p> <p> - The syntax for these case is given below: + The syntax for prebuilt libraries is given below: </p> <pre class="programlisting"> lib z : : <name>z <search>/home/ghost ; lib compress : : <file>/opt/libs/compress.a ; </pre> <p> - The <code class="computeroutput">name</code> property specifies the name that should be passed to - the <code class="option">-l</code> option, and the <code class="computeroutput">file</code> property - specifies the file location. The <code class="varname">search</code> feature - specifies paths in which to search for the library. That feature can be - specified several times or it can be omitted, in which case only the - default compiler paths will be searched. + The <code class="computeroutput">name</code> property specifies the name of the library + without the standard prefixes and suffixes. For example, depending + on the system, <code class="computeroutput">z</code> could refer to a file called + z.so, libz.a, or z.lib, etc. The <code class="computeroutput">search</code> feature + specifies paths in which to search for the library in addition + to the default compiler paths. <code class="computeroutput">search</code> can be specified + several times or it can be omitted, in which case only the default + compiler paths will be searched. The <code class="computeroutput">file</code> property + specifies the file location. </p> <p> - The difference between using the <code class="varname">file</code> feature as - opposed to the <code class="varname">name</code> feature together with the <code class="varname"> - search</code> feature is that <code class="varname">file</code> is more precise. - A specific file will be used as opposed to the <code class="varname">search</code> - feature only adding a library path, or the <code class="varname">name</code> feature - giving only the basic name of the library. The search rules are specific - to the linker used. For example, given these definition: + The difference between using the <code class="computeroutput">file</code> feature and + using a combination of the <code class="computeroutput">name</code> and <code class="computeroutput">search</code> + features is that <code class="computeroutput">file</code> is more precise. + + </p> +<div class="warning"><table border="0" summary="Warning"> +<tr> +<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/src/images/warning.png"></td> +<th align="left">Warning</th> +</tr> +<tr><td align="left" valign="top"> +<p> + The value of the <code class="computeroutput">search</code> feature is just added to the + linker search path. When linking to multiple libraries, + the paths specified by <code class="computeroutput">search</code> are combined without + regard to which <code class="computeroutput">lib</code> target each path came from. + Thus, given </p> <pre class="programlisting"> -lib a : : <variant>release <file>/pool/release/a.so ; -lib a : : <variant>debug <file>/pool/debug/a.so ; -lib b : : <variant>release <file>/pool/release/b.so ; -lib b : : <variant>debug <file>/pool/debug/b.so ; +lib a : : <name>a <search>/pool/release ; +lib b : : <name>b <search>/pool/debug ; </pre> <p> - It is possible to use a release version of <code class="computeroutput">a</code> and debug - version of <code class="computeroutput">b</code>. Had we used the <code class="varname">name</code> and - <code class="varname">search</code> features, the linker would have always picked - either the release or the debug versions. - + If /pool/release/a.so, /pool/release/b.so, /pool/debug/a.so, + and /pool/release/b.so all exist, the linker will probably + take both <code class="computeroutput">a</code> and <code class="computeroutput">b</code> from the same + directory, instead of finding <code class="computeroutput">a</code> in /pool/release + and <code class="computeroutput">b</code> in /pool/debug. If you need to distinguish + between multiple libraries with the same name, it's safer + to use <code class="computeroutput">file</code>. + </p> +</td></tr> +</table></div> +<p> </p> <p> For convenience, the following syntax is allowed: @@ -190,18 +203,18 @@ lib png : z : <name>png ; </tr> <tr><td align="left" valign="top"> <p> - When a library has a shared library defined as its source, or a static - library has another static library defined as its source then any target + When a library has a shared library as a source, or a static + library has another static library as a source then any target linking to the first library with automatically link to its source library as well. </p> <p> - On the other hand, when a shared library has a static library defined as - its source then the first library will be built so that it completely + On the other hand, when a shared library has a static library as + a source then the first library will be built so that it completely includes the second one. </p> <p> - If you do not want shared libraries to include all libraries specified + If you do not want a shared library to include all the libraries specified in its sources (especially statically linked ones), you would need to use the following: </p> @@ -211,15 +224,16 @@ lib a : a.cpp : <use>b : : <library>b ; </pre> <p> This specifies that library <code class="computeroutput">a</code> uses library <code class="computeroutput">b</code>, - and causes all executables that link to <code class="computeroutput">a</code> also link to - <code class="computeroutput">b</code>. In this case, even for shared linking, the - <code class="computeroutput">a</code> library will not even refer to <code class="computeroutput">b</code>. + and causes all executables that link to <code class="computeroutput">a</code> to link to + <code class="computeroutput">b</code> also. In this case, even for shared linking, the + <code class="computeroutput">a</code> library will not refer to <code class="computeroutput">b</code>. </p> </td></tr> </table></div> <p> - One Boost.Build feature that is often very useful for defining library - targets are usage requirements. For example, imagine that + + <a class="link" href="overview.html#bbv2.overview.targets" title="Declaring Targets">Usage requirements</a> are often + very useful for defining library targets. For example, imagine that you want you build a <code class="computeroutput">helpers</code> library and its interface is described in its <code class="computeroutput">helpers.hpp</code> header file located in the same directory as the <code class="computeroutput">helpers.cpp</code> source file. Then you could add @@ -293,7 +307,7 @@ exe main : main.cpp static_libraries ; files. </p> <h4> -<a name="id3898659"></a>Basic install</h4> +<a name="id3998370"></a>Basic install</h4> <p> For installing a built target you should use the <code class="computeroutput">install</code> rule, which follows the <a class="link" href="overview.html#bbv2.main-target-rule-syntax"> @@ -332,7 +346,7 @@ install dist2 : hello helpers : <location>$(DIST) ; variables</a> </p> <h4> -<a name="id3898771"></a>Installing with all dependencies</h4> +<a name="id3998482"></a>Installing with all dependencies</h4> <p> Specifying the names of all libraries to install can be boring. The <code class="computeroutput">install</code> allows you to specify only the top-level executable @@ -356,8 +370,8 @@ install dist : hello otherwise, all found target will be installed. </p> <h4> -<a name="id3898824"></a>Preserving Directory Hierarchy</h4> -<a class="indexterm" name="id3898827"></a><p> +<a name="id3998535"></a>Preserving Directory Hierarchy</h4> +<a class="indexterm" name="id3998538"></a><p> By default, the <code class="computeroutput">install</code> rule will strip paths from its sources. So, if sources include <code class="filename">a/b/c.hpp</code>, the <code class="filename">a/b</code> part will be ignored. To make the @@ -381,7 +395,7 @@ install headers an entire directory tree. </p> <h4> -<a name="id3898903"></a>Installing into Several Directories</h4> +<a name="id3998614"></a>Installing into Several Directories</h4> <p> The <a class="link" href="tasks.html#bbv2.tasks.alias" title="Alias"><code class="computeroutput">alias</code></a> rule can be used when targets need to be installed into several directories: @@ -395,7 +409,7 @@ install install-lib : helper : /usr/lib ; </p> <p> Because the <code class="computeroutput">install</code> rule just copies targets, most free - features <sup>[<a name="id3898939" href="#ftn.id3898939" class="footnote">12</a>]</sup> have no + features <sup>[<a name="id3998650" href="#ftn.id3998650" class="footnote">12</a>]</sup> have no effect when used in requirements of the <code class="computeroutput">install</code> rule. The only two that matter are <a class="link" href="reference.html#bbv2.builtin.features.dependency"> <code class="varname">dependency</code></a> and, on Unix, <a class="link" href="reference.html#bbv2.reference.features.dll-path"><code class="varname">dll-path</code> @@ -429,7 +443,7 @@ unit-test helpers_test : helpers_test.cpp helpers ; </p> <p> The <code class="computeroutput">unit-test</code> rule behaves like the - <code class="computeroutput">exe</code> rule, but after the executable is created + <a class="link" href="tasks.html#bbv2.tasks.programs" title="Programs">exe</a> rule, but after the executable is created it is also run. If the executable returns an error code, the build system will also return an error and will try running the executable on the next invocation until it runs successfully. This behaviour ensures that you can @@ -504,7 +518,7 @@ rule run ( sources + : args * : input-files * : requirements * : target-name ? target-name</code></em>.output</code>. </p> <p> - <a class="indexterm" name="id3899260"></a> + <a class="indexterm" name="id3998973"></a> If the <code class="literal">preserve-test-targets</code> feature has the value <code class="literal">off</code>, then <code class="computeroutput">run</code> and the <code class="computeroutput">run-fail</code> rules will remove the executable after running it. This somewhat decreases @@ -523,8 +537,8 @@ boost-test(<em class="replaceable"><code>test-type</code></em>) <em class="repla <p> </p> <p> - It is possible to process the list of tests, the output of bjam during - command run, and the presense/absense of the <code class="filename">*.test</code> + It is possible to process the list of tests, Boost.Build output + and the presense/absense of the <code class="filename">*.test</code> files created when test passes into human-readable status table of tests. Such processing utilities are not included in Boost.Build. </p> @@ -533,12 +547,12 @@ boost-test(<em class="replaceable"><code>test-type</code></em>) <em class="repla <div class="titlepage"><div><div><h3 class="title"> <a name="bbv2.builtins.raw"></a>Custom commands</h3></div></div></div> <p> - When you use most of main target rules, Boost.Build automatically figures - what commands to run and it what order. As soon as you want to use new + For most main target rules, Boost.Build automatically figures out + the commands to run. When you want to use new file types or support new tools, one approach is to extend Boost.Build to - smoothly support them, as documented in <a class="xref" href="extender.html" title="Extender Manual">the section called “Extender Manual”</a>. - However, if there is only a single place where the new tool is used, it - might be easier to just explicitly specify the commands to run. + support them smoothly, as documented in <a class="xref" href="extender.html" title="Extender Manual">the section called “Extender Manual”</a>. + However, if the new tool is only used in a single place, it + might be easier just to specify the commands to run explicitly. </p> <p> @@ -547,8 +561,8 @@ boost-test(<em class="replaceable"><code>test-type</code></em>) <em class="repla of source file, by running a command you specify. The <code class="computeroutput"> notfile</code> rule allows you to run an arbitrary command, without creating any files. And finaly, the <code class="computeroutput">generate - </code> rule allows you to describe transformation using - Boost.Build's virtual targets. This is higher-level than file names that + </code> rule allows you to describe a transformation using + Boost.Build's virtual targets. This is higher-level than the file names that the <code class="computeroutput">make</code> rule operates with and allows you to create more than one target, create differently named targets depending on properties or use more than one tool. @@ -560,8 +574,8 @@ boost-test(<em class="replaceable"><code>test-type</code></em>) <em class="repla command. </p> <p> - Suppose you want to create file <code class="filename">file.out</code> from file - <code class="filename">file.in</code> by running command <span class="command"><strong> + Suppose you want to create the file <code class="filename">file.out</code> from + the file <code class="filename">file.in</code> by running the command <span class="command"><strong> in2out</strong></span>. Here is how you would do this in Boost.Build: </p> <pre class="programlisting"> @@ -572,7 +586,7 @@ actions in2out } </pre> <p> - If you run <span class="command"><strong>bjam</strong></span> and <code class="filename">file.out</code> does + If you run <span class="command"><strong>b2</strong></span> and <code class="filename">file.out</code> does not exist, Boost.Build will run the <span class="command"><strong>in2out</strong></span> command to create that file. For more details on specifying actions, see <a class="xref" href="overview.html#bbv2.overview.jam_language.actions">the section called “Boost.Jam Language”</a>. </p> @@ -719,7 +733,7 @@ exe main : main.cpp pch ; Making this mechanism work across main target boundaries is possible, but imposes certain overhead. For that reason, if there is implicit dependency on files from other main targets, the <code class="literal"><implicit-dependency> - </code> [ link ] feature must be used, for example: + </code> feature must be used, for example: </p> <pre class="programlisting"> lib parser : parser.y ; @@ -734,7 +748,7 @@ exe app : app.cpp : <implicit-dependency>parser ; <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="bbv2.tasks.crosscompile"></a>Cross-compilation</h3></div></div></div> -<a class="indexterm" name="id3899849"></a><p>Boost.Build supports cross compilation with the gcc and msvc +<a class="indexterm" name="id3999554"></a><p>Boost.Build supports cross compilation with the gcc and msvc toolsets.</p> <p> When using gcc, you first need to specify your cross compiler @@ -748,7 +762,7 @@ using gcc : arm : arm-none-linux-gnueabi-g++ ; just request that this compiler version to be used: </p> <pre class="screen"> -bjam toolset=gcc-arm +b2 toolset=gcc-arm </pre> <p> If you want to target different operating system from the host, you need @@ -757,9 +771,9 @@ bjam toolset=gcc-arm </p> <pre class="screen"> # On windows box -bjam toolset=gcc-arm <span class="bold"><strong>target-os=linux</strong></span> +b2 toolset=gcc-arm <span class="bold"><strong>target-os=linux</strong></span> # On Linux box -bjam toolset=gcc-mingw <span class="bold"><strong>target-os=windows</strong></span> +b2 toolset=gcc-mingw <span class="bold"><strong>target-os=windows</strong></span> </pre> <p> For the complete list of allowed opeating system names, please see the documentation for @@ -773,7 +787,7 @@ bjam toolset=gcc-mingw <span class="bold"><strong>target-os=windows</strong></sp </div> <div class="footnotes"> <br><hr width="100" align="left"> -<div class="footnote"><p><sup>[<a id="ftn.id3898939" href="#id3898939" class="para">12</a>] </sup>see the definition of "free" in <a class="xref" href="reference.html#bbv2.reference.features.attributes" title="Feature Attributes">the section called “Feature Attributes”</a>.</p></div> +<div class="footnote"><p><sup>[<a id="ftn.id3998650" href="#id3998650" class="para">12</a>] </sup>see the definition of "free" in <a class="xref" href="reference.html#bbv2.reference.features.attributes" title="Feature Attributes">the section called “Feature Attributes”</a>.</p></div> </div> </div> <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> diff --git a/doc/html/bbv2/tutorial.html b/doc/html/bbv2/tutorial.html index 7273c7eaf0..4a1fb9fd19 100755..100644 --- a/doc/html/bbv2/tutorial.html +++ b/doc/html/bbv2/tutorial.html @@ -49,30 +49,30 @@ </p> <pre class="programlisting"> -exe hello : hello.cpp ; +exe hello <span class="special">:</span> hello.cpp <span class="special">;</span> </pre> <p> Even with this simple setup, you can do some interesting things. First of - all, just invoking <span class="command"><strong>bjam</strong></span> will build the <code class="filename">hello + all, just invoking <span class="command"><strong>b2</strong></span> will build the <code class="filename">hello </code> executable by compiling and linking <code class="filename">hello.cpp - </code>. By default, debug variant is built. Now, to build the release + </code>. By default, the debug variant is built. Now, to build the release variant of <code class="filename">hello</code>, invoke </p> <pre class="screen"> -bjam release +b2 release </pre> <p> - Note that debug and release variants are created in different directories, + Note that the debug and release variants are created in different directories, so you can switch between variants or even build multiple variants at once, without any unnecessary recompilation. Let us extend the example by adding another line to our project's <code class="filename">Jamroot</code>: </p> <pre class="programlisting"> -exe hello2 : hello.cpp ; +exe hello2 <span class="special">:</span> hello.cpp <span class="special">;</span> </pre> <p> @@ -80,7 +80,7 @@ exe hello2 : hello.cpp ; </p> <pre class="screen"> -bjam debug release +b2 debug release </pre> <p> @@ -92,7 +92,7 @@ bjam debug release </p> <pre class="screen"> -bjam --clean debug release +b2 --clean debug release </pre> <p> @@ -102,8 +102,8 @@ bjam --clean debug release </p> <pre class="screen"> -bjam hello2 -bjam --clean hello2 +b2 hello2 +b2 --clean hello2 </pre> <p> </p> @@ -116,9 +116,9 @@ bjam --clean hello2 <dt><span class="section"><a href="tutorial.html#bbv2.tutorial.properties.project_attributes">Project Attributes</a></span></dt> </dl></div> <p> - To portably represent aspects of target configuration such as + To represent aspects of target configuration such as debug and release variants, or single- and multi-threaded - builds, Boost.Build uses <em class="firstterm">features</em> with + builds portably, Boost.Build uses <em class="firstterm">features</em> with associated <em class="firstterm">values</em>. For example, the <code class="computeroutput">debug-symbols</code> feature can have a value of <code class="computeroutput">on</code> or <code class="computeroutput">off</code>. A <em class="firstterm">property</em> is just a (feature, @@ -134,7 +134,7 @@ bjam --clean hello2 disabled and debug symbols enabled: </p> <pre class="screen"> -bjam release inlining=off debug-symbols=on +b2 release inlining=off debug-symbols=on </pre> <p> </p> @@ -149,20 +149,20 @@ bjam release inlining=off debug-symbols=on </p> <p> The <code class="option">release</code> and <code class="option">debug</code> that we have seen - in <span class="command"><strong>bjam</strong></span> invocations are just a shorthand way to specify + in <span class="command"><strong>b2</strong></span> invocations are just a shorthand way to specify values of the <code class="varname">variant</code> feature. For example, the command above could also have been written this way: </p> <pre class="screen"> -bjam variant=release inlining=off debug-symbols=on +b2 variant=release inlining=off debug-symbols=on </pre> <p> </p> <p> <code class="varname">variant</code> is so commonly-used that it has been given special status as an <em class="firstterm">implicit</em> feature— - Boost.Build will deduce the its identity just from the name of one of its + Boost.Build will deduce its identity just from the name of one of its values. </p> <p> @@ -172,7 +172,7 @@ bjam variant=release inlining=off debug-symbols=on <div class="titlepage"><div><div><h4 class="title"> <a name="bbv2.tutorial.properties.requirements"></a>Build Requests and Target Requirements</h4></div></div></div> <p> - The set of properties specified on the command line constitute + The set of properties specified on the command line constitutes a <em class="firstterm">build request</em>—a description of the desired properties for building the requested targets (or, if no targets were explicitly requested, the project in the @@ -192,18 +192,18 @@ bjam variant=release inlining=off debug-symbols=on </p> <pre class="programlisting"> exe hello - : hello.cpp - : <include>boost <threading>multi - ; + <span class="special">:</span> hello.cpp + <span class="special">:</span> <include>boost <threading>multi + <span class="special">;</span> </pre> <p> When <code class="filename">hello</code> is built, the two requirements specified above will always be present. If the build request given on the - <span class="command"><strong>bjam</strong></span> command-line explictly contradicts a target's + <span class="command"><strong>b2</strong></span> command-line explictly contradicts a target's requirements, the target requirements usually override (or, in the case of “free”” features like <code class="varname"><include></code>, - <sup>[<a name="id3892911" href="#ftn.id3892911" class="footnote">10</a>]</sup> + <sup>[<a name="id3992490" href="#ftn.id3992490" class="footnote">10</a>]</sup> augments) the build request. </p> <div class="tip"><table border="0" summary="Tip"> @@ -222,9 +222,10 @@ exe hello <div class="titlepage"><div><div><h4 class="title"> <a name="bbv2.tutorial.properties.project_attributes"></a>Project Attributes</h4></div></div></div> <p> - If we want the same requirements for our other target, <code class="filename">hello2 - </code>, we could simply duplicate them. However, as projects grow, - that approach leads to a great deal of repeated boilerplate in Jamfiles. + If we want the same requirements for our other target, + <code class="filename">hello2</code>, we could simply duplicate them. However, + as projects grow, that approach leads to a great deal of repeated + boilerplate in Jamfiles. Fortunately, there's a better way. Each project can specify a set of <em class="firstterm">attributes</em>, including requirements: @@ -232,11 +233,11 @@ exe hello </p> <pre class="programlisting"> project - : requirements <include>/home/ghost/Work/boost <threading>multi - ; + <span class="special">:</span> requirements <include>/home/ghost/Work/boost <threading>multi + <span class="special">;</span> -exe hello : hello.cpp ; -exe hello2 : hello.cpp ;</pre> +exe hello <span class="special">:</span> hello.cpp <span class="special">;</span> +exe hello2 <span class="special">:</span> hello.cpp <span class="special">;</span></pre> <p> The effect would be as if we specified the same requirement for both @@ -248,8 +249,8 @@ exe hello2 : hello.cpp ;</pre> <div class="titlepage"><div><div><h3 class="title"> <a name="bbv2.tutorial.hierarchy"></a>Project Hierarchies</h3></div></div></div> <p> - So far we have only considered examples with one project —a. with - one user-written Boost.Jam file, <code class="filename">Jamroot</code>). A typical + So far we have only considered examples with one project, with + one user-written Boost.Jam file, <code class="filename">Jamroot</code>. A typical large codebase would be composed of many projects organized into a tree. The top of the tree is called the <em class="firstterm">project root</em>. Every subproject is defined by a file called <code class="filename">Jamfile</code> @@ -314,12 +315,12 @@ top/ in its requirements, then all of its subprojects will have it in their requirements, too. Of course, any project can add - include paths to those specified by its parents. <sup>[<a name="id3893145" href="#ftn.id3893145" class="footnote">11</a>]</sup> + include paths to those specified by its parents. <sup>[<a name="id3992753" href="#ftn.id3992753" class="footnote">11</a>]</sup> More details can be found in <a class="xref" href="overview.html#bbv2.overview.projects" title="Projects">the section called “Projects”</a>. </p> <p> - Invoking <span class="command"><strong>bjam</strong></span> without explicitly specifying + Invoking <span class="command"><strong>b2</strong></span> without explicitly specifying any targets on the command line builds the project rooted in the current directory. Building a project does not automatically cause its subprojects to be built unless the parent project's @@ -328,7 +329,7 @@ top/ </p> <pre class="programlisting"> -build-project app ; +build-project app <span class="special">;</span> </pre> <p> @@ -343,7 +344,7 @@ build-project app ; <div class="titlepage"><div><div><h3 class="title"> <a name="bbv2.tutorial.libs"></a>Dependent Targets</h3></div></div></div> <p> - When a building a target <code class="filename">X</code> depends on first + When building a target <code class="filename">X</code> that depends on first building another target <code class="filename">Y</code> (such as a library that must be linked with <em class="firstterm">X</em>), <code class="filename">Y</code> is called a @@ -358,7 +359,7 @@ build-project app ; </p> <pre class="programlisting"> -lib bar : bar.cpp ; +lib bar <span class="special">:</span> bar.cpp <span class="special">;</span> </pre> <p> @@ -367,7 +368,7 @@ lib bar : bar.cpp ; </p> <pre class="programlisting"> -exe app : app.cpp ../util/foo//bar ; +exe app <span class="special">:</span> app.cpp ../util/foo//bar <span class="special">;</span> </pre> <p> @@ -389,7 +390,7 @@ exe app : app.cpp ../util/foo//bar ; <p>Suppose we build <code class="filename">app</code> with: </p> <pre class="screen"> -bjam app optimization=full define=USE_ASM +b2 app optimization=full define=USE_ASM </pre> <p> Which properties will be used to build <code class="computeroutput">foo</code>? The answer is @@ -405,19 +406,19 @@ bjam app optimization=full define=USE_ASM <p> Let's improve this project further. The library probably has some headers that must be used when compiling <code class="filename">app.cpp</code>. We could - manually add the necessary <code class="computeroutput">#include</code> paths to <code class="filename">app - </code>'s requirements as values of the <code class="varname"><include> - </code> feature, but then this work will be repeated for all programs - that use <code class="filename">foo</code>. A better solution is to modify - <code class="filename">util/foo/Jamfile</code> in this way: + manually add the necessary <code class="computeroutput">#include</code> paths to + <code class="filename">app</code>'s requirements as values of the + <code class="varname"><include> </code> feature, but then this work will be + repeated for all programs that use <code class="filename">foo</code>. A better + solution is to modify <code class="filename">util/foo/Jamfile</code> in this way: </p> <pre class="programlisting"> project - : usage-requirements <include>. - ; + <span class="special">:</span> usage-requirements <include>. + <span class="special">;</span> -lib foo : foo.cpp ;</pre> +lib foo <span class="special">:</span> foo.cpp <span class="special">;</span></pre> <p> Usage requirements are applied not to the target being declared but to its @@ -434,7 +435,7 @@ lib foo : foo.cpp ;</pre> code to <code class="filename">Jamroot</code>: </p> <pre class="programlisting"> -use-project /library-example/foo : util/foo ;</pre> +use-project /library-example/foo <span class="special">:</span> util/foo <span class="special">;</span></pre> <p> Second, we modify <code class="filename">app/Jamfile</code> to use the project id: </p> @@ -466,8 +467,8 @@ exe app : app.cpp /library-example/foo//bar ;</pre> </p> <pre class="programlisting"> project - : requirements <library>/boost/filesystem//fs - ;</pre> + <span class="special">:</span> requirements <library>/boost/filesystem//fs + <span class="special">;</span></pre> </td></tr> </table></div> </div> @@ -488,11 +489,11 @@ project be <code class="literal">static</code>. You can request a static build either on the command line: </p> -<pre class="programlisting">bjam link=static</pre> +<pre class="programlisting">b2 link=static</pre> <p> or in the library's requirements: </p> -<pre class="programlisting">lib l : l.cpp : <link>static ;</pre> +<pre class="programlisting">lib l <span class="special">:</span> l.cpp <span class="special">:</span> <link>static <span class="special">;</span></pre> <p> </p> <p> @@ -506,10 +507,10 @@ project </p> <pre class="programlisting"> -exe important : main.cpp helpers/<link>static ;</pre> +exe important <span class="special">:</span> main.cpp helpers/<link>static <span class="special">;</span></pre> <p> - No matter what arguments are specified on the <span class="command"><strong>bjam</strong></span> + No matter what arguments are specified on the <span class="command"><strong>b2</strong></span> command line, <code class="filename">important</code> will only be linked with the static version of <code class="filename">helpers</code>. </p> @@ -522,8 +523,8 @@ exe important : main.cpp helpers/<link>static ;</pre> </p> <pre class="programlisting"> -exe e1 : e1.cpp /other_project//bar/<link>static ; -exe e10 : e10.cpp /other_project//bar/<link>static ;</pre> +exe e1 <span class="special">:</span> e1.cpp /other_project//bar/<link>static <span class="special">;</span> +exe e10 <span class="special">:</span> e10.cpp /other_project//bar/<link>static <span class="special">;</span></pre> <p> but that's far from being convenient. A better approach is to introduce a @@ -537,9 +538,9 @@ exe e1 : e1.cpp foo ; exe e10 : e10.cpp foo ;</pre> <p> - The <a class="link" href="tasks.html#bbv2.tasks.alias" title="Alias"><code class="computeroutput">alias</code> - </a> rule is specifically used to rename a reference to a target and - possibly change the properties. + The <a class="link" href="tasks.html#bbv2.tasks.alias" title="Alias">alias</a> rule is specifically + used to rename a reference to a target and possibly change the + properties. </p> @@ -554,9 +555,9 @@ exe e10 : e10.cpp foo ;</pre> list of the first. For example: </p> <pre class="programlisting"> -lib utils : utils.cpp /boost/filesystem//fs ; -lib core : core.cpp utils ; -exe app : app.cpp core ;</pre> +lib utils <span class="special">:</span> utils.cpp /boost/filesystem//fs <span class="special">;</span> +lib core <span class="special">:</span> core.cpp utils <span class="special">;</span> +exe app <span class="special">:</span> app.cpp core <span class="special">;</span></pre> <p> This works no matter what kind of linking is used. When <code class="filename">core </code> is built as a shared library, it is linked directly into @@ -598,10 +599,10 @@ exe app : app.cpp core ;</pre> </p> <pre class="programlisting"> -lib network : network.cpp - : <span class="bold"><strong><link>shared:<define>NEWORK_LIB_SHARED</strong></span> +lib network <span class="special">:</span> network.cpp + <span class="special">:</span> <span class="bold"><strong><link>shared:<define>NEWORK_LIB_SHARED</strong></span> <variant>release:<define>EXTRA_FAST - ;</pre> + <span class="special">;</span></pre> <p> In the example above, whenever <code class="filename">network</code> is built with @@ -618,9 +619,9 @@ lib network : network.cpp alternatives</em>: </p> <pre class="programlisting"> -lib demangler : dummy_demangler.cpp ; # alternative 1 -lib demangler : demangler_gcc.cpp : <toolset>gcc ; # alternative 2 -lib demangler : demangler_msvc.cpp : <toolset>msvc ; # alternative 3</pre> +lib demangler <span class="special">:</span> dummy_demangler.cpp <span class="special">;</span> <span class="comment"># alternative 1</span> +lib demangler <span class="special">:</span> demangler_gcc.cpp <span class="special">:</span> <toolset>gcc <span class="special">;</span> <span class="comment"># alternative 2</span> +lib demangler <span class="special">:</span> demangler_msvc.cpp <span class="special">:</span> <toolset>msvc <span class="special">;</span> <span class="comment"># alternative 3</span></pre> <p> When building <code class="filename">demangler</code>, Boost.Build will compare requirements for each alternative with build properties to find the best @@ -641,16 +642,16 @@ lib demangler : demangler_msvc.cpp : <toolset>msvc ; # alternative 3</pre> example: </p> <pre class="programlisting"> -# util/lib2/Jamfile +<span class="comment"># util/lib2/Jamfile</span> lib lib2 - : - : <file>lib2_release.a <variant>release - ; + <span class="special">:</span> + <span class="special">:</span> <file>lib2_release.a <variant>release + <span class="special">;</span> lib lib2 - : - : <file>lib2_debug.a <variant>debug - ;</pre> + <span class="special">:</span> + <span class="special">:</span> <file>lib2_debug.a <variant>debug + <span class="special">;</span></pre> <p> This example defines two alternatives for <code class="filename">lib2</code>, and @@ -664,7 +665,7 @@ lib lib2 </p> <pre class="programlisting"> -exe app : app.cpp ../util/lib2//lib2 ;</pre> +exe app <span class="special">:</span> app.cpp ../util/lib2//lib2 <span class="special">;</span></pre> <p> As with any target, the alternative selected depends on the properties @@ -680,7 +681,7 @@ exe app : app.cpp ../util/lib2//lib2 ;</pre> </p> <pre class="programlisting"> -lib pythonlib : : <name>python22 ;</pre> +lib pythonlib <span class="special">:</span> <span class="special">:</span> <name>python22 <span class="special">;</span></pre> <p> We again don't specify any sources, but give a <code class="varname">name</code> @@ -694,15 +695,15 @@ lib pythonlib : : <name>python22 ;</pre> </p> <pre class="programlisting"> -lib pythonlib : : <name>python22 <search>/opt/lib ;</pre> +lib pythonlib <span class="special">:</span> <span class="special">:</span> <name>python22 <search>/opt/lib <span class="special">;</span></pre> <p> And, of course, target alternatives can be used in the usual way: </p> <pre class="programlisting"> -lib pythonlib : : <name>python22 <variant>release ; -lib pythonlib : : <name>python22_d <variant>debug ;</pre> +lib pythonlib <span class="special">:</span> <span class="special">:</span> <name>python22 <variant>release <span class="special">;</span> +lib pythonlib <span class="special">:</span> <span class="special">:</span> <name>python22_d <variant>debug <span class="special">;</span></pre> <p> </p> <p> @@ -711,10 +712,10 @@ lib pythonlib : : <name>python22_d <variant>debug ;</pre> </div> <div class="footnotes"> <br><hr width="100" align="left"> -<div class="footnote"><p><sup>[<a id="ftn.id3892911" href="#id3892911" class="para">10</a>] </sup> +<div class="footnote"><p><sup>[<a id="ftn.id3992490" href="#id3992490" class="para">10</a>] </sup> See <a class="xref" href="reference.html#bbv2.reference.features.attributes" title="Feature Attributes">the section called “Feature Attributes”</a> </p></div> -<div class="footnote"><p><sup>[<a id="ftn.id3893145" href="#id3893145" class="para">11</a>] </sup>Many +<div class="footnote"><p><sup>[<a id="ftn.id3992753" href="#id3992753" class="para">11</a>] </sup>Many features will be overridden, rather than added-to, in subprojects. See <a class="xref" href="reference.html#bbv2.reference.features.attributes" title="Feature Attributes">the section called “Feature Attributes”</a> for more information</p></div> |