Merge pull request #4230 from mwichmann/doc/not-env-methods

doc: change five functions to appear global-only

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>