From a25367b4f6151a7888b9446e45e234ed84c9a163 Mon Sep 17 00:00:00 2001 From: grbd Date: Mon, 19 Jun 2017 15:45:03 +0100 Subject: Updated the documentation for nested tools located within subdirs --- doc/man/scons.xml | 16 +++++++++++++++ doc/user/builders-writing.xml | 47 +++++++++++++++++++++++++++++++++++++++++++ src/CHANGES.txt | 4 ++++ 3 files changed, 67 insertions(+) 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. + 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 + + +# 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 + + SCons supports the following tool specifications out of the box: 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') +
+ Nested and namespace builders; + + + &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 + + + +# Regular non namespace target +env = Environment(ENV = os.environ, tools = ['SomeTool']) +env.SomeTool(targets, sources) + + + + The locations would include + SCons\Tool\SomeTool.py + SCons\Tool\SomeTool\__init__.py + .\site_scons\site_tools\SomeTool.py + .\site_scons\site_tools\SomeTool\__init__.py + + 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 + + + +# namespaced target +env = Environment(ENV = os.environ, tools = ['SubDir1.SubDir2.SomeTool']) +env.SomeTool(targets, sources) + + + + With this example the search locations would include + 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 + + 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). + + +
+