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

git-svn-id: http://scons.tigris.org/svn/scons/trunk@3306 fdb21ef1-2011-0410-befe-b5e4ea1792b1

diff --git a/doc/scons.mod b/doc/scons.mod
index b924a249770c046883628d5bf4501a5357138e05..767b40cef139a3ad51c4251ba5560fa4fca1ef3e 100644 (file)
--- 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 21bb0bb77d1e7ecdb9982d776bfa28c5bf6b58ec..cb969e71f6b1abc131b57725888f4d484cfe1034 100644 (file)
--- 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 54b021a0a86edbc3758a358ac0317a609c3eaee8..c5f29b684d11774b36d30122014ba6734a30d73d 100644 (file)
--- 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 2c8bd267784d523358be108188dd3a4fa0fb837e..292c7411adbf478af5bc49b64de221d48e30aee7 100644 (file)
--- 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,