Merged revisions 2928-2932,2934-2946 via svnmerge from

http://scons.tigris.org/svn/scons/branches/core

........
  r2932 | garyo | 2008-04-30 09:14:38 -0700 (Wed, 30 Apr 2008) | 1 line

  Add doc for site_scons dir and related options.  Closes issue #1996.
........
  r2934 | stevenknight | 2008-04-30 22:05:38 -0700 (Wed, 30 Apr 2008) | 3 lines

  Issue 2039:  Fix a syntax error in Intel C compiler support on Windows.
  (Jonas Olsson)
........
  r2935 | belley | 2008-05-01 06:59:21 -0700 (Thu, 01 May 2008) | 10 lines

  test/KeyboardInterrupt.py no longer hangs under Cygwin.

  There seems to be a bug on Cygwin where the compiler process hangs
  after sending the SIGINT signal to the process group. It is probably a
  bug in cygwin1.dll, or maybe in the Python 'C' code or the Python
  subprocess module. We therefore do not use 'killpg' on Cygwin.

  Benoit
........
  r2936 | belley | 2008-05-01 07:10:23 -0700 (Thu, 01 May 2008) | 12 lines

  cell_contents not defined in python < 2.5. [Issue 2035]

  Some versions of Python supports lexical scoping of local variables
  (aka closures) but not the cell_contents attribute that would allow
  the FunctionAction signature that take the content of these closure
  cells into account. The access to the cell_contents attribute is now
  protected with a try/except AttributeError so that at least the other
  parts of the function signature are properly computed.

  Benoit
........
  r2937 | stevenknight | 2008-05-01 12:08:25 -0700 (Thu, 01 May 2008) | 3 lines

  When running tests, allow the user to set the $SCONSIGN variable to pick a
  specific sconsign script to execute.
........
  r2938 | stevenknight | 2008-05-02 19:13:14 -0700 (Fri, 02 May 2008) | 2 lines

  Set svn:ignore to '*.py[co]'.
........
  r2939 | stevenknight | 2008-05-08 21:07:18 -0700 (Thu, 08 May 2008) | 4 lines

  Issue 2033:  Fix excessive memory use when a Python Value node's
  representation is stored in a .sconsign file and then re-stored
  after being interpreted with escaped backslashes and quotes.
........
  r2940 | cournape | 2008-05-16 03:56:49 -0700 (Fri, 16 May 2008) | 1 line

  Fix issue 2054.
........
  r2941 | stevenknight | 2008-05-16 12:02:45 -0700 (Fri, 16 May 2008) | 8 lines

  Issue 2045:  After a Node has failed its build and we're propagating
  the failure to other Nodes on the candidate list, don't marke candidate
  Nodes as FAILED if they've already been visited and been determined
  to be up-to-date.  This avoids problems with Configure tests not
  running because failure of an earlier Configure tests caused (e.g.)
  /usr/bin/g++ to get marked as FAILED, making SCons think it doesn't
  need to bother trying to rebuild anything that will use it...
........
  r2942 | stevenknight | 2008-05-16 12:10:14 -0700 (Fri, 16 May 2008) | 8 lines

  Improve the regular expressions used by the test infrastructure to
  examine SCons output to decide if a list of targets are considered
  up-to-date or not.  The new code uses the re.escape() function instead
  of hand-escaping '.' and '\n'.  This required a little restructuring in
  the not_up_to_date() method to escape the characters within the arguments
  themselves, but not the surrounding characters we use to construct the
  regex that makes sure those strings *don't* exist in the output.
........
  r2943 | stevenknight | 2008-05-16 14:04:23 -0700 (Fri, 16 May 2008) | 3 lines

  Issue 2049:  Handle multiple pipe-separated values in Visual Studio for
  INCLUDE, LIB and PATH.  Still only uses Win32, not any other values.
........
  r2944 | stevenknight | 2008-05-16 18:36:27 -0700 (Fri, 16 May 2008) | 2 lines

  Record changes by David Cournapeau and Benoit Belley.
........
  r2945 | stevenknight | 2008-05-17 07:13:46 -0700 (Sat, 17 May 2008) | 3 lines

  Pass in dc as a keyword argument to _smartLink for older Python versions
  without nested scopes.
........
  r2946 | stevenknight | 2008-05-17 07:14:01 -0700 (Sat, 17 May 2008) | 3 lines

  Expect a warning about shadowing global variables on Python 2.1.
  (This code can go away after we release 1.0.)
........

6 files changed, 274 insertions, 13 deletions

diff --git a/doc/user/add-method.in b/doc/user/add-method.in
index 853b9a8..a0a6039 100644
--- a/doc/user/add-method.in
+++ b/doc/user/add-method.in
@@ -72,7 +72,7 @@
 
   <scons_example name="ex2">
      <file name="SConstruct" printme="1">
-     import sys;
+     import sys
      def BuildTestProg(env, testfile, resourcefile, testdir="tests"):
          """Build the test program;
          prepends "test_" to src and target, and puts target into testdir."""
@@ -103,3 +103,9 @@
     <scons_output_command>scons -Q</scons_output_command>
   </scons_output>
 
