Merge pull request #4856 from mwichmann/doc/implicit-deps

Tweak IMPLICIT_COMMAND_DEPENDENCIES man entry

Author: bdbaddog

CHANGES.txt

@@ -47,15 +47,14 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
 
   From Mats Wichmann:
     - Introduce some unit tests for the file locking utility routines
-    - More clarifications in manpage Builder Methods section.
     - Reduce unneeded computation of overrides. The Mkdir builder used an
       unknown argument ('explain') on creation, causing it to be considered
       an override. Also, if override dict is empty, don't even call the
       Override factory function.
     - Handle the default (unset) ProgressObject differently for the sole
       purpose of avoiding Sphinx 9.0+ blowing up on it (it's been giving
       a warning for years, but now it's a fatal error).
-    - Improve covarage of API doc build by ignoring any setting of
+    - Improve coverage of API doc build by ignoring any setting of
       __all__ in a package and not showing inherited members from optparse.
     - Fix --debug=includes for case of multiple source files.
     - Unify internal "_null" sentinel usage.
@@ -79,21 +78,23 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
     - Adjust race protection for CacheDir - now uses a unique temporary
       directory for each writer before doing the move, instead of depending
       on a one-time uuid to make a path to the file.
-    - Clarify VariantDir behavior when switching to not duplicate sources
-      and tweak wording a bit.
     - Test suite: add support for Python 3.15 in the Action unit tests.
-    - Update documentation of the three file-finding functions in the API
-      (FindFile, FindInstalledFiles, FindSourceFiles) as well as FindPathDirs.
-      Also add a test for FindFile to be sure it locates non-existing
-      derived files as advertised.
+    - Add a test for FindFile to be sure it locates non-existing derived
+      files as advertised.
     - zip tool now uses zipfile module's "from_file" method to populate
       ZipInfo records, rather than doing manually.
-    - Update documentation for linking-related construction variables.
-      Add a few more live links.
-    - Update documentation for CacheDir and related option flags
-    - Drop old example section from manpage. This has been commented out
-      since release 4.0, when the content was used to populate the new
-      SCons Cookbook.
+    - Reference manual improvements:
+      * More clarifications in Builder Methods section.
+      * Clarify VariantDir behavior when switching from duplicate=True (the
+        default) to duplicate=False, and tweak wording a bit.
+      * Update documentation of the three file-finding functions (FindFile,
+        FindInstalledFiles, FindSourceFiles) as well as FindPathDirs.
+      * Update linking-related construction variables.
+      * Add a few more live links.
+      * Clarify CacheDir and related option flags.
+      * Drop old example section from manpage (not a visible change: has been
+        commented out since v4.0, when the content moved to the new Cookbook)
+      * Reword IMPLICIT_COMMAND_DEPENDENCIES construction variable.
 
 
 RELEASE 4.10.1 - Sun, 16 Nov 2025 10:51:57 -0700

RELEASE.txt

@@ -133,6 +133,8 @@ DOCUMENTATION
 - Drop old example section from manpage. This has been commented out since
   release 4.0, when the content was used to populate the new SCons Cookbook.
 
+- Update documentation for IMPLICIT_COMMAND_DEPENDENCIES construction variable.
+
 DEVELOPMENT
 -----------
 

SCons/Action.xml

@@ -27,109 +27,66 @@ This file is processed by the bin/SConsDoc.py module.
 <cvar name="IMPLICIT_COMMAND_DEPENDENCIES">
 <summary>
 <para>
-Controls whether or not &SCons; will
-add implicit dependencies for the commands
-executed to build targets.
+Controls how &SCons; adds implicit dependencies from action strings
+(the commands executed to build targets).
+These implicit dependencies allow &SCons; to trigger target rebuilds
+when the compilers, tools, or scripts that affect build outcomes change
+(for example, when a new version of a compiler is installed).
+By default, &SCons; adds an implicit dependency on the executable
+represented by the first argument of the command line.
+This executable is first checked as a path;
+if not found, it is searched for in the execution environment's search path
+(<literal>env['ENV']['PATH']</literal>).
 </para>
 
 <para>
-By default, &SCons; will add to each target
-an implicit dependency on the command
-represented by the first argument of any
-command line it executes (which is typically
-the command itself). By setting such
-a dependency, &SCons; can determine that
-a target should be rebuilt if the command changes,
-such as when a compiler is upgraded to a new version.
-The specific file for the dependency is
-found by searching the
-<varname>PATH</varname>
-variable in the
-<varname>ENV</varname> dictionary
-in the &consenv; used to execute the command.
-The default is the same as
-setting the &consvar;
+If &cv-IMPLICIT_COMMAND_DEPENDENCIES; is set to a falsy value
+(<literal>"none"</literal>, <literal>"false"</literal>,
+<literal>"no"</literal>, <literal>"off"</literal>,
+<literal>"0"</literal> or integer <literal>0</literal>),
+no implicit dependencies from action strings are added.
+If set to an integer value greater than <literal>1</literal>,
+or to <literal>"all"</literal>,
+additional command-line arguments are checked.
+A numeric value <emphasis>N</emphasis>
+checks the first <emphasis>N</emphasis> arguments,
+while <literal>"all"</literal> checks every argument.
+A checked argument beyond the first is added as a dependency
+if it is an absolute path or it refers to
+an existing file in the filesystem;
+unlike the first argument, these additional arguments are not searched
+using the execution environment's search path.
+All other values of &cv-IMPLICIT_COMMAND_DEPENDENCIES;
+are treated the same as the default.
+The value of
 &cv-IMPLICIT_COMMAND_DEPENDENCIES;
-to a True-like value (<quote>true</quote>,
-<quote>yes</quote>,
-or <quote>1</quote> - but not a number
-greater than one, as that has a different meaning).
+is subject to substitution before it is used,
+so it can contain a &consvar; reference.
 </para>
 
 <para>
-Action strings can be segmented by the
-use of an AND operator, <literal>&amp;&amp;</literal>.
-In a segmented string, each segment is a separate
-<quote>command line</quote>, these are run
-sequentially until one fails, or the entire
-sequence has been executed. If an
-action string is segmented, then the selected
-behavior of &cv-IMPLICIT_COMMAND_DEPENDENCIES;
-is applied to each segment.
+Action strings may be segmented with a logical AND operator
+(<literal>&amp;&amp;</literal>),
+indicating each segment is executed sequentially,
+but only if the previous segment succeeded.
+If &cv-IMPLICIT_COMMAND_DEPENDENCIES; is set to
+<literal>"all"</literal> or an integer greater than <literal>1</literal>,
+each segment is treated as a separate command line
+for computing dependencies;
+otherwise, only the first segment is checked.
 </para>
-
-<para>
-If &cv-IMPLICIT_COMMAND_DEPENDENCIES;
-is set to a False-like value
-(<quote>none</quote>,
-<quote>false</quote>,
-<quote>no</quote>,
-<quote>0</quote>,
-etc.),
-then the implicit dependency will
-not be added to the targets
-built with that &consenv;.
-</para>
-
-<para>
-If &cv-IMPLICIT_COMMAND_DEPENDENCIES;
-is set to <quote>2</quote> or higher,
-then that number of arguments in the command line
-will be scanned for relative or absolute paths.
-If any are present, they will be added as
-implicit dependencies to the targets built
-with that &consenv;.
-The first argument in the command line will be
-searched for using the <varname>PATH</varname>
-variable in the <varname>ENV</varname> dictionary
-in the &consenv; used to execute the command.
-The other arguments will only be found if they
-are absolute paths or valid paths relative
-to the working directory.
-</para>
-
-<para>
-If &cv-IMPLICIT_COMMAND_DEPENDENCIES;
-is set to <quote>all</quote>,
-then all arguments in the command line will be
-scanned for relative or absolute paths.
-If any are present, they will be added as
-implicit dependencies to the targets built
-with that &consenv;.
-The first argument in the command line will be
-searched for using the <varname>PATH</varname>
-variable in the <varname>ENV</varname> dictionary
-in the &consenv; used to execute the command.
-The other arguments will only be found if they
-are absolute paths or valid paths relative
-to the working directory.
-</para>
-
-<example_commands>
-env = Environment(IMPLICIT_COMMAND_DEPENDENCIES=False)
-</example_commands>
 </summary>
 </cvar>
 
 <cvar name="PRINT_CMD_LINE_FUNC">
 <summary>
 <para>
-A Python function used to print the command lines as they are executed
-(assuming command printing is not disabled by the
-<option>-q</option>
+A &Python; function used to print the command lines as they are executed
+(unless command printing is disabled by the
+<link linkend="opt-question"><option>-q</option>/<option>--question</option></link>
 or
-<option>-s</option>
-options or their equivalents).
+<link linkend="opt-silent"><option>-s</option>/<option>--silent</option></link>
+options).
 The function must accept four arguments:
 <varname>s</varname>,
 <varname>target</varname>,

SCons/Defaults.xml

@@ -266,8 +266,8 @@ directly into &cv-link-CCFLAGS; or &cv-link-CXXFLAGS;
 as the result will be non-portable
 and the directories will not be searched by the dependency scanner.
 &cv-CPPPATH; should be a list of path strings,
-or a single string, not a pathname list joined by
-Python's <systemitem>os.pathsep</systemitem>.
+or a single string, not a pathname list joined by the
+&Python; <systemitem>os.pathsep</systemitem> character.
 </para>
 
 <para>
@@ -527,7 +527,7 @@ The list of directories that will be searched for libraries
 specified by the &cv-link-LIBS; &consvar;.
 &cv-LIBPATH; should be a list of path strings,
 or a single string, not a pathname list joined by
-Python's <systemitem>os.pathsep</systemitem>.
+the &Python; <systemitem>os.pathsep</systemitem> character.
 <!-- XXX OLD
 The implicit dependency scanner will search these
 directories for include files. Don't explicitly put include directory

SCons/Script/Main.xml

@@ -37,7 +37,7 @@ the strings representing how the option can be called,
 while the keyword arguments define attributes of the option.
 For the most part these are the same as for the
 <function>OptionParser.add_option</function>
-method in the standard Python library module
+method in the standard &Python; library module
 <systemitem>optparse</systemitem>,
 but with a few additional capabilities noted below.
 See the
@@ -240,7 +240,7 @@ when the build failure occurred.
 <para>
 <literal>.status</literal>
 The numeric exit status
-returned by the command or Python function
+returned by the command or &Python; function
 that failed when trying to build the
 specified Node.
 </para>
@@ -322,8 +322,8 @@ Its primary intended use is
 for functions that will be
 executed before SCons exits
 by passing them to the
-standard Python
-<function>atexit.register</function>()
+standard &Python;
+<function>atexit.register</function>
 function.
 Example:
 </para>
@@ -706,7 +706,7 @@ evaluating Nodes (e.g. files).
 </para>
 
 <para>
-If the first specified argument is a Python callable
+If the first specified argument is a &Python; callable
 (a function or an object that has a
 <methodname>__call__</methodname> method),
 the function will be called

SCons/Script/SConscript.xml

@@ -90,11 +90,11 @@ env.Default(hello)
 </arguments>
 <summary>
 <para>
-Ensure that the Python version is at least
+Ensure that the &Python; version is at least
 <varname>major</varname>.<varname>minor</varname>.
 This function will
-print out an error message and exit SCons with a non-zero exit code if the
-actual Python version is not late enough.
+print out an error message and exit &SCons; with a non-zero exit code if the
+actual &Python; version is not late enough.
 </para>
 
 <para>

SCons/Tool/msvs.xml

@@ -61,7 +61,7 @@ This file is processed by the bin/SConsDoc.py module.
         Note &SCons; does not know how to construct project files for
         other languages (e.g. <filename>.csproj</filename> for C#,
         <filename>.vbproj</filename> for Visual Basic or
-        <filename>.pyproject</filename> for Python).
+        <filename>.pyproject</filename> for &Python;).
         </para>
       <para>
         For the <filename>.vcxproj</filename> file, the underlying

SCons/Tool/python.xml

@@ -27,9 +27,9 @@ This file is processed by the bin/SConsDoc.py module.
 <tool name="python">
 <summary>
 <para>
-Loads the Python source scanner into the invoking environment.
+Loads the &Python; source scanner into the invoking environment.
 When loaded, the scanner will attempt to find implicit
-dependencies for any Python source files in the list of sources
+dependencies for any &Python; source files in the list of sources
 provided to an Action that uses this environment.
 </para>
 <para><emphasis>Available since &scons; 4.0.</emphasis>.</para>

SCons/Tool/textfile.xml

@@ -56,8 +56,8 @@ value of the
 the line separator is not emitted after the last string.
 Nested lists of source strings
 are flattened.
-Source strings need not literally be Python strings:
-they can be Nodes or Python objects that convert cleanly
+Source strings need not literally be &Python; strings:
+they can be Nodes or &Python; objects that convert cleanly
 to &f-link-Value; nodes.
 </para>
 
@@ -149,7 +149,7 @@ are automatically added to the target if they are not already present.
 
 <para>
 If a construction variable named &cv-link-SUBST_DICT; is present,
-it may be either a Python dictionary or a sequence of
+it may be either a &Python; dictionary or a sequence of
 (<replaceable>key</replaceable>, <replaceable>value</replaceable>) tuples.
 If it is a dictionary it is converted into a list of tuples
 with unspecified order,
