summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/generated/functions.gen25
-rw-r--r--doc/generated/functions.mod4
-rw-r--r--doc/generated/tools.gen16
-rw-r--r--doc/generated/tools.mod4
-rw-r--r--doc/generated/variables.gen29
-rw-r--r--doc/generated/variables.mod2
-rw-r--r--doc/man/scons.xml16
-rw-r--r--doc/scons.mod1
-rw-r--r--doc/user/environments.xml169
9 files changed, 264 insertions, 2 deletions
diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen
index 8181d56c..e72740a2 100644
--- a/doc/generated/functions.gen
+++ b/doc/generated/functions.gen
@@ -3320,6 +3320,31 @@ Multiple targets can be passed in to a single call to
</para>
</listitem>
</varlistentry>
+ <varlistentry id="f-PyPackageDir">
+ <term>
+ <literal>PyPackageDir(modulename)</literal>
+ </term>
+ <term>
+ <literal>env.PyPackageDir(modulename)</literal>
+ </term>
+ <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+This returns a Directory Node similar to Dir.
+The python module / package is looked up and if located
+the directory is returned for the location.
+<varname>modulename</varname>
+Is a named python package / module to
+lookup the directory for it's location.
+</para>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If
+<varname>modulename</varname>
+is a list, SCons returns a list of Dir nodes.
+Construction variables are expanded in
+<varname>modulename</varname>.
+</para>
+</listitem>
+ </varlistentry>
<varlistentry id="f-Replace">
<term>
<literal>env.Replace(key=val, [...])</literal>
diff --git a/doc/generated/functions.mod b/doc/generated/functions.mod
index 61832939..e460aafe 100644
--- a/doc/generated/functions.mod
+++ b/doc/generated/functions.mod
@@ -69,6 +69,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT.
<!ENTITY f-PrependUnique "<function xmlns='http://www.scons.org/dbxsd/v1.0'>PrependUnique</function>">
<!ENTITY f-Progress "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Progress</function>">
<!ENTITY f-Pseudo "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Pseudo</function>">
+<!ENTITY f-PyPackageDir "<function xmlns='http://www.scons.org/dbxsd/v1.0'>PyPackageDir</function>">
<!ENTITY f-Replace "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Replace</function>">
<!ENTITY f-Repository "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Repository</function>">
<!ENTITY f-Requires "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Requires</function>">
@@ -152,6 +153,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT.
<!ENTITY f-env-PrependUnique "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.PrependUnique</function>">
<!ENTITY f-env-Progress "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.Progress</function>">
<!ENTITY f-env-Pseudo "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.Pseudo</function>">
+<!ENTITY f-env-PyPackageDir "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.PyPackageDir</function>">
<!ENTITY f-env-Replace "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.Replace</function>">
<!ENTITY f-env-Repository "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.Repository</function>">
<!ENTITY f-env-Requires "<function xmlns='http://www.scons.org/dbxsd/v1.0'>env.Requires</function>">
@@ -245,6 +247,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT.
<!ENTITY f-link-PrependUnique "<link linkend='f-PrependUnique' xmlns='http://www.scons.org/dbxsd/v1.0'><function>PrependUnique</function></link>">
<!ENTITY f-link-Progress "<link linkend='f-Progress' xmlns='http://www.scons.org/dbxsd/v1.0'><function>Progress</function></link>">
<!ENTITY f-link-Pseudo "<link linkend='f-Pseudo' xmlns='http://www.scons.org/dbxsd/v1.0'><function>Pseudo</function></link>">
+<!ENTITY f-link-PyPackageDir "<link linkend='f-PyPackageDir' xmlns='http://www.scons.org/dbxsd/v1.0'><function>PyPackageDir</function></link>">
<!ENTITY f-link-Replace "<link linkend='f-Replace' xmlns='http://www.scons.org/dbxsd/v1.0'><function>Replace</function></link>">
<!ENTITY f-link-Repository "<link linkend='f-Repository' xmlns='http://www.scons.org/dbxsd/v1.0'><function>Repository</function></link>">
<!ENTITY f-link-Requires "<link linkend='f-Requires' xmlns='http://www.scons.org/dbxsd/v1.0'><function>Requires</function></link>">
@@ -328,6 +331,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT.
<!ENTITY f-link-env-PrependUnique "<link linkend='f-PrependUnique' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.PrependUnique</function></link>">
<!ENTITY f-link-env-Progress "<link linkend='f-Progress' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.Progress</function></link>">
<!ENTITY f-link-env-Pseudo "<link linkend='f-Pseudo' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.Pseudo</function></link>">
+<!ENTITY f-link-env-PyPackageDir "<link linkend='f-PyPackageDir' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.PyPackageDir</function></link>">
<!ENTITY f-link-env-Replace "<link linkend='f-Replace' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.Replace</function></link>">
<!ENTITY f-link-env-Repository "<link linkend='f-Repository' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.Repository</function></link>">
<!ENTITY f-link-env-Requires "<link linkend='f-Requires' xmlns='http://www.scons.org/dbxsd/v1.0'><function>env.Requires</function></link>">
diff --git a/doc/generated/tools.gen b/doc/generated/tools.gen
index c0cc2f72..e3bc27f1 100644
--- a/doc/generated/tools.gen
+++ b/doc/generated/tools.gen
@@ -95,6 +95,22 @@ Sets construction variables for generic POSIX C copmilers.
</para>
<para>Sets: &cv-link-CC;, &cv-link-CCCOM;, &cv-link-CCFLAGS;, &cv-link-CFILESUFFIX;, &cv-link-CFLAGS;, &cv-link-CPPDEFPREFIX;, &cv-link-CPPDEFSUFFIX;, &cv-link-FRAMEWORKPATH;, &cv-link-FRAMEWORKS;, &cv-link-INCPREFIX;, &cv-link-INCSUFFIX;, &cv-link-SHCC;, &cv-link-SHCCCOM;, &cv-link-SHCCFLAGS;, &cv-link-SHCFLAGS;, &cv-link-SHOBJSUFFIX;.</para><para>Uses: &cv-link-PLATFORM;.</para></listitem>
</varlistentry>
+ <varlistentry id="t-clang">
+ <term>clang</term>
+ <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Set construction variables for the Clang C compiler.
+</para>
+<para>Sets: &cv-link-CC;, &cv-link-CCVERSION;, &cv-link-SHCCFLAGS;.</para></listitem>
+ </varlistentry>
+ <varlistentry id="t-clangxx">
+ <term>clangxx</term>
+ <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Set construction variables for the Clang C++ compiler.
+</para>
+<para>Sets: &cv-link-CXX;, &cv-link-CXXVERSION;, &cv-link-SHCXXFLAGS;, &cv-link-SHOBJSUFFIX;, &cv-link-STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME;.</para></listitem>
+ </varlistentry>
<varlistentry id="t-cvf">
<term>cvf</term>
<listitem>
diff --git a/doc/generated/tools.mod b/doc/generated/tools.mod
index bf552c33..1209d74f 100644
--- a/doc/generated/tools.mod
+++ b/doc/generated/tools.mod
@@ -18,6 +18,8 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT.
<!ENTITY t-as "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>as</literal>">
<!ENTITY t-bcc32 "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>bcc32</literal>">
<!ENTITY t-cc "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>cc</literal>">
+<!ENTITY t-clang "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>clang</literal>">
+<!ENTITY t-clangxx "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>clangxx</literal>">
<!ENTITY t-cvf "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>cvf</literal>">
<!ENTITY t-cXX "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>cXX</literal>">
<!ENTITY t-cyglink "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>cyglink</literal>">
@@ -124,6 +126,8 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT.
<!ENTITY t-link-as "<link linkend='t-as' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>as</literal></link>">
<!ENTITY t-link-bcc32 "<link linkend='t-bcc32' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>bcc32</literal></link>">
<!ENTITY t-link-cc "<link linkend='t-cc' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>cc</literal></link>">
+<!ENTITY t-link-clang "<link linkend='t-clang' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>clang</literal></link>">
+<!ENTITY t-link-clangxx "<link linkend='t-clangxx' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>clangxx</literal></link>">
<!ENTITY t-link-cvf "<link linkend='t-cvf' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>cvf</literal></link>">
<!ENTITY t-link-cXX "<link linkend='t-cXX' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>cXX</literal></link>">
<!ENTITY t-link-cyglink "<link linkend='t-cyglink' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>cyglink</literal></link>">
diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen
index 6ad5b6b1..39411371 100644
--- a/doc/generated/variables.gen
+++ b/doc/generated/variables.gen
@@ -3046,7 +3046,7 @@ The command line used to call the Java archive tool.
<para xmlns="http://www.scons.org/dbxsd/v1.0">
The string displayed when the Java archive tool
is called
-If this is not set, then <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-JARCOM"><envar>$JARCOM</envar></link> (the command line) is displayed.
+If this is not set, then <envar xmlns="http://www.scons.org/dbxsd/v1.0">$JARCOM</envar> (the command line) is displayed.
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -3056,7 +3056,7 @@ env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
<para xmlns="http://www.scons.org/dbxsd/v1.0">
The string displayed when the Java archive tool
is called
-If this is not set, then <envar xmlns="http://www.scons.org/dbxsd/v1.0">$JARCOM</envar> (the command line) is displayed.
+If this is not set, then <link xmlns="http://www.scons.org/dbxsd/v1.0" linkend="cv-JARCOM"><envar>$JARCOM</envar></link> (the command line) is displayed.
</para>
<example_commands xmlns="http://www.scons.org/dbxsd/v1.0">
@@ -4179,6 +4179,29 @@ window and importing the shell's environment variables.
</para>
</listitem>
</varlistentry>
+ <varlistentry id="cv-MSVC_UWP_APP">
+ <term>MSVC_UWP_APP</term>
+ <listitem>
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Build libraries for a Universal Windows Platform (UWP) Application.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+If <envar xmlns="http://www.scons.org/dbxsd/v1.0">$MSVC_UWP_APP</envar> is set, the Visual Studio environment will be set up to point
+to the Windows Store compatible libraries and Visual Studio runtimes. In doing so,
+any libraries that are built will be able to be used in a UWP App and published
+to the Windows Store.
+This flag will only have an effect with Visual Studio 2015+.
+This variable must be passed as an argument to the Environment()
+constructor; setting it later has no effect.
+</para>
+
+<para xmlns="http://www.scons.org/dbxsd/v1.0">
+Valid values are '1' or '0'
+</para>
+
+</listitem>
+ </varlistentry>
<varlistentry id="cv-MSVC_VERSION">
<term>MSVC_VERSION</term>
<listitem>
@@ -4196,6 +4219,8 @@ constructor; setting it later has no effect.
<para xmlns="http://www.scons.org/dbxsd/v1.0">
Valid values for Windows are
+<literal>14.0</literal>,
+<literal>14.0Exp</literal>,
<literal>12.0</literal>,
<literal>12.0Exp</literal>,
<literal>11.0</literal>,
diff --git a/doc/generated/variables.mod b/doc/generated/variables.mod
index 43d26041..319ac669 100644
--- a/doc/generated/variables.mod
+++ b/doc/generated/variables.mod
@@ -304,6 +304,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT.
<!ENTITY cv-MSSDK_VERSION "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$MSSDK_VERSION</envar>">
<!ENTITY cv-MSVC_BATCH "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$MSVC_BATCH</envar>">
<!ENTITY cv-MSVC_USE_SCRIPT "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$MSVC_USE_SCRIPT</envar>">
+<!ENTITY cv-MSVC_UWP_APP "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$MSVC_UWP_APP</envar>">
<!ENTITY cv-MSVC_VERSION "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$MSVC_VERSION</envar>">
<!ENTITY cv-MSVS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$MSVS</envar>">
<!ENTITY cv-MSVS_ARCH "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$MSVS_ARCH</envar>">
@@ -927,6 +928,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT.
<!ENTITY cv-link-MSSDK_VERSION "<link linkend='cv-MSSDK_VERSION' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$MSSDK_VERSION</envar></link>">
<!ENTITY cv-link-MSVC_BATCH "<link linkend='cv-MSVC_BATCH' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$MSVC_BATCH</envar></link>">
<!ENTITY cv-link-MSVC_USE_SCRIPT "<link linkend='cv-MSVC_USE_SCRIPT' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$MSVC_USE_SCRIPT</envar></link>">
+<!ENTITY cv-link-MSVC_UWP_APP "<link linkend='cv-MSVC_UWP_APP' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$MSVC_UWP_APP</envar></link>">
<!ENTITY cv-link-MSVC_VERSION "<link linkend='cv-MSVC_VERSION' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$MSVC_VERSION</envar></link>">
<!ENTITY cv-link-MSVS "<link linkend='cv-MSVS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$MSVS</envar></link>">
<!ENTITY cv-link-MSVS_ARCH "<link linkend='cv-MSVS_ARCH' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$MSVS_ARCH</envar></link>">
diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index b68f27ae..3268860b 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.</para>
+<para> 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</para>
+
+<programlisting>
+# 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
+</programlisting>
+
<para>SCons supports the following tool specifications out of the box:</para>
<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
diff --git a/doc/scons.mod b/doc/scons.mod
index 8d640541..448a2120 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -243,6 +243,7 @@
<!ENTITY PrependENVPath "<function xmlns='http://www.scons.org/dbxsd/v1.0'>PrependENVPath</function>">
<!ENTITY PrependUnique "<function xmlns='http://www.scons.org/dbxsd/v1.0'>PrependUnique</function>">
<!ENTITY Progress "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Progress</function>">
+<!ENTITY PyPackageDir "<function xmlns='http://www.scons.org/dbxsd/v1.0'>PyPackageDir</function>">
<!ENTITY Replace "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Replace</function>">
<!ENTITY Repository "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Repository</function>">
<!ENTITY Requires "<function xmlns='http://www.scons.org/dbxsd/v1.0'>Requires</function>">
diff --git a/doc/user/environments.xml b/doc/user/environments.xml
index d1da3f9c..ae670a80 100644
--- a/doc/user/environments.xml
+++ b/doc/user/environments.xml
@@ -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>
View Lorry Controller Status