Add tests for SConscript(must_warn) option

Testcases added to confirm the behavior of: first attempt
to call a non-existent script gives a deprecation warning,
additional ones give plain warning; True/False values for
must_warn behave as expected; if scons default is changed
to exception the call fails but if must_warn=False it
still works.

Tweaked the logic to actually get that last bit to work.
Also minor doc update.

Signed-off-by: Mats Wichmann <mats@linux.com>

3 files changed, 130 insertions, 9 deletions

diff --git a/src/engine/SCons/Script/SConscript.py b/src/engine/SCons/Script/SConscript.py
index 5968346..fb6ec0d 100644
--- a/src/engine/SCons/Script/SConscript.py
+++ b/src/engine/SCons/Script/SConscript.py
@@ -153,14 +153,14 @@ def Return(*vars, **kw):
 
 stack_bottom = '% Stack boTTom %' # hard to define a variable w/this name :)
 
-def handle_missing_SConscript(f, must_exist):
+def handle_missing_SConscript(f, must_exist=None):
     """Take appropriate action on missing file in SConscript() call.
 
     The action may be to raise an exception, or print a warning.
     On first warning, also print a deprecation warning.
     """
 
-    if SCons.Script._no_missing_sconscript or must_exist:
+    if must_exist or (SCons.Script._no_missing_sconscript and must_exist is not False):
         msg = "Fatal: missing SConscript '%s'" % f.get_internal_path()
         raise SCons.Errors.UserError(msg)
 
@@ -285,7 +285,7 @@ def _SConscript(fs, *files, **kw):
                         if old_file is not None:
                             call_stack[-1].globals.update({__file__:old_file})
                 else:
-                    handle_missing_SConscript(f, kw.get('must_exist', False))
+                    handle_missing_SConscript(f, kw.get('must_exist', None))
 
         finally:
             SCons.Script.sconscript_reading = SCons.Script.sconscript_reading - 1
@@ -568,6 +568,7 @@ class SConsEnvironment(SCons.Environment.Base):
 
         files, exports = self._get_SConscript_filenames(ls, subst_kw)
         subst_kw['exports'] = exports
+        
         return _SConscript(self.fs, *files, **subst_kw)
 
     def SConscriptChdir(self, flag):
diff --git a/src/engine/SCons/Script/SConscript.xml b/src/engine/SCons/Script/SConscript.xml
index 29a89c2..a6258c4 100644
--- a/src/engine/SCons/Script/SConscript.xml
+++ b/src/engine/SCons/Script/SConscript.xml
@@ -357,12 +357,12 @@ Return('val1 val2')
 
 <scons_function name="SConscript">
 <arguments>
-(scripts, [exports, variant_dir, duplicate, must_exist=flag])
-<!-- (scripts, [exports, variant_dir, src_dir, duplicate, must_exist=flag]) -->
+(scripts, [exports, variant_dir, duplicate, must_exist])
+<!-- (scripts, [exports, variant_dir, src_dir, duplicate, must_exist]) -->
 </arguments>
 <arguments>
-(dirs=subdirs, [name=script, exports, variant_dir, duplicate, must_exist=flag])
-<!-- (dirs=subdirs, [name=script, exports, variant_dir, src_dir, duplicate, must_exist=flag]) -->
+(dirs=subdirs, [name=script, exports, variant_dir, duplicate, must_exist])
+<!-- (dirs=subdirs, [name=script, exports, variant_dir, src_dir, duplicate, must_exist]) -->
 </arguments>
 <summary>
 <para>
@@ -562,12 +562,13 @@ and what about this alternative?
 TODO??? SConscript('build/SConscript', src_dir='src')
 -->
 </para>
+
 <para>
 The optional
 <varname>must_exist</varname>
 argument, if true, causes an exception to be raised if a requested
-&SConscript; file is not found. The default is false,
-which only prints a warning, but this behavior is deprecated.
+&SConscript; file is not found. The current default is false,
+causing only a warning to be omitted, but this behavior is deprecated.
 For scripts which truly intend to be optional, transition to
 explicty supplying
 <literal>must_exist=False</literal> to the call.
diff --git a/test/SConscript/must_exist.py b/test/SConscript/must_exist.py
new file mode 100644
index 0000000..a4341fa
--- /dev/null
+++ b/test/SConscript/must_exist.py
@@ -0,0 +1,119 @@
+#!/usr/bin/env python
+#
+# __COPYRIGHT__
+#
+# 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.
+#
+
+__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__"
+
+'''
+Test handling of must_exist flag and global setting requiring the
+file to exist in an SConscript call
+'''
+
+import TestSCons
+
+test = TestSCons.TestSCons()
+
+# catch the exception if is raised, send it on as a warning
+# this gives us traceability of the line responsible
+SConstruct_path = test.workpath('SConstruct')
+test.write(SConstruct_path, """\
+import SCons
+from SCons.Warnings import _warningOut
+import sys
+
+# 1. call should succeed with deprecation warning
+try:
+    SConscript('missing/SConscript')
+except SCons.Errors.UserError as e:
+    if _warningOut:
+        _warningOut(e)
+# 2. call should succeed with warning
+try:
+    SConscript('missing/SConscript')
+except SCons.Errors.UserError as e:
+    if _warningOut:
+        _warningOut(e)
+# 3. call should raise exception
+try:
+    SConscript('missing/SConscript', must_exist=True)
+except SCons.Errors.UserError as e:
+    if _warningOut:
+        _warningOut(e)
+# 4. call should succeed with warning
+try:
+    SConscript('missing/SConscript', must_exist=False)
+except SCons.Errors.UserError as e:
+    if _warningOut:
+        _warningOut(e)
+SCons.Script.set_missing_sconscript_error()
+# 5. with system setting changed, should raise exception
+try:
+    SConscript('missing/SConscript')
+except SCons.Errors.UserError as e:
+    if _warningOut:
+        _warningOut(e)
+# 6. must_exist=False should override system setting
+try:
+    SConscript('missing/SConscript', must_exist=False)
+except SCons.Errors.UserError as e:
+    if _warningOut:
+        _warningOut(e)
+""")
+
+# we should see two exceptions as "Fatal" and
+# and see four warnings, the first having the depr message
+warn1 = """
+scons: warning: Calling missing SConscripts without error is deprecated.
+Transition by adding must_exist=0 to SConscript calls.
+Missing SConscript 'missing/SConscript'
+""" + test.python_file_line(SConstruct_path, 7)
+
+warn2 = """
+scons: warning: Ignoring missing SConscript 'missing/SConscript'
+""" + test.python_file_line(SConstruct_path, 13)
+
+err1 = """
+scons: warning: Fatal: missing SConscript 'missing/SConscript'
+""" + test.python_file_line(SConstruct_path, 22)
+
+warn3 = """
+scons: warning: Ignoring missing SConscript 'missing/SConscript'
+""" + test.python_file_line(SConstruct_path, 25)
+
+err2 = """
+scons: warning: Fatal: missing SConscript 'missing/SConscript'
+""" + test.python_file_line(SConstruct_path, 35)
+
+warn4 = """
+scons: warning: Ignoring missing SConscript 'missing/SConscript'
+""" + test.python_file_line(SConstruct_path, 38)
+
+expect_stderr = warn1 + warn2 + err1 + warn3 + err2 + warn4
+test.run(arguments = ".", stderr = expect_stderr)
+test.pass_test()
+
+# Local Variables:
+# tab-width:4
+# indent-tabs-mode:nil
+# End:
+# vim: set expandtab tabstop=4 shiftwidth=4: