diff --git a/CHANGES.txt b/CHANGES.txt index 15c48f6d61..0bbbfdf3ba 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -37,6 +37,7 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER real reason it shouldn't keep working - add to `__all__`. - Switch SCons build to use setuptools' supported version fetcher from the old homegrown one. + - Improve wording of manpage "Functions and Environment Methods" section. RELEASE 4.8.0 - Sun, 07 Jul 2024 17:22:20 -0700 diff --git a/RELEASE.txt b/RELEASE.txt index 887ceb2eff..534727d66c 100644 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -62,9 +62,7 @@ PACKAGING DOCUMENTATION ------------- -- List any significant changes to the documentation (not individual - typo fixes, even if they're mentioned in src/CHANGES.txt to give - the contributor credit) +- Improve wording of manpage "Functions and Environment Methods" section. DEVELOPMENT ----------- diff --git a/doc/man/scons.xml b/doc/man/scons.xml index ea518c84c5..cea021c996 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -2519,7 +2519,7 @@ that can be used in &SConscript; files. Quick links: Construction Environments Tools Builder Methods - Methods and Functions to do Things + Functions and Environment Methods SConscript Variables Construction Variables Configure Contexts @@ -3384,89 +3384,98 @@ object. - -Methods and Functions To Do Things + +&SCons; Functions and Environment Methods -In addition to Builder methods, -&scons; -provides a number of other &consenv; methods -and global functions to -manipulate the build configuration. -Usually, a &consenv; method -and global function with the same name both exist -for convenience. -In the following list, the global function -is documented in this style: + +&SCons; provides a variety of &consenv; methods +and global functions to manipulate the build configuration. +Often, a &consenv; method and a global function with +the same name exist for convenience. +In this section, both forms are shown if the function can be called +in either way. +The documentation style for these is as follows: + -Function(arguments, [optional arguments]) +Function(arguments, [optional arguments, ...]) # Global function +env.Function(arguments, [optional arguments, ...]) # Environment method -and the &consenv; method looks like: - - -env.Function(arguments, [optional arguments]) - + +In these function signatures, +arguments in brackets ([]) are optional, +and ellipses (...) indicate possible repetition. +Positional vs. keyword arguments are usually detailed +in the following text, not in the signature itself. +The &Python; positional-only (/) +and keyword-only (*) markers are not used. + -If the function can be called both ways, -then both forms are listed. + +When the &Python; keyword=value style is shown, +it can have two meanings. +If the keyword argument is known to the function, +the value is the default for that argument if it is omitted. +If the keyword is unknown to the function, +some methods treat it as a &consvar; assignment; +otherwise an exception is raised for an unknown argument. + -The global function and same-named -&consenv; method -provide almost identical functionality, with a couple of exceptions. -First, many of the &consenv; methods affect only that -&consenv;, while the global function has a -global effect (or, alternatively, takes an additional -positional argument to specify the affected &consenv;). -Second, where appropriate, -calling the functionality through a &consenv; will -substitute &consvars; into -any supplied string arguments, while the global function, -unless it takes a &consenv; parameter, -does not have the context of a &consenv; to pick variables from, -and thus cannot perform substitutions. -For example: + +A global function and a same-named &consenv; method +have the same base functionality, +with two key differences: + - -Default('$FOO') + + + +&Consenv; methods that change the environment +act on the environment instance from which they are called, +while the corresponding global function acts on +a special “hidden” &consenv; called the Default Environment. +In some cases, the global function may take +an initial argument giving the object to operate on. + + + + +String-valued arguments +(including strings in list-valued arguments) +are subject to construction variable expansion +by the environment method form; +variable expansion is not immediately performed in the global function. +For example, Default('$MYTARGET') +adds '$MYTARGET' to the +list of default targets, +while if the value in env of +MYTARGET is 'mine', +env.Default('$MYTARGET' adds +'mine' +to the default targets. +For more details on &consvar; expansion, see the +&Consvars; section. + + + -env = Environment(FOO='foo') -env.Default('$FOO') - - -In the above example, -the call to the global &f-Default; -function will add a target named -$FOO -to the list of default targets, -while the call to the -&f-env-Default; &consenv; method -will expand the value -and add a target named -foo -to the list of default targets. -For more on &consvar; expansion, -see the -&Consvars; -section below. - - - -Global functions are automatically in scope inside -&SConscript; files. -If you have custom &Python; code that you import into an &SConscript; file, -such code will need to bring them into their own scope. -You can do that by adding the following import -to the &Python; module: + +Global functions are automatically in scope inside &SConscript; files. +If your project adds &Python; modules that you include +via the &Python; import statement +from an &SConscript; file, +such code will need to add the functions +to that module’s global scope explicitly. +You can do that by adding the following import to the &Python; module: +from SCons.Script import *. + - -from SCons.Script import * - + +&SCons; provides the following &consenv; methods and global functions. +The list can be augmented on a project basis using &f-link-AddMethod; + -&Consenv; methods -and global functions provided by -&scons; -include: