From ce316de1c22a841966d4f8a6823b8286a8970986 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 26 Jul 2023 08:51:10 -0600 Subject: Docs tweaking [skip appveyor] Two separate topics, combined for convenince. * use consistent wording for version-added: "New in" rather than "Added in" to match the sphinx :versionadded: macro. * Tweak wording around DefaultEnvironment, both manpage and docstring. Some "nearby" docstrings in SCons/Defaults.py also got some markup improvements. Signed-off-by: Mats Wichmann --- SCons/Defaults.py | 63 ++++++++++++++++++-------------------- SCons/Defaults.xml | 55 ++++++++++++++++++++------------- SCons/Tool/packaging/packaging.xml | 4 ++- SCons/Tool/textfile.xml | 7 +++-- doc/man/scons.xml | 4 +-- 5 files changed, 74 insertions(+), 59 deletions(-) diff --git a/SCons/Defaults.py b/SCons/Defaults.py index ae5de89..cabadcc 100644 --- a/SCons/Defaults.py +++ b/SCons/Defaults.py @@ -58,31 +58,28 @@ _default_env = None # Lazily instantiate the default environment so the overhead of creating # it doesn't apply when it's not needed. -def _fetch_DefaultEnvironment(*args, **kw): +def _fetch_DefaultEnvironment(*args, **kwargs): """Returns the already-created default construction environment.""" - global _default_env return _default_env -def DefaultEnvironment(*args, **kw): - """ - Initial public entry point for creating the default construction - Environment. - - After creating the environment, we overwrite our name - (DefaultEnvironment) with the _fetch_DefaultEnvironment() function, - which more efficiently returns the initialized default construction - environment without checking for its existence. - - (This function still exists with its _default_check because someone - else (*cough* Script/__init__.py *cough*) may keep a reference - to this function. So we can't use the fully functional idiom of - having the name originally be a something that *only* creates the - construction environment and then overwrites the name.) +def DefaultEnvironment(*args, **kwargs): + """Construct the global ("default") construction environment. + + The environment is provisioned with the values from *kwargs*. + + After the environment is created, this function is replaced with + a reference to :func:`_fetch_DefaultEnvironment` which efficiently + returns the initialized default construction environment without + checking for its existence. + + Historically, some parts of the code held references to this function. + Thus it still has the existence check for :data:`_default_env` rather + than just blindly creating the environment and overwriting itself. """ global _default_env if not _default_env: - _default_env = SCons.Environment.Environment(*args, **kw) + _default_env = SCons.Environment.Environment(*args, **kwargs) _default_env.Decider('content') global DefaultEnvironment DefaultEnvironment = _fetch_DefaultEnvironment @@ -591,15 +588,13 @@ def _defines(prefix, defs, suffix, env, target=None, source=None, c=_concat_ixes class NullCmdGenerator: - """This is a callable class that can be used in place of other - command generators if you don't want them to do anything. + """Callable class for use as a no-effect command generator. - The __call__ method for this class simply returns the thing - you instantiated it with. + The ``__call__`` method for this class simply returns the thing + you instantiated it with. Example usage:: - Example usage: - env["DO_NOTHING"] = NullCmdGenerator - env["LINKCOM"] = "${DO_NOTHING('$LINK $SOURCES $TARGET')}" + env["DO_NOTHING"] = NullCmdGenerator + env["LINKCOM"] = "${DO_NOTHING('$LINK $SOURCES $TARGET')}" """ def __init__(self, cmd) -> None: @@ -613,13 +608,15 @@ class Variable_Method_Caller: """A class for finding a construction variable on the stack and calling one of its methods. - We use this to support "construction variables" in our string - eval()s that actually stand in for methods--specifically, use - of "RDirs" in call to _concat that should actually execute the - "TARGET.RDirs" method. (We used to support this by creating a little - "build dictionary" that mapped RDirs to the method, but this got in - the way of Memoizing construction environments, because we had to - create new environment objects to hold the variables.) + Used to support "construction variables" appearing in string + ``eval``s that actually stand in for methods--specifically, the use + of "RDirs" in a call to :func:`_concat` that should actually execute the + ``TARGET.RDirs`` method. + + Historical note: This was formerly supported by creating a little + "build dictionary" that mapped RDirs to the method, but this got + in the way of Memoizing construction environments, because we had to + create new environment objects to hold the variables. """ def __init__(self, variable, method) -> None: @@ -677,7 +674,7 @@ def __lib_either_version_flag(env, version_var1, version_var2, flags_var): return None - + ConstructionEnvironment = { diff --git a/SCons/Defaults.xml b/SCons/Defaults.xml index 7b37475..b892f2e 100644 --- a/SCons/Defaults.xml +++ b/SCons/Defaults.xml @@ -243,7 +243,7 @@ to each directory in &cv-link-CPPPATH;. The list of directories that the C preprocessor will search for include directories. The C/C++ implicit dependency scanner will search these -directories for include files. +directories for include files. In general it's not advised to put include directory directives directly into &cv-link-CCFLAGS; or &cv-link-CXXFLAGS; as the result will be non-portable @@ -257,9 +257,9 @@ Python's os.sep. Note: directory names in &cv-CPPPATH; will be looked-up relative to the directory of the SConscript file -when they are used in a command. +when they are used in a command. To force &scons; -to look-up a directory relative to the root of the source tree use +to look-up a directory relative to the root of the source tree use the # prefix: @@ -529,9 +529,9 @@ as the result will be non-portable. Note: directory names in &cv-LIBPATH; will be looked-up relative to the directory of the SConscript file -when they are used in a command. +when they are used in a command. To force &scons; -to look-up a directory relative to the root of the source tree use +to look-up a directory relative to the root of the source tree use the # prefix: @@ -575,7 +575,7 @@ env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE A list of one or more libraries that will be added to the link line -for linking with any executable program, shared library, or loadable module +for linking with any executable program, shared library, or loadable module created by the &consenv; or override. @@ -647,26 +647,39 @@ searching the repositories. -Instantiates and returns the default &consenv; object. -The &defenv; is used internally by SCons -in order to execute many of the global functions in this list +Instantiates and returns the global &consenv; object. +This environment is used internally by SCons +when it executes many of the global functions listed in this section (that is, those not called as methods of a specific &consenv;). +The &defenv; is a singleton: +the keyword arguments are used only on the first call; +on subsequent calls the already-constructed object is returned +and any keyword arguments are silently ignored. +The &defenv; can still be modified after instantiation +in the same way as any other &consenv;. +The &defenv; is independent: +modifying it has no effect on any other &consenv; +constructed by an &f-link-Environment; or &f-link-Clone; call. + + + It is not mandatory to call &f-DefaultEnvironment;: -the &defenv; will be instantiated automatically when the -build phase begins if the function has not been called, +the &defenv; is instantiated automatically when the +build phase begins if this function has not been called; however calling it explicitly gives the opportunity to affect and examine the contents of the &defenv;. +Instantiation happens even if no build instructions +appar to use it, as there are internal uses. +If there are no uses in the project &SConscript; files, +a small performance gain may be seen by calling +&f-DefaultEnvironment; with an empty tools list, +thus avoiding that part of the initialization cost. +This is mainly of interest in testing when &scons; is +launched repeatedly in a short time period: - -The &defenv; is a singleton, so the keyword -arguments affect it only on the first call, on subsequent -calls the already-constructed object is returned and -any keyword arguments are silently ignored. -The &defenv; can be modified after instantiation -in the same way as any &consenv;. -Modifying the &defenv; has no effect on the &consenv; -constructed by an &f-link-Environment; or &f-link-Clone; call. - + +DefaultEnvironment(tools=[]) + diff --git a/SCons/Tool/packaging/packaging.xml b/SCons/Tool/packaging/packaging.xml index 8516ca5..b248880 100644 --- a/SCons/Tool/packaging/packaging.xml +++ b/SCons/Tool/packaging/packaging.xml @@ -552,7 +552,9 @@ to disable debug package generation. To enable debug package generation, include this variable set either to None, or to a custom list that does not include the default line. -Added in version 3.1. + + +New in version 3.1. diff --git a/SCons/Tool/textfile.xml b/SCons/Tool/textfile.xml index 557be5b..c41ee2a 100644 --- a/SCons/Tool/textfile.xml +++ b/SCons/Tool/textfile.xml @@ -271,8 +271,11 @@ The suffix used for &b-link-Textfile; file names; -File encoding used for files written by &b-link-Textfile; and &b-link-Substfile;. Set to "utf-8" by default. -Added in version 4.5.0. +File encoding used for files written by &b-link-Textfile; and &b-link-Substfile;. +Set to "utf-8" by default. + + +New in version 4.5.0. diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 80d16c0..4a422be 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -1205,8 +1205,8 @@ the mechanisms in the specified order. A comma-separated string can be used to select multiple features. The default setting is none. Current available features are: - ninja (added in version 4.2), - tm_v2 (added in version 4.4.1). + ninja (New in version 4.2), + tm_v2 (New in version 4.4.1). No Support offered for any features or tools enabled by this flag. -- cgit v0.12