Change the default to error on missing SConscript

This completes a change begun in 3.0.2, when the behavior changed
from "skip silently" to "skip but issue a warning"; that behavior
was marked deprecated in 3.1.  Use must_exist=False to get the old
"skip silently" behavior.

Fixes #3958

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

CHANGES.txt

@@ -131,6 +131,9 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER
  - More tweaking of test framework overview (which is duplicated onto
  the website, but not in the regular documentation section).
  - Extend range of recognized Java versions to 20.
+ - Finish the change to make calling SConscript() with a nonexistent
+ file an error. It has issued a warning since 3.0, with "warn instead
+ of fail" deprecated since 3.1. Fixes #3958.
 
  From Jonathon Reinhart:
  - Fix another instance of `int main()` in CheckLib() causing failures

README.rst

@@ -167,7 +167,7 @@ messages during installation like this::
  Consider adding this directory to PATH or, if you prefer to suppress this warning,
  use --no-warn-script-location.
 
-If you are running on a system which uses a package manager 
+If you are running on a system which uses a package manager
 (for example most Linux distributions), you may, at your option,
 use the package manager (e.g. ``apt``, ``dnf``, ``yum``,
 ``zypper``, ``brew``, ``pacman`` etc.) to install a version

RELEASE.txt

@@ -60,6 +60,12 @@ CHANGED/ENHANCED EXISTING FUNCTIONALITY
  architecture combination. For example, when using VS2022 on arm64, the arm64 native
  tools are only installed for the 14.3x toolsets.
 - Extend range of recognized Java versions to 20.
+- Calling SConscript() with a nonexistent file is now an error.
+ Previously this succeeded - prior to SCons 3.0, silently; since 3.0, with
+ a warning. Developers can still instruct such an SConscript() call not
+ to fail by being explicit: pass keyword argument "must_exist=False".
+ The "--warn=missing-sconscript" commandline option is no longer available
+ as the warning was part of the transitional phase.
 
 FIXES
 -----

SCons/Script/SConscript.py

@@ -145,40 +145,32 @@ def Return(*vars, **kw):
 
 stack_bottom = '% Stack boTTom %' # hard to define a variable w/this name :)
 
-def handle_missing_SConscript(f, must_exist=None):
+def handle_missing_SConscript(f: str, must_exist: bool = True) -> None:
  """Take appropriate action on missing file in SConscript() call.
 
  Print a warning or raise an exception on missing file, unless
- missing is explicitly allowed by the *must_exist* value.
- On first warning, print a deprecation message.
+ missing is explicitly allowed by the *must_exist* parameter or by
+ a global flag.
 
  Args:
- f (str): path of missing configuration file
- must_exist (bool): if true, fail. If false, but not ``None``,
- allow the file to be missing. The default is ``None``,
- which means issue the warning. The default is deprecated.
+ f: path to missing configuration file
+ must_exist: if true (the default), fail. If false
+ do nothing, allowing a build to declare it's okay to be missing.
 
  Raises:
-  UserError: if *must_exist* is true or if global
+ UserError: if *must_exist* is true or if global
  :data:`SCons.Script._no_missing_sconscript` is true.
+
+ .. versionchanged: 4.6.0
+ Changed default from False.
  """
+ if not must_exist: # explicitly set False: ok
+ return
+ if not SCons.Script._no_missing_sconscript: # system default changed: ok
+ return
+ msg = f"Fatal: missing SConscript '{f.get_internal_path()}'"
+ raise SCons.Errors.UserError(msg)
 
- 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)
-
- if must_exist is None:
- if SCons.Script._warn_missing_sconscript_deprecated:
- msg = (
- "Calling missing SConscript without error is deprecated.\n"
- "Transition by adding must_exist=False to SConscript calls.\n"
- "Missing SConscript '%s'" % f.get_internal_path()
- )
- SCons.Warnings.warn(SCons.Warnings.MissingSConscriptWarning, msg)
- SCons.Script._warn_missing_sconscript_deprecated = False
- else:
- msg = "Ignoring missing SConscript '%s'" % f.get_internal_path()
- SCons.Warnings.warn(SCons.Warnings.MissingSConscriptWarning, msg)
 
 def _SConscript(fs, *files, **kw):
  top = fs.Top
