Updated the documentation for nested tools located within subdirs

2 files changed, 63 insertions, 0 deletions

diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index b68f27a..3268860 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -2187,6 +2187,22 @@ platform name when the Environment is constructed. Changing the PATH
 variable after the Environment is constructed will not cause the tools to
 be redetected.</para>
 
+<para> One feature now present within Scons is the ability to have nested tools.
+Tools which can be located within a subdirectory in the toolpath.
+With a nested tool name the dot represents a directory seperator</para>
+
+<programlisting>
+# namespaced builder
+env = Environment(ENV = os.environ, tools = ['SubDir1.SubDir2.SomeTool'])
+env.SomeTool(targets, sources)
+
+# Search Paths
+# SCons\Tool\SubDir1\SubDir2\SomeTool.py
+# SCons\Tool\SubDir1\SubDir2\SomeTool\__init__.py
+# .\site_scons\site_tools\SubDir1\SubDir2\SomeTool.py
+# .\site_scons\site_tools\SubDir1\SubDir2\SomeTool\__init__.py
+</programlisting>
+
 <para>SCons supports the following tool specifications out of the box:</para>
 
 <!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml
index 07f2dec..35dd989 100644
--- a/doc/user/builders-writing.xml
+++ b/doc/user/builders-writing.xml
@@ -880,6 +880,53 @@ env2.Foo('file2')
 
   </section>
 
+  <section>
+  <title>Nested and namespace builders;</title>
+
+    <para>
+    &SCons; now supports the ability for a Builder to be located within a sub-directory of the toolpath.
+	This is similar to namespacing within python.
+
+    Normally when loading a tool into the environment, scons will search for the tool within two locations
+    </para>
+
+    <sconstruct>
+# Regular non namespace target
+env = Environment(ENV = os.environ, tools = ['SomeTool'])
+env.SomeTool(targets, sources)
+    </sconstruct>
+
+    <para>
+    The locations would include
+	<filename>SCons\Tool\SomeTool.py</filename>
+    <filename>SCons\Tool\SomeTool\__init__.py</filename>
+    <filename>.\site_scons\site_tools\SomeTool.py</filename>
+	<filename>.\site_scons\site_tools\SomeTool\__init__.py</filename>
+
+    If a toolpath is specified this is also searched as well.
+	With nested or namespaced tools we can use the dot notation to specify a sub-directoty that the tool is located under
+    </para>
+
+    <sconstruct>
+# namespaced target
+env = Environment(ENV = os.environ, tools = ['SubDir1.SubDir2.SomeTool'])
+env.SomeTool(targets, sources)
+    </sconstruct>
+
+    <para>
+    With this example the search locations would include
+	<filename>SCons\Tool\SubDir1\SubDir2\SomeTool.py</filename>
+    <filename>SCons\Tool\SubDir1\SubDir2\SomeTool\__init__.py</filename>
+    <filename>.\site_scons\site_tools\SubDir1\SubDir2\SomeTool.py</filename>
+	<filename>.\site_scons\site_tools\SubDir1\SubDir2\SomeTool\__init__.py</filename>
+
+    It's important to note when creating tools within sub-directories, there needs to be a __init__.py file within each directory.
+	This file can just be empty however.
+	This is the same constraint used by python when loading modules from within sub-directories (packages).
+
+    </para>
+  </section>
+
   <!--
 
   <section>