@@ -161,7 +161,7 @@ it is unpredictable whether the expansion will occur.
 <para>
 Any occurrences of a key in the source
 are replaced by the corresponding value,
-which may be a Python callable function or a string.
+which may be a &Python; callable function or a string.
 If the value is a callable, it is called with no arguments to get a string.
 Strings are <emphasis>subst</emphasis>-expanded
 and the result replaces the key.

SCons/Tool/zip.xml

@@ -86,7 +86,7 @@ The zip compression and file packaging utility.
 <summary>
 <para>
 The command line used to call the zip utility,
-or the internal Python function used to create a
+or the internal &Python; function used to create a
 zip archive.
 </para>
 </summary>
@@ -98,7 +98,7 @@ zip archive.
 The string displayed when archiving files
 using the zip utility.
 If this is not set, then &cv-link-ZIPCOM;
-(the command line or internal Python function) is displayed.
+(the command line or internal &Python; function) is displayed.
 </para>
 
 <example_commands>
@@ -112,10 +112,9 @@ env = Environment(ZIPCOMSTR = "Zipping $TARGET")
 <para>
 The
 <varname>compression</varname>
-flag
-from the Python
-<filename>zipfile</filename>
-module used by the internal Python function
+flag from the &Python;
+<systemitem>zipfile</systemitem>
+module used by the internal &Python; function
 to control whether the zip archive
 is compressed or not.
 The default value is