From d6c4a4236512d1310ca5cfe990bd0af71dfe89a9 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Tue, 16 May 2023 09:23:33 -0600 Subject: Doc fiddling - Alias, Action, Decider [skip appveyor] * Signature of Alias() now matches implementation to avoid problem if kwargs used * Case of Alias with no targets is mentioned in text (was already shown in example) * Now mention that Action([item]) does not return a ListAction - previously implied that if arg was a list, a ListAction was *always* returned * Mention default Decider and sort the names of available decider functions, and add version marking. * Minor fiddling with Alias.py docstrings. Signed-off-by: Mats Wichmann --- CHANGES.txt | 7 +++ RELEASE.txt | 7 +-- SCons/Action.py | 55 ++++++++++--------- SCons/Environment.xml | 142 ++++++++++++++++++++++++++++++-------------------- doc/man/scons.xml | 12 +++-- doc/user/caching.xml | 2 +- 6 files changed, 134 insertions(+), 91 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index 5ad76b8..6e8e677 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -25,6 +25,13 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER Only used in msvs.py. Use base64.decodebytes instead. - SCons test runner now uses pathlib to normalize and compare paths to test files. + - Minor doc fixes: signature of Alias() now matches implementation + to avoid problem if kwargs used; case of Alias with no targets is + mentioned in text (was already shown in example); now mention that + Action([item]) does not return a ListAction - previously implied + that if arg was a list, a ListAction was *always* returned; mention + default Decider and sort the names of available decider functions, + and add a version marking. Minor fiddling with Alias.py docstrings. RELEASE 4.5.2 - Sun, 21 Mar 2023 14:08:29 -0700 diff --git a/RELEASE.txt b/RELEASE.txt index bafda47..5cef731 100644 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -57,9 +57,10 @@ 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) +- Aligned manpage signature for Alias function to match implementation - + if the previous *targets* parameter had been used as a keyword argument, + the results would be incorrect (does not apply to positional argument + usage, which had no problem). DEVELOPMENT ----------- diff --git a/SCons/Action.py b/SCons/Action.py index 3f1a24e..fcc6f3f 100644 --- a/SCons/Action.py +++ b/SCons/Action.py @@ -148,9 +148,8 @@ def default_exitstatfunc(s): strip_quotes = re.compile(r'^[\'"](.*)[\'"]$') -def _callable_contents(obj): - """Return the signature contents of a callable Python object. - """ +def _callable_contents(obj) -> bytearray: + """Return the signature contents of a callable Python object.""" try: # Test if obj is a method. return _function_contents(obj.__func__) @@ -170,7 +169,7 @@ def _callable_contents(obj): return _function_contents(obj) -def _object_contents(obj): +def _object_contents(obj) -> bytearray: """Return the signature contents of any Python object. We have to handle the case where object contains a code object @@ -210,8 +209,10 @@ def _object_contents(obj): # the best we can. return bytearray(repr(obj), 'utf-8') +# TODO: docstrings for _code_contents and _function_contents +# do not render well with Sphinx. Consider reworking. -def _code_contents(code, docstring=None): +def _code_contents(code, docstring=None) -> bytearray: r"""Return the signature contents of a code object. By providing direct access to the code object of the @@ -223,7 +224,7 @@ def _code_contents(code, docstring=None): recompilations from moving a Python function. See: - - https://docs.python.org/2/library/inspect.html + - https://docs.python.org/3/library/inspect.html - http://python-reference.readthedocs.io/en/latest/docs/code/index.html For info on what each co\_ variable provides @@ -243,7 +244,6 @@ def _code_contents(code, docstring=None): co_code - Returns a string representing the sequence of bytecode instructions. """ - # contents = [] # The code contents depends on the number of local variables @@ -281,8 +281,9 @@ def _code_contents(code, docstring=None): return contents -def _function_contents(func): - """ +def _function_contents(func) -> bytearray: + """Return the signature contents of a function. + The signature is as follows (should be byte/chars): < _code_contents (see above) from func.__code__ > ,( comma separated _object_contents for function argument defaults) @@ -293,11 +294,7 @@ def _function_contents(func): - func.__code__ - The code object representing the compiled function body. - func.__defaults__ - A tuple containing default argument values for those arguments that have defaults, or None if no arguments have a default value - func.__closure__ - None or a tuple of cells that contain bindings for the function's free variables. - - :Returns: - Signature contents of a function. (in bytes) """ - contents = [_code_contents(func.__code__, func.__doc__)] # The function contents depends on the value of defaults arguments @@ -439,16 +436,13 @@ def _do_create_keywords(args, kw): def _do_create_action(act, kw): - """This is the actual "implementation" for the - Action factory method, below. This handles the - fact that passing lists to Action() itself has - different semantics than passing lists as elements - of lists. - - The former will create a ListAction, the latter - will create a CommandAction by converting the inner - list elements to strings.""" + """The internal implementation for the Action factory method. + This handles the fact that passing lists to :func:`Action` itself has + different semantics than passing lists as elements of lists. + The former will create a :class:`ListAction`, the latter will create a + :class:`CommandAction by converting the inner list elements to strings. + """ if isinstance(act, ActionBase): return act @@ -491,13 +485,22 @@ def _do_create_action(act, kw): return None -def _do_create_list_action(act, kw): - """A factory for list actions. Convert the input list into Actions - and then wrap them in a ListAction.""" +# TODO: from __future__ import annotations once we get to Python 3.7 base, +# to avoid quoting the defined-later classname +def _do_create_list_action(act, kw) -> "ListAction": + """A factory for list actions. + + Convert the input list *act* into Actions and then wrap them in a + :class:`ListAction`. If *act* has only a single member, return that + member, not a *ListAction*. This is intended to allow a contained + list to specify a command action without being processed into a + list action. + """ acts = [] for a in act: aa = _do_create_action(a, kw) - if aa is not None: acts.append(aa) + if aa is not None: + acts.append(aa) if not acts: return ListAction([]) elif len(acts) == 1: diff --git a/SCons/Environment.xml b/SCons/Environment.xml index f87e883..2b4c4af 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -351,9 +351,9 @@ to be performed after the specified target has been built. -The specified action(s) may be +action may be an Action object, or anything that -can be converted into an Action object +can be converted into an Action object. See the manpage section "Action Objects" for a complete explanation. @@ -364,6 +364,13 @@ the action may be called multiple times, once after each action that generates one or more targets in the list. + + +foo = Program('foo.c') +# remove execute permission from binary: +AddPostAction(foo, Chmod('$TARGET', "a-x")) + + @@ -379,9 +386,9 @@ to be performed before the specified target is built. -The specified action(s) may be +action may be an Action object, or anything that -can be converted into an Action object +can be converted into an Action object. See the manpage section "Action Objects" for a complete explanation. @@ -426,21 +433,35 @@ file into an object file. -(alias, [targets, [action]]) +(alias, [source, [action]]) -Creates one or more phony targets that -expand to one or more other targets. -An optional +Creates a phony target (or targets) that +can be used as references to zero or more other targets, +as specified by the optional source +parameter. +alias and +source +may each be a string or Node object, +or a list of strings or Node objects; +if Nodes are used for +alias +they must be Alias nodes. +The optional action -(command) -or list of actions -can be specified that will be executed +parameter specifies an action or list of actions +that will be executed whenever the any of the alias targets are out-of-date. -Returns the Node object representing the alias, -which exists outside of any file system. -This Node object, or the alias name, + + + +Returns a list of Alias Node objects representing the alias(es), +which exist outside of any physical file system. + + + +The alias name, or an Alias Node object, may be used as a dependency of any other target, including another alias. &f-Alias; @@ -593,7 +614,7 @@ giving an easy way to enter multiple macros in one addition. Use an = to specify a valued macro. -A tuple is treated as a valued macro. +A tuple is treated as a valued macro. Use the value None if the macro should not have a value. It is an error to supply more than two elements in such a tuple. @@ -1238,8 +1259,8 @@ so you normally don't need to create directories by hand. -Creates a Configure object for integrated -functionality similar to GNU autoconf. +Creates a &Configure; object for integrated +functionality similar to GNU autoconf. See the manpage section "Configure Contexts" for a complete explanation of the arguments and behavior. @@ -1265,50 +1286,24 @@ that will be applied: -"timestamp-newer" - - -Specifies that a target shall be considered out of date and rebuilt -if the dependency's timestamp is newer than the target file's timestamp. -This is the behavior of the classic Make utility, -and -make -can be used a synonym for -timestamp-newer. - - - - -"timestamp-match" - - -Specifies that a target shall be considered out of date and rebuilt -if the dependency's timestamp is different than the -timestamp recorded the last time the target was built. -This provides behavior very similar to the classic Make utility -(in particular, files are not opened up so that their -contents can be checksummed) -except that the target will also be rebuilt if a -dependency file has been restored to a version with an -earlier -timestamp, such as can happen when restoring files from backup archives. - - - - "content" Specifies that a target shall be considered out of date and rebuilt if the dependency's content has changed since the last time the target was built, -as determined be performing an checksum -on the dependency's contents +as determined by performing a checksum +on the dependency's contents using the selected hash function, and comparing it to the checksum recorded the last time the target was built. -MD5 -can be used as a synonym for -content, but it is deprecated. +content is the default decider. + + +Changed in version 4.1: +The decider was renamed to content +since the hash function is now selectable. +The former name, MD5, +can still be used as a synonym, but is deprecated. @@ -1339,9 +1334,44 @@ that runs a build, updates a file, and runs the build again, all within a single second. -MD5-timestamp -can be used as a synonym for -content-timestamp, but it is deprecated. + + +Changed in version 4.1: +The decider was renamed to content-timestamp +since the hash function is now selectable. +The former name, MD5-timestamp, +can still be used as a synonym, but is deprecated. + + + + +"timestamp-newer" + + +Specifies that a target shall be considered out of date and rebuilt +if the dependency's timestamp is newer than the target file's timestamp. +This is the behavior of the classic Make utility, +and +make +can be used a synonym for +timestamp-newer. + + + + +"timestamp-match" + + +Specifies that a target shall be considered out of date and rebuilt +if the dependency's timestamp is different than the +timestamp recorded the last time the target was built. +This provides behavior very similar to the classic Make utility +(in particular, files are not opened up so that their +contents can be checksummed) +except that the target will also be rebuilt if a +dependency file has been restored to a version with an +earlier +timestamp, such as can happen when restoring files from backup archives. diff --git a/doc/man/scons.xml b/doc/man/scons.xml index e79a267..b070dcb 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -1216,7 +1216,7 @@ small block-size slows down the build considerably. The default value is to use a chunk size of 64 kilobytes, which should be appropriate for most uses. -New in version 4.2. +New in version 4.1. @@ -1256,7 +1256,7 @@ For example, uses a SConsign database named .sconsign_sha256.dblite. -New in version 4.2. +New in version 4.1. @@ -3961,7 +3961,7 @@ it will not be added again. The default is False. library can be a list of library names, or None (the default if the argument is omitted). If the former, symbol is checked against -each library name in order, returning +each library name in order, returning (and reporting success) on the first successful test; if the latter, it is checked with the current value of &cv-LIBS; @@ -6526,9 +6526,11 @@ env.Command( -The behavior of Chmod is limited on Windows, +The behavior of Chmod is limited on Windows +and on WebAssembly platforms, see the notes in the Python documentation for -os.chmod, which is the underlying function. + +os.chmod, which is the underlying function. diff --git a/doc/user/caching.xml b/doc/user/caching.xml index 69368d7..f00bd69 100644 --- a/doc/user/caching.xml +++ b/doc/user/caching.xml @@ -129,7 +129,7 @@ CacheDir('/usr/local/build_cache') A few inside details: &SCons; tracks two main kinds of cryptographic hashes: a &contentsig;, which is a hash of the contents of a file participating in the - build (depepdencies as well as targets); + build (dependencies as well as targets); and a &buildsig;, which is a hash of the elements needed to build a target, such as the command line, the contents of the sources, and possibly information about -- cgit v0.12