From a5c85cf6cda3b01b670fb50b9478f76deebda09f Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 31 Jul 2024 09:15:27 -0600 Subject: [PATCH 1/2] Doc: use consistent repeated-args syntax [skip appveyor] For now, want to keep the "key=value, ..." form for Functions/Method signatures instead of using **kwargs, since that terminology hasn't been introduced. May switch signatures later, but if so, do them all, let's not be piecemeal. Signed-off-by: Mats Wichmann --- CHANGES.txt | 2 ++ SCons/Defaults.xml | 72 ++++++++++++++++++++++++------------------- SCons/Environment.xml | 2 +- SCons/Script/Main.xml | 26 ++++++++++------ 4 files changed, 60 insertions(+), 42 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index 0bbbfdf3ba..ffebcd0cbf 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -38,6 +38,8 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER - Switch SCons build to use setuptools' supported version fetcher from the old homegrown one. - Improve wording of manpage "Functions and Environment Methods" section. + Make doc function signature style more consistent - tweaks to AddOption, + DefaultEnvironment and Tool,. RELEASE 4.8.0 - Sun, 07 Jul 2024 17:22:20 -0700 diff --git a/SCons/Defaults.xml b/SCons/Defaults.xml index c896f69d6d..3e8601f518 100644 --- a/SCons/Defaults.xml +++ b/SCons/Defaults.xml @@ -729,43 +729,53 @@ searching the repositories. -([**kwargs]) +([key=value, ...]) 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 +The &DefEnv; is used internally by &SCons; +when executing a global function +or the global form of a Builder method +that requires access to a &consenv;. + + + +On the first call, +arguments are interpreted as for the &f-link-Environment; function. +The &DefEnv; is a singleton; +subsequent calls to &f-DefaultEnvironment; return +the already-constructed object, 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; 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: - -DefaultEnvironment(tools=[]) - + + +The &DefEnv; can be modified after instantiation, +similar to other &consenvs;, +although some &consenv; methods may be unavailable. +Modifying the &DefEnv; has no effect on any other &consenv;, +either existing or newly constructed. + + + +It is not necessary to explcitly call &f-DefaultEnvironment;. +&SCons; instantiates the &defenv; automatically when the +build phase begins, if has not already been done. +However, calling it explicitly provides the opportunity to +affect and examine its contents. +Instantiation occurs even if nothing in the build system +appars to use it, due to internal uses. + + + +If the project &SConscript; files do not use global functions or Builders, +a small performance gain may be achieved by calling +&f-DefaultEnvironment; with an empty tools list +(DefaultEnvironment(tools=[])). +This avoids the tool initialization cost for the &DefEnv;, +which is mainly of interest in the test suite +where &scons; is launched repeatedly in a short time period. + diff --git a/SCons/Environment.xml b/SCons/Environment.xml index ce73cad6aa..25f0536eed 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -3489,7 +3489,7 @@ source_nodes = env.subst('$EXPAND_TO_NODELIST', conv=lambda x: x) -(name, [toolpath, **kwargs]) +(name, [toolpath, key=value, ...]) diff --git a/SCons/Script/Main.xml b/SCons/Script/Main.xml index 7b5d0ef0be..9dd9609a10 100644 --- a/SCons/Script/Main.xml +++ b/SCons/Script/Main.xml @@ -27,18 +27,25 @@ This file is processed by the bin/SConsDoc.py module. -(arguments) +(opt_str, ..., attr=value, ...) Adds a local (project-specific) command-line option. -arguments -are the same as those supported by the add_option -method in the standard Python library module optparse, -with a few additional capabilities noted below. -See the documentation for -optparse +One or more opt_str values are +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 +OptionParser.add_option +method in the standard Python library module +optparse, +but with a few additional capabilities noted below. +See the + +optparse documentation for a thorough discussion of its option-processing capabities. +All options added through &f-AddOption; are placed +in a special "Local Options" option group. @@ -49,10 +56,9 @@ method, &f-AddOption; allows setting the nargs keyword value to -a string consisting of a question mark -('?') +a string '?' (question mark) to indicate that the option argument for -that option string is optional. +that option string may be omitted. If the option string is present on the command line but has no matching option argument, the value of the From b44c536eff4ecf50c6c07142765cbcf95fc216af Mon Sep 17 00:00:00 2001 From: William Deegan Date: Mon, 5 Aug 2024 20:55:48 -0700 Subject: [PATCH 2/2] added release.txt blurb. Fixed spelling typo in Defaults.xml --- RELEASE.txt | 3 +++ SCons/Defaults.xml | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/RELEASE.txt b/RELEASE.txt index 534727d66c..2efc001214 100644 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -63,6 +63,9 @@ DOCUMENTATION ------------- - Improve wording of manpage "Functions and Environment Methods" section. +- Make doc function signature style more consistent - tweaks to AddOption, + DefaultEnvironment and Tool,. + DEVELOPMENT ----------- diff --git a/SCons/Defaults.xml b/SCons/Defaults.xml index 3e8601f518..933fe9dc94 100644 --- a/SCons/Defaults.xml +++ b/SCons/Defaults.xml @@ -758,7 +758,7 @@ either existing or newly constructed. -It is not necessary to explcitly call &f-DefaultEnvironment;. +It is not necessary to explicitly call &f-DefaultEnvironment;. &SCons; instantiates the &defenv; automatically when the build phase begins, if has not already been done. However, calling it explicitly provides the opportunity to