Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/doc/html/bbv2/reference/generators.html @ 12

Last change on this file since 12 was 12, checked in by landauf, 18 years ago

added boost
File size: 10.8 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Generators</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">
8body { 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="../reference.html" title="Chapter 26. Detailed reference">
18<link rel="prev" href="definitions.html" title="Definitions">
19<link rel="next" href="../faq.html" title="Chapter 27. Frequently Asked Questions">
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="definitions.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="../faq.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.reference.generators"></a>Generators</h2></div></div></div>
37<div class="toc"><dl>
38<dt><span class="section"><a href="generators.html#id2861414">Selecting and ranking viable generators</a></span></dt>
39<dt><span class="section"><a href="generators.html#id2861462">Running generators</a></span></dt>
40<dt><span class="section"><a href="generators.html#id2861501">Selecting dependency graph</a></span></dt>
41<dt><span class="section"><a href="generators.html#id2861512">Property adjustment</a></span></dt>
42<dt><span class="section"><a href="generators.html#id2861573">Transformations cache</a></span></dt>
43</dl></div>
44<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
45<h3 class="title">Warning</h3>
46<p>The information is this section is likely to be outdated
47        and misleading.
48      </p>
49</div>
50<p>To construct a main target with given properties from sources,
51      it is required to create a dependency graph for that main target,
52      which will also include actions to be run. The algorithm for
53      creating the dependency graph is described here.</p>
54<p>The fundamental concept is <span class="emphasis"><em>generator</em></span>. If encapsulates
55      the notion of build tool and is capable to converting a set of
56      input targets into a set of output targets, with some properties.
57      Generator matches a build tool as closely as possible: it works
58      only when the tool can work with requested properties (for
59      example, msvc compiler can't work when requested toolset is gcc),
60      and should produce exactly the same targets as the tool (for
61      example, if Borland's linker produces additional files with debug
62      information, generator should also).</p>
63<p>Given a set of generators, the fundamental operation is to
64      construct a target of a given type, with given properties, from a
65      set of targets. That operation is performed by rule
66      <code class="literal">generators.construct</code> and the used algorithm is described
67      below.</p>
68<div class="section" lang="en">
69<div class="titlepage"><div><div><h3 class="title">
70<a name="id2861414"></a>Selecting and ranking viable generators</h3></div></div></div>
71<p>Each generator, in addition to target types that it can
72        produce, have attribute that affects its applicability in
73        particular sitiation. Those attributes are:</p>
74<div class="orderedlist"><ol type="1">
75<li>
76            Required properties, which are properties absolutely
77            necessary for the generator to work. For example, generator
78            encapsulating the gcc compiler would have &lt;toolset&gt;gcc as
79            required property.
80          </li>
81<li>
82            Optional properties, which increase the generators
83            suitability for a particual build.
84          </li>
85</ol></div>
86<p>
87        Generator's required and optional properties may not include
88        either free or incidental properties. (Allowing this would
89        greatly complicate caching targets).
90      </p>
91<p>When trying to construct a target, the first step is to select
92        all possible generators for the requested target type, which
93        required properties are a subset of requested properties.
94        Generators that were already selected up the call stack are
95        excluded. In addition, if any composing generators were selected
96        up the call stack, all other composing generators are ignored
97        (TODO: define composing generators). The found generators
98        are assigned a rank, which is the number of optional properties
99        present in requested properties. Finally, generators with highest
100        rank are selected for futher processing.</p>
101</div>
102<div class="section" lang="en">
103<div class="titlepage"><div><div><h3 class="title">
104<a name="id2861462"></a>Running generators</h3></div></div></div>
105<p>When generators are selected, each is run to produce a list of
106        created targets. This list might include targets that are not of
107        requested types, because generators create the same targets as
108        some tool, and tool's behaviour is fixed. (Note: should specify
109        that in some cases we actually want extra targets). If generator
110        fails, it returns an empty list. Generator is free to call
111        'construct' again, to convert sources to the types it can handle.
112        It also can pass modified properties to 'construct'. However, a
113        generator is not allowed to modify any propagated properties,
114        otherwise when actually consuming properties we might discover
115        that the set of propagated properties is different from what was
116        used for building sources.</p>
117<p>For all targets that are not of requested types, we try to
118        convert them to requested type, using a second call to
119        <code class="literal">construct</code>. This is done in order to support
120        transformation sequences where single source file expands to
121        several later. See <a href="http://groups.yahoo.com/group/jamboost/message/1667" target="_top">this
122          message</a> for details.</p>
123</div>
124<div class="section" lang="en">
125<div class="titlepage"><div><div><h3 class="title">
126<a name="id2861501"></a>Selecting dependency graph</h3></div></div></div>
127<p>
128        After all generators are run,
129        it is necessary to decide which of successfull invocation will be
130        taken as final result. At the moment, this is not done. Instead,
131        it is checked whether all successfull generator invocation
132        returned the same target list. Error is issued otherwise.
133      </p>
134</div>
135<div class="section" lang="en">
136<div class="titlepage"><div><div><h3 class="title">
137<a name="id2861512"></a>Property adjustment</h3></div></div></div>
138<p>Because target location is determined by the build system, it
139        is sometimes necessary to adjust properties, in order to not
140        break actions. For example, if there's an action that generates
141        a header, say "a_parser.h", and a source file "a.cpp" which
142        includes that file, we must make everything work as if a_parser.h
143        is generated in the same directory where it would be generated
144        without any subvariants.</p>
145<p>Correct property adjustment can be done only after all targets
146        are created, so the approach taken is:</p>
147<div class="orderedlist"><ol type="1">
148<li><p>
149            When dependency graph is constructed, each action can be
150            assigned a rule for property adjustment.
151          </p></li>
152<li><p>
153            When virtual target is actualized, that rule is run and
154            return the final set of properties. At this stage it can use
155            information of all created virtual targets.
156          </p></li>
157</ol></div>
158<p>In case of quoted includes, no adjustment can give 100% correct
159        results. If target dirs are not changed by build system, quoted
160        includes are searched in "." and then in include path, while angle
161        includes are searched only in include path. When target dirs are
162        changed, we'd want to make quoted includes to be search in "." then in
163        additional dirs and then in the include path and make angle includes
164        be searched in include path, probably with additional paths added at
165        some position. Unless, include path already has "." as the first
166        element, this is not possible. So, either generated headers should not
167        be included with quotes, or first element of include path should be
168        ".", which essentially erases the difference between quoted and angle
169        includes. <span class="bold"><strong>Note:</strong></span> the only way to get
170        "." as include path into compiler command line is via verbatim
171        compiler option. In all other case, Boost.Build will convert "." into
172        directory where it occurs.</p>
173</div>
174<div class="section" lang="en">
175<div class="titlepage"><div><div><h3 class="title">
176<a name="id2861573"></a>Transformations cache</h3></div></div></div>
177<p>
178        Under certain conditions, an
179        attempt is made to cache results of transformation search. First,
180        the sources are replaced with targets with special name and the
181        found target list is stored. Later, when properties, requested
182        type, and source type are the same, the store target list is
183        retrieved and cloned, with appropriate change in names.
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="definitions.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="../faq.html"><img src="../../images/next.png" alt="Next"></a>
194</div>
195</body>
196</html>
Note: See TracBrowser for help on using the repository browser.