@@ -294,7 +286,7 @@ def _SConscript(fs, *files, **kw):
  call_stack[-1].globals.update({__file__:old_file})
 
  else:
- handle_missing_SConscript(f, kw.get('must_exist', None))
+ handle_missing_SConscript(f, kw.get('must_exist', True))
 
  finally:
  SCons.Script.sconscript_reading = SCons.Script.sconscript_reading - 1

SCons/Script/SConscript.xml

@@ -538,17 +538,20 @@ TODO??? SConscript('build/SConscript', src_dir='src')
 <para>
 If the optional
 <varname>must_exist</varname>
-is <constant>True</constant>,
+is <constant>True</constant> (the default),
 causes an exception to be raised if a requested
-SConscript file is not found. The current default is
-<constant>False</constant>,
-causing only a warning to be emitted, but this default is deprecated
-(<emphasis>since 3.1</emphasis>).
-For scripts which truly intend to be optional, transition to
-explicitly supplying
+SConscript file is not found.
+To allow missing scripts to be silently ignored
+(the default behavior prior to &SCons; version 3.1),
+pass
 <literal>must_exist=False</literal> to the &f-SConscript; call.
 </para>
 
+<para>
+<emphasis>Changed in 4.6.0</emphasis>: <parameter>must_exist</parameter>
+now defaults to <constant>True</constant>.
+</para>
+
 <para>
 Here are some composite examples:
 </para>

SCons/Script/__init__.py

@@ -269,10 +269,10 @@ def HelpFunction(text, append: bool=False) -> None:
 # Will be non-zero if we are reading an SConscript file.
 sconscript_reading = 0
 
-_no_missing_sconscript = False
-_warn_missing_sconscript_deprecated = True
+_no_missing_sconscript = True
+_warn_missing_sconscript_deprecated = False # TODO: now unused
 
-def set_missing_sconscript_error(flag: int=1):
+def set_missing_sconscript_error(flag: bool = True) -> bool:
  """Set behavior on missing file in SConscript() call.
 
  Returns:

SCons/Warnings.py

@@ -70,6 +70,7 @@ class LinkWarning(WarningOnByDefault):
 class MisleadingKeywordsWarning(WarningOnByDefault):
  pass
 
+# TODO: no longer needed, now an error instead of warning. Leave for a bit.
 class MissingSConscriptWarning(WarningOnByDefault):
  pass
 

doc/man/scons.xml

@@ -2272,13 +2272,13 @@ of this tool module.
  </listitem>
  </varlistentry>
 
- <varlistentry>
+ <!--varlistentry> Removed in 4.6.0
  <term><emphasis role="bold">missing-sconscript</emphasis></term>
  <listitem>
 <para>Warnings about missing &SConscript; files.
 These warnings are enabled by default.</para>
  </listitem>
- </varlistentry>
+ </varlistentry-->
 
  <varlistentry>
  <term><emphasis role="bold">no-object-count</emphasis></term>

test/option/warn-missing-sconscript.py → test/Removed/Old/warn-missing-sconscript.py

@@ -61,14 +61,10 @@ def build(target, source, env):
 #scons: warning: Ignoring missing SConscript 'no_such_file'
 "" + TestSCons.file_expr
 
-test.run(arguments = '--warn=missing-sconscript .', stderr = expect)
-
-test.run(arguments = '--warn=no-missing-sconscript .', stderr = "")
-
-test.run(arguments = 'WARN=missing-sconscript .', stderr = expect)
-
-test.run(arguments = 'WARN=no-missing-sconscript .', stderr = "")
-
+test.run(arguments='--warn=missing-sconscript .', stderr=expect)
+test.run(arguments='--warn=no-missing-sconscript .', stderr="")
+test.run(arguments='WARN=missing-sconscript .', stderr=expect)
+test.run(arguments='WARN=no-missing-sconscript .', stderr="")
 
 test.pass_test()
 

test/SConscript/must_exist.py

@@ -37,76 +37,93 @@
 # 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
+import traceback
+
+import SCons.Script
+from SCons.Errors import UserError
+from SCons.Script.Main import find_deepest_user_frame
 
 DefaultEnvironment(tools=[])
-# 1. 1st default call should succeed with deprecation warning
-try:
- SConscript('missing/SConscript')
-except SCons.Errors.UserError as e:
- if _warningOut:
- _warningOut(e)
-# 2. 2nd default call should succeed with warning (no depr)
+
+def user_error(e):
+ "Synthesize msg from UserError."
+ # Borrowed from SCons.Script._scons_user_error which we don't use
+ # because it exits - we only want the message.
+ etype, value, tb = sys.exc_info()
+ filename, lineno, routine, _ = find_deepest_user_frame(traceback.extract_tb(tb))
+ sys.stderr.write(f"\\nscons: *** {value}\\n")
+ sys.stderr.write(f'File "{filename}", line {lineno}, in {routine}\\n')
+
+# 1. Call with defaults raises exception
 try:
- SConscript('missing/SConscript')
-except SCons.Errors.UserError as e:
- if _warningOut:
- _warningOut(e)
-# 3. must_exist True call should raise exception
+ SConscript("missing/SConscript")
+except UserError as e:
+ user_error(e)
+
+# 2. Call with must_exist=True raises exception
 try:
- SConscript('missing/SConscript', must_exist=True)
-except SCons.Errors.UserError as e:
- if _warningOut:
- _warningOut(e)
-# 4. must_exist False call should succeed silently
+ SConscript("missing/SConscript", must_exist=True)
+except UserError as e:
+ user_error(e)
+
+# 3. Call with must_exist=False call should succeed silently
 try:
- SConscript('missing/SConscript', must_exist=False)
-except SCons.Errors.UserError as e:
- if _warningOut:
- _warningOut(e)
-# 5. with system setting changed, should raise exception
-SCons.Script.set_missing_sconscript_error()
+ SConscript("missing/SConscript", must_exist=False)
+except UserError as e:
+ user_error(e)
+
+# 4. with system setting changed, should succeed silently
+SCons.Script.set_missing_sconscript_error(flag=False)
 try:
- SConscript('missing/SConscript')
-except SCons.Errors.UserError as e:
- if _warningOut:
- _warningOut(e)
-# 6. must_exist=False overrides system setting, should emit warning
+ SConscript("missing/SConscript")
+except UserError as e:
+ user_error(e)
+
+# 5. must_exist=True "wins" over 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
-# need to build the path in the expected msg in an OS-agnostic way
-missing = os.path.normpath('missing/SConscript')
-warn1 = """
-scons: warning: Calling missing SConscript without error is deprecated.
-Transition by adding must_exist=False to SConscript calls.
-Missing SConscript '{}'
-""".format(missing) + test.python_file_line(SConstruct_path, 8)
-
-warn2 = """
-scons: warning: Ignoring missing SConscript '{}'
-""".format(missing) + test.python_file_line(SConstruct_path, 14)
-
-err1 = """
-scons: warning: Fatal: missing SConscript '{}'
-""".format(missing) + test.python_file_line(SConstruct_path, 23)
-
-err2 = """
-scons: warning: Fatal: missing SConscript '{}'
-""".format(missing) + test.python_file_line(SConstruct_path, 36)
+ SConscript("missing/SConscript", must_exist=True)
+except UserError as e:
+ user_error(e)
+""",
+)
+
+missing = "missing/SConscript"
+err1 = f"""
+scons: *** Fatal: missing SConscript {missing!r}
+""" + test.python_file_line(
+ SConstruct_path, 21
+)
+
+err2 = f"""
+scons: *** Fatal: missing SConscript {missing!r}
+""" + test.python_file_line(
+ SConstruct_path, 27
+)
+
+err3 = f"""
+scons: *** Fatal: missing SConscript {missing!r}
+""" + test.python_file_line(
+ SConstruct_path, 33
+)
+
+err4 = f"""
+scons: *** Fatal: missing SConscript {missing!r}
+""" + test.python_file_line(
+ SConstruct_path, 40
+)
+
+err5 = f"""
+scons: *** Fatal: missing SConscript {missing!r}
+""" + test.python_file_line(
+ SConstruct_path, 46
+)
 
 nowarn = ""
 
-expect_stderr = warn1 + warn2 + err1 + nowarn + err2 + nowarn
-test.run(arguments = ".", stderr = expect_stderr)
+# of the five tests, we actually expect fails from 1 and 2
+expect_stderr = err1 + err2 + nowarn + nowarn + nowarn
+test.run(arguments=".", stderr=expect_stderr)
 test.pass_test()
 
 # Local Variables: