diff options
Diffstat (limited to 'doc/html/bbv2/extender.html')
-rw-r--r--[-rwxr-xr-x] | doc/html/bbv2/extender.html | 89 |
1 files changed, 49 insertions, 40 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> |