Issue 1982: document GetLaunchDir() in the User's Guide.

4 files changed, 97 insertions, 0 deletions

diff --git a/doc/scons.mod b/doc/scons.mod
index b924a24..767b40c 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -191,6 +191,7 @@
 <!ENTITY Flatten "<function>Flatten</function>">
 <!ENTITY GenerateHelpText "<function>GenerateHelpText</function>">
 <!ENTITY GetBuildFailures "<function>GetBuildFailures</function>">
+<!ENTITY GetLaunchDir "<function>GetLaunchDir</function>">
 <!ENTITY GetOption "<function>GetOption</function>">
 <!ENTITY Glob "<function>Glob</function>">
 <!ENTITY Help "<function>Help</function>">
diff --git a/doc/user/misc.in b/doc/user/misc.in
index 21bb0bb..cb969e7 100644
--- a/doc/user/misc.in
+++ b/doc/user/misc.in
@@ -373,3 +373,49 @@
     </screen>
 
   </section>
+
+  <section>
+  <title>Finding the Invocation Directory:  the &GetLaunchDir; Function</title>
+
+    <para>
+
+    If you need to find the directory from
+    which the user invoked the &scons; command,
+    you can use the &GetLaunchDir; function:
+
+    </para>
+
+    <sconstruct>
+      env = Environment(
+          LAUNCHDIR = GetLaunchDir(),
+      )
+      env.Command('directory_build_info',
+                  '$LAUNCHDIR/build_info'
+                  Copy('$TARGET', '$SOURCE'))
+    </sconstruct>
+
+    <para>
+
+    Because &SCons; is usually invoked from the top-level
+    directory in which the &SConstruct; file lives,
+    the Python <function>os.getcwd()</function>
+    is often equivalent.
+    However, the &SCons;
+    <literal>-u</literal>,
+    <literal>-U</literal>
+    and
+    <literal>-D</literal>
+    command-line options,
+    when invoked from a subdirectory,
+    will cause &SCons; to change to the directory
+    in which the &SConstruct; file is found.
+    When those options are used,
+    &GetLaunchDir; will still return the path to the
+    user's invoking subdirectory,
+    allowing the &SConscript; configuration
+    to still get at configuration (or other) files
+    from the originating directory.
+
+    </para>
+
+  </section>
diff --git a/doc/user/misc.xml b/doc/user/misc.xml
index 54b021a..c5f29b6 100644
--- a/doc/user/misc.xml
+++ b/doc/user/misc.xml
@@ -353,3 +353,49 @@
     </screen>
 
   </section>
+
+  <section>
+  <title>Finding the Invocation Directory:  the &GetLaunchDir; Function</title>
+
+    <para>
+
+    If you need to find the directory from
+    which the user invoked the &scons; command,
+    you can use the &GetLaunchDir; function:
+
+    </para>
+
+    <programlisting>
+      env = Environment(
+          LAUNCHDIR = GetLaunchDir(),
+      )
+      env.Command('directory_build_info',
+                  '$LAUNCHDIR/build_info'
+                  Copy('$TARGET', '$SOURCE'))
+    </programlisting>
+
+    <para>
+
+    Because &SCons; is usually invoked from the top-level
+    directory in which the &SConstruct; file lives,
+    the Python <function>os.getcwd()</function>
+    is often equivalent.
+    However, the &SCons;
+    <literal>-u</literal>,
+    <literal>-U</literal>
+    and
+    <literal>-D</literal>
+    command-line options,
+    when invoked from a subdirectory,
+    will cause &SCons; to change to the directory
+    in which the &SConstruct; file is found.
+    When those options are used,
+    &GetLaunchDir; will still return the path to the
+    user's invoking subdirectory,
+    allowing the &SConscript; configuration
+    to still get at configuration (or other) files
+    from the originating directory.
+
+    </para>
+
+  </section>
diff --git a/src/CHANGES.txt b/src/CHANGES.txt
index 2c8bd26..292c741 100644
--- a/src/CHANGES.txt
+++ b/src/CHANGES.txt
@@ -20,6 +20,10 @@ RELEASE 1.0.0 - XXX
 
     - Document the ParseDepends() function in the User's Guide.
 
+  From Steven Knight:
+
+    - Document the GetLaunchDir() function in the User's Guide.
+
   From Greg Noel:
 
     - Handle yacc/bison on newer Mac OS X versions creating file.hpp,