Merge branch 'master' into runtest-exit5

Author: bdbaddog

CHANGES.txt

@@ -89,6 +89,8 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       which means no tests were run. SCons/Script/MainTests.py currently
       has no tests, so this particular error code is expected - should not
       cause runtest to give up with an "unknown error code".
+    - Updated the notes about reproducible builds with SCons and the example.
+    - The Clone() method now respects the variables argument (fixes #3590)
 
 
 RELEASE 4.7.0 -  Sun, 17 Mar 2024 17:22:20 -0700

README.rst

@@ -249,6 +249,19 @@ notifications and other GitHub events (``#github-update``),
 if those are of interest. See the website for more contact information:
 https://scons.org/contact.html.
 
+Reproducible Builds
+===================
+SCons itself is set up to do "reproducible builds"
+(see (https://reproducible-builds.org/specs/source-date-epoch/)
+if environment variables ``SOURCE_DATE_EPOCH`` is set - that is,
+fields in the package which could change each time the package is
+constructed are forced to constant values.
+
+To support other projects which wish to do the same, a sample script
+is provided which can be placed in a site directory, which imports
+``SOURCE_DATE_EPOCH`` and sets it in the execution environment of
+every created construction envirionment. There's also an installer
+script (POSIX shell only). See packaging/etc/README.txt for more details.
 
 Donations
 =========
@@ -258,15 +271,6 @@ software, or hardware) to support continued work on the project.  Information
 is available at https://www.scons.org/donate.html
 or the GitHub Sponsors button on https://github.com/scons/scons.
 
-Reproducible Builds
-===================
-In order to suppor those users who which to produce reproducible builds
-(https://reproducible-builds.org/specs/source-date-epoch/) we're now including
-logic to force SCons to propagate SOURCE_DATE_EPOCH from your shell environment for
-all SCons builds to support reproducible builds we're now providing an example
-site_init.py and a script to install it in your ~/.scons. See packaging/etc/README.txt
-for more info
-
 For More Information
 ====================
 

RELEASE.txt

@@ -58,6 +58,7 @@ FIXES
 - Improved the conversion of a "foreign" exception from an action
   into BuildError by making sure our defaults get applied even in
   corner cases. Fixes Issue #4530
+- The Clone() method now respects the variables argument (fixes #3590)
 
 IMPROVEMENTS
 ------------
@@ -82,6 +83,7 @@ DOCUMENTATION
 - Restructured API Docs build so main package contents are listed
   before contents of package submodules.
 - Updated manpage description of Command "builder" and function.
+- Updated the notes about reproducible builds with SCons and the example.
 
 
 

SCons/Environment.py

@@ -1568,16 +1568,28 @@ def AppendUnique(self, delete_existing: bool=False, **kw) -> None:
                     self._dict[key] = dk + val
         self.scanner_map_delete(kw)
 
-    def Clone(self, tools=[], toolpath=None, parse_flags = None, **kw):
+    def Clone(self, tools=[], toolpath=None, variables=None, parse_flags=None, **kw):
         """Return a copy of a construction Environment.
 
-        The copy is like a Python "deep copy"--that is, independent
-        copies are made recursively of each objects--except that
-        a reference is copied when an object is not deep-copyable
-        (like a function).  There are no references to any mutable
-        objects in the original Environment.
-        """
+        The copy is like a Python "deep copy": independent copies are made
+        recursively of each object, except that a reference is copied when
+        an object is not deep-copyable (like a function).  There are no
+        references to any mutable objects in the original environment.
+
+        Unrecognized keyword arguments are taken as construction variable
+        assignments.
 
+        Arguments:
+           tools: list of tools to initialize.
+           toolpath: list of paths to search for tools.
+           variables: a :class:`~SCons.Variables.Variables` object to
+              use to populate construction variables from command-line
+              variables.
+           parse_flags: option strings to parse into construction variables.
+
+        .. versionadded:: 4.8.0
+              The optional *variables* parameter was added.
+        """
         builders = self._dict.get('BUILDERS', {})
 
         clone = copy.copy(self)
@@ -1603,6 +1615,8 @@ def Clone(self, tools=[], toolpath=None, parse_flags = None, **kw):
         for key, value in kw.items():
             new[key] = SCons.Subst.scons_subst_once(value, self, key)
         clone.Replace(**new)
+        if variables:
+            variables.Update(clone)
 
         apply_tools(clone, tools, toolpath)
 

SCons/Environment.xml

@@ -1079,11 +1079,12 @@ Clean(docdir, os.path.join(docdir, projectname))
 </arguments>
 <summary>
 <para>
-Returns a separate copy of a construction environment.
-If there are any keyword arguments specified,
-they are added to the returned copy,
+Returns an independent copy of a &consenv;.
+If there are any unrecognized keyword arguments specified,
+they are added as &consvars; in the copy,
 overwriting any existing values
-for the keywords.
+for those keywords.
+See the manpage section "Construction Environments" for more details.
 </para>
 
 <para>
@@ -1096,8 +1097,9 @@ env3 = env.Clone(CCFLAGS='-g')
 </example_commands>
 
 <para>
-Additionally, a list of tools and a toolpath may be specified, as in
-the &f-link-Environment; constructor:
+A list of <parameter>tools</parameter>
+and a <parameter>toolpath</parameter> may be specified,
+as in the &f-link-Environment; constructor:
 </para>
 
 <example_commands>
@@ -1110,7 +1112,7 @@ env4 = env.Clone(tools=['msvc', MyTool])
 <para>
 The
 <parameter>parse_flags</parameter>
-keyword argument is also recognized to allow merging command-line
+keyword argument is also recognized, to allow merging command-line
 style arguments into the appropriate construction
 variables (see &f-link-env-MergeFlags;).
 </para>
@@ -1119,6 +1121,17 @@ variables (see &f-link-env-MergeFlags;).
 # create an environment for compiling programs that use wxWidgets
 wx_env = env.Clone(parse_flags='!wx-config --cflags --cxxflags')
 </example_commands>
+
+<para>
+The <parameter>variables</parameter>
+keyword argument is also recognized, to allow (re)initializing
+&consvars; from a <literal>Variables</literal> object.
+</para>
+
+<para>
+<emphasis>Changed in version 4.8.0:</emphasis>
+the <parameter>variables</parameter> parameter was added.
+</para>
 </summary>
 </scons_function>
 
@@ -1760,7 +1773,7 @@ will print:
 </arguments>
 <summary>
 <para>
-Return a new construction environment
+Return a new &consenv;
 initialized with the specified
 <parameter>key</parameter>=<replaceable>value</replaceable>
 pairs.
@@ -1770,7 +1783,8 @@ The keyword arguments
 <parameter>toolpath</parameter>,
 <parameter>tools</parameter>
 and <parameter>variables</parameter>
-are also specially recognized.
+are specially recognized and do not lead to
+&consvar; creation.
 See the manpage section "Construction Environments" for more details.
 </para>
 </summary>

packaging/etc/README.txt

@@ -1,10 +1,18 @@
-This directory contains a number of scripts/files useful when building/packageing SCons
+This directory contains helpers for doing reproducible builds with SCons.
+
+To force SCons to propagate SOURCE_DATE_EPOCH from the shell running SCons,
+the reproducible_site_init.py file can be installed (as site_init.py)
+in any site directory - either in the project itself, or more globally.
+See the manpage for default site directories or how to set your own path:
+https://scons.org/doc/production/HTML/scons-man.html#opt-site-dir.
+This code will make sure SOURCE_DATE_EPOCH is set in the execution
+environment, meaning any external commands run by SCons will have it
+in their environment.  Any logic in your build system itself will still
+need to examine this variable.
+
+The shell script reproducible_install.sh can be used to install the
+Python site file in your user site directory ($HOME/.scons/site_scons).
+It is careful to not overwrite any existing site_init.py there. This
+only works for a POSIX shell.
 
-To force SCons to propagate SOURCE_DATE_EPOCH from the shell running SCons we're providing
-a script to create a ~/.scons/site_scons/site_init.py.
-Note that reproducible_install.sh will NOT overwite an existing ~/.scons/site_scons/site_init.py
 This supports https://reproducible-builds.org/specs/source-date-epoch/
-If you wanted to include this in your build tree you would place in site_scons/site_init.py relative
-to your SConstruct.
-* reproducible_install.sh
-* reproducible_site_init.py

packaging/etc/reproducible_site_init.py

@@ -1,5 +1,6 @@
 """
-Use this file as your ~/.site_scons/scons_init.py to enable reprodicble builds as described at
+Use this file as your site_init.py in a site directory,
+to enable reprodicble builds as described at
 https://reproducible-builds.org/specs/source-date-epoch/
 """
 
@@ -8,17 +9,22 @@
 
 old_init = SCons.Environment.Base.__init__
 
-print("Adding logic to propagate SOURCE_DATE_EPOCH from the shell environment when building with SCons")
+print(
+    "Adding logic to propagate SOURCE_DATE_EPOCH from the shell environment when building with SCons"
+)
 
 
 def new_init(self, **kw):
-    """
-    This logic will add SOURCE_DATE_EPOCH to the execution environment used to run
-    all the build commands.
+    """Replacement Environment initializer.
+
+    When this is monkey-patched into :class:`SCons.Environment.Base` it adds
+    ``SOURCE_DATE_EPOCH`` to the execution environment used to run
+    all external build commands; the original iinitializer is called first.
     """
     old_init(self, **kw)
-    if 'SOURCE_DATE_EPOCH' in os.environ:
-        self._dict['ENV']['SOURCE_DATE_EPOCH'] = os.environ['SOURCE_DATE_EPOCH']
+    epoch = os.environ.get("SOURCE_DATE_EPOCH")
+    if epoch is not None:
+        self._dict["ENV"]["SOURCE_DATE_EPOCH"] = epoch
 
 
 SCons.Environment.Base.__init__ = new_init

test/Clone-Variables.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python
+#
+# MIT License
+#
+# Copyright The SCons Foundation
+#
+# 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.
+
+
+"""
+Verify that Clone() respects the variables kwarg.
+
+"""
+
+import TestSCons
+
+test = TestSCons.TestSCons()
+
+test.write('SConstruct', """\
+vars = Variables()
+vars.Add(BoolVariable('MYTEST', 'help', default=False))
+
+_ = DefaultEnvironment(tools=[])
+env = Environment(variables=vars, tools=[])
+print(f"MYTEST={env.Dictionary('MYTEST')}")
+env.Replace(MYTEST=True)
+print(f"MYTEST={env.Dictionary('MYTEST')}")
+env1 = env.Clone(variables=vars)
+print(f"MYTEST={env1.Dictionary('MYTEST')}")
+""")
+
+expect = """\
+MYTEST=False
+MYTEST=True
+MYTEST=False
+"""
+
+test.run(arguments = '-q -Q', stdout=expect)
+
+test.pass_test()
+
+# Local Variables:
+# tab-width:4
+# indent-tabs-mode:nil
+# End:
+# vim: set expandtab tabstop=4 shiftwidth=4: