Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/doc/html/jam/language.html @ 29

Last change on this file since 29 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 82.7 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title> Language</title>
5<link rel="stylesheet" href="../boostbook.css" type="text/css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
7<link rel="start" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
8<link rel="up" href="../jam.html" title="Chapter 24. Boost.Jam : 3.1.14">
9<link rel="prev" href="usage.html" title=" Using BJam">
10<link rel="next" href="miscellaneous.html" title="Miscellaneous">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13<table cellpadding="2" width="100%">
14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
15<td align="center"><a href="../../../index.htm">Home</a></td>
16<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
17<td align="center"><a href="../../../people/people.htm">People</a></td>
18<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
19<td align="center"><a href="../../../more/index.htm">More</a></td>
20</table>
21<hr>
22<div class="spirit-nav">
23<a accesskey="p" href="usage.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../jam.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="miscellaneous.html"><img src="../images/next.png" alt="Next"></a>
24</div>
25<div class="section" lang="en">
26<div class="titlepage"><div><div><h2 class="title" style="clear: both">
27<a name="jam.language"></a> Language</h2></div></div></div>
28<div class="toc"><dl>
29<dt><span class="section"><a href="language.html#jam.language.lexical"> Lexical Features</a></span></dt>
30<dt><span class="section"><a href="language.html#jam.language.target"> Targets</a></span></dt>
31<dt><span class="section"><a href="language.html#jam.language.rules"> Rules</a></span></dt>
32<dt><span class="section"><a href="language.html#jam.language.flow_of_control">Flow-of-Control</a></span></dt>
33<dt><span class="section"><a href="language.html#jam.language.variables">Variables</a></span></dt>
34<dt><span class="section"><a href="language.html#jam.language.modules">Modules</a></span></dt>
35</dl></div>
36<p>
37      <code class="literal">BJam</code> has an interpreted, procedural language. Statements
38      in <code class="literal">bjam</code> are rule (procedure) definitions, rule invocations,
39      flow-of-control structures, variable assignments, and sundry language support.
40    </p>
41<div class="section" lang="en">
42<div class="titlepage"><div><div><h3 class="title">
43<a name="jam.language.lexical"></a> Lexical Features</h3></div></div></div>
44<p>
45        <code class="literal">BJam</code> treats its input files as whitespace-separated tokens,
46        with two exceptions: double quotes (") can enclose whitespace to embed
47        it into a token, and everything between the matching curly braces ({}) in
48        the definition of a rule action is treated as a single string. A backslash
49        (\) can escape a double quote, or any single whitespace character.
50      </p>
51<p>
52        <code class="literal">BJam</code> requires whitespace (blanks, tabs, or newlines) to
53        surround all tokens, including the colon (:) and semicolon (;) tokens.
54      </p>
55<p>
56        <code class="literal">BJam</code> keywords (an mentioned in this document) are reserved
57        and generally must be quoted with double quotes (") to be used as arbitrary
58        tokens, such as variable or target names.
59      </p>
60<p>
61        Comments start with the <code class="literal">#</code> character and extend until the
62        end of line.
63      </p>
64</div>
65<div class="section" lang="en">
66<div class="titlepage"><div><div><h3 class="title">
67<a name="jam.language.target"></a> Targets</h3></div></div></div>
68<div class="toc"><dl><dt><span class="section"><a href="language.html#jam.language.target.binding_detection">Binding Detection</a></span></dt></dl></div>
69<p>
70        The essential <code class="literal">bjam</code> data entity is a target. Build targets
71        are files to be updated. Source targets are the files used in updating built
72        targets. Built targets and source targets are collectively referred to as
73        file targets, and frequently built targets are source targets for other built
74        targets. Pseudotargets are symbols which represent dependencies on other
75        targets, but which are not themselves associated with any real file.
76      </p>
77<p>
78        A file target's identifier is generally the file's name, which can be absolutely
79        rooted, relative to the directory of <code class="literal">bjam</code>'s invocation,
80        or simply local (no directory). Most often it is the last case, and the actual
81        file path is bound using the <code class="literal">$(SEARCH)</code> and <code class="literal">$(LOCATE)</code>
82        special variables. See <a href="language.html#jam.language.variables.builtins.search" title=" SEARCH and LOCATE">SEARCH
83        and LOCATE Variables</a> below. A local filename is optionally qualified
84        with grist, a string value used to assure uniqueness. A file target with
85        an identifier of the form <span class="emphasis"><em>file(member)</em></span> is a library
86        member (usually an <code class="literal">ar</code>(1) archive on Unix).
87      </p>
88<div class="section" lang="en">
89<div class="titlepage"><div><div><h4 class="title">
90<a name="jam.language.target.binding_detection"></a>Binding Detection</h4></div></div></div>
91<p>
92          Whenever a target is bound to a location in the filesystem, Boost Jam will
93          look for a variable called <code class="literal">BINDRULE</code> (first "on"
94          the target being bound, then in the global module). If non-empty, <code class="literal">$(BINDRULE[1])</code>
95          names a rule which is called with the name of the target and the path it
96          is being bound to. The signature of the rule named by <code class="literal">$(BINDRULE[1])</code>
97          should match the following:
98        </p>
99<pre class="programlisting">rule <span class="emphasis"><em>bind-rule</em></span> ( <span class="emphasis"><em>target</em></span> : <span class="emphasis"><em>path</em></span> )
100</pre>
101<p>
102          This facility is useful for correct header file scanning, since many compilers
103          will search for <code class="computeroutput"><span class="preprocessor">#include</span></code>
104          files first in the directory containing the file doing the <code class="computeroutput"><span class="preprocessor">#include</span></code> directive. <code class="literal">$(BINDRULE)</code>
105          can be used to make a record of that directory.
106        </p>
107</div>
108</div>
109<div class="section" lang="en">
110<div class="titlepage"><div><div><h3 class="title">
111<a name="jam.language.rules"></a> Rules</h3></div></div></div>
112<div class="toc"><dl>
113<dt><span class="section"><a href="language.html#jam.language.rules.action_modifiers">Action Modifiers</a></span></dt>
114<dt><span class="section"><a href="language.html#jam.language.rules.argument_lists">Argument lists</a></span></dt>
115<dt><span class="section"><a href="language.html#jam.language.rules.builtins"> Built-in Rules</a></span></dt>
116</dl></div>
117<p>
118        The basic <code class="literal">bjam</code> language entity is called a rule. A rule
119        is defined in two parts: the procedure and the actions. The procedure is
120        a body of jam statements to be run when the rule is invoked; the actions
121        are the OS shell commands to execute when updating the built targets of the
122        rule.
123      </p>
124<p>
125        Rules can return values, which can be expanded into a list with "[
126        <span class="emphasis"><em>rule</em></span> <span class="emphasis"><em>args</em></span> ... ]". A rule's
127        value is the value of its last statement, though only the following statements
128        have values: 'if' (value of the leg chosen), 'switch' (value of the case
129        chosen), set (value of the resulting variable), and 'return' (value of its
130        arguments). Note that 'return' doesn't actually cause a return, i.e., is
131        a no-op unless it is the last statement of the last block executed within
132        rule body.
133      </p>
134<p>
135        The <code class="literal">bjam</code> statements for defining and invoking rules are
136        as follows:
137      </p>
138<p>
139        Define a rule's procedure, replacing any previous definition.
140      </p>
141<pre class="programlisting">rule <span class="emphasis"><em>rulename</em></span> { <span class="emphasis"><em>statements</em></span> }
142</pre>
143<p>
144        Define a rule's updating actions, replacing any previous definition.
145      </p>
146<pre class="programlisting">actions [ <span class="emphasis"><em>modifiers</em></span> ] <span class="emphasis"><em>rulename</em></span> { <span class="emphasis"><em>commands</em></span> }
147</pre>
148<p>
149        Invoke a rule.
150      </p>
151<pre class="programlisting"><span class="emphasis"><em>rulename</em></span> <span class="emphasis"><em>field1</em></span> : <span class="emphasis"><em>field2</em></span> : <span class="emphasis"><em>...</em></span> : <span class="emphasis"><em>fieldN</em></span> ;
152</pre>
153<p>
154        Invoke a rule under the influence of target's specific variables..
155      </p>
156<pre class="programlisting">on <span class="emphasis"><em>target</em></span> <span class="emphasis"><em>rulename</em></span> <span class="emphasis"><em>field1</em></span> : <span class="emphasis"><em>field2</em></span> : <span class="emphasis"><em>...</em></span> : <span class="emphasis"><em>fieldN</em></span> ;
157</pre>
158<p>
159        Used as an argument, expands to the return value of the rule invoked.
160      </p>
161<pre class="programlisting">[ <span class="emphasis"><em>rulename</em></span> <span class="emphasis"><em>field1</em></span> : <span class="emphasis"><em>field2</em></span> : <span class="emphasis"><em>...</em></span> : <span class="emphasis"><em>fieldN</em></span> ]
162[ on <span class="emphasis"><em>target</em></span> <span class="emphasis"><em>rulename</em></span> <span class="emphasis"><em>field1</em></span> : <span class="emphasis"><em>field2</em></span> : <span class="emphasis"><em>...</em></span> : <span class="emphasis"><em>fieldN</em></span> ]
163</pre>
164<p>
165        A rule is invoked with values in <span class="emphasis"><em>field1</em></span> through <span class="emphasis"><em>fieldN</em></span>.
166        They may be referenced in the procedure's statements as <code class="literal">$(1)</code>
167        through <code class="literal">$(<span class="emphasis"><em>N</em></span>)</code> (9 max), and the first
168        two only may be referenced in the action's <span class="emphasis"><em>commands</em></span>
169        as <code class="literal">$(1)</code> and <code class="literal">$(2)</code>. <code class="literal">$(&lt;)</code>
170        and <code class="literal">$(&gt;)</code> are synonymous with <code class="literal">$(1)</code>
171        and <code class="literal">$(2)</code>.
172      </p>
173<p>
174        Rules fall into two categories: updating rules (with actions), and pure procedure
175        rules (without actions). Updating rules treat arguments <code class="literal">$(1)</code>
176        and <code class="literal">$(2)</code> as built targets and sources, respectively, while
177        pure procedure rules can take arbitrary arguments.
178      </p>
179<p>
180        When an updating rule is invoked, its updating actions are added to those
181        associated with its built targets (<code class="literal">$(1)</code>) before the rule's
182        procedure is run. Later, to build the targets in the updating phase, <span class="emphasis"><em>commands</em></span>
183        are passed to the OS command shell, with <code class="literal">$(1)</code> and <code class="literal">$(2)</code>
184        replaced by bound versions of the target names. See Binding above.
185      </p>
186<p>
187        Rule invocation may be indirected through a variable:
188      </p>
189<pre class="programlisting">$(<span class="emphasis"><em>var</em></span>) <span class="emphasis"><em>field1</em></span> : <span class="emphasis"><em>field2</em></span> : <span class="emphasis"><em>...</em></span> : <span class="emphasis"><em>fieldN</em></span> ;
190
191on <span class="emphasis"><em>target</em></span> $(<span class="emphasis"><em>var</em></span>) <span class="emphasis"><em>field1</em></span> : <span class="emphasis"><em>field2</em></span> : <span class="emphasis"><em>...</em></span> : <span class="emphasis"><em>fieldN</em></span> ;
192
193[ $(<span class="emphasis"><em>var</em></span>) <span class="emphasis"><em>field1</em></span> : <span class="emphasis"><em>field2</em></span> : <span class="emphasis"><em>...</em></span> : <span class="emphasis"><em>fieldN</em></span> ]
194[ on <span class="emphasis"><em>target</em></span> $(<span class="emphasis"><em>var</em></span>) <span class="emphasis"><em>field1</em></span> : <span class="emphasis"><em>field2</em></span> : <span class="emphasis"><em>...</em></span> : <span class="emphasis"><em>fieldN</em></span> ]
195</pre>
196<p>
197        The variable's value names the rule (or rules) to be invoked. A rule is invoked
198        for each element in the list of <code class="literal">$(<span class="emphasis"><em>var</em></span>)</code>'s
199        values. The fields <code class="literal"><span class="emphasis"><em>field1</em></span> : <span class="emphasis"><em>field2</em></span>
200        : <span class="emphasis"><em>...</em></span></code> are passed as arguments for each invokation.
201        For the [ ... ] forms, the return value is the concatenation of the return
202        values for all of the invocations.
203      </p>
204<div class="section" lang="en">
205<div class="titlepage"><div><div><h4 class="title">
206<a name="jam.language.rules.action_modifiers"></a>Action Modifiers</h4></div></div></div>
207<p>
208          The following action modifiers are understood:
209        </p>
210<div class="variablelist">
211<p class="title"><b></b></p>
212<dl>
213<dt><span class="term"><code class="literal">actions bind <span class="emphasis"><em>vars</em></span></code></span></dt>
214<dd>
215<code class="literal">$(<span class="emphasis"><em>vars</em></span>)</code> will be replaced with
216            bound values.
217          </dd>
218<dt><span class="term"><code class="literal">actions existing</code></span></dt>
219<dd>
220<code class="literal">$(&gt;)</code> includes only source targets currently existing.
221          </dd>
222<dt><span class="term"><code class="literal">actions ignore</code></span></dt>
223<dd>
224            The return status of the commands is ignored.
225          </dd>
226<dt><span class="term"><code class="literal">actions piecemeal</code></span></dt>
227<dd>
228            commands are repeatedly invoked with a subset of <code class="literal">$(&gt;)</code>
229            small enough to fit in the command buffer on this OS.
230          </dd>
231<dt><span class="term"><code class="literal">actions quietly</code></span></dt>
232<dd>
233            The action is not echoed to the standard output.
234          </dd>
235<dt><span class="term"><code class="literal">actions together</code></span></dt>
236<dd>
237            The <code class="literal">$(&gt;)</code> from multiple invocations of the same
238            action on the same built target are glommed together.
239          </dd>
240<dt><span class="term"><code class="literal">actions updated</code></span></dt>
241<dd>
242<code class="literal">$(&gt;)</code> includes only source targets themselves marked
243            for updating.
244          </dd>
245</dl>
246</div>
247</div>
248<div class="section" lang="en">
249<div class="titlepage"><div><div><h4 class="title">
250<a name="jam.language.rules.argument_lists"></a>Argument lists</h4></div></div></div>
251<p>
252          You can describe the arguments accepted by a rule, and refer to them by
253          name within the rule. For example, the following prints "I'm sorry,
254          Dave" to the console:
255        </p>
256<pre class="programlisting">rule report ( pronoun index ? : state : names + )
257{
258    local he.suffix she.suffix it.suffix = s ;
259    local I.suffix = m ;
260    local they.suffix you.suffix = re ;
261    ECHO $(pronoun)'$($(pronoun).suffix) $(state), $(names[$(index)]) ;
262}
263report I 2 : sorry : Joe Dave Pete ;
264</pre>
265<p>
266          Each name in a list of formal arguments (separated by "<code class="literal">:</code>"
267          in the rule declaration) is bound to a single element of the corresponding
268          actual argument unless followed by one of these modifiers:
269        </p>
270<div class="informaltable">
271<h4>
272<a name="id2095002"></a>
273          </h4>
274<table class="table">
275<colgroup>
276<col>
277<col>
278</colgroup>
279<thead><tr>
280<th>Symbol</th>
281<th>Semantics of preceding symbol</th>
282</tr></thead>
283<tbody>
284<tr>
285<td><code class="literal">?</code></td>
286<td>optional</td>
287</tr>
288<tr>
289<td><code class="literal">*</code></td>
290<td>Bind to zero or more unbound
291                elements of the actual argument. When <code class="literal">*</code> appears
292                where an argument name is expected, any number of additional arguments
293                are accepted. This feature can be used to implement "varargs"
294                rules.</td>
295</tr>
296<tr>
297<td><code class="literal">+</code></td>
298<td>Bind to one or more unbound
299                elements of the actual argument.</td>
300</tr>
301</tbody>
302</table>
303</div>
304<p>
305          The actual and formal arguments are checked for inconsistencies, which
306          cause Jam to exit with an error code:
307        </p>
308<pre class="programlisting">### argument error
309# rule report ( pronoun index ?  : state  : names + )
310# called with: ( I 2 foo  : sorry  : Joe Dave Pete )
311# extra argument foo
312### argument error
313# rule report ( pronoun index ?  : state  : names + )
314# called with: ( I 2  : sorry )
315# missing argument names
316</pre>
317<p>
318          If you omit the list of formal arguments, all checking is bypassed as in
319          "classic" Jam. Argument lists drastically improve the reliability
320          and readability of your rules, however, and are <span class="bold"><strong>strongly
321          recommended</strong></span> for any new Jam code you write.
322        </p>
323</div>
324<div class="section" lang="en">
325<div class="titlepage"><div><div><h4 class="title">
326<a name="jam.language.rules.builtins"></a> Built-in Rules</h4></div></div></div>
327<div class="toc"><dl>
328<dt><span class="section"><a href="language.html#jam.language.rules.builtins.dependency_building">Dependency Building</a></span></dt>
329<dt><span class="section"><a href="language.html#jam.language.rules.builtins.modifying_binding">Modifying Binding</a></span></dt>
330<dt><span class="section"><a href="language.html#jam.language.rules.builtins.utility">Utility</a></span></dt>
331</dl></div>
332<p>
333          <code class="literal">BJam</code> has a growing set of built-in rules, all of which
334          are pure procedure rules without updating actions. They are in three groups:
335          the first builds the dependency graph; the second modifies it; and the
336          third are just utility rules.
337        </p>
338<div class="section" lang="en">
339<div class="titlepage"><div><div><h5 class="title">
340<a name="jam.language.rules.builtins.dependency_building"></a>Dependency Building</h5></div></div></div>
341<pre class="programlisting">DEPENDS <span class="emphasis"><em>targets1</em></span> : <span class="emphasis"><em>targets2</em></span> ;
342</pre>
343<p>
344            Builds a direct dependency: makes each of <span class="emphasis"><em>targets1</em></span>
345            depend on each of <span class="emphasis"><em>targets2</em></span>. Generally, <span class="emphasis"><em>targets1</em></span>
346            will be rebuilt if <span class="emphasis"><em>targets2</em></span> are themselves rebuilt
347            are or are newer than <span class="emphasis"><em>targets1</em></span>.
348          </p>
349<pre class="programlisting">INCLUDES <span class="emphasis"><em>targets1</em></span> : <span class="emphasis"><em>targets2</em></span> ;
350</pre>
351<p>
352            Builds a sibling dependency: makes any target that depends on any of
353            <span class="emphasis"><em>targets1</em></span> also depend on each of <span class="emphasis"><em>targets2</em></span>.
354            This reflects the dependencies that arise when one source file includes
355            another: the object built from the source file depends both on the original
356            and included source file, but the two sources files don't depend on each
357            other. For example:
358          </p>
359<pre class="programlisting">DEPENDS foo.o : foo.c ;
360INCLUDES foo.c : foo.h ;
361</pre>
362<p>
363            "<code class="literal">foo.o</code>" depends on "<code class="literal">foo.c</code>"
364            and "<code class="literal">foo.h</code>" in this example.
365          </p>
366</div>
367<div class="section" lang="en">
368<div class="titlepage"><div><div><h5 class="title">
369<a name="jam.language.rules.builtins.modifying_binding"></a>Modifying Binding</h5></div></div></div>
370<p>
371            The six rules <code class="literal">ALWAYS</code>, <code class="literal">LEAVES</code>,
372            <code class="literal">NOCARE</code>, <code class="literal">NOTFILE</code>, <code class="literal">NOUPDATE</code>,
373            and <code class="literal">TEMPORARY</code> modify the dependency graph so that
374            <code class="literal">bjam</code> treats the targets differently during its target
375            binding phase. See Binding above. Normally, <code class="literal">bjam</code> updates
376            a target if it is missing, if its filesystem modification time is older
377            than any of its dependencies (recursively), or if any of its dependencies
378            are being updated. This basic behavior can be changed by invoking the
379            following rules:
380          </p>
381<pre class="programlisting">ALWAYS <span class="emphasis"><em>targets</em></span> ;
382</pre>
383<p>
384            Causes <span class="emphasis"><em>targets</em></span> to be rebuilt regardless of whether
385            they are up-to-date (they must still be in the dependency graph). This
386            is used for the clean and uninstall targets, as they have no dependencies
387            and would otherwise appear never to need building. It is best applied
388            to targets that are also <code class="literal">NOTFILE</code> targets, but it can
389            also be used to force a real file to be updated as well.
390          </p>
391<pre class="programlisting">LEAVES <span class="emphasis"><em>targets</em></span> ;
392</pre>
393<p>
394            Makes each of <span class="emphasis"><em>targets</em></span> depend only on its leaf sources,
395            and not on any intermediate targets. This makes it immune to its dependencies
396            being updated, as the "leaf" dependencies are those without
397            their own dependencies and without updating actions. This allows a target
398            to be updated only if original source files change.
399          </p>
400<pre class="programlisting">NOCARE <span class="emphasis"><em>targets</em></span> ;
401</pre>
402<p>
403            Causes <code class="literal">bjam</code> to ignore <span class="emphasis"><em>targets</em></span>
404            that neither can be found nor have updating actions to build them. Normally
405            for such targets <code class="literal">bjam</code> issues a warning and then skips
406            other targets that depend on these missing targets. The <code class="literal">HdrRule</code>
407            in <code class="literal">Jambase</code> uses <code class="literal">NOCARE</code> on the header
408            file names found during header file scanning, to let <code class="literal">bjam</code>
409            know that the included files may not exist. For example, if an <code class="computeroutput"><span class="preprocessor">#include</span></code> is within an <code class="computeroutput"><span class="preprocessor">#ifdef</span></code>, the included file may not
410            actually be around.
411          </p>
412<div class="warning"><table border="0" summary="Warning">
413<tr>
414<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../images/warning.png"></td>
415<th align="left">Warning</th>
416</tr>
417<tr><td align="left" valign="top"><p>
418              For targets with build actions: if their build actions exit with a
419              nonzero return code, dependent targets will still be built.
420            </p></td></tr>
421</table></div>
422<pre class="programlisting">NOTFILE <span class="emphasis"><em>targets</em></span> ;
423</pre>
424<p>
425            Marks <span class="emphasis"><em>targets</em></span> as pseudotargets and not real files.
426            No timestamp is checked, and so the actions on such a target are only
427            executed if the target's dependencies are updated, or if the target is
428            also marked with <code class="literal">ALWAYS</code>. The default <code class="literal">bjam</code>
429            target "<code class="literal">all</code>" is a pseudotarget. In <code class="literal">Jambase</code>,
430            <code class="literal">NOTFILE</code> is used to define several addition convenient
431            pseudotargets.
432          </p>
433<pre class="programlisting">NOUPDATE <span class="emphasis"><em>targets</em></span> ;
434</pre>
435<p>
436            Causes the timestamps on <span class="emphasis"><em>targets</em></span> to be ignored.
437            This has two effects: first, once the target has been created it will
438            never be updated; second, manually updating target will not cause other
439            targets to be updated. In <code class="literal">Jambase</code>, for example, this
440            rule is applied to directories by the <code class="literal">MkDir</code> rule,
441            because <code class="literal">MkDir</code> only cares that the target directory
442            exists, not when it has last been updated.
443          </p>
444<pre class="programlisting">TEMPORARY <span class="emphasis"><em>targets</em></span> ;
445</pre>
446<p>
447            Marks <span class="emphasis"><em>targets</em></span> as temporary, allowing them to be
448            removed after other targets that depend upon them have been updated.
449            If a <code class="literal">TEMPORARY</code> target is missing, <code class="literal">bjam</code>
450            uses the timestamp of the target's parent. <code class="literal">Jambase</code>
451            uses <code class="literal">TEMPORARY</code> to mark object files that are archived
452            in a library after they are built, so that they can be deleted after
453            they are archived.
454          </p>
455<pre class="programlisting">FAIL_EXPECTED <span class="emphasis"><em>targets</em></span> ;
456</pre>
457<p>
458            For handling targets whose build actions are expected to fail (e.g. when
459            testing that assertions or compile-time type checkin work properly),
460            Boost Jam supplies the <code class="literal">FAIL_EXPECTED</code> rule in the same
461            style as <code class="literal">NOCARE</code>, et. al. During target updating, the
462            return code of the build actions for arguments to <code class="literal">FAIL_EXPECTED</code>
463            is inverted: if it fails, building of dependent targets continues as
464            though it succeeded. If it succeeds, dependent targets are skipped.
465          </p>
466<pre class="programlisting">RMOLD <span class="emphasis"><em>targets</em></span> ;
467</pre>
468<p>
469            <code class="literal">BJam</code> removes any target files that may exist on disk
470            when the rule used to build those targets fails. However, targets whose
471            dependencies fail to build are not removed by default. The <code class="literal">RMOLD</code>
472            rule causes its arguments to be removed if any of their dependencies
473            fail to build.
474          </p>
475<pre class="programlisting">rule ISFILE ( <span class="emphasis"><em>targets</em></span> * )
476</pre>
477<p>
478            <code class="literal">ISFILE</code> marks targets as required to be files. This
479            changes the way <code class="literal">bjam</code> searches for the target such
480            that it ignores mathes for file system items that are not file, like
481            directories. This makes it possible to avoid <code class="computeroutput"><span class="preprocessor">#include</span> <span class="string">"exception"</span></code> matching if one happens
482            to have a directory named exception in the header search path.
483          </p>
484<div class="warning"><table border="0" summary="Warning">
485<tr>
486<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../images/warning.png"></td>
487<th align="left">Warning</th>
488</tr>
489<tr><td align="left" valign="top"><p>
490              This is currently not fully implemented.
491            </p></td></tr>
492</table></div>
493</div>
494<div class="section" lang="en">
495<div class="titlepage"><div><div><h5 class="title">
496<a name="jam.language.rules.builtins.utility"></a>Utility</h5></div></div></div>
497<p>
498            The two rules <code class="literal">ECHO</code> and <code class="literal">EXIT</code> are
499            utility rules, used only in <code class="literal">bjam</code>'s parsing phase.
500          </p>
501<pre class="programlisting">ECHO <span class="emphasis"><em>args</em></span> ;
502</pre>
503<p>
504            Blurts out the message <span class="emphasis"><em>args</em></span> to stdout.
505          </p>
506<pre class="programlisting">rule EXIT ( <span class="emphasis"><em>message</em></span> * : <span class="emphasis"><em>result-value</em></span> ? )
507</pre>
508<p>
509            Blurts out the <span class="emphasis"><em>message</em></span> to stdout and then exits
510            with a failure status if no <span class="emphasis"><em>result-value</em></span> is given,
511            otherwise it exits with the given <span class="emphasis"><em>result-value</em></span>.
512          </p>
513<p>
514            "<code class="literal">Echo</code>", "<code class="literal">echo</code>",
515            "<code class="literal">Exit</code>", and "<code class="literal">exit</code>"
516            are accepted as aliases for <code class="literal">ECHO</code> and <code class="literal">EXIT</code>,
517            since it is hard to tell that these are built-in rules and not part of
518            the language, like "<code class="literal">include</code>".
519          </p>
520<p>
521            The <code class="literal">GLOB</code> rule does filename globbing.
522          </p>
523<pre class="programlisting">GLOB <span class="emphasis"><em>directories</em></span> : <span class="emphasis"><em>patterns</em></span> : <span class="emphasis"><em>downcase-opt</em></span>
524</pre>
525<p>
526            Using the same wildcards as for the patterns in the switch statement.
527            It is invoked by being used as an argument to a rule invocation inside
528            of "<code class="literal">[ ]</code>". For example: "<code class="literal">FILES
529            = [ GLOB dir1 dir2 : *.c *.h ]</code>" sets <code class="literal">FILES</code>
530            to the list of C source and header files in <code class="literal">dir1</code> and
531            <code class="literal">dir2</code>. The resulting filenames are the full pathnames,
532            including the directory, but the pattern is applied only to the file
533            name without the directory.
534          </p>
535<p>
536            If <span class="emphasis"><em>downcase-opt</em></span> is supplied, filenames are converted
537            to all-lowercase before matching against the pattern; you can use this
538            to do case-insensitive matching using lowercase patterns. The paths returned
539            will still have mixed case if the OS supplies them. On Windows NT and
540            Cygwin, filenames are always downcased before matching.
541          </p>
542<p>
543            The <code class="literal">MATCH</code> rule does pattern matching.
544          </p>
545<pre class="programlisting">MATCH <span class="emphasis"><em>regexps</em></span> : <span class="emphasis"><em>list</em></span>
546</pre>
547<p>
548            Matches the <code class="literal">egrep</code>(1) style regular expressions <span class="emphasis"><em>regexps</em></span>
549            against the strings in <span class="emphasis"><em>list</em></span>. The result is the concatenation
550            of matching <code class="literal">()</code> subexpressions for each string in
551            <span class="emphasis"><em>list</em></span>, and for each regular expression in <span class="emphasis"><em>regexps</em></span>.
552            Only useful within the "<code class="literal">[ ]</code>" construct,
553            to change the result into a list.
554          </p>
555<pre class="programlisting">rule BACKTRACE ( )
556</pre>
557<p>
558            Returns a list of quadruples: <span class="emphasis"><em>filename</em></span> <span class="emphasis"><em>line</em></span> <span class="emphasis"><em>module</em></span> <span class="emphasis"><em>rulename</em></span>...,
559            describing each shallower level of the call stack. This rule can be used
560            to generate useful diagnostic messages from Jam rules.
561          </p>
562<pre class="programlisting">rule UPDATE ( <span class="emphasis"><em>targets</em></span> * )
563</pre>
564<p>
565            Classic jam treats any non-option element of command line as a name of
566            target to be updated. This prevented more sophisticated handling of command
567            line. This is now enabled again but with additional changes to the <code class="literal">UPDATE</code>
568            rule to allow for the flexibility of changing the list of targets to
569            update. The UPDATE rule has two effects:
570          </p>
571<div class="orderedlist"><ol type="1">
572<li>
573              It clears the list of targets to update, and
574            </li>
575<li>
576              Causes the specified targets to be updated.
577            </li>
578</ol></div>
579<p>
580            If no target was specified with the <code class="literal">UPDATE</code> rule, no
581            targets will be updated. To support changing of the update list in more
582            usefull ways, the rule also returns the targets previously in the update
583            list. This makes it possible to add targets as such:
584          </p>
585<pre class="programlisting">local previous-updates = [ UPDATE ] ;
586UPDATE $(previous-updates) a-new-target ;
587</pre>
588<pre class="programlisting">rule W32_GETREG ( <span class="emphasis"><em>path</em></span> : <span class="emphasis"><em>data</em></span> ? )
589</pre>
590<p>
591            Defined only for win32 platform. It reads the registry of Windows. '<span class="emphasis"><em>path</em></span>'
592            is the location of the information, and '<span class="emphasis"><em>data</em></span>' is
593            the name of the value which we want to get. If '<span class="emphasis"><em>data</em></span>'
594            is omitted, the default value of '<span class="emphasis"><em>path</em></span>' will be
595            returned. The '<span class="emphasis"><em>path</em></span>' value must conform to MS key
596            path format and must be prefixed with one of the predefined root keys.
597            As usual,
598          </p>
599<div class="itemizedlist"><ul type="disc">
600<li>
601              '<code class="literal">HKLM</code>' is equivalent to '<code class="literal">HKEY_LOCAL_MACHINE</code>'.
602            </li>
603<li>
604              '<code class="literal">HKCU</code>' is equivalent to '<code class="literal">HKEY_CURRENT_USER</code>'.
605            </li>
606<li>
607              '<code class="literal">HKCR</code>' is equivalent to '<code class="literal">HKEY_CLASSES_ROOT</code>'.
608            </li>
609</ul></div>
610<p>
611            Other predefined root keys are not supported.
612          </p>
613<p>
614            Currently supported data types : '<code class="literal">REG_DWORD</code>', '<code class="literal">REG_SZ</code>',
615            '<code class="literal">REG_EXPAND_SZ</code>', '<code class="literal">REG_MULTI_SZ</code>'.
616            The data with '<code class="literal">REG_DWORD</code>' type will be turned into
617            a string, '<code class="literal">REG_MULTI_SZ</code>' into a list of strings, and
618            for those with '<code class="literal">REG_EXPAND_SZ</code>' type environment variables
619            in it will be replaced with their defined values. The data with '<code class="literal">REG_SZ</code>'
620            type and other unsupported types will be put into a string without modification.
621            If it can't receive the value of the data, it just return an empty list.
622            For example,
623          </p>
624<pre class="programlisting">local PSDK-location =
625  [ W32_GETREG HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\MicrosoftSDK\\Directories : "Install Dir" ] ;
626</pre>
627<pre class="programlisting">rule SHELL ( <span class="emphasis"><em>command</em></span> : * )
628</pre>
629<p>
630            <code class="literal">SHELL</code> executes <span class="emphasis"><em>command</em></span>, and then
631            returns the standard output of <span class="emphasis"><em>command</em></span>. <code class="literal">SHELL</code>
632            only works on platforms with a <code class="literal">popen()</code> function in
633            the C library. On platforms without a working <code class="literal">popen()</code>
634            function, <code class="literal">SHELL</code> is implemented as a no-op. <code class="literal">SHELL</code>
635            works on Unix, MacOS X, and most Windows compilers. <code class="literal">SHELL</code>
636            is a no-op on Metrowerks compilers under Windows. There is a variable
637            set of allowed options as additional arguments:
638          </p>
639<div class="variablelist">
640<p class="title"><b></b></p>
641<dl>
642<dt><span class="term"><code class="literal">exit-status</code></span></dt>
643<dd>
644              In addition to the output the result status of the executed command
645              is returned as a second element of the result.
646            </dd>
647<dt><span class="term"><code class="literal">no-output</code></span></dt>
648<dd>
649              Don't capture the output of the command. Instead an empty ("")
650              string value is returned in place of the output.
651            </dd>
652</dl>
653</div>
654<p>
655            Because the Perforce/Jambase defines a <code class="literal">SHELL</code> rule
656            which hides the builtin rule, <code class="literal">COMMAND</code> can be used
657            as an alias for <code class="literal">SHELL</code> in such a case.
658          </p>
659</div>
660</div>
661</div>
662<div class="section" lang="en">
663<div class="titlepage"><div><div><h3 class="title">
664<a name="jam.language.flow_of_control"></a>Flow-of-Control</h3></div></div></div>
665<p>
666        <code class="literal">BJam</code> has several simple flow-of-control statements:
667      </p>
668<pre class="programlisting">for <span class="emphasis"><em>var</em></span> in <span class="emphasis"><em>list</em></span> { <span class="emphasis"><em>statements</em></span> }
669</pre>
670<p>
671        Executes <span class="emphasis"><em>statements</em></span> for each element in <span class="emphasis"><em>list</em></span>,
672        setting the variable <span class="emphasis"><em>var</em></span> to the element value.
673      </p>
674<pre class="programlisting">if <span class="emphasis"><em>cond</em></span> { <span class="emphasis"><em>statements</em></span> }
675[ else { <span class="emphasis"><em>statements</em></span> } ]
676</pre>
677<p>
678        Does the obvious; the <code class="literal">else</code> clause is optional. <span class="emphasis"><em>cond</em></span>
679        is built of:
680      </p>
681<div class="variablelist">
682<p class="title"><b></b></p>
683<dl>
684<dt><span class="term"><code class="literal"><span class="emphasis"><em>a</em></span></code></span></dt>
685<dd>
686          true if any <span class="emphasis"><em>a</em></span> element is a non-zero-length string
687        </dd>
688<dt><span class="term"><code class="literal"><span class="emphasis"><em>a</em></span> = <span class="emphasis"><em>b</em></span></code></span></dt>
689<dd>
690          list <span class="emphasis"><em>a</em></span> matches list <span class="emphasis"><em>b</em></span> string-for-string
691        </dd>
692<dt><span class="term"><code class="literal"><span class="emphasis"><em>a</em></span> != <span class="emphasis"><em>b</em></span></code></span></dt>
693<dd>
694          list <span class="emphasis"><em>a</em></span> does not match list <span class="emphasis"><em>b</em></span>
695</dd>
696<dt><span class="term"><code class="literal"><span class="emphasis"><em>a</em></span> &lt;
697        <span class="emphasis"><em>b</em></span></code></span></dt>
698<dd>
699<span class="emphasis"><em>a[i]</em></span> string is less than <span class="emphasis"><em>b[i]</em></span>
700          string, where <span class="emphasis"><em>i</em></span> is first mismatched element in lists
701          <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>b</em></span>
702</dd>
703<dt><span class="term"><code class="literal"><span class="emphasis"><em>a</em></span> &lt;=
704        <span class="emphasis"><em>b</em></span></code></span></dt>
705<dd>
706          every <span class="emphasis"><em>a</em></span> string is less than or equal to its <span class="emphasis"><em>b</em></span>
707          counterpart
708        </dd>
709<dt><span class="term"><code class="literal"><span class="emphasis"><em>a</em></span> &gt;
710        <span class="emphasis"><em>b</em></span></code></span></dt>
711<dd>
712<span class="emphasis"><em>a[i]</em></span> string is greater than <span class="emphasis"><em>b[i]</em></span>
713          string, where <span class="emphasis"><em>i</em></span> is first mismatched element
714        </dd>
715<dt><span class="term"><code class="literal"><span class="emphasis"><em>a</em></span> &gt;=
716        <span class="emphasis"><em>b</em></span></code></span></dt>
717<dd>
718          every <span class="emphasis"><em>a</em></span> string is greater than or equal to its <span class="emphasis"><em>b</em></span>
719          counterpart
720        </dd>
721<dt><span class="term"><code class="literal"><span class="emphasis"><em>a</em></span> in <span class="emphasis"><em>b</em></span></code></span></dt>
722<dd>
723          true if all elements of <span class="emphasis"><em>a</em></span> can be found in <span class="emphasis"><em>b</em></span>,
724          or if <span class="emphasis"><em>a</em></span> has no elements
725        </dd>
726<dt><span class="term"><code class="literal">! <span class="emphasis"><em>cond</em></span></code></span></dt>
727<dd>
728          condition not true
729        </dd>
730<dt><span class="term"><code class="literal"><span class="emphasis"><em>cond</em></span> &amp;&amp;
731        <span class="emphasis"><em>cond</em></span></code></span></dt>
732<dd>
733          conjunction
734        </dd>
735<dt><span class="term"><code class="literal"><span class="emphasis"><em>cond</em></span> ||
736        <span class="emphasis"><em>cond</em></span></code></span></dt>
737<dd>
738          disjunction
739        </dd>
740<dt><span class="term"><code class="literal">( <span class="emphasis"><em>cond</em></span>
741        )</code></span></dt>
742<dd>
743          precedence grouping
744        </dd>
745</dl>
746</div>
747<pre class="programlisting">include <span class="emphasis"><em>file</em></span> ;
748</pre>
749<p>
750        Causes <code class="literal">bjam</code> to read the named <span class="emphasis"><em>file</em></span>.
751        The <span class="emphasis"><em>file</em></span> is bound like a regular target (see Binding
752        above) but unlike a regular target the include <span class="emphasis"><em>file</em></span>
753        cannot be built.
754      </p>
755<p>
756        The include <span class="emphasis"><em>file</em></span> is inserted into the input stream during
757        the parsing phase. The primary input file and all the included file(s) are
758        treated as a single file; that is, jam infers no scope boundaries from included
759        files.
760      </p>
761<pre class="programlisting">local <span class="emphasis"><em>vars</em></span> [ = <span class="emphasis"><em>values</em></span> ] ;
762</pre>
763<p>
764        Creates new <span class="emphasis"><em>vars</em></span> inside to the enclosing <code class="literal">{}</code>
765        block, obscuring any previous values they might have. The previous values
766        for vars are restored when the current block ends. Any rule called or file
767        included will see the local and not the previous value (this is sometimes
768        called Dynamic Scoping). The local statement may appear anywhere, even outside
769        of a block (in which case the previous value is restored when the input ends).
770        The <span class="emphasis"><em>vars</em></span> are initialized to <span class="emphasis"><em>values</em></span>
771        if present, or left uninitialized otherwise.
772      </p>
773<pre class="programlisting">return <span class="emphasis"><em>values</em></span> ;
774</pre>
775<p>
776        Within a rule body, the return statement sets the return value for an invocation
777        of the rule. It does <span class="bold"><strong>not</strong></span> cause the rule
778        to return; a rule's value is actually the value of the last statement executed,
779        so a return should be the last statement executed before the rule "naturally"
780        returns.
781      </p>
782<pre class="programlisting">switch <span class="emphasis"><em>value</em></span>
783{
784    case <span class="emphasis"><em>pattern1</em></span> : <span class="emphasis"><em>statements</em></span> ;
785    case <span class="emphasis"><em>pattern2</em></span> : <span class="emphasis"><em>statements</em></span> ;
786    ...
787}
788</pre>
789<p>
790        The switch statement executes zero or one of the enclosed <span class="emphasis"><em>statements</em></span>,
791        depending on which, if any, is the first case whose <span class="emphasis"><em>pattern</em></span>
792        matches <span class="emphasis"><em>value</em></span>. The <span class="emphasis"><em>pattern</em></span> values
793        are not variable-expanded. The pattern values may include the following wildcards:
794      </p>
795<div class="variablelist">
796<p class="title"><b></b></p>
797<dl>
798<dt><span class="term"><code class="literal">?</code></span></dt>
799<dd>
800          match any single character
801        </dd>
802<dt><span class="term"><code class="literal">*</code></span></dt>
803<dd>
804          match zero or more characters
805        </dd>
806<dt><span class="term"><code class="literal">[<span class="emphasis"><em>chars</em></span>]</code></span></dt>
807<dd>
808          match any single character in <span class="emphasis"><em>chars</em></span>
809</dd>
810<dt><span class="term"><code class="literal">[^<span class="emphasis"><em>chars</em></span>]</code></span></dt>
811<dd>
812          match any single character not in <span class="emphasis"><em>chars</em></span>
813</dd>
814<dt><span class="term"><code class="literal">\<span class="emphasis"><em>x</em></span></code></span></dt>
815<dd>
816          match <span class="emphasis"><em>x</em></span> (escapes the other wildcards)
817        </dd>
818</dl>
819</div>
820<pre class="programlisting">while <span class="emphasis"><em>cond</em></span> { <span class="emphasis"><em>statements</em></span> }
821</pre>
822<p>
823        Repeatedly execute <span class="emphasis"><em>statements</em></span> while <span class="emphasis"><em>cond</em></span>
824        remains true upon entry. (See the description of <span class="emphasis"><em>cond</em></span>
825        expression syntax under if, above).
826      </p>
827</div>
828<div class="section" lang="en">
829<div class="titlepage"><div><div><h3 class="title">
830<a name="jam.language.variables"></a>Variables</h3></div></div></div>
831<div class="toc"><dl>
832<dt><span class="section"><a href="language.html#jam.language.variables.expansion"> Variable Expansion</a></span></dt>
833<dt><span class="section"><a href="language.html#jam.language.variables.local_for_loop_variables">Local For Loop Variables</a></span></dt>
834<dt><span class="section"><a href="language.html#jam.language.variables.builtins"> Built-in Variables</a></span></dt>
835</dl></div>
836<p>
837        <code class="literal">BJam</code> variables are lists of zero or more elements, with
838        each element being a string value. An undefined variable is indistinguishable
839        from a variable with an empty list, however, a defined variable may have
840        one more elements which are null strings. All variables are referenced as
841        <code class="literal">$(<span class="emphasis"><em>variable</em></span>)</code>.
842      </p>
843<p>
844        Variables are either global or target-specific. In the latter case, the variable
845        takes on the given value only during the updating of the specific target.
846      </p>
847<p>
848        A variable is defined with:
849      </p>
850<pre class="programlisting"><span class="emphasis"><em>variable</em></span> = <span class="emphasis"><em>elements</em></span> ;
851<span class="emphasis"><em>variable</em></span> += <span class="emphasis"><em>elements</em></span> ;
852<span class="emphasis"><em>variable</em></span> on <span class="emphasis"><em>targets</em></span> = <span class="emphasis"><em>elements</em></span> ;
853<span class="emphasis"><em>variable</em></span> on <span class="emphasis"><em>targets</em></span> += <span class="emphasis"><em>elements</em></span> ;
854<span class="emphasis"><em>variable</em></span> default = <span class="emphasis"><em>elements</em></span> ;
855<span class="emphasis"><em>variable</em></span> ?= <span class="emphasis"><em>elements</em></span> ;
856</pre>
857<p>
858        The first two forms set <span class="emphasis"><em>variable</em></span> globally. The third
859        and forth forms set a target-specific variable. The <code class="literal">=</code>
860        operator replaces any previous elements of <span class="emphasis"><em>variable</em></span>
861        with <span class="emphasis"><em>elements</em></span>; the <code class="literal">+=</code> operation adds
862        <span class="emphasis"><em>elements</em></span> to <span class="emphasis"><em>variable</em></span>'s list of
863        elements. The final two forms are synonymous: they set <span class="emphasis"><em>variable</em></span>
864        globally, but only if it was previously unset.
865      </p>
866<p>
867        Variables referenced in updating commands will be replaced with their values;
868        target-specific values take precedence over global values. Variables passed
869        as arguments (<code class="literal">$(1)</code> and <code class="literal">$(2)</code>) to actions
870        are replaced with their bound values; the "<code class="literal">bind</code>"
871        modifier can be used on actions to cause other variables to be replaced with
872        bound values. See Action Modifiers above.
873      </p>
874<p>
875        <code class="literal">BJam</code> variables are not re-exported to the environment
876        of the shell that executes the updating actions, but the updating actions
877        can reference <code class="literal">bjam</code> variables with <code class="literal">$(<span class="emphasis"><em>variable</em></span>)</code>.
878      </p>
879<div class="section" lang="en">
880<div class="titlepage"><div><div><h4 class="title">
881<a name="jam.language.variables.expansion"></a> Variable Expansion</h4></div></div></div>
882<p>
883          During parsing, <code class="literal">bjam</code> performs variable expansion on
884          each token that is not a keyword or rule name. Such tokens with embedded
885          variable references are replaced with zero or more tokens. Variable references
886          are of the form <code class="literal">$(<span class="emphasis"><em>v</em></span>)</code> or <code class="literal">$(<span class="emphasis"><em>vm</em></span>)</code>,
887          where <span class="emphasis"><em>v</em></span> is the variable name, and <span class="emphasis"><em>m</em></span>
888          are optional modifiers.
889        </p>
890<p>
891          Variable expansion in a rule's actions is similar to variable expansion
892          in statements, except that the action string is tokenized at whitespace
893          regardless of quoting.
894        </p>
895<p>
896          The result of a token after variable expansion is the <span class="emphasis"><em>product</em></span>
897          of the components of the token, where each component is a literal substring
898          or a list substituting a variable reference. For example:
899        </p>
900<pre class="programlisting">$(X) -&gt; a b c
901t$(X) -&gt; ta tb tc
902$(X)z -&gt; az bz cz
903$(X)-$(X) -&gt; a-a a-b a-c b-a b-b b-c c-a c-b c-c
904</pre>
905<p>
906          The variable name and modifiers can themselves contain a variable reference,
907          and this partakes of the product as well:
908        </p>
909<pre class="programlisting">$(X) -&gt; a b c
910$(Y) -&gt; 1 2
911$(Z) -&gt; X Y
912$($(Z)) -&gt; a b c 1 2
913</pre>
914<p>
915          Because of this product expansion, if any variable reference in a token
916          is undefined, the result of the expansion is an empty list. If any variable
917          element is a null string, the result propagates the non-null elements:
918        </p>
919<pre class="programlisting">$(X) -&gt; a ""
920$(Y) -&gt; "" 1
921$(Z) -&gt;
922-$(X)$(Y)- -&gt; -a- -a1- -- -1-
923-$(X)$(Z)- -&gt;
924</pre>
925<p>
926          A variable element's string value can be parsed into grist and filename-related
927          components. Modifiers to a variable are used to select elements, select
928          components, and replace components. The modifiers are:
929        </p>
930<div class="variablelist">
931<p class="title"><b></b></p>
932<dl>
933<dt><span class="term"><code class="literal">[<span class="emphasis"><em>n</em></span>]</code></span></dt>
934<dd>
935            Select element number <span class="emphasis"><em>n</em></span> (starting at 1). If the
936            variable contains fewer than <span class="emphasis"><em>n</em></span> elements, the result
937            is a zero-element list. <span class="emphasis"><em>n</em></span> can be negative in which
938            case the element number <span class="emphasis"><em>n</em></span> from the last leftward
939            is returned.
940          </dd>
941<dt><span class="term"><code class="literal">[<span class="emphasis"><em>n</em></span>-<span class="emphasis"><em>m</em></span>]</code></span></dt>
942<dd>
943            Select elements number <span class="emphasis"><em>n</em></span> through <span class="emphasis"><em>m</em></span>.
944            <span class="emphasis"><em>n</em></span> and <span class="emphasis"><em>m</em></span> can be negative in
945            which case they refer to elements counting from the last leftward.
946          </dd>
947<dt><span class="term"><code class="literal">[<span class="emphasis"><em>n</em></span>-]</code></span></dt>
948<dd>
949            Select elements number <span class="emphasis"><em>n</em></span> through the last. <span class="emphasis"><em>n</em></span>
950            can be negative in which case it refers to the element counting from
951            the last leftward.
952          </dd>
953<dt><span class="term"><code class="literal">:B</code></span></dt>
954<dd>
955            Select filename base.
956          </dd>
957<dt><span class="term"><code class="literal">:S</code></span></dt>
958<dd>
959            Select (last) filename suffix.
960          </dd>
961<dt><span class="term"><code class="literal">:M</code></span></dt>
962<dd>
963            Select archive member name.
964          </dd>
965<dt><span class="term"><code class="literal">:D</code></span></dt>
966<dd>
967            Select directory path.
968          </dd>
969<dt><span class="term"><code class="literal">:P</code></span></dt>
970<dd>
971            Select parent directory.
972          </dd>
973<dt><span class="term"><code class="literal">:G</code></span></dt>
974<dd>
975            Select grist.
976          </dd>
977<dt><span class="term"><code class="literal">:U</code></span></dt>
978<dd>
979            Replace lowercase characters with uppercase.
980          </dd>
981<dt><span class="term"><code class="literal">:L</code></span></dt>
982<dd>
983            Replace uppercase characters with lowercase.
984          </dd>
985<dt><span class="term"><code class="literal">:W</code></span></dt>
986<dd>
987            When invoking Windows-based tools from <a href="http://www.cygwin.com/" target="_top">Cygwin</a>
988            it can be important to pass them true windows-style paths. The <code class="literal">:W</code>
989            modifier, <span class="bold"><strong>under Cygwin only</strong></span>, turns a
990            cygwin path into a Win32 path using the <a href="http://www.cygwin.com/cygwin-api/func-cygwin-conv-to-win32-path.html" target="_top"><code class="literal">cygwin_conv_to_win32_path</code></a>
991            function. On other platforms, the string is unchanged. For example
992<pre class="programlisting">
993
994<span class="identifier">x</span> <span class="special">=</span> <span class="string">"/cygdrive/c/Program Files/Borland"</span> <span class="special">;</span> <span class="identifier">ECHO</span> #<span class="special">(</span><span class="identifier">x</span><span class="special">:</span><span class="identifier">W</span><span class="special">)</span> <span class="special">;</span>
995</pre>
996            prints <code class="literal">"C:\Program Files\Borland"</code> on Cygwin
997          </dd>
998<dt><span class="term"><code class="literal">:<span class="emphasis"><em>chars</em></span></code></span></dt>
999<dd>
1000            Select the components listed in <span class="emphasis"><em>chars</em></span>.
1001          </dd>
1002<dt><span class="term"><code class="literal">:G=<span class="emphasis"><em>grist</em></span></code></span></dt>
1003<dd>
1004            Replace grist with <span class="emphasis"><em>grist</em></span>.
1005          </dd>
1006<dt><span class="term"><code class="literal">:D=<span class="emphasis"><em>path</em></span></code></span></dt>
1007<dd>
1008            Replace directory with <span class="emphasis"><em>path</em></span>.
1009          </dd>
1010<dt><span class="term"><code class="literal">:B=<span class="emphasis"><em>base</em></span></code></span></dt>
1011<dd>
1012            Replace the base part of file name with <span class="emphasis"><em>base</em></span>.
1013          </dd>
1014<dt><span class="term"><code class="literal">:S=<span class="emphasis"><em>suf</em></span></code></span></dt>
1015<dd>
1016            Replace the suffix of file name with <span class="emphasis"><em>suf</em></span>.
1017          </dd>
1018<dt><span class="term"><code class="literal">:M=<span class="emphasis"><em>mem</em></span></code></span></dt>
1019<dd>
1020            Replace the archive member name with <span class="emphasis"><em>mem</em></span>.
1021          </dd>
1022<dt><span class="term"><code class="literal">:R=<span class="emphasis"><em>root</em></span></code></span></dt>
1023<dd>
1024            Prepend <span class="emphasis"><em>root</em></span> to the whole file name, if not already
1025            rooted.
1026          </dd>
1027<dt><span class="term"><code class="literal">:E=<span class="emphasis"><em>value</em></span></code></span></dt>
1028<dd>
1029            Assign <span class="emphasis"><em>value</em></span> to the variable if it is unset.
1030          </dd>
1031<dt><span class="term"><code class="literal">:J=<span class="emphasis"><em>joinval</em></span></code></span></dt>
1032<dd>
1033            Concatentate list elements into single element, separated by <span class="emphasis"><em>joinval</em></span>'.
1034          </dd>
1035</dl>
1036</div>
1037<p>
1038          On VMS, <code class="literal">$(var:P)</code> is the parent directory of <code class="literal">$(var:D)</code>.
1039        </p>
1040</div>
1041<div class="section" lang="en">
1042<div class="titlepage"><div><div><h4 class="title">
1043<a name="jam.language.variables.local_for_loop_variables"></a>Local For Loop Variables</h4></div></div></div>
1044<p>
1045          Boost Jam allows you to declare a local for loop control variable right
1046          in the loop:
1047        </p>
1048<pre class="programlisting">x = 1 2 3 ;
1049y = 4 5 6 ;
1050for <span class="bold"><strong>local</strong></span> y in $(x)
1051{
1052    ECHO $(y) ; # prints "1", "2", or "3"
1053}
1054ECHO $(y) ;     # prints "4 5 6"
1055</pre>
1056</div>
1057<div class="section" lang="en">
1058<div class="titlepage"><div><div><h4 class="title">
1059<a name="jam.language.variables.builtins"></a> Built-in Variables</h4></div></div></div>
1060<div class="toc"><dl>
1061<dt><span class="section"><a href="language.html#jam.language.variables.builtins.search"> SEARCH and LOCATE</a></span></dt>
1062<dt><span class="section"><a href="language.html#jam.language.variables.builtins.hdrscan"> HDRSCAN and HDRRULE</a></span></dt>
1063<dt><span class="section"><a href="language.html#jam.language.variables.builtins.semaphores">Semaphores</a></span></dt>
1064<dt><span class="section"><a href="language.html#jam.language.variables.builtins.platform_identifier">Platform Identifier</a></span></dt>
1065<dt><span class="section"><a href="language.html#jam.language.variables.builtins.jam_version">Jam Version</a></span></dt>
1066<dt><span class="section"><a href="language.html#jam.language.variables.builtins.jamshell">JAMSHELL</a></span></dt>
1067</dl></div>
1068<p>
1069          This section discusses variables that have special meaning to <code class="literal">bjam</code>.
1070        </p>
1071<div class="section" lang="en">
1072<div class="titlepage"><div><div><h5 class="title">
1073<a name="jam.language.variables.builtins.search"></a> SEARCH and LOCATE</h5></div></div></div>
1074<p>
1075            These two variables control the binding of file target names to locations
1076            in the file system. Generally, <code class="literal">$(SEARCH)</code> is used to
1077            find existing sources while <code class="literal">$(LOCATE)</code> is used to fix
1078            the location for built targets.
1079          </p>
1080<p>
1081            Rooted (absolute path) file targets are bound as is. Unrooted file target
1082            names are also normally bound as is, and thus relative to the current
1083            directory, but the settings of <code class="literal">$(LOCATE)</code> and <code class="literal">$(SEARCH)</code>
1084            alter this:
1085          </p>
1086<div class="itemizedlist"><ul type="disc">
1087<li>
1088              If <code class="literal">$(LOCATE)</code> is set then the target is bound relative
1089              to the first directory in <code class="literal">$(LOCATE)</code>. Only the first
1090              element is used for binding.
1091            </li>
1092<li>
1093              If <code class="literal">$(SEARCH)</code> is set then the target is bound to
1094              the first directory in <code class="literal">$(SEARCH)</code> where the target
1095              file already exists.
1096            </li>
1097<li>
1098              If the <code class="literal">$(SEARCH)</code> search fails, the target is bound
1099              relative to the current directory anyhow.
1100            </li>
1101</ul></div>
1102<p>
1103            Both <code class="literal">$(SEARCH)</code> and <code class="literal">$(LOCATE)</code> should
1104            be set target-specific and not globally. If they were set globally,
1105            <code class="literal">bjam</code> would use the same paths for all file binding,
1106            which is not likely to produce sane results. When writing your own rules,
1107            especially ones not built upon those in Jambase, you may need to set
1108            <code class="literal">$(SEARCH)</code> or <code class="literal">$(LOCATE)</code> directly.
1109            Almost all of the rules defined in Jambase set <code class="literal">$(SEARCH)</code>
1110            and <code class="literal">$(LOCATE)</code> to sensible values for sources they
1111            are looking for and targets they create, respectively.
1112          </p>
1113</div>
1114<div class="section" lang="en">
1115<div class="titlepage"><div><div><h5 class="title">
1116<a name="jam.language.variables.builtins.hdrscan"></a> HDRSCAN and HDRRULE</h5></div></div></div>
1117<p>
1118            These two variables control header file scanning. <code class="literal">$(HDRSCAN)</code>
1119            is an <code class="literal">egrep(1)</code> pattern, with ()'s surrounding the
1120            file name, used to find file inclusion statements in source files. <code class="literal">Jambase</code>
1121            uses <code class="literal">$(HDRPATTERN)</code> as the pattern for <code class="literal">$(HDRSCAN)</code>.
1122            <code class="literal">$(HDRRULE)</code> is the name of a rule to invoke with the
1123            results of the scan: the scanned file is the target, the found files
1124            are the sources. This is the only place where <code class="literal">bjam</code>
1125            invokes a rule through a variable setting.
1126          </p>
1127<p>
1128            Both <code class="literal">$(HDRSCAN)</code> and <code class="literal">$(HDRRULE)</code>
1129            must be set for header file scanning to take place, and they should be
1130            set target-specific and not globally. If they were set globally, all
1131            files, including executables and libraries, would be scanned for header
1132            file include statements.
1133          </p>
1134<p>
1135            The scanning for header file inclusions is not exact, but it is at least
1136            dynamic, so there is no need to run something like <code class="literal">makedepend(GNU)</code>
1137            to create a static dependency file. The scanning mechanism errs on the
1138            side of inclusion (i.e., it is more likely to return filenames that are
1139            not actually used by the compiler than to miss include files) because
1140            it can't tell if <code class="computeroutput"><span class="preprocessor">#include</span></code>
1141            lines are inside <code class="computeroutput"><span class="preprocessor">#ifdefs</span></code>
1142            or other conditional logic. In <code class="literal">Jambase</code>, <code class="literal">HdrRule</code>
1143            applies the <code class="literal">NOCARE</code> rule to each header file found
1144            during scanning so that if the file isn't present yet doesn't cause the
1145            compilation to fail, <code class="literal">bjam</code> won't care.
1146          </p>
1147<p>
1148            Also, scanning for regular expressions only works where the included
1149            file name is literally in the source file. It can't handle languages
1150            that allow including files using variable names (as the <code class="literal">Jam</code>
1151            language itself does).
1152          </p>
1153</div>
1154<div class="section" lang="en">
1155<div class="titlepage"><div><div><h5 class="title">
1156<a name="jam.language.variables.builtins.semaphores"></a>Semaphores</h5></div></div></div>
1157<p>
1158            It is sometimes desirable to disallow parallel execution of some actions.
1159            For example:
1160          </p>
1161<div class="itemizedlist"><ul type="disc">
1162<li>
1163              Old versions of yacc use files with fixed names. So, running two yacc
1164              actions is dangerous.
1165            </li>
1166<li>
1167              One might want to perform parallel compiling, but not do parallel linking,
1168              because linking is i/o bound and only gets slower.
1169            </li>
1170</ul></div>
1171<p>
1172            Craig McPeeters has extended Perforce Jam to solve such problems, and
1173            that extension was integrated in Boost.Jam.
1174          </p>
1175<p>
1176            Any target can be assigned a <span class="emphasis"><em>semaphore</em></span>, by setting
1177            a variable called <code class="literal">SEMAPHORE</code> on that target. The value
1178            of the variable is the semaphore name. It must be different from names
1179            of any declared target, but is arbitrary otherwise.
1180          </p>
1181<p>
1182            The semantic of semaphores is that in a group of targets which have the
1183            same semaphore, only one can be updated at the moment, regardless of
1184            "<code class="literal">-j</code>" option.
1185          </p>
1186</div>
1187<div class="section" lang="en">
1188<div class="titlepage"><div><div><h5 class="title">
1189<a name="jam.language.variables.builtins.platform_identifier"></a>Platform Identifier</h5></div></div></div>
1190<p>
1191            A number of Jam built-in variables can be used to identify runtime platform:
1192          </p>
1193<div class="variablelist">
1194<p class="title"><b></b></p>
1195<dl>
1196<dt><span class="term"><code class="literal">OS</code></span></dt>
1197<dd>
1198              OS identifier string
1199            </dd>
1200<dt><span class="term"><code class="literal">OSPLAT</code></span></dt>
1201<dd>
1202              Underlying architecture, when applicable
1203            </dd>
1204<dt><span class="term"><code class="literal">MAC</code></span></dt>
1205<dd>
1206              true on MAC platform
1207            </dd>
1208<dt><span class="term"><code class="literal">NT</code></span></dt>
1209<dd>
1210              true on NT platform
1211            </dd>
1212<dt><span class="term"><code class="literal">OS2</code></span></dt>
1213<dd>
1214              true on OS2 platform
1215            </dd>
1216<dt><span class="term"><code class="literal">UNIX</code></span></dt>
1217<dd>
1218              true on Unix platforms
1219            </dd>
1220<dt><span class="term"><code class="literal">VMS</code></span></dt>
1221<dd>
1222              true on VMS platform
1223            </dd>
1224</dl>
1225</div>
1226</div>
1227<div class="section" lang="en">
1228<div class="titlepage"><div><div><h5 class="title">
1229<a name="jam.language.variables.builtins.jam_version"></a>Jam Version</h5></div></div></div>
1230<div class="variablelist">
1231<p class="title"><b></b></p>
1232<dl>
1233<dt><span class="term"><code class="literal">JAMDATE</code></span></dt>
1234<dd>
1235              Time and date at <code class="literal">bjam</code> start-up.
1236            </dd>
1237<dt><span class="term"><code class="literal">JAMUNAME</code></span></dt>
1238<dd>
1239              Ouput of uname(1) command (Unix only)
1240            </dd>
1241<dt><span class="term"><code class="literal">JAMVERSION</code></span></dt>
1242<dd>
1243<code class="literal">bjam</code> version, currently "3.1.14"
1244            </dd>
1245<dt><span class="term"><code class="literal">JAM_VERSION</code></span></dt>
1246<dd>
1247              A predefined global variable with two elements indicates the version
1248              number of Boost Jam. Boost Jam versions start at "<code class="literal">03</code>"
1249              "<code class="literal">00</code>". Earlier versions of <code class="literal">Jam</code>
1250              do not automatically define <code class="literal">JAM_VERSION</code>.
1251            </dd>
1252</dl>
1253</div>
1254</div>
1255<div class="section" lang="en">
1256<div class="titlepage"><div><div><h5 class="title">
1257<a name="jam.language.variables.builtins.jamshell"></a>JAMSHELL</h5></div></div></div>
1258<p>
1259            When <code class="literal">bjam</code> executes a rule's action block, it forks
1260            and execs a shell, passing the action block as an argument to the shell.
1261            The invocation of the shell can be controlled by <code class="literal">$(JAMSHELL)</code>.
1262            The default on Unix is, for example:
1263          </p>
1264<pre class="programlisting">JAMSHELL = /bin/sh -c % ;
1265</pre>
1266<p>
1267            The <code class="literal">%</code> is replaced with the text of the action block.
1268          </p>
1269<p>
1270            <code class="literal">BJam</code> does not directly support building in parallel
1271            across multiple hosts, since that is heavily dependent on the local environment.
1272            To build in parallel across multiple hosts, you need to write your own
1273            shell that provides access to the multiple hosts. You then reset <code class="literal">$(JAMSHELL)</code>
1274            to reference it.
1275          </p>
1276<p>
1277            Just as <code class="literal">bjam</code> expands a <code class="literal">%</code> to be
1278            the text of the rule's action block, it expands a <code class="literal">!</code>
1279            to be the multi-process slot number. The slot number varies between 1
1280            and the number of concurrent jobs permitted by the <code class="literal">-j</code>
1281            flag given on the command line. Armed with this, it is possible to write
1282            a multiple host shell. For example:
1283          </p>
1284<pre class="programlisting">#!/bin/sh
1285
1286# This sample JAMSHELL uses the SunOS on(1) command to execute a
1287# command string with an identical environment on another host.
1288
1289# Set JAMSHELL = jamshell ! %
1290#
1291# where jamshell is the name of this shell file.
1292#
1293# This version handles up to -j6; after that they get executed
1294# locally.
1295
1296case $1 in
12971|4) on winken sh -c "$2";;
12982|5) on blinken sh -c "$2";;
12993|6) on nod sh -c "$2";;
1300*) eval "$2";;
1301esac
1302</pre>
1303</div>
1304</div>
1305</div>
1306<div class="section" lang="en">
1307<div class="titlepage"><div><div><h3 class="title">
1308<a name="jam.language.modules"></a>Modules</h3></div></div></div>
1309<div class="toc"><dl>
1310<dt><span class="section"><a href="language.html#jam.language.modules.declaration">Declaration</a></span></dt>
1311<dt><span class="section"><a href="language.html#jam.language.modules.variable_scope">Variable Scope</a></span></dt>
1312<dt><span class="section"><a href="language.html#jam.language.modules.local_rules">Local Rules</a></span></dt>
1313<dt><span class="section"><a href="language.html#jam.language.modules.the__rulenames__rule">The <code class="literal">RULENAMES</code> Rule</a></span></dt>
1314<dt><span class="section"><a href="language.html#jam.language.modules.the__varnames__rule">The <code class="literal">VARNAMES</code> Rule</a></span></dt>
1315<dt><span class="section"><a href="language.html#jam.language.modules.the__import__rule">The <code class="literal">IMPORT</code> Rule</a></span></dt>
1316<dt><span class="section"><a href="language.html#jam.language.modules.the__export__rule">The <code class="literal">EXPORT</code> Rule</a></span></dt>
1317<dt><span class="section"><a href="language.html#jam.language.modules.the__caller_module__rule">The <code class="literal">CALLER_MODULE</code> Rule</a></span></dt>
1318<dt><span class="section"><a href="language.html#jam.language.modules.the__delete_module__rule">The <code class="literal">DELETE_MODULE</code> Rule</a></span></dt>
1319</dl></div>
1320<p>
1321        Boost Jam introduces support for modules, which provide some rudimentary
1322        namespace protection for rules and variables. A new keyword, "<code class="literal">module</code>"
1323        was also introduced. The features described in this section are primitives,
1324        meaning that they are meant to provide the operations needed to write Jam
1325        rules which provide a more elegant module interface.
1326      </p>
1327<div class="section" lang="en">
1328<div class="titlepage"><div><div><h4 class="title">
1329<a name="jam.language.modules.declaration"></a>Declaration</h4></div></div></div>
1330<pre class="programlisting">module <span class="emphasis"><em>expression</em></span> { ... }
1331</pre>
1332<p>
1333          Code within the <code class="literal">{ ... }</code> executes within the module named
1334          by evaluating expression. Rule definitions can be found in the module's
1335          own namespace, and in the namespace of the global module as <span class="emphasis"><em>module-name</em></span>.<span class="emphasis"><em>rule-name</em></span>,
1336          so within a module, other rules in that module may always be invoked without
1337          qualification:
1338        </p>
1339<pre class="programlisting"><span class="bold"><strong>module my_module</strong></span>
1340<span class="bold"><strong>{</strong></span>
1341    rule salute ( x ) { ECHO $(x), world ; }
1342    rule greet ( ) { salute hello ; }
1343    greet ;
1344<span class="bold"><strong>}</strong></span>
1345<span class="bold"><strong>my_module.salute</strong></span> goodbye ;
1346</pre>
1347<p>
1348          When an invoked rule is not found in the current module's namespace, it
1349          is looked up in the namespace of the global module, so qualified calls
1350          work across modules:
1351        </p>
1352<pre class="programlisting">module your_module
1353{
1354    rule bedtime ( ) { <span class="bold"><strong>my_module.salute</strong></span> goodnight ; }
1355}
1356</pre>
1357</div>
1358<div class="section" lang="en">
1359<div class="titlepage"><div><div><h4 class="title">
1360<a name="jam.language.modules.variable_scope"></a>Variable Scope</h4></div></div></div>
1361<p>
1362          Each module has its own set of dynamically nested variable scopes. When
1363          execution passes from module A to module B, all the variable bindings from
1364          A become unavailable, and are replaced by the bindings that belong to B.
1365          This applies equally to local and global variables:
1366        </p>
1367<pre class="programlisting">module A
1368{
1369    x = 1 ;
1370    rule f ( )
1371    {
1372        local y = 999 ; # becomes visible again when B.f calls A.g
1373        B.f ;
1374    }
1375    rule g ( )
1376    {
1377        ECHO $(y) ;     # prints "999"
1378    }
1379}
1380module B
1381{
1382    y = 2 ;
1383    rule f ( )
1384    {
1385        ECHO $(y) ; # always prints "2"
1386        A.g ;
1387    }
1388}
1389</pre>
1390<p>
1391          The only way to access another module's variables is by entering that module:
1392        </p>
1393<pre class="programlisting">rule peek ( module-name ? : variables + )
1394{
1395    module $(module-name)
1396    {
1397        return $($(&gt;)) ;
1398    }
1399}
1400</pre>
1401<p>
1402          Note that because existing variable bindings change whenever a new module
1403          scope is entered, argument bindings become unavailable. That explains the
1404          use of "<code class="literal">$(&gt;)</code>" in the peek rule above.
1405        </p>
1406</div>
1407<div class="section" lang="en">
1408<div class="titlepage"><div><div><h4 class="title">
1409<a name="jam.language.modules.local_rules"></a>Local Rules</h4></div></div></div>
1410<pre class="programlisting">local rule <span class="emphasis"><em>rulename</em></span>...
1411</pre>
1412<p>
1413          The rule is declared locally to the current module. It is not entered in
1414          the global module with qualification, and its name will not appear in the
1415          result of:
1416        </p>
1417<pre class="programlisting">[ RULENAMES <span class="emphasis"><em>module-name</em></span> ]
1418</pre>
1419</div>
1420<div class="section" lang="en">
1421<div class="titlepage"><div><div><h4 class="title">
1422<a name="jam.language.modules.the__rulenames__rule"></a>The <code class="literal">RULENAMES</code> Rule</h4></div></div></div>
1423<pre class="programlisting">rule RULENAMES ( <span class="emphasis"><em>module</em></span> ? )
1424</pre>
1425<p>
1426          Returns a list of the names of all non-local rules in the given module.
1427          If <span class="emphasis"><em>module</em></span> is omitted, the names of all non-local rules
1428          in the global module are returned.
1429        </p>
1430</div>
1431<div class="section" lang="en">
1432<div class="titlepage"><div><div><h4 class="title">
1433<a name="jam.language.modules.the__varnames__rule"></a>The <code class="literal">VARNAMES</code> Rule</h4></div></div></div>
1434<pre class="programlisting">rule VARNAMES ( <span class="emphasis"><em>module</em></span> ? )
1435</pre>
1436<p>
1437          Returns a list of the names of all variable bindings in the given module.
1438          If <span class="emphasis"><em>module</em></span> is omitted, the names of all variable bindings
1439          in the global module are returned.
1440        </p>
1441<div class="note"><table border="0" summary="Note">
1442<tr>
1443<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
1444<th align="left">Note</th>
1445</tr>
1446<tr><td align="left" valign="top"><p>
1447            This includes any local variables in rules from the call stack which
1448            have not returned at the time of the <code class="literal">VARNAMES</code> invocation.
1449          </p></td></tr>
1450</table></div>
1451</div>
1452<div class="section" lang="en">
1453<div class="titlepage"><div><div><h4 class="title">
1454<a name="jam.language.modules.the__import__rule"></a>The <code class="literal">IMPORT</code> Rule</h4></div></div></div>
1455<p>
1456          <code class="literal">IMPORT</code> allows rule name aliasing across modules:
1457        </p>
1458<pre class="programlisting">rule IMPORT ( <span class="emphasis"><em>source_module</em></span> ? : <span class="emphasis"><em>source_rules</em></span> *
1459            : <span class="emphasis"><em>target_module</em></span> ? : <span class="emphasis"><em>target_rules</em></span> * )
1460</pre>
1461<p>
1462          The <code class="literal">IMPORT</code> rule copies rules from the <span class="emphasis"><em>source_module</em></span>
1463          into the <span class="emphasis"><em>target_module</em></span> as local rules. If either
1464          <span class="emphasis"><em>source_module</em></span> or <span class="emphasis"><em>target_module</em></span>
1465          is not supplied, it refers to the global module. <span class="emphasis"><em>source_rules</em></span>
1466          specifies which rules from the <span class="emphasis"><em>source_module</em></span> to import;
1467          <span class="emphasis"><em>target_rules</em></span> specifies the names to give those rules
1468          in <span class="emphasis"><em>target_module</em></span>. If <span class="emphasis"><em>source_rules</em></span>
1469          contains a name which doesn't correspond to a rule in <span class="emphasis"><em>source_module</em></span>,
1470          or if it contains a different number of items than <span class="emphasis"><em>target_rules</em></span>,
1471          an error is issued. For example,
1472        </p>
1473<pre class="programlisting"># import m1.rule1 into m2 as local rule m1-rule1.
1474IMPORT m1 : rule1 : m2 : m1-rule1 ;
1475# import all non-local rules from m1 into m2
1476IMPORT m1 : [ RULENAMES m1 ] : m2 : [ RULENAMES m1 ] ;
1477</pre>
1478</div>
1479<div class="section" lang="en">
1480<div class="titlepage"><div><div><h4 class="title">
1481<a name="jam.language.modules.the__export__rule"></a>The <code class="literal">EXPORT</code> Rule</h4></div></div></div>
1482<p>
1483          <code class="literal">EXPORT</code> allows rule name aliasing across modules:
1484        </p>
1485<pre class="programlisting">rule EXPORT ( <span class="emphasis"><em>module</em></span> ? : <span class="emphasis"><em>rules</em></span> * )
1486</pre>
1487<p>
1488          The <code class="literal">EXPORT</code> rule marks <span class="emphasis"><em>rules</em></span> from
1489          the <code class="literal">source_module</code> as non-local (and thus exportable).
1490          If an element of <span class="emphasis"><em>rules</em></span> does not name a rule in <span class="emphasis"><em>module</em></span>,
1491          an error is issued. For example,
1492        </p>
1493<pre class="programlisting">module X {
1494  local rule r { ECHO X.r ; }
1495}
1496IMPORT X : r : : r ; # error - r is local in X
1497EXPORT X : r ;
1498IMPORT X : r : : r ; # OK.
1499</pre>
1500</div>
1501<div class="section" lang="en">
1502<div class="titlepage"><div><div><h4 class="title">
1503<a name="jam.language.modules.the__caller_module__rule"></a>The <code class="literal">CALLER_MODULE</code> Rule</h4></div></div></div>
1504<pre class="programlisting">rule CALLER_MODULE ( <span class="emphasis"><em>levels</em></span> ? )
1505</pre>
1506<p>
1507          <code class="literal">CALLER_MODULE</code> returns the name of the module scope enclosing
1508          the call to its caller (if levels is supplied, it is interpreted as an
1509          integer number of additional levels of call stack to traverse to locate
1510          the module). If the scope belongs to the global module, or if no such module
1511          exists, returns the empty list. For example, the following prints "{Y}
1512          {X}":
1513        </p>
1514<pre class="programlisting">module X {
1515    rule get-caller { return [ CALLER_MODULE ] ; }
1516    rule get-caller's-caller { return [ CALLER_MODULE 1 ] ; }
1517    rule call-Y { return Y.call-X2 ; }
1518}
1519module Y {
1520    rule call-X { return X.get-caller ; }
1521    rule call-X2 { return X.get-caller's-caller ; }
1522}
1523callers = [ X.get-caller ] [ Y.call-X ] [ X.call-Y ] ;
1524ECHO {$(callers)} ;
1525</pre>
1526</div>
1527<div class="section" lang="en">
1528<div class="titlepage"><div><div><h4 class="title">
1529<a name="jam.language.modules.the__delete_module__rule"></a>The <code class="literal">DELETE_MODULE</code> Rule</h4></div></div></div>
1530<pre class="programlisting">rule DELETE_MODULE ( <span class="emphasis"><em>module</em></span> ? )
1531</pre>
1532<p>
1533          <code class="literal">DELETE_MODULE</code> removes all of the variable bindings and
1534          otherwise-unreferenced rules from the given module (or the global module,
1535          if no module is supplied), and returns their memory to the system.
1536        </p>
1537<div class="note"><table border="0" summary="Note">
1538<tr>
1539<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
1540<th align="left">Note</th>
1541</tr>
1542<tr><td align="left" valign="top"><p>
1543            Though it won't affect rules that are currently executing until they
1544            complete, <code class="literal">DELETE_MODULE</code> should be used with extreme
1545            care because it will wipe out any others and all variable (including
1546            locals in that module) immediately. Because of the way dynamic binding
1547            works, variables which are shadowed by locals will not be destroyed,
1548            so the results can be really unpredictable.
1549          </p></td></tr>
1550</table></div>
1551</div>
1552</div>
1553</div>
1554<table width="100%"><tr>
1555<td align="left"></td>
1556<td align="right"><small>Copyright © 2003-2006 Rene
1557      Rivera, David Abrahams, Vladimir Prus</small></td>
1558</tr></table>
1559<hr>
1560<div class="spirit-nav">
1561<a accesskey="p" href="usage.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../jam.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="miscellaneous.html"><img src="../images/next.png" alt="Next"></a>
1562</div>
1563</body>
1564</html>
Note: See TracBrowser for help on using the repository browser.