+  <para>
+  Using AddMethod is better than just adding an instance method to an
+  Environment because it gets called as a proper method, and AddMethod
+  provides for copying the method to any copies of the Environment
+  instance.
+  </para>
diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml
index 22f5f1a..7e84b80 100644
--- a/doc/user/add-method.xml
+++ b/doc/user/add-method.xml
@@ -98,3 +98,9 @@
     cc -o tests/test_stuff test_stuff.o
   </screen>
 
+  <para>
+  Using AddMethod is better than just adding an instance method to an
+  Environment because it gets called as a proper method, and AddMethod
+  provides for copying the method to any copies of the Environment
+  instance.
+  </para>
diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in
index 2285ac8..67a95f9 100644
--- a/doc/user/builders-writing.in
+++ b/doc/user/builders-writing.in
@@ -761,6 +761,144 @@ This functionality could be invoked as in the following example:
 
   </section>
 
+  <section>
+  <title>Where To Put Your Custom Builders and Tools</title>
+
+  <para>
+
+  The <filename>site_scons</filename> directory gives you a place to
+  put Python modules you can import into your SConscripts
+  (site_scons), add-on tools that can integrate into &SCons;
+  (site_scons/site_tools), and a site_scons/site_init.py file that
+  gets read before any &SConstruct; or &SConscript;, allowing you to
+  change &SCons;'s default behavior.
+
+  </para>
+
+  <para>
+
+  If you get a tool from somewhere (the &SCons; wiki or a third party,
+  for instance) and you'd like to use it in your project, the
+  <filename>site_scons</filename> dir is the simplest place to put it.
+  Tools come in two flavors; either a Python function that operates on
+  an &Environment; or a Python file containing two functions, exists()
+  and generate().
+
+  </para>
+
+  <para>
+
+  A single-function Tool can just be included in your
+  <filename>site_scons/site_init.py</filename> file where it will be
+  parsed and made available for use.  For instance, you could have a
+  <filename>site_scons/site_init.py</filename> file like this:
+
+  </para>
+
+  <scons_example name="site1">
+    <file name="site_scons/site_init.py" printme=1>
+      def TOOL_ADD_HEADER(env):
+         """A Tool to add a header from $HEADER to the source file"""
+         add_header = Builder(action=['echo "$HEADER" > $TARGET',
+                                      'cat $SOURCE >> $TARGET'])
+         env.Append(BUILDERS = {'AddHeader' : add_header})
+         env['HEADER'] = '' # set default value
+    </file>
+    <file name="SConstruct">
+      env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====")
+      env.AddHeader('tgt', 'src')
+    </file>
+    <file name="src">
+      hi there
+    </file>
+  </scons_example>
+
+  <para>
+
+  and a &SConstruct; like this:
+
+  </para>
+
+  <sconstruct>
+      # Use TOOL_ADD_HEADER from site_scons/site_init.py
+      env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====")
+      env.AddHeader('tgt', 'src')
+  </sconstruct>
+
+  <para>
+
+    The <function>TOOL_ADD_HEADER</function> tool method will be
+    called to add the <function>AddHeader</function> tool to the
+    environment.
+
+  </para>
+
+  <!-- 
+  <scons_output example="site1" os="posix">
+     <scons_output_command>scons -Q</scons_output_command>
+  </scons_output>
+  -->
+
+  <para>
+    Similarly, a more full-fledged tool with
+    <function>exists()</function> and <function>generate()</function>
+    methods can be installed in
+    <filename>site_scons/site_tools/toolname.py</filename>.  Since
+    <filename>site_scons/site_tools</filename> is automatically added
+    to the head of the tool search path, any tool found there will be
+    available to all environments.  Furthermore, a tool found there
+    will override a built-in tool of the same name, so if you need to
+    change the behavior of a built-in tool, site_scons gives you the
+    hook you need.
+  </para>
+
+  <para>
+    Many people have a library of utility Python functions they'd like
+    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:
+  </para>
+    
+  <scons_example name="site2">
+    <file name="site_scons/my_utils.py" printme=1>
+      def build_id():
+         """Return a build ID (stub version)"""
+	 return "100"
+    </file>
+    <file name="SConscript">
+      import my_utils
+      print "build_id=" + my_utils.build_id()
+    </file>
+  </scons_example>
+
+  <para>
+
+  And then in your &SConscript; or any sub-&SConscript; anywhere in
+  your build, you can import <filename>my_utils</filename> and use it:
+
+  </para>
+
+  <sconstruct>
+      import my_utils
+      print "build_id=" + my_utils.build_id()
+  </sconstruct>
+
+  <para>
+
+    If you have a machine-wide site dir you'd like to use instead of
+    <filename>./site_scons</filename>, use the
+    <literal>--site-dir</literal> option to point to your dir.
+    <filename>site_init.py</filename> and
+    <filename>site_tools</filename> will be located under that dir.
+    To avoid using a <filename>site_scons</filename> dir at all, even
+    if it exists, use the <literal>--no-site-dir</literal> option.
+
+  </para>
+
+  </section>
+
+
   <!--
 
   <section>
diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml
index 8ab4fca..df3affa 100644
--- a/doc/user/builders-writing.xml
+++ b/doc/user/builders-writing.xml
@@ -659,6 +659,129 @@ This functionality could be invoked as in the following example:
 
   </section>
 
+  <section>
+  <title>Where To Put Your Custom Builders and Tools</title>
+
+  <para>
+
+  The <filename>site_scons</filename> directory gives you a place to
+  put Python modules you can import into your SConscripts
+  (site_scons), add-on tools that can integrate into &SCons;
+  (site_scons/site_tools), and a site_scons/site_init.py file that
+  gets read before any &SConstruct; or &SConscript;, allowing you to
+  change &SCons;'s default behavior.
+
+  </para>
+
+  <para>
+
+  If you get a tool from somewhere (the &SCons; wiki or a third party,
+  for instance) and you'd like to use it in your project, the
+  <filename>site_scons</filename> dir is the simplest place to put it.
+  Tools come in two flavors; either a Python function that operates on
+  an &Environment; or a Python file containing two functions, exists()
+  and generate().
+
+  </para>
+
+  <para>
+
+  A single-function Tool can just be included in your
+  <filename>site_scons/site_init.py</filename> file where it will be
+  parsed and made available for use.  For instance, you could have a
+  <filename>site_scons/site_init.py</filename> file like this:
+
+  </para>
+
+  <programlisting>
+      def TOOL_ADD_HEADER(env):
+         """A Tool to add a header from $HEADER to the source file"""
+         add_header = Builder(action=['echo "$HEADER" &gt; $TARGET',
+                                      'cat $SOURCE &gt;&gt; $TARGET'])
+         env.Append(BUILDERS = {'AddHeader' : add_header})
+         env['HEADER'] = '' # set default value
+  </programlisting>
+
+  <para>
+
+  and a &SConstruct; like this:
+
+  </para>
+
+  <programlisting>
+      # Use TOOL_ADD_HEADER from site_scons/site_init.py
+      env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====")
+      env.AddHeader('tgt', 'src')
+  </programlisting>
+
+  <para>
+
+    The <function>TOOL_ADD_HEADER</function> tool method will be
+    called to add the <function>AddHeader</function> tool to the
+    environment.
+
+  </para>
+
+  <!-- 
+  <scons_output example="site1" os="posix">
+     <scons_output_command>scons -Q</scons_output_command>
+  </scons_output>
+  -->
+
+  <para>
+    Similarly, a more full-fledged tool with
+    <function>exists()</function> and <function>generate()</function>
+    methods can be installed in
+    <filename>site_scons/site_tools/toolname.py</filename>.  Since
+    <filename>site_scons/site_tools</filename> is automatically added
+    to the head of the tool search path, any tool found there will be
+    available to all environments.  Furthermore, a tool found there
+    will override a built-in tool of the same name, so if you need to
+    change the behavior of a built-in tool, site_scons gives you the
+    hook you need.
+  </para>
+
+  <para>
+    Many people have a library of utility Python functions they'd like
+    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:
+  </para>
+    
+  <programlisting>
+      def build_id():
+         """Return a build ID (stub version)"""
+	 return "100"
+  </programlisting>
+
+  <para>
+
+  And then in your &SConscript; or any sub-&SConscript; anywhere in
+  your build, you can import <filename>my_utils</filename> and use it:
+
+  </para>
+
+  <programlisting>
+      import my_utils
+      print "build_id=" + my_utils.build_id()
+  </programlisting>
+
+  <para>
+
+    If you have a machine-wide site dir you'd like to use instead of
+    <filename>./site_scons</filename>, use the
+    <literal>--site-dir</literal> option to point to your dir.
+    <filename>site_init.py</filename> and
+    <filename>site_tools</filename> will be located under that dir.
+    To avoid using a <filename>site_scons</filename> dir at all, even
+    if it exists, use the <literal>--no-site-dir</literal> option.
+
+  </para>
+
+  </section>
+
+
   <!--
 
   <section>
diff --git a/doc/user/main.in b/doc/user/main.in
index 8981b14..0dbadfc 100644
--- a/doc/user/main.in
+++ b/doc/user/main.in
@@ -135,16 +135,10 @@
 
   XXX CheckTypeSize()
 
-  XXX Glob()
-
   XXX Progress()
 
   XXX - - diskcheck=
 
-  XXX site_scons
-  XXX - - site-dir
-  XXX - - no-site-dir
-
   XXX - - warn=
 
   XXX ARGLIST
diff --git a/doc/user/main.xml b/doc/user/main.xml
index 8981b14..0dbadfc 100644
--- a/doc/user/main.xml
+++ b/doc/user/main.xml
@@ -135,16 +135,10 @@
 
   XXX CheckTypeSize()
 
-  XXX Glob()
-
   XXX Progress()
 
   XXX - - diskcheck=
 
-  XXX site_scons
-  XXX - - site-dir
-  XXX - - no-site-dir
-
   XXX - - warn=
 
   XXX ARGLIST