[Boost-commit] svn:boost r77578 - trunk/tools/build/v2/doc/src

Subject: [Boost-commit] svn:boost r77578 - trunk/tools/build/v2/doc/src
From: steven_at_[hidden]
Date: 2012-03-26 21:49:01

Author: steven_watanabe
Date: 2012-03-26 21:49:01 EDT (Mon, 26 Mar 2012)
New Revision: 77578
URL: http://svn.boost.org/trac/boost/changeset/77578

Log:
Document modules.
Text files modified: 
   trunk/tools/build/v2/doc/src/reference.xml |   140 ++++++++++++++++++++++++++++++++++++++++
   1 files changed, 140 insertions(+), 0 deletions(-)

Modified: trunk/tools/build/v2/doc/src/reference.xml
==============================================================================
--- trunk/tools/build/v2/doc/src/reference.xml	(original)
+++ trunk/tools/build/v2/doc/src/reference.xml	2012-03-26 21:49:01 EDT (Mon, 26 Mar 2012)
@@ -1761,6 +1761,146 @@
 
     </section>
 
+  <section id="bbv2.reference.modules">
+    <title>Builtin modules</title>
+
+    <para>
+      This section describes the modules that are provided
+      by Boost.Build.  The import rule allows rules from
+      one module to be used in another module or Jamfile.
+    </para>
+    
+    <section id="bbv2.reference.modules.modules">
+      <title>modules</title>
+      <indexterm><primary>modules</primary></indexterm>
+      
+      <para>The <code>modules</code> module defines basic
+      functionality for importing modules.</para>
+      
+      <variablelist>
+      
+        <varlistentry>
+          <indexterm><primary>binding</primary></indexterm>
+          <term><literal>binding</literal></term>
+          <listitem>
+            <para>Returns the binding of the given module.</para>
+            <programlisting>rule binding ( module ) </programlisting>
+          </listitem>
+        </varlistentry>
+      
+        <varlistentry>
+          <indexterm><primary>poke</primary></indexterm>
+          <term><literal>poke</literal></term>
+          <listitem>
+            <para>Sets the module-local value of a variable.</para>
+            <programlisting>rule poke ( module-name ? : variables + : value * ) </programlisting>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <indexterm><primary>peek</primary></indexterm>
+          <term><literal>peek</literal></term>
+          <listitem>
+            <para>Returns the module-local value of a variable.</para>
+            <programlisting>rule peek ( module-name ? : variables + ) </programlisting>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <indexterm><primary>call-in</primary></indexterm>
+          <term><literal>call-in</literal></term>
+          <listitem>
+            <para>Call the given rule locally in the given module. Use
+            this for rules accepting rule names as arguments, so that
+            the passed rule may be invoked in the context of the rule's
+            caller (for example, if the rule accesses module globals or
+            is a local rule).
+            <note><para>rules called this way may accept at most
+            8 parameters.</para></note></para>
+            <programlisting>rule call-in ( module-name ? : rule-name args * : * ) </programlisting>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <indexterm><primary>call-locally</primary></indexterm>
+          <term><literal>call-locally</literal></term>
+          <listitem>
+            <para>Given a possibly qualified rule name and arguments, remove
+            any initial module qualification from the rule and invoke it in
+            that module. If there is no module qualification, the rule is
+            invoked in the global module.
+            <note><para>rules called this way may accept at most
+            8 parameters.</para></note></para>
+            <programlisting>rule call-locally ( qualified-rule-name args * : * ) </programlisting>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <indexterm><primary>load</primary></indexterm>
+          <term><literal>load</literal></term>
+          <listitem>
+            <para>Load the indicated module if it is not already loaded.</para>
+            <programlisting>rule load ( module-name : filename ? : search * )</programlisting>
+            <variablelist>
+              <varlistentry>
+                <term><literal>module-name</literal></term>
+                <listitem><para>Name of module to load.</para></listitem>
+              </varlistentry>
+            </variablelist>
+            <variablelist>
+              <varlistentry>
+                <term><literal>filename</literal></term>
+                <listitem><para>(partial) path to file; Defaults to <code>$(module-name).jam</code></para></listitem>
+              </varlistentry>
+            </variablelist>
+            <variablelist>
+              <varlistentry>
+                <term><literal>search</literal></term>
+                <listitem><para>Directories in which to search for filename.
+                   Defaults to <code>$(BOOST_BUILD_PATH)</code>.</para></listitem>
+              </varlistentry>
+            </variablelist>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <indexterm><primary>import</primary></indexterm>
+          <term><literal>import</literal></term>
+          <listitem>
+            <para>Load the indicated module and import rule names into the
+            current module. Any members of <code>rules-opt</code> will be
+            available without qualification in the caller's module. Any
+            members of <code>rename-opt</code> will be taken as the names
+            of the rules in the caller's module, in place of the names they
+            have in the imported module.  If <code>rules-opt = '*'</code>,
+            all rules from the indicated module are imported into the
+            caller's module. If <code>rename-opt</code> is supplied, it must have the
+            same number of elements as <code>rules-opt</code>.</para>
+            <programlisting>rule import ( module-names + : rules-opt * : rename-opt * )</programlisting>
+            <note><para>The <literal>import</literal> rule is available
+            without qualification in all modules.</para></note>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <indexterm><primary>clone-rulest</primary></indexterm>
+          <term><literal>clone-rules</literal></term>
+          <listitem>
+            <para>Define exported copies in <code>$(target-module)</code>
+            of all rules exported from <code>$(source-module)</code>. Also
+            make them available in the global module with qualification,
+            so that it is just as though the rules were defined originally
+            in <code>$(target-module)</code>.</para>
+            <programlisting>rule clone-rules ( source-module target-module )</programlisting>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+    </section>
+  
+  </section>
+
   <section id="bbv2.reference.buildprocess">
     <title>Build process</title>