| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> |
| <title>Extender Manual</title> |
| <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.75.2"> |
| <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> |
| <link rel="up" href="../bbv2.html" title="Chapter 33. Boost.Build V2 User Manual"> |
| <link rel="prev" href="reference.html" title="Reference"> |
| <link rel="next" href="faq.html" title="Frequently Asked Questions"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table cellpadding="2" width="100%"><tr> |
| <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> |
| <td align="center"><a href="../../../index.html">Home</a></td> |
| <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> |
| <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> |
| <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> |
| <td align="center"><a href="../../../more/index.htm">More</a></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <a accesskey="p" href="reference.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../bbv2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="faq.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> |
| <a name="bbv2.extender"></a>Extender Manual</h2></div></div></div> |
| <div class="toc"><dl> |
| <dt><span class="section"><a href="extender.html#bbv2.extender.intro">Introduction</a></span></dt> |
| <dt><span class="section"><a href="extender.html#bbv2.extender.example">Example: 1-to-1 generator</a></span></dt> |
| <dt><span class="section"><a href="extender.html#bbv2.extending.targets">Target types</a></span></dt> |
| <dt><span class="section"><a href="extender.html#bbv2.extending.tools">Tools and generators</a></span></dt> |
| <dt><span class="section"><a href="extender.html#bbv2.extending.features">Features</a></span></dt> |
| <dt><span class="section"><a href="extender.html#bbv2.extending.rules">Main target rules</a></span></dt> |
| <dt><span class="section"><a href="extender.html#bbv2.extending.toolset_modules">Toolset modules</a></span></dt> |
| </dl></div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.extender.intro"></a>Introduction</h3></div></div></div> |
| <div class="toc"><dl> |
| <dt><span class="section"><a href="extender.html#bbv2.extender.overview.metatargets">Metatargets</a></span></dt> |
| <dt><span class="section"><a href="extender.html#bbv2.extender.overview.targets">Concrete targets</a></span></dt> |
| <dt><span class="section"><a href="extender.html#bbv2.extender.overview.generators">Generators</a></span></dt> |
| </dl></div> |
| <p> |
| This section explains how to extend Boost.Build to accomodate your |
| local requirements—primarily to add support for non-standard |
| tools you have. Before we start, be sure you have read and understoon |
| the concept of metatarget, <a class="xref" href="overview.html#bbv2.overview.concepts" title="Concepts">the section called “Concepts”</a>, |
| which is critical to understanding the remaining material. |
| </p> |
| <p> |
| The current version of Boost.Build has three levels of targets, listed |
| below. |
| </p> |
| <div class="variablelist"><dl> |
| <dt><span class="term">metatarget</span></dt> |
| <dd><p> |
| Object that is created from declarations in Jamfiles. May |
| be called with a set of properties to produce concrete |
| targets. |
| </p></dd> |
| <dt><span class="term">concrete target</span></dt> |
| <dd><p> |
| Object that corresponds to a file or an action. |
| </p></dd> |
| <dt><span class="term">jam target</span></dt> |
| <dd><p> |
| Low-level concrete target that is specific to Boost.Jam build |
| engine. Essentially a string—most often a name of file. |
| </p></dd> |
| </dl></div> |
| <p> |
| In most cases, you will only have to deal with concrete targets and |
| the process that creates concrete targets from |
| metatargets. Extending metatarget level is rarely required. The jam |
| targets are typically only used inside the command line patterns. |
| </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>All of the Boost.Jam target-related builtin functions, like |
| <code class="computeroutput">DEPENDS</code> or <code class="computeroutput">ALWAYS</code> operate on jam |
| targets. Applying them to metatargets or concrete targets has no |
| effect.</p></td></tr> |
| </table></div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="bbv2.extender.overview.metatargets"></a>Metatargets</h4></div></div></div> |
| <p>Metatarget is an object that records information specified |
| 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="id3277625" href="#ftn.id3277625" class="footnote">14</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 |
| 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> |
| <li class="listitem"><p>As subsequent elements—created concrete targets ( |
| instances of the <code class="computeroutput">virtual-target</code> class.)</p></li> |
| </ul></div> |
| <p>It's possible to lookup a metataget by target-id using the |
| <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> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"><p><code class="computeroutput">project-target</code> that |
| corresponds to a project and is not intended for further |
| subclassing. The <code class="computeroutput">generate</code> 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 |
| 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 |
| 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. |
| </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 |
| 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>, |
| 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 |
| 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 |
| 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. |
| That rule creates new instance of type-target, associated with that type. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="bbv2.extender.overview.targets"></a>Concrete targets</h4></div></div></div> |
| <p>Concrete targets are represented by instance of classes derived |
| from <code class="computeroutput">virtual-target</code>. The most commonly used |
| 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> |
| <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) ] ; |
| local t = [ new file-target $(name) : CPP : $(project) : $(a) ] ; |
| </pre> |
| <p>The first line creates an instance of the <code class="computeroutput">action></code> class. |
| The first parameter is the list of sources. The second parameter is the name |
| a jam-level <a class="link" href="overview.html#bbv2.overview.jam_language.actions">action</a>. |
| The third parameter is the property-set applying to this action. The second line |
| creates a target. We specifie a name, a type and a project. We also pass the |
| action object created earlier. If the action creates several targets, we can repeat |
| the second line several times.</p> |
| <p>In some cases, code that creates concrete targets may be invoked more than |
| once with the same properties. Returning to different instance of <code class="computeroutput">file-target</code> |
| 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="id3277966" href="#ftn.id3277966" class="footnote">15</a>]</sup> |
| Here are a couple of examples: |
| </p> |
| <pre class="programlisting"> |
| return [ virtual-target.register $(t) ] ; |
| return [ sequence.transform virtual-target.register : $(targets) ] ; |
| </pre> |
| <p> |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="bbv2.extender.overview.generators"></a>Generators</h4></div></div></div> |
| <p>In theory, every kind of metatarget in Boost.Build (like <code class="computeroutput">exe</code>, |
| <code class="computeroutput">lib</code> or <code class="computeroutput">obj</code>) could be implemented |
| by writing a new metatarget class that, independently of the other code, figures |
| what files to produce and what commands to use. However, that would be rather inflexible. |
| For example, adding support for a new compiler would require editing several metatargets. |
| </p> |
| <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="id3278026"></a> |
| <em class="firstterm">generators</em>, and has special metatarget class |
| <code class="computeroutput">typed-target</code>. 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> |
| is associated with specific target type, and relays the generator (or generators) |
| for that type. |
| </p> |
| <p>A generator is an instance of a class derived from <code class="computeroutput">generator</code>. |
| The <code class="computeroutput">generator</code> class itself is suitable for common cases. |
| You can define derived classes for custom scenarios.</p> |
| </div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.extender.example"></a>Example: 1-to-1 generator</h3></div></div></div> |
| <p>Say you're writing an application that generates C++ code. If |
| you ever did this, you know that it's not nice. Embedding large |
| portions of C++ code in string literals is very awkward. A much |
| better solution is:</p> |
| <div class="orderedlist"><ol class="orderedlist" type="1"> |
| <li class="listitem"> |
| Write the template of the code to be generated, leaving |
| placeholders at the points that will change |
| </li> |
| <li class="listitem"> |
| Access the template in your application and replace |
| placeholders with appropriate text. |
| </li> |
| <li class="listitem">Write the result.</li> |
| </ol></div> |
| <p>It's quite easy to achieve. You write special verbatim files that are |
| just C++, except that the very first line of the file contains the name of a |
| variable that should be generated. A simple tool is created that takes a |
| verbatim file and creates a cpp file with a single <code class="computeroutput">char*</code> variable |
| whose name is taken from the first line of the verbatim file and whose value |
| is the file's properly quoted content.</p> |
| <p>Let's see what Boost.Build can do.</p> |
| <p>First off, Boost.Build has no idea about "verbatim files". So, you must |
| register a new target type. The following code does it:</p> |
| <pre class="programlisting"> |
| import type ; |
| type.register VERBATIM : verbatim ; |
| </pre> |
| <p>The first parameter to <code class="computeroutput">type.register</code> 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 |
| type <code class="computeroutput">VERBATIM</code>.</p> |
| <p>Next, you tell Boost.Build that the verbatim files can be |
| transformed into C++ files in one build step. A |
| <em class="firstterm">generator</em> is a template for a build step that |
| transforms targets of one type (or set of types) into another. Our |
| generator will be called <code class="computeroutput">verbatim.inline-file</code>; it |
| transforms <code class="computeroutput">VERBATIM</code> files into <code class="computeroutput">CPP</code> files: |
| |
| </p> |
| <pre class="programlisting"> |
| import generators ; |
| generators.register-standard verbatim.inline-file : VERBATIM : CPP ; |
| </pre> |
| <p> |
| </p> |
| <p>Lastly, you have to inform Boost.Build about the shell |
| commands used to make that transformation. That's done with an |
| <code class="computeroutput">actions</code> declaration. |
| |
| </p> |
| <pre class="programlisting"> |
| actions inline-file |
| { |
| "./inline-file.py" $(<) $(>) |
| } |
| </pre> |
| <p> |
| |
| |
| |
| |
| </p> |
| <p> |
| Now, we're ready to tie it all together. Put all the code above in file |
| <code class="filename">verbatim.jam</code>, add <code class="computeroutput">import verbatim ;</code> to |
| <code class="filename">Jamroot.jam</code>, and it's possible to write the following |
| in your Jamfile: |
| </p> |
| <pre class="programlisting"> |
| exe codegen : codegen.cpp class_template.verbatim usage.verbatim ; |
| </pre> |
| <p> |
| The listed verbatim files will be automatically converted into C++ source |
| files, compiled and then linked to the codegen executable. |
| </p> |
| <p> |
| In subsequent sections, we will extend this example, and review all the |
| mechanisms in detail. The complete code is available in the |
| <code class="filename">example/customization</code> directory. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.extending.targets"></a>Target types</h3></div></div></div> |
| <div class="toc"><dl><dt><span class="section"><a href="extender.html#bbv2.extending.scanners">Scanners</a></span></dt></dl></div> |
| <p>The first thing we did in the <a class="link" href="extender.html#bbv2.extender.intro" title="Introduction">intruduction</a> was declaring a |
| new target type: |
| </p> |
| <pre class="programlisting"> |
| import type ; |
| type.register VERBATIM : verbatim ; |
| </pre> |
| <p> |
| The type is the most important property of a target. Boost.Build can |
| automatically generate necessary build actions only because you |
| specify the desired type (using the different main target rules), and |
| because Boost.Build can guess the type of sources from their |
| extensions. |
| </p> |
| <p>The first two parameters for the <code class="computeroutput">type.register</code> rule |
| are the name of new type and the list of extensions associated with |
| it. A file with an extension from the list will have the given target |
| type. In the case where a target of the declared type is generated |
| from other sources, the first specified extension will be used. |
| </p> |
| <p>Sometimes you want to change the suffix used for generated targets |
| depending on build properties, such as toolset. For example, some compiler |
| uses extension <code class="literal">elf</code> for executable files. You can use the |
| <code class="computeroutput">type.set-generated-target-suffix</code> rule: |
| </p> |
| <pre class="programlisting"> |
| type.set-generated-target-suffix EXE : <toolset>elf : elf ; |
| </pre> |
| <p> |
| </p> |
| <p>A new target type can be inherited from an existing one. |
| </p> |
| <pre class="programlisting"> |
| type.register PLUGIN : : SHARED_LIB ; |
| </pre> |
| <p> |
| The above code defines a new type derived from |
| <code class="computeroutput">SHARED_LIB</code>. Initially, the new type inherits all the |
| properties of the base type - in particular generators and suffix. |
| Typically, you'll change the new type in some way. For example, using |
| <code class="computeroutput">type.set-generated-target-suffix</code> you can set the suffix for |
| the new type. Or you can write special a generator for the new type. For |
| example, it can generate additional metainformation for the plugin. |
| In either way, the <code class="computeroutput">PLUGIN</code> type can be used whenever |
| <code class="computeroutput">SHARED_LIB</code> can. For example, you can directly link plugins |
| to an application. |
| </p> |
| <p>A type can be defined as "main", in which case Boost.Build will |
| automatically declare a main target rule for building targets of that |
| type. More details can be found <a class="link" href="extender.html#bbv2.extending.rules.main-type">later</a>. |
| </p> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="bbv2.extending.scanners"></a>Scanners</h4></div></div></div> |
| <p> |
| Sometimes, a file can refer to other files via some include system. To |
| make Boost.Build track dependencies between included files, you need |
| to provide a scanner. The primary limitation is that only one scanner |
| can be assigned to a target type. |
| </p> |
| <p>First, we need to declare a new class for the scanner: |
| </p> |
| <pre class="programlisting"> |
| class verbatim-scanner : common-scanner |
| { |
| rule pattern ( ) |
| { |
| return "//###include[ ]*\"([^\"]*)\"" ; |
| } |
| } |
| </pre> |
| <p> |
| All the complex logic is in the <code class="computeroutput">common-scanner</code> |
| class, and you only need to override the method that returns |
| the regular expression to be used for scanning. The |
| parentheses in the regular expression indicate which part |
| of the string is the name of the included file. Only the |
| first parenthesized group in the regular expression will be |
| recognized; if you can't express everything you want that |
| way, you can return multiple regular expressions, each of |
| which contains a parenthesized group to be matched. |
| </p> |
| <p>After that, we need to register our scanner class: |
| </p> |
| <pre class="programlisting"> |
| scanner.register verbatim-scanner : include ; |
| </pre> |
| <p> |
| The value of the second parameter, in this case |
| <code class="computeroutput">include</code>, specifies the properties that contain the list |
| of paths that should be searched for the included files. |
| </p> |
| <p>Finally, we assign the new scanner to the <code class="computeroutput">VERBATIM</code> |
| target type: |
| </p> |
| <pre class="programlisting"> |
| type.set-scanner VERBATIM : verbatim-scanner ; |
| </pre> |
| <p> |
| That's enough for scanning include dependencies. |
| </p> |
| </div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.extending.tools"></a>Tools and generators</h3></div></div></div> |
| <p> |
| This section will describe how Boost.Build can be extended to support |
| new tools. |
| </p> |
| <p>For each additional tool, a Boost.Build object called generator |
| must be created. That object has specific types of targets that it |
| accepts and produces. Using that information, Boost.Build is able |
| to automatically invoke the generator. For example, if you declare a |
| generator that takes a target of the type <code class="literal">D</code> and |
| produces a target of the type <code class="literal">OBJ</code>, when placing a |
| file with extention <code class="literal">.d</code> in a list of sources will |
| cause Boost.Build to invoke your generator, and then to link the |
| resulting object file into an application. (Of course, this requires |
| that you specify that the <code class="literal">.d</code> extension corresponds |
| to the <code class="literal">D</code> type.) |
| </p> |
| <p>Each generator should be an instance of a class derived from the |
| <code class="computeroutput">generator</code> class. In the simplest case, you don't need to |
| create a derived class, but simply create an instance of the |
| <code class="computeroutput">generator</code> class. Let's review the example we've seen in the |
| <a class="link" href="extender.html#bbv2.extender.intro" title="Introduction">introduction</a>. |
| |
| </p> |
| <pre class="programlisting"> |
| import generators ; |
| generators.register-standard verbatim.inline-file : VERBATIM : CPP ; |
| actions inline-file |
| { |
| "./inline-file.py" $(<) $(>) |
| } |
| </pre> |
| <p> |
| </p> |
| <p>We declare a standard generator, specifying its id, the source type |
| and the target type. When invoked, the generator will create a target |
| of type <code class="literal">CPP</code> with a source target of |
| type <code class="literal">VERBATIM</code> as the only source. But what command |
| will be used to actually generate the file? In bjam, actions are |
| specified using named "actions" blocks and the name of the action |
| block should be specified when creating targets. By convention, |
| generators use the same name of the action block as their own id. So, |
| in above example, the "inline-file" actions block will be used to |
| convert the source into the target. |
| </p> |
| <p> |
| There are two primary kinds of generators: standard and composing, |
| which are registered with the |
| <code class="computeroutput">generators.register-standard</code> and the |
| <code class="computeroutput">generators.register-composing</code> rules, respectively. For |
| example: |
| </p> |
| <pre class="programlisting"> |
| generators.register-standard verbatim.inline-file : VERBATIM : CPP ; |
| generators.register-composing mex.mex : CPP LIB : MEX ; |
| </pre> |
| <p> |
| The first (standard) generator takes a <span class="emphasis"><em>single</em></span> |
| source of type <code class="computeroutput">VERBATIM</code> and produces a result. The second |
| (composing) generator takes any number of sources, which can have either |
| the <code class="computeroutput">CPP</code> or the <code class="computeroutput">LIB</code> type. Composing generators |
| are typically used for generating top-level target type. For example, |
| the first generator invoked when building an <code class="computeroutput">exe</code> target is |
| a composing generator corresponding to the proper linker. |
| </p> |
| <p>You should also know about two specific functions for registering |
| generators: <code class="computeroutput">generators.register-c-compiler</code> and |
| <code class="computeroutput">generators.register-linker</code>. The first sets up header |
| dependecy scanning for C files, and the seconds handles various |
| complexities like searched libraries. For that reason, you should always |
| use those functions when adding support for compilers and linkers. |
| </p> |
| <p>(Need a note about UNIX)</p> |
| <h4> |
| <a name="id3278703"></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, |
| |
| you need to create a new generator class with your own logic. Then, |
| you have to create an instance of that class and register it. Here's |
| an example how you can create your own generator class: |
| </p> |
| <pre class="programlisting"> |
| class custom-generator : generator |
| { |
| rule __init__ ( * : * ) |
| { |
| generator.__init__ $(1) : $(2) : $(3) : $(4) : $(5) : $(6) : $(7) : $(8) : $(9) ; |
| } |
| |
| } |
| |
| generators.register |
| [ new custom-generator verbatim.inline-file : VERBATIM : CPP ] ; |
| </pre> |
| <p> |
| This generator will work exactly like the |
| <code class="computeroutput">verbatim.inline-file</code> generator we've defined above, but |
| it's possible to customize the behaviour by overriding methods of the |
| <code class="computeroutput">generator</code> class. |
| </p> |
| <p>There are two methods of interest. The <code class="computeroutput">run</code> method is |
| responsible for the overall process - it takes a number of source targets, |
| converts them to the right types, and creates the result. The |
| <code class="computeroutput">generated-targets</code> method is called when all sources are |
| converted to the right types to actually create the result. |
| </p> |
| <p>The <code class="computeroutput">generated-targets</code> method can be overridden when you |
| want to add additional properties to the generated targets or use |
| additional sources. For a real-life example, suppose you have a program |
| analysis tool that should be given a name of executable and the list of |
| all sources. Naturally, you don't want to list all source files |
| manually. Here's how the <code class="computeroutput">generated-targets</code> method can find |
| the list of sources automatically: |
| </p> |
| <pre class="programlisting"> |
| class itrace-generator : generator { |
| .... |
| rule generated-targets ( sources + : property-set : project name ? ) |
| { |
| local leaves ; |
| local temp = [ virtual-target.traverse $(sources[1]) : : include-sources ] ; |
| for local t in $(temp) |
| { |
| if ! [ $(t).action ] |
| { |
| leaves += $(t) ; |
| } |
| } |
| return [ generator.generated-targets $(sources) $(leafs) |
| : $(property-set) : $(project) $(name) ] ; |
| } |
| } |
| generators.register [ new itrace-generator nm.itrace : EXE : ITRACE ] ; |
| </pre> |
| <p> |
| The <code class="computeroutput">generated-targets</code> method will be called with a single |
| source target of type <code class="literal">EXE</code>. The call to |
| <code class="computeroutput">virtual-target.traverse</code> will return all targets the |
| executable depends on, and we further find files that are not |
| produced from anything. |
| The found targets are added to the sources. |
| </p> |
| <p>The <code class="computeroutput">run</code> method can be overriden to completely |
| customize the way the generator works. In particular, the conversion of |
| sources to the desired types can be completely customized. Here's |
| another real example. Tests for the Boost Python library usually |
| consist of two parts: a Python program and a C++ file. The C++ file is |
| compiled to Python extension that is loaded by the Python |
| program. But in the likely case that both files have the same name, |
| the created Python extension must be renamed. Otherwise, the Python |
| program will import itself, not the extension. Here's how it can be |
| done: |
| </p> |
| <pre class="programlisting"> |
| rule run ( project name ? : property-set : sources * ) |
| { |
| local python ; |
| for local s in $(sources) |
| { |
| if [ $(s).type ] = PY |
| { |
| python = $(s) ; |
| } |
| } |
| |
| local libs ; |
| for local s in $(sources) |
| { |
| if [ type.is-derived [ $(s).type ] LIB ] |
| { |
| libs += $(s) ; |
| } |
| } |
| |
| local new-sources ; |
| for local s in $(sources) |
| { |
| if [ type.is-derived [ $(s).type ] CPP ] |
| { |
| local name = [ $(s).name ] ; # get the target's basename |
| if $(name) = [ $(python).name ] |
| { |
| name = $(name)_ext ; # rename the target |
| } |
| new-sources += [ generators.construct $(project) $(name) : |
| PYTHON_EXTENSION : $(property-set) : $(s) $(libs) ] ; |
| } |
| } |
| |
| result = [ construct-result $(python) $(new-sources) : $(project) $(name) |
| : $(property-set) ] ; |
| } |
| </pre> |
| <p> |
| |
| |
| First, we separate all source into python files, libraries and C++ |
| sources. For each C++ source we create a separate Python extension by |
| calling <code class="computeroutput">generators.construct</code> and passing the C++ source |
| and the libraries. At this point, we also change the extension's name, |
| if necessary. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.extending.features"></a>Features</h3></div></div></div> |
| <p> |
| Often, we need to control the options passed the invoked tools. This |
| is done with features. Consider an example: |
| </p> |
| <pre class="programlisting"> |
| # Declare a new free feature |
| import feature : feature ; |
| feature verbatim-options : : free ; |
| |
| # Cause the value of the 'verbatim-options' feature to be |
| # available as 'OPTIONS' variable inside verbatim.inline-file |
| import toolset : flags ; |
| flags verbatim.inline-file OPTIONS <verbatim-options> ; |
| |
| # Use the "OPTIONS" variable |
| actions inline-file |
| { |
| "./inline-file.py" $(OPTIONS) $(<) $(>) |
| } |
| </pre> |
| <p> |
| We first define a new feature. Then, the <code class="computeroutput">flags</code> invocation |
| says that whenever verbatin.inline-file action is run, the value of |
| the <code class="computeroutput">verbatim-options</code> feature will be added to the |
| <code class="computeroutput">OPTIONS</code> variable, and can be used inside the action body. |
| You'd need to consult online help (--help) to find all the features of |
| the <code class="computeroutput">toolset.flags</code> rule. |
| |
| </p> |
| <p> |
| Although you can define any set of features and interpret their values |
| in any way, Boost.Build suggests the following coding standard for |
| designing features. |
| </p> |
| <p>Most features should have a fixed set of values that is portable |
| (tool neutral) across the class of tools they are designed to work |
| with. The user does not have to adjust the values for a exact tool. For |
| example, <code class="computeroutput"><optimization>speed</code> has the same meaning for |
| all C++ compilers and the user does not have to worry about the exact |
| options passed to the compiler's command line. |
| </p> |
| <p> |
| Besides such portable features there are special 'raw' features that |
| allow the user to pass any value to the command line parameters for a |
| particular tool, if so desired. For example, the |
| <code class="computeroutput"><cxxflags></code> feature allows you to pass any command line |
| options to a C++ compiler. The <code class="computeroutput"><include></code> feature |
| allows you to pass any string preceded by <code class="computeroutput">-I</code> and the interpretation |
| is tool-specific. (See <a class="xref" href="faq.html#bbv2.faq.external" title="Can I get capture external program output using a Boost.Jam variable?">the section called “ |
| Can I get capture external program output using a Boost.Jam variable? |
| ”</a> for an example of very smart usage of that |
| feature). Of course one should always strive to use portable |
| features, but these are still be provided as a backdoor just to make |
| sure Boost.Build does not take away any control from the user. |
| </p> |
| <p> |
| Using portable features is a good idea because: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"><p>When a portable feature is given a fixed set of |
| values, you can build your project with two different |
| settings of the feature and Boost.Build will automatically |
| use two different directories for generated files. |
| Boost.Build does not try to separate targets built with |
| different raw options. |
| |
| </p></li> |
| <li class="listitem"><p>Unlike with “raw” features, you don't need to use |
| specific command-line flags in your Jamfile, and it will be |
| more likely to work with other tools. |
| </p></li> |
| </ul></div> |
| <p> |
| </p> |
| <h4> |
| <a name="id3278985"></a>Steps for adding a feauture</h4> |
| <p>Adding a feature requires three steps: |
| |
| </p> |
| <div class="orderedlist"><ol class="orderedlist" type="1"> |
| <li class="listitem"> |
| <p>Declaring a feature. For that, the "feature.feature" |
| rule is used. You have to decide on the set of <a class="link" href="reference.html#bbv2.reference.features.attributes" title="Feature Attributes">feature |
| attributes</a>: |
| |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"><p>if you want a feature value set for one target |
| to automaticaly propagate to its dependant targets then make it |
| “propagated”. </p></li> |
| <li class="listitem"><p>if a feature does not have a fixed list of |
| values, it must be “free.” For example, the <code class="computeroutput">include |
| </code> feature is a free feature.</p></li> |
| <li class="listitem"><p>if a feature is used to refer to a path relative |
| to the Jamfile, it must be a “path” feature. Such features will |
| also get their values automatically converted to Boost Build's |
| internal path representation. For example, <code class="computeroutput">include</code> |
| is a path feature.</p></li> |
| <li class="listitem"><p>if feature is used to refer to some target, it |
| must be a “dependency” feature. </p></li> |
| </ul></div> |
| <p> |
| </p> |
| </li> |
| <li class="listitem"><p>Representing the feature value in a |
| target-specific variable. Build actions are command |
| templates modified by Boost.Jam variable expansions. The |
| <code class="computeroutput">toolset.flags</code> rule sets a target-specific |
| variable to the value of a feature.</p></li> |
| <li class="listitem"><p>Using the variable. The variable set in step 2 can |
| be used in a build action to form command parameters or |
| files.</p></li> |
| </ol></div> |
| <p> |
| </p> |
| <h4> |
| <a name="id3279084"></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 |
| specify a "DEF file", telling what functions should be exported. It |
| would be nice to use this file like this: |
| </p> |
| <pre class="programlisting"> |
| lib a : a.cpp : <def-file>a.def ; |
| </pre> |
| <p> |
| |
| Actually, this feature is already supported, but anyway... |
| |
| </p> |
| <div class="orderedlist"><ol class="orderedlist" type="1"> |
| <li class="listitem"> |
| <p>Since the feature refers to a target, it must be "dependency". |
| </p> |
| <pre class="programlisting"> |
| feature def-file : : free dependency ; |
| </pre> |
| <p> |
| </p> |
| </li> |
| <li class="listitem"> |
| <p>One of the toolsets that cares about |
| |
| DEF files is msvc. The following line should be added to it. |
| |
| |
| </p> |
| <pre class="programlisting"> |
| flags msvc.link DEF_FILE <def-file> ; |
| </pre> |
| <p> |
| |
| </p> |
| </li> |
| <li class="listitem"> |
| <p>Since the DEF_FILE variable is not used by the |
| msvc.link action, |
| |
| we need to modify it to be: |
| |
| </p> |
| <pre class="programlisting"> |
| actions link bind DEF_FILE |
| { |
| $(.LD) .... /DEF:$(DEF_FILE) .... |
| } |
| </pre> |
| <p> |
| </p> |
| <p> Note the <code class="computeroutput">bind DEF_FILE</code> part. It tells |
| bjam to translate the internal target name in |
| <code class="varname">DEF_FILE</code> to a corresponding filename in |
| the <code class="computeroutput">link</code> action. Without it the expansion of |
| <code class="computeroutput">$(DEF_FILE)</code> would be a strange symbol that is |
| not likely to make sense for the linker. |
| </p> |
| <p> |
| We are almost done, but we should stop for a small workaround. Add the following |
| code to msvc.jam |
| |
| </p> |
| <pre class="programlisting"> |
| rule link |
| { |
| DEPENDS $(<) : [ on $(<) return $(DEF_FILE) ] ; |
| } |
| </pre> |
| <p> |
| |
| |
| This is needed to accomodate some bug in bjam, which hopefully |
| will be fixed one day. |
| |
| </p> |
| </li> |
| </ol></div> |
| <h4> |
| <a name="id3279196"></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. |
| </p> |
| <p>It is possible to define your own build variants. For example: |
| </p> |
| <pre class="programlisting"> |
| variant crazy : <optimization>speed <inlining>off |
| <debug-symbols>on <profiling>on ; |
| </pre> |
| <p> |
| will define a new variant with the specified set of properties. You |
| can also extend an existing variant: |
| </p> |
| <pre class="programlisting"> |
| variant super_release : release : <define>USE_ASM ; |
| </pre> |
| <p> |
| In this case, <code class="computeroutput">super_release</code> will expand to all properties |
| specified by <code class="computeroutput">release</code>, and the additional one you've specified. |
| </p> |
| <p>You are not restricted to using the <code class="computeroutput">variant</code> feature |
| only. |
| |
| Here's example that defines a brand new feature: |
| </p> |
| <pre class="programlisting"> |
| feature parallelism : mpi fake none : composite link-incompatible ; |
| feature.compose <parallelism>mpi : <library>/mpi//mpi/<parallelism>none ; |
| feature.compose <parallelism>fake : <library>/mpi//fake/<parallelism>none ; |
| </pre> |
| <p> |
| |
| This will allow you to specify the value of feature |
| <code class="computeroutput">parallelism</code>, which will expand to link to the necessary |
| library. |
| </p> |
| </div> |
| <div class="section"> |
| <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 |
| there are two ways to do that. |
| |
| </p> |
| <p><a name="bbv2.extending.rules.main-type"></a>The first way applies when |
| |
| your target rule should just produce a target of specific type. In that case, a |
| rule is already defined for you! When you define a new type, Boost.Build |
| automatically defines a corresponding rule. The name of the rule is |
| obtained from the name of the type, by downcasing all letters and |
| replacing underscores with dashes. |
| |
| For example, if you create a module |
| <code class="filename">obfuscate.jam</code> containing: |
| |
| </p> |
| <pre class="programlisting"> |
| import type ; |
| type.register OBFUSCATED_CPP : ocpp ; |
| |
| import generators ; |
| generators.register-standard obfuscate.file : CPP : OBFUSCATED_CPP ; |
| </pre> |
| <p> |
| and import that module, you'll be able to use the rule "obfuscated-cpp" |
| in Jamfiles, which will convert source to the OBFUSCATED_CPP type. |
| </p> |
| <p> |
| The second way is to write a wrapper rule that calls any of the existing |
| rules. For example, suppose you have only one library per directory and |
| want all cpp files in the directory to be compiled into that library. You |
| can achieve this effect using: |
| </p> |
| <pre class="programlisting"> |
| lib codegen : [ glob *.cpp ] ; |
| </pre> |
| <p> |
| If you want to make it even simpler, you could add the following |
| definition to the <code class="filename">Jamroot.jam</code> file: |
| </p> |
| <pre class="programlisting"> |
| rule glib ( name : extra-sources * : requirements * ) |
| { |
| lib $(name) : [ glob *.cpp ] $(extra-sources) : $(requirements) ; |
| } |
| </pre> |
| <p> |
| allowing you to reduce the Jamfile to just |
| </p> |
| <pre class="programlisting"> |
| glib codegen ; |
| </pre> |
| <p> |
| </p> |
| <p> |
| Note that because you can associate a custom generator with a target type, |
| the logic of building can be rather complicated. For example, the |
| <code class="computeroutput">boostbook</code> module declares a target type |
| <code class="computeroutput">BOOSTBOOK_MAIN</code> and a custom generator for that type. You can |
| use that as example if your main target rule is non-trivial. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.extending.toolset_modules"></a>Toolset modules</h3></div></div></div> |
| <p> |
| If your extensions will be used only on one project, they can be placed in |
| a separate <code class="filename">.jam</code> file and imported by your |
| <code class="filename">Jamroot.jam</code>. If the extensions will be used on many |
| projects, users will thank you for a finishing touch. |
| </p> |
| <p>The <code class="computeroutput">using</code> rule provides a standard mechanism |
| for loading and configuring extensions. To make it work, your module |
| |
| should provide an <code class="computeroutput">init</code> rule. The rule will be called |
| with the same parameters that were passed to the |
| <code class="computeroutput">using</code> rule. The set of allowed parameters is |
| determined by you. For example, you can allow the user to specify |
| paths, tool versions, and other options. |
| |
| </p> |
| <p>Here are some guidelines that help to make Boost.Build more |
| consistent: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"><p>The <code class="computeroutput">init</code> rule should never fail. Even if |
| the user provided an incorrect path, you should emit a warning and go |
| on. Configuration may be shared between different machines, and |
| wrong values on one machine can be OK on another. |
| |
| </p></li> |
| <li class="listitem"> |
| <p>Prefer specifying the command to be executed |
| to specifying the tool's installation path. First of all, this |
| gives more control: it's possible to specify |
| </p> |
| <pre class="programlisting"> |
| /usr/bin/g++-snapshot |
| time g++ |
| |
| </pre> |
| <p> |
| as the command. Second, while some tools have a logical |
| "installation root", it's better if the user doesn't have to remember whether |
| a specific tool requires a full command or a path. |
| |
| </p> |
| </li> |
| <li class="listitem"> |
| <p>Check for multiple initialization. A user can try to |
| initialize the module several times. You need to check for this |
| and decide what to do. Typically, unless you support several |
| versions of a tool, duplicate initialization is a user error. |
| |
| If the |
| tool's version can be specified during initialization, make sure the |
| version is either always specified, or never specified (in which |
| case the tool is initialied only once). For example, if you allow: |
| </p> |
| <pre class="programlisting"> |
| using yfc ; |
| using yfc : 3.3 ; |
| using yfc : 3.4 ; |
| </pre> |
| <p> |
| Then it's not clear if the first initialization corresponds to |
| version 3.3 of the tool, version 3.4 of the tool, or some other |
| version. This can lead to building twice with the same version. |
| |
| </p> |
| </li> |
| <li class="listitem"> |
| <p>If possible, <code class="computeroutput">init</code> must be callable |
| with no parameters. In which case, it should try to autodetect all |
| the necessary information, for example, by looking for a tool in |
| <code class="envar">PATH</code> or in common installation locations. Often this |
| is possible and allows the user to simply write: |
| </p> |
| <pre class="programlisting"> |
| using yfc ; |
| </pre> |
| <p> |
| </p> |
| </li> |
| <li class="listitem"><p>Consider using facilities in the |
| <code class="computeroutput">tools/common</code> module. You can take a look at how |
| <code class="computeroutput">tools/gcc.jam</code> uses that module in the <code class="computeroutput">init</code> rule. |
| </p></li> |
| </ul></div> |
| <p> |
| </p> |
| </div> |
| <div class="footnotes"> |
| <br><hr width="100" align="left"> |
| <div class="footnote"><p><sup>[<a name="ftn.id3277625" href="#id3277625" class="para">14</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 name="ftn.id3277966" href="#id3277966" class="para">15</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> |
| <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> |
| <td align="left"></td> |
| <td align="right"><div class="copyright-footer">Copyright © 2006-2009 Vladimir Prus<p>Distributed under the Boost Software License, Version 1.0. |
| (See accompanying file <code class="filename">LICENSE_1_0.txt</code> or copy at |
| <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) |
| </p> |
| </div></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <a accesskey="p" href="reference.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../bbv2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="faq.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> |
| </div> |
| </body> |
| </html> |