From 2936910a440633c465a42339a6df2757a7ed1c46 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Mon, 6 Sep 2021 06:51:24 -0600 Subject: Update manpage mentions of for_signature In the Builder Objects section, under generator, just add a note about omitting pieces that don't affect rebuilds if for_signature is true. In the Variable Substitution section, the same is added for a variable referring to a function, but a little mroe wording added, and since the new info kind of depends on the $( $) construct, which came just below it in the section, that chunk is moved up to make the reference a little more natural. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 131 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 68 insertions(+), 63 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index d86a123..e5fd5bd 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -5622,11 +5622,14 @@ must accept four arguments: source is a list of source nodes, target is a list of target nodes, env is the &consenv; to use for context, -for_signature is -a Boolean value that specifies -whether the generator is being called -for generating a build signature +and for_signature is +a Boolean value that tells the function +if it is being called for the purpose of generating a build signature (as opposed to actually executing the command). +Since the build signature is used for rebuild determination, +the function should omit those elements +that do not affect whether a rebuild should be triggered +if for_signature is true. Example: @@ -6703,23 +6706,66 @@ to enclose a Python expression to be evaluated. See below for a description. -A variable name -may also be a Python function -associated with a -&consvar; in the environment. -The function should -accept four arguments: +The special pseudo-variables +$( +and +$) +may be used to surround parts of a command line +that may change +without +causing a rebuild--that is, +which are not included in the signature +of target files built with this command. +All text between +$( +and +$) +will be removed from the command line +before it is added to file signatures, +and the +$( +and +$) +will be removed before the command is executed. +For example, the command line: + + +echo Last build occurred $( $TODAY $). > $TARGET + + +would execute the command: + + +echo Last build occurred $TODAY. > $TARGET + + +but the command signature added to any target files would be: + + +echo Last build occurred . > $TARGET + + +A variable name may also be the name +of a &consvar; which refers to a &Python; function +called to perform the variable substitution. +Such a function must accept four arguments: +target, +source, +env and +for_signature. +source is a list of source nodes, +target is a list of target nodes, +env is the &consenv; to use for context, +and for_signature is +a Boolean value that tells the function +if it is being called for the purpose of generating a build signature. +Since the build signature is used for rebuild determination, +the function should omit variable elements +that do not affect whether a rebuild should be triggered +(see $( +and $) +above) if for_signature is true. - - target - a list of target nodes - source - a list of source nodes - env - the &consenv; - for_signature - - a Boolean value that specifies - whether the function is being called - for generating a build signature. - - SCons will insert whatever @@ -6732,10 +6778,10 @@ def foo(target, source, env, for_signature): return "bar" # Will expand $BAR to "bar baz" -env=Environment(FOO=foo, BAR="$FOO baz") +env = Environment(FOO=foo, BAR="$FOO baz") -As a reminder, this evaluation happens when +As a reminder, substitution evaluation happens when $BAR is actually used in a builder action. The value of env['BAR'] will be exactly as it was set: "$FOO baz". @@ -6765,47 +6811,6 @@ class foo: # Will expand $BAR to "my argument bar baz" env=Environment(FOO=foo, BAR="${FOO('my argument')} baz") - - -The special pseudo-variables -$( -and -$) -may be used to surround parts of a command line -that may change -without -causing a rebuild--that is, -which are not included in the signature -of target files built with this command. -All text between -$( -and -$) -will be removed from the command line -before it is added to file signatures, -and the -$( -and -$) -will be removed before the command is executed. -For example, the command line: - - -echo Last build occurred $( $TODAY $). > $TARGET - - -would execute the command: - - -echo Last build occurred $TODAY. > $TARGET - - -but the command signature added to any target files would be: - - -echo Last build occurred . > $TARGET - - -- cgit v0.12