| 1 | <html> |
|---|
| 2 | <head> |
|---|
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
|---|
| 4 | <title>The build layer</title> |
|---|
| 5 | <link rel="stylesheet" href="../../boostbook.css" type="text/css"> |
|---|
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.69.1"> |
|---|
| 7 | <style type="text/css"> |
|---|
| 8 | body { background-image: url('http://docbook.sourceforge.net/release/images/draft.png'); |
|---|
| 9 | background-repeat: no-repeat; |
|---|
| 10 | background-position: top left; |
|---|
| 11 | /* The following properties make the watermark "fixed" on the page. */ |
|---|
| 12 | /* I think that's just a bit too distracting for the reader... */ |
|---|
| 13 | /* background-attachment: fixed; */ |
|---|
| 14 | /* background-position: center center; */ |
|---|
| 15 | }</style> |
|---|
| 16 | <link rel="start" href="../../index.html" title="The Boost C++ Libraries"> |
|---|
| 17 | <link rel="up" href="../arch.html" title="Appendix B. Boost.Build v2 architecture"> |
|---|
| 18 | <link rel="prev" href="../arch.html" title="Appendix B. Boost.Build v2 architecture"> |
|---|
| 19 | <link rel="next" href="tools.html" title="The tools layer"> |
|---|
| 20 | </head> |
|---|
| 21 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
|---|
| 22 | <table cellpadding="2" width="100%"> |
|---|
| 23 | <td valign="top"><img alt="boost.png (6897 bytes)" width="277" height="86" src="../../../../boost.png"></td> |
|---|
| 24 | <td align="center"><a href="../../../../index.htm">Home</a></td> |
|---|
| 25 | <td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> |
|---|
| 26 | <td align="center"><a href="../../../../people/people.htm">People</a></td> |
|---|
| 27 | <td align="center"><a href="../../../../more/faq.htm">FAQ</a></td> |
|---|
| 28 | <td align="center"><a href="../../../../more/index.htm">More</a></td> |
|---|
| 29 | </table> |
|---|
| 30 | <hr> |
|---|
| 31 | <div class="spirit-nav"> |
|---|
| 32 | <a accesskey="p" href="../arch.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../arch.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="tools.html"><img src="../../images/next.png" alt="Next"></a> |
|---|
| 33 | </div> |
|---|
| 34 | <div class="section" lang="en"> |
|---|
| 35 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> |
|---|
| 36 | <a name="bbv2.arch.build"></a>The build layer</h2></div></div></div> |
|---|
| 37 | <div class="toc"><dl> |
|---|
| 38 | <dt><span class="section"><a href="build.html#bbv2.arch.metatargets">Metatargets</a></span></dt> |
|---|
| 39 | <dt><span class="section"><a href="build.html#bbv2.arch.virtual">Virtual targets</a></span></dt> |
|---|
| 40 | <dt><span class="section"><a href="build.html#bbv2.arch.properties"></a></span></dt> |
|---|
| 41 | </dl></div> |
|---|
| 42 | <p>The build layer has just four main parts -- metatargets (abstract targets), |
|---|
| 43 | virtual targets, generators and properties. |
|---|
| 44 | </p> |
|---|
| 45 | <div class="itemizedlist"><ul type="disc"> |
|---|
| 46 | <li><p>Metatargets (see the "targets.jam" module) represent |
|---|
| 47 | all the user-defined entities which can be built. The "meta" prefix |
|---|
| 48 | signify that they don't really corrspond to files -- depending of |
|---|
| 49 | build request, they can produce different set of |
|---|
| 50 | files. Metatargets are created when Jamfiles are loaded. Each |
|---|
| 51 | metagarget has a <code class="computeroutput">generate</code> method which is given a |
|---|
| 52 | property set and produces virtual targets for the passed properties. |
|---|
| 53 | </p></li> |
|---|
| 54 | <li><p>Virtual targets (see the "virtual-targets.jam" |
|---|
| 55 | module) correspond to the atomic things which can be updated -- |
|---|
| 56 | most typically files. |
|---|
| 57 | </p></li> |
|---|
| 58 | <li><p>Properties are just (name, value) pairs, specified |
|---|
| 59 | by the user and describing how the targets should be |
|---|
| 60 | built. Properties are stored using the <code class="computeroutput">property-set</code> class. |
|---|
| 61 | </p></li> |
|---|
| 62 | <li><p>Generators are the objects which encapsulate tools |
|---|
| 63 | -- they can take a list of source virtual targets and produce new |
|---|
| 64 | virtual targets from them. |
|---|
| 65 | </p></li> |
|---|
| 66 | </ul></div> |
|---|
| 67 | <p>The build process includes those steps: |
|---|
| 68 | </p> |
|---|
| 69 | <div class="orderedlist"><ol type="1"> |
|---|
| 70 | <li><p>Top-level code calls the <code class="computeroutput">generate</code> |
|---|
| 71 | method of a metatarget with some properties. </p></li> |
|---|
| 72 | <li><p>The metatarget combines the requested properties |
|---|
| 73 | with requirements and passes the result, together with the list |
|---|
| 74 | of sources, to the <code class="computeroutput">generators.construct</code> |
|---|
| 75 | function</p></li> |
|---|
| 76 | <li><p>A generator appropriate for the build properties is |
|---|
| 77 | selected and its <code class="computeroutput">run</code> method is |
|---|
| 78 | called. The method returns a list of virtual targets |
|---|
| 79 | </p></li> |
|---|
| 80 | <li><p>The targets are returned to the top level code. They |
|---|
| 81 | are converted into bjam targets (via |
|---|
| 82 | <code class="computeroutput">virtual-target.actualize</code>) and passed to bjam for building. |
|---|
| 83 | </p></li> |
|---|
| 84 | </ol></div> |
|---|
| 85 | <div class="section" lang="en"> |
|---|
| 86 | <div class="titlepage"><div><div><h3 class="title"> |
|---|
| 87 | <a name="bbv2.arch.metatargets"></a>Metatargets</h3></div></div></div> |
|---|
| 88 | <p>There are several classes derived from "abstract-target". The |
|---|
| 89 | "main-target" class represents top-level main target, the "project-target" |
|---|
| 90 | acts like container for all main targets, and "basic-target" class is a |
|---|
| 91 | base class for all further target types. |
|---|
| 92 | </p> |
|---|
| 93 | <p>Since each main target can have several alternatives, all top-level |
|---|
| 94 | target objects are just containers, referring to "real" main target |
|---|
| 95 | classes. The type is that container is "main-target". For example, given: |
|---|
| 96 | </p> |
|---|
| 97 | <pre class="programlisting"> |
|---|
| 98 | alias a ; |
|---|
| 99 | lib a : a.cpp : <toolset>gcc ; |
|---|
| 100 | </pre> |
|---|
| 101 | <p> |
|---|
| 102 | we would have one-top level instance of "main-target-class", which will |
|---|
| 103 | contain one instance of "alias-target-class" and one instance of |
|---|
| 104 | "lib-target-class". The "generate" method of "main-target" decides |
|---|
| 105 | which of the alternative should be used, and call "generate" on the |
|---|
| 106 | corresponding instance. |
|---|
| 107 | </p> |
|---|
| 108 | <p>Each alternative is a instance of a class derived from |
|---|
| 109 | "basic-target". The "basic-target.generate" does several things that are |
|---|
| 110 | always should be done: |
|---|
| 111 | </p> |
|---|
| 112 | <div class="itemizedlist"><ul type="disc"> |
|---|
| 113 | <li><p>Determines what properties should be used for building the |
|---|
| 114 | target. This includes looking at requested properties, requirements, |
|---|
| 115 | and usage requirements of all sources.</p></li> |
|---|
| 116 | <li><p>Builds all sources</p></li> |
|---|
| 117 | <li><p>Computes the usage requirements which should be passes back.</p></li> |
|---|
| 118 | </ul></div> |
|---|
| 119 | <p> |
|---|
| 120 | For the real work of constructing virtual target, a new method |
|---|
| 121 | "construct" is called. |
|---|
| 122 | </p> |
|---|
| 123 | <p>The "construct" method can be implemented in any way by classes |
|---|
| 124 | derived from "basic-target", but one specific derived class plays the |
|---|
| 125 | central role -- "typed-target". That class holds the desired type of file |
|---|
| 126 | to be produces, and calls the generators modules to do the job. |
|---|
| 127 | </p> |
|---|
| 128 | <p>This means that a specific metatarget subclass may avoid using |
|---|
| 129 | generators at all. However, this is deprecated and we're trying to |
|---|
| 130 | eliminate all such subsclasses at the moment. |
|---|
| 131 | </p> |
|---|
| 132 | <p>Note that the <code class="filename">build/targets.jam</code> file contains |
|---|
| 133 | an UML diagram which might help.</p> |
|---|
| 134 | </div> |
|---|
| 135 | <div class="section" lang="en"> |
|---|
| 136 | <div class="titlepage"><div><div><h3 class="title"> |
|---|
| 137 | <a name="bbv2.arch.virtual"></a>Virtual targets</h3></div></div></div> |
|---|
| 138 | <p>Virtual targets correspond to the atomic things which can be |
|---|
| 139 | updated. Each virtual target can be assigned an updating action -- |
|---|
| 140 | instance of the <code class="computeroutput">action</code> class. The action class, in |
|---|
| 141 | turn, contains a list of source targets, properties, and a name of |
|---|
| 142 | bjam action block which should be executed. |
|---|
| 143 | </p> |
|---|
| 144 | <p>We try hard to never create equal instances of the |
|---|
| 145 | <code class="computeroutput">virtual-target</code> class. Each code which creates virtual |
|---|
| 146 | targets passes them though the <code class="computeroutput">virtual-target.register</code> |
|---|
| 147 | function, which detects if a target with the same name, sources, and |
|---|
| 148 | properties was created. In that case, existing target is returned. |
|---|
| 149 | </p> |
|---|
| 150 | <p>When all virtual targets are produced, they are |
|---|
| 151 | "actualized". This means that the real file names are computed, and |
|---|
| 152 | the commands that should be run are generated. This is done by the |
|---|
| 153 | <code class="computeroutput">virtual-target.actualize</code> method and the |
|---|
| 154 | <code class="computeroutput">action.actualize</code> methods. The first is conceptually |
|---|
| 155 | simple, while the second need additional explanation. The commands |
|---|
| 156 | in bjam are generated in two-stage process. First, a rule with the |
|---|
| 157 | appropriate name (for example |
|---|
| 158 | "gcc.compile") is called and is given the names of targets. The rule |
|---|
| 159 | sets some variables, like "OPTIONS". After that, the command string |
|---|
| 160 | is taken, and variable are substitutes, so use of OPTIONS inside the |
|---|
| 161 | command string become the real compile options. |
|---|
| 162 | </p> |
|---|
| 163 | <p>Boost.Build added a third stage to simplify things. It's now |
|---|
| 164 | possible to automatically convert properties to appropriate assignments to |
|---|
| 165 | variables. For example, <debug-symbols>on would add "-g" to the |
|---|
| 166 | OPTIONS variable, without requiring to manually add this logic to |
|---|
| 167 | gcc.compile. This functionality is part of the "toolset" module. |
|---|
| 168 | </p> |
|---|
| 169 | <p>Note that the <code class="filename">build/virtual-targets.jam</code> file |
|---|
| 170 | contains an UML diagram which might help.</p> |
|---|
| 171 | </div> |
|---|
| 172 | <div class="section" lang="en"> |
|---|
| 173 | <div class="titlepage"></div> |
|---|
| 174 | <p>Above, we noted that metatargets are built with a set of |
|---|
| 175 | properties. That set is represented with the |
|---|
| 176 | <code class="computeroutput">property-set</code> class. An important point is that handling |
|---|
| 177 | of property sets can get very expensive. For that reason, we make |
|---|
| 178 | sure that for each set of (name, value) pairs only one |
|---|
| 179 | <code class="computeroutput">property-set</code> instance is created. The |
|---|
| 180 | <code class="computeroutput">property-set</code> uses extensive caching for all operation, |
|---|
| 181 | so most work is avoided. The <code class="computeroutput">property-set.create</code> is the |
|---|
| 182 | factory function which should be used to create instances of the |
|---|
| 183 | <code class="computeroutput">property-set</code> class. |
|---|
| 184 | </p> |
|---|
| 185 | </div> |
|---|
| 186 | </div> |
|---|
| 187 | <table width="100%"><tr> |
|---|
| 188 | <td align="left"></td> |
|---|
| 189 | <td align="right"><small></small></td> |
|---|
| 190 | </tr></table> |
|---|
| 191 | <hr> |
|---|
| 192 | <div class="spirit-nav"> |
|---|
| 193 | <a accesskey="p" href="../arch.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../arch.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="tools.html"><img src="../../images/next.png" alt="Next"></a> |
|---|
| 194 | </div> |
|---|
| 195 | </body> |
|---|
| 196 | </html> |
|---|
