find_program_path() can now add discovered path

CHANGES.txt

@@ -184,6 +184,10 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       that link has been modified (issue #3880)
     - Modernize a few tests that use now-deprecated unittest.getTestCaseNames
       and unittest.makeSuite - Python itself suggests the replacements.
+    - SCons.Tool.find_program_path now takes an optional add_path argument
+      to add a path to the execution environment if it was discovered in
+      default_paths. Previously, the routine, called by many tool modules,
+      never altered the execution environment, leaving it to the tools.
 
   From Zhichang Yu:
     - Added MSVC_USE_SCRIPT_ARGS variable to pass arguments to MSVC_USE_SCRIPT.

SCons/Tool/ToolTests.py

@@ -1,5 +1,6 @@
+# MIT License
 #
-# __COPYRIGHT__
+# 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
@@ -19,9 +20,6 @@
 # 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.
-#
-
-__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__"
 
 import os
 import unittest
@@ -99,21 +97,24 @@ def test_Tool(self):
 
 
     def test_pathfind(self):
-        """Test that find_program_path() does not alter PATH"""
+        """Test that find_program_path() alters PATH only if add_path is true"""
 
         env = DummyEnvironment()
         PHONY_PATHS = [
             r'C:\cygwin64\bin',
             r'C:\cygwin\bin',
             '/usr/local/dummy/bin',
-            env.PHONY_PATH,     # will be recognized by dummy WhereIs
+            env.PHONY_PATH,  # will be recognized by dummy WhereIs
         ]
         env['ENV'] = {}
         env['ENV']['PATH'] = '/usr/local/bin:/opt/bin:/bin:/usr/bin'
         pre_path = env['ENV']['PATH']
         _ = SCons.Tool.find_program_path(env, 'no_tool', default_paths=PHONY_PATHS)
         assert env['ENV']['PATH'] == pre_path, env['ENV']['PATH']
 
+        _ = SCons.Tool.find_program_path(env, 'no_tool', default_paths=PHONY_PATHS, add_path=True)
+        assert env.PHONY_PATH in env['ENV']['PATH'], env['ENV']['PATH']
+
 
 if __name__ == "__main__":
     loader = unittest.TestLoader()

SCons/Tool/__init__.py

@@ -21,13 +21,10 @@
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-"""SCons.Tool
+"""SCons tool selection.
 
-SCons tool selection.
-
-This looks for modules that define a callable object that can modify
-a construction environment as appropriate for a given tool (or tool
-chain).
+Looks for modules that define a callable object that can modify a
+construction environment as appropriate for a given tool (or tool chain).
 
 Note that because this subsystem just *selects* a callable that can
 modify a construction environment, it's possible for people to define
@@ -36,8 +33,6 @@
 tool specifications.
 """
 
-
-
 import sys
 import os
 import importlib.util
@@ -834,15 +829,17 @@ def tool_list(platform, env):
     return [x for x in tools if x]
 
 
-def find_program_path(env, key_program, default_paths=None):
+def find_program_path(env, key_program, default_paths=None, add_path=False) -> str:
     """
     Find the location of a tool using various means.
 
     Mainly for windows where tools aren't all installed in /usr/bin, etc.
 
-    :param env: Current Construction Environment.
-    :param key_program: Tool to locate.
-    :param default_paths: List of additional paths this tool might be found in.
+    Args:
+        env: Current Construction Environment.
+        key_program: Tool to locate.
+        default_paths: List of additional paths this tool might be found in.
+        add_path: If true, add path found if it was from *default_paths*.
     """
     # First search in the SCons path
     path = env.WhereIs(key_program)
@@ -854,15 +851,22 @@ def find_program_path(env, key_program, default_paths=None):
     if path:
         return path
 
-    # Finally, add the defaults and check again. Do not change
-    # ['ENV']['PATH'] permananetly, the caller can do that if needed.
+    # Finally, add the defaults and check again.
     if default_paths is None:
         return path
+
     save_path = env['ENV']['PATH']
     for p in default_paths:
         env.AppendENVPath('PATH', p)
     path = env.WhereIs(key_program)
+
+    # By default, do not change ['ENV']['PATH'] permananetly
+    # leave that to the caller, unless add_path is true.
     env['ENV']['PATH'] = save_path
+    if path and add_path:
+        bin_dir = os.path.dirname(path)
+        env.AppendENVPath('PATH', bin_dir)
+
     return path
 
 # Local Variables: