Updated version 3.0.0 from 'upstream/3.0.0'

with Debian dir 147caafe8506326dfd094432b42ae32c21ed284e

1 files changed, 185 insertions, 16 deletions

diff --git a/doc/user/environments.xml b/doc/user/environments.xml
index bbe8b07..ea5d472 100644
--- a/doc/user/environments.xml
+++ b/doc/user/environments.xml
@@ -22,7 +22,7 @@
 
 <!--
 
-     Copyright (c) 2001 - 2016 The SCons Foundation
+     Copyright (c) 2001 - 2017 The SCons Foundation
 
      Permission is hereby granted, free of charge, to any person obtaining
      a copy of this software and associated documentation files (the
@@ -627,7 +627,7 @@ int main() { }
       <scons_example name="environments_ex6">
         <file name="SConstruct" printme="1">
 env = Environment()
-print "CC is:", env['CC']
+print("CC is:", env['CC'])
         </file>
       </scons_example>
 
@@ -658,7 +658,7 @@ print "CC is:", env['CC']
 env = Environment(FOO = 'foo', BAR = 'bar')
 dict = env.Dictionary()
 for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']:
-    print "key = %s, value = %s" % (key, dict[key])
+    print("key = %s, value = %s" % (key, dict[key]))
          </file>
       </scons_example>
 
@@ -695,7 +695,7 @@ for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']:
       <sconstruct>
 env = Environment()
 for item in sorted(env.Dictionary().items()):
-    print "construction variable = '%s', value = '%s'" % item
+    print("construction variable = '%s', value = '%s'" % item)
       </sconstruct>
 
     </section>
@@ -721,7 +721,7 @@ for item in sorted(env.Dictionary().items()):
 
       <sconstruct>
 env = Environment()
-print "CC is:", env.subst('$CC')
+print("CC is:", env.subst('$CC'))
       </sconstruct>
 
       <para>
@@ -738,7 +738,7 @@ print "CC is:", env.subst('$CC')
 
       <sconstruct>
 env = Environment(CCFLAGS = '-DFOO')
-print "CCCOM is:", env['CCCOM']
+print("CCCOM is:", env['CCCOM'])
       </sconstruct>
 
       <para>
@@ -764,7 +764,7 @@ scons: `.' is up to date.
 
       <sconstruct>
 env = Environment(CCFLAGS = '-DFOO')
-print "CCCOM is:", env.subst('$CCCOM')
+print("CCCOM is:", env.subst('$CCCOM'))
       </sconstruct>
 
       <para>
@@ -806,7 +806,7 @@ scons: `.' is up to date.
        <scons_example name="environments_missing1">
          <file name="SConstruct" printme="1">
 env = Environment()
-print "value is:", env.subst( '->$MISSING&lt;-' )
+print("value is:", env.subst( '->$MISSING&lt;-' ))
         </file>
       </scons_example>
 
@@ -834,7 +834,7 @@ print "value is:", env.subst( '->$MISSING&lt;-' )
          <file name="SConstruct" printme="1">
 AllowSubstExceptions()
 env = Environment()
-print "value is:", env.subst( '->$MISSING&lt;-' )
+print("value is:", env.subst( '->$MISSING&lt;-' ))
         </file>
       </scons_example>
 
@@ -854,7 +854,7 @@ print "value is:", env.subst( '->$MISSING&lt;-' )
          <file name="SConstruct" printme="1">
 AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
 env = Environment()
-print "value is:", env.subst( '->${1 / 0}&lt;-' )
+print("value is:", env.subst( '->${1 / 0}&lt;-' ))
         </file>
       </scons_example>
 
@@ -1216,7 +1216,7 @@ int main() { }
         <file name="SConstruct" printme="1">
 env = Environment()
 env.Replace(NEW_VARIABLE = 'xyzzy')
-print "NEW_VARIABLE =", env['NEW_VARIABLE']
+print("NEW_VARIABLE =", env['NEW_VARIABLE'])
         </file>
       </scons_example>
 
@@ -1251,11 +1251,11 @@ print "NEW_VARIABLE =", env['NEW_VARIABLE']
       <scons_example name="environments_Replace2">
         <file name="SConstruct" printme="1">
 env = Environment(CCFLAGS = '-DDEFINE1')
-print "CCFLAGS =", env['CCFLAGS']
+print("CCFLAGS =", env['CCFLAGS'])
 env.Program('foo.c')
 
 env.Replace(CCFLAGS = '-DDEFINE2')
-print "CCFLAGS =", env['CCFLAGS']
+print("CCFLAGS =", env['CCFLAGS'])
 env.Program('bar.c')
         </file>
         <file name="foo.c">
@@ -1375,7 +1375,7 @@ int main() { }
         <file name="SConstruct" printme="1">
 env = Environment()
 env.Append(NEW_VARIABLE = 'added')
-print "NEW_VARIABLE =", env['NEW_VARIABLE']
+print("NEW_VARIABLE =", env['NEW_VARIABLE'])
         </file>
       </scons_example>
 
@@ -1475,7 +1475,7 @@ int main() { }
         <file name="SConstruct" printme="1">
 env = Environment()
 env.Prepend(NEW_VARIABLE = 'added')
-print "NEW_VARIABLE =", env['NEW_VARIABLE']
+print("NEW_VARIABLE =", env['NEW_VARIABLE'])
         </file>
       </scons_example>
 
@@ -1650,7 +1650,7 @@ if len(sys.argv) &gt; 1:
 else:
     keys = sorted(os.environ.keys())
 for key in keys:
-    print "    " + key + "=" + os.environ[key]
+    print("    " + key + "=" + os.environ[key])
       </file>
     </scons_example>
 
@@ -1765,4 +1765,173 @@ env.AppendENVPath('LIB', '/usr/local/lib')
 
   </section>
 
+
+  <section id="sect-environment-toolpath">
+  <title>Using the toolpath for external Tools</title>
+
+    <section>
+    <title>The default tool search path</title>
+
+      <para>
+      Normally when using a tool from the construction environment,
+      several different search locations are checked by default.
+      This includes the <literal>Scons/Tools/</literal> directory
+      inbuilt to scons and the directory <literal>site_scons/site_tools</literal>
+      relative to the root SConstruct file.
+      </para>
+
+      <sconstruct>
+# Builtin tool or tool located within site_tools
+env = Environment(tools = ['SomeTool'])
+env.SomeTool(targets, sources)
+
+# The search locations would include by default
+SCons/Tool/SomeTool.py
+SCons/Tool/SomeTool/__init__.py
+./site_scons/site_tools/SomeTool.py
+./site_scons/site_tools/SomeTool/__init__.py
+      </sconstruct>
+
+    </section>
+
+	<section>
+    <title>Providing an external directory to toolpath</title>
+
+      <para>
+      In some cases you may want to specify a different location to search for tools.
+      The Environment constructor contains an option for this called toolpath
+      This can be used to add additional search directories.
+      </para>
+
+      <sconstruct>
+# Tool located within the toolpath directory option
+env = Environment(tools = ['SomeTool'], toolpath = ['/opt/SomeToolPath', '/opt/SomeToolPath2'])
+env.SomeTool(targets, sources)
+
+# The search locations in this example would include:
+/opt/SomeToolPath/SomeTool.py
+/opt/SomeToolPath/SomeTool/__init__.py
+/opt/SomeToolPath2/SomeTool.py
+/opt/SomeToolPath2/SomeTool/__init__.py
+SCons/Tool/SomeTool.py
+SCons/Tool/SomeTool/__init__.py
+./site_scons/site_tools/SomeTool.py
+./site_scons/site_tools/SomeTool/__init__.py
+      </sconstruct>
+
+    </section>
+
+	<section>
+    <title>Nested Tools within a toolpath</title>
+
+      <para>
+      &SCons; 3.0 now supports the ability for a Builder to be located
+	  within a sub-directory / sub-package of the toolpath.
+	  This is similar to namespacing within python.
+	  With nested or namespaced tools we can use the dot notation
+	  to specify a sub-directory that the tool is located under.
+      </para>
+
+      <sconstruct>
+# namespaced target
+env = Environment(tools = ['SubDir1.SubDir2.SomeTool'], toolpath = ['/opt/SomeToolPath'])
+env.SomeTool(targets, sources)
+
+# With this example the search locations would include
+/opt/SomeToolPath/SubDir1/SubDir2/SomeTool.py
+/opt/SomeToolPath/SubDir1/SubDir2/SomeTool/__init__.py
+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
+      </sconstruct>
+
+      <para>
+      For python2 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.
+      This is the same constraint used by python when loading modules
+      from within sub-directories (packages).
+      For python3 this appears to be no longer a requirement.
+      </para>
+    </section>
+
+	<section>
+    <title>Using sys.path within the toolpath</title>
+
+      <para>
+      If we want to access tools externally to scons on the sys.path
+      (one example would be tools installed via the pip package manager)
+      One way to do this is to use sys.path with the toolpath.
+
+      One thing to watch out for with this approach is that sys.path
+      can sometimes contains paths to .egg files instead of directories.
+      So we need to filter those out with this approach.
+      </para>
+
+      <sconstruct>
+# namespaced target using sys.path within toolpath
+
+searchpaths = []
+for item in sys.path:
+    if os.path.isdir(item): searchpaths.append(item)
+
+env = Environment(tools = ['someinstalledpackage.SomeTool'], toolpath = searchpaths)
+env.SomeTool(targets, sources)
+      </sconstruct>
+
+      <para>
+      By using sys.path with the toolpath argument
+      and by using the nested syntax we can have scons search
+      packages installed via pip for Tools.
+      </para>
+
+<sconstruct>
+# For Windows based on the python version and install directory, this may be something like
+C:\Python35\Lib\site-packages\someinstalledpackage\SomeTool.py
+C:\Python35\Lib\site-packages\someinstalledpackage\SomeTool\__init__.py
+
+# For Linux this could be something like:
+/usr/lib/python3/dist-packages/someinstalledpackage/SomeTool.py
+/usr/lib/python3/dist-packages/someinstalledpackage/SomeTool/__init__.py
+</sconstruct>
+
+    </section>
+
+	<section>
+    <title>Using the &PyPackageDir; function to add to the toolpath</title>
+
+      <para>
+      In some cases you may want to use a tool
+      located within a installed external pip package.
+      This is possible by the use of sys.path with the toolpath.
+      However in that situation you need to provide a prefix to the toolname
+      to indicate where it is located within sys.path
+      </para>
+
+      <sconstruct>
+searchpaths = []
+for item in sys.path:
+    if os.path.isdir(item): searchpaths.append(item)
+env = Environment(tools = ['tools_example.subdir1.subdir2.SomeTool'], toolpath = searchpaths)
+env.SomeTool(targets, sources)
+      </sconstruct>
+
+      <para>
+      To avoid the use of a prefix within the name of the tool or filtering sys.path for directories,
+      we can use the <function>PyPackageDir(modulename)</function> function to locate the directory of the python package.
+      <function>PyPackageDir</function> returns a Dir object which represents the path of the directory
+      for the python package / module specified as a parameter.
+      </para>
+
+      <sconstruct>
+# namespaced target using sys.path
+env = Environment(tools = ['SomeTool'], toolpath = [PyPackageDir('tools_example.subdir1.subdir2')])
+env.SomeTool(targets, sources)
+      </sconstruct>
+
+    </section>
+
+  </section>
+
 </chapter>