From 5c99f683df7d74773a1b90426b23d37de8de03a6 Mon Sep 17 00:00:00 2001
From: Ray Speth <speth@mit.edu>
Date: Fri, 28 Mar 2014 23:12:06 +0000
Subject: [PATCH] [SCons] Add 'dump' command line target, and update FAQ

---
 SConstruct         | 13 +++++++------
 doc/sphinx/faq.rst | 21 +++++++++++++++++++--
 2 files changed, 26 insertions(+), 8 deletions(-)

diff --git a/SConstruct b/SConstruct
index 7c7237695..774aab2cb 100644
--- a/SConstruct
+++ b/SConstruct
@@ -38,7 +38,7 @@ if not COMMAND_LINE_TARGETS:
     sys.exit(0)
 
 valid_commands = ('build','clean','install','uninstall',
-                  'help','msi','samples','sphinx','doxygen')
+                  'help','msi','samples','sphinx','doxygen','dump')
 
 for command in COMMAND_LINE_TARGETS:
     if command not in valid_commands and not command.startswith('test'):
@@ -146,11 +146,6 @@ env = Environment(tools=toolchain+['textfile', 'subst', 'recursiveInstall', 'wix
                   toolchain=toolchain,
                   **extraEnvArgs)
 
-#
-# To print the current environment
-#
-# print env.Dump()
-
 env['OS'] = platform.system()
 env['OS_BITS'] = int(platform.architecture()[0][:2])
 if 'cygwin' in env['OS'].lower():
@@ -1571,3 +1566,9 @@ if any(target.startswith('test') for target in COMMAND_LINE_TARGETS):
         for name in env['testNames']:
             print 'test-%s' % name
         sys.exit(0)
+
+### Dump (debugging SCons)
+if 'dump' in COMMAND_LINE_TARGETS:
+    # Typical usage: 'scons build dump'
+    print env.Dump()
+    sys.exit(0)
diff --git a/doc/sphinx/faq.rst b/doc/sphinx/faq.rst
index a3c265eaf..c782a204c 100644
--- a/doc/sphinx/faq.rst
+++ b/doc/sphinx/faq.rst
@@ -2,8 +2,8 @@
 Frequently Asked Questions
 **************************
 
-Installation
-------------
+Installation & Compilation
+--------------------------
 
 **How do I install Cantera on Windows?**
 
@@ -18,6 +18,23 @@ Installation
     <https://sourceforge.net/projects/cantera/files/cantera/>`_ and follow the
     instructions in the :ref:`sec-compiling`.
 
+**How do I debug issues with the SCons build system?**
+
+    Sometimes, it is helpful to see all of the internal variables defined by
+    SCons, either automatically or by the Cantera build scripts. To do this, add
+    ``dump`` to your SCons command line. For example::
+
+        $ scons build dump
+
+    will show the variables that would be set during the ``build`` step. Note
+    that in this case, the ``build`` step will not be executed.
+
+    Alternatively, it is also possible to run SCons through the Python debugger, and set a breakpoint in the ``SConstruct`` file. For example::
+
+        $ scons --debug=pdb build
+        (Pdb) b /full/path/to/SConstruct:33
+        (Pdb) cont
+
 General
 -------