Merge pull request SCons#4552 from mwichmann/repro-build-notes

Reproducible builds info updated

Author: bdbaddog

CHANGES.txt

@@ -85,6 +85,7 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       Now matches the annotation and docstring (which were prematurely
       updated in 4.6). All SCons usage except unit test was already fully
       consistent with a bool.
+    - Updated the notes about reproducible builds with SCons and the example.
     - The Clone() method now respects the variables argument (fixes #3590)
 
 

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

@@ -83,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.
 
 
 

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