diff options
Diffstat (limited to 'doc/user')
| -rw-r--r-- | doc/user/environments.xml | 71 |
1 files changed, 58 insertions, 13 deletions
diff --git a/doc/user/environments.xml b/doc/user/environments.xml index d591dff..ae670a8 100644 --- a/doc/user/environments.xml +++ b/doc/user/environments.xml @@ -1781,7 +1781,7 @@ env.AppendENVPath('LIB', '/usr/local/lib') </para> <sconstruct> -# Inbuilt tool or tool located within site_tools +# Builtin tool or tool located within site_tools env = Environment(tools = ['SomeTool']) env.SomeTool(targets, sources) @@ -1847,11 +1847,12 @@ SCons/Tool/SubDir1/SubDir2/SomeTool/__init__.py </sconstruct> <para> - 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 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> @@ -1859,20 +1860,30 @@ SCons/Tool/SubDir1/SubDir2/SomeTool/__init__.py <title>Using sys.path within the toolpath</title> <para> - Using the toolpath option with sys.path - we can also include tools installed via the pip package manager. - </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 -env = Environment(tools = ['someinstalledpackage.SomeTool'], toolpath = sys.path) + +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 supplying sys.path to the toolpath argument - and by using the nested syntax we can have scons search - the sys.path (which will include packages installed via pip). + 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> @@ -1887,6 +1898,40 @@ C:\Python35\Lib\site-packages\someinstalledpackage\SomeTool\__init__.py </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> |