summaryrefslogtreecommitdiff
path: root/doc/user/environments.xml
diff options
context:
space:
mode:
authorJörg Frings-Fürst <debian@jff-webhosting.net>2017-09-28 12:19:30 +0200
committerJörg Frings-Fürst <debian@jff-webhosting.net>2017-09-28 12:19:30 +0200
commit7c6dd0eee627772485f8b06470ac84adc0f077f6 (patch)
tree69a28021c01029c221f78be31c4cb0335922ebfe /doc/user/environments.xml
parent6be31f5d140b81227911cabfc61d3802c76c1b61 (diff)
parentbaee03c569c91b745a1e025660b19a718db16e7d (diff)
Updated version 3.0.0 from 'upstream/3.0.0'
with Debian dir 147caafe8506326dfd094432b42ae32c21ed284e
Diffstat (limited to 'doc/user/environments.xml')
-rw-r--r--doc/user/environments.xml201
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>