boost-react-native-bundle

<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.78.1"> <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> <link rel="up" href="../jam.html" title="Chapter 42. Boost.Jam : 3.1.19"> <link rel="prev" href="../jam.html" title="Chapter 42. Boost.Jam : 3.1.19"> <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="../jam.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 class="toc"> <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">B2</code> has an interpreted, procedural language. Statements in <code class="literal">b2</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">B2</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">B2</code> requires whitespace (blanks, tabs, or newlines) to surround all tokens, including the colon (:) and semicolon (;) tokens. </p> <p> <code class="literal">B2</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 class="toc"><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">b2</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 representing 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">b2</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 class="toc"> <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">b2</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">b2</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 class="variablelist"> <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 <code class="literal">b2</code> 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 class="toc"> <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">B2</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">b2</code> treats the targets differently during its target binding phase. See Binding above. Normally, <code class="literal">b2</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">b2</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">b2</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">b2</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">b2</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">b2</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">B2</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">b2</code> searches for the target such that it ignores matches for file system items that are not files, 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">b2</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 "=[ ]=". 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 a list 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>. </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" style="list-style-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 class="variablelist"> <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 class="variablelist"> <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="programl