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>