doc: change five functions to appear global-only

The five functions EnsureSConsVersion, EnsurePythonVersion, Exit,
GetLaunchDir, SConscriptChdir were listed as both global and
environment functions, but they do nothing in the context of an
environment, so marked in the xml as "global".  This only changes
the presentation in the manpage & userguide appendix, not the behavior.

Minor tweaks in the code around SConscriptChdir - actually use a
bool True/False instead of 0/1, and added a couple of type annotations.

Signed-off-by: Mats Wichmann <[email protected]>

CHANGES.txt

@@ -33,6 +33,9 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       if asked to copy a list to an existing non-directory destination.
       Both the implementation and the strfunction which prints the progress
       message were adjusted. Fixes #3009.
+    - doc: EnsureSConsVersion, EnsurePythonVersion, Exit, GetLaunchDir and
+      SConscriptChdir are now listed as Global functions only; the
+      Environment versions still work but are not documented.
 
 RELEASE 4.4.0 -  Sat, 30 Jul 2022 14:08:29 -0700
 

RELEASE.txt

@@ -70,6 +70,8 @@ DOCUMENTATION
   the contributor credit)
 
 - Updated the --hash-format manpage entry.
+- EnsureSConsVersion, EnsurePythonVersion, Exit, GetLaunchDir and
+  SConscriptChdir are now listed as Global functions only.
 
 DEVELOPMENT
 -----------

SCons/Environment.xml

@@ -2862,7 +2862,7 @@ for a complete explanation of the arguments and behavior.
 </scons_function>
 
 <scons_function name="SConscriptChdir">
-<arguments>
+<arguments signature="global">
 (value)
 </arguments>
 <summary>
@@ -2871,18 +2871,11 @@ By default,
 &scons;
 changes its working directory
 to the directory in which each
-subsidiary SConscript file lives.
+subsidiary SConscript file lives
+while reading and processing that script.
 This behavior may be disabled
-by specifying either:
-</para>
-
-<example_commands>
-SConscriptChdir(0)
-env.SConscriptChdir(0)
-</example_commands>
-
-<para>
-in which case
+by specifying an argument which
+evaluates false, in which case
 &scons;
 will stay in the top-level directory
 while reading all SConscript files.
@@ -2900,10 +2893,9 @@ Example:
 </para>
 
 <example_commands>
-env = Environment()
-SConscriptChdir(0)
+SConscriptChdir(False)
 SConscript('foo/SConscript')	# will not chdir to foo
-env.SConscriptChdir(1)
+SConscriptChdir(True)
 SConscript('bar/SConscript')	# will chdir to bar
 </example_commands>
 </summary>
@@ -3485,7 +3477,7 @@ The subsidiary SConscript file must be called as if it were in
 <parameter>variant_dir</parameter>,
 regardless of the value of
 <parameter>duplicate</parameter>.
-When calling an SConscript file, you can use the 
+When calling an SConscript file, you can use the
 <parameter>exports</parameter> keyword argument
 to pass parameters (individually or as an appropriately set up environment)
 so the SConscript can pick up the right settings for that variant build.

SCons/Node/FS.py

@@ -1239,7 +1239,7 @@ def getcwd(self):
         else:
             return "<no cwd>"
 
-    def chdir(self, dir, change_os_dir=0):
+    def chdir(self, dir, change_os_dir=False):
         """Change the current working directory for lookups.
         If change_os_dir is true, we will also change the "real" cwd
         to match.

SCons/Node/FSTests.py

@@ -1822,7 +1822,7 @@ def test_same_name(self):
         test.write(['subdir', 'build'], "subdir/build\n")
 
         subdir = fs.Dir('subdir')
-        fs.chdir(subdir, change_os_dir=1)
+        fs.chdir(subdir, change_os_dir=True)
         self.fs._lookup('#build/file', subdir, SCons.Node.FS.File)
 
     def test_above_root(self):

SCons/SConf.py

@@ -515,7 +515,7 @@ def BuildNodes(self, nodes):
         # the engine assumes the current path is the SConstruct directory ...
         old_fs_dir = SConfFS.getcwd()
         old_os_dir = os.getcwd()
-        SConfFS.chdir(SConfFS.Top, change_os_dir=1)
+        SConfFS.chdir(SConfFS.Top, change_os_dir=True)
 
         # Because we take responsibility here for writing out our
         # own .sconsign info (see SConfBuildTask.execute(), above),
@@ -562,7 +562,7 @@ def BuildNodes(self, nodes):
         finally:
             SConfFS.set_max_drift(save_max_drift)
             os.chdir(old_os_dir)
-            SConfFS.chdir(old_fs_dir, change_os_dir=0)
+            SConfFS.chdir(old_fs_dir, change_os_dir=False)
             if self.logstream is not None:
                 # restore stdout / stderr
                 sys.stdout = oldStdout
@@ -772,7 +772,7 @@ def conflog_cleanup(logf):
 
             tb = traceback.extract_stack()[-3-self.depth]
             old_fs_dir = SConfFS.getcwd()
-            SConfFS.chdir(SConfFS.Top, change_os_dir=0)
+            SConfFS.chdir(SConfFS.Top, change_os_dir=False)
             self.logstream.write('file %s,line %d:\n\tConfigure(confdir = %s)\n' %
                                  (tb[0], tb[1], str(self.confdir)) )
             SConfFS.chdir(old_fs_dir)

SCons/Script/SConscript.py

@@ -57,7 +57,7 @@ class SConscriptReturn(Exception):
 global_exports = {}
 
 # chdir flag
-sconscript_chdir = 1
+sconscript_chdir: bool = True
 
 def get_calling_namespaces():
     """Return the locals and globals for the function that called
@@ -205,7 +205,7 @@ def _SConscript(fs, *files, **kw):
                 # Change directory to the top of the source
                 # tree to make sure the os's cwd and the cwd of
                 # fs match so we can open the SConscript.
-                fs.chdir(top, change_os_dir=1)
+                fs.chdir(top, change_os_dir=True)
                 if f.rexists():
                     actual = f.rfile()
                     _file_ = open(actual.get_abspath(), "rb")
@@ -254,7 +254,7 @@ def _SConscript(fs, *files, **kw):
                         # fs.chdir(), because we still need to
                         # interpret the stuff within the SConscript file
                         # relative to where we are logically.
-                        fs.chdir(ldir, change_os_dir=0)
+                        fs.chdir(ldir, change_os_dir=False)
                         os.chdir(actual.dir.get_abspath())
 
                     # Append the SConscript directory to the beginning
@@ -292,7 +292,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', None))
 
@@ -306,7 +306,7 @@ def _SConscript(fs, *files, **kw):
                 # There was no local directory, so chdir to the
                 # Repository directory.  Like above, we do this
                 # directly.
-                fs.chdir(frame.prev_dir, change_os_dir=0)
+                fs.chdir(frame.prev_dir, change_os_dir=False)
                 rdir = frame.prev_dir.rdir()
                 rdir._create()  # Make sure there's a directory there.
                 try:
@@ -600,7 +600,7 @@ def subst_element(x, subst=self.subst):
         subst_kw['exports'] = exports
         return _SConscript(self.fs, *files, **subst_kw)
 
-    def SConscriptChdir(self, flag):
+    def SConscriptChdir(self, flag: bool) -> None:
         global sconscript_chdir
         sconscript_chdir = flag
 

SCons/Script/SConscript.xml

@@ -84,7 +84,7 @@ env.Default(hello)
 </scons_function>
 
 <scons_function name="EnsurePythonVersion">
-<arguments>
+<arguments signature="global">
 (major, minor)
 </arguments>
 <summary>
@@ -107,7 +107,7 @@ EnsurePythonVersion(2,2)
 </scons_function>
 
 <scons_function name="EnsureSConsVersion">
-<arguments>
+<arguments signature="global">
 (major, minor, [revision])
 </arguments>
 <summary>
@@ -137,7 +137,7 @@ EnsureSConsVersion(0,96,90)
 </scons_function>
 
 <scons_function name="Exit">
-<arguments>
+<arguments signature="global">
 ([value])
 </arguments>
 <summary>
@@ -215,7 +215,7 @@ See the description below.
 </scons_function>
 
 <scons_function name="GetLaunchDir">
-<arguments>
+<arguments signature="global">
 ()
 </arguments>
 <summary>