From a9212612153b83480fdfb00c3c2e7138bd38b485 Mon Sep 17 00:00:00 2001
From: Catherine <whitequark@whitequark.org>
Date: Sun, 23 Jul 2023 03:42:03 +0000
Subject: [PATCH] build.run: add `env=` argument to
 `BuildPlan.execute_local()`.

Build scripts are explicitly intended to have overrides that are
done through the use of environment variables, and right now this
would require a very awkward `run_script=False` invocation followed
by copying a bit of code out of the Amaranth codebase, which is
clearly suboptimal.
---
 amaranth/build/run.py | 14 ++++++++++----
 docs/changes.rst      |  1 +
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/amaranth/build/run.py b/amaranth/build/run.py
index c6a281d..2e4045e 100644
--- a/amaranth/build/run.py
+++ b/amaranth/build/run.py
@@ -61,12 +61,13 @@ class BuildPlan:
             for filename in sorted(self.files):
                 archive.writestr(zipfile.ZipInfo(filename), self.files[filename])
 
-    def execute_local(self, root="build", *, run_script=True):
+    def execute_local(self, root="build", *, run_script=True, env=None):
         """
         Execute build plan using the local strategy. Files from the build plan are placed in
         the build root directory ``root``, and, if ``run_script`` is ``True``, the script
         appropriate for the platform (``{script}.bat`` on Windows, ``{script}.sh`` elsewhere) is
-        executed in the build root.
+        executed in the build root. If ``env`` is not ``None``, the environment is extended
+        (not replaced) with ``env``.
 
         Returns :class:`LocalBuildProducts`.
         """
@@ -90,13 +91,18 @@ class BuildPlan:
                     f.write(content)
 
             if run_script:
+                script_env = dict(os.environ)
+                if env is not None:
+                    script_env.update(env)
                 if sys.platform.startswith("win32"):
                     # Without "call", "cmd /c {}.bat" will return 0.
                     # See https://stackoverflow.com/a/30736987 for a detailed explanation of why.
                     # Running the script manually from a command prompt is unaffected.
-                    subprocess.check_call(["cmd", "/c", "call {}.bat".format(self.script)])
+                    subprocess.check_call(["cmd", "/c", "call {}.bat".format(self.script)],
+                                          env=script_env)
                 else:
-                    subprocess.check_call(["sh", "{}.sh".format(self.script)])
+                    subprocess.check_call(["sh", "{}.sh".format(self.script)],
+                                          env=script_env)
 
             return LocalBuildProducts(os.getcwd())
 
diff --git a/docs/changes.rst b/docs/changes.rst
index 261f6c1..f9a8eb0 100644
--- a/docs/changes.rst
+++ b/docs/changes.rst
@@ -95,6 +95,7 @@ Toolchain changes
 
 * Changed: text files are written with LF line endings on Windows, like on other platforms.
 * Added: ``debug_verilog`` override in :class:`build.TemplatedPlatform`.
+* Added: ``env=`` argument to :meth:`build.run.BuildPlan.execute_local`.
 * Deprecated: use of mixed-case toolchain environment variable names, such as ``NMIGEN_ENV_Diamond`` or ``AMARANTH_ENV_Diamond``; use upper-case environment variable names, such as ``AMARANTH_ENV_DIAMOND``.
 * Removed: (deprecated in 0.3) :meth:`sim.Simulator.step`.
 * Removed: (deprecated in 0.3) :mod:`back.pysim`.