Merge pull request #4602 from mwichmann/doc/guide-env

Tweak User Guide environment descriptions

CHANGES.txt

@@ -47,6 +47,7 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       Note: on Windows, SCons currently only has builtin support for
       clang, not for clang-cl, the version of the frontend that uses
       cl.exe-compatible command line switches.
+    - Some clarifications in the User Guide "Environments" chapter.
 
 
 RELEASE 4.8.1 -  Tue, 03 Sep 2024 17:22:20 -0700

RELEASE.txt

@@ -29,7 +29,7 @@ CHANGED/ENHANCED EXISTING FUNCTIONALITY
 - List modifications to existing features, where the previous behavior
   wouldn't actually be considered a bug
 
-- Override envirionments, created when giving construction environment
+- Override environments, created when giving construction environment
   keyword arguments to Builder calls (or manually, through the
   undocumented Override method), were modified not to "leak" on item deletion.
   The item will now not be deleted from the base environment.
@@ -77,6 +77,8 @@ DOCUMENTATION
   typo fixes, even if they're mentioned in src/CHANGES.txt to give
   the contributor credit)
 
+- Some clarifications in the User Guide "Environments" chapter.
+
 DEVELOPMENT
 -----------
 

SCons/EnvironmentTests.py

@@ -1037,7 +1037,8 @@ def test_BuilderWrapper_attributes(self) -> None:
     # underlying method it tests (Environment.BuilderWrapper.execute())
     # is necessary, but we're leaving the code here for now in case
     # that's mistaken.
-    def _DO_NOT_test_Builder_execs(self) -> None:
+    @unittest.skip("BuilderWrapper.execute method not needed")
+    def test_Builder_execs(self) -> None:
         """Test Builder execution through different environments
 
         One environment is initialized with a single
@@ -1291,10 +1292,14 @@ def RDirs(pathlist, fs=env.fs):
         ]
         assert flags == expect, flags
 
-        env.Replace(F77PATH = [ 'foo', '$FOO/bar', blat ],
-                    INCPREFIX = 'foo ',
-                    INCSUFFIX = 'bar',
-                    FOO = 'baz')
+        # do a Replace using the dict form
+        newvalues = {
+            "F77PATH": ['foo', '$FOO/bar', blat],
+            "INCPREFIX": 'foo ',
+            "INCSUFFIX": 'bar',
+            "FOO": 'baz',
+        }
+        env.Replace(**newvalues)
         flags = env.subst_list('$_F77INCFLAGS', 1)[0]
         expect = [ '$(',
                    normalize_path('foo'),

SCons/Subst.xml

@@ -31,16 +31,16 @@ This file is processed by the bin/SConsDoc.py module.
 </arguments>
 <summary>
 <para>
-Specifies the exceptions that will be allowed
-when expanding construction variables.
+Specifies the exceptions that will be ignored
+when expanding &consvars;.
 By default,
-any construction variable expansions that generate a
-<literal>NameError</literal>
+any &consvar; expansions that generate a
+&NameError;
 or
-<literal>IndexError</literal>
+&IndexError;
 exception will expand to a
 <literal>''</literal>
-(an empty string) and not cause scons to fail.
+(an empty string) and not cause &scons; to fail.
 All exceptions not in the specified list
 will generate an error message
 and terminate processing.
@@ -51,7 +51,8 @@ If
 &f-AllowSubstExceptions;
 is called multiple times,
 each call completely overwrites the previous list
-of allowed exceptions.
+of ignored exceptions.
+Calling it with no arguments means no exceptions will be ignored.
 </para>
 
 <para>

doc/generated/functions.gen

@@ -405,16 +405,16 @@ env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
   <varlistentry id="f-AllowSubstExceptions">
     <term><function>AllowSubstExceptions</function>(<parameter>[exception, ...]</parameter>)</term>
     <listitem><para>
-Specifies the exceptions that will be allowed
-when expanding construction variables.
+Specifies the exceptions that will be ignored
+when expanding &consvars;.
 By default,
-any construction variable expansions that generate a
-<literal>NameError</literal>
+any &consvar; expansions that generate a
+&NameError;
 or
-<literal>IndexError</literal>
+&IndexError;
 exception will expand to a
 <literal>''</literal>
-(an empty string) and not cause scons to fail.
+(an empty string) and not cause &scons; to fail.
 All exceptions not in the specified list
 will generate an error message
 and terminate processing.
@@ -425,7 +425,8 @@ If
 &f-AllowSubstExceptions;
 is called multiple times,
 each call completely overwrites the previous list
-of allowed exceptions.
+of ignored exceptions.
+Calling it with no arguments means no exceptions will be ignored.
 </para>
 
 <para>
@@ -1634,6 +1635,19 @@ Example:
 cvars = env.Dictionary()
 cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
 </example_commands>
+
+<note><para>
+The object returned by &f-link-env-Dictionary; should be treated
+as a read-only view into the &consvars;.
+Some &consvars; have special internal handling,
+and making changes through the &f-env-Dictionary; object can bypass
+that handling and cause data inconsistencies.
+The primary use of &f-env-Dictionary; is for diagnostic purposes -
+it is used widely by test cases specifically because
+it bypasses the special handling so that behavior
+can be verified.
+</para></note>
+
 </listitem>
   </varlistentry>
   <varlistentry id="f-Dir">

doc/generated/variables.gen

@@ -9651,23 +9651,53 @@ The suffix used for tar file names.
       <envar>TEMPFILE</envar>
     </term>
     <listitem><para>
-A callable object used to handle overly long command line strings,
-since operations which call out to a shell will fail
-if the line is longer than the shell can accept.
-This tends to particularly impact linking.
-The tempfile object stores the command line in a temporary
-file in the appropriate format, and returns
-an alternate command line so the invoked tool will make
-use of the contents of the temporary file.
-If you need to replace the default tempfile object,
-the callable should take into account the settings of
+Holds a callable object which will be invoked to transform long
+command lines (string or list) into an alternate form.
+Length limits on various operating systems
+may cause long command lines to fail when calling out to
+a shell to run the command.
+Most often affects linking, when there are many object files and/or
+libraries to be linked, but may also affect other
+compilation steps which have many arguments.
+&cv-TEMPFILE; is not called directly,
+but rather is typically embedded in another
+&consvar;, to be expanded when used. Example:
+</para>
+
+<example_commands>
+env["TEMPFILE"] = TempFileMunge
+env["LINKCOM"] = "${TEMPFILE('$LINK $TARGET $SOURCES', '$LINKCOMSTR')}"
+</example_commands>
+
+<para>
+The SCons default value for &cv-TEMPFILE;,
+<classname>TempFileMunge</classname>,
+performs command substitution on the passed command line,
+calculates whether modification is needed,
+then puts all but the first word (assumed to be the command name)
+of the resulting list into a temporary file
+(sometimes called a response file or command file),
+and returns a new command line consisting of the
+the command name and an appropriately formatted reference
+to the temporary file.
+</para>
+
+<para>
+A replacement for the default tempfile object would need
+to do fundamentally the same thing, including taking into account
+the values of
 &cv-link-MAXLINELENGTH;,
 &cv-link-TEMPFILEPREFIX;,
 &cv-link-TEMPFILESUFFIX;,
 &cv-link-TEMPFILEARGJOIN;,
 &cv-link-TEMPFILEDIR;
 and
 &cv-link-TEMPFILEARGESCFUNC;.
+If a particular use case requires a different transformation
+than the default, it is recommended to copy the mechanism and
+define a new &consvar; and rewrite the relevant <literal>*COM</literal>
+variable(s) to use it, to avoid possibly disrupting existing uses
+of &cv-TEMPFILE;.
 </para>
 </listitem>
   </varlistentry>
@@ -9726,6 +9756,9 @@ Note this value is used literally and not expanded by the subst logic.
     </term>
     <listitem><para>
 The directory to create the long-lines temporary file in.
+If unset, some suitable default should be chosen.
+The default tempfile object lets the &Python;
+<systemitem>tempfile</systemitem> module choose.
 </para>
 </listitem>
   </varlistentry>
@@ -9736,6 +9769,8 @@ The directory to create the long-lines temporary file in.
     <listitem><para>
 The prefix for the name of the temporary file used
 to store command lines exceeding &cv-link-MAXLINELENGTH;.
+The prefix must include the compiler syntax to actually
+include and process the file.
 The default prefix is <literal>'@'</literal>, which works for the &MSVC;
 and GNU toolchains on Windows.
 Set this appropriately for other toolchains,
@@ -9751,7 +9786,7 @@ or <literal>'-via'</literal> for ARM toolchain.
     <listitem><para>
 The suffix for the name of the temporary file used
 to store command lines exceeding &cv-link-MAXLINELENGTH;.
-The suffix should include the dot ('.') if one is wanted as
+The suffix should include the dot ('.') if one is needed as
 it will not be added automatically.
 The default is <filename>.lnk</filename>.
 </para>

doc/scons.mod

@@ -308,8 +308,10 @@ This file is processed by the bin/SConsDoc.py module.
 
 <!-- Python functions and classes -->
 
-<!ENTITY IndexError "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>IndexError</classname>">
-<!ENTITY NameError "<classname xmlns='http://www.scons.org/dbxsd/v1.0'>NameError</classname>">
+<!ENTITY AttributeError "<exceptionname xmlns='http://www.scons.org/dbxsd/v1.0'>AttributeError</exceptionname>">
+<!ENTITY IndexError "<exceptionname xmlns='http://www.scons.org/dbxsd/v1.0'>IndexError</exceptionname>">
+<!ENTITY KeyError "<exceptionname xmlns='http://www.scons.org/dbxsd/v1.0'>KeyError</exceptionname>">
+<!ENTITY NameError "<exceptionname xmlns='http://www.scons.org/dbxsd/v1.0'>NameError</exceptionname>">
 <!ENTITY str "<function xmlns='http://www.scons.org/dbxsd/v1.0'>str</function>">
 <!ENTITY zipfile "<function xmlns='http://www.scons.org/dbxsd/v1.0'>zipfile</function>">
 

doc/user/command-line.xml

@@ -874,7 +874,7 @@ prog.c
           <methodname>get</methodname> method,
           so you can supply a default value if the variable is
           not given on the command line. Otherwise, the build
-          will fail with a <exceptionname>KeyError</exceptionname>
+          will fail with a &KeyError;
           if the variable is not set.
         </para>
       </listitem>