Merge commit 'upstream/2.1.0'

112 files changed, 911 insertions, 4376 deletions

diff --git a/doc/SConscript b/doc/SConscript
index e0b3f71..54b620e 100644
--- a/doc/SConscript
+++ b/doc/SConscript
@@ -3,7 +3,7 @@
 #
 
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -43,7 +43,7 @@ dist_doc_tar_gz = '$DISTDIR/scons-doc-${VERSION}.tar.gz'
 # if lynx is available to do the dump.
 #
 fig2dev = whereis('fig2dev')
-epydoc = whereis('epydoc')
+epydoc_cli = whereis('epydoc')
 groff = whereis('groff')
 lynx = whereis('lynx')
 man2html = whereis('man2html')
@@ -121,7 +121,7 @@ scons_doc_files = list(map(chop, open(manifest_xml_in).readlines()))
 scons_doc_files = [File('#src/engine/'+x).rstr() for x in scons_doc_files]
 
 if not jw:
-    print "jw not found, skipping building User Guide."
+    print "doc: jw not found, skipping building User Guide."
 else:
     #
     # Always create a version.xml file containing the version information
@@ -151,6 +151,8 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 
     builders_gen = os.path.join(build, 'user', 'builders.gen')
     builders_mod = os.path.join(build, 'user', 'builders.mod')
+    functions_gen = os.path.join(build, 'user', 'functions.gen')
+    functions_mod = os.path.join(build, 'user', 'functions.mod')
     tools_gen = os.path.join(build, 'user', 'tools.gen')
     tools_mod = os.path.join(build, 'user', 'tools.mod')
     variables_gen = os.path.join(build, 'user', 'variables.gen')
@@ -163,11 +165,12 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
     # vs. the other.  The *.gen and *.mod targets will still be dependent
     # on the list of the files themselves.
     doc_output_files = [builders_gen, builders_mod,
+                        functions_gen, functions_mod,
                         tools_gen, tools_mod,
                         variables_gen, variables_mod]
     b = env.Command(doc_output_files,
                     scons_doc_files,
-                    "$PYTHON $SCONS_PROC_PY --xml -b ${TARGETS[0]},${TARGETS[1]} -t ${TARGETS[2]},${TARGETS[3]} -v ${TARGETS[4]},${TARGETS[5]} $( $SOURCES $)")
+                    "$PYTHON $SCONS_PROC_PY --xml -b ${TARGETS[0]},${TARGETS[1]} -f ${TARGETS[2]},${TARGETS[3]} -t ${TARGETS[4]},${TARGETS[5]} -v ${TARGETS[6]},${TARGETS[7]} $( $SOURCES $)")
     env.Depends(b, "$SCONS_PROC_PY")
 
     env.Local(b)
@@ -403,11 +406,11 @@ for m in man_page_list:
     x = orig_env.SCons_revision(os.path.join(build, 'man', m),
                             os.path.join('man', m))
 
-man_i_files = ['builders.man', 'tools.man', 'variables.man']
+man_i_files = ['builders.man', 'functions.man', 'tools.man', 'variables.man']
 
 man_intermediate_files = [os.path.join(build, 'man', x) for x in man_i_files]
 
-cmd = "$PYTHON $SCONS_PROC_PY --man -b ${TARGETS[0]} -t ${TARGETS[1]} -v ${TARGETS[2]} $( $SOURCES $)"
+cmd = "$PYTHON $SCONS_PROC_PY --man -b ${TARGETS[0]} -f ${TARGETS[1]} -t ${TARGETS[2]} -v ${TARGETS[3]} $( $SOURCES $)"
 man_intermediate_files = env.Command(man_intermediate_files,
                                      scons_doc_files,
                                      cmd)
@@ -458,8 +461,79 @@ for man_1 in man_page_list:
         tar_deps.append(html)
         tar_list.append(html)
 
-if not epydoc:
-    print "epydoc not found, skipping building API documentation."
+if not epydoc_cli:
+    try:
+        import epydoc
+    except ImportError:
+        epydoc = None
+    else:
+        # adding Epydoc builder using imported module
+        def epydoc_builder_action(target, source, env):
+            """
+            Take a list of `source` files and build docs for them in
+            `target` dir.
+
+            `target` and `source` are lists.
+
+            Uses OUTDIR and EPYDOCFLAGS environment variables.
+
+            http://www.scons.org/doc/2.0.1/HTML/scons-user/x3594.html
+            """
+
+            # the epydoc build process is the following:
+            # 1. build documentation index
+            # 2. feed doc index to writer for docs
+
+            from epydoc.docbuilder import build_doc_index
+            from epydoc.docwriter.html import HTMLWriter
+            from epydoc.docwriter.latex import LatexWriter
+
+            # first arg is a list where can be names of python package dirs,
+            # python files, object names or objects itself
+            docindex = build_doc_index([str(src) for src in source])
+            if docindex == None:
+                return -1
+
+            if env['EPYDOCFLAGS'] == '--html':
+                html_writer = HTMLWriter(docindex,
+                                         docformat='restructuredText',
+                                         prj_name='SCons',
+                                         prj_url='http://www.scons.org/')
+                try:
+                    html_writer.write(env['OUTDIR'])
+                except OSError: # If directory cannot be created or any file cannot
+                                # be created or written to.
+                    return -2
+
+            """
+            # PDF support requires external Linux utilites, so it's not crossplatform.
+            # Leaving for now.
+            # http://epydoc.svn.sourceforge.net/viewvc/epydoc/trunk/epydoc/src/epydoc/cli.py
+
+            elif env['EPYDOCFLAGS'] == '--pdf':
+                pdf_writer = LatexWriter(docindex, 
+                                         docformat='restructuredText',
+                                         prj_name='SCons',
+                                         prj_url='http://www.scons.org/')
+            """
+            return 0
+
+        epydoc_commands = [
+            Delete('$OUTDIR'),
+            epydoc_builder_action,
+            Touch('$TARGET'),
+        ]
+
+else: # epydoc_cli is found
+    epydoc_commands = [
+        Delete('$OUTDIR'),
+        '$EPYDOC $EPYDOCFLAGS --debug --output $OUTDIR --docformat=restructuredText --name SCons --url http://www.scons.org/ $SOURCES',
+        Touch('$TARGET'),
+    ]
+
+     
+if not epydoc_cli and not epydoc:
+    print "doc: epydoc not found, skipping building API documentation."
 else:
     # XXX Should be in common with reading the same thing in
     # the SConstruct file.
@@ -475,40 +549,37 @@ else:
     e = os.path.join(build, '..', 'scons', 'engine')
     sources = [os.path.join(e, x) for x in sources]
 
-    epydoc_commands = [
-        Delete('$OUTDIR'),
-        '$EPYDOC $EPYDOCFLAGS --debug --output $OUTDIR --docformat=restructuredText --name SCons --url http://www.scons.org/ $SOURCES',
-        Touch('$TARGET'),
-    ]
-
     htmldir = os.path.join(build, 'HTML', 'scons-api')
     env.Command('${OUTDIR}/index.html', sources, epydoc_commands,
-                EPYDOC=epydoc, EPYDOCFLAGS='--html', OUTDIR=htmldir)
+                EPYDOC=epydoc_cli, EPYDOCFLAGS='--html', OUTDIR=htmldir)
     tar_deps.append(htmldir)
     tar_list.append(htmldir)
 
-    # PDF and PostScript and TeX are built from the
-    # same invocation.
-    api_dir = os.path.join(build, 'scons-api')
-    api_pdf = os.path.join(api_dir, 'api.pdf')
-    api_ps = os.path.join(api_dir, 'api.ps')
-    api_tex = os.path.join(api_dir, 'api.tex')
-    api_targets = [api_pdf, api_ps, api_tex]
-    env.Command(api_targets, sources, epydoc_commands,
-                EPYDOC=epydoc, EPYDOCFLAGS='--pdf', OUTDIR=api_dir)
-    Local(api_targets)
-
-    pdf_install = os.path.join(build, 'PDF', 'scons-api.pdf')
-    env.InstallAs(pdf_install, api_pdf)
-    tar_deps.append(pdf_install)
-    tar_list.append(pdf_install)
-    Local(pdf_install)
-
-    ps_install = os.path.join(build, 'PS', 'scons-api.ps')
-    env.InstallAs(ps_install, api_ps)
-    tar_deps.append(ps_install)
-    tar_list.append(ps_install)
-    Local(ps_install)
+    if not epydoc_cli:
+        print "doc: command line epydoc is not found, skipping PDF/PS/Tex output"
+    else:
+        # PDF and PostScript and TeX are built from the
+        # same invocation.
+        api_dir = os.path.join(build, 'scons-api')
+        api_pdf = os.path.join(api_dir, 'api.pdf')
+        api_ps = os.path.join(api_dir, 'api.ps')
+        api_tex = os.path.join(api_dir, 'api.tex')
+        api_targets = [api_pdf, api_ps, api_tex]
+        env.Command(api_targets, sources, epydoc_commands,
+                    EPYDOC=epydoc_cli, EPYDOCFLAGS='--pdf', OUTDIR=api_dir)
+        Local(api_targets)
+
+        pdf_install = os.path.join(build, 'PDF', 'scons-api.pdf')
+        env.InstallAs(pdf_install, api_pdf)
+        tar_deps.append(pdf_install)
+        tar_list.append(pdf_install)
+        Local(pdf_install)
+
+        ps_install = os.path.join(build, 'PS', 'scons-api.ps')
+        env.InstallAs(ps_install, api_ps)
+        tar_deps.append(ps_install)
+        tar_list.append(ps_install)
+        Local(ps_install)
 
 #
 # Now actually create the tar file of the documentation,
diff --git a/doc/design/scons.mod b/doc/design/scons.mod
index 012bc3e..33538fb 100644
--- a/doc/design/scons.mod
+++ b/doc/design/scons.mod
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   An SCons-specific DTD module, for use with SCons DocBook
   documentation, that contains names, phrases, acronyms, etc. used
diff --git a/doc/developer/architecture.xml b/doc/developer/architecture.xml
index e7c2f56..c122148 100644
--- a/doc/developer/architecture.xml
+++ b/doc/developer/architecture.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/developer/branches.xml b/doc/developer/branches.xml
index 8f88c3c..b88bccf 100644
--- a/doc/developer/branches.xml
+++ b/doc/developer/branches.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/developer/copyright.xml b/doc/developer/copyright.xml
index d718e5e..f89ef84 100644
--- a/doc/developer/copyright.xml
+++ b/doc/developer/copyright.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/developer/cycle.xml b/doc/developer/cycle.xml
index bb34db5..cca4422 100644
--- a/doc/developer/cycle.xml
+++ b/doc/developer/cycle.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/developer/main.xml b/doc/developer/main.xml
index c72ad38..25c56bf 100644
--- a/doc/developer/main.xml
+++ b/doc/developer/main.xml
@@ -2,7 +2,7 @@
 
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/developer/packaging.xml b/doc/developer/packaging.xml
index 2ecae8c..50d8e7b 100644
--- a/doc/developer/packaging.xml
+++ b/doc/developer/packaging.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/developer/preface.xml b/doc/developer/preface.xml
index da2964c..b61d7b8 100644
--- a/doc/developer/preface.xml
+++ b/doc/developer/preface.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/developer/sourcetree.xml b/doc/developer/sourcetree.xml
index 3c89189..305a134 100644
--- a/doc/developer/sourcetree.xml
+++ b/doc/developer/sourcetree.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/developer/testing.xml b/doc/developer/testing.xml
index ea01780..1287e19 100644
--- a/doc/developer/testing.xml
+++ b/doc/developer/testing.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/man/scons-time.1 b/doc/man/scons-time.1
index dda1c13..69db49a 100644
--- a/doc/man/scons-time.1
+++ b/doc/man/scons-time.1
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 .\"
 .\" Permission is hereby granted, free of charge, to any person obtaining
 .\" a copy of this software and associated documentation files (the
@@ -19,7 +19,7 @@
 .\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 .\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 .\"
-.\" doc/man/scons-time.1 5134 2010/08/16 23:02:40 bdeegan
+.\" doc/man/scons-time.1 5357 2011/09/09 21:31:03 bdeegan
 .\"
 .\" ES - Example Start - indents and turns off line fill
 .de ES
@@ -98,7 +98,7 @@
 [\fB--which=\fIWHICH\fR]
 [\fIARGUMENTS\fR]
 ..
-.TH SCONS-TIME 1 "August 2010"
+.TH SCONS-TIME 1 "September 2011"
 .SH NAME
 scons-time \- generate and display SCons timing information
 '\"==========================================================================
diff --git a/doc/man/scons.1 b/doc/man/scons.1
index 5d2b795..bd0d965 100644
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 .\"
 .\" Permission is hereby granted, free of charge, to any person obtaining
 .\" a copy of this software and associated documentation files (the
@@ -19,9 +19,9 @@
 .\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 .\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 .\"
-.\" doc/man/scons.1 5134 2010/08/16 23:02:40 bdeegan
+.\" doc/man/scons.1 5357 2011/09/09 21:31:03 bdeegan
 .\"
-.TH SCONS 1 "August 2010"
+.TH SCONS 1 "September 2011"
 .\" ES - Example Start - indents and turns off line fill
 .rm ES
 .de ES
@@ -100,17 +100,17 @@ file,
 .B scons
 looks for a directory named
 .I site_scons
-in the directory containing the
+in various system directories (see below) and the directory containing the
 .I SConstruct
-file; if it exists,
+file; for each of those dirs which exists,
 .I site_scons
-is added to sys.path,
+is prepended to sys.path,
 the file
 .IR site_scons/site_init.py ,
 is evaluated if it exists,
 and the directory
 .I site_scons/site_tools
-is added to the default toolpath if it exist.
+is prepended to the default toolpath if it exists.
 See the
 .I --no-site-dir
 and
@@ -601,6 +601,12 @@ have been compiled with optimization
 files).
 
 .TP
+--debug=duplicate
+Print a line for each unlink/relink (or copy) of a variant file from
+its source file.  Includes debugging info for unlinking stale variant
+files, as well as unlinking old targets before building them.
+
+.TP
 --debug=dtree
 A synonym for the newer
 .B --tree=derived
@@ -664,6 +670,18 @@ Re-run SCons under the control of the
 Python debugger.
 
 .TP
+--debug=prepare
+Print a line each time any target (internal or external)
+is prepared for building.
+.B scons
+prints this for each target it considers, even if that
+target is up to date (see also --debug=explain).
+This can help debug problems with targets that aren't being
+built; it shows whether
+.B scons
+is at least considering them or not.
+
+.TP
 --debug=presub
 Print the raw command line used to build each target
 before the construction environment variables are substituted.
@@ -1095,13 +1113,13 @@ any out-of-date target files, but do not execute the commands.
 .RI --no-site-dir
 Prevents the automatic addition of the standard
 .I site_scons
-dir to
+dirs to
 .IR sys.path .
 Also prevents loading the
 .I site_scons/site_init.py
-module if it exists, and prevents adding
+modules if they exist, and prevents adding their
 .I site_scons/site_tools
-to the toolpath.
+dirs to the toolpath.
 
 .\" .TP
 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
@@ -1182,7 +1200,7 @@ Ignored for compatibility with GNU
 .RI --site-dir= dir
 Uses the named dir as the site dir rather than the default
 .I site_scons
-dir.  This dir will get prepended to
+dirs.  This dir will get prepended to
 .IR sys.path ,
 the module
 .IR dir /site_init.py
@@ -1190,6 +1208,48 @@ will get loaded if it exists, and
 .IR dir /site_tools
 will get added to the default toolpath.
 
+The default set of
+.I site_scons
+dirs used when
+.I --site-dir
+is not specified depends on the system platform, as follows.  Note
+that the directories are examined in the order given, from most
+generic to most specific, so the last-executed site_init.py file is
+the most specific one (which gives it the chance to override
+everything else), and the dirs are prepended to the paths, again so
+the last dir examined comes first in the resulting path.
+
+.IP "Windows:"
+.nf
+    %ALLUSERSPROFILE/Application Data/scons/site_scons
+    %USERPROFILE%/Local Settings/Application Data/scons/site_scons
+    %APPDATA%/scons/site_scons
+    %HOME%/.scons/site_scons
+    ./site_scons
+.fi
+.IP "Mac OS X:"
+.nf
+    /Library/Application Support/SCons/site_scons
+    /opt/local/share/scons/site_scons (for MacPorts)
+    /sw/share/scons/site_scons (for Fink)
+    $HOME/Library/Application Support/SCons/site_scons
+    $HOME/.scons/site_scons
+    ./site_scons
+.fi
+.IP "Solaris:"
+.nf
+    /opt/sfw/scons/site_scons
+    /usr/share/scons/site_scons
+    $HOME/.scons/site_scons
+    ./site_scons
+.fi
+.IP "Linux, HPUX, and other Posix-like systems:"
+.nf
+    /usr/share/scons/site_scons
+    $HOME/.scons/site_scons
+    ./site_scons
+.fi
+
 .TP
 .RI --stack-size= KILOBYTES
 Set the size stack used to run threads to
@@ -2269,7 +2329,7 @@ Builders by adding them
 to the
 .B SourceFileScanner
 object.
-See the section "Scanner Objects,"
+See the section "Scanner Objects"
 below, for more information about
 defining your own Scanner objects
 and using the
@@ -2351,4049 +2411,34 @@ and global functions supported by
 include:
 
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])"
-.TP
-.IR env .Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])"
-Creates an Action object for
-the specified
-.IR action .
-See the section "Action Objects,"
-below, for a complete explanation of the arguments and behavior.
-
-Note that the
-.BR env.Action ()
-form of the invocation will expand
-construction variables in any argument strings,
-including the
-.I action
-argument, at the time it is called
-using the construction variables in the
-.I env
-construction environment through which
-.BR env.Action ()
-was called.
-The
-.BR Action ()
-form delays all variable expansion
-until the Action object is actually used.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI AddMethod( object, function ", [" name ])
-.TP
-.RI env.AddMethod( function ", [" name ])
-When called with the
-.BR AddMethod ()
-form,
-adds the specified
-.I function
-to the specified
-.I object
-as the specified method
-.IR name .
-When called with the
-.BR env.AddMethod ()
-form,
-adds the specified
-.I function
-to the construction environment
-.I env
-as the specified method
-.IR name .
-In both cases, if
-.I name
-is omitted or
-.BR None ,
-the name of the
-specified
-.I function
-itself is used for the method name.
-
-Examples:
-
-.ES
-# Note that the first argument to the function to
-# be attached as a method must be the object through
-# which the method will be called; the Python
-# convention is to call it 'self'.
-def my_method(self, arg):
-    print "my_method() got", arg
-
-# Use the global AddMethod() function to add a method
-# to the Environment class.  This
-AddMethod(Environment, my_method)
-env = Environment()
-env.my_method('arg')
-
-# Add the function as a method, using the function
-# name for the method call.
-env = Environment()
-env.AddMethod(my_method, 'other_method_name')
-env.other_method_name('another arg')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI AddOption( arguments )
-This function adds a new command-line option to be recognized.
-The specified
-.I arguments
-are the same as supported by the standard Python
-.BR optparse.add_option ()
-method (with a few additional capabilities noted below);
-see the documentation for
-.B optparse
-for a thorough discussion of its option-processing capabities.
-
-In addition to the arguments and values supported by the
-.B optparse.add_option ()
-method,
-the SCons
-.BR AddOption ()
-function allows you to set the
-.B nargs
-keyword value to
-.B '?'
-(a string with just the question mark)
-to indicate that the specified long option(s) take(s) an
-.I optional
-argument.
-When
-.B "nargs = '?'"
-is passed to the
-.BR AddOption ()
-function, the
-.B const
-keyword argument
-may be used to supply the "default"
-value that should be used when the
-option is specified on the command line
-without an explicit argument.
-
-If no
-.B default=
-keyword argument is supplied when calling
-.BR AddOption (),
-the option will have a default value of
-.BR None .
-
-Once a new command-line option has been added with
-.BR AddOption (),
-the option value may be accessed using
-.BR GetOption ()
-or
-.BR env.GetOption ().
-\" NOTE: in SCons 1.x or 2.0, user options will be settable, but not yet.
-\" Uncomment this when that works.  See tigris issue 2105.
-\" The value may also be set, using
-\" .BR SetOption ()
-\" or
-\" .BR env.SetOption (),
-\" if conditions in a
-\" .B SConscript
-\" require overriding any default value.
-\" Note, however, that a
-\" value specified on the command line will
-\" .I always
-\" override a value set by any SConscript file.
-
-Any specified
-.B help=
-strings for the new option(s)
-will be displayed by the
-.B -H
-or
-.B -h
-options
-(the latter only if no other help text is
-specified in the SConscript files).
-The help text for the local options specified by
-.BR AddOption ()
-will appear below the SCons options themselves,
-under a separate
-.B "Local Options"
-heading.
-The options will appear in the help text
-in the order in which the
-.BR AddOption ()
-calls occur.
-
-Example:
-
-.ES
-AddOption('--prefix',
-          dest='prefix',
-          nargs=1, type='string',
-          action='store',
-          metavar='DIR',
-          help='installation prefix')
-env = Environment(PREFIX = GetOption('prefix'))
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI AddPostAction( target ", " action )
-.TP
-.RI env.AddPostAction( target ", " action )
-Arranges for the specified
-.I action
-to be performed
-after the specified
-.I target
-has been built.
-The specified action(s) may be
-an Action object, or anything that
-can be converted into an Action object
-(see below).
-
-When multiple targets are supplied,
-the action may be called multiple times,
-once after each action that generates
-one or more targets in the list.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI AddPreAction( target ", " action )
-.TP
-.RI env.AddPreAction( target ", " action )
-Arranges for the specified
-.I action
-to be performed
-before the specified
-.I target
-is built.
-The specified action(s) may be
-an Action object, or anything that
-can be converted into an Action object
-(see below).
-
-When multiple targets are specified,
-the action(s) may be called multiple times,
-once before each action that generates
-one or more targets in the list.
-
-Note that if any of the targets are built in multiple steps,
-the action will be invoked just
-before the "final" action that specifically
-generates the specified target(s).
-For example, when building an executable program
-from a specified source
-.B .c
-file via an intermediate object file:
-
-.ES
-foo = Program('foo.c')
-AddPreAction(foo, 'pre_action')
-.EE
-
-The specified
-.B pre_action
-would be executed before
-.B scons
-calls the link command that actually
-generates the executable program binary
-.BR foo ,
-not before compiling the
-.B foo.c
-file into an object file.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Alias( alias ", [" targets ", [" action ]])
-.TP
-.RI env.Alias( alias ", [" targets ", [" action ]])
-Creates one or more phony targets that
-expand to one or more other targets.
-An optional
-.I action
-(command)
-or list of actions
-can be specified that will be executed
-whenever the any of the alias targets are out-of-date.
-Returns the Node object representing the alias,
-which exists outside of any file system.
-This Node object, or the alias name,
-may be used as a dependency of any other target,
-including another alias.
-.B Alias
-can be called multiple times for the same
-alias to add additional targets to the alias,
-or additional actions to the list for this alias.
-
-Examples:
-
-.ES
-Alias('install')
-Alias('install', '/usr/bin')
-Alias(['install', 'install-lib'], '/usr/local/lib')
-
-env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
-env.Alias('install', ['/usr/local/man'])
-
-env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI AllowSubstExceptions([ exception ", ...])"
-Specifies the exceptions that will be allowed
-when expanding construction variables.
-By default,
-any construction variable expansions that generate a
-.B NameError
-or
-.BR IndexError
-exception will expand to a
-.B ''
-(a null string) and not cause scons to fail.
-All exceptions not in the specified list
-will generate an error message
-and terminate processing.
-
-If
-.B AllowSubstExceptions
-is called multiple times,
-each call completely overwrites the previous list
-of allowed exceptions.
-
-Example:
-
-.ES
-# Requires that all construction variable names exist.
-# (You may wish to do this if you want to enforce strictly
-# that all construction variables must be defined before use.)
-AllowSubstExceptions()
-
-# Also allow a string containing a zero-division expansion
-# like '${1 / 0}' to evalute to ''.
-AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI AlwaysBuild( target ", ...)"
-.TP
-.RI env.AlwaysBuild( target ", ...)"
-Marks each given
-.I target
-so that it is always assumed to be out of date,
-and will always be rebuilt if needed.
-Note, however, that
-.BR AlwaysBuild ()
-does not add its target(s) to the default target list,
-so the targets will only be built
-if they are specified on the command line,
-or are a dependent of a target specified on the command line--but
-they will
-.I always
-be built if so specified.
-Multiple targets can be passed in to a single call to
-.BR AlwaysBuild ().
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.Append( key = val ", [...])"
-Appends the specified keyword arguments
-to the end of construction variables in the environment.
-If the Environment does not have
-the specified construction variable,
-it is simply added to the environment.
-If the values of the construction variable
-and the keyword argument are the same type,
-then the two values will be simply added together.
-Otherwise, the construction variable
-and the value of the keyword argument
-are both coerced to lists,
-and the lists are added together.
-(See also the Prepend method, below.)
-
-Example:
-
-.ES
-env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
-This appends new path elements to the given path in the
-specified external environment
-.RB ( ENV
-by default).
-This will only add
-any particular path once (leaving the last one it encounters and
-ignoring the rest, to preserve path order),
-and to help assure this,
-will normalize all paths (using
-.B os.path.normpath
-and
-.BR os.path.normcase ).
-This can also handle the
-case where the given old path variable is a list instead of a
-string, in which case a list will be returned instead of a string.
-
-If 
-.I delete_existing
-is 0, then adding a path that already exists
-will not move it to the end; it will stay where it is in the list.
-
-Example:
-
-.ES
-print 'before:',env['ENV']['INCLUDE']
-include_path = '/foo/bar:/foo'
-env.AppendENVPath('INCLUDE', include_path)
-print 'after:',env['ENV']['INCLUDE']
-
-yields:
-before: /foo:/biz
-after: /biz:/foo/bar:/foo
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.AppendUnique( key = val ", [...], delete_existing=0)"
-Appends the specified keyword arguments
-to the end of construction variables in the environment.
-If the Environment does not have
-the specified construction variable,
-it is simply added to the environment.
-If the construction variable being appended to is a list,
-then any value(s) that already exist in the
-construction variable will
-.I not
-be added again to the list.
-However, if delete_existing is 1, 
-existing matching values are removed first, so
-existing values in the arg list move to the end of the list.
-
-Example:
-
-.ES
-env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-env.BitKeeper()
-A factory function that
-returns a Builder object
-to be used to fetch source files
-using BitKeeper.
-The returned Builder
-is intended to be passed to the
-.B SourceCode
-function.
-
-This function is deprecated.  For details, see the entry for the
-.B SourceCode
-function.
-
-Example:
-
-.ES
-env.SourceCode('.', env.BitKeeper())
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
-.TP
-.RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
-Deprecated synonyms for
-.BR VariantDir ()
-and
-.BR env.VariantDir ().
-The
-.I build_dir
-argument becomes the
-.I variant_dir
-argument of
-.BR VariantDir ()
-or
-.BR env.VariantDir ().
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Builder( action ", [" arguments ])
-.TP
-.RI env.Builder( action ", [" arguments ])
-Creates a Builder object for
-the specified
-.IR action .
-See the section "Builder Objects,"
-below, for a complete explanation of the arguments and behavior.
-
-Note that the
-.BR env.Builder ()
-form of the invocation will expand
-construction variables in any arguments strings,
-including the
-.I action
-argument,
-at the time it is called
-using the construction variables in the
-.B env
-construction environment through which
-.BR env.Builder ()
-was called.
-The
-.BR Builder ()
-form delays all variable expansion
-until after the Builder object is actually called.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI CacheDir( cache_dir )
-.TP
-.RI env.CacheDir( cache_dir )
-Specifies that
-.B scons
-will maintain a cache of derived files in
-.I cache_dir .
-The derived files in the cache will be shared
-among all the builds using the same
-.BR CacheDir ()
-call.
-Specifying a
-.I cache_dir
-of
-.B None
-disables derived file caching.
-
-Calling
-.BR env.CacheDir ()
-will only affect targets built
-through the specified construction environment.
-Calling
-.BR CacheDir ()
-sets a global default
-that will be used by all targets built
-through construction environments
-that do
-.I not
-have an
-.BR env.CacheDir ()
-specified.
-
-When a
-.BR CacheDir ()
-is being used and
-.B scons
-finds a derived file that needs to be rebuilt,
-it will first look in the cache to see if a
-derived file has already been built
-from identical input files and an identical build action
-(as incorporated into the MD5 build signature).
-If so,
-.B scons
-will retrieve the file from the cache.
-If the derived file is not present in the cache,
-.B scons
-will rebuild it and
-then place a copy of the built file in the cache
-(identified by its MD5 build signature),
-so that it may be retrieved by other
-builds that need to build the same derived file
-from identical inputs.
-
-Use of a specified
-.BR CacheDir()
-may be disabled for any invocation
-by using the
-.B --cache-disable
-option.
-
-If the
-.B --cache-force
-option is used,
-.B scons
-will place a copy of
-.I all
-derived files in the cache,
-even if they already existed
-and were not built by this invocation.
-This is useful to populate a cache
-the first time
-.BR CacheDir ()
-is added to a build,
-or after using the
-.B --cache-disable
-option.
-
-When using
-.BR CacheDir (),
-.B scons
-will report,
-"Retrieved `file' from cache,"
-unless the
-.B --cache-show
-option is being used.
-When the
-.B --cache-show
-option is used,
-.B scons
-will print the action that
-.I would
-have been used to build the file,
-without any indication that
-the file was actually retrieved from the cache.
-This is useful to generate build logs
-that are equivalent regardless of whether
-a given derived file has been built in-place
-or retrieved from the cache.
-
-The
-.BR NoCache ()
-method can be used to disable caching of specific files.  This can be
-useful if inputs and/or outputs of some tool are impossible to
-predict or prohibitively large.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Clean( targets ", " files_or_dirs )
-.TP
-.RI env.Clean( targets ", " files_or_dirs )
-This specifies a list of files or directories which should be removed
-whenever the targets are specified with the
-.B -c
-command line option.
-The specified targets may be a list
-or an individual target.
-Multiple calls to
-.BR Clean ()
-are legal,
-and create new targets or add files and directories to the
-clean list for the specified targets.
-
-Multiple files or directories should be specified
-either as separate arguments to the
-.BR Clean ()
-method, or as a list.
-.BR Clean ()
-will also accept the return value of any of the construction environment
-Builder methods.
-Examples:
-
-The related
-.BR NoClean ()
-function overrides calling
-.BR Clean ()
-for the same target,
-and any targets passed to both functions will
-.I not
-be removed by the
-.B -c
-option.
-
-Examples:
-
-.ES
-Clean('foo', ['bar', 'baz'])
-Clean('dist', env.Program('hello', 'hello.c'))
-Clean(['foo', 'bar'], 'something_else_to_clean')
-.EE
-
-In this example,
-installing the project creates a subdirectory for the documentation.
-This statement causes the subdirectory to be removed
-if the project is deinstalled.
-.ES
-Clean(docdir, os.path.join(docdir, projectname))
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Command( target ", " source ", " action ", [" key = val ", ...])"
-.TP
-.RI env.Command( target ", " source ", " action ", [" key = val ", ...])"
-Executes a specific action
-(or list of actions)
-to build a target file or files.
-This is more convenient
-than defining a separate Builder object
-for a single special-case build.
-
-As a special case, the
-.B source_scanner
-keyword argument can
-be used to specify
-a Scanner object
-that will be used to scan the sources.
-(The global
-.B DirScanner
-object can be used
-if any of the sources will be directories
-that must be scanned on-disk for
-changes to files that aren't
-already specified in other Builder of function calls.)
-
-Any other keyword arguments specified override any
-same-named existing construction variables.
-
-An action can be an external command,
-specified as a string,
-or a callable Python object;
-see "Action Objects," below,
-for more complete information.
-Also note that a string specifying an external command
-may be preceded by an
-.B @
-(at-sign)
-to suppress printing the command in question,
-or by a
-.B \-
-(hyphen)
-to ignore the exit status of the external command.
-
-Examples:
-
-.ES
-env.Command('foo.out', 'foo.in',
-            "$FOO_BUILD < $SOURCES > $TARGET")
-
-env.Command('bar.out', 'bar.in',
-            ["rm -f $TARGET",
-             "$BAR_BUILD < $SOURCES > $TARGET"],
-            ENV = {'PATH' : '/usr/local/bin/'})
-
-def rename(env, target, source):
-    import os
-    os.rename('.tmp', str(target[0]))
-
-env.Command('baz.out', 'baz.in',
-            ["$BAZ_BUILD < $SOURCES > .tmp",
-	     rename ])
-.EE
-
-.IP
-Note that the
-.BR Command ()
-function will usually assume, by default,
-that the specified targets and/or sources are Files,
-if no other part of the configuration
-identifies what type of entry it is.
-If necessary, you can explicitly specify
-that targets or source nodes should
-be treated as directoriese
-by using the
-.BR Dir ()
-or
-.BR env.Dir ()
-functions.
-
-Examples:
-
-.ES
-env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
-
-env['DISTDIR'] = 'destination/directory'
-env.Command(env.Dir('$DISTDIR')), None, make_distdir)
-.EE
-
-.IP
-(Also note that SCons will usually
-automatically create any directory necessary to hold a target file,
-so you normally don't need to create directories by hand.)
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
-.TP
-.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
-Creates a Configure object for integrated
-functionality similar to GNU autoconf.
-See the section "Configure Contexts,"
-below, for a complete explanation of the arguments and behavior.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.Clone([ key = val ", ...])"
-Return a separate copy of a construction environment.
-If there are any keyword arguments specified,
-they are added to the returned copy,
-overwriting any existing values
-for the keywords.
-
-Example:
-
-.ES
-env2 = env.Clone()
-env3 = env.Clone(CCFLAGS = '-g')
-.EE
-.IP
-Additionally, a list of tools and a toolpath may be specified, as in
-the Environment constructor:
-
-.ES
-def MyTool(env): env['FOO'] = 'bar'
-env4 = env.Clone(tools = ['msvc', MyTool])
-.EE
-
-The
-.I parse_flags
-keyword argument is also recognized:
-
-.ES
-# create an environment for compiling programs that use wxWidgets
-wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.Copy([ key = val ", ...])"
-A now-deprecated synonym for
-.BR env.Clone() .
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.CVS( repository ", " module )
-A factory function that
-returns a Builder object
-to be used to fetch source files
-from the specified
-CVS
-.IR repository .
-The returned Builder
-is intended to be passed to the
-.B SourceCode
-function.
-
-The optional specified
-.I module
-will be added to the beginning
-of all repository path names;
-this can be used, in essence,
-to strip initial directory names
-from the repository path names,
-so that you only have to
-replicate part of the repository
-directory hierarchy in your
-local build directory.
-
-This function is deprecated.  For details, see the entry for the
-.B SourceCode
-function.
-
-Examples:
-
-.ES
-# Will fetch foo/bar/src.c
-# from /usr/local/CVSROOT/foo/bar/src.c.
-env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
-
-# Will fetch bar/src.c
-# from /usr/local/CVSROOT/foo/bar/src.c.
-env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
-
-# Will fetch src.c
-# from /usr/local/CVSROOT/foo/bar/src.c.
-env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Decider( function )
-.TP
-.RI env.Decider( function )
-Specifies that all up-to-date decisions for
-targets built through this construction environment
-will be handled by the specified
-.IR function .
-The
-.I function
-can be one of the following strings
-that specify the type of decision function
-to be performed:
-
-.RS 10
-.HP 6
-.B timestamp-newer
-Specifies that a target shall be considered out of date and rebuilt
-if the dependency's timestamp is newer than the target file's timestamp.
-This is the behavior of the classic Make utility,
-and
-.B make
-can be used a synonym for
-.BR timestamp-newer .
-
-.HP 6
-.B timestamp-match
-Specifies that a target shall be considered out of date and rebuilt
-if the dependency's timestamp is different than the
-timestamp recorded the last time the target was built.
-This provides behavior very similar to the classic Make utility
-(in particular, files are not opened up so that their
-contents can be checksummed)
-except that the target will also be rebuilt if a
-dependency file has been restored to a version with an
-.I earlier
-timestamp, such as can happen when restoring files from backup archives.
-
-.HP 6
-.B MD5
-Specifies that a target shall be considered out of date and rebuilt
-if the dependency's content has changed sine the last time
-the target was built,
-as determined be performing an MD5 checksum
-on the dependency's contents
-and comparing it to the checksum recorded the
-last time the target was built.
-.B content
-can be used as a synonym for
-.BR MD5 .
-
-.HP 6
-.B MD5-timestamp
-Specifies that a target shall be considered out of date and rebuilt
-if the dependency's content has changed sine the last time
-the target was built,
-except that dependencies with a timestamp that matches
-the last time the target was rebuilt will be
-assumed to be up-to-date and
-.I not
-rebuilt.
-This provides behavior very similar
-to the
-.B MD5
-behavior of always checksumming file contents,
-with an optimization of not checking
-the contents of files whose timestamps haven't changed.
-The drawback is that SCons will
-.I not
-detect if a file's content has changed
-but its timestamp is the same,
-as might happen in an automated script
-that runs a build,
-updates a file,
-and runs the build again,
-all within a single second.
-.RE
-
-.IP
-Examples:
-
-.ES
-# Use exact timestamp matches by default.
-Decider('timestamp-match')
-
-# Use MD5 content signatures for any targets built
-# with the attached construction environment.
-env.Decider('content')
-.EE
-
-.IP
-In addition to the above already-available functions,
-the
-.I function
-argument may be an actual Python function
-that takes the following three arguments:
-
-.RS 10
-.IP dependency
-The Node (file) which
-should cause the
-.I target
-to be rebuilt
-if it has "changed" since the last tme
-.I target was built.
-
-.IP target
-The Node (file) being built.
-In the normal case,
-this is what should get rebuilt
-if the
-.I dependency
-has "changed."
-
-.IP prev_ni
-Stored information about the state of the
-.I dependency
-the last time the
-.I target
-was built.
-This can be consulted to match various
-file characteristics
-such as the timestamp,
-size, or content signature.
-.RE
-
-.IP
-The
-.I function
-should return a
-.B True
-(non-zero)
-value if the
-.I dependency
-has "changed" since the last time
-the
-.I target
-was built
-(indicating that the target
-.I should
-be rebuilt),
-and
-.B False
-(zero)
-otherwise
-(indicating that the target should
-.I not
-be rebuilt).
-Note that the decision can be made
-using whatever criteria are appopriate.
-Ignoring some or all of the function arguments
-is perfectly normal.
-
-Example:
-
-.ES
-def my_decider(dependency, target, prev_ni):
-    return not os.path.exists(str(target))
-
-env.Decider(my_decider)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Default( targets )
-.TP
-.RI env.Default( targets )
-This specifies a list of default targets,
-which will be built by
-.B scons
-if no explicit targets are given on the command line.
-Multiple calls to
-.BR Default ()
-are legal,
-and add to the list of default targets.
-
-Multiple targets should be specified as
-separate arguments to the
-.BR Default ()
-method, or as a list.
-.BR Default ()
-will also accept the Node returned by any
-of a construction environment's
-builder methods.
-
-Examples:
-
-.ES
-Default('foo', 'bar', 'baz')
-env.Default(['a', 'b', 'c'])
-hello = env.Program('hello', 'hello.c')
-env.Default(hello)
-.EE
-.IP
-An argument to
-.BR Default ()
-of
-.B None
-will clear all default targets.
-Later calls to
-.BR Default ()
-will add to the (now empty) default-target list
-like normal.
-
-The current list of targets added using the
-.BR Default ()
-function or method is available in the
-.B DEFAULT_TARGETS
-list;
-see below.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI DefaultEnvironment([ args ])
-Creates and returns a default construction environment object.
-This construction environment is used internally by SCons
-in order to execute many of the global functions in this list,
-and to fetch source files transparently
-from source code management systems.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Depends( target ", " dependency )
-.TP
-.RI env.Depends( target ", " dependency )
-Specifies an explicit dependency;
-the
-.I target
-will be rebuilt
-whenever the
-.I dependency
-has changed.
-Both the specified
-.I target
-and
-.I dependency
-can be a string
-(usually the path name of a file or directory)
-or Node objects,
-or a list of strings or Node objects
-(such as returned by a Builder call).
-This should only be necessary
-for cases where the dependency
-is not caught by a Scanner
-for the file.
-
-Example:
-
-.ES
-env.Depends('foo', 'other-input-file-for-foo')
-
-mylib = env.Library('mylib.c')
-installed_lib = env.Install('lib', mylib)
-bar = env.Program('bar.c')
-
-# Arrange for the library to be copied into the installation
-# directory before trying to build the "bar" program.
-# (Note that this is for example only.  A "real" library
-# dependency would normally be configured through the $LIBS
-# and $LIBPATH variables, not using an env.Depends() call.)
-
-env.Depends(bar, installed_lib)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.Dictionary([ vars ])
-Returns a dictionary object
-containing copies of all of the
-construction variables in the environment.
-If there are any variable names specified,
-only the specified construction
-variables are returned in the dictionary.
-
-Example:
-
-.ES
-dict = env.Dictionary()
-cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Dir( name ", [" directory ])
-.TP
-.RI env.Dir( name ", [" directory ])
-This returns a Directory Node,
-an object that represents the specified directory
-.IR name .
-.I name
-can be a relative or absolute path.
-.I directory
-is an optional directory that will be used as the parent directory.
-If no
-.I directory
-is specified, the current script's directory is used as the parent.
-
-If
-.I name
-is a list, SCons returns a list of Dir nodes.
-Construction variables are expanded in
-.IR name .
-
-Directory Nodes can be used anywhere you
-would supply a string as a directory name
-to a Builder method or function.
-Directory Nodes have attributes and methods
-that are useful in many situations;
-see "File and Directory Nodes," below.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.Dump([ key ])
-Returns a pretty printable representation of the environment.
-.IR key ,
-if not
-.IR None ,
-should be a string containing the name of the variable of interest.
-
-This SConstruct:
-.ES
-env=Environment()
-print env.Dump('CCCOM')
-.EE
-.IP
-will print:
-.ES
-\&'$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES'
-.EE
-
-.ES
-env=Environment()
-print env.Dump()
-.EE
-.IP
-will print:
-.ES
-{ 'AR': 'ar',
-  'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
-  'ARFLAGS': ['r'],
-  'AS': 'as',
-  'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
-  'ASFLAGS': [],
-  ...
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI EnsurePythonVersion( major ", " minor )
-.TP
-.RI env.EnsurePythonVersion( major ", " minor )
-Ensure that the Python version is at least
-.IR major . minor .
-This function will
-print out an error message and exit SCons with a non-zero exit code if the
-actual Python version is not late enough.
-
-Example:
-
-.ES
-EnsurePythonVersion(2,2)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI EnsureSConsVersion( major ", " minor ", [" revision ])
-.TP
-.RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
-Ensure that the SCons version is at least
-.IR major.minor ,
-or
-.IR major.minor.revision .
-if
-.I revision
-is specified.
-This function will
-print out an error message and exit SCons with a non-zero exit code if the
-actual SCons version is not late enough.
-
-Examples:
-
-.ES
-EnsureSConsVersion(0,14)
-
-EnsureSConsVersion(0,96,90)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Environment([ key = value ", ...])"
-.TP
-.RI env.Environment([ key = value ", ...])"
-Return a new construction environment
-initialized with the specified
-.IR key = value
-pairs.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Execute( action ", [" strfunction ", " varlist ])
-.TP
-.RI env.Execute( action ", [" strfunction ", " varlist ])
-Executes an Action object.
-The specified
-.IR action
-may be an Action object
-(see the section "Action Objects,"
-below, for a complete explanation of the arguments and behavior),
-or it may be a command-line string,
-list of commands,
-or executable Python function,
-each of which will be converted
-into an Action object
-and then executed.
-The exit value of the command
-or return value of the Python function
-will be returned.
-
-Note that
-.B scons
-will print an error message if the executed
-.I action
-fails--that is,
-exits with or returns a non-zero value.
-.B scons
-will
-.I not ,
-however,
-automatically terminate the build
-if the specified
-.I action
-fails.
-If you want the build to stop in response to a failed
-.BR Execute ()
-call,
-you must explicitly check for a non-zero return value:
-
-.ES
-Execute(Copy('file.out', 'file.in'))
-
-if Execute("mkdir sub/dir/ectory"):
-    # The mkdir failed, don't try to build.
-    Exit(1)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Exit([ value ])
-.TP
-.RI env.Exit([ value ])
-This tells
-.B scons
-to exit immediately
-with the specified
-.IR value .
-A default exit value of
-.B 0
-(zero)
-is used if no value is specified.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Export( vars )
-.TP
-.RI env.Export( vars )
-This tells
-.B scons
-to export a list of variables from the current
-SConscript file to all other SConscript files.
-The exported variables are kept in a global collection,
-so subsequent calls to
-.BR Export ()
-will over-write previous exports that have the same name.
-Multiple variable names can be passed to
-.BR Export ()
-as separate arguments or as a list.
-Keyword arguments can be used to provide names and their values.
-A dictionary can be used to map variables to a different name when exported.
-Both local variables and global variables can be exported.
-
-Examples:
-
-.ES
-env = Environment()
-# Make env available for all SConscript files to Import().
-Export("env")
-
-package = 'my_name'
-# Make env and package available for all SConscript files:.
-Export("env", "package")
-
-# Make env and package available for all SConscript files:
-Export(["env", "package"])
-
-# Make env available using the name debug:
-Export(debug = env)
-
-# Make env available using the name debug:
-Export({"debug":env})
-.EE
-
-.IP
-Note that the
-.BR SConscript ()
-function supports an
-.I exports
-argument that makes it easier to to export a variable or
-set of variables to a single SConscript file.
-See the description of the
-.BR SConscript ()
-function, below.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI File( name ", [" directory ])
-.TP
-.RI env.File( name ", [" directory ])
-This returns a
-File Node,
-an object that represents the specified file
-.IR name .
-.I name
-can be a relative or absolute path.
-.I directory
-is an optional directory that will be used as the parent directory.
-
-If
-.I name
-is a list, SCons returns a list of File nodes.
-Construction variables are expanded in
-.IR name .
-
-File Nodes can be used anywhere you
-would supply a string as a file name
-to a Builder method or function.
-File Nodes have attributes and methods
-that are useful in many situations;
-see "File and Directory Nodes," below.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI FindFile( file ", " dirs )
-.TP
-.RI env.FindFile( file ", " dirs )
-Search for
-.I file
-in the path specified by
-.IR dirs .
-.I dirs
-may be a list of directory names or a single directory name.
-In addition to searching for files that exist in the filesystem,
-this function also searches for derived files
-that have not yet been built.
-
-Example:
-
-.ES
-foo = env.FindFile('foo', ['dir1', 'dir2'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI FindInstalledFiles( )
-.TP
-.RI env.FindInstalledFiles( )
-Returns the list of targets set up by the
-.B Install()
-or
-.B InstallAs()
-builders.
-
-This function serves as a convenient method to select the contents of
-a binary package.
-
-Example:
-
-.ES
-Install( '/bin', [ 'executable_a', 'executable_b' ] )
-
-# will return the file node list
-# [ '/bin/executable_a', '/bin/executable_b' ]
-FindInstalledFiles()
-
-Install( '/lib', [ 'some_library' ] )
-
-# will return the file node list
-# [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
-FindInstalledFiles()
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI FindSourceFiles( node = '"."' )
-.TP
-.RI env.FindSourceFiles( node = '"."' )
-
-Returns the list of nodes which serve as the source of the built files.
-It does so by inspecting the dependency tree starting at the optional
-argument
-.B node
-which defaults to the '"."'-node. It will then return all leaves of
-.B node.
-These are all children which have no further children.
-
-This function is a convenient method to select the contents of a Source
-Package.
-
-Example:
-
-.ES
-Program( 'src/main_a.c' )
-Program( 'src/main_b.c' )
-Program( 'main_c.c' )
-
-# returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
-FindSourceFiles()
-
-# returns ['src/main_b.c', 'src/main_a.c' ]
-FindSourceFiles( 'src' )
-.EE
-
-.IP
-As you can see build support files (SConstruct in the above example)
-will also be returned by this function.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI FindPathDirs( variable )
-Returns a function
-(actually a callable Python object)
-intended to be used as the
-.B path_function
-of a Scanner object.
-The returned object will look up the specified
-.I variable
-in a construction environment
-and treat the construction variable's value as a list of
-directory paths that should be searched
-(like
-.BR CPPPATH ,
-.BR LIBPATH ,
-etc.).
-
-Note that use of
-.BR FindPathDirs ()
-is generally preferable to
-writing your own
-.B path_function
-for the following reasons:
-1) The returned list will contain all appropriate directories
-found in source trees
-(when
-.BR VariantDir ()
-is used)
-or in code repositories
-(when
-.BR Repository ()
-or the
-.B \-Y
-option are used).
-2) scons will identify expansions of
-.I variable
-that evaluate to the same list of directories as,
-in fact, the same list,
-and avoid re-scanning the directories for files,
-when possible.
-
-Example:
-
-.ES
-def my_scan(node, env, path, arg):
-    # Code to scan file contents goes here...
-    return include_files
-
-scanner = Scanner(name = 'myscanner',
-                  function = my_scan,
-                  path_function = FindPathDirs('MYPATH'))
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Flatten( sequence )
-.TP
-.RI env.Flatten( sequence )
-Takes a sequence (that is, a Python list or tuple)
-that may contain nested sequences
-and returns a flattened list containing
-all of the individual elements in any sequence.
-This can be helpful for collecting
-the lists returned by calls to Builders;
-other Builders will automatically
-flatten lists specified as input,
-but direct Python manipulation of
-these lists does not.
-
-Examples:
-
-.ES
-foo = Object('foo.c')
-bar = Object('bar.c')
-
-# Because `foo' and `bar' are lists returned by the Object() Builder,
-# `objects' will be a list containing nested lists:
-objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
-
-# Passing such a list to another Builder is all right because
-# the Builder will flatten the list automatically:
-Program(source = objects)
-
-# If you need to manipulate the list directly using Python, you need to
-# call Flatten() yourself, or otherwise handle nested lists:
-for object in Flatten(objects):
-    print str(object)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI GetBuildFailures()
-Returns a list of exceptions for the
-actions that failed while
-attempting to build targets.
-Each element in the returned list is a
-.B BuildError
-object
-with the following attributes
-that record various aspects
-of the build failure:
-
-.B .node
-The node that was being built
-when the build failure occurred.
-
-.B .status
-The numeric exit status
-returned by the command or Python function
-that failed when trying to build the
-specified Node.
-
-.B .errstr
-The SCons error string
-describing the build failure.
-(This is often a generic
-message like "Error 2"
-to indicate that an executed
-command exited with a status of 2.)
-
-.B .filename
-The name of the file or
-directory that actually caused the failure.
-This may be different from the
-.B .node
-attribute.
-For example,
-if an attempt to build a target named
-.B sub/dir/target
-fails because the
-.B sub/dir
-directory could not be created,
-then the
-.B .node
-attribute will be
-.B sub/dir/target
-but the
-.B .filename
-attribute will be
-.BR sub/dir .
-
-.B .executor
-The SCons Executor object
-for the target Node
-being built.
-This can be used to retrieve
-the construction environment used
-for the failed action.
-
-.B .action
-The actual SCons Action object that failed.
-This will be one specific action
-out of the possible list of
-actions that would have been
-executed to build the target.
-
-.B .command
-The actual expanded command that was executed and failed,
-after expansion of
-.BR $TARGET ,
-.BR $SOURCE ,
-and other construction variables.
-
-Note that the
-.BR GetBuildFailures ()
-function
-will always return an empty list
-until any build failure has occurred,
-which means that
-.BR GetBuildFailures ()
-will always return an empty list
-while the
-.B SConscript
-files are being read.
-Its primary intended use is
-for functions that will be
-executed before SCons exits
-by passing them to the
-standard Python
-.BR atexit.register ()
-function.
-Example:
-
-.ES
-import atexit
-
-def print_build_failures():
-    from SCons.Script import GetBuildFailures
-    for bf in GetBuildFailures():
-        print "%s failed: %s" % (bf.node, bf.errstr)
-
-atexit.register(print_build_failures)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI GetBuildPath( file ", [" ... ])
-.TP
-.RI env.GetBuildPath( file ", [" ... ])
-Returns the
-.B scons
-path name (or names) for the specified
-.I file
-(or files).
-The specified
-.I file
-or files
-may be
-.B scons
-Nodes or strings representing path names.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI GetLaunchDir()
-.TP
-.RI env.GetLaunchDir()
-Returns the absolute path name of the directory from which
-.B scons
-was initially invoked.
-This can be useful when using the
-.BR \-u ,
-.BR \-U
-or
-.BR \-D
-options, which internally
-change to the directory in which the
-.B SConstruct
-file is found.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI GetOption( name )
-.TP
-.RI env.GetOption( name )
-This function provides a way to query the value of
-SCons options set on scons command line
-(or set using the
-.IR SetOption ()
-function).
-The options supported are:
-
-.RS 10
-.TP 6
-.B cache_debug
-which corresponds to --cache-debug;
-.TP 6
-.B cache_disable
-which corresponds to --cache-disable;
-.TP 6
-.B cache_force
-which corresponds to --cache-force;
-.TP 6
-.B cache_show
-which corresponds to --cache-show;
-.TP 6
-.B clean
-which corresponds to -c, --clean and --remove;
-.TP 6
-.B config
-which corresponds to --config;
-.TP 6
-.B directory
-which corresponds to -C and --directory;
-.TP 6
-.B diskcheck
-which corresponds to --diskcheck
-.TP 6
-.B duplicate
-which corresponds to --duplicate;
-.TP 6
-.B file
-which corresponds to -f, --file, --makefile and --sconstruct;
-.TP 6
-.B help
-which corresponds to -h and --help;
-.TP 6
-.B ignore_errors
-which corresponds to --ignore-errors;
-.TP 6
-.B implicit_cache
-which corresponds to --implicit-cache;
-.TP 6
-.B implicit_deps_changed
-which corresponds to --implicit-deps-changed;
-.TP 6
-.B implicit_deps_unchanged
-which corresponds to --implicit-deps-unchanged;
-.TP 6
-.B interactive
-which corresponds to --interact and --interactive;
-.TP 6
-.B keep_going
-which corresponds to -k and --keep-going;
-.TP 6
-.B max_drift
-which corresponds to --max-drift;
-.TP 6
-.B no_exec
-which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
-.TP 6
-.B no_site_dir
-which corresponds to --no-site-dir;
-.TP 6
-.B num_jobs
-which corresponds to -j and --jobs;
-.TP 6
-.B profile_file
-which corresponds to --profile;
-.TP 6
-.B question
-which corresponds to -q and --question;
-.TP 6
-.B random
-which corresponds to --random;
-.TP 6
-.B repository
-which corresponds to -Y, --repository and --srcdir;
-.TP 6
-.B silent
-which corresponds to -s, --silent and --quiet;
-.TP 6
-.B site_dir
-which corresponds to --site-dir;
-.TP 6
-.B stack_size
-which corresponds to --stack-size;
-.TP 6
-.B taskmastertrace_file
-which corresponds to --taskmastertrace; and
-.TP 6
-.B warn
-which corresponds to --warn and --warning.
-.RE
-
-.IP
-See the documentation for the
-corresponding command line object for information about each specific
-option.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Glob( pattern ", [" ondisk ", " source ", " strings ])
-.TP
-.RI env.Glob( pattern ", [" ondisk ", " source ", " strings ])
-Returns Nodes (or strings) that match the specified
-.IR pattern ,
-relative to the directory of the current
-.B SConscript
-file.
-The
-.BR env.Glob ()
-form performs string substition on
-.I pattern
-and returns whatever matches
-the resulting expanded pattern.
-
-The specified
-.I pattern
-uses Unix shell style metacharacters for matching:
-
-.ES
-  *       matches everything
-  ?       matches any single character
-  [seq]   matches any character in seq
-  [!seq]  matches any char not in seq
-.EE
-
-.IP
-If the first character of a filename is a dot,
-it must be matched explicitly.
-Character matches do
-.I not
-span directory separators.
-
-The
-.BR Glob ()
-knows about
-repositories
-(see the
-.BR Repository ()
-function)
-and source directories
-(see the
-.BR VariantDir ()
-function)
-and
-returns a Node (or string, if so configured)
-in the local (SConscript) directory
-if matching Node is found
-anywhere in a corresponding
-repository or source directory.
-
-The
-.B ondisk
-argument may be set to
-.B False
-(or any other non-true value)
-to disable the search for matches on disk,
-thereby only returning matches among
-already-configured File or Dir Nodes.
-The default behavior is to
-return corresponding Nodes
-for any on-disk matches found.
-
-The
-.B source
-argument may be set to
-.B True
-(or any equivalent value)
-to specify that,
-when the local directory is a
-.BR VariantDir (),
-the returned Nodes should be from the
-corresponding source directory,
-not the local directory.
-
-The
-.B strings
-argument may be set to
-.B True
-(or any equivalent value)
-to have the
-.BR Glob ()
-function return strings, not Nodes,
-that represent the matched files or directories.
-The returned strings will be relative to
-the local (SConscript) directory.
-(Note that This may make it easier to perform
-arbitrary manipulation of file names,
-but if the returned strings are
-passed to a different
-.B SConscript
-file,
-any Node translation will be relative
-to the other
-.B SConscript
-directory,
-not the original
-.B SConscript
-directory.)
-
-Examples:
-
-.ES
-Program('foo', Glob('*.c'))
-Zip('/tmp/everything', Glob('.??*') + Glob('*'))
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-'\".TP
-'\".RI GlobalBuilders( flag )
-'\"When
-'\".B flag
-'\"is non-zero,
-'\"adds the names of the default builders
-'\"(Program, Library, etc.)
-'\"to the global name space
-'\"so they can be called without an explicit construction environment.
-'\"(This is the default.)
-'\"When
-'\".B
-'\"flag is zero,
-'\"the names of the default builders are removed
-'\"from the global name space
-'\"so that an explicit construction environment is required
-'\"to call all builders.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Help( text )
-.TP
-.RI env.Help( text )
-This specifies help text to be printed if the
-.B -h
-argument is given to
-.BR scons .
-If
-.BR Help
-is called multiple times, the text is appended together in the order
-that
-.BR Help
-is called.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Ignore( target ", " dependency )
-.TP
-.RI env.Ignore( target ", " dependency )
-The specified dependency file(s)
-will be ignored when deciding if
-the target file(s) need to be rebuilt.
-
-You can also use
-.BR Ignore()
-to remove a target from the default build.
-In order to do this you must specify the directory the target will
-be built in as the target, and the file you want to skip building
-as the dependency.
-
-Note that this will only remove the dependencies listed from 
-the files built by default.  It will still be built if that 
-dependency is needed by another object being built. 
-See the third and forth examples below.
-
-Examples:
-
-.ES
-env.Ignore('foo', 'foo.c')
-env.Ignore('bar', ['bar1.h', 'bar2.h'])
-env.Ignore('.','foobar.obj')
-env.Ignore('bar','bar/foobar.obj')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Import( vars )
-.TP
-.RI env.Import( vars )
-This tells
-.B scons
-to import a list of variables into the current SConscript file. This
-will import variables that were exported with
-.BR Export ()
-or in the
-.I exports
-argument to
-.BR SConscript ().
-Variables exported by
-.BR SConscript ()
-have precedence.
-Multiple variable names can be passed to
-.BR Import ()
-as separate arguments or as a list. The variable "*" can be used
-to import all variables.
-
-Examples:
-
-.ES
-Import("env")
-Import("env", "variable")
-Import(["env", "variable"])
-Import("*")
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Literal( string )
-.TP
-.RI env.Literal( string )
-The specified
-.I string
-will be preserved as-is
-and not have construction variables expanded.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Local( targets )
-.TP
-.RI env.Local( targets )
-The specified
-.I targets
-will have copies made in the local tree,
-even if an already up-to-date copy
-exists in a repository.
-Returns a list of the target Node or Nodes.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-\" .TP
-\" .RI env.MergeShellPaths( arg ", [" prepend ])
-\" Merges the elements of the specified
-\" .IR arg ,
-\" which must be a dictionary, to the construction
-\" environment's copy of the shell environment
-\" in env['ENV'].
-\" (This is the environment which is passed
-\" to subshells spawned by SCons.)
-\" Note that
-\" .I arg
-\" must be a single value,
-\" so multiple strings must
-\" be passed in as a list,
-\" not as separate arguments to
-\" .BR env.MergeShellPaths ().
-
-\" New values are prepended to the environment variable by default,
-\" unless prepend=0 is specified.  
-\" Duplicate values are always eliminated, 
-\" since this function calls
-\" .B AppendENVPath
-\" or
-\" .B PrependENVPath
-\" depending on the
-\" .I prepend
-\" argument.  See those functions for more details.
-
-\" Examples:
-
-\" .ES
-\" # Prepend a path to the shell PATH.
-\" env.MergeShellPaths({'PATH':'/usr/local/bin'} )
-\" # Append two dirs to the shell INCLUDE.
-\" env.MergeShellPaths({'INCLUDE':['c:/inc1', 'c:/inc2']}, prepend=0 )
-
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.MergeFlags( arg ", [" unique ])
-Merges the specified
-.I arg
-values to the construction environment's construction variables.
-If the
-.I arg
-argument is not a dictionary,
-it is converted to one by calling
-.B env.ParseFlags()
-on the argument
-before the values are merged.
-Note that
-.I arg
-must be a single value,
-so multiple strings must
-be passed in as a list,
-not as separate arguments to
-.BR env.MergeFlags ().
-
-By default,
-duplicate values are eliminated;
-you can, however, specify
-.B unique=0
-to allow duplicate
-values to be added.
-When eliminating duplicate values,
-any construction variables that end with
-the string
-.B PATH
-keep the left-most unique value.
-All other construction variables keep
-the right-most unique value.
-
-Examples:
-
-.ES
-# Add an optimization flag to $CCFLAGS.
-env.MergeFlags('-O3')
-
-# Combine the flags returned from running pkg-config with an optimization
-# flag and merge the result into the construction variables.
-env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
-
-# Combine an optimization flag with the flags returned from running pkg-config
-# twice and merge the result into the construction variables.
-env.MergeFlags(['-O3',
-               '!pkg-config gtk+-2.0 --cflags --libs',
-               '!pkg-config libpng12 --cflags --libs'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI NoCache( target ", ...)"
-.TP
-.RI env.NoCache( target ", ...)"
-Specifies a list of files which should
-.I not
-be cached whenever the
-.BR CacheDir ()
-method has been activated.
-The specified targets may be a list
-or an individual target.
-
-Multiple files should be specified
-either as separate arguments to the
-.BR NoCache ()
-method, or as a list.
-.BR NoCache ()
-will also accept the return value of any of the construction environment
-Builder methods.
-
-Calling
-.BR NoCache ()
-on directories and other non-File Node types has no effect because
-only File Nodes are cached.
-
-Examples:
-
-.ES
-NoCache('foo.elf')
-NoCache(env.Program('hello', 'hello.c'))
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI NoClean( target ", ...)"
-.TP
-.RI env.NoClean( target ", ...)"
-Specifies a list of files or directories which should
-.I not
-be removed whenever the targets (or their dependencies)
-are specified with the
-.B -c
-command line option.
-The specified targets may be a list
-or an individual target.
-Multiple calls to
-.BR NoClean ()
-are legal,
-and prevent each specified target
-from being removed by calls to the
-.B -c
-option.
-
-Multiple files or directories should be specified
-either as separate arguments to the
-.BR NoClean ()
-method, or as a list.
-.BR NoClean ()
-will also accept the return value of any of the construction environment
-Builder methods.
-
-Calling
-.BR NoClean ()
-for a target overrides calling
-.BR Clean ()
-for the same target,
-and any targets passed to both functions will
-.I not
-be removed by the
-.B -c
-option.
-
-Examples:
-
-.ES
-NoClean('foo.elf')
-NoClean(env.Program('hello', 'hello.c'))
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.ParseConfig( command ", [" function ", " unique ])
-Calls the specified
-.I function
-to modify the environment as specified by the output of
-.I command .
-The default
-.I function
-is
-.BR env.MergeFlags (),
-which expects the output of a typical
-.I *-config command
-(for example,
-.BR gtk-config )
-and adds the options
-to the appropriate construction variables.
-By default,
-duplicate values are not
-added to any construction variables;
-you can specify
-.B unique=0
-to allow duplicate
-values to be added.
-
-Interpreted options
-and the construction variables they affect
-are as specified for the
-.BR env.ParseFlags ()
-method (which this method calls).
-See that method's description, below,
-for a table of options and construction variables.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI ParseDepends( filename ", [" must_exist ", " only_one ])
-.TP
-.RI env.ParseDepends( filename ", [" must_exist ", " only_one ])
-Parses the contents of the specified
-.I filename
-as a list of dependencies in the style of
-.BR Make
-or
-.BR mkdep ,
-and explicitly establishes all of the listed dependencies.
-
-By default,
-it is not an error
-if the specified
-.I filename
-does not exist.
-The optional
-.I must_exist
-argument may be set to a non-zero
-value to have
-scons
-throw an exception and
-generate an error if the file does not exist,
-or is otherwise inaccessible.
-
-The optional
-.I only_one
-argument may be set to a non-zero
-value to have
-scons
-thrown an exception and
-generate an error
-if the file contains dependency
-information for more than one target.
-This can provide a small sanity check
-for files intended to be generated
-by, for example, the
-.B gcc -M
-flag,
-which should typically only
-write dependency information for
-one output file into a corresponding
-.B .d
-file.
-
-The
-.I filename
-and all of the files listed therein
-will be interpreted relative to
-the directory of the
-.I SConscript
-file which calls the
-.B ParseDepends
-function.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.ParseFlags( flags ", ...)"
-Parses one or more strings containing
-typical command-line flags for GCC tool chains
-and returns a dictionary with the flag values
-separated into the appropriate SCons construction variables.
-This is intended as a companion to the
-.BR env.MergeFlags ()
-method, but allows for the values in the returned dictionary
-to be modified, if necessary,
-before merging them into the construction environment.
-(Note that
-.BR env.MergeFlags ()
-will call this method if its argument is not a dictionary,
-so it is usually not necessary to call
-.BR env.ParseFlags ()
-directly unless you want to manipulate the values.)
-
-If the first character in any string is
-an exclamation mark (!),
-the rest of the string is executed as a command,
-and the output from the command is
-parsed as GCC tool chain command-line flags
-and added to the resulting dictionary.
-
-Flag values are translated accordig to the prefix found,
-and added to the following construction variables:
-
-.ES
--arch               CCFLAGS, LINKFLAGS
--D                  CPPDEFINES
--framework          FRAMEWORKS
--frameworkdir=      FRAMEWORKPATH
--include            CCFLAGS
--isysroot           CCFLAGS, LINKFLAGS
--I                  CPPPATH
--l                  LIBS
--L                  LIBPATH
--mno-cygwin         CCFLAGS, LINKFLAGS
--mwindows           LINKFLAGS
--pthread            CCFLAGS, LINKFLAGS
--std=               CFLAGS
--Wa,                ASFLAGS, CCFLAGS
--Wl,-rpath=         RPATH
--Wl,-R,             RPATH
--Wl,-R              RPATH
--Wl,                LINKFLAGS
--Wp,                CPPFLAGS
--                   CCFLAGS
-+                   CCFLAGS, LINKFLAGS
-.EE
-
-.IP
-Any other strings not associated with options
-are assumed to be the names of libraries
-and added to the
-.B LIBS
-construction variable.
-
-Examples (all of which produce the same result):
-
-.ES
-dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
-dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
-dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
-dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-env.Perforce()
-A factory function that
-returns a Builder object
-to be used to fetch source files
-from the Perforce source code management system.
-The returned Builder
-is intended to be passed to the
-.B SourceCode
-function.
-
-This function is deprecated.  For details, see the entry for the
-.B SourceCode
-function.
-
-Example:
-
-.ES
-env.SourceCode('.', env.Perforce())
-.EE
-.IP
-Perforce uses a number of external
-environment variables for its operation.
-Consequently, this function adds the
-following variables from the user's external environment
-to the construction environment's
-ENV dictionary:
-P4CHARSET,
-P4CLIENT,
-P4LANGUAGE,
-P4PASSWD,
-P4PORT,
-P4USER,
-SystemRoot,
-USER,
-and
-USERNAME.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Platform( string )
-Returns a callable object
-that can be used to initialize
-a construction environment using the
-platform keyword of the Environment() method.
-
-Example:
-
-.ES
-env = Environment(platform = Platform('win32'))
-.EE
-.TP
-.RI env.Platform( string )
-Applies the callable object for the specified platform
-.I string
-to the environment through which the method was called.
-
-.ES
-env.Platform('posix')
-.EE
-.IP
-Note that the
-.B win32
-platform adds the
-.B SystemDrive
-and
-.B SystemRoot
-variables from the user's external environment
-to the construction environment's
-.B ENV
-dictionary.
-This is so that any executed commands
-that use sockets to connect with other systems
-(such as fetching source files from
-external CVS repository specifications like
-.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
-will work on Windows systems.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Progress( callable ", [" interval ])
-.TP
-.RI Progress( string ", [" interval ", " file ", " overwrite ])
-.TP
-.RI Progress( list_of_strings ", [" interval ", " file ", " overwrite ])
-Allows SCons to show progress made during the build
-by displaying a string or calling a function while
-evaluating Nodes (e.g. files).
-
-If the first specified argument is a Python callable
-(a function or an object that has a
-.BR __call__ ()
-method),
-the function will be called
-once every
-.I interval
-times a Node is evaluated.
-The callable will be passed the evaluated Node
-as its only argument.
-(For future compatibility,
-it's a good idea to also add
-.B *args
-and
-.B **kw
-as arguments to your function or method.
-This will prevent the code from breaking
-if SCons ever changes the interface
-to call the function with additional arguments in the future.)
-
-An example of a simple custom progress function
-that prints a string containing the Node name
-every 10 Nodes:
-
-.ES
-def my_progress_function(node, *args, **kw):
-    print 'Evaluating node %s!' % node
-Progress(my_progress_function, interval=10)
-.EE
-.IP
-A more complicated example of a custom progress display object
-that prints a string containing a count
-every 100 evaluated Nodes.
-Note the use of
-.B \\\\r
-(a carriage return)
-at the end so that the string
-will overwrite itself on a display:
-
-.ES
-import sys
-class ProgressCounter(object):
-    count = 0
-    def __call__(self, node, *args, **kw):
-        self.count += 100
-        sys.stderr.write('Evaluated %s nodes\\r' % self.count)
-Progress(ProgressCounter(), interval=100)
-.EE
-.IP
-If the first argument
-.BR Progress ()
-is a string,
-the string will be displayed
-every
-.I interval
-evaluated Nodes.
-The default is to print the string on standard output;
-an alternate output stream
-may be specified with the
-.B file=
-argument.
-The following will print a series of dots
-on the error output,
-one dot for every 100 evaluated Nodes:
-
-.ES
-import sys
-Progress('.', interval=100, file=sys.stderr)
-.EE
-.IP
-If the string contains the verbatim substring
-.B $TARGET,
-it will be replaced with the Node.
-Note that, for performance reasons, this is
-.I not
-a regular SCons variable substition,
-so you can not use other variables
-or use curly braces.
-The following example will print the name of
-every evaluated Node,
-using a
-.B \\\\r
-(carriage return) to cause each line to overwritten by the next line,
-and the
-.B overwrite=
-keyword argument to make sure the previously-printed
-file name is overwritten with blank spaces:
-
-.ES
-import sys
-Progress('$TARGET\\r', overwrite=True)
-.EE
-.IP
-If the first argument to
-.BR Progress ()
-is a list of strings,
-then each string in the list will be displayed
-in rotating fashion every
-.I interval
-evaluated Nodes.
-This can be used to implement a "spinner"
-on the user's screen as follows:
-
-.ES
-Progress(['-\\r', '\\\\\\r', '|\\r', '/\\r'], interval=5)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Precious( target ", ...)"
-.TP
-.RI env.Precious( target ", ...)"
-Marks each given
-.I target
-as precious so it is not deleted before it is rebuilt. Normally
-.B scons
-deletes a target before building it.
-Multiple targets can be passed in to a single call to
-.BR Precious ().
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.Prepend( key = val ", [...])"
-Appends the specified keyword arguments
-to the beginning of construction variables in the environment.
-If the Environment does not have
-the specified construction variable,
-it is simply added to the environment.
-If the values of the construction variable
-and the keyword argument are the same type,
-then the two values will be simply added together.
-Otherwise, the construction variable
-and the value of the keyword argument
-are both coerced to lists,
-and the lists are added together.
-(See also the Append method, above.)
-
-Example:
-
-.ES
-env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
-This appends new path elements to the given path in the
-specified external environment
-.RB ( ENV
-by default).
-This will only add
-any particular path once (leaving the first one it encounters and
-ignoring the rest, to preserve path order),
-and to help assure this,
-will normalize all paths (using
-.B os.path.normpath
-and
-.BR os.path.normcase ).
-This can also handle the
-case where the given old path variable is a list instead of a
-string, in which case a list will be returned instead of a string.
-
-If
-.I delete_existing
-is 0, then adding a path that already exists
-will not move it to the beginning;
-it will stay where it is in the list.
-
-Example:
-
-.ES
-print 'before:',env['ENV']['INCLUDE']
-include_path = '/foo/bar:/foo'
-env.PrependENVPath('INCLUDE', include_path)
-print 'after:',env['ENV']['INCLUDE']
-.EE
-
-The above exmaple will print:
-
-.ES
-before: /biz:/foo
-after: /foo/bar:/foo:/biz
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.PrependUnique( key = val ", delete_existing=0, [...])"
-Appends the specified keyword arguments
-to the beginning of construction variables in the environment.
-If the Environment does not have
-the specified construction variable,
-it is simply added to the environment.
-If the construction variable being appended to is a list,
-then any value(s) that already exist in the
-construction variable will
-.I not
-be added again to the list.
-However, if delete_existing is 1, 
-existing matching values are removed first, so
-existing values in the arg list move to the front of the list.
-
-Example:
-
-.ES
-env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-env.RCS()
-A factory function that
-returns a Builder object
-to be used to fetch source files
-from RCS.
-The returned Builder
-is intended to be passed to the
-.B SourceCode
-function:
-
-This function is deprecated.  For details, see the entry for the
-.B SourceCode
-function.
-
-Examples:
-
-.ES
-env.SourceCode('.', env.RCS())
-.EE
-.IP
-Note that
-.B scons
-will fetch source files
-from RCS subdirectories automatically,
-so configuring RCS
-as demonstrated in the above example
-should only be necessary if
-you are fetching from
-RCS,v
-files in the same
-directory as the source files,
-or if you need to explicitly specify RCS
-for a specific subdirectory.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.Replace( key = val ", [...])"
-Replaces construction variables in the Environment
-with the specified keyword arguments.
-
-Example:
-
-.ES
-env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Repository( directory )
-.TP
-.RI env.Repository( directory )
-Specifies that
-.I directory
-is a repository to be searched for files.
-Multiple calls to
-.BR Repository ()
-are legal,
-and each one adds to the list of
-repositories that will be searched.
-
-To
-.BR scons ,
-a repository is a copy of the source tree,
-from the top-level directory on down,
-which may contain
-both source files and derived files
-that can be used to build targets in
-the local source tree.
-The canonical example would be an
-official source tree maintained by an integrator.
-If the repository contains derived files,
-then the derived files should have been built using
-.BR scons ,
-so that the repository contains the necessary
-signature information to allow
-.B scons
-to figure out when it is appropriate to
-use the repository copy of a derived file,
-instead of building one locally.
-
-Note that if an up-to-date derived file
-already exists in a repository,
-.B scons
-will
-.I not
-make a copy in the local directory tree.
-In order to guarantee that a local copy
-will be made,
-use the
-.B Local()
-method.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Requires( target ", " prerequisite )
-.TP
-.RI env.Requires( target ", " prerequisite )
-Specifies an order-only relationship
-between the specified target file(s)
-and the specified prerequisite file(s).
-The prerequisite file(s)
-will be (re)built, if necessary,
-.I before
-the target file(s),
-but the target file(s) do not actually
-depend on the prerequisites
-and will not be rebuilt simply because
-the prerequisite file(s) change.
-
-Example:
-
-.ES
-env.Requires('foo', 'file-that-must-be-built-before-foo')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Return([ vars "... , " stop= ])
-By default,
-this stops processing the current SConscript
-file and returns to the calling SConscript file
-the values of the variables named in the
-.I vars
-string arguments.
-Multiple strings contaning variable names may be passed to
-.BR Return ().
-Any strings that contain white space
-
-The optional
-.B stop=
-keyword argument may be set to a false value
-to continue processing the rest of the SConscript
-file after the
-.BR Return ()
-call.
-This was the default behavior prior to SCons 0.98.
-However, the values returned
-are still the values of the variables in the named
-.I vars
-at the point
-.BR Return ()
-is called.
-
-Examples:
-
-.ES
-# Returns without returning a value.
-Return()
-
-# Returns the value of the 'foo' Python variable.
-Return("foo")
-
-# Returns the values of the Python variables 'foo' and 'bar'.
-Return("foo", "bar")
-
-# Returns the values of Python variables 'val1' and 'val2'.
-Return('val1 val2')
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
-.TP
-.RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
-Creates a Scanner object for
-the specified
-.IR function .
-See the section "Scanner Objects,"
-below, for a complete explanation of the arguments and behavior.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-env.SCCS()
-A factory function that
-returns a Builder object
-to be used to fetch source files
-from SCCS.
-The returned Builder
-is intended to be passed to the
-.B SourceCode
-function.
-
-This function is deprecated.  For details, see the entry for the
-.B SourceCode
-function.
-
-Example:
-
-.ES
-env.SourceCode('.', env.SCCS())
-.EE
-.IP
-Note that
-.B scons
-will fetch source files
-from SCCS subdirectories automatically,
-so configuring SCCS
-as demonstrated in the above example
-should only be necessary if
-you are fetching from
-.I s.SCCS
-files in the same
-directory as the source files,
-or if you need to explicitly specify SCCS
-for a specific subdirectory.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
-'\" .RI SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
-.TP
-.RI env.SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
-'\" .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
-.TP
-.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
-'\" .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
-.TP
-.RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
-'\" .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
-This tells
-.B scons
-to execute
-one or more subsidiary SConscript (configuration) files.
-Any variables returned by a called script using
-.BR Return ()
-will be returned by the call to
-.BR SConscript ().
-There are two ways to call the
-.BR SConscript ()
-function.
-
-The first way you can call
-.BR SConscript ()
-is to explicitly specify one or more
-.I scripts
-as the first argument.
-A single script may be specified as a string;
-multiple scripts must be specified as a list
-(either explicitly or as created by
-a function like
-.BR Split ()).
-Examples:
-.ES
-SConscript('SConscript')      # run SConscript in the current directory
-SConscript('src/SConscript')  # run SConscript in the src directory
-SConscript(['src/SConscript', 'doc/SConscript'])
-config = SConscript('MyConfig.py')
-.EE
-
-The second way you can call
-.BR SConscript ()
-is to specify a list of (sub)directory names
-as a
-.RI dirs= subdirs
-keyword argument.
-In this case,
-.B scons
-will, by default,
-execute a subsidiary configuration file named
-.B SConscript
-in each of the specified directories.
-You may specify a name other than
-.B SConscript
-by supplying an optional
-.RI name= script
-keyword argument.
-The first three examples below have the same effect
-as the first three examples above:
-.ES
-SConscript(dirs='.')      # run SConscript in the current directory
-SConscript(dirs='src')    # run SConscript in the src directory
-SConscript(dirs=['src', 'doc'])
-SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
-.EE
-
-The optional
-.I exports
-argument provides a list of variable names or a dictionary of
-named values to export to the
-.IR script(s) .
-These variables are locally exported only to the specified
-.IR script(s) ,
-and do not affect the global pool of variables used by the
-.BR Export ()
-function.
-'\"If multiple dirs are provided, each script gets a fresh export.
-The subsidiary
-.I script(s)
-must use the
-.BR Import ()
-function to import the variables.
-Examples:
-.ES
-foo = SConscript('sub/SConscript', exports='env')
-SConscript('dir/SConscript', exports=['env', 'variable'])
-SConscript(dirs='subdir', exports='env variable')
-SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
-.EE
-
-If the optional
-.I variant_dir
-argument is present, it causes an effect equivalent to the
-.BR VariantDir ()
-method described below.
-(If
-.I variant_dir
-is not present, the
-'\" .IR src_dir and
-.I duplicate
-'\" arguments are ignored.)
-argument is ignored.)
-The
-.I variant_dir
-'\" and
-'\" .I src_dir
-'\" arguments are interpreted relative to the directory of the calling
-argument is interpreted relative to the directory of the calling
-.B SConscript
-file.
-See the description of the
-.BR VariantDir ()
-function below for additional details and restrictions.
-
-If
-.I variant_dir
-is present,
-'\" but
-'\" .IR src_dir " is not,"
-the source directory is the directory in which the
-.B SConscript
-file resides and the
-.B SConscript
-file is evaluated as if it were in the
-.I variant_dir
-directory:
-.ES
-SConscript('src/SConscript', variant_dir = 'build')
-.EE
-is equivalent to
-.ES
-VariantDir('build', 'src')
-SConscript('build/SConscript')
-.EE
-This later paradigm is often used when the sources are
-in the same directory as the
-.BR SConstruct:
-.ES
-SConscript('SConscript', variant_dir = 'build')
-.EE
-is equivalent to
-.ES
-VariantDir('build', '.')
-SConscript('build/SConscript')
-.EE
-
-'\" If
-'\" .IR variant_dir " and"
-'\" .IR src_dir " are both present,"
-'\" xxxxx everything is in a state of confusion.
-'\" .ES
-'\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.')
-'\" runs src/SConscript in build/src, but
-'\" SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src')
-'\" runs lib/SConscript (in lib!).  However,
-'\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = 'src')
-'\" runs src/SConscript in build.  Moreover,
-'\" SConscript(dirs = 'src/lib', variant_dir = 'build', src_dir = 'src')
-'\" runs src/lib/SConscript in build/lib.  Moreover,
-'\" SConscript(dirs = 'build/src/lib', variant_dir = 'build', src_dir = 'src')
-'\" can't find build/src/lib/SConscript, even though it ought to exist.
-'\" .EE
-'\" is equivalent to
-'\" .ES
-'\" ????????????????
-'\" .EE
-'\" and what about this alternative?
-'\"TODO??? SConscript('build/SConscript', src_dir='src')
-
-Here are some composite examples:
-
-.ES
-# collect the configuration information and use it to build src and doc
-shared_info = SConscript('MyConfig.py')
-SConscript('src/SConscript', exports='shared_info')
-SConscript('doc/SConscript', exports='shared_info')
-.EE
-
-.ES
-# build debugging and production versions.  SConscript
-# can use Dir('.').path to determine variant.
-SConscript('SConscript', variant_dir='debug', duplicate=0)
-SConscript('SConscript', variant_dir='prod', duplicate=0)
-.EE
-
-.ES
-# build debugging and production versions.  SConscript
-# is passed flags to use.
-opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
-SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
-opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
-SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
-.EE
-
-.ES
-# build common documentation and compile for different architectures
-SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
-SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
-SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SConscriptChdir( value )
-.TP
-.RI env.SConscriptChdir( value )
-By default,
-.B scons
-changes its working directory
-to the directory in which each
-subsidiary SConscript file lives.
-This behavior may be disabled
-by specifying either:
-
-.ES
-SConscriptChdir(0)
-env.SConscriptChdir(0)
-.EE
-.IP
-in which case
-.B scons
-will stay in the top-level directory
-while reading all SConscript files.
-(This may be necessary when building from repositories,
-when all the directories in which SConscript files may be found
-don't necessarily exist locally.)
-You may enable and disable
-this ability by calling
-SConscriptChdir()
-multiple times.
-
-Example:
-
-.ES
-env = Environment()
-SConscriptChdir(0)
-SConscript('foo/SConscript')	# will not chdir to foo
-env.SConscriptChdir(1)
-SConscript('bar/SConscript')	# will chdir to bar
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SConsignFile([ file , dbm_module ])
-.TP
-.RI env.SConsignFile([ file , dbm_module ])
-This tells
-.B scons
-to store all file signatures
-in the specified database
-.IR file .
-If the
-.I file
-name is omitted,
-.B .sconsign
-is used by default.
-(The actual file name(s) stored on disk
-may have an appropriated suffix appended
-by the
-.IR  dbm_module .)
-If
-.I file
-is not an absolute path name,
-the file is placed in the same directory as the top-level
-.B SConstruct
-file.
-
-If
-.I file
-is
-.BR None ,
-then
-.B scons
-will store file signatures
-in a separate
-.B .sconsign
-file in each directory,
-not in one global database file.
-(This was the default behavior
-prior to SCons 0.96.91 and 0.97.)
-
-The optional
-.I dbm_module
-argument can be used to specify
-which Python database module
-The default is to use a custom
-.B SCons.dblite
-module that uses pickled
-Python data structures,
-and which works on all Python versions.
-
-Examples:
-
-.ES
-# Explicitly stores signatures in ".sconsign.dblite"
-# in the top-level SConstruct directory (the
-# default behavior).
-SConsignFile()
-
-# Stores signatures in the file "etc/scons-signatures"
-# relative to the top-level SConstruct directory.
-SConsignFile("etc/scons-signatures")
-
-# Stores signatures in the specified absolute file name.
-SConsignFile("/home/me/SCons/signatures")
-
-# Stores signatures in a separate .sconsign file
-# in each directory.
-SConsignFile(None)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.SetDefault(key = val ", [...])"
-Sets construction variables to default values specified with the keyword
-arguments if (and only if) the variables are not already set.
-The following statements are equivalent:
-
-.ES
-env.SetDefault(FOO = 'foo')
-
-if 'FOO' not in env: env['FOO'] = 'foo'
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SetOption( name ", " value )
-.TP
-.RI env.SetOption( name ", " value )
-This function provides a way to set a select subset of the scons command
-line options from a SConscript file. The options supported are:
-
-.RS 10
-.TP 6
-.B clean
-which corresponds to -c, --clean and --remove;
-.TP 6
-.B duplicate
-which corresponds to --duplicate;
-.TP 6
-.B help
-which corresponds to -h and --help;
-.TP 6
-.B implicit_cache
-which corresponds to --implicit-cache;
-.TP 6
-.B max_drift
-which corresponds to --max-drift;
-.TP 6
-.B no_exec
-which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
-.TP 6
-.B num_jobs
-which corresponds to -j and --jobs;
-.TP 6
-.B random
-which corresponds to --random; and
-.TP 6
-.B stack_size
-which corresponds to --stack-size.
-.RE
-
-.IP
-See the documentation for the
-corresponding command line object for information about each specific
-option.
-
-Example:
-
-.ES
-SetOption('max_drift', 1)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SideEffect( side_effect ", " target )
-.TP
-.RI env.SideEffect( side_effect ", " target )
-Declares
-.I side_effect
-as a side effect of building
-.IR target .
-Both
-.I side_effect
-and
-.I target
-can be a list, a file name, or a node.
-A side effect is a target file that is created or updated
-as a side effect of building other targets.
-For example, a Windows PDB
-file is created as a side effect of building the .obj
-files for a static library,
-and various log files are created updated
-as side effects of various TeX commands.
-If a target is a side effect of multiple build commands,
-.B scons
-will ensure that only one set of commands
-is executed at a time.
-Consequently, you only need to use this method
-for side-effect targets that are built as a result of
-multiple build commands.
-
-Because multiple build commands may update
-the same side effect file,
-by default the
-.I side_effect
-target is
-.I not
-automatically removed
-when the
-.I target
-is removed by the
-.B -c
-option.
-(Note, however, that the
-.I side_effect
-might be removed as part of
-cleaning the directory in which it lives.)
-If you want to make sure the
-.I side_effect
-is cleaned whenever a specific
-.I target
-is cleaned,
-you must specify this explicitly
-with the
-.BR Clean ()
-or
-.BR env.Clean ()
-function.
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SourceCode( entries ", " builder )
-.TP
-.RI env.SourceCode( entries ", " builder )
-This function and its associate factory functions are deprecated.
-There is no replacement.
-The intended use was to keep a local tree in sync with an archive,
-but in actuality the function only causes the archive
-to be fetched on the first run.
-Synchronizing with the archive is best done external to SCons.
-
-Arrange for non-existent source files to
-be fetched from a source code management system
-using the specified
-.IR builder .
-The specified
-.I entries
-may be a Node, string or list of both,
-and may represent either individual
-source files or directories in which
-source files can be found.
-
-For any non-existent source files,
-.B scons
-will search up the directory tree
-and use the first
-.B SourceCode
-builder it finds.
-The specified
-.I builder
-may be
-.BR None ,
-in which case
-.B scons
-will not use a builder to fetch
-source files for the specified
-.IR entries ,
-even if a
-.B SourceCode
-builder has been specified
-for a directory higher up the tree.
-
-.B scons
-will, by default,
-fetch files from SCCS or RCS subdirectories
-without explicit configuration.
-This takes some extra processing time
-to search for the necessary
-source code management files on disk.
-You can avoid these extra searches
-and speed up your build a little
-by disabling these searches as follows:
-
-.ES
-env.SourceCode('.', None)
-.EE
-
-.IP
-Note that if the specified
-.I builder
-is one you create by hand,
-it must have an associated
-construction environment to use
-when fetching a source file.
-
-.B scons
-provides a set of canned factory
-functions that return appropriate
-Builders for various popular
-source code management systems.
-Canonical examples of invocation include:
-
-.ES
-env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
-env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
-env.SourceCode('/', env.RCS())
-env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
-env.SourceCode('no_source.c', None)
-.EE
-'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI env.subst( input ", [" raw ", " target ", " source ", " conv ])
-Performs construction variable interpolation
-on the specified string or sequence argument
-.IR input .
-
-By default,
-leading or trailing white space will
-be removed from the result.
-and all sequences of white space
-will be compressed to a single space character.
-Additionally, any
-.B $(
-and
-.B $)
-character sequences will be stripped from the returned string,
-The optional
-.I raw
-argument may be set to
-.B 1
-if you want to preserve white space and
-.BR $( - $)
-sequences.
-The
-.I raw
-argument may be set to
-.B 2
-if you want to strip
-all characters between
-any
-.B $(
-and
-.B $)
-pairs
-(as is done for signature calculation).
-
-If the input is a sequence
-(list or tuple),
-the individual elements of
-the sequence will be expanded,
-and the results will be returned as a list.
-
-The optional
-.I target
-and
-.I source
-keyword arguments
-must be set to lists of
-target and source nodes, respectively,
-if you want the
-.BR $TARGET ,
-.BR $TARGETS ,
-.BR $SOURCE
-and
-.BR $SOURCES
-to be available for expansion.
-This is usually necessary if you are
-calling
-.BR env.subst ()
-from within a Python function used
-as an SCons action.
-
-Returned string values or sequence elements
-are converted to their string representation by default.
-The optional
-.I conv
-argument
-may specify a conversion function
-that will be used in place of
-the default.
-For example, if you want Python objects
-(including SCons Nodes)
-to be returned as Python objects,
-you can use the Python
-.B lambda
-idiom to pass in an unnamed function
-that simply returns its unconverted argument.
-
-Example:
-
-.ES
-print env.subst("The C compiler is: $CC")
-
-def compile(target, source, env):
-    sourceDir = env.subst("${SOURCE.srcdir}",
-                          target=target,
-                          source=source)
-
-source_nodes = env.subst('$EXPAND_TO_NODELIST',
-                         conv=lambda x: x)
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-'\".TP
-'\".RI Subversion( repository ", " module )
-'\"A factory function that
-'\"returns a Builder object
-'\"to be used to fetch source files
-'\"from the specified Subversion
-'\".IR repository .
-'\"The returned Builder
-'\"is intended to be passed to the
-'\".B SourceCode
-'\"function.
-'\"
-'\"The optional specified
-'\".I module
-'\"will be added to the beginning
-'\"of all repository path names;
-'\"this can be used, in essence,
-'\"to strip initial directory names
-'\"from the repository path names,
-'\"so that you only have to
-'\"replicate part of the repository
-'\"directory hierarchy in your
-'\"local build directory.
-'\"
-'\"This function is deprecated.  For details, see the entry for the
-'\".B SourceCode
-'\"function.
-'\"
-'\"Example:
-'\"
-'\".ES
-'\"# Will fetch foo/bar/src.c
-'\"# from /usr/local/Subversion/foo/bar/src.c.
-'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
+'\" BEGIN GENERATED FUNCTION DESCRIPTIONS
 '\"
-'\"# Will fetch bar/src.c
-'\"# from /usr/local/Subversion/foo/bar/src.c.
-'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
+'\" The descriptions below of the various SCons functions are generated
+'\" from the .xml files that live next to the various Python modules in
+'\" the build enginer library.  If you're reading this [gnt]roff file
+'\" with an eye towards patching this man page, you can still submit
+'\" a diff against this text, but it will have to be translated to a
+'\" diff against the underlying .xml file before the patch is actually
+'\" accepted.  If you do that yourself, it will make it easier to
+'\" integrate the patch.
 '\"
-'\"# Will fetch src.c
-'\"# from /usr/local/Subversion/foo/bar/src.c.
-'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
-'\".EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI SourceSignatures( type )
-.TP
-.RI env.SourceSignatures( type )
-Note:  Although it is not yet officially deprecated,
-use of this function is discouraged.
-See the
-.BR Decider ()
-function for a more flexible and straightforward way
-to configure SCons' decision-making.
-
-The
-.BR SourceSignatures ()
-function tells
-.B scons
-how to decide if a source file
-(a file that is not built from any other files)
-has changed since the last time it
-was used to build a particular target file.
-Legal values are
-.B "MD5"
-or
-.BR "timestamp" .
-
-If the environment method is used,
-the specified type of source signature
-is only used when deciding whether targets
-built with that environment are up-to-date or must be rebuilt.
-If the global function is used,
-the specified type of source signature becomes the default
-used for all decisions
-about whether targets are up-to-date.
-
-.B "MD5"
-means
-.B scons
-decides that a source file has changed
-if the MD5 checksum of its contents has changed since
-the last time it was used to rebuild a particular target file.
-
-.B "timestamp"
-means
-.B scons
-decides that a source file has changed
-if its timestamp (modification time) has changed since
-the last time it was used to rebuild a particular target file.
-(Note that although this is similar to the behavior of Make,
-by default it will also rebuild if the dependency is
-.I older
-than the last time it was used to rebuild the target file.)
-
-There is no different between the two behaviors
-for Python
-.BR Value ()
-node objects.
-
-.B "MD5"
-signatures take longer to compute,
-but are more accurate than
-.B "timestamp"
-signatures.
-The default value is
-.BR "MD5" .
-
-Note that the default
-.BR TargetSignatures ()
-setting (see below)
-is to use this
-.BR SourceSignatures ()
-setting for any target files that are used
-to build other target files.
-Consequently, changing the value of
-.BR SourceSignatures ()
-will, by default,
-affect the up-to-date decision for all files in the build
-(or all files built with a specific construction environment
-when
-.BR env.SourceSignatures ()
-is used).
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Split( arg )
-.TP
-.RI env.Split( arg )
-Returns a list of file names or other objects.
-If arg is a string,
-it will be split on strings of white-space characters
-within the string,
-making it easier to write long lists of file names.
-If arg is already a list,
-the list will be returned untouched.
-If arg is any other type of object,
-it will be returned as a list
-containing just the object.
-
-Example:
-
-.ES
-files = Split("f1.c f2.c f3.c")
-files = env.Split("f4.c f5.c f6.c")
-files = Split("""
-	f7.c
-	f8.c
-	f9.c
-""")
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Tag( node ", " tags )
-Annotates file or directory Nodes with
-information about how the
-.BR Package ()
-Builder should package those files or directories.
-All tags are optional.
-
-Examples:
-
-.ES
-# makes sure the built library will be installed with 0644 file
-# access mode
-Tag( Library( 'lib.c' ), UNIX_ATTR="0644" )
-
-# marks file2.txt to be a documentation file
-Tag( 'file2.txt', DOC )
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI TargetSignatures( type )
-.TP
-.RI env.TargetSignatures( type )
-Note:  Although it is not yet officially deprecated,
-use of this function is discouraged.
-See the
-.BR Decider ()
-function for a more flexible and straightforward way
-to configure SCons' decision-making.
-
-The
-.BR TargetSignatures ()
-function tells
-.B scons
-how to decide if a target file
-(a file that
-.I is
-built from any other files)
-has changed since the last time it
-was used to build some other target file.
-Legal values are
-.BR "build" ;
-.BR "content"
-(or its synonym
-.BR "MD5" );
-.BR "timestamp" ;
-or
-.BR "source" .
-
-If the environment method is used,
-the specified type of target signature is only used
-for targets built with that environment.
-If the global function is used,
-the specified type of signature becomes the default
-used for all target files that
-don't have an explicit target signature type
-specified for their environments.
-
-.B "content"
-(or its synonym
-.BR "MD5" )
-means
-.B scons
-decides that a target file has changed
-if the MD5 checksum of its contents has changed since
-the last time it was used to rebuild some other target file.
-This means
-.B scons
-will open up
-MD5 sum the contents
-of target files after they're built,
-and may decide that it does not need to rebuild
-"downstream" target files if a file was
-rebuilt with exactly the same contents as the last time.
-
-.B "timestamp"
-means
-.B scons
-decides that a target file has changed
-if its timestamp (modification time) has changed since
-the last time it was used to rebuild some other target file.
-(Note that although this is similar to the behavior of Make,
-by default it will also rebuild if the dependency is
-.I older
-than the last time it was used to rebuild the target file.)
-
-.B "source"
-means
-.B scons
-decides that a target file has changed
-as specified by the corresponding
-.BR SourceSignatures ()
-setting
-.BR "" ( "MD5"
-or
-.BR "timestamp" ).
-This means that
-.B scons
-will treat all input files to a target the same way,
-regardless of whether they are source files
-or have been built from other files.
-
-.B "build"
-means
-.B scons
-decides that a target file has changed
-if it has been rebuilt in this invocation
-or if its content or timestamp have changed
-as specified by the corresponding
-.BR SourceSignatures ()
-setting.
-This "propagates" the status of a rebuilt file
-so that other "downstream" target files
-will always be rebuilt,
-even if the contents or the timestamp
-have not changed.
-
-.B "build"
-signatures are fastest because
-.B "content"
-(or
-.BR "MD5" )
-signatures take longer to compute,
-but are more accurate than
-.B "timestamp"
-signatures,
-and can prevent unnecessary "downstream" rebuilds
-when a target file is rebuilt to the exact same contents
-as the previous build.
-The
-.B "source"
-setting provides the most consistent behavior
-when other target files may be rebuilt from
-both source and target input files.
-The default value is
-.BR "source" .
-
-Because the default setting is
-.BR "source" ,
-using
-.BR SourceSignatures ()
-is generally preferable to
-.BR TargetSignatures () ,
-so that the up-to-date decision
-will be consistent for all files
-(or all files built with a specific construction environment).
-Use of
-.BR TargetSignatures ()
-provides specific control for how built target files
-affect their "downstream" dependencies.
-
+'\" BEGIN GENERATED FUNCTION DESCRIPTIONS
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Tool( string [, toolpath ", " **kw ])
-Returns a callable object
-that can be used to initialize
-a construction environment using the
-tools keyword of the Environment() method.
-The object may be called with a construction
-environment as an argument,
-in which case the object will
-add the necessary variables
-to the construction environment
-and the name of the tool will be added to the
-.B $TOOLS
-construction variable.
-
-Additional keyword arguments are passed to the tool's
-.B generate()
-method.
-
-Examples:
-
-.ES
-env = Environment(tools = [ Tool('msvc') ])
-
-env = Environment()
-t = Tool('msvc')
-t(env)  # adds 'msvc' to the TOOLS variable
-u = Tool('opengl', toolpath = ['tools'])
-u(env)  # adds 'opengl' to the TOOLS variable
-.EE
-.TP
-.RI env.Tool( string [, toolpath ", " **kw ])
-Applies the callable object for the specified tool
-.I string
-to the environment through which the method was called.
-
-Additional keyword arguments are passed to the tool's
-.B generate()
-method.
-
-.ES
-env.Tool('gcc')
-env.Tool('opengl', toolpath = ['build/tools'])
-.EE
-
+.so functions.man
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI Value( value ", [" built_value ])
-.TP
-.RI env.Value( value ", [" built_value ])
-Returns a Node object representing the specified Python value.  Value
-Nodes can be used as dependencies of targets.  If the result of
-calling
-.BR str( value )
-changes between SCons runs, any targets depending on
-.BR Value( value )
-will be rebuilt.
-(This is true even when using timestamps to decide if
-files are up-to-date.)
-When using timestamp source signatures, Value Nodes'
-timestamps are equal to the system time when the Node is created.
-
-The returned Value Node object has a
-.BR write ()
-method that can be used to "build" a Value Node
-by setting a new value.
-The optional
-.I built_value
-argument can be specified
-when the Value Node is created
-to indicate the Node should already be considered
-"built."
-There is a corresponding
-.BR read ()
-method that will return the built value of the Node.
-
-Examples:
-
-.ES
-env = Environment()
-
-def create(target, source, env):
-    # A function that will write a 'prefix=$SOURCE'
-    # string into the file name specified as the
-    # $TARGET.
-    f = open(str(target[0]), 'wb')
-    f.write('prefix=' + source[0].get_contents())
-
-# Fetch the prefix= argument, if any, from the command
-# line, and use /usr/local as the default.
-prefix = ARGUMENTS.get('prefix', '/usr/local')
-
-# Attach a .Config() builder for the above function action
-# to the construction environment.
-env['BUILDERS']['Config'] = Builder(action = create)
-env.Config(target = 'package-config', source = Value(prefix))
-
-def build_value(target, source, env):
-    # A function that "builds" a Python Value by updating
-    # the the Python value with the contents of the file
-    # specified as the source of the Builder call ($SOURCE).
-    target[0].write(source[0].get_contents())
-
-output = env.Value('before')
-input = env.Value('after')
-
-# Attach a .UpdateValue() builder for the above function
-# action to the construction environment.
-env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
-env.UpdateValue(target = Value(output), source = Value(input))
-.EE
-
-'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI VariantDir( variant_dir ", " src_dir ", [" duplicate ])
-.TP
-.RI env.VariantDir( variant_dir ", " src_dir ", [" duplicate ])
-Use the
-.BR VariantDir ()
-function to create a copy of your sources in another location:
-if a name under
-.IR variant_dir
-is not found but exists under
-.IR src_dir ,
-the file or directory is copied to
-.IR variant_dir .
-Target files can be built in a different directory
-than the original sources by simply refering to the sources (and targets)
-within the variant tree.
-
-.BR VariantDir ()
-can be called multiple times with the same
-.I  src_dir
-to set up multiple builds with different options
-.RI ( variants ).
-The
-.I src_dir
-location must be in or underneath the SConstruct file's directory, and
-.I variant_dir
-may not be underneath
-.IR src_dir .
-'\"TODO: Can the above restrictions be clarified or relaxed?
-'\"TODO: The latter restriction is clearly not completely right;
-'\"TODO: src_dir = '.' works fine with a build dir under it.
-
-The default behavior is for
-.B scons
-to physically duplicate the source files in the variant tree.
-Thus, a build performed in the variant tree is guaranteed to be identical
-to a build performed in the source tree even if
-intermediate source files are generated during the build,
-or preprocessors or other scanners search for included files
-relative to the source file,
-or individual compilers or other invoked tools are hard-coded
-to put derived files in the same directory as source files.
-
-If possible on the platform,
-the duplication is performed by linking rather than copying;
-see also the
-.IR --duplicate
-command-line option.
-Moreover, only the files needed for the build are duplicated;
-files and directories that are not used are not present in
-.IR variant_dir .
-
-Duplicating the source tree may be disabled by setting the
-.I duplicate
-argument to 0 (zero).
-This will cause
-.B scons
-to invoke Builders using the path names of source files in
-.I src_dir
-and the path names of derived files within
-.IR variant_dir .
-This is always more efficient than
-.IR duplicate =1,
-and is usually safe for most builds
-(but see above for cases that may cause problems).
-
-Note that
-.BR VariantDir ()
-works most naturally with a subsidiary SConscript file.
-However, you would then call the subsidiary SConscript file
-not in the source directory, but in the
-.I variant_dir ,
-regardless of the value of
-.IR duplicate .
-This is how you tell
-.B scons
-which variant of a source tree to build:
-
-.ES
-# run src/SConscript in two variant directories
-VariantDir('build/variant1', 'src')
-SConscript('build/variant1/SConscript')
-VariantDir('build/variant2', 'src')
-SConscript('build/variant2/SConscript')
-.EE
-
-.IP
-See also the
-.BR SConscript ()
-function, described above,
-for another way to specify a variant directory
-in conjunction with calling a subsidiary SConscript file.
-
-Examples:
-
-.ES
-# use names in the build directory, not the source directory
-VariantDir('build', 'src', duplicate=0)
-Program('build/prog', 'build/source.c')
-.EE
-
-.ES
-# this builds both the source and docs in a separate subtree
-VariantDir('build', '.', duplicate=0)
-SConscript(dirs=['build/src','build/doc'])
-.EE
-
-.ES
-# same as previous example, but only uses SConscript
-SConscript(dirs='src', variant_dir='build/src', duplicate=0)
-SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
-.EE
-
+'\" END GENERATED FUNCTION DESCRIPTIONS
+'\"
+'\" The descriptions above of the various SCons functions are generated
+'\" from the .xml files that live next to the various Python modules in
+'\" the build enginer library.  If you're reading this [gnt]roff file
+'\" with an eye towards patching this man page, you can still submit
+'\" a diff against this text, but it will have to be translated to a
+'\" diff against the underlying .xml file before the patch is actually
+'\" accepted.  If you do that yourself, it will make it easier to
+'\" integrate the patch.
+'\"
+'\" END GENERATED FUNCTION DESCRIPTIONS
 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-.TP
-.RI WhereIs( program ", [" path  ", " pathext ", " reject ])
-.TP
-.RI env.WhereIs( program ", [" path  ", " pathext ", " reject ])
-
-Searches for the specified executable
-.I program,
-returning the full path name to the program
-if it is found,
-and returning None if not.
-Searches the specified
-.I path,
-the value of the calling environment's PATH
-(env['ENV']['PATH']),
-or the user's current external PATH
-(os.environ['PATH'])
-by default.
-On Windows systems, searches for executable
-programs with any of the file extensions
-listed in the specified
-.I pathext,
-the calling environment's PATHEXT
-(env['ENV']['PATHEXT'])
-or the user's current PATHEXT
-(os.environ['PATHEXT'])
-by default.
-Will not select any
-path name or names
-in the specified
-.I reject
-list, if any.
 
 .SS SConscript Variables
 In addition to the global functions and methods,
@@ -8105,14 +4150,14 @@ implicit dependencies
 based only on the target file
 and the construction environment,
 .I not
-for implicit
-(See the section "Scanner Objects," below,
+for implicit dependencies based on source files.
+(See the section "Scanner Objects" below,
 for information about creating Scanner objects.)
 
 .IP source_scanner
 A Scanner object that
 will be invoked to
-find implicit dependences in
+find implicit dependencies in
 any source files
 used to build this target file.
 This is where you would
@@ -8129,7 +4174,7 @@ for on-disk changes to files
 that
 .B scons
 does not know about from other Builder or function calls.
-(See the section "Scanner Objects," below,
+(See the section "Scanner Objects" below,
 for information about creating your own Scanner objects.)
 
 .IP target_factory
@@ -9234,7 +5279,7 @@ to enclose arbitrary Python code to be evaluated.
 (In fact, this is how the above modifiers are substituted,
 they are simply attributes of the Python objects
 that represent TARGET, SOURCES, etc.)
-See the section "Python Code Substitution," below,
+See the section "Python Code Substitution" below,
 for more thorough examples of
 how this can be used.
 
@@ -9411,9 +5456,9 @@ function accepts the following arguments:
 This can be either:
 1) a Python function that will process
 the Node (file)
-and return a list of strings (file names)
+and return a list of File Nodes
 representing the implicit
-dependencies found in the contents;
+dependencies (file names) found in the contents;
 or:
 2) a dictionary that maps keys
 (typically the file suffix, but see below for more discussion)
@@ -9587,7 +5632,7 @@ def xyz_scan(node, env, path):
 
 XYZScanner = Scanner(xyz_scan)
 
-SourceFileScanner.add_scanner('.xyx', XYZScanner)
+SourceFileScanner.add_scanner('.xyz', XYZScanner)
 
 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
 .EE
@@ -9856,7 +5901,7 @@ include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
 def kfile_scan(node, env, path, arg):
     contents = node.get_text_contents()
     includes = include_re.findall(contents)
-    return includes
+    return env.File(includes)
 
 kscan = Scanner(name = 'kfile',
                 function = kfile_scan,
@@ -9872,6 +5917,14 @@ env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
 bar_in.target_scanner = kscan
 .EE
 
+It is important to note that you
+have to return a list of File nodes from the scan function, simple
+strings for the file names won't do. As in the examples we are showing here,
+you can use the
+.BR File()
+function of your current Environment in order to create nodes on the fly from
+a sequence of file names with relative paths.
+
 Here is a similar but more complete example that searches
 a path of directories
 (specified as the
@@ -9880,30 +5933,35 @@ construction variable)
 for files that actually exist:
 
 .ES
+import re
+import os
 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
 
 def my_scan(node, env, path, arg):
-   contents = node.get_text_contents()
-   includes = include_re.findall(contents)
-   if includes == []:
+    contents = node.get_text_contents()
+    includes = include_re.findall(contents)
+    if includes == []:
         return []
     results = []
     for inc in includes:
         for dir in path:
-            file = dir + os.sep + inc
+            file = str(dir) + os.sep + inc
             if os.path.exists(file):
                 results.append(file)
                 break
-    return results
+    return env.File(results)
 
 scanner = Scanner(name = 'myscanner',
                  function = my_scan,
                  argument = None,
                  skeys = ['.x'],
-                 path_function = FindPathDirs('MYPATH'),
+                 path_function = FindPathDirs('MYPATH')
                  )
 scanners = Environment().Dictionary('SCANNERS')
-env = Environment(SCANNERS = scanners + [scanner])
+env = Environment(SCANNERS = scanners + [scanner],
+                  MYPATH = ['incs'])
+
+env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET')
 .EE
 
 The
@@ -9913,7 +5971,13 @@ function used in the previous example returns a function
 that will return a list of directories
 specified in the
 .B $MYPATH
-construction variable.
+construction variable. It lets SCons detect the file
+.B incs/foo.inc
+, even if 
+.B foo.x 
+contains the line
+.B include foo.inc 
+only.
 If you need to customize how the search path is derived,
 you would provide your own
 .B path_function
@@ -9934,7 +5998,7 @@ scanner = Scanner(name = 'myscanner',
                  function = my_scan,
                  argument = None,
                  skeys = ['.x'],
-                 path_function = pf,
+                 path_function = pf
                  )
 .EE
 
diff --git a/doc/man/sconsign.1 b/doc/man/sconsign.1
index d7f7ef9..2cd2fca 100644
--- a/doc/man/sconsign.1
+++ b/doc/man/sconsign.1
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 .\"
 .\" Permission is hereby granted, free of charge, to any person obtaining
 .\" a copy of this software and associated documentation files (the
@@ -19,7 +19,7 @@
 .\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 .\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 .\"
-.\" doc/man/sconsign.1 5134 2010/08/16 23:02:40 bdeegan
+.\" doc/man/sconsign.1 5357 2011/09/09 21:31:03 bdeegan
 .\"
 .\" ES - Example Start - indents and turns off line fill
 .de ES
@@ -31,7 +31,7 @@
 .RE
 .fi
 ..
-.TH SCONSIGN 1 "August 2010"
+.TH SCONSIGN 1 "September 2011"
 .SH NAME
 sconsign \- print SCons .sconsign file information
 .SH SYNOPSIS
diff --git a/doc/python10/scons.mod b/doc/python10/scons.mod
index ee5b1bb..bec5425 100644
--- a/doc/python10/scons.mod
+++ b/doc/python10/scons.mod
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   An SCons-specific DTD module, for use with SCons DocBook
   documentation, that contains names, phrases, acronyms, etc. used
diff --git a/doc/scons.mod b/doc/scons.mod
index b1993d4..73ea8f3 100644
--- a/doc/scons.mod
+++ b/doc/scons.mod
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   An SCons-specific DTD module, for use with SCons DocBook
   documentation, that contains names, phrases, acronyms, etc. used
@@ -100,6 +100,7 @@
 <!ENTITY debug-explain "<literal>--debug=explain</literal>">
 <!ENTITY debug-findlibs "<literal>--debug=findlibs</literal>">
 <!ENTITY debug-includes "<literal>--debug=includes</literal>">
+<!ENTITY debug-prepare "<literal>--debug=prepare</literal>">
 <!ENTITY debug-presub "<literal>--debug=presub</literal>">
 <!ENTITY debug-stacktrace "<literal>--debug=stacktrace</literal>">
 <!ENTITY implicit-cache "<literal>--implicit-cache</literal>">
@@ -180,6 +181,7 @@
 <!ENTITY Depends "<function>Depends</function>">
 <!ENTITY Dir "<function>Dir</function>">
 <!ENTITY Dump "<function>Dump</function>">
+<!ENTITY Duplicate "<function>Duplicate</function>">
 <!ENTITY Entry "<function>Entry</function>">
 <!ENTITY EnumOption "<function>EnumOption</function>">
 <!ENTITY EnumVariable "<function>EnumVariable</function>">
diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST
index ef273d3..0994f2b 100644
--- a/doc/user/MANIFEST
+++ b/doc/user/MANIFEST
@@ -17,6 +17,7 @@ errors.xml
 example.xml
 factories.xml
 file-removal.xml
+functions.xml
 hierarchy.xml
 install.xml
 java.xml
diff --git a/doc/user/README b/doc/user/README
index 773fbc2..7ebdb93 100644
--- a/doc/user/README
+++ b/doc/user/README
@@ -1,4 +1,4 @@
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
 When adding a new file, add it to main.xml and MANIFEST.
 
diff --git a/doc/user/actions.in b/doc/user/actions.in
index 06dcd63..6634a0d 100644
--- a/doc/user/actions.in
+++ b/doc/user/actions.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/actions.xml b/doc/user/actions.xml
index 7231a70..a3cce98 100644
--- a/doc/user/actions.xml
+++ b/doc/user/actions.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/add-method.in b/doc/user/add-method.in
index a9595a9..815e0a7 100644
--- a/doc/user/add-method.in
+++ b/doc/user/add-method.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml
index 46f858d..6cb1a93 100644
--- a/doc/user/add-method.xml
+++ b/doc/user/add-method.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -113,6 +113,7 @@
     rc /fores.res res.rc
     cl /Fotest_stuff.obj /c test_stuff.c /nologo
     link /nologo /OUT:tests\test_stuff.exe test_stuff.obj res.res
+    embedManifestExeCheck(target, source, env)
   </screen>
 
   <para>
diff --git a/doc/user/alias.in b/doc/user/alias.in
index c17d76a..1fb7e30 100644
--- a/doc/user/alias.in
+++ b/doc/user/alias.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/alias.xml b/doc/user/alias.xml
index fed201f..8888f77 100644
--- a/doc/user/alias.xml
+++ b/doc/user/alias.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/ant.in b/doc/user/ant.in
index d39207d..2cc83a3 100644
--- a/doc/user/ant.in
+++ b/doc/user/ant.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/ant.xml b/doc/user/ant.xml
index d39207d..2cc83a3 100644
--- a/doc/user/ant.xml
+++ b/doc/user/ant.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/build-install.in b/doc/user/build-install.in
index 8d1c005..aad4a44 100644
--- a/doc/user/build-install.in
+++ b/doc/user/build-install.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -121,9 +121,10 @@
 
     <para>
 
-    &SCons; will work with any version of Python from 2.4 or later.
+    &SCons; will work with any 2.x version of Python from 2.4 on;
+    3.0 and later are not yet supported.
     If you need to install Python and have a choice,
-    we recommend using the most recent Python version available.
+    we recommend using the most recent 2.x Python version available.
     Newer Pythons have significant improvements
     that help speed up the performance of &SCons;.
 
@@ -198,7 +199,7 @@
       </para>
 
       <screen>
-        # <userinput>rpm -Uvh scons-2.0.1-1.noarch.rpm</userinput>
+        # <userinput>rpm -Uvh scons-2.1.0-1.noarch.rpm</userinput>
       </screen>
 
       <para>
@@ -260,7 +261,7 @@
 
       &SCons; provides a Windows installer
       that makes installation extremely easy.
-      Download the <filename>scons-2.0.1.win32.exe</filename>
+      Download the <filename>scons-2.1.0.win32.exe</filename>
       file from the &SCons; download page at
       <ulink url="http://www.scons.org/download.php">http://www.scons.org/download.php</ulink>.
       Then all you need to do is execute the file
@@ -370,8 +371,8 @@
     <para>
 
     The first step is to download either the
-    <filename>scons-2.0.1.tar.gz</filename>
-    or <filename>scons-2.0.1.zip</filename>,
+    <filename>scons-2.1.0.tar.gz</filename>
+    or <filename>scons-2.1.0.zip</filename>,
     which are available from the SCons download page at
     <ulink url="http://www.scons.org/download.html">http://www.scons.org/download.html</ulink>.
 
@@ -384,7 +385,7 @@
     on Linux or UNIX,
     or <application>WinZip</application> on Windows.
     This will create a directory called
-    <filename>scons-2.0.1</filename>,
+    <filename>scons-2.1.0</filename>,
     usually in your local directory.
     Then change your working directory to that directory
     and install &SCons; by executing the following commands:
@@ -392,7 +393,7 @@
     </para>
 
     <screen>
-      # <userinput>cd scons-2.0.1</userinput>
+      # <userinput>cd scons-2.1.0</userinput>
       # <userinput>python setup.py install</userinput>
     </screen>
 
@@ -460,9 +461,9 @@
 
       This will install the &SCons; build engine
       in the
-      <filename>/usr/lib/scons-2.0.1</filename>
+      <filename>/usr/lib/scons-2.1.0</filename>
       or
-      <filename>C:\Python25\scons-2.0.1</filename>
+      <filename>C:\Python25\scons-2.1.0</filename>
       directory, for example.
 
       </para>
@@ -519,7 +520,7 @@
       relative to the specified prefix.
       Adding <option>--version-lib</option> to the
       above example would install the build engine in
-      <filename>/opt/scons/lib/scons-2.0.1</filename>.
+      <filename>/opt/scons/lib/scons-2.1.0</filename>.
 
       </para>
 
diff --git a/doc/user/build-install.xml b/doc/user/build-install.xml
index 8d1c005..aad4a44 100644
--- a/doc/user/build-install.xml
+++ b/doc/user/build-install.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -121,9 +121,10 @@
 
     <para>
 
-    &SCons; will work with any version of Python from 2.4 or later.
+    &SCons; will work with any 2.x version of Python from 2.4 on;
+    3.0 and later are not yet supported.
     If you need to install Python and have a choice,
-    we recommend using the most recent Python version available.
+    we recommend using the most recent 2.x Python version available.
     Newer Pythons have significant improvements
     that help speed up the performance of &SCons;.
 
@@ -198,7 +199,7 @@
       </para>
 
       <screen>
-        # <userinput>rpm -Uvh scons-2.0.1-1.noarch.rpm</userinput>
+        # <userinput>rpm -Uvh scons-2.1.0-1.noarch.rpm</userinput>
       </screen>
 
       <para>
@@ -260,7 +261,7 @@
 
       &SCons; provides a Windows installer
       that makes installation extremely easy.
-      Download the <filename>scons-2.0.1.win32.exe</filename>
+      Download the <filename>scons-2.1.0.win32.exe</filename>
       file from the &SCons; download page at
       <ulink url="http://www.scons.org/download.php">http://www.scons.org/download.php</ulink>.
       Then all you need to do is execute the file
@@ -370,8 +371,8 @@
     <para>
 
     The first step is to download either the
-    <filename>scons-2.0.1.tar.gz</filename>
-    or <filename>scons-2.0.1.zip</filename>,
+    <filename>scons-2.1.0.tar.gz</filename>
+    or <filename>scons-2.1.0.zip</filename>,
     which are available from the SCons download page at
     <ulink url="http://www.scons.org/download.html">http://www.scons.org/download.html</ulink>.
 
@@ -384,7 +385,7 @@
     on Linux or UNIX,
     or <application>WinZip</application> on Windows.
     This will create a directory called
-    <filename>scons-2.0.1</filename>,
+    <filename>scons-2.1.0</filename>,
     usually in your local directory.
     Then change your working directory to that directory
     and install &SCons; by executing the following commands:
@@ -392,7 +393,7 @@
     </para>
 
     <screen>
-      # <userinput>cd scons-2.0.1</userinput>
+      # <userinput>cd scons-2.1.0</userinput>
       # <userinput>python setup.py install</userinput>
     </screen>
 
@@ -460,9 +461,9 @@
 
       This will install the &SCons; build engine
       in the
-      <filename>/usr/lib/scons-2.0.1</filename>
+      <filename>/usr/lib/scons-2.1.0</filename>
       or
-      <filename>C:\Python25\scons-2.0.1</filename>
+      <filename>C:\Python25\scons-2.1.0</filename>
       directory, for example.
 
       </para>
@@ -519,7 +520,7 @@
       relative to the specified prefix.
       Adding <option>--version-lib</option> to the
       above example would install the build engine in
-      <filename>/opt/scons/lib/scons-2.0.1</filename>.
+      <filename>/opt/scons/lib/scons-2.1.0</filename>.
 
       </para>
 
diff --git a/doc/user/builders-built-in.in b/doc/user/builders-built-in.in
index f7da806..d16e8c3 100644
--- a/doc/user/builders-built-in.in
+++ b/doc/user/builders-built-in.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/builders-built-in.xml b/doc/user/builders-built-in.xml
index 3d47f5c..39e0533 100644
--- a/doc/user/builders-built-in.xml
+++ b/doc/user/builders-built-in.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -160,6 +160,7 @@
       cl /Fogoodbye.obj /c goodbye.c /nologo
       cl /Fohello.obj /c hello.c /nologo
       link /nologo /OUT:hello.exe /LIBPATH:\usr\dir1 /LIBPATH:dir2 foo1.lib foo2.lib hello.obj goodbye.obj
+      embedManifestExeCheck(target, source, env)
     </screen>
 
     <para>
diff --git a/doc/user/builders-commands.in b/doc/user/builders-commands.in
index af3aec8..1082058 100644
--- a/doc/user/builders-commands.in
+++ b/doc/user/builders-commands.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -72,7 +72,7 @@
   <scons_example name="ex1">
      <file name="SConstruct" printme="1">
      env = Environment()
-     env.Command('foo.out', 'foo.in', "sed 's/x/y/' < $SOURCE > $TARGET")
+     env.Command('foo.out', 'foo.in', "sed 's/x/y/' &lt; $SOURCE > $TARGET")
      </file>
      <file name="foo.in">
      foo.in
diff --git a/doc/user/builders-commands.xml b/doc/user/builders-commands.xml
index 7e48660..e3066c6 100644
--- a/doc/user/builders-commands.xml
+++ b/doc/user/builders-commands.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in
index 0bf6971..addc837 100644
--- a/doc/user/builders-writing.in
+++ b/doc/user/builders-writing.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -823,7 +823,6 @@ This functionality could be invoked as in the following example:
         <file name="my_command" chmod="0755">
         cat
         </file>
-      </file>
 
     </scons_example>
 
@@ -842,7 +841,6 @@ This functionality could be invoked as in the following example:
                          MY_EMITTER = modify2)
       env1.Foo('file1')
       env2.Foo('file2')
-      </file>
     </sconstruct>
 
     <para>
@@ -899,8 +897,8 @@ This functionality could be invoked as in the following example:
 
     <para>
 
-    The <filename>site_scons</filename> directory gives you a place to
-    put Python modules you can import into your &SConscript; files
+    The <filename>site_scons</filename> directories give you a place to
+    put Python modules and packages that you can import into your &SConscript; files
     (<filename>site_scons</filename>),
     add-on tools that can integrate into &SCons;
     (<filename>site_scons/site_tools</filename>),
@@ -912,11 +910,21 @@ This functionality could be invoked as in the following example:
 
     <para>
 
+    Each system type (Windows, Mac, Linux, etc.) searches a canonical
+    set of directories for site_scons; see the man page for details.
+    The top-level SConstruct's site_scons dir is always searched last,
+    and its dir is placed first in the tool path so it overrides all
+    others.
+
+    </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
+    for instance) and you'd like to use it in your project, a
     <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,
+    an &Environment; or a Python module or package  containing two functions,
     <function>exists()</function> and <function>generate()</function>.
 
     </para>
@@ -931,7 +939,7 @@ This functionality could be invoked as in the following example:
     </para>
 
     <scons_example name="site1">
-      <file name="site_scons/site_init.py" printme=1>
+      <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" &gt; $TARGET',
@@ -975,16 +983,23 @@ This functionality could be invoked as in the following example:
     -->
 
     <para>
-      Similarly, a more full-fledged tool with
+      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.
+      methods can be installed either as a module in the file
+      <filename>site_scons/site_tools/toolname.py</filename> or as a
+      package in the
+      directory <filename>site_scons/site_tools/toolname</filename>.  In
+      the case of using a package, the <function>exists()</function>
+      and <function>generate()</function> are in the
+      file <filename>site_scons/site_tools/toolname/__init__.py</filename>.
+      (In all the above case <filename>toolname</filename> is replaced
+      by the name of the tool.)
+      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, <filename>site_scons</filename> gives you the hook you need.
     </para>
 
     <para>
@@ -998,7 +1013,7 @@ This functionality could be invoked as in the following example:
     </para>
       
     <scons_example name="site2">
-      <file name="site_scons/my_utils.py" printme=1>
+      <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)"""
@@ -1047,13 +1062,15 @@ This functionality could be invoked as in the following example:
 
     <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.
+      You can use any of the user- or machine-wide site dirs such as
+      <filename>~/.scons/site_scons</filename> instead of
+      <filename>./site_scons</filename>, or use the
+      <literal>--site-dir</literal> option to point to your own 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.
+      To avoid using a <filename>site_scons</filename> dir at all,
+      even if it exists, use the <literal>--no-site-dir</literal>
+      option.
 
     </para>
 
diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml
index f364e27..d9bda79 100644
--- a/doc/user/builders-writing.xml
+++ b/doc/user/builders-writing.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -703,7 +703,6 @@ This functionality could be invoked as in the following example:
         import os
         env1['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd()
         env2['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd()
-      
 
     </programlisting>
 
@@ -722,7 +721,6 @@ This functionality could be invoked as in the following example:
                          MY_EMITTER = modify2)
       env1.Foo('file1')
       env2.Foo('file2')
-      
     </programlisting>
 
     <para>
@@ -781,8 +779,8 @@ This functionality could be invoked as in the following example:
 
     <para>
 
-    The <filename>site_scons</filename> directory gives you a place to
-    put Python modules you can import into your &SConscript; files
+    The <filename>site_scons</filename> directories give you a place to
+    put Python modules and packages that you can import into your &SConscript; files
     (<filename>site_scons</filename>),
     add-on tools that can integrate into &SCons;
     (<filename>site_scons/site_tools</filename>),
@@ -794,11 +792,21 @@ This functionality could be invoked as in the following example:
 
     <para>
 
+    Each system type (Windows, Mac, Linux, etc.) searches a canonical
+    set of directories for site_scons; see the man page for details.
+    The top-level SConstruct's site_scons dir is always searched last,
+    and its dir is placed first in the tool path so it overrides all
+    others.
+
+    </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
+    for instance) and you'd like to use it in your project, a
     <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,
+    an &Environment; or a Python module or package  containing two functions,
     <function>exists()</function> and <function>generate()</function>.
 
     </para>
@@ -848,16 +856,23 @@ This functionality could be invoked as in the following example:
     -->
 
     <para>
-      Similarly, a more full-fledged tool with
+      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.
+      methods can be installed either as a module in the file
+      <filename>site_scons/site_tools/toolname.py</filename> or as a
+      package in the
+      directory <filename>site_scons/site_tools/toolname</filename>.  In
+      the case of using a package, the <function>exists()</function>
+      and <function>generate()</function> are in the
+      file <filename>site_scons/site_tools/toolname/__init__.py</filename>.
+      (In all the above case <filename>toolname</filename> is replaced
+      by the name of the tool.)
+      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, <filename>site_scons</filename> gives you the hook you need.
     </para>
 
     <para>
@@ -913,13 +928,15 @@ This functionality could be invoked as in the following example:
 
     <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.
+      You can use any of the user- or machine-wide site dirs such as
+      <filename>~/.scons/site_scons</filename> instead of
+      <filename>./site_scons</filename>, or use the
+      <literal>--site-dir</literal> option to point to your own 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.
+      To avoid using a <filename>site_scons</filename> dir at all,
+      even if it exists, use the <literal>--no-site-dir</literal>
+      option.
 
     </para>
 
diff --git a/doc/user/builders.in b/doc/user/builders.in
index 9e9b647..f2bf36d 100644
--- a/doc/user/builders.in
+++ b/doc/user/builders.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/builders.xml b/doc/user/builders.xml
index 9e9b647..f2bf36d 100644
--- a/doc/user/builders.xml
+++ b/doc/user/builders.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/caching.in b/doc/user/caching.in
index e5e2742..d60f067 100644
--- a/doc/user/caching.in
+++ b/doc/user/caching.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/caching.xml b/doc/user/caching.xml
index 5a64e7d..c3dae0a 100644
--- a/doc/user/caching.xml
+++ b/doc/user/caching.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/command-line.in b/doc/user/command-line.in
index cd5ead6..52a61ac 100644
--- a/doc/user/command-line.in
+++ b/doc/user/command-line.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -221,7 +221,7 @@
 
       </para>
 
-      <sconstruct)
+      <sconstruct>
         if not GetOption('help'):
             SConscript('src/SConscript', export='env')
       </sconstruct>
@@ -2195,7 +2195,7 @@
 
         Second,
         the contents of the &DEFAULT_TARGETS; list change
-        in response to calls to the &Default: function,
+        in response to calls to the &Default; function,
         as you can see from the following &SConstruct; file:
 
         </para>
diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml
index 8bc72bb..f06442e 100644
--- a/doc/user/command-line.xml
+++ b/doc/user/command-line.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -214,7 +214,10 @@
 
       </para>
 
-      <programlisting></programlisting>
+      <programlisting>
+        if not GetOption('help'):
+            SConscript('src/SConscript', export='env')
+      </programlisting>
 
       <para>
 
@@ -1252,7 +1255,7 @@
         <screen>
           % <userinput>scons -Q COLOR=magenta foo.o</userinput>
           
-          scons: *** Invalid value for option COLOR: magenta
+          scons: *** Invalid value for option COLOR: magenta.  Valid values are: ('red', 'green', 'blue')
           File "/home/my/project/SConstruct", line 5, in &lt;module&gt;
         </screen>
 
@@ -1308,15 +1311,15 @@
         <screen>
           % <userinput>scons -Q COLOR=Red foo.o</userinput>
           
-          scons: *** Invalid value for option COLOR: Red
+          scons: *** Invalid value for option COLOR: Red.  Valid values are: ('red', 'green', 'blue')
           File "/home/my/project/SConstruct", line 5, in &lt;module&gt;
           % <userinput>scons -Q COLOR=BLUE foo.o</userinput>
           
-          scons: *** Invalid value for option COLOR: BLUE
+          scons: *** Invalid value for option COLOR: BLUE.  Valid values are: ('red', 'green', 'blue')
           File "/home/my/project/SConstruct", line 5, in &lt;module&gt;
           % <userinput>scons -Q COLOR=nAvY foo.o</userinput>
           
-          scons: *** Invalid value for option COLOR: nAvY
+          scons: *** Invalid value for option COLOR: nAvY.  Valid values are: ('red', 'green', 'blue')
           File "/home/my/project/SConstruct", line 5, in &lt;module&gt;
         </screen>
 
@@ -2107,7 +2110,7 @@
 
         Second,
         the contents of the &DEFAULT_TARGETS; list change
-        in response to calls to the &Default;: function,
+        in response to calls to the &Default; function,
         as you can see from the following &SConstruct; file:
 
         </para>
diff --git a/doc/user/copyright.in b/doc/user/copyright.in
index 8b90dbc..19689fe 100644
--- a/doc/user/copyright.in
+++ b/doc/user/copyright.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/copyright.xml b/doc/user/copyright.xml
index 8b90dbc..19689fe 100644
--- a/doc/user/copyright.xml
+++ b/doc/user/copyright.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/depends.in b/doc/user/depends.in
index 69bb242..190670c 100644
--- a/doc/user/depends.in
+++ b/doc/user/depends.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -386,7 +386,7 @@
 
       <para>
 
-      So configured, &SCons will still behave like
+      So configured, &SCons; will still behave like
       it does when using <literal>Decider('MD5')</literal>:
 
       </para>
@@ -487,7 +487,7 @@
       only its section of the input file.
       However, since the input file may contain a lot of data,
       we want to open the input file only if its timestamp has changed.
-      This could done with a custom
+      This could be done with a custom
       &Decider; function that might look something like this:
 
       </para>
@@ -591,6 +591,59 @@
 
       </para>
 
+      <para>
+
+      Another thing to look out for, is the fact that the three
+      attributes above may not be present at the time of the first run.
+      Without any prior build, no targets got created and no
+      <filename>.sconsign</filename> DB file exists yet.
+      So, it is recommended to always check whether the
+      <varname>prev_ni</varname> attribute in question is available.
+
+      </para>
+
+      <para>
+
+      We finally present a small example for a
+      <varname>csig</varname>-based decider function. Note how the
+      signature information for the <varname>dependency</varname> file
+      has to get initialized via <function>get_csig</function>
+      during each function call (this is mandatory!).
+
+      </para>
+
+      <sconstruct>
+        env = Environment()
+        
+        def config_file_decider(dependency, target, prev_ni):
+            import os.path
+        
+            # We always have to init the .csig value...
+            dep_csig = dependency.get_csig()
+            # .csig may not exist, because no target was built yet...
+            if 'csig' not in dir(prev_ni):
+                return True
+            # Target file may not exist yet
+            if not os.path.exists(str(target.abspath)):
+                return True
+            if dep_csig != prev_ni.csig:
+                # Some change on source file => update installed one
+                return True
+            return False
+        
+        def update_file():
+            f = open("test.txt","a")
+            f.write("some line\n")
+            f.close()
+            
+        update_file()
+        
+        # Activate our own decider function
+        env.Decider(config_file_decider)
+        
+        env.Install("install","test.txt")
+      </sconstruct>
+
     </section>
 
     <section>
@@ -861,7 +914,7 @@
 
   </section>
 
-  <section>
+  <section id="sect-implicit-dependencies">
   <title>Implicit Dependencies:  The &cv-CPPPATH; Construction Variable</title>
 
     <para>
diff --git a/doc/user/depends.xml b/doc/user/depends.xml
index 430e64a..5b19220 100644
--- a/doc/user/depends.xml
+++ b/doc/user/depends.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -488,7 +488,7 @@
       only its section of the input file.
       However, since the input file may contain a lot of data,
       we want to open the input file only if its timestamp has changed.
-      This could done with a custom
+      This could be done with a custom
       &Decider; function that might look something like this:
 
       </para>
@@ -587,6 +587,59 @@
 
       </para>
 
+      <para>
+
+      Another thing to look out for, is the fact that the three
+      attributes above may not be present at the time of the first run.
+      Without any prior build, no targets got created and no
+      <filename>.sconsign</filename> DB file exists yet.
+      So, it is recommended to always check whether the
+      <varname>prev_ni</varname> attribute in question is available.
+
+      </para>
+
+      <para>
+
+      We finally present a small example for a
+      <varname>csig</varname>-based decider function. Note how the
+      signature information for the <varname>dependency</varname> file
+      has to get initialized via <function>get_csig</function>
+      during each function call (this is mandatory!).
+
+      </para>
+
+      <programlisting>
+        env = Environment()
+        
+        def config_file_decider(dependency, target, prev_ni):
+            import os.path
+        
+            # We always have to init the .csig value...
+            dep_csig = dependency.get_csig()
+            # .csig may not exist, because no target was built yet...
+            if 'csig' not in dir(prev_ni):
+                return True
+            # Target file may not exist yet
+            if not os.path.exists(str(target.abspath)):
+                return True
+            if dep_csig != prev_ni.csig:
+                # Some change on source file =&gt; update installed one
+                return True
+            return False
+        
+        def update_file():
+            f = open("test.txt","a")
+            f.write("some line\n")
+            f.close()
+            
+        update_file()
+        
+        # Activate our own decider function
+        env.Decider(config_file_decider)
+        
+        env.Install("install","test.txt")
+      </programlisting>
+
     </section>
 
     <section>
@@ -850,7 +903,7 @@
 
   </section>
 
-  <section>
+  <section id="sect-implicit-dependencies">
   <title>Implicit Dependencies:  The &cv-CPPPATH; Construction Variable</title>
 
     <para>
@@ -989,6 +1042,7 @@
        C:\><userinput>scons -Q hello.exe</userinput>
        cl /Fohello.obj /c hello.c /nologo /Iinclude /I\home\project\inc
        link /nologo /OUT:hello.exe hello.obj
+       embedManifestExeCheck(target, source, env)
     </screen>
 
   </section>
diff --git a/doc/user/environments.in b/doc/user/environments.in
index 9ce5568..ecfea8a 100644
--- a/doc/user/environments.in
+++ b/doc/user/environments.in
@@ -1,6 +1,6 @@
 <!--
 
-     Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+     Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
      Permission is hereby granted, free of charge, to any person obtaining
      a copy of this software and associated documentation files (the
@@ -347,7 +347,7 @@ environment, of directory names, suffixes, etc.
 
     The <literal>external environment</literal>
     is the set of variables in the user's environment
-    at the time the user runs &SCons.
+    at the time the user runs &SCons;.
     These variables are available within the &SConscript; files
     through the Python <literal>os.environ</literal> dictionary.
     See <xref linkend="sect-external-environments"></xref>, below.
@@ -406,7 +406,7 @@ environment, of directory names, suffixes, etc.
 
   Unlike &Make;,  &SCons; does not automatically
   copy or import values between different environments
-  (with the exception of explicit clones of &consenvs,
+  (with the exception of explicit clones of &consenvs;,
   which inherit values from their parent).
   This is a deliberate design choice
   to make sure that builds are,
@@ -638,7 +638,7 @@ environment, of directory names, suffixes, etc.
          for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']:
              print "key = %s, value = %s" % (key, dict[key])
          </file>
-      </scons_Example>
+      </scons_example>
 
       <para>
 
@@ -779,18 +779,20 @@ environment, of directory names, suffixes, etc.
       If a problem occurs when expanding a construction variable,
       by default it is expanded to <literal>''</literal>
       (a null string), and will not cause scons to fail. 
-      
+      </para>
+
        <scons_example name="missing1">
          <file name="SConstruct" printme="1">
           env = Environment()
-          print "value is:", env.subst( '->$MISSING<-' )
+          print "value is:", env.subst( '->$MISSING&lt;-' )
         </file>
       </scons_example>
 
        <scons_output example="missing1">
           <scons_output_command>scons -Q</scons_output_command>
        </scons_output>
-      
+
+      <para>
       This default behaviour can be changed using the &AllowSubstExceptions;
       function.
       When a problem occurs with a variable expansion it generates
@@ -810,7 +812,7 @@ environment, of directory names, suffixes, etc.
          <file name="SConstruct" printme="1">
           AllowSubstExceptions()
           env = Environment()
-          print "value is:", env.subst( '->$MISSING<-' )
+          print "value is:", env.subst( '->$MISSING&lt;-' )
         </file>
       </scons_example>
 
@@ -830,7 +832,7 @@ environment, of directory names, suffixes, etc.
          <file name="SConstruct" printme="1">
           AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
           env = Environment()
-          print "value is:", env.subst( '->${1 / 0}<-' )
+          print "value is:", env.subst( '->${1 / 0}&lt;-' )
         </file>
       </scons_example>
 
@@ -1093,7 +1095,7 @@ environment, of directory names, suffixes, etc.
 
     </section>
 
-    <section>
+    <section id="sect-clone-environments">
     <title>Making Copies of &ConsEnvs;:  the &Clone; Method</title>
 
       <para>
diff --git a/doc/user/environments.xml b/doc/user/environments.xml
index 5bb1089..81f43a4 100644
--- a/doc/user/environments.xml
+++ b/doc/user/environments.xml
@@ -1,6 +1,6 @@
 <!--
 
-     Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+     Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
      Permission is hereby granted, free of charge, to any person obtaining
      a copy of this software and associated documentation files (the
@@ -779,7 +779,8 @@ environment, of directory names, suffixes, etc.
       If a problem occurs when expanding a construction variable,
       by default it is expanded to <literal>''</literal>
       (a null string), and will not cause scons to fail. 
-      
+      </para>
+
        <programlisting>
           env = Environment()
           print "value is:", env.subst( '-&gt;$MISSING&lt;-' )
@@ -790,7 +791,8 @@ environment, of directory names, suffixes, etc.
           value is: -&gt;&lt;-
           scons: `.' is up to date.
        </screen>
-      
+
+      <para>
       This default behaviour can be changed using the &AllowSubstExceptions;
       function.
       When a problem occurs with a variable expansion it generates
@@ -1087,7 +1089,7 @@ environment, of directory names, suffixes, etc.
 
     </section>
 
-    <section>
+    <section id="sect-clone-environments">
     <title>Making Copies of &ConsEnvs;:  the &Clone; Method</title>
 
       <para>
diff --git a/doc/user/errors.in b/doc/user/errors.in
index ad4c2ef..7e33118 100644
--- a/doc/user/errors.in
+++ b/doc/user/errors.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/errors.xml b/doc/user/errors.xml
index ad4c2ef..7e33118 100644
--- a/doc/user/errors.xml
+++ b/doc/user/errors.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/example.in b/doc/user/example.in
index ad4c2ef..7e33118 100644
--- a/doc/user/example.in
+++ b/doc/user/example.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/example.xml b/doc/user/example.xml
index ad4c2ef..7e33118 100644
--- a/doc/user/example.xml
+++ b/doc/user/example.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/factories.in b/doc/user/factories.in
index c0f524d..da92082 100644
--- a/doc/user/factories.in
+++ b/doc/user/factories.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -209,7 +209,7 @@
     <para>
 
     Of course, like all of these &Action; factories,
-    the &Delete factory also expands
+    the &Delete; factory also expands
     &cv-link-TARGET; and &cv-link-SOURCE; variables appropriately.
     For example:
 
diff --git a/doc/user/factories.xml b/doc/user/factories.xml
index 6a92b0c..7f51c8d 100644
--- a/doc/user/factories.xml
+++ b/doc/user/factories.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/file-removal.in b/doc/user/file-removal.in
index 1b12d35..b664ba0 100644
--- a/doc/user/file-removal.in
+++ b/doc/user/file-removal.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/file-removal.xml b/doc/user/file-removal.xml
index 92c1c0d..47b081a 100644
--- a/doc/user/file-removal.xml
+++ b/doc/user/file-removal.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/functions.in b/doc/user/functions.in
new file mode 100644
index 0000000..7c96c54
--- /dev/null
+++ b/doc/user/functions.in
@@ -0,0 +1,38 @@
+<!--
+
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  "Software"), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+<para>
+
+This appendix contains descriptions of all of the
+function and construction environment methods
+in this version of &SCons;
+
+</para>
+
+<variablelist>
+
+&functions-gen;
+
+</variablelist>
diff --git a/doc/user/functions.xml b/doc/user/functions.xml
new file mode 100644
index 0000000..7c96c54
--- /dev/null
+++ b/doc/user/functions.xml
@@ -0,0 +1,38 @@
+<!--
+
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  "Software"), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+<para>
+
+This appendix contains descriptions of all of the
+function and construction environment methods
+in this version of &SCons;
+
+</para>
+
+<variablelist>
+
+&functions-gen;
+
+</variablelist>
diff --git a/doc/user/hierarchy.in b/doc/user/hierarchy.in
index 16d9389..950bc8a 100644
--- a/doc/user/hierarchy.in
+++ b/doc/user/hierarchy.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -478,7 +478,7 @@ make no difference to the build.
 
   </section>
 
-  <section>
+  <section id="sect-sharing-environments">
   <title>Sharing Environments (and Other Variables) Between &SConscript; Files</title>
 
     <para>
@@ -688,7 +688,7 @@ make no difference to the build.
 
       Sometimes, you would like to be able to
       use information from a subsidiary
-      &SConscript file in some way.
+      &SConscript; file in some way.
       For example,
       suppose that you want to create one
       library from source files
diff --git a/doc/user/hierarchy.xml b/doc/user/hierarchy.xml
index bc4073e..6691e70 100644
--- a/doc/user/hierarchy.xml
+++ b/doc/user/hierarchy.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -442,7 +442,7 @@ make no difference to the build.
 
   </section>
 
-  <section>
+  <section id="sect-sharing-environments">
   <title>Sharing Environments (and Other Variables) Between &SConscript; Files</title>
 
     <para>
diff --git a/doc/user/install.in b/doc/user/install.in
index 8f9498e..131fc6a 100644
--- a/doc/user/install.in
+++ b/doc/user/install.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/install.xml b/doc/user/install.xml
index f119b00..6b49ae8 100644
--- a/doc/user/install.xml
+++ b/doc/user/install.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/java.in b/doc/user/java.in
index 290cd43..bad5c34 100644
--- a/doc/user/java.in
+++ b/doc/user/java.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -390,7 +390,7 @@
     You can generate C header and source files
     for implementing native methods,
     by using the &b-link-JavaH; Builder.
-    There are several ways of using the &JavaH Builder.
+    There are several ways of using the &JavaH; Builder.
     One typical invocation might look like:
 
     </para>
@@ -636,7 +636,7 @@
     As it did with the &b-link-JavaH; Builder,
     &SCons; remembers the class directory
     and passes it as the <option>-classpath</option> option
-    to &rmic:
+    to &rmic;:
 
     </para>
 
diff --git a/doc/user/java.xml b/doc/user/java.xml
index a0544f7..f277558 100644
--- a/doc/user/java.xml
+++ b/doc/user/java.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/less-simple.in b/doc/user/less-simple.in
index cccad83..d717014 100644
--- a/doc/user/less-simple.in
+++ b/doc/user/less-simple.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/less-simple.xml b/doc/user/less-simple.xml
index 24b45e6..e269490 100644
--- a/doc/user/less-simple.xml
+++ b/doc/user/less-simple.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -102,6 +102,7 @@
        C:\><userinput>scons -Q</userinput>
        cl /Fohello.obj /c hello.c /nologo
        link /nologo /OUT:new_hello.exe hello.obj
+       embedManifestExeCheck(target, source, env)
     </screen>
 
   </section>
@@ -193,6 +194,7 @@
        cl /Fofile2.obj /c file2.c /nologo
        cl /Foprog.obj /c prog.c /nologo
        link /nologo /OUT:program.exe prog.obj file1.obj file2.obj
+       embedManifestExeCheck(target, source, env)
     </screen>
 
   </section>
diff --git a/doc/user/libraries.in b/doc/user/libraries.in
index 5b449e7..a56f2c3 100644
--- a/doc/user/libraries.in
+++ b/doc/user/libraries.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/libraries.xml b/doc/user/libraries.xml
index 3eed3cc..6909758 100644
--- a/doc/user/libraries.xml
+++ b/doc/user/libraries.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -206,6 +206,7 @@
         cl /Fof3.obj /c f3.c /nologo
         link /nologo /dll /out:foo.dll /implib:foo.lib f1.obj f2.obj f3.obj
         RegServerFunc(target, source, env)
+        embedManifestDllCheck(target, source, env)
       </screen>
 
       <para>
@@ -288,6 +289,7 @@
       lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj
       cl /Foprog.obj /c prog.c /nologo
       link /nologo /OUT:prog.exe /LIBPATH:. foo.lib bar.lib prog.obj
+      embedManifestExeCheck(target, source, env)
     </screen>
 
     <para>
@@ -412,6 +414,7 @@
       C:\><userinput>scons -Q</userinput>
       cl /Foprog.obj /c prog.c /nologo
       link /nologo /OUT:prog.exe /LIBPATH:\usr\lib /LIBPATH:\usr\local\lib m.lib prog.obj
+      embedManifestExeCheck(target, source, env)
     </screen>
     <!-- The link command is too wide in the PDF version. 
          There are some other examples of this throughout the document. -->
diff --git a/doc/user/main.in b/doc/user/main.in
index fbc28df..feb8c25 100644
--- a/doc/user/main.in
+++ b/doc/user/main.in
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -37,6 +37,9 @@
     <!ENTITY % builders-mod SYSTEM "builders.mod">
     %builders-mod;
 
+    <!ENTITY % functions-mod SYSTEM "functions.mod">
+    %functions-mod;
+
     <!ENTITY % tools-mod SYSTEM "tools.mod">
     %tools-mod;
 
@@ -61,6 +64,7 @@
     <!ENTITY example SYSTEM "example.xml">
     <!ENTITY factories SYSTEM "factories.xml">
     <!ENTITY file-removal SYSTEM "file-removal.xml">
+    <!ENTITY functions SYSTEM "functions.xml">
     <!ENTITY hierarchy SYSTEM "hierarchy.xml">
     <!ENTITY java SYSTEM "java.xml">
     <!ENTITY install SYSTEM "install.xml">
@@ -89,6 +93,7 @@
     <!ENTITY variants SYSTEM "variants.xml">
 
     <!ENTITY builders-gen SYSTEM "builders.gen">
+    <!ENTITY functions-gen SYSTEM "functions.gen">
     <!ENTITY tools-gen SYSTEM "tools.gen">
     <!ENTITY variables-gen SYSTEM "variables.gen">
 
@@ -177,18 +182,35 @@
     &environments;
   </chapter>
 
-  <!-- These next three sections should be combined into one chapter -->
-  <chapter id="chap-mergeflags">
-    <title>Merging Options into the Environment: the &MergeFlags; Function</title>
-    &mergeflags;
-  </chapter>
-  <chapter id="chap-parseflags">
-    <title>Separating Compile Arguments into their Variables:  the &ParseFlags; Function</title>
-    &parseflags;
-  </chapter>
-  <chapter id="chap-parseconfig">
-    <title>Finding Installed Library Information:  the &ParseConfig; Function</title>
-    &parseconfig;
+  <chapter id="chap-manip-options">
+    <title>Automatically Putting Command-line Options into their Construction Variables</title>
+    <!-- TODO:  This intro paragraph should describe at a high-level
+    what these things do.  People are likely to use the intro as a
+    (brief) overview of *what* these functions do to decide if this
+    chapter is where they should read in more detail.  -->
+    <para>
+    This chapter describes the &MergeFlags;, &ParseFlags;, and &ParseConfig; methods of a &consenv;.
+    </para>
+    <section id="sect-mergeflags">
+      <title>Merging Options into the Environment: the &MergeFlags; Function</title>
+      &mergeflags;
+    </section>
+    <section id="sect-parseflags">
+      <title>Separating Compile Arguments into their Variables: the &ParseFlags; Function</title>
+      &parseflags;
+    </section>
+    <section id="sect-parseconfig">
+      <title>Finding Installed Library Information: the &ParseConfig; Function</title>
+      &parseconfig;
+    </section>
+    <!--
+    XXX parse_flags= option of Environment()
+
+    <section id="sect-env-parseflags">
+      <title>Adding Flags when Constructing Enviroment: the parse_flags Optional Argument</title>
+      &envparseflags;
+    </section>
+    -->
   </chapter>
 
   <chapter id="chap-output">
@@ -341,6 +363,11 @@
     &tools;
   </appendix>
 
+  <appendix id="app-functions">
+    <title>Functions and Environment Methods</title>
+    &functions;
+  </appendix>
+
   <appendix id="app-tasks">
     <title>Handling Common Tasks</title>
     &tasks;
diff --git a/doc/user/main.xml b/doc/user/main.xml
index fbc28df..feb8c25 100644
--- a/doc/user/main.xml
+++ b/doc/user/main.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -37,6 +37,9 @@
     <!ENTITY % builders-mod SYSTEM "builders.mod">
     %builders-mod;
 
+    <!ENTITY % functions-mod SYSTEM "functions.mod">
+    %functions-mod;
+
     <!ENTITY % tools-mod SYSTEM "tools.mod">
     %tools-mod;
 
@@ -61,6 +64,7 @@
     <!ENTITY example SYSTEM "example.xml">
     <!ENTITY factories SYSTEM "factories.xml">
     <!ENTITY file-removal SYSTEM "file-removal.xml">
+    <!ENTITY functions SYSTEM "functions.xml">
     <!ENTITY hierarchy SYSTEM "hierarchy.xml">
     <!ENTITY java SYSTEM "java.xml">
     <!ENTITY install SYSTEM "install.xml">
@@ -89,6 +93,7 @@
     <!ENTITY variants SYSTEM "variants.xml">
 
     <!ENTITY builders-gen SYSTEM "builders.gen">
+    <!ENTITY functions-gen SYSTEM "functions.gen">
     <!ENTITY tools-gen SYSTEM "tools.gen">
     <!ENTITY variables-gen SYSTEM "variables.gen">
 
@@ -177,18 +182,35 @@
     &environments;
   </chapter>
 
-  <!-- These next three sections should be combined into one chapter -->
-  <chapter id="chap-mergeflags">
-    <title>Merging Options into the Environment: the &MergeFlags; Function</title>
-    &mergeflags;
-  </chapter>
-  <chapter id="chap-parseflags">
-    <title>Separating Compile Arguments into their Variables:  the &ParseFlags; Function</title>
-    &parseflags;
-  </chapter>
-  <chapter id="chap-parseconfig">
-    <title>Finding Installed Library Information:  the &ParseConfig; Function</title>
-    &parseconfig;
+  <chapter id="chap-manip-options">
+    <title>Automatically Putting Command-line Options into their Construction Variables</title>
+    <!-- TODO:  This intro paragraph should describe at a high-level
+    what these things do.  People are likely to use the intro as a
+    (brief) overview of *what* these functions do to decide if this
+    chapter is where they should read in more detail.  -->
+    <para>
+    This chapter describes the &MergeFlags;, &ParseFlags;, and &ParseConfig; methods of a &consenv;.
+    </para>
+    <section id="sect-mergeflags">
+      <title>Merging Options into the Environment: the &MergeFlags; Function</title>
+      &mergeflags;
+    </section>
+    <section id="sect-parseflags">
+      <title>Separating Compile Arguments into their Variables: the &ParseFlags; Function</title>
+      &parseflags;
+    </section>
+    <section id="sect-parseconfig">
+      <title>Finding Installed Library Information: the &ParseConfig; Function</title>
+      &parseconfig;
+    </section>
+    <!--
+    XXX parse_flags= option of Environment()
+
+    <section id="sect-env-parseflags">
+      <title>Adding Flags when Constructing Enviroment: the parse_flags Optional Argument</title>
+      &envparseflags;
+    </section>
+    -->
   </chapter>
 
   <chapter id="chap-output">
@@ -341,6 +363,11 @@
     &tools;
   </appendix>
 
+  <appendix id="app-functions">
+    <title>Functions and Environment Methods</title>
+    &functions;
+  </appendix>
+
   <appendix id="app-tasks">
     <title>Handling Common Tasks</title>
     &tasks;
diff --git a/doc/user/make.in b/doc/user/make.in
index c17b047..7102557 100644
--- a/doc/user/make.in
+++ b/doc/user/make.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/make.xml b/doc/user/make.xml
index c17b047..7102557 100644
--- a/doc/user/make.xml
+++ b/doc/user/make.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/mergeflags.in b/doc/user/mergeflags.in
index 58d437c..086d042 100644
--- a/doc/user/mergeflags.in
+++ b/doc/user/mergeflags.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/mergeflags.xml b/doc/user/mergeflags.xml
index ab10e54..f0bc2b6 100644
--- a/doc/user/mergeflags.xml
+++ b/doc/user/mergeflags.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/misc.in b/doc/user/misc.in
index 87b5db4..fef1b8f 100644
--- a/doc/user/misc.in
+++ b/doc/user/misc.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -36,7 +36,7 @@
     <para>
 
     Although the &SCons; code itself will run 
-    on any Python version 2.4 or later,
+    on any 2.x Python version 2.4 or later,
     you are perfectly free to make use of
     Python syntax and modules from more modern versions
     (for example, Python 2.5 or 2.6)
@@ -82,7 +82,7 @@
 
     <para>
 
-    And then &SCons will exit with the following error
+    And then &SCons; will exit with the following error
     message when a user runs it with an unsupported
     earlier version of Python:
 
@@ -151,7 +151,7 @@
 
     <para>
 
-    And then &SCons will exit with the following error
+    And then &SCons; will exit with the following error
     message when a user runs it with an unsupported
     earlier version of &SCons;:
 
@@ -274,13 +274,13 @@
       </file>
       <directory name="src"></directory>
       <directory name="src/include"></directory>
-      </file>
       <file name="src/include/private.h">
         exists
-      <directory name="include"></directory>
       </file>
+      <directory name="include"></directory>
       <file name="include/dist.h">
         exists
+      </file>
     </scons_example>
 
     <scons_output example="FindFile1b" os="posix">
diff --git a/doc/user/misc.xml b/doc/user/misc.xml
index f79f1cc..069f94b 100644
--- a/doc/user/misc.xml
+++ b/doc/user/misc.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -36,7 +36,7 @@
     <para>
 
     Although the &SCons; code itself will run 
-    on any Python version 2.4 or later,
+    on any 2.x Python version 2.4 or later,
     you are perfectly free to make use of
     Python syntax and modules from more modern versions
     (for example, Python 2.5 or 2.6)
@@ -263,7 +263,7 @@
        headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h']
        for hdr in headers:
            print '%-12s' % ('%s:' % hdr), FindFile(hdr, includes)
-</programlisting>
+    </programlisting>
 
     <screen>
        % <userinput>scons -Q</userinput>
diff --git a/doc/user/nodes.in b/doc/user/nodes.in
index c65a2ad..7799d3f 100644
--- a/doc/user/nodes.in
+++ b/doc/user/nodes.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/nodes.xml b/doc/user/nodes.xml
index 71ac7c1..fe8e167 100644
--- a/doc/user/nodes.xml
+++ b/doc/user/nodes.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -131,6 +131,7 @@
        cl /Fogoodbye.obj /c goodbye.c -DGOODBYE
        cl /Fohello.obj /c hello.c -DHELLO
        link /nologo /OUT:hello.exe hello.obj goodbye.obj
+       embedManifestExeCheck(target, source, env)
     </screen>
 
     <para>
@@ -275,6 +276,7 @@
       The program file is: hello.exe
       cl /Fohello.obj /c hello.c /nologo
       link /nologo /OUT:hello.exe hello.obj
+      embedManifestExeCheck(target, source, env)
     </screen>
 
     <para>
diff --git a/doc/user/output.in b/doc/user/output.in
index e456026..d2823d0 100644
--- a/doc/user/output.in
+++ b/doc/user/output.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -490,7 +490,7 @@
     over how to print each evaluated node
     by passing a Python function
     (or other Python callable)
-    to the &Progress function.
+    to the &Progress; function.
     Your function will be called
     for each evaluated node,
     allowing you to
diff --git a/doc/user/output.xml b/doc/user/output.xml
index 297e6f8..6910b59 100644
--- a/doc/user/output.xml
+++ b/doc/user/output.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/parseconfig.in b/doc/user/parseconfig.in
index 667601f..5eb990c 100644
--- a/doc/user/parseconfig.in
+++ b/doc/user/parseconfig.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/parseconfig.xml b/doc/user/parseconfig.xml
index 534ea3d..409abfe 100644
--- a/doc/user/parseconfig.xml
+++ b/doc/user/parseconfig.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/parseflags.in b/doc/user/parseflags.in
index 2f4bea5..6e72c18 100644
--- a/doc/user/parseflags.in
+++ b/doc/user/parseflags.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/parseflags.xml b/doc/user/parseflags.xml
index fd15de7..7350831 100644
--- a/doc/user/parseflags.xml
+++ b/doc/user/parseflags.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -91,6 +91,7 @@
     LIBS ['foo']
     cl /Fof1.obj /c f1.c /nologo /I\opt\include
     link /nologo /OUT:f1.exe /LIBPATH:\opt\lib foo.lib f1.obj
+    embedManifestExeCheck(target, source, env)
  </screen>
 
  <para>
diff --git a/doc/user/preface.in b/doc/user/preface.in
index a60beab..e82ee3b 100644
--- a/doc/user/preface.in
+++ b/doc/user/preface.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -104,7 +104,7 @@
     <para>
 
     There are a few overriding principles
-    we try to live up to in designing and implementing &SCons:
+    we try to live up to in designing and implementing &SCons;:
 
     </para>
 
@@ -418,7 +418,7 @@
 
     <para>
 
-    If you want to receive announcements about &SCons,
+    If you want to receive announcements about &SCons;,
     join the low-volume &scons-announce; mailing list.
 
     </para>
diff --git a/doc/user/preface.xml b/doc/user/preface.xml
index db2031d..e82ee3b 100644
--- a/doc/user/preface.xml
+++ b/doc/user/preface.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/python.in b/doc/user/python.in
index 18679e4..c3ea5fe 100644
--- a/doc/user/python.in
+++ b/doc/user/python.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/python.xml b/doc/user/python.xml
index 18679e4..c3ea5fe 100644
--- a/doc/user/python.xml
+++ b/doc/user/python.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/repositories.in b/doc/user/repositories.in
index 531aa8a..5ba9090 100644
--- a/doc/user/repositories.in
+++ b/doc/user/repositories.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -210,9 +210,9 @@
     in the repository trees, though,
     it will be unable to find the <literal>#include</literal> files.
     If, for example, the &hello_c; file in
-    our previous example includes the &hello.h;
+    our previous example includes the &hello_h;
     in its current directory,
-    and the &hello.h; only exists in the repository:
+    and the &hello_h; only exists in the repository:
 
     </para>
 
diff --git a/doc/user/repositories.xml b/doc/user/repositories.xml
index 6400b23..219dbaf 100644
--- a/doc/user/repositories.xml
+++ b/doc/user/repositories.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -193,9 +193,9 @@
     in the repository trees, though,
     it will be unable to find the <literal>#include</literal> files.
     If, for example, the &hello_c; file in
-    our previous example includes the &hello;.h;
+    our previous example includes the &hello_h;
     in its current directory,
-    and the &hello;.h; only exists in the repository:
+    and the &hello_h; only exists in the repository:
 
     </para>
 
diff --git a/doc/user/run.in b/doc/user/run.in
index 761f37c..8d47b27 100644
--- a/doc/user/run.in
+++ b/doc/user/run.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/run.xml b/doc/user/run.xml
index 761f37c..8d47b27 100644
--- a/doc/user/run.xml
+++ b/doc/user/run.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/scanners.in b/doc/user/scanners.in
index db3170a..e8bdff7 100644
--- a/doc/user/scanners.in
+++ b/doc/user/scanners.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -171,10 +171,21 @@ over the file scanning rather than being called for each input line:
       
       def kfile_scan(node, env, path, arg):
           contents = node.get_text_contents()
-          return include_re.findall(contents)
+          return env.File(include_re.findall(contents))
     </programlisting>
 
     <para>
+    
+      It is important to note that you
+      have to return a list of File nodes from the scanner function, simple
+      strings for the file names won't do. As in the examples we are showing here,
+      you can use the &File;
+      function of your current Environment in order to create nodes on the fly from
+      a sequence of file names with relative paths.
+      
+    </para>
+
+    <para>
 
       The scanner function must
       accept the four specified arguments
@@ -283,7 +294,7 @@ over the file scanning rather than being called for each input line:
         def kfile_scan(node, env, path):
             contents = node.get_text_contents()
             includes = include_re.findall(contents)
-            return includes
+            return env.File(includes)
 
         kscan = Scanner(function = kfile_scan,
                         skeys = ['.k'])
diff --git a/doc/user/scanners.xml b/doc/user/scanners.xml
index 2aba7d2..7862265 100644
--- a/doc/user/scanners.xml
+++ b/doc/user/scanners.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -171,10 +171,21 @@ over the file scanning rather than being called for each input line:
       
       def kfile_scan(node, env, path, arg):
           contents = node.get_text_contents()
-          return include_re.findall(contents)
+          return env.File(include_re.findall(contents))
     </programlisting>
 
     <para>
+    
+      It is important to note that you
+      have to return a list of File nodes from the scanner function, simple
+      strings for the file names won't do. As in the examples we are showing here,
+      you can use the &File;
+      function of your current Environment in order to create nodes on the fly from
+      a sequence of file names with relative paths.
+      
+    </para>
+
+    <para>
 
       The scanner function must
       accept the four specified arguments
@@ -282,7 +293,7 @@ over the file scanning rather than being called for each input line:
         def kfile_scan(node, env, path):
             contents = node.get_text_contents()
             includes = include_re.findall(contents)
-            return includes
+            return env.File(includes)
 
         kscan = Scanner(function = kfile_scan,
                         skeys = ['.k'])
diff --git a/doc/user/sconf.in b/doc/user/sconf.in
index 94a455e..52fe132 100644
--- a/doc/user/sconf.in
+++ b/doc/user/sconf.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -31,7 +31,7 @@
   figuring out what libraries or header files
   are available on the local system.
   This section describes how to use
-  this &SCons feature.
+  this &SCons; feature.
 
   </para>
 
@@ -446,7 +446,7 @@
     when removing targets doesn't hurt anything,
     it's usually unnecessary.
     You can avoid this by using the
-    &GetOption(); method to
+    &GetOption; method to
     check whether the <option>-c</option> (clean)
     option has been invoked on the command line:
 
diff --git a/doc/user/sconf.xml b/doc/user/sconf.xml
index 35f4367..460c3d1 100644
--- a/doc/user/sconf.xml
+++ b/doc/user/sconf.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -446,7 +446,7 @@
     when removing targets doesn't hurt anything,
     it's usually unnecessary.
     You can avoid this by using the
-    &GetOption;(); method to
+    &GetOption; method to
     check whether the <option>-c</option> (clean)
     option has been invoked on the command line:
 
diff --git a/doc/user/separate.in b/doc/user/separate.in
index 8c08cbe..932c285 100644
--- a/doc/user/separate.in
+++ b/doc/user/separate.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/separate.xml b/doc/user/separate.xml
index 2c6f97b..7df53e9 100644
--- a/doc/user/separate.xml
+++ b/doc/user/separate.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/sideeffect.in b/doc/user/sideeffect.in
index 3356d6c..852f99a 100644
--- a/doc/user/sideeffect.in
+++ b/doc/user/sideeffect.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/sideeffect.xml b/doc/user/sideeffect.xml
index f6055f3..35e026f 100644
--- a/doc/user/sideeffect.xml
+++ b/doc/user/sideeffect.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/simple.in b/doc/user/simple.in
index b4802f8..0d15f12 100644
--- a/doc/user/simple.in
+++ b/doc/user/simple.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -297,7 +297,7 @@
 
  </section>
 
- <section>
+ <section id="sect-sconstruct-file">
  <title>The &SConstruct; File</title>
 
    <para>
@@ -353,14 +353,14 @@
 
    </section>
 
-   <section>
+   <section id="sect-order-independent">
    <title>&SCons; Functions Are Order-Independent</title>
 
      <para>
 
      One important way in which the &SConstruct;
      file is not exactly like a normal Python script,
-     and is more like a &Makefile,
+     and is more like a &Makefile;,
      is that the order in which
      the &SCons; functions are called in
      the &SConstruct; file
@@ -453,7 +453,7 @@
      <para>
 
      Notice also that &SCons; built the &goodbye; program first,
-     even though the "reading &SConscript" output
+     even though the "reading &SConscript;" output
      shows that we called <literal>Program('hello.c')</literal>
      first in the &SConstruct; file.
 
diff --git a/doc/user/simple.xml b/doc/user/simple.xml
index 54f6b56..49b8805 100644
--- a/doc/user/simple.xml
+++ b/doc/user/simple.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -110,6 +110,7 @@
       scons: Building targets ...
       cl /Fohello.obj /c hello.c /nologo
       link /nologo /OUT:hello.exe hello.obj
+      embedManifestExeCheck(target, source, env)
       scons: done building targets.
    </screen>
 
@@ -300,6 +301,7 @@
       scons: Building targets ...
       cl /Fohello.obj /c hello.c /nologo
       link /nologo /OUT:hello.exe hello.obj
+      embedManifestExeCheck(target, source, env)
       scons: done building targets.
       C:\><userinput>scons -c</userinput>
       scons: Reading SConscript files ...
@@ -320,7 +322,7 @@
 
  </section>
 
- <section>
+ <section id="sect-sconstruct-file">
  <title>The &SConstruct; File</title>
 
    <para>
@@ -376,7 +378,7 @@
 
    </section>
 
-   <section>
+   <section id="sect-order-independent">
    <title>&SCons; Functions Are Order-Independent</title>
 
      <para>
@@ -507,6 +509,7 @@
       scons: Building targets ...
       cl /Fohello.obj /c hello.c /nologo
       link /nologo /OUT:hello.exe hello.obj
+      embedManifestExeCheck(target, source, env)
       scons: done building targets.
    </screen>
 
@@ -536,6 +539,7 @@
       C:\><userinput>scons -Q</userinput>
       cl /Fohello.obj /c hello.c /nologo
       link /nologo /OUT:hello.exe hello.obj
+      embedManifestExeCheck(target, source, env)
    </screen>
 
    <para>
diff --git a/doc/user/sourcecode.in b/doc/user/sourcecode.in
index 5a9637e..e4fc5be 100644
--- a/doc/user/sourcecode.in
+++ b/doc/user/sourcecode.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/sourcecode.xml b/doc/user/sourcecode.xml
index 73c2490..6642d0f 100644
--- a/doc/user/sourcecode.xml
+++ b/doc/user/sourcecode.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/tasks.in b/doc/user/tasks.in
index 8842dcd..aa6a12e 100644
--- a/doc/user/tasks.in
+++ b/doc/user/tasks.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -99,14 +99,14 @@ env.Append(CPPPATH = "#")
 
 ## Header example
 env.Append(BUILDERS =
-   {'Copy1' : Builder(action = 'cat < $SOURCE > $TARGET',
+   {'Copy1' : Builder(action = 'cat &lt; $SOURCE > $TARGET',
                       suffix='.h', src_suffix='.bar')})
 env.Copy1('test.bar') # produces test.h from test.bar. 
 env.Program('app','main.cpp') # indirectly depends on test.bar
 
 ## Source file example
 env.Append(BUILDERS =
-  {'Copy2' : Builder(action = 'cat < $SOURCE > $TARGET',
+  {'Copy2' : Builder(action = 'cat &lt; $SOURCE > $TARGET',
                      suffix='.cpp', src_suffix='.bar2')})
 foo = env.Copy2('foo.bar2') # produces foo.cpp from foo.bar2. 
 env.Program('app2',['main2.cpp'] + foo) # compiles main2.cpp and foo.cpp into app2.
diff --git a/doc/user/tasks.xml b/doc/user/tasks.xml
index 2b2eb0b..ada4de5 100644
--- a/doc/user/tasks.xml
+++ b/doc/user/tasks.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/tools.in b/doc/user/tools.in
index 16228e7..9dd71df 100644
--- a/doc/user/tools.in
+++ b/doc/user/tools.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/tools.xml b/doc/user/tools.xml
index 16228e7..9dd71df 100644
--- a/doc/user/tools.xml
+++ b/doc/user/tools.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/troubleshoot.in b/doc/user/troubleshoot.in
index 97df351..615d677 100644
--- a/doc/user/troubleshoot.in
+++ b/doc/user/troubleshoot.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -34,7 +34,7 @@
   &SCons; is no different.
   This appendix contains a number of
   different ways in which you can
-  get some additional insight into &SCons' behavior.
+  get some additional insight into &SCons;' behavior.
 
   </para>
 
@@ -410,12 +410,12 @@
 
     <para>
 
-    The <literaL>--tree</literal> option only prints
+    The <literal>--tree</literal> option only prints
     the dependency graph for the specified targets
     (or the default target(s) if none are specified on the command line).
     So if you specify a target like <filename>f2.o</filename>
     on the command line,
-    the <literaL>--tree</literal> option will only
+    the <literal>--tree</literal> option will only
     print the dependency graph for that file:
 
     </para>
@@ -722,7 +722,7 @@
 
     <para>
 
-    For example, the following &SConstruct file:
+    For example, the following &SConstruct; file:
 
     </para>
 
@@ -842,8 +842,47 @@
 
   </section>
 
+  <section>
+
+  <title>Watch &SCons; prepare targets for building: the &debug-prepare; Option</title>
+
+    <para>
+
+    Sometimes SCons doesn't build the target you want
+    and it's difficult to figure out why.  You can use
+    the <literal>--debug=prepare</literal> option
+    to see all the targets &SCons; is considering, whether
+    they are already up-to-date or not. The message is
+    printed before &SCons; decides whether to build the target.
+    </para>
+
+  </section>
+
+  <section>
+
+  <title>Why is a file disappearing?  the --debug=duplicate Option</title>
+
+    <para>
+
+    When using the &Duplicate; option to create variant dirs,
+    sometimes you may find files not getting copied to where you
+    expect (or not at all), or files mysteriously disappearing.  These
+    are usually because of a misconfiguration of some kind in the
+    SConstruct/SConscript, but they can be tricky to debug.  The
+    --debug=duplicate option shows each time a variant file is
+    unlinked and relinked from its source (or copied, depending on
+    settings), and also shows a message for removing "stale"
+    variant-dir files that no longer have a corresponding source file.
+    It also prints a line for each target that's removed just before
+    building, since that can also be mistaken for the same thing.
+
+    </para>
+
+  </section>
+
   <!--
 
+
   <section>
 
   <title>Where Are My Build Bottlenecks?  the &profile; Option</title>
diff --git a/doc/user/troubleshoot.xml b/doc/user/troubleshoot.xml
index 468af92..1f32a35 100644
--- a/doc/user/troubleshoot.xml
+++ b/doc/user/troubleshoot.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -282,7 +282,8 @@
                          '.mm',
                          '.S',
                          '.spp',
-                         '.SPP'],
+                         '.SPP',
+                         '.sx'],
         'DSUFFIXES': ['.d'],
         'Dir': &lt;SCons.Defaults.Variable_Method_Caller object at 0x700000&gt;,
         'Dirs': &lt;SCons.Defaults.Variable_Method_Caller object at 0x700000&gt;,
@@ -345,7 +346,7 @@
         'CC': 'cl',
         'CCCOM': &lt;SCons.Action.FunctionAction object at 0x700000&gt;,
         'CCFLAGS': ['/nologo'],
-        'CCPCHFLAGS': ['${(PCH and "/Yu%s /Fp%s"%(PCHSTOP or "",File(PCH))) or ""}'],
+        'CCPCHFLAGS': ['${(PCH and "/Yu%s \\"/Fp%s\\""%(PCHSTOP or "",File(PCH))) or ""}'],
         'CCPDBFLAGS': ['${(PDB and "/Z7") or ""}'],
         'CFILESUFFIX': '.c',
         'CFLAGS': [],
@@ -371,9 +372,10 @@
                          '.mm',
                          '.S',
                          '.spp',
-                         '.SPP'],
+                         '.SPP',
+                         '.sx'],
         'CXX': '$CC',
-        'CXXCOM': '$CXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $CXXFLAGS $CCFLAGS $_CCCOMCOM',
+        'CXXCOM': '${TEMPFILE("$CXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $CXXFLAGS $CCFLAGS $_CCCOMCOM")}',
         'CXXFILESUFFIX': '.cc',
         'CXXFLAGS': ['$(', '/TP', '$)'],
         'DSUFFIXES': ['.d'],
@@ -415,7 +417,7 @@
         'SHCCFLAGS': ['$CCFLAGS'],
         'SHCFLAGS': ['$CFLAGS'],
         'SHCXX': '$CXX',
-        'SHCXXCOM': '$SHCXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $SHCXXFLAGS $SHCCFLAGS $_CCCOMCOM',
+        'SHCXXCOM': '${TEMPFILE("$SHCXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $SHCXXFLAGS $SHCCFLAGS $_CCCOMCOM")}',
         'SHCXXFLAGS': ['$CXXFLAGS'],
         'SHELL': None,
         'SHLIBPREFIX': '',
@@ -1120,9 +1122,9 @@
       scons: internal stack trace:
         File "bootstrap/src/engine/SCons/Job.py", line 199, in start
           task.prepare()
-        File "bootstrap/src/engine/SCons/Script/Main.py", line 167, in prepare
+        File "bootstrap/src/engine/SCons/Script/Main.py", line 168, in prepare
           return SCons.Taskmaster.OutOfDateTask.prepare(self)
-        File "bootstrap/src/engine/SCons/Taskmaster.py", line 187, in prepare
+        File "bootstrap/src/engine/SCons/Taskmaster.py", line 189, in prepare
           executor.prepare()
         File "bootstrap/src/engine/SCons/Executor.py", line 392, in prepare
           raise SCons.Errors.StopError(msg % (s, self.batches[0].targets[0]))
@@ -1260,8 +1262,47 @@
 
   </section>
 
+  <section>
+
+  <title>Watch &SCons; prepare targets for building: the &debug-prepare; Option</title>
+
+    <para>
+
+    Sometimes SCons doesn't build the target you want
+    and it's difficult to figure out why.  You can use
+    the <literal>--debug=prepare</literal> option
+    to see all the targets &SCons; is considering, whether
+    they are already up-to-date or not. The message is
+    printed before &SCons; decides whether to build the target.
+    </para>
+
+  </section>
+
+  <section>
+
+  <title>Why is a file disappearing?  the --debug=duplicate Option</title>
+
+    <para>
+
+    When using the &Duplicate; option to create variant dirs,
+    sometimes you may find files not getting copied to where you
+    expect (or not at all), or files mysteriously disappearing.  These
+    are usually because of a misconfiguration of some kind in the
+    SConstruct/SConscript, but they can be tricky to debug.  The
+    --debug=duplicate option shows each time a variant file is
+    unlinked and relinked from its source (or copied, depending on
+    settings), and also shows a message for removing "stale"
+    variant-dir files that no longer have a corresponding source file.
+    It also prints a line for each target that's removed just before
+    building, since that can also be mistaken for the same thing.
+
+    </para>
+
+  </section>
+
   <!--
 
+
   <section>
 
   <title>Where Are My Build Bottlenecks?  the &profile; Option</title>
diff --git a/doc/user/variables.in b/doc/user/variables.in
index bf8be1b..9b8afc1 100644
--- a/doc/user/variables.in
+++ b/doc/user/variables.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/variables.xml b/doc/user/variables.xml
index bf8be1b..9b8afc1 100644
--- a/doc/user/variables.xml
+++ b/doc/user/variables.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/variants.in b/doc/user/variants.in
index d94e3f3..5050306 100644
--- a/doc/user/variants.in
+++ b/doc/user/variants.in
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
diff --git a/doc/user/variants.xml b/doc/user/variants.xml
index bca84c8..e096eed 100644
--- a/doc/user/variants.xml
+++ b/doc/user/variants.xml
@@ -1,6 +1,6 @@
 <!--
 
-  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -114,6 +114,7 @@ is pretty smart about rebuilding things when you change options.
     lib /nologo /OUT:build\windows\world\world.lib build\windows\world\world.obj
     Install file: "build/windows/world/world.lib" as "export/windows/lib/world.lib"
     link /nologo /OUT:build\windows\hello\hello.exe /LIBPATH:export\windows\lib world.lib build\windows\hello\hello.obj
+    embedManifestExeCheck(target, source, env)
     Install file: "build/windows/hello/hello.exe" as "export/windows/bin/hello.exe"
   </screen>