diff options
Diffstat (limited to 'doc/user/environments.xml')
| -rw-r--r-- | doc/user/environments.xml | 201 |
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<-' ) +print("value is:", env.subst( '->$MISSING<-' )) </file> </scons_example> @@ -834,7 +834,7 @@ print "value is:", env.subst( '->$MISSING<-' ) <file name="SConstruct" printme="1"> AllowSubstExceptions() env = Environment() -print "value is:", env.subst( '->$MISSING<-' ) +print("value is:", env.subst( '->$MISSING<-' )) </file> </scons_example> @@ -854,7 +854,7 @@ print "value is:", env.subst( '->$MISSING<-' ) <file name="SConstruct" printme="1"> AllowSubstExceptions(IndexError, NameError, ZeroDivisionError) env = Environment() -print "value is:", env.subst( '->${1 / 0}<-' ) +print("value is:", env.subst( '->${1 / 0}<-' )) </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) > 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> |