Merge pull request SCons#4508 from mwichmann/doc/Tools

Tools update, mainly documentation

CHANGES.txt

@@ -30,6 +30,8 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
     - Drop duplicated __getstate__ and __setstate__ methods in AliasNodeInfo,
       FileNodeInfo and ValueNodeInfo classes, as they are identical to the
       ones in parent NodeInfoBase and can just be inherited.
+    - Update manpage for Tools, and for TOOL, which also gets a minor
+      tweak for how it's handled (should be more accurate in a few situations).
 
 
 RELEASE 4.7.0 -  Sun, 17 Mar 2024 17:22:20 -0700

RELEASE.txt

@@ -62,6 +62,7 @@ DOCUMENTATION
 -------------
 
 - Updated Value Node docs.
+- Update manpage for Tools, and for the TOOL variable.
 
 
 

SCons/Environment.py

@@ -37,7 +37,7 @@
 import shlex
 from collections import UserDict, UserList, deque
 from subprocess import PIPE, DEVNULL
-from typing import Optional, Sequence
+from typing import Callable, Collection, Optional, Sequence, Union
 
 import SCons.Action
 import SCons.Builder
@@ -1250,9 +1250,11 @@ def __init__(
         SCons.Tool.Initializers(self)
 
         if tools is None:
-            tools = self._dict.get('TOOLS', None)
-            if tools is None:
-                tools = ['default']
+            tools = self._dict.get('TOOLS', ['default'])
+        else:
+            # for a new env, if we didn't use TOOLS, make sure it starts empty
+            # so it only shows tools actually initialized.
+            self._dict['TOOLS'] = []
         apply_tools(self, tools, toolpath)
 
         # Now restore the passed-in and customized variables
@@ -2014,11 +2016,20 @@ def SetDefault(self, **kw) -> None:
     def _find_toolpath_dir(self, tp):
         return self.fs.Dir(self.subst(tp)).srcnode().get_abspath()
 
-    def Tool(self, tool, toolpath=None, **kwargs) -> SCons.Tool.Tool:
+    def Tool(
+        self, tool: Union[str, Callable], toolpath: Optional[Collection[str]] = None, **kwargs
+    ) -> Callable:
         """Find and run tool module *tool*.
 
+        *tool* is generally a string, but can also be a callable object,
+        in which case it is just called, without any of the setup.
+        The skipped setup includes storing *kwargs* into the created
+        :class:`~SCons.Tool.Tool` instance, which is extracted and used
+        when the instance is called, so in the skip case, the called
+        object will not get the *kwargs*.
+
         .. versionchanged:: 4.2
-           returns the tool module rather than ``None``.
+           returns the tool object rather than ``None``.
         """
         if is_String(tool):
             tool = self.subst(tool)

SCons/Environment.xml

@@ -241,8 +241,11 @@ for more information).
 <cvar name="TOOLS">
 <summary>
 <para>
-A list of the names of the Tool specifications
-that are part of this construction environment.
+A list of the names of the Tool specification modules
+that were actually initialized in the current &consenv;.
+This may be useful as a diagnostic aid
+to see if a tool did (or did not) run.
+The value is informative and is not guaranteed to be complete.
 </para>
 </summary>
 </cvar>
@@ -3437,32 +3440,43 @@ source_nodes = env.subst('$EXPAND_TO_NODELIST', conv=lambda x: x)
 <para>
 Locates the tool specification module <parameter>name</parameter>
 and returns a callable tool object for that tool.
-The tool module is searched for in standard locations
-and in any paths specified by the optional
-<parameter>toolpath</parameter> parameter.
-The standard locations are &SCons;' own internal
-path for tools plus the toolpath, if any (see the
-<emphasis role="bold">Tools</emphasis> section in the manual page
-for more details).
-Any additional keyword arguments
-<parameter>kwargs</parameter> are passed
-to the tool module's <function>generate</function> function
-during tool object construction.
+When the environment method (&f-env-Tool;) form is used,
+the tool object is automatically called before the method returns
+to update <varname>env</varname>,
+and <parameter>name</parameter> is
+appended to the &cv-link-TOOLS;
+&consvar; in that environment.
+When the global function &f-Tool; form is used,
+the tool object is constructed but not called,
+as it lacks the context of an environment to update,
+and the returned object needs to be used to arrange for the call.
 </para>
 
 <para>
-When called, the tool object
-updates a &consenv; with &consvars; and arranges
+The tool module is searched for in the tool search paths (see the
+<emphasis role="bold">Tools</emphasis> section in the manual page
+for details)
+and in any paths specified by the optional
+<parameter>toolpath</parameter> parameter,
+which must be a list of strings.
+If <parameter>toolpath</parameter> is omitted,
+the <parameter>toolpath</parameter>
+supplied when the environment was created,
+if any, is used.
+</para>
+
+<para>
+Any remaining keyword arguments are saved in
+the tool object,
+and will be passed to the tool module's
+<function>generate</function> function
+when the tool object is actually called.
+The <function>generate</function> function
+can update the &consenv; with &consvars; and arrange
 any other initialization
-needed to use the mechanisms that tool describes.
-</para>
-
-<para>
-When the &f-env-Tool; form is used,
-the tool object is automatically called to update <varname>env</varname>
-and the value of <parameter>tool</parameter> is
-appended to the &cv-link-TOOLS;
-&consvar; in that environment.
+needed to use the mechanisms that tool describes,
+and can use these extra arguments to help
+guide its actions.
 </para>
 
 <para>
@@ -3481,10 +3495,7 @@ env.Tool('opengl', toolpath=['build/tools'])
 </example_commands>
 
 <para>
-When the global function &f-Tool; form is used,
-the tool object is constructed but not called,
-as it lacks the context of an environment to update.
-The tool object can be passed to an
+The returned tool object can be passed to an
 &f-link-Environment; or &f-link-Clone; call
 as part of the <parameter>tools</parameter> keyword argument,
 in which case the tool is applied to the environment being constructed,

SCons/Tool/ToolTests.py

@@ -39,6 +39,9 @@ def Detect(self, progs):
         return progs[0]
     def Append(self, **kw) -> None:
         self.dict.update(kw)
+    # Adding a tool now calls AppendUnique so we need a mocked one. Since
+    # the only usage is adding one tool, using Append is good enough.
+    AppendUnique = Append
     def __getitem__(self, key):
         return self.dict[key]
     def __setitem__(self, key, val) -> None:

SCons/Tool/__init__.py

@@ -251,7 +251,7 @@ def __call__(self, env, *args, **kw) -> None:
                 kw.update(call_kw)
             else:
                 kw = self.init_kw
-        env.Append(TOOLS=[self.name])
+        env.AppendUnique(TOOLS=[self.name])
         if hasattr(self, 'options'):
             import SCons.Variables
             if 'options' not in env: