summaryrefslogtreecommitdiffstats
path: root/doc/user
diff options
context:
space:
mode:
authorGary Oberbrunner <garyo@oberbrunner.com>2010-06-03 01:40:26 (GMT)
committerGary Oberbrunner <garyo@oberbrunner.com>2010-06-03 01:40:26 (GMT)
commit3ebd1cd7be97f4e763c552b053db193e95262dfd (patch)
tree2ed74af7acea46957b5eaadf8ac438f12d5ae7cf /doc/user
parent4e1eae9dd17035d0a6beaf99a1ea85e20a68489d (diff)
downloadSCons-3ebd1cd7be97f4e763c552b053db193e95262dfd.zip
SCons-3ebd1cd7be97f4e763c552b053db193e95262dfd.tar.gz
SCons-3ebd1cd7be97f4e763c552b053db193e95262dfd.tar.bz2
Document GetBuildPath in Users Guide
Diffstat (limited to 'doc/user')
-rw-r--r--doc/user/nodes.in45
-rw-r--r--doc/user/nodes.xml45
2 files changed, 90 insertions, 0 deletions
diff --git a/doc/user/nodes.in b/doc/user/nodes.in
index d8169df..fb5ce23 100644
--- a/doc/user/nodes.in
+++ b/doc/user/nodes.in
@@ -332,6 +332,51 @@
</section>
+ <section>
+ <title>&GetBuildPath;: Getting the Path From a &Node; or String</title>
+
+ <para>
+
+ <function>env.GetBuildPath(file_or_list)</function>
+ returns the path of a &Node; or a string representing a
+ path. It can also take a list of &Node;s and/or strings, and
+ returns the list of paths. If passed a single &Node;, the result
+ is the same as calling <literal>str(node)</literal> (see above).
+ The string(s) can have embedded construction variables, which are
+ expanded as usual, using the calling environment's set of
+ variables. The paths can be files or directories, and do not have
+ to exist.
+
+ </para>
+
+ <scons_example name="GetBuildPath">
+ <file name="SConstruct" printme="1">
+ env=Environment(VAR="value")
+ n=File("foo.c")
+ print env.GetBuildPath([n, "sub/dir/$VAR"])
+ </file>
+ </scons_example>
+
+ <para>
+
+ Would print the following file names:
+
+ </para>
+
+ <scons_output example="GetBuildPath" os="posix">
+ <scons_output_command>scons -Q</scons_output_command>
+ </scons_output>
+
+ <para>
+
+ There is also a function version of &GetBuildPath; which can
+ be called without an &Environment;; that uses the default SCons
+ &Environment; to do substitution on any string arguments.
+
+ </para>
+
+ </section>
+
<!--
<section>
diff --git a/doc/user/nodes.xml b/doc/user/nodes.xml
index 8f3436a..e27d894 100644
--- a/doc/user/nodes.xml
+++ b/doc/user/nodes.xml
@@ -335,6 +335,51 @@
</section>
+ <section>
+ <title>&GetBuildPath;: Getting the Path From a &Node; or String</title>
+
+ <para>
+
+ <function>env.GetBuildPath(file_or_list)</function>
+ returns the path of a &Node; or a string representing a
+ path. It can also take a list of &Node;s and/or strings, and
+ returns the list of paths. If passed a single &Node;, the result
+ is the same as calling <literal>str(node)</literal> (see above).
+ The string(s) can have embedded construction variables, which are
+ expanded as usual, using the calling environment's set of
+ variables. The paths can be files or directories, and do not have
+ to exist.
+
+ </para>
+
+ <programlisting>
+ env=Environment(VAR="value")
+ n=File("foo.c")
+ print env.GetBuildPath([n, "sub/dir/$VAR"])
+ </programlisting>
+
+ <para>
+
+ Would print the following file names:
+
+ </para>
+
+ <screen>
+ % <userinput>scons -Q</userinput>
+ ['foo.c', 'sub/dir/value']
+ scons: `.' is up to date.
+ </screen>
+
+ <para>
+
+ There is also a function version of &GetBuildPath; which can
+ be called without an &Environment;; that uses the default SCons
+ &Environment; to do substitution on any string arguments.
+
+ </para>
+
+ </section>
+
<!--
<section>