Skip to content

Commit

Permalink
Merge pull request #4602 from mwichmann/doc/guide-env
Browse files Browse the repository at this point in the history
Tweak User Guide environment descriptions
  • Loading branch information
bdbaddog authored Sep 22, 2024
2 parents 19b49de + a1afc93 commit ccadea6
Show file tree
Hide file tree
Showing 11 changed files with 268 additions and 169 deletions.
1 change: 1 addition & 0 deletions CHANGES.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion RELEASE.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
-----------

Expand Down
15 changes: 10 additions & 5 deletions SCons/EnvironmentTests.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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'),
Expand Down
15 changes: 8 additions & 7 deletions SCons/Subst.xml
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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>
Expand Down
28 changes: 21 additions & 7 deletions doc/generated/functions.gen
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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>
Expand Down Expand Up @@ -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">
Expand Down
57 changes: 46 additions & 11 deletions doc/generated/variables.gen
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand All @@ -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,
Expand All @@ -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>
Expand Down
6 changes: 4 additions & 2 deletions doc/scons.mod
Original file line number Diff line number Diff line change
Expand Up @@ -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>">

Expand Down
2 changes: 1 addition & 1 deletion doc/user/command-line.xml
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
Loading

0 comments on commit ccadea6

Please sign in to comment.