From b2c050e545289ebfe716503b162fddd4fa9eef13 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Fri, 28 Mar 2014 23:12:11 +0000 Subject: [PATCH] [Doc] Add FAQ on debugging compilation issues --- SConstruct | 4 +++- doc/sphinx/faq.rst | 21 +++++++++++++++++++++ 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/SConstruct b/SConstruct index 774aab2cb..3037e07b0 100644 --- a/SConstruct +++ b/SConstruct @@ -1569,6 +1569,8 @@ if any(target.startswith('test') for target in COMMAND_LINE_TARGETS): ### Dump (debugging SCons) if 'dump' in COMMAND_LINE_TARGETS: + import pprint # Typical usage: 'scons build dump' - print env.Dump() + print 'os.environ:\n', pprint.pprint(dict(os.environ)) + print 'env.Dump():\n', env.Dump() sys.exit(0) diff --git a/doc/sphinx/faq.rst b/doc/sphinx/faq.rst index c782a204c..6484c243b 100644 --- a/doc/sphinx/faq.rst +++ b/doc/sphinx/faq.rst @@ -18,6 +18,27 @@ Installation & Compilation `_ and follow the instructions in the :ref:`sec-compiling`. +**What do I do if compiling Cantera fails?** + + - Examine the output of the ``scons build`` command, especially anything + identified as a ``WARNING`` or ``ERROR``. Check for discrepancies + with your expected configuration (e.g. not finding SUNDIALS even though + you have it installed). + - Check the contents of ``cantera.conf`` to make sure they are correct. + - If any of the configuration tests (``Checking for...``) fail unexpectedly, + look at the contents of ``config.log`` to determine the reason. + - If none of these help identify the cause of the failure, consider asking + for help on the Cantera Users' Group. If you decide to make a post, please + include the following information: + + * The contents of ``cantera.conf`` and ``config.log`` + * The output of the ``scons build`` and ``scons build dump`` commands + (you can direct this output to a file by running ``scons build >buildlog.txt 2>&1``) + * The exact version of Cantera you are trying to compile, and how it was + obtained (i.e. downloaded source tarball or the specific Git/SVN commit) + * Your operating system, compiler versions, and the versions of any other + relevant software. + **How do I debug issues with the SCons build system?** Sometimes, it is helpful to see all of the internal variables defined by