| <html> | |
| <head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> | |
| <title>Language</title> | |
| <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> | |
| <meta name="generator" content="DocBook XSL Stylesheets V1.75.2"> | |
| <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> | |
| <link rel="up" href="../jam.html" title="Chapter 32. Boost.Jam : 3.1.19"> | |
| <link rel="prev" href="usage.html" title="Using BJam"> | |
| <link rel="next" href="miscellaneous.html" title="Miscellaneous"> | |
| </head> | |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> | |
| <table cellpadding="2" width="100%"><tr> | |
| <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> | |
| <td align="center"><a href="../../../index.html">Home</a></td> | |
| <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> | |
| <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> | |
| <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> | |
| <td align="center"><a href="../../../more/index.htm">More</a></td> | |
| </tr></table> | |
| <hr> | |
| <div class="spirit-nav"> | |
| <a accesskey="p" href="usage.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../jam.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="miscellaneous.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | |
| <a name="jam.language"></a><a class="link" href="language.html" title="Language">Language</a> | |
| </h2></div></div></div> | |
| <div class="toc"><dl> | |
| <dt><span class="section"><a href="language.html#jam.language.lexical">Lexical Features</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.target">Targets</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.rules">Rules</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.flow_of_control">Flow-of-Control</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.variables">Variables</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.modules">Modules</a></span></dt> | |
| </dl></div> | |
| <p> | |
| <code class="literal">BJam</code> has an interpreted, procedural language. Statements | |
| in <code class="literal">bjam</code> are rule (procedure) definitions, rule invocations, | |
| flow-of-control structures, variable assignments, and sundry language support. | |
| </p> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h3 class="title"> | |
| <a name="jam.language.lexical"></a><a class="link" href="language.html#jam.language.lexical" title="Lexical Features">Lexical Features</a> | |
| </h3></div></div></div> | |
| <p> | |
| <code class="literal">BJam</code> treats its input files as whitespace-separated tokens, | |
| with two exceptions: double quotes (") can enclose whitespace to embed | |
| it into a token, and everything between the matching curly braces ({}) in | |
| the definition of a rule action is treated as a single string. A backslash | |
| (\) can escape a double quote, or any single whitespace character. | |
| </p> | |
| <p> | |
| <code class="literal">BJam</code> requires whitespace (blanks, tabs, or newlines) to | |
| surround all tokens, including the colon (:) and semicolon (;) tokens. | |
| </p> | |
| <p> | |
| <code class="literal">BJam</code> keywords (an mentioned in this document) are reserved | |
| and generally must be quoted with double quotes (") to be used as arbitrary | |
| tokens, such as variable or target names. | |
| </p> | |
| <p> | |
| Comments start with the <code class="literal">#</code> character and extend until the | |
| end of line. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h3 class="title"> | |
| <a name="jam.language.target"></a><a class="link" href="language.html#jam.language.target" title="Targets">Targets</a> | |
| </h3></div></div></div> | |
| <div class="toc"><dl><dt><span class="section"><a href="language.html#jam.language.target.binding_detection">Binding Detection</a></span></dt></dl></div> | |
| <p> | |
| The essential <code class="literal">bjam</code> data entity is a target. Build targets | |
| are files to be updated. Source targets are the files used in updating built | |
| targets. Built targets and source targets are collectively referred to as | |
| file targets, and frequently built targets are source targets for other built | |
| targets. Pseudotargets are symbols which represent dependencies on other | |
| targets, but which are not themselves associated with any real file. | |
| </p> | |
| <p> | |
| A file target's identifier is generally the file's name, which can be absolutely | |
| rooted, relative to the directory of <code class="literal">bjam</code>'s invocation, | |
| or simply local (no directory). Most often it is the last case, and the actual | |
| file path is bound using the <code class="literal">$(SEARCH)</code> and <code class="literal">$(LOCATE)</code> | |
| special variables. See <a class="link" href="language.html#jam.language.variables.builtins.search" title="SEARCH and LOCATE">SEARCH | |
| and LOCATE Variables</a> below. A local filename is optionally qualified | |
| with grist, a string value used to assure uniqueness. A file target with | |
| an identifier of the form <span class="emphasis"><em>file(member)</em></span> is a library | |
| member (usually an <code class="literal">ar</code>(1) archive on Unix). | |
| </p> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="jam.language.target.binding_detection"></a><a class="link" href="language.html#jam.language.target.binding_detection" title="Binding Detection">Binding Detection</a> | |
| </h4></div></div></div> | |
| <p> | |
| Whenever a target is bound to a location in the filesystem, Boost Jam will | |
| look for a variable called <code class="literal">BINDRULE</code> (first "on" | |
| the target being bound, then in the global module). If non-empty, =$(BINDRULE[1])= | |
| names a rule which is called with the name of the target and the path it | |
| is being bound to. The signature of the rule named by =$(BINDRULE[1])= | |
| should match the following: | |
| </p> | |
| <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> ) | |
| </pre> | |
| <p> | |
| This facility is useful for correct header file scanning, since many compilers | |
| will search for <code class="computeroutput"><span class="preprocessor">#include</span></code> | |
| 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> | |
| can be used to make a record of that directory. | |
| </p> | |
| </div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h3 class="title"> | |
| <a name="jam.language.rules"></a><a class="link" href="language.html#jam.language.rules" title="Rules">Rules</a> | |
| </h3></div></div></div> | |
| <div class="toc"><dl> | |
| <dt><span class="section"><a href="language.html#jam.language.rules.action_modifiers">Action Modifiers</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.rules.argument_lists">Argument lists</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.rules.builtins">Built-in Rules</a></span></dt> | |
| </dl></div> | |
| <p> | |
| The basic <code class="literal">bjam</code> language entity is called a rule. A rule | |
| is defined in two parts: the procedure and the actions. The procedure is | |
| a body of jam statements to be run when the rule is invoked; the actions | |
| are the OS shell commands to execute when updating the built targets of the | |
| rule. | |
| </p> | |
| <p> | |
| Rules can return values, which can be expanded into a list with "[ | |
| <span class="emphasis"><em>rule</em></span> <span class="emphasis"><em>args</em></span> ... ]". A rule's | |
| value is the value of its last statement, though only the following statements | |
| have values: 'if' (value of the leg chosen), 'switch' (value of the case | |
| chosen), set (value of the resulting variable), and 'return' (value of its | |
| arguments). Note that 'return' doesn't actually cause a return, i.e., is | |
| a no-op unless it is the last statement of the last block executed within | |
| rule body. | |
| </p> | |
| <p> | |
| The <code class="literal">bjam</code> statements for defining and invoking rules are | |
| as follows: | |
| </p> | |
| <p> | |
| Define a rule's procedure, replacing any previous definition. | |
| </p> | |
| <pre class="programlisting">rule <span class="emphasis"><em>rulename</em></span> { <span class="emphasis"><em>statements</em></span> } | |
| </pre> | |
| <p> | |
| Define a rule's updating actions, replacing any previous definition. | |
| </p> | |
| <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> } | |
| </pre> | |
| <p> | |
| Invoke a rule. | |
| </p> | |
| <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> ; | |
| </pre> | |
| <p> | |
| Invoke a rule under the influence of target's specific variables.. | |
| </p> | |
| <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> ; | |
| </pre> | |
| <p> | |
| Used as an argument, expands to the return value of the rule invoked. | |
| </p> | |
| <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> ] | |
| [ 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> ] | |
| </pre> | |
| <p> | |
| A rule is invoked with values in <span class="emphasis"><em>field1</em></span> through <span class="emphasis"><em>fieldN</em></span>. | |
| They may be referenced in the procedure's statements as <code class="literal">$(1)</code> | |
| through <code class="literal">$(<span class="emphasis"><em>N</em></span>)</code> (9 max), and the first | |
| two only may be referenced in the action's <span class="emphasis"><em>commands</em></span> | |
| as <code class="literal">$(1)</code> and <code class="literal">$(2)</code>. <code class="literal">$(<)</code> | |
| and <code class="literal">$(>)</code> are synonymous with <code class="literal">$(1)</code> | |
| and <code class="literal">$(2)</code>. | |
| </p> | |
| <p> | |
| Rules fall into two categories: updating rules (with actions), and pure procedure | |
| rules (without actions). Updating rules treat arguments <code class="literal">$(1)</code> | |
| and <code class="literal">$(2)</code> as built targets and sources, respectively, while | |
| pure procedure rules can take arbitrary arguments. | |
| </p> | |
| <p> | |
| When an updating rule is invoked, its updating actions are added to those | |
| associated with its built targets (<code class="literal">$(1)</code>) before the rule's | |
| procedure is run. Later, to build the targets in the updating phase, <span class="emphasis"><em>commands</em></span> | |
| are passed to the OS command shell, with <code class="literal">$(1)</code> and <code class="literal">$(2)</code> | |
| replaced by bound versions of the target names. See Binding above. | |
| </p> | |
| <p> | |
| Rule invocation may be indirected through a variable: | |
| </p> | |
| <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> ; | |
| 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> ; | |
| [ $(<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> ] | |
| [ 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> ] | |
| </pre> | |
| <p> | |
| The variable's value names the rule (or rules) to be invoked. A rule is invoked | |
| for each element in the list of <code class="literal">$(<span class="emphasis"><em>var</em></span>)</code>'s | |
| values. The fields <code class="literal"><span class="emphasis"><em>field1</em></span> : <span class="emphasis"><em>field2</em></span> | |
| : <span class="emphasis"><em>...</em></span></code> are passed as arguments for each invokation. | |
| For the [ ... ] forms, the return value is the concatenation of the return | |
| values for all of the invocations. | |
| </p> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="jam.language.rules.action_modifiers"></a><a class="link" href="language.html#jam.language.rules.action_modifiers" title="Action Modifiers">Action Modifiers</a> | |
| </h4></div></div></div> | |
| <p> | |
| The following action modifiers are understood: | |
| </p> | |
| <div class="variablelist"> | |
| <p class="title"><b></b></p> | |
| <dl> | |
| <dt><span class="term"><code class="literal">actions bind <span class="emphasis"><em>vars</em></span></code></span></dt> | |
| <dd><p> | |
| <code class="literal">$(<span class="emphasis"><em>vars</em></span>)</code> will be replaced | |
| with bound values. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">actions existing</code></span></dt> | |
| <dd><p> | |
| <code class="literal">$(>)</code> includes only source targets currently | |
| existing. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">actions ignore</code></span></dt> | |
| <dd><p> | |
| The return status of the commands is ignored. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">actions piecemeal</code></span></dt> | |
| <dd><p> | |
| commands are repeatedly invoked with a subset of <code class="literal">$(>)</code> | |
| small enough to fit in the command buffer on this OS. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">actions quietly</code></span></dt> | |
| <dd><p> | |
| The action is not echoed to the standard output. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">actions together</code></span></dt> | |
| <dd><p> | |
| The <code class="literal">$(>)</code> from multiple invocations of the same | |
| action on the same built target are glommed together. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">actions updated</code></span></dt> | |
| <dd><p> | |
| <code class="literal">$(>)</code> includes only source targets themselves | |
| marked for updating. | |
| </p></dd> | |
| </dl> | |
| </div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="jam.language.rules.argument_lists"></a><a class="link" href="language.html#jam.language.rules.argument_lists" title="Argument lists">Argument lists</a> | |
| </h4></div></div></div> | |
| <p> | |
| You can describe the arguments accepted by a rule, and refer to them by | |
| name within the rule. For example, the following prints "I'm sorry, | |
| Dave" to the console: | |
| </p> | |
| <pre class="programlisting">rule report ( pronoun index ? : state : names + ) | |
| { | |
| local he.suffix she.suffix it.suffix = s ; | |
| local I.suffix = m ; | |
| local they.suffix you.suffix = re ; | |
| ECHO $(pronoun)'$($(pronoun).suffix) $(state), $(names[$(index)]) ; | |
| } | |
| report I 2 : sorry : Joe Dave Pete ; | |
| </pre> | |
| <p> | |
| Each name in a list of formal arguments (separated by "<code class="literal">:</code>" | |
| in the rule declaration) is bound to a single element of the corresponding | |
| actual argument unless followed by one of these modifiers: | |
| </p> | |
| <div class="informaltable"><table class="table"> | |
| <colgroup> | |
| <col> | |
| <col> | |
| </colgroup> | |
| <thead><tr> | |
| <th> | |
| <p> | |
| Symbol | |
| </p> | |
| </th> | |
| <th> | |
| <p> | |
| Semantics of preceding symbol | |
| </p> | |
| </th> | |
| </tr></thead> | |
| <tbody> | |
| <tr> | |
| <td> | |
| <p> | |
| <code class="literal">?</code> | |
| </p> | |
| </td> | |
| <td> | |
| <p> | |
| optional | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td> | |
| <p> | |
| <code class="literal">*</code> | |
| </p> | |
| </td> | |
| <td> | |
| <p> | |
| Bind to zero or more unbound elements of the actual argument. | |
| When <code class="literal">*</code> appears where an argument name is expected, | |
| any number of additional arguments are accepted. This feature | |
| can be used to implement "varargs" rules. | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td> | |
| <p> | |
| <code class="literal">+</code> | |
| </p> | |
| </td> | |
| <td> | |
| <p> | |
| Bind to one or more unbound elements of the actual argument. | |
| </p> | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table></div> | |
| <p> | |
| The actual and formal arguments are checked for inconsistencies, which | |
| cause Jam to exit with an error code: | |
| </p> | |
| <pre class="programlisting">### argument error | |
| # rule report ( pronoun index ? : state : names + ) | |
| # called with: ( I 2 foo : sorry : Joe Dave Pete ) | |
| # extra argument foo | |
| ### argument error | |
| # rule report ( pronoun index ? : state : names + ) | |
| # called with: ( I 2 : sorry ) | |
| # missing argument names | |
| </pre> | |
| <p> | |
| If you omit the list of formal arguments, all checking is bypassed as in | |
| "classic" Jam. Argument lists drastically improve the reliability | |
| and readability of your rules, however, and are <span class="bold"><strong>strongly | |
| recommended</strong></span> for any new Jam code you write. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="jam.language.rules.builtins"></a><a class="link" href="language.html#jam.language.rules.builtins" title="Built-in Rules">Built-in Rules</a> | |
| </h4></div></div></div> | |
| <div class="toc"><dl> | |
| <dt><span class="section"><a href="language.html#jam.language.rules.builtins.dependency_building">Dependency | |
| Building</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.rules.builtins.modifying_binding">Modifying | |
| Binding</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.rules.builtins.utility">Utility</a></span></dt> | |
| </dl></div> | |
| <p> | |
| <code class="literal">BJam</code> has a growing set of built-in rules, all of which | |
| are pure procedure rules without updating actions. They are in three groups: | |
| the first builds the dependency graph; the second modifies it; and the | |
| third are just utility rules. | |
| </p> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="jam.language.rules.builtins.dependency_building"></a><a class="link" href="language.html#jam.language.rules.builtins.dependency_building" title="Dependency Building">Dependency | |
| Building</a> | |
| </h5></div></div></div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.dependency_building._depends__"></a><a class="link" href="language.html#jam.language.rules.builtins.dependency_building._depends__" title="DEPENDS"><code class="literal">DEPENDS</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule DEPENDS ( <span class="emphasis"><em>targets1</em></span> * : <span class="emphasis"><em>targets2</em></span> * ) | |
| </pre> | |
| <p> | |
| Builds a direct dependency: makes each of <span class="emphasis"><em>targets1</em></span> | |
| depend on each of <span class="emphasis"><em>targets2</em></span>. Generally, <span class="emphasis"><em>targets1</em></span> | |
| will be rebuilt if <span class="emphasis"><em>targets2</em></span> are themselves rebuilt | |
| or are newer than <span class="emphasis"><em>targets1</em></span>. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.dependency_building._includes__"></a><a class="link" href="language.html#jam.language.rules.builtins.dependency_building._includes__" title="INCLUDES"><code class="literal">INCLUDES</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule INCLUDES ( <span class="emphasis"><em>targets1</em></span> * : <span class="emphasis"><em>targets2</em></span> * ) | |
| </pre> | |
| <p> | |
| Builds a sibling dependency: makes any target that depends on any of | |
| <span class="emphasis"><em>targets1</em></span> also depend on each of <span class="emphasis"><em>targets2</em></span>. | |
| This reflects the dependencies that arise when one source file includes | |
| another: the object built from the source file depends both on the | |
| original and included source file, but the two sources files don't | |
| depend on each other. For example: | |
| </p> | |
| <pre class="programlisting">DEPENDS foo.o : foo.c ; | |
| INCLUDES foo.c : foo.h ; | |
| </pre> | |
| <p> | |
| "<code class="literal">foo.o</code>" depends on "<code class="literal">foo.c</code>" | |
| and "<code class="literal">foo.h</code>" in this example. | |
| </p> | |
| </div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="jam.language.rules.builtins.modifying_binding"></a><a class="link" href="language.html#jam.language.rules.builtins.modifying_binding" title="Modifying Binding">Modifying | |
| Binding</a> | |
| </h5></div></div></div> | |
| <p> | |
| The six rules <code class="literal">ALWAYS</code>, <code class="literal">LEAVES</code>, | |
| <code class="literal">NOCARE</code>, <code class="literal">NOTFILE</code>, <code class="literal">NOUPDATE</code>, | |
| and <code class="literal">TEMPORARY</code> modify the dependency graph so that | |
| <code class="literal">bjam</code> treats the targets differently during its target | |
| binding phase. See Binding above. Normally, <code class="literal">bjam</code> updates | |
| a target if it is missing, if its filesystem modification time is older | |
| than any of its dependencies (recursively), or if any of its dependencies | |
| are being updated. This basic behavior can be changed by invoking the | |
| following rules: | |
| </p> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.modifying_binding._always__"></a><a class="link" href="language.html#jam.language.rules.builtins.modifying_binding._always__" title="ALWAYS"><code class="literal">ALWAYS</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule ALWAYS ( <span class="emphasis"><em>targets</em></span> * ) | |
| </pre> | |
| <p> | |
| Causes <span class="emphasis"><em>targets</em></span> to be rebuilt regardless of whether | |
| they are up-to-date (they must still be in the dependency graph). This | |
| is used for the clean and uninstall targets, as they have no dependencies | |
| and would otherwise appear never to need building. It is best applied | |
| to targets that are also <code class="literal">NOTFILE</code> targets, but it | |
| can also be used to force a real file to be updated as well. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.modifying_binding._leaves__"></a><a class="link" href="language.html#jam.language.rules.builtins.modifying_binding._leaves__" title="LEAVES"><code class="literal">LEAVES</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule LEAVES ( <span class="emphasis"><em>targets</em></span> * ) | |
| </pre> | |
| <p> | |
| Makes each of <span class="emphasis"><em>targets</em></span> depend only on its leaf | |
| sources, and not on any intermediate targets. This makes it immune | |
| to its dependencies being updated, as the "leaf" dependencies | |
| are those without their own dependencies and without updating actions. | |
| This allows a target to be updated only if original source files change. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.modifying_binding._nocare__"></a><a class="link" href="language.html#jam.language.rules.builtins.modifying_binding._nocare__" title="NOCARE"><code class="literal">NOCARE</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule NOCARE ( <span class="emphasis"><em>targets</em></span> * ) | |
| </pre> | |
| <p> | |
| Causes <code class="literal">bjam</code> to ignore <span class="emphasis"><em>targets</em></span> | |
| that neither can be found nor have updating actions to build them. | |
| Normally for such targets <code class="literal">bjam</code> issues a warning | |
| and then skips other targets that depend on these missing targets. | |
| The <code class="literal">HdrRule</code> in <code class="literal">Jambase</code> uses | |
| <code class="literal">NOCARE</code> on the header file names found during header | |
| file scanning, to let <code class="literal">bjam</code> 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 actually be around. | |
| </p> | |
| <div class="warning"><table border="0" summary="Warning"> | |
| <tr> | |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/src/images/warning.png"></td> | |
| <th align="left">Warning</th> | |
| </tr> | |
| <tr><td align="left" valign="top"><p> | |
| For targets with build actions: if their build actions exit with | |
| a nonzero return code, dependent targets will still be built. | |
| </p></td></tr> | |
| </table></div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.modifying_binding._notfile__"></a><a class="link" href="language.html#jam.language.rules.builtins.modifying_binding._notfile__" title="NOTFILE"><code class="literal">NOTFILE</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule NOTFILE ( <span class="emphasis"><em>targets</em></span> * ) | |
| </pre> | |
| <p> | |
| Marks <span class="emphasis"><em>targets</em></span> as pseudotargets and not real files. | |
| No timestamp is checked, and so the actions on such a target are only | |
| executed if the target's dependencies are updated, or if the target | |
| is also marked with <code class="literal">ALWAYS</code>. The default <code class="literal">bjam</code> | |
| target "<code class="literal">all</code>" is a pseudotarget. In <code class="literal">Jambase</code>, | |
| <code class="literal">NOTFILE</code> is used to define several addition convenient | |
| pseudotargets. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.modifying_binding._noupdate__"></a><a class="link" href="language.html#jam.language.rules.builtins.modifying_binding._noupdate__" title="NOUPDATE"><code class="literal">NOUPDATE</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule NOUPDATE ( <span class="emphasis"><em>targets</em></span> * ) | |
| </pre> | |
| <p> | |
| Causes the timestamps on <span class="emphasis"><em>targets</em></span> to be ignored. | |
| This has two effects: first, once the target has been created it will | |
| never be updated; second, manually updating target will not cause other | |
| targets to be updated. In <code class="literal">Jambase</code>, for example, | |
| this rule is applied to directories by the <code class="literal">MkDir</code> | |
| rule, because <code class="literal">MkDir</code> only cares that the target directory | |
| exists, not when it has last been updated. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.modifying_binding._temporary__"></a><a class="link" href="language.html#jam.language.rules.builtins.modifying_binding._temporary__" title="TEMPORARY"><code class="literal">TEMPORARY</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule TEMPORARY ( <span class="emphasis"><em>targets</em></span> * ) | |
| </pre> | |
| <p> | |
| Marks <span class="emphasis"><em>targets</em></span> as temporary, allowing them to be | |
| removed after other targets that depend upon them have been updated. | |
| If a <code class="literal">TEMPORARY</code> target is missing, <code class="literal">bjam</code> | |
| uses the timestamp of the target's parent. <code class="literal">Jambase</code> | |
| uses <code class="literal">TEMPORARY</code> to mark object files that are archived | |
| in a library after they are built, so that they can be deleted after | |
| they are archived. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.modifying_binding._fail_expected__"></a><a class="link" href="language.html#jam.language.rules.builtins.modifying_binding._fail_expected__" title="FAIL_EXPECTED"><code class="literal">FAIL_EXPECTED</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule FAIL_EXPECTED ( <span class="emphasis"><em>targets</em></span> * ) | |
| </pre> | |
| <p> | |
| For handling targets whose build actions are expected to fail (e.g. | |
| when testing that assertions or compile-time type checking work properly), | |
| Boost Jam supplies the <code class="literal">FAIL_EXPECTED</code> rule in the | |
| same style as <code class="literal">NOCARE</code>, et. al. During target updating, | |
| the return code of the build actions for arguments to <code class="literal">FAIL_EXPECTED</code> | |
| is inverted: if it fails, building of dependent targets continues as | |
| though it succeeded. If it succeeds, dependent targets are skipped. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.modifying_binding._rmold__"></a><a class="link" href="language.html#jam.language.rules.builtins.modifying_binding._rmold__" title="RMOLD"><code class="literal">RMOLD</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule RMOLD ( <span class="emphasis"><em>targets</em></span> * ) | |
| </pre> | |
| <p> | |
| <code class="literal">BJam</code> removes any target files that may exist on | |
| disk when the rule used to build those targets fails. However, targets | |
| whose dependencies fail to build are not removed by default. The <code class="literal">RMOLD</code> | |
| rule causes its arguments to be removed if any of their dependencies | |
| fail to build. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.modifying_binding._isfile__"></a><a class="link" href="language.html#jam.language.rules.builtins.modifying_binding._isfile__" title="ISFILE"><code class="literal">ISFILE</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule ISFILE ( <span class="emphasis"><em>targets</em></span> * ) | |
| </pre> | |
| <p> | |
| <code class="literal">ISFILE</code> marks targets as required to be files. This | |
| changes the way <code class="literal">bjam</code> searches for the target such | |
| that it ignores mathes for file system items that are not file, like | |
| 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 to have a directory named exception in the header search | |
| path. | |
| </p> | |
| <div class="warning"><table border="0" summary="Warning"> | |
| <tr> | |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/src/images/warning.png"></td> | |
| <th align="left">Warning</th> | |
| </tr> | |
| <tr><td align="left" valign="top"><p> | |
| This is currently not fully implemented. | |
| </p></td></tr> | |
| </table></div> | |
| </div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="jam.language.rules.builtins.utility"></a><a class="link" href="language.html#jam.language.rules.builtins.utility" title="Utility">Utility</a> | |
| </h5></div></div></div> | |
| <p> | |
| The two rules <code class="literal">ECHO</code> and <code class="literal">EXIT</code> are | |
| utility rules, used only in <code class="literal">bjam</code>'s parsing phase. | |
| </p> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.utility._echo__"></a><a class="link" href="language.html#jam.language.rules.builtins.utility._echo__" title="ECHO"><code class="literal">ECHO</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule ECHO ( <span class="emphasis"><em>args</em></span> * ) | |
| </pre> | |
| <p> | |
| Blurts out the message <span class="emphasis"><em>args</em></span> to stdout. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.utility._exit__"></a><a class="link" href="language.html#jam.language.rules.builtins.utility._exit__" title="EXIT"><code class="literal">EXIT</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule EXIT ( <span class="emphasis"><em>message</em></span> * : <span class="emphasis"><em>result-value</em></span> ? ) | |
| </pre> | |
| <p> | |
| Blurts out the <span class="emphasis"><em>message</em></span> to stdout and then exits | |
| with a failure status if no <span class="emphasis"><em>result-value</em></span> is given, | |
| otherwise it exits with the given <span class="emphasis"><em>result-value</em></span>. | |
| </p> | |
| <p> | |
| "<code class="literal">Echo</code>", "<code class="literal">echo</code>", | |
| "<code class="literal">Exit</code>", and "<code class="literal">exit</code>" | |
| are accepted as aliases for <code class="literal">ECHO</code> and <code class="literal">EXIT</code>, | |
| since it is hard to tell that these are built-in rules and not part | |
| of the language, like "<code class="literal">include</code>". | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.utility._glob__"></a><a class="link" href="language.html#jam.language.rules.builtins.utility._glob__" title="GLOB"><code class="literal">GLOB</code> | |
| </a> | |
| </h6></div></div></div> | |
| <p> | |
| The <code class="literal">GLOB</code> rule does filename globbing. | |
| </p> | |
| <pre class="programlisting">rule GLOB ( <span class="emphasis"><em>directories</em></span> * : <span class="emphasis"><em>patterns</em></span> * : <span class="emphasis"><em>downcase-opt</em></span> ? ) | |
| </pre> | |
| <p> | |
| Using the same wildcards as for the patterns in the switch statement. | |
| It is invoked by being used as an argument to a rule invocation inside | |
| of "<code class="literal">[ ]</code>". For example: "<code class="literal">FILES | |
| = [ GLOB dir1 dir2 : *.c *.h ]</code>" sets <code class="literal">FILES</code> | |
| to the list of C source and header files in <code class="literal">dir1</code> | |
| and <code class="literal">dir2</code>. The resulting filenames are the full pathnames, | |
| including the directory, but the pattern is applied only to the file | |
| name without the directory. | |
| </p> | |
| <p> | |
| If <span class="emphasis"><em>downcase-opt</em></span> is supplied, filenames are converted | |
| to all-lowercase before matching against the pattern; you can use this | |
| to do case-insensitive matching using lowercase patterns. The paths | |
| returned will still have mixed case if the OS supplies them. On Windows | |
| NT and Cygwin, filenames are always downcased before matching. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.utility._match__"></a><a class="link" href="language.html#jam.language.rules.builtins.utility._match__" title="MATCH"><code class="literal">MATCH</code> | |
| </a> | |
| </h6></div></div></div> | |
| <p> | |
| The <code class="literal">MATCH</code> rule does pattern matching. | |
| </p> | |
| <pre class="programlisting">rule MATCH ( <span class="emphasis"><em>regexps</em></span> + : <span class="emphasis"><em>list</em></span> * ) | |
| </pre> | |
| <p> | |
| Matches the <code class="literal">egrep</code>(1) style regular expressions | |
| <span class="emphasis"><em>regexps</em></span> against the strings in <span class="emphasis"><em>list</em></span>. | |
| The result is the concatenation of matching <code class="literal">()</code> subexpressions | |
| for each string in <span class="emphasis"><em>list</em></span>, and for each regular | |
| expression in <span class="emphasis"><em>regexps</em></span>. Only useful within the | |
| "<code class="literal">[ ]</code>" construct, to change the result | |
| into a list. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.utility._backtrace__"></a><a class="link" href="language.html#jam.language.rules.builtins.utility._backtrace__" title="BACKTRACE"><code class="literal">BACKTRACE</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule BACKTRACE ( ) | |
| </pre> | |
| <p> | |
| 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>..., describing | |
| each shallower level of the call stack. This rule can be used to generate | |
| useful diagnostic messages from Jam rules. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.utility._update__"></a><a class="link" href="language.html#jam.language.rules.builtins.utility._update__" title="UPDATE"><code class="literal">UPDATE</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule UPDATE ( <span class="emphasis"><em>targets</em></span> * ) | |
| </pre> | |
| <p> | |
| Classic jam treats any non-option element of command line as a name | |
| of target to be updated. This prevented more sophisticated handling | |
| of command line. This is now enabled again but with additional changes | |
| to the <code class="literal">UPDATE</code> rule to allow for the flexibility | |
| of changing the list of targets to update. The UPDATE rule has two | |
| effects: | |
| </p> | |
| <div class="orderedlist"><ol class="orderedlist" type="1"> | |
| <li class="listitem"> | |
| It clears the list of targets to update, and | |
| </li> | |
| <li class="listitem"> | |
| Causes the specified targets to be updated. | |
| </li> | |
| </ol></div> | |
| <p> | |
| If no target was specified with the <code class="literal">UPDATE</code> rule, | |
| no targets will be updated. To support changing of the update list | |
| in more useful ways, the rule also returns the targets previously in | |
| the update list. This makes it possible to add targets as such: | |
| </p> | |
| <pre class="programlisting">local previous-updates = [ UPDATE ] ; | |
| UPDATE $(previous-updates) a-new-target ; | |
| </pre> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.utility._w32_getreg__"></a><a class="link" href="language.html#jam.language.rules.builtins.utility._w32_getreg__" title="W32_GETREG"><code class="literal">W32_GETREG</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule W32_GETREG ( <span class="emphasis"><em>path</em></span> : <span class="emphasis"><em>data</em></span> ? ) | |
| </pre> | |
| <p> | |
| Defined only for win32 platform. It reads the registry of Windows. | |
| '<span class="emphasis"><em>path</em></span>' is the location of the information, and | |
| '<span class="emphasis"><em>data</em></span>' is the name of the value which we want | |
| to get. If '<span class="emphasis"><em>data</em></span>' is omitted, the default value | |
| of '<span class="emphasis"><em>path</em></span>' will be returned. The '<span class="emphasis"><em>path</em></span>' | |
| value must conform to MS key path format and must be prefixed with | |
| one of the predefined root keys. As usual, | |
| </p> | |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | |
| <li class="listitem"> | |
| '<code class="literal">HKLM</code>' is equivalent to '<code class="literal">HKEY_LOCAL_MACHINE</code>'. | |
| </li> | |
| <li class="listitem"> | |
| '<code class="literal">HKCU</code>' is equivalent to '<code class="literal">HKEY_CURRENT_USER</code>'. | |
| </li> | |
| <li class="listitem"> | |
| '<code class="literal">HKCR</code>' is equivalent to '<code class="literal">HKEY_CLASSES_ROOT</code>'. | |
| </li> | |
| </ul></div> | |
| <p> | |
| Other predefined root keys are not supported. | |
| </p> | |
| <p> | |
| Currently supported data types : '<code class="literal">REG_DWORD</code>', '<code class="literal">REG_SZ</code>', | |
| '<code class="literal">REG_EXPAND_SZ</code>', '<code class="literal">REG_MULTI_SZ</code>'. | |
| The data with '<code class="literal">REG_DWORD</code>' type will be turned into | |
| a string, '<code class="literal">REG_MULTI_SZ</code>' into a list of strings, | |
| and for those with '<code class="literal">REG_EXPAND_SZ</code>' type environment | |
| variables in it will be replaced with their defined values. The data | |
| with '<code class="literal">REG_SZ</code>' type and other unsupported types will | |
| be put into a string without modification. If it can't receive the | |
| value of the data, it just return an empty list. For example, | |
| </p> | |
| <pre class="programlisting">local PSDK-location = | |
| [ W32_GETREG HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\MicrosoftSDK\\Directories : "Install Dir" ] ; | |
| </pre> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.utility._w32_getregnames__"></a><a class="link" href="language.html#jam.language.rules.builtins.utility._w32_getregnames__" title="W32_GETREGNAMES"><code class="literal">W32_GETREGNAMES</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule W32_GETREGNAMES ( <span class="emphasis"><em>path</em></span> : <span class="emphasis"><em>result-type</em></span> ) | |
| </pre> | |
| <p> | |
| Defined only for win32 platform. It reads the registry of Windows. | |
| '<span class="emphasis"><em>path</em></span>' is the location of the information, and | |
| '<span class="emphasis"><em>result-type</em></span>' is either '<code class="literal">subkeys</code>' | |
| or '<code class="literal">values</code>'. For more information on '<span class="emphasis"><em>path</em></span>' | |
| format and constraints, please see <code class="literal">W32_GETREG</code>. | |
| </p> | |
| <p> | |
| Depending on '<span class="emphasis"><em>result-type</em></span>', the rule returns one | |
| of the following: | |
| </p> | |
| <div class="variablelist"> | |
| <p class="title"><b></b></p> | |
| <dl> | |
| <dt><span class="term"><code class="literal">subkeys</code></span></dt> | |
| <dd><p> | |
| Names of all direct subkeys of '<span class="emphasis"><em>path</em></span>'. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">values</code></span></dt> | |
| <dd><p> | |
| Names of values contained in registry key given by '<span class="emphasis"><em>path</em></span>'. | |
| The "default" value of the key appears in the returned | |
| list only if its value has been set in the registry. | |
| </p></dd> | |
| </dl> | |
| </div> | |
| <p> | |
| If '<span class="emphasis"><em>result-type</em></span>' is not recognized, or requested | |
| data cannot be retrieved, the rule returns an empty list. Example: | |
| </p> | |
| <pre class="programlisting">local key = "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths" ; | |
| local subkeys = [ W32_GETREGNAMES "$(key)" : subkeys ] ; | |
| for local subkey in $(subkeys) | |
| { | |
| local values = [ W32_GETREGNAMES "$(key)\\$(subkey)" : values ] ; | |
| for local value in $(values) | |
| { | |
| local data = [ W32_GETREG "$(key)\\$(subkey)" : "$(value)" ] ; | |
| ECHO "Registry path: " $(key)\\$(subkey) ":" $(value) "=" $(data) ; | |
| } | |
| } | |
| </pre> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.utility._shell__"></a><a class="link" href="language.html#jam.language.rules.builtins.utility._shell__" title="SHELL"><code class="literal">SHELL</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule SHELL ( <span class="emphasis"><em>command</em></span> : * ) | |
| </pre> | |
| <p> | |
| <code class="literal">SHELL</code> executes <span class="emphasis"><em>command</em></span>, and | |
| then returns the standard output of <span class="emphasis"><em>command</em></span>. | |
| <code class="literal">SHELL</code> only works on platforms with a <code class="literal">popen()</code> | |
| function in the C library. On platforms without a working <code class="literal">popen()</code> | |
| function, <code class="literal">SHELL</code> is implemented as a no-op. <code class="literal">SHELL</code> | |
| works on Unix, MacOS X, and most Windows compilers. <code class="literal">SHELL</code> | |
| is a no-op on Metrowerks compilers under Windows. There is a variable | |
| set of allowed options as additional arguments: | |
| </p> | |
| <div class="variablelist"> | |
| <p class="title"><b></b></p> | |
| <dl> | |
| <dt><span class="term"><code class="literal">exit-status</code></span></dt> | |
| <dd><p> | |
| In addition to the output the result status of the executed command | |
| is returned as a second element of the result. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">no-output</code></span></dt> | |
| <dd><p> | |
| Don't capture the output of the command. Instead an empty ("") | |
| string value is returned in place of the output. | |
| </p></dd> | |
| </dl> | |
| </div> | |
| <p> | |
| Because the Perforce/Jambase defines a <code class="literal">SHELL</code> rule | |
| which hides the builtin rule, <code class="literal">COMMAND</code> can be used | |
| as an alias for <code class="literal">SHELL</code> in such a case. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.utility._md5__"></a><a class="link" href="language.html#jam.language.rules.builtins.utility._md5__" title="MD5"><code class="literal">MD5</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule MD5 ( <span class="emphasis"><em>string</em></span> ) | |
| </pre> | |
| <p> | |
| <code class="literal">MD5</code> computes the MD5 hash of the string passed as | |
| paramater and returns it. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.utility._split_by_characters__"></a><a class="link" href="language.html#jam.language.rules.builtins.utility._split_by_characters__" title="SPLIT_BY_CHARACTERS"><code class="literal">SPLIT_BY_CHARACTERS</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule SPLIT_BY_CHARACTERS ( <span class="emphasis"><em>string</em></span> : <span class="emphasis"><em>delimiters</em></span> ) | |
| </pre> | |
| <p> | |
| <code class="literal">SPLIT_BY_CHARACTERS</code> splits the specified <span class="emphasis"><em>string</em></span> | |
| on any delimiter character present in <span class="emphasis"><em>delimiters</em></span> | |
| and returns the resulting list. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.utility._precious__"></a><a class="link" href="language.html#jam.language.rules.builtins.utility._precious__" title="PRECIOUS"><code class="literal">PRECIOUS</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule PRECIOUS ( <span class="emphasis"><em>targets</em></span> * ) | |
| </pre> | |
| <p> | |
| The <code class="literal">PRECIOUS</code> rule specifies that each of the targets | |
| passed as the arguments should not be removed even if the command updating | |
| that target fails. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.utility._pad__"></a><a class="link" href="language.html#jam.language.rules.builtins.utility._pad__" title="PAD"><code class="literal">PAD</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule PAD ( <span class="emphasis"><em>string</em></span> : <span class="emphasis"><em>width</em></span> ) | |
| </pre> | |
| <p> | |
| If <span class="emphasis"><em>string</em></span> is shorter than <span class="emphasis"><em>width</em></span> | |
| characters, pads it with whitespace characters on the right, and returns | |
| the result. Otherwise, returns <span class="emphasis"><em>string</em></span> unmodified. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.utility._file_open__"></a><a class="link" href="language.html#jam.language.rules.builtins.utility._file_open__" title="FILE_OPEN"><code class="literal">FILE_OPEN</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule FILE_OPEN ( <span class="emphasis"><em>filename</em></span> : <span class="emphasis"><em>mode</em></span> ) | |
| </pre> | |
| <p> | |
| The <code class="literal">FILE_OPEN</code> rule opens the specified file and | |
| returns a file descriptor. The <span class="emphasis"><em>mode</em></span> parameter | |
| can be either "w" or "r". Note that at present, | |
| only the <code class="literal">UPDATE_NOW</code> rule can use the resulting file | |
| descriptor number. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="jam.language.rules.builtins.utility._update_now__"></a><a class="link" href="language.html#jam.language.rules.builtins.utility._update_now__" title="UPDATE_NOW"><code class="literal">UPDATE_NOW</code> | |
| </a> | |
| </h6></div></div></div> | |
| <pre class="programlisting">rule UPDATE_NOW ( <span class="emphasis"><em>targets</em></span> * : <span class="emphasis"><em>log</em></span> ? : <span class="emphasis"><em>ignore-minus-n</em></span> ? ) | |
| </pre> | |
| <p> | |
| The <code class="literal">UPDATE_NOW</code> caused the specified targets to be | |
| updated immediately. If update was successfull, non-empty string is | |
| returned. The <span class="emphasis"><em>log</em></span> parameter, if present, specifies | |
| a descriptor of a file where all output from building is redirected. | |
| If the <span class="emphasis"><em>ignore-minus-n</em></span> parameter is specified, | |
| the targets are updated even if the <code class="literal">-n</code> parameter | |
| is specified on the command line. | |
| </p> | |
| </div> | |
| </div> | |
| </div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h3 class="title"> | |
| <a name="jam.language.flow_of_control"></a><a class="link" href="language.html#jam.language.flow_of_control" title="Flow-of-Control">Flow-of-Control</a> | |
| </h3></div></div></div> | |
| <p> | |
| <code class="literal">BJam</code> has several simple flow-of-control statements: | |
| </p> | |
| <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> } | |
| </pre> | |
| <p> | |
| Executes <span class="emphasis"><em>statements</em></span> for each element in <span class="emphasis"><em>list</em></span>, | |
| setting the variable <span class="emphasis"><em>var</em></span> to the element value. | |
| </p> | |
| <pre class="programlisting">if <span class="emphasis"><em>cond</em></span> { <span class="emphasis"><em>statements</em></span> } | |
| [ else { <span class="emphasis"><em>statements</em></span> } ] | |
| </pre> | |
| <p> | |
| Does the obvious; the <code class="literal">else</code> clause is optional. <span class="emphasis"><em>cond</em></span> | |
| is built of: | |
| </p> | |
| <div class="variablelist"> | |
| <p class="title"><b></b></p> | |
| <dl> | |
| <dt><span class="term"><code class="literal"><span class="emphasis"><em>a</em></span></code></span></dt> | |
| <dd><p> | |
| true if any <span class="emphasis"><em>a</em></span> element is a non-zero-length string | |
| </p></dd> | |
| <dt><span class="term"><code class="literal"><span class="emphasis"><em>a</em></span> = <span class="emphasis"><em>b</em></span></code></span></dt> | |
| <dd><p> | |
| list <span class="emphasis"><em>a</em></span> matches list <span class="emphasis"><em>b</em></span> string-for-string | |
| </p></dd> | |
| <dt><span class="term"><code class="literal"><span class="emphasis"><em>a</em></span> != <span class="emphasis"><em>b</em></span></code></span></dt> | |
| <dd><p> | |
| list <span class="emphasis"><em>a</em></span> does not match list <span class="emphasis"><em>b</em></span> | |
| </p></dd> | |
| <dt><span class="term"><code class="literal"><span class="emphasis"><em>a</em></span> < <span class="emphasis"><em>b</em></span></code></span></dt> | |
| <dd><p> | |
| <span class="emphasis"><em>a[i]</em></span> string is less than <span class="emphasis"><em>b[i]</em></span> | |
| string, where <span class="emphasis"><em>i</em></span> is first mismatched element in | |
| lists <span class="emphasis"><em>a</em></span> and <span class="emphasis"><em>b</em></span> | |
| </p></dd> | |
| <dt><span class="term"><code class="literal"><span class="emphasis"><em>a</em></span> <= <span class="emphasis"><em>b</em></span></code></span></dt> | |
| <dd><p> | |
| every <span class="emphasis"><em>a</em></span> string is less than or equal to its <span class="emphasis"><em>b</em></span> | |
| counterpart | |
| </p></dd> | |
| <dt><span class="term"><code class="literal"><span class="emphasis"><em>a</em></span> > <span class="emphasis"><em>b</em></span></code></span></dt> | |
| <dd><p> | |
| <span class="emphasis"><em>a[i]</em></span> string is greater than <span class="emphasis"><em>b[i]</em></span> | |
| string, where <span class="emphasis"><em>i</em></span> is first mismatched element | |
| </p></dd> | |
| <dt><span class="term"><code class="literal"><span class="emphasis"><em>a</em></span> >= <span class="emphasis"><em>b</em></span></code></span></dt> | |
| <dd><p> | |
| every <span class="emphasis"><em>a</em></span> string is greater than or equal to its | |
| <span class="emphasis"><em>b</em></span> counterpart | |
| </p></dd> | |
| <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> | |
| <dd><p> | |
| true if all elements of <span class="emphasis"><em>a</em></span> can be found in <span class="emphasis"><em>b</em></span>, | |
| or if <span class="emphasis"><em>a</em></span> has no elements | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">! <span class="emphasis"><em>cond</em></span></code></span></dt> | |
| <dd><p> | |
| condition not true | |
| </p></dd> | |
| <dt><span class="term"><code class="literal"><span class="emphasis"><em>cond</em></span> && <span class="emphasis"><em>cond</em></span></code></span></dt> | |
| <dd><p> | |
| conjunction | |
| </p></dd> | |
| <dt><span class="term"><code class="literal"><span class="emphasis"><em>cond</em></span> || <span class="emphasis"><em>cond</em></span></code></span></dt> | |
| <dd><p> | |
| disjunction | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">( <span class="emphasis"><em>cond</em></span> )</code></span></dt> | |
| <dd><p> | |
| precedence grouping | |
| </p></dd> | |
| </dl> | |
| </div> | |
| <pre class="programlisting">include <span class="emphasis"><em>file</em></span> ; | |
| </pre> | |
| <p> | |
| Causes <code class="literal">bjam</code> to read the named <span class="emphasis"><em>file</em></span>. | |
| The <span class="emphasis"><em>file</em></span> is bound like a regular target (see Binding | |
| above) but unlike a regular target the include <span class="emphasis"><em>file</em></span> | |
| cannot be built. | |
| </p> | |
| <p> | |
| The include <span class="emphasis"><em>file</em></span> is inserted into the input stream during | |
| the parsing phase. The primary input file and all the included file(s) are | |
| treated as a single file; that is, jam infers no scope boundaries from included | |
| files. | |
| </p> | |
| <pre class="programlisting">local <span class="emphasis"><em>vars</em></span> [ = <span class="emphasis"><em>values</em></span> ] ; | |
| </pre> | |
| <p> | |
| Creates new <span class="emphasis"><em>vars</em></span> inside to the enclosing <code class="literal">{}</code> | |
| block, obscuring any previous values they might have. The previous values | |
| for vars are restored when the current block ends. Any rule called or file | |
| included will see the local and not the previous value (this is sometimes | |
| called Dynamic Scoping). The local statement may appear anywhere, even outside | |
| of a block (in which case the previous value is restored when the input ends). | |
| The <span class="emphasis"><em>vars</em></span> are initialized to <span class="emphasis"><em>values</em></span> | |
| if present, or left uninitialized otherwise. | |
| </p> | |
| <pre class="programlisting">return <span class="emphasis"><em>values</em></span> ; | |
| </pre> | |
| <p> | |
| Within a rule body, the return statement sets the return value for an invocation | |
| of the rule. It does <span class="bold"><strong>not</strong></span> cause the rule | |
| to return; a rule's value is actually the value of the last statement executed, | |
| so a return should be the last statement executed before the rule "naturally" | |
| returns. | |
| </p> | |
| <pre class="programlisting">switch <span class="emphasis"><em>value</em></span> | |
| { | |
| case <span class="emphasis"><em>pattern1</em></span> : <span class="emphasis"><em>statements</em></span> ; | |
| case <span class="emphasis"><em>pattern2</em></span> : <span class="emphasis"><em>statements</em></span> ; | |
| ... | |
| } | |
| </pre> | |
| <p> | |
| The switch statement executes zero or one of the enclosed <span class="emphasis"><em>statements</em></span>, | |
| depending on which, if any, is the first case whose <span class="emphasis"><em>pattern</em></span> | |
| matches <span class="emphasis"><em>value</em></span>. The <span class="emphasis"><em>pattern</em></span> values | |
| are not variable-expanded. The pattern values may include the following wildcards: | |
| </p> | |
| <div class="variablelist"> | |
| <p class="title"><b></b></p> | |
| <dl> | |
| <dt><span class="term"><code class="literal">?</code></span></dt> | |
| <dd><p> | |
| match any single character | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">*</code></span></dt> | |
| <dd><p> | |
| match zero or more characters | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">[<span class="emphasis"><em>chars</em></span>]</code></span></dt> | |
| <dd><p> | |
| match any single character in <span class="emphasis"><em>chars</em></span> | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">[^<span class="emphasis"><em>chars</em></span>]</code></span></dt> | |
| <dd><p> | |
| match any single character not in <span class="emphasis"><em>chars</em></span> | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">\<span class="emphasis"><em>x</em></span></code></span></dt> | |
| <dd><p> | |
| match <span class="emphasis"><em>x</em></span> (escapes the other wildcards) | |
| </p></dd> | |
| </dl> | |
| </div> | |
| <pre class="programlisting">while <span class="emphasis"><em>cond</em></span> { <span class="emphasis"><em>statements</em></span> } | |
| </pre> | |
| <p> | |
| Repeatedly execute <span class="emphasis"><em>statements</em></span> while <span class="emphasis"><em>cond</em></span> | |
| remains true upon entry. (See the description of <span class="emphasis"><em>cond</em></span> | |
| expression syntax under if, above). | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h3 class="title"> | |
| <a name="jam.language.variables"></a><a class="link" href="language.html#jam.language.variables" title="Variables">Variables</a> | |
| </h3></div></div></div> | |
| <div class="toc"><dl> | |
| <dt><span class="section"><a href="language.html#jam.language.variables.expansion">Variable Expansion</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.variables.local_for_loop_variables">Local | |
| For Loop Variables</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.variables.atfile">Generated File Expansion</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.variables.builtins">Built-in Variables</a></span></dt> | |
| </dl></div> | |
| <p> | |
| <code class="literal">BJam</code> variables are lists of zero or more elements, with | |
| each element being a string value. An undefined variable is indistinguishable | |
| from a variable with an empty list, however, a defined variable may have | |
| one more elements which are null strings. All variables are referenced as | |
| <code class="literal">$(<span class="emphasis"><em>variable</em></span>)</code>. | |
| </p> | |
| <p> | |
| Variables are either global or target-specific. In the latter case, the variable | |
| takes on the given value only during the updating of the specific target. | |
| </p> | |
| <p> | |
| A variable is defined with: | |
| </p> | |
| <pre class="programlisting"><span class="emphasis"><em>variable</em></span> = <span class="emphasis"><em>elements</em></span> ; | |
| <span class="emphasis"><em>variable</em></span> += <span class="emphasis"><em>elements</em></span> ; | |
| <span class="emphasis"><em>variable</em></span> on <span class="emphasis"><em>targets</em></span> = <span class="emphasis"><em>elements</em></span> ; | |
| <span class="emphasis"><em>variable</em></span> on <span class="emphasis"><em>targets</em></span> += <span class="emphasis"><em>elements</em></span> ; | |
| <span class="emphasis"><em>variable</em></span> default = <span class="emphasis"><em>elements</em></span> ; | |
| <span class="emphasis"><em>variable</em></span> ?= <span class="emphasis"><em>elements</em></span> ; | |
| </pre> | |
| <p> | |
| The first two forms set <span class="emphasis"><em>variable</em></span> globally. The third | |
| and forth forms set a target-specific variable. The <code class="literal">=</code> | |
| operator replaces any previous elements of <span class="emphasis"><em>variable</em></span> | |
| with <span class="emphasis"><em>elements</em></span>; the <code class="literal">+=</code> operation adds | |
| <span class="emphasis"><em>elements</em></span> to <span class="emphasis"><em>variable</em></span>'s list of | |
| elements. The final two forms are synonymous: they set <span class="emphasis"><em>variable</em></span> | |
| globally, but only if it was previously unset. | |
| </p> | |
| <p> | |
| Variables referenced in updating commands will be replaced with their values; | |
| target-specific values take precedence over global values. Variables passed | |
| as arguments (<code class="literal">$(1)</code> and <code class="literal">$(2)</code>) to actions | |
| are replaced with their bound values; the "<code class="literal">bind</code>" | |
| modifier can be used on actions to cause other variables to be replaced with | |
| bound values. See Action Modifiers above. | |
| </p> | |
| <p> | |
| <code class="literal">BJam</code> variables are not re-exported to the environment | |
| of the shell that executes the updating actions, but the updating actions | |
| can reference <code class="literal">bjam</code> variables with <code class="literal">$(<span class="emphasis"><em>variable</em></span>)</code>. | |
| </p> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="jam.language.variables.expansion"></a><a class="link" href="language.html#jam.language.variables.expansion" title="Variable Expansion">Variable Expansion</a> | |
| </h4></div></div></div> | |
| <p> | |
| During parsing, <code class="literal">bjam</code> performs variable expansion on | |
| each token that is not a keyword or rule name. Such tokens with embedded | |
| variable references are replaced with zero or more tokens. Variable references | |
| 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>, | |
| where <span class="emphasis"><em>v</em></span> is the variable name, and <span class="emphasis"><em>m</em></span> | |
| are optional modifiers. | |
| </p> | |
| <p> | |
| Variable expansion in a rule's actions is similar to variable expansion | |
| in statements, except that the action string is tokenized at whitespace | |
| regardless of quoting. | |
| </p> | |
| <p> | |
| The result of a token after variable expansion is the <span class="emphasis"><em>product</em></span> | |
| of the components of the token, where each component is a literal substring | |
| or a list substituting a variable reference. For example: | |
| </p> | |
| <pre class="programlisting">$(X) -> a b c | |
| t$(X) -> ta tb tc | |
| $(X)z -> az bz cz | |
| $(X)-$(X) -> a-a a-b a-c b-a b-b b-c c-a c-b c-c | |
| </pre> | |
| <p> | |
| The variable name and modifiers can themselves contain a variable reference, | |
| and this partakes of the product as well: | |
| </p> | |
| <pre class="programlisting">$(X) -> a b c | |
| $(Y) -> 1 2 | |
| $(Z) -> X Y | |
| $($(Z)) -> a b c 1 2 | |
| </pre> | |
| <p> | |
| Because of this product expansion, if any variable reference in a token | |
| is undefined, the result of the expansion is an empty list. If any variable | |
| element is a null string, the result propagates the non-null elements: | |
| </p> | |
| <pre class="programlisting">$(X) -> a "" | |
| $(Y) -> "" 1 | |
| $(Z) -> | |
| -$(X)$(Y)- -> -a- -a1- -- -1- | |
| -$(X)$(Z)- -> | |
| </pre> | |
| <p> | |
| A variable element's string value can be parsed into grist and filename-related | |
| components. Modifiers to a variable are used to select elements, select | |
| components, and replace components. The modifiers are: | |
| </p> | |
| <div class="variablelist"> | |
| <p class="title"><b></b></p> | |
| <dl> | |
| <dt><span class="term"><code class="literal">[<span class="emphasis"><em>n</em></span>]</code></span></dt> | |
| <dd><p> | |
| Select element number <span class="emphasis"><em>n</em></span> (starting at 1). If | |
| the variable contains fewer than <span class="emphasis"><em>n</em></span> elements, | |
| the result is a zero-element list. <span class="emphasis"><em>n</em></span> can be | |
| negative in which case the element number <span class="emphasis"><em>n</em></span> | |
| from the last leftward is returned. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">[<span class="emphasis"><em>n</em></span>-<span class="emphasis"><em>m</em></span>]</code></span></dt> | |
| <dd><p> | |
| Select elements number <span class="emphasis"><em>n</em></span> through <span class="emphasis"><em>m</em></span>. | |
| <span class="emphasis"><em>n</em></span> and <span class="emphasis"><em>m</em></span> can be negative | |
| in which case they refer to elements counting from the last leftward. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">[<span class="emphasis"><em>n</em></span>-]</code></span></dt> | |
| <dd><p> | |
| Select elements number <span class="emphasis"><em>n</em></span> through the last. | |
| <span class="emphasis"><em>n</em></span> can be negative in which case it refers to | |
| the element counting from the last leftward. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">:B</code></span></dt> | |
| <dd><p> | |
| Select filename base. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">:S</code></span></dt> | |
| <dd><p> | |
| Select (last) filename suffix. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">:M</code></span></dt> | |
| <dd><p> | |
| Select archive member name. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">:D</code></span></dt> | |
| <dd><p> | |
| Select directory path. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">:P</code></span></dt> | |
| <dd><p> | |
| Select parent directory. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">:G</code></span></dt> | |
| <dd><p> | |
| Select grist. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">:U</code></span></dt> | |
| <dd><p> | |
| Replace lowercase characters with uppercase. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">:L</code></span></dt> | |
| <dd><p> | |
| Replace uppercase characters with lowercase. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">:T</code></span></dt> | |
| <dd> | |
| <p> | |
| Converts all back-slashes ("\") to forward slashes ("/"). | |
| For example | |
| </p> | |
| <pre class="programlisting"><span class="identifier">x</span> <span class="special">=</span> <span class="string">"C:\\Program Files\\Borland"</span> <span class="special">;</span> <span class="identifier">ECHO</span> <span class="error">$</span><span class="special">(</span><span class="identifier">x</span><span class="special">:</span><span class="identifier">T</span><span class="special">)</span> <span class="special">;</span> | |
| </pre> | |
| <p> | |
| prints <code class="literal">"C:/Program Files/Borland"</code> | |
| </p> | |
| </dd> | |
| <dt><span class="term"><code class="literal">:W</code></span></dt> | |
| <dd> | |
| <p> | |
| When invoking Windows-based tools from <a href="http://www.cygwin.com/" target="_top">Cygwin</a> | |
| it can be important to pass them true windows-style paths. The <code class="literal">:W</code> | |
| modifier, <span class="bold"><strong>under Cygwin only</strong></span>, turns | |
| a 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> | |
| function. On other platforms, the string is unchanged. For example | |
| </p> | |
| <pre class="programlisting"><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="error">$</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> | |
| </pre> | |
| <p> | |
| prints <code class="literal">"C:\Program Files\Borland"</code> on | |
| Cygwin | |
| </p> | |
| </dd> | |
| <dt><span class="term"><code class="literal">:<span class="emphasis"><em>chars</em></span></code></span></dt> | |
| <dd><p> | |
| Select the components listed in <span class="emphasis"><em>chars</em></span>. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">:G=<span class="emphasis"><em>grist</em></span></code></span></dt> | |
| <dd><p> | |
| Replace grist with <span class="emphasis"><em>grist</em></span>. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">:D=<span class="emphasis"><em>path</em></span></code></span></dt> | |
| <dd><p> | |
| Replace directory with <span class="emphasis"><em>path</em></span>. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">:B=<span class="emphasis"><em>base</em></span></code></span></dt> | |
| <dd><p> | |
| Replace the base part of file name with <span class="emphasis"><em>base</em></span>. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">:S=<span class="emphasis"><em>suf</em></span></code></span></dt> | |
| <dd><p> | |
| Replace the suffix of file name with <span class="emphasis"><em>suf</em></span>. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">:M=<span class="emphasis"><em>mem</em></span></code></span></dt> | |
| <dd><p> | |
| Replace the archive member name with <span class="emphasis"><em>mem</em></span>. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">:R=<span class="emphasis"><em>root</em></span></code></span></dt> | |
| <dd><p> | |
| Prepend <span class="emphasis"><em>root</em></span> to the whole file name, if not | |
| already rooted. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">:E=<span class="emphasis"><em>value</em></span></code></span></dt> | |
| <dd><p> | |
| Assign <span class="emphasis"><em>value</em></span> to the variable if it is unset. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">:J=<span class="emphasis"><em>joinval</em></span></code></span></dt> | |
| <dd><p> | |
| Concatentate list elements into single element, separated by <span class="emphasis"><em>joinval</em></span>'. | |
| </p></dd> | |
| </dl> | |
| </div> | |
| <p> | |
| On VMS, <code class="literal">$(var:P)</code> is the parent directory of <code class="literal">$(var:D)</code>. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="jam.language.variables.local_for_loop_variables"></a><a class="link" href="language.html#jam.language.variables.local_for_loop_variables" title="Local For Loop Variables">Local | |
| For Loop Variables</a> | |
| </h4></div></div></div> | |
| <p> | |
| Boost Jam allows you to declare a local for loop control variable right | |
| in the loop: | |
| </p> | |
| <pre class="programlisting">x = 1 2 3 ; | |
| y = 4 5 6 ; | |
| for <span class="bold"><strong>local</strong></span> y in $(x) | |
| { | |
| ECHO $(y) ; # prints "1", "2", or "3" | |
| } | |
| ECHO $(y) ; # prints "4 5 6" | |
| </pre> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="jam.language.variables.atfile"></a><a class="link" href="language.html#jam.language.variables.atfile" title="Generated File Expansion">Generated File Expansion</a> | |
| </h4></div></div></div> | |
| <p> | |
| During expansion of expressions <code class="literal">bjam</code> also looks for | |
| subexpressions of the form =@(filename:E<code class="literal">filecontents)</code> | |
| and replaces the expression with <code class="literal">filename</code> after creating | |
| the given file with the contents set to <code class="literal">filecontents</code>. | |
| This is useful for creating compiler response files, and other "internal" | |
| files. The expansion works both during parsing and action execution. Hence | |
| it is possible to create files during any of the three build phases. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="jam.language.variables.builtins"></a><a class="link" href="language.html#jam.language.variables.builtins" title="Built-in Variables">Built-in Variables</a> | |
| </h4></div></div></div> | |
| <div class="toc"><dl> | |
| <dt><span class="section"><a href="language.html#jam.language.variables.builtins.search">SEARCH and | |
| LOCATE</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.variables.builtins.hdrscan">HDRSCAN | |
| and HDRRULE</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.variables.builtins.semaphores">Semaphores</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.variables.builtins.platform_identifier">Platform | |
| Identifier</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.variables.builtins.jam_version">Jam | |
| Version</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.variables.builtins.jamshell">JAMSHELL</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.variables.builtins.actionrule"><code class="literal">__TIMING_RULE__</code> | |
| and <code class="literal">__ACTION_RULE__</code></a></span></dt> | |
| </dl></div> | |
| <p> | |
| This section discusses variables that have special meaning to <code class="literal">bjam</code>. | |
| All of these must be defined or used in the global module -- using those | |
| variables inside a named module will not have the desired effect. See | |
| <a class="link" href="language.html#jam.language.modules" title="Modules">Modules</a>. | |
| </p> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="jam.language.variables.builtins.search"></a><a class="link" href="language.html#jam.language.variables.builtins.search" title="SEARCH and LOCATE">SEARCH and | |
| LOCATE</a> | |
| </h5></div></div></div> | |
| <p> | |
| These two variables control the binding of file target names to locations | |
| in the file system. Generally, <code class="literal">$(SEARCH)</code> is used to | |
| find existing sources while <code class="literal">$(LOCATE)</code> is used to fix | |
| the location for built targets. | |
| </p> | |
| <p> | |
| Rooted (absolute path) file targets are bound as is. Unrooted file target | |
| names are also normally bound as is, and thus relative to the current | |
| directory, but the settings of <code class="literal">$(LOCATE)</code> and <code class="literal">$(SEARCH)</code> | |
| alter this: | |
| </p> | |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | |
| <li class="listitem"> | |
| If <code class="literal">$(LOCATE)</code> is set then the target is bound relative | |
| to the first directory in <code class="literal">$(LOCATE)</code>. Only the | |
| first element is used for binding. | |
| </li> | |
| <li class="listitem"> | |
| If <code class="literal">$(SEARCH)</code> is set then the target is bound to | |
| the first directory in <code class="literal">$(SEARCH)</code> where the target | |
| file already exists. | |
| </li> | |
| <li class="listitem"> | |
| If the <code class="literal">$(SEARCH)</code> search fails, the target is bound | |
| relative to the current directory anyhow. | |
| </li> | |
| </ul></div> | |
| <p> | |
| Both <code class="literal">$(SEARCH)</code> and <code class="literal">$(LOCATE)</code> should | |
| be set target-specific and not globally. If they were set globally, | |
| <code class="literal">bjam</code> would use the same paths for all file binding, | |
| which is not likely to produce sane results. When writing your own rules, | |
| especially ones not built upon those in Jambase, you may need to set | |
| <code class="literal">$(SEARCH)</code> or <code class="literal">$(LOCATE)</code> directly. | |
| Almost all of the rules defined in Jambase set <code class="literal">$(SEARCH)</code> | |
| and <code class="literal">$(LOCATE)</code> to sensible values for sources they | |
| are looking for and targets they create, respectively. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="jam.language.variables.builtins.hdrscan"></a><a class="link" href="language.html#jam.language.variables.builtins.hdrscan" title="HDRSCAN and HDRRULE">HDRSCAN | |
| and HDRRULE</a> | |
| </h5></div></div></div> | |
| <p> | |
| These two variables control header file scanning. <code class="literal">$(HDRSCAN)</code> | |
| is an <code class="literal">egrep(1)</code> pattern, with ()'s surrounding the | |
| file name, used to find file inclusion statements in source files. <code class="literal">Jambase</code> | |
| uses <code class="literal">$(HDRPATTERN)</code> as the pattern for <code class="literal">$(HDRSCAN)</code>. | |
| <code class="literal">$(HDRRULE)</code> is the name of a rule to invoke with the | |
| results of the scan: the scanned file is the target, the found files | |
| are the sources. This is the only place where <code class="literal">bjam</code> | |
| invokes a rule through a variable setting. | |
| </p> | |
| <p> | |
| Both <code class="literal">$(HDRSCAN)</code> and <code class="literal">$(HDRRULE)</code> | |
| must be set for header file scanning to take place, and they should be | |
| set target-specific and not globally. If they were set globally, all | |
| files, including executables and libraries, would be scanned for header | |
| file include statements. | |
| </p> | |
| <p> | |
| The scanning for header file inclusions is not exact, but it is at least | |
| dynamic, so there is no need to run something like <code class="literal">makedepend(GNU)</code> | |
| to create a static dependency file. The scanning mechanism errs on the | |
| side of inclusion (i.e., it is more likely to return filenames that are | |
| not actually used by the compiler than to miss include files) because | |
| it can't tell if <code class="computeroutput"><span class="preprocessor">#include</span></code> | |
| lines are inside <code class="computeroutput"><span class="preprocessor">#ifdefs</span></code> | |
| or other conditional logic. In <code class="literal">Jambase</code>, <code class="literal">HdrRule</code> | |
| applies the <code class="literal">NOCARE</code> rule to each header file found | |
| during scanning so that if the file isn't present yet doesn't cause the | |
| compilation to fail, <code class="literal">bjam</code> won't care. | |
| </p> | |
| <p> | |
| Also, scanning for regular expressions only works where the included | |
| file name is literally in the source file. It can't handle languages | |
| that allow including files using variable names (as the <code class="literal">Jam</code> | |
| language itself does). | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="jam.language.variables.builtins.semaphores"></a><a class="link" href="language.html#jam.language.variables.builtins.semaphores" title="Semaphores">Semaphores</a> | |
| </h5></div></div></div> | |
| <p> | |
| It is sometimes desirable to disallow parallel execution of some actions. | |
| For example: | |
| </p> | |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | |
| <li class="listitem"> | |
| Old versions of yacc use files with fixed names. So, running two | |
| yacc actions is dangerous. | |
| </li> | |
| <li class="listitem"> | |
| One might want to perform parallel compiling, but not do parallel | |
| linking, because linking is i/o bound and only gets slower. | |
| </li> | |
| </ul></div> | |
| <p> | |
| Craig McPeeters has extended Perforce Jam to solve such problems, and | |
| that extension was integrated in Boost.Jam. | |
| </p> | |
| <p> | |
| Any target can be assigned a <span class="emphasis"><em>semaphore</em></span>, by setting | |
| a variable called <code class="literal">SEMAPHORE</code> on that target. The value | |
| of the variable is the semaphore name. It must be different from names | |
| of any declared target, but is arbitrary otherwise. | |
| </p> | |
| <p> | |
| The semantic of semaphores is that in a group of targets which have the | |
| same semaphore, only one can be updated at the moment, regardless of | |
| "<code class="literal">-j</code>" option. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="jam.language.variables.builtins.platform_identifier"></a><a class="link" href="language.html#jam.language.variables.builtins.platform_identifier" title="Platform Identifier">Platform | |
| Identifier</a> | |
| </h5></div></div></div> | |
| <p> | |
| A number of Jam built-in variables can be used to identify runtime platform: | |
| </p> | |
| <div class="variablelist"> | |
| <p class="title"><b></b></p> | |
| <dl> | |
| <dt><span class="term"><code class="literal">OS</code></span></dt> | |
| <dd><p> | |
| OS identifier string | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">OSPLAT</code></span></dt> | |
| <dd><p> | |
| Underlying architecture, when applicable | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">MAC</code></span></dt> | |
| <dd><p> | |
| true on MAC platform | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">NT</code></span></dt> | |
| <dd><p> | |
| true on NT platform | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">OS2</code></span></dt> | |
| <dd><p> | |
| true on OS2 platform | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">UNIX</code></span></dt> | |
| <dd><p> | |
| true on Unix platforms | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">VMS</code></span></dt> | |
| <dd><p> | |
| true on VMS platform | |
| </p></dd> | |
| </dl> | |
| </div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="jam.language.variables.builtins.jam_version"></a><a class="link" href="language.html#jam.language.variables.builtins.jam_version" title="Jam Version">Jam | |
| Version</a> | |
| </h5></div></div></div> | |
| <div class="variablelist"> | |
| <p class="title"><b></b></p> | |
| <dl> | |
| <dt><span class="term"><code class="literal">JAMDATE</code></span></dt> | |
| <dd><p> | |
| Time and date at <code class="literal">bjam</code> start-up as an ISO-8601 | |
| UTC value. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">JAMUNAME</code></span></dt> | |
| <dd><p> | |
| Ouput of uname(1) command (Unix only) | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">JAMVERSION</code></span></dt> | |
| <dd><p> | |
| <code class="literal">bjam</code> version, currently "3.1.19" | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">JAM_VERSION</code></span></dt> | |
| <dd><p> | |
| A predefined global variable with two elements indicates the version | |
| number of Boost Jam. Boost Jam versions start at "<code class="literal">03</code>" | |
| "<code class="literal">00</code>". Earlier versions of <code class="literal">Jam</code> | |
| do not automatically define <code class="literal">JAM_VERSION</code>. | |
| </p></dd> | |
| </dl> | |
| </div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="jam.language.variables.builtins.jamshell"></a><a class="link" href="language.html#jam.language.variables.builtins.jamshell" title="JAMSHELL">JAMSHELL</a> | |
| </h5></div></div></div> | |
| <p> | |
| When <code class="literal">bjam</code> executes a rule's action block, it forks | |
| and execs a shell, passing the action block as an argument to the shell. | |
| The invocation of the shell can be controlled by <code class="literal">$(JAMSHELL)</code>. | |
| The default on Unix is, for example: | |
| </p> | |
| <pre class="programlisting">JAMSHELL = /bin/sh -c % ; | |
| </pre> | |
| <p> | |
| The <code class="literal">%</code> is replaced with the text of the action block. | |
| </p> | |
| <p> | |
| <code class="literal">BJam</code> does not directly support building in parallel | |
| across multiple hosts, since that is heavily dependent on the local environment. | |
| To build in parallel across multiple hosts, you need to write your own | |
| shell that provides access to the multiple hosts. You then reset <code class="literal">$(JAMSHELL)</code> | |
| to reference it. | |
| </p> | |
| <p> | |
| Just as <code class="literal">bjam</code> expands a <code class="literal">%</code> to be | |
| the text of the rule's action block, it expands a <code class="literal">!</code> | |
| to be the multi-process slot number. The slot number varies between 1 | |
| and the number of concurrent jobs permitted by the <code class="literal">-j</code> | |
| flag given on the command line. Armed with this, it is possible to write | |
| a multiple host shell. For example: | |
| </p> | |
| <pre class="programlisting">#!/bin/sh | |
| # This sample JAMSHELL uses the SunOS on(1) command to execute a | |
| # command string with an identical environment on another host. | |
| # Set JAMSHELL = jamshell ! % | |
| # | |
| # where jamshell is the name of this shell file. | |
| # | |
| # This version handles up to -j6; after that they get executed | |
| # locally. | |
| case $1 in | |
| 1|4) on winken sh -c "$2";; | |
| 2|5) on blinken sh -c "$2";; | |
| 3|6) on nod sh -c "$2";; | |
| *) eval "$2";; | |
| esac | |
| </pre> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="jam.language.variables.builtins.actionrule"></a><a class="link" href="language.html#jam.language.variables.builtins.actionrule" title="__TIMING_RULE__ and __ACTION_RULE__"><code class="literal">__TIMING_RULE__</code> | |
| and <code class="literal">__ACTION_RULE__</code></a> | |
| </h5></div></div></div> | |
| <p> | |
| The <code class="literal">__TIMING_RULE__</code> and <code class="literal">__ACTION_RULE__</code> | |
| can be set to the name of a rule for <code class="literal">bjam</code> to call | |
| <span class="bold"><strong>after</strong></span> an action completes for a target. | |
| They both give diagnostic information about the action that completed. | |
| For <code class="literal">__TIMING_RULE__</code> the rule is called as: | |
| </p> | |
| <pre class="programlisting"><span class="identifier">rule</span> <span class="identifier">timing</span><span class="special">-</span><span class="identifier">rule</span> <span class="special">(</span> <span class="identifier">args</span> <span class="special">*</span> <span class="special">:</span> <span class="identifier">target</span> <span class="special">:</span> <span class="identifier">start</span> <span class="identifier">end</span> <span class="identifier">user</span> <span class="identifier">system</span> <span class="special">)</span> | |
| </pre> | |
| <p> | |
| And <code class="literal">__ACTION_RULE__</code> is called as: | |
| </p> | |
| <pre class="programlisting"><span class="identifier">rule</span> <span class="identifier">action</span><span class="special">-</span><span class="identifier">rule</span> <span class="special">(</span> <span class="identifier">args</span> <span class="special">*</span> <span class="special">:</span> <span class="identifier">target</span> <span class="special">:</span> <span class="identifier">command</span> <span class="identifier">status</span> <span class="identifier">start</span> <span class="identifier">end</span> <span class="identifier">user</span> <span class="identifier">system</span> <span class="special">:</span> <span class="identifier">output</span> <span class="special">?</span> <span class="special">)</span> | |
| </pre> | |
| <p> | |
| The arguments for both are: | |
| </p> | |
| <div class="variablelist"> | |
| <p class="title"><b></b></p> | |
| <dl> | |
| <dt><span class="term"><code class="literal">args</code></span></dt> | |
| <dd><p> | |
| Any values following the rule name in the <code class="literal">__TIMING_RULE__</code> | |
| or <code class="literal">__ACTION_RULE__</code> are passed along here. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">target</code></span></dt> | |
| <dd><p> | |
| The <code class="literal">bjam</code> target that was built. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">command</code></span></dt> | |
| <dd><p> | |
| The text of the executed command in the action body. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">status</code></span></dt> | |
| <dd><p> | |
| The integer result of the executed command. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">start</code></span></dt> | |
| <dd><p> | |
| The starting timestamp of the executed command as a ISO-8601 UTC | |
| value. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">end</code></span></dt> | |
| <dd><p> | |
| The completion timestamp of the executed command as a ISO-8601 | |
| UTC value. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">user</code></span></dt> | |
| <dd><p> | |
| The number of user CPU seconds the executed command spent as a | |
| floating point value. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">system</code></span></dt> | |
| <dd><p> | |
| The number of system CPU seconds the executed command spent as | |
| a floating point value. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">output</code></span></dt> | |
| <dd><p> | |
| The output of the command as a single string. The content of the | |
| output reflects the use of the <code class="literal">-pX</code> option. | |
| </p></dd> | |
| </dl> | |
| </div> | |
| <div class="note"><table border="0" summary="Note"> | |
| <tr> | |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> | |
| <th align="left">Note</th> | |
| </tr> | |
| <tr><td align="left" valign="top"><p> | |
| If both variables are set for a target both are called, first <code class="literal">__TIMING_RULE__</code> | |
| then <code class="literal">__ACTION_RULE__</code>. | |
| </p></td></tr> | |
| </table></div> | |
| </div> | |
| </div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h3 class="title"> | |
| <a name="jam.language.modules"></a><a class="link" href="language.html#jam.language.modules" title="Modules">Modules</a> | |
| </h3></div></div></div> | |
| <div class="toc"><dl> | |
| <dt><span class="section"><a href="language.html#jam.language.modules.declaration">Declaration</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.modules.variable_scope">Variable Scope</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.modules.local_rules">Local Rules</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.modules.the__rulenames__rule">The <code class="literal">RULENAMES</code> | |
| Rule</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.modules.the__varnames__rule">The <code class="literal">VARNAMES</code> | |
| Rule</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.modules.the__import__rule">The <code class="literal">IMPORT</code> | |
| Rule</a></span></dt> | |
| <dt><span class="section"><a href="language.html#jam.language.modules.the__export__rule">The <code class="literal">EXPORT</code> | |
| Rule</a></span></dt> | |
| <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> | |
| <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> | |
| </dl></div> | |
| <p> | |
| Boost Jam introduces support for modules, which provide some rudimentary | |
| namespace protection for rules and variables. A new keyword, "<code class="literal">module</code>" | |
| was also introduced. The features described in this section are primitives, | |
| meaning that they are meant to provide the operations needed to write Jam | |
| rules which provide a more elegant module interface. | |
| </p> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="jam.language.modules.declaration"></a><a class="link" href="language.html#jam.language.modules.declaration" title="Declaration">Declaration</a> | |
| </h4></div></div></div> | |
| <pre class="programlisting">module <span class="emphasis"><em>expression</em></span> { ... } | |
| </pre> | |
| <p> | |
| Code within the <code class="literal">{ ... }</code> executes within the module named | |
| by evaluating expression. Rule definitions can be found in the module's | |
| 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>, | |
| so within a module, other rules in that module may always be invoked without | |
| qualification: | |
| </p> | |
| <pre class="programlisting"><span class="bold"><strong>module my_module</strong></span> | |
| <span class="bold"><strong>{</strong></span> | |
| rule salute ( x ) { ECHO $(x), world ; } | |
| rule greet ( ) { salute hello ; } | |
| greet ; | |
| <span class="bold"><strong>}</strong></span> | |
| <span class="bold"><strong>my_module.salute</strong></span> goodbye ; | |
| </pre> | |
| <p> | |
| When an invoked rule is not found in the current module's namespace, it | |
| is looked up in the namespace of the global module, so qualified calls | |
| work across modules: | |
| </p> | |
| <pre class="programlisting">module your_module | |
| { | |
| rule bedtime ( ) { <span class="bold"><strong>my_module.salute</strong></span> goodnight ; } | |
| } | |
| </pre> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="jam.language.modules.variable_scope"></a><a class="link" href="language.html#jam.language.modules.variable_scope" title="Variable Scope">Variable Scope</a> | |
| </h4></div></div></div> | |
| <p> | |
| Each module has its own set of dynamically nested variable scopes. When | |
| execution passes from module A to module B, all the variable bindings from | |
| A become unavailable, and are replaced by the bindings that belong to B. | |
| This applies equally to local and global variables: | |
| </p> | |
| <pre class="programlisting">module A | |
| { | |
| x = 1 ; | |
| rule f ( ) | |
| { | |
| local y = 999 ; # becomes visible again when B.f calls A.g | |
| B.f ; | |
| } | |
| rule g ( ) | |
| { | |
| ECHO $(y) ; # prints "999" | |
| } | |
| } | |
| module B | |
| { | |
| y = 2 ; | |
| rule f ( ) | |
| { | |
| ECHO $(y) ; # always prints "2" | |
| A.g ; | |
| } | |
| } | |
| </pre> | |
| <p> | |
| The only way to access another module's variables is by entering that module: | |
| </p> | |
| <pre class="programlisting">rule peek ( module-name ? : variables + ) | |
| { | |
| module $(module-name) | |
| { | |
| return $($(>)) ; | |
| } | |
| } | |
| </pre> | |
| <p> | |
| Note that because existing variable bindings change whenever a new module | |
| scope is entered, argument bindings become unavailable. That explains the | |
| use of "<code class="literal">$(>)</code>" in the peek rule above. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="jam.language.modules.local_rules"></a><a class="link" href="language.html#jam.language.modules.local_rules" title="Local Rules">Local Rules</a> | |
| </h4></div></div></div> | |
| <pre class="programlisting">local rule <span class="emphasis"><em>rulename</em></span>... | |
| </pre> | |
| <p> | |
| The rule is declared locally to the current module. It is not entered in | |
| the global module with qualification, and its name will not appear in the | |
| result of: | |
| </p> | |
| <pre class="programlisting">[ RULENAMES <span class="emphasis"><em>module-name</em></span> ] | |
| </pre> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="jam.language.modules.the__rulenames__rule"></a><a class="link" href="language.html#jam.language.modules.the__rulenames__rule" title="The RULENAMES Rule">The <code class="literal">RULENAMES</code> | |
| Rule</a> | |
| </h4></div></div></div> | |
| <pre class="programlisting">rule RULENAMES ( <span class="emphasis"><em>module</em></span> ? ) | |
| </pre> | |
| <p> | |
| Returns a list of the names of all non-local rules in the given module. | |
| If <span class="emphasis"><em>module</em></span> is omitted, the names of all non-local rules | |
| in the global module are returned. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="jam.language.modules.the__varnames__rule"></a><a class="link" href="language.html#jam.language.modules.the__varnames__rule" title="The VARNAMES Rule">The <code class="literal">VARNAMES</code> | |
| Rule</a> | |
| </h4></div></div></div> | |
| <pre class="programlisting">rule VARNAMES ( <span class="emphasis"><em>module</em></span> ? ) | |
| </pre> | |
| <p> | |
| Returns a list of the names of all variable bindings in the given module. | |
| If <span class="emphasis"><em>module</em></span> is omitted, the names of all variable bindings | |
| in the global module are returned. | |
| </p> | |
| <div class="note"><table border="0" summary="Note"> | |
| <tr> | |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> | |
| <th align="left">Note</th> | |
| </tr> | |
| <tr><td align="left" valign="top"><p> | |
| This includes any local variables in rules from the call stack which | |
| have not returned at the time of the <code class="literal">VARNAMES</code> invocation. | |
| </p></td></tr> | |
| </table></div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="jam.language.modules.the__import__rule"></a><a class="link" href="language.html#jam.language.modules.the__import__rule" title="The IMPORT Rule">The <code class="literal">IMPORT</code> | |
| Rule</a> | |
| </h4></div></div></div> | |
| <p> | |
| <code class="literal">IMPORT</code> allows rule name aliasing across modules: | |
| </p> | |
| <pre class="programlisting">rule IMPORT ( <span class="emphasis"><em>source_module</em></span> ? : <span class="emphasis"><em>source_rules</em></span> * | |
| : <span class="emphasis"><em>target_module</em></span> ? : <span class="emphasis"><em>target_rules</em></span> * ) | |
| </pre> | |
| <p> | |
| The <code class="literal">IMPORT</code> rule copies rules from the <span class="emphasis"><em>source_module</em></span> | |
| into the <span class="emphasis"><em>target_module</em></span> as local rules. If either | |
| <span class="emphasis"><em>source_module</em></span> or <span class="emphasis"><em>target_module</em></span> | |
| is not supplied, it refers to the global module. <span class="emphasis"><em>source_rules</em></span> | |
| specifies which rules from the <span class="emphasis"><em>source_module</em></span> to import; | |
| <span class="emphasis"><em>target_rules</em></span> specifies the names to give those rules | |
| in <span class="emphasis"><em>target_module</em></span>. If <span class="emphasis"><em>source_rules</em></span> | |
| contains a name which doesn't correspond to a rule in <span class="emphasis"><em>source_module</em></span>, | |
| or if it contains a different number of items than <span class="emphasis"><em>target_rules</em></span>, | |
| an error is issued. For example, | |
| </p> | |
| <pre class="programlisting"># import m1.rule1 into m2 as local rule m1-rule1. | |
| IMPORT m1 : rule1 : m2 : m1-rule1 ; | |
| # import all non-local rules from m1 into m2 | |
| IMPORT m1 : [ RULENAMES m1 ] : m2 : [ RULENAMES m1 ] ; | |
| </pre> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="jam.language.modules.the__export__rule"></a><a class="link" href="language.html#jam.language.modules.the__export__rule" title="The EXPORT Rule">The <code class="literal">EXPORT</code> | |
| Rule</a> | |
| </h4></div></div></div> | |
| <p> | |
| <code class="literal">EXPORT</code> allows rule name aliasing across modules: | |
| </p> | |
| <pre class="programlisting">rule EXPORT ( <span class="emphasis"><em>module</em></span> ? : <span class="emphasis"><em>rules</em></span> * ) | |
| </pre> | |
| <p> | |
| The <code class="literal">EXPORT</code> rule marks <span class="emphasis"><em>rules</em></span> from | |
| the <code class="literal">source_module</code> as non-local (and thus exportable). | |
| If an element of <span class="emphasis"><em>rules</em></span> does not name a rule in <span class="emphasis"><em>module</em></span>, | |
| an error is issued. For example, | |
| </p> | |
| <pre class="programlisting">module X { | |
| local rule r { ECHO X.r ; } | |
| } | |
| IMPORT X : r : : r ; # error - r is local in X | |
| EXPORT X : r ; | |
| IMPORT X : r : : r ; # OK. | |
| </pre> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="jam.language.modules.the__caller_module__rule"></a><a class="link" href="language.html#jam.language.modules.the__caller_module__rule" title="The CALLER_MODULE Rule">The | |
| <code class="literal">CALLER_MODULE</code> Rule</a> | |
| </h4></div></div></div> | |
| <pre class="programlisting">rule CALLER_MODULE ( <span class="emphasis"><em>levels</em></span> ? ) | |
| </pre> | |
| <p> | |
| <code class="literal">CALLER_MODULE</code> returns the name of the module scope enclosing | |
| the call to its caller (if levels is supplied, it is interpreted as an | |
| integer number of additional levels of call stack to traverse to locate | |
| the module). If the scope belongs to the global module, or if no such module | |
| exists, returns the empty list. For example, the following prints "{Y} | |
| {X}": | |
| </p> | |
| <pre class="programlisting">module X { | |
| rule get-caller { return [ CALLER_MODULE ] ; } | |
| rule get-caller's-caller { return [ CALLER_MODULE 1 ] ; } | |
| rule call-Y { return Y.call-X2 ; } | |
| } | |
| module Y { | |
| rule call-X { return X.get-caller ; } | |
| rule call-X2 { return X.get-caller's-caller ; } | |
| } | |
| callers = [ X.get-caller ] [ Y.call-X ] [ X.call-Y ] ; | |
| ECHO {$(callers)} ; | |
| </pre> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="jam.language.modules.the__delete_module__rule"></a><a class="link" href="language.html#jam.language.modules.the__delete_module__rule" title="The DELETE_MODULE Rule">The | |
| <code class="literal">DELETE_MODULE</code> Rule</a> | |
| </h4></div></div></div> | |
| <pre class="programlisting">rule DELETE_MODULE ( <span class="emphasis"><em>module</em></span> ? ) | |
| </pre> | |
| <p> | |
| <code class="literal">DELETE_MODULE</code> removes all of the variable bindings and | |
| otherwise-unreferenced rules from the given module (or the global module, | |
| if no module is supplied), and returns their memory to the system. | |
| </p> | |
| <div class="note"><table border="0" summary="Note"> | |
| <tr> | |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> | |
| <th align="left">Note</th> | |
| </tr> | |
| <tr><td align="left" valign="top"><p> | |
| Though it won't affect rules that are currently executing until they | |
| complete, <code class="literal">DELETE_MODULE</code> should be used with extreme | |
| care because it will wipe out any others and all variable (including | |
| locals in that module) immediately. Because of the way dynamic binding | |
| works, variables which are shadowed by locals will not be destroyed, | |
| so the results can be really unpredictable. | |
| </p></td></tr> | |
| </table></div> | |
| </div> | |
| </div> | |
| </div> | |
| <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> | |
| <td align="left"></td> | |
| <td align="right"><div class="copyright-footer">Copyright © 2003-2007 Rene Rivera, David Abrahams, Vladimir Prus<p> | |
| Distributed under the Boost Software License, Version 1.0. (See accompanying | |
| file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) | |
| </p> | |
| </div></td> | |
| </tr></table> | |
| <hr> | |
| <div class="spirit-nav"> | |
| <a accesskey="p" href="usage.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../jam.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="miscellaneous.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> | |
| </div> | |
| </body> | |
| </html> |