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