From: garyo <garyo@fdb21ef1-2011-0410-befe-b5e4ea1792b1>
Date: Wed, 19 Nov 2008 01:29:38 +0000 (+0000)
Subject: Update Users Guide to clarify usage of site_scons and site_init.py.
X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=d9d39141d8f2028abd4f0cfdd0602684b60ab67d;p=scons.git

Update Users Guide to clarify usage of site_scons and site_init.py.

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

diff --git a/doc/user/README b/doc/user/README
index bdccf519..2d05359b 100644
--- a/doc/user/README
+++ b/doc/user/README
@@ -3,7 +3,7 @@
 When adding a new file, add it to main.xml and MANIFEST.
 
 To build the .xml files from the .in files:
-  scons -D . BUILDDOC=1
+  scons -D BUILDDOC=1 foo.xml
 To build the whole PDF doc from this dir, for testing:
   scons -D ../../build/doc/PDF/scons-user.pdf 
 
diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in
index b9539756..dc6e95b9 100644
--- a/doc/user/builders-writing.in
+++ b/doc/user/builders-writing.in
@@ -955,17 +955,22 @@ This functionality could be invoked as in the following example:
     to include in &SConscript;s; just put that module in
     <filename>site_scons/my_utils.py</filename> or any valid Python module name of your
     choice.  For instance you can do something like this in
-    <filename>site_scons/my_utils.py</filename> to add a build_id method:
+    <filename>site_scons/my_utils.py</filename> to add build_id and MakeWorkDir functions:
   </para>
     
   <scons_example name="site2">
     <file name="site_scons/my_utils.py" printme=1>
+      from SCons.Script import *   # for Execute and Mkdir
       def build_id():
          """Return a build ID (stub version)"""
          return "100"
+      def MakeWorkDir(workdir):
+         """Create the specified dir immediately"""
+         Execute(Mkdir(workdir))
     </file>
     <file name="SConscript">
       import my_utils
+      MakeWorkDir('/tmp/work')
       print "build_id=" + my_utils.build_id()
     </file>
   </scons_example>
@@ -980,8 +985,27 @@ This functionality could be invoked as in the following example:
   <sconstruct>
       import my_utils
       print "build_id=" + my_utils.build_id()
+      my_utils.MakeWorkDir('/tmp/work')
   </sconstruct>
 
+  <para>
+    Note that although you can put this library in
+    <filename>site_scons/site_init.py</filename>,
+    it is no better there than <filename>site_scons/my_utils.py</filename>
+    since you still have to import that module into your &SConscript;.
+    Also note that in order to refer to objects in the SCons namespace
+    such as &Environment; or &Mkdir; or &Execute; in any file other
+    than a &SConstruct; or &SConscript; you always need to do
+  </para>
+  <sconstruct>
+      from SCons.Script import *
+  </sconstruct>
+
+  <para>
+    This is true in modules in <filename>site_scons</filename> such as
+    <filename>site_scons/site_init.py</filename> as well.
+  </para>
+
   <para>
 
     If you have a machine-wide site dir you'd like to use instead of
diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml
index c45af8a0..2c0f6974 100644
--- a/doc/user/builders-writing.xml
+++ b/doc/user/builders-writing.xml
@@ -828,13 +828,17 @@ This functionality could be invoked as in the following example:
     to include in &SConscript;s; just put that module in
     <filename>site_scons/my_utils.py</filename> or any valid Python module name of your
     choice.  For instance you can do something like this in
-    <filename>site_scons/my_utils.py</filename> to add a build_id method:
+    <filename>site_scons/my_utils.py</filename> to add build_id and MakeWorkDir functions:
   </para>
     
   <programlisting>
+      from SCons.Script import *   # for Execute and Mkdir
       def build_id():
          """Return a build ID (stub version)"""
          return "100"
+      def MakeWorkDir(workdir):
+         """Create the specified dir immediately"""
+         Execute(Mkdir(workdir))
   </programlisting>
 
   <para>
@@ -847,8 +851,27 @@ This functionality could be invoked as in the following example:
   <programlisting>
       import my_utils
       print "build_id=" + my_utils.build_id()
+      my_utils.MakeWorkDir('/tmp/work')
   </programlisting>
 
+  <para>
+    Note that although you can put this library in
+    <filename>site_scons/site_init.py</filename>,
+    it is no better there than <filename>site_scons/my_utils.py</filename>
+    since you still have to import that module into your &SConscript;.
+    Also note that in order to refer to objects in the SCons namespace
+    such as &Environment; or &Mkdir; or &Execute; in any file other
+    than a &SConstruct; or &SConscript; you always need to do
+  </para>
+  <programlisting>
+      from SCons.Script import *
+  </programlisting>
+
+  <para>
+    This is true in modules in <filename>site_scons</filename> such as
+    <filename>site_scons/site_init.py</filename> as well.
+  </para>
+
   <para>
 
     If you have a machine-wide site dir you'd like to use instead of