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

Subject: [Boost-commit] svn:boost r77642 - trunk/tools/build/v2/doc/src
From: steven_at_[hidden]
Date: 2012-03-30 07:57:16

Author: steven_watanabe
Date: 2012-03-30 07:57:15 EDT (Fri, 30 Mar 2012)
New Revision: 77642
URL: http://svn.boost.org/trac/boost/changeset/77642

Log:
Add some examples to modules doc.
Text files modified: 
   trunk/tools/build/v2/doc/src/reference.xml |    77 +++++++++++++++++++++++++++++++++++++-- 
   1 files changed, 72 insertions(+), 5 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-30 07:57:15 EDT (Fri, 30 Mar 2012)
@@ -1787,28 +1787,73 @@
     <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>
+
+      <para>
+        The <code>modules</code> module defines basic functionality
+        for handling modules.
+      </para>
+
+      <para>
+        A module defines a number of rules that can be used in other
+        modules.  Modules can contain code at the top level to initialize
+        the module.  This code is executed the first time the
+        module is loaded.
+        <note>
+          <para>
+            A Jamfile is a special kind of module which is managed by
+            the build system.  Although they cannot be loaded directly
+            by users, the other features of modules are still useful
+            for Jamfiles.
+          </para>
+        </note>
+      </para>
+
+      <para>
+        Each module has its own namespaces for variables and rules.  If two
+        modules A and B both use a variable named X, each one gets its own
+        copy of X.  They won't interfere with each other in any way.
+        Similarly, importing rules into one module has no effect on any other
+        module.
+      </para>
+
+      <para>
+        Every module has two special variables.
+        <code>$(__file__)</code> contains the name of the file that
+        the module was loaded from and <code>$(__name__)</code>
+        contains the name of the module.
+        <note><para><code>$(__file__)</code> does not contain
+        the full path to the file.  If you need this, use
+        <code>modules.binding</code>.</para></note>
+      </para>
       
       <orderedlist>
 
         <listitem>
           <indexterm><primary>binding</primary></indexterm>
           <code lang="jam">rule binding ( module-name )</code>
-          <para>Returns the binding of the given module.</para>
+          <para>Returns the filesystem binding of the given module.</para>
+          <para>For example, a module can get its own location with:
+          <programlisting>me = [ modules.binding $(__name__) ] ;</programlisting>
+          </para>
         </listitem>
 
         <listitem>
           <indexterm><primary>poke</primary></indexterm>
           <code lang="jam">rule poke ( module-name ? : variables + : value * )</code>
           <para>Sets the module-local value of a variable.</para>
+          <para>For example, to set a variable in the global module:
+          <programlisting>modules.poke : ZLIB_INCLUDE : /usr/local/include ;</programlisting>
+          </para>
         </listitem>
 
         <listitem>
           <indexterm><primary>peek</primary></indexterm>
           <code lang="jam">rule peek ( module-name ? : variables + )</code>
           <para>Returns the module-local value of a variable.</para>
+          <para>
+            For example, to read a variable from the global module:
+            <programlisting>local ZLIB_INCLUDE = [ modules.peek : ZLIB_INCLUDE ] ;</programlisting>
+          </para>
         </listitem>
 
         <listitem>
@@ -1821,6 +1866,21 @@
           is a local rule).
           <note><para>rules called this way may accept at most
           8 parameters.</para></note></para>
+          <para>Example:
+          <programlisting>rule filter ( f : values * )
+{
+    local m = [ CALLER_MODULE ] ;
+    local result ;
+    for v in $(values)
+    {
+        if [ modules.call-in $(m) : $(f) $(v) ]
+        {
+            result += $(v) ;
+        }
+    }
+    return result ;
+}</programlisting>
+          </para>
         </listitem>
 
         <listitem>
@@ -1831,7 +1891,8 @@
           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>
+          8 parameters.</para></note>
+          </para>
         </listitem>
 
         <listitem>
@@ -1873,6 +1934,12 @@
           same number of elements as <code>rules-opt</code>.</para>
           <note><para>The <literal>import</literal> rule is available
           without qualification in all modules.</para></note>
+          <para>Examples:
+          <programlisting>import path ;
+import path : * ;
+import path : join ;
+import path : native make : native-path make-path ;</programlisting>
+          </para>
         </listitem>
 
         <listitem>