From 2235c5c6ac22abfa5af46007ade31d572fe72e6f Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 28 Aug 2020 08:40:58 -0600 Subject: Updated docs on Actions for output control Manpage now mentions specifically generating your own Action object in order to control the output string. Calls out using None as the command-output specifier to avoid output: Action(foo, None) and Action(foo, cmdstr=None), as well Userguide got a mention of using the action kwarg for readability and an example showing creating the Action for Command manually to set the output string. Signed-off-by: Mats Wichmann --- doc/generated/examples/builderscommands_ex5_1.xml | 3 ++ doc/man/scons.xml | 57 ++++++++++++-------- doc/user/builders-commands.xml | 66 +++++++++++++++++++++-- doc/user/output.xml | 2 +- 4 files changed, 100 insertions(+), 28 deletions(-) create mode 100644 doc/generated/examples/builderscommands_ex5_1.xml diff --git a/doc/generated/examples/builderscommands_ex5_1.xml b/doc/generated/examples/builderscommands_ex5_1.xml new file mode 100644 index 0000000..3811242 --- /dev/null +++ b/doc/generated/examples/builderscommands_ex5_1.xml @@ -0,0 +1,3 @@ +% scons -Q +Building foo.in + diff --git a/doc/man/scons.xml b/doc/man/scons.xml index fc28e2a..96b5700 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -5521,18 +5521,21 @@ and emitter functions. function will turn its action keyword argument into an appropriate -internal Action object. +internal Action object, as will +the &f-link-Command; function. You can also explicitly create Action objects for passing to &f-Builder;, or other functions that take actions as arguments, by calling the &f-link-Action; factory function. -This can be used to configure -an Action object more flexibly, -or it may simply be more efficient -than letting each separate Builder object -create a separate Action -when multiple -Builder objects need to do the same thing. +This may more efficient when multiple +Builder objects need to do the same thing +rather than letting each of those Builder objects +create a separate Action object. +It also allows more flexible configuration +of an Action object. For example, to control +the message printed when the action is taken +you need to create the action object using &f-Action;. + The &Action; factory function @@ -5652,23 +5655,22 @@ it was called. The global function form &f-link-Action; the Action object is actually used. -The second argument to &f-Action; -is optional and is used to define the output +The optional second argument to &f-Action; +is used to control the output which is printed when the Action is actually performed. -In the absence of this parameter, -or if it's an empty string, +If this parameter is omitted, +or if the value is an empty string, a default output depending on the type of the action is used. For example, a command-line action will print the executed command. -The argument must be either a Python function or a string: +The following argument types are accepted: + If the output argument is a function, -it must return a string +the function will be called to obtain a string describing the action being executed. -A function may also be specified using the -strfunction -keyword argument. The function +The function must accept these three keyword arguments: @@ -5689,18 +5691,29 @@ more than one target file or source file. If the output argument is a string, -substitution is performed on it before it is printed. -The output string may also be specified using the -cmdstr -keyword argument. +substitution is performed on the string before it is printed. The string typically contains variables, notably $TARGET(S) and $SOURCE(S), or consists of just a single variable, which is optionally defined somewhere else. -SCons itself heavily uses the latter variant. +&SCons; itself heavily uses the latter variant. + + + +If the argument is None, +output is suppressed entirely. + +Instead of using a positional argument, +the cmdstr +keyword argument may be used to specify the output string, +or the strfunction keyword argument +may be used to specify a function to return the output string, +Use cmdstr=None to suppress output. + + Examples: diff --git a/doc/user/builders-commands.xml b/doc/user/builders-commands.xml index 5d378b3..9bbd962 100644 --- a/doc/user/builders-commands.xml +++ b/doc/user/builders-commands.xml @@ -81,7 +81,7 @@ if you only need to execute one specific command to build a single file (or group of files). For these situations, &SCons; supports a - &Command; &Builder; that arranges + &f-link-Command; builder that arranges for a specific action to be executed to build a specific file or files. This looks a lot like the other builders @@ -119,7 +119,7 @@ foo.in This is often more convenient than creating a &Builder; object and adding it to the &cv-link-BUILDERS; variable - of a &consenv; + of a &consenv;. @@ -134,9 +134,11 @@ foo.in env = Environment() + def build(target, source, env): # Whatever it takes to build return None + env.Command('foo.out', 'foo.in', build) @@ -157,8 +159,7 @@ foo.in Note that &cv-link-SOURCE; and &cv-link-TARGET; are expanded - in the source and target as well as of SCons 1.1, - so you can write: + in the source and target as well, so you can write: @@ -168,7 +169,6 @@ env.Command('${SOURCE.basename}.out', 'foo.in', build) - which does the same thing as the previous example, but allows you @@ -176,5 +176,61 @@ env.Command('${SOURCE.basename}.out', 'foo.in', build) + + + It may be helpful to use the action + keyword to specify the action, is this makes things more clear + to the reader: + + + + + +env.Command('${SOURCE.basename}.out', 'foo.in', action=build) + + + + + + The method described in + for controlling + build output works well when used with pre-defined builders which + have pre-defined *COMSTR variables for that purpose, + but that is not the case when calling &f-Command;, + where &SCons; has no specific knowledge of the action ahead of time. + If the action argument to &f-Command is not already an &Action; object, + it will construct one for you with suitable defaults, + which include a message based on the type of action. + However, you can also construct the &Action; object yourself + and pass that, which gives you much more control. + Here's an evolution of the example from above showing this approach: + + + + + +env = Environment() + +def build(target, source, env): + # Whatever it takes to build + return None + +act = Action(build, cmdstr="Building ${SOURCE}") +env.Command('foo.out', 'foo.in', action=act) + + +foo.in + + + + + + Which executes as follows: + + + + + scons -Q + diff --git a/doc/user/output.xml b/doc/user/output.xml index bae018a..cf6571c 100644 --- a/doc/user/output.xml +++ b/doc/user/output.xml @@ -197,7 +197,7 @@ if env['PLATFORM'] == 'win32': -
+
Controlling How &SCons; Prints Build Commands: the <envar>$*COMSTR</envar> Variables -- cgit v0.12