From 8bd83c995b21e159af9f59a1c93648392309abe6 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Tue, 23 Jun 2020 16:35:05 -0600 Subject: A bit of tweaking on Action Objects in manpage [ci skip] Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 157 ++++++++++++++++++++++++++---------------------------- 1 file changed, 75 insertions(+), 82 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 18e4321..7a12f3f 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -5335,9 +5335,10 @@ env = Environment(BUILDERS={'MyBuild' : b}) env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in') -WARNING: + + Python only keeps one current directory -location for all of the threads. +location even if there are multiple threads. This means that use of the chdir argument @@ -5349,6 +5350,7 @@ option, because individual worker threads spawned by SCons interfere with each other when they start changing directory. + @@ -5387,9 +5389,9 @@ function will turn its keyword argument into an appropriate internal Action object. You can also explicitly create Action objects -using the &f-link-Action; global function, -which can then be passed to the -&f-Builder; function. +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 @@ -5399,31 +5401,26 @@ when multiple Builder objects need to do the same thing. The -&f-link-Action; -global function +&Action; factory function returns an appropriate object for the action -represented by the type of the first argument: +represented by the type of the action argument +(the first positional parmeter): - - - action + -If the first argument is already an Action object, +If the action argument is already an Action object, the object is simply returned. - - - string -If the first argument is a string, +If the action argument is a string, a command-line Action is returned. If such a string begins with @, it indicates printing of the command line is to be suppressed. If the string begins with - (hyphen), -it indicated the exit status from the specified command +it indicates the exit status from the specified command is to be ignored, allowing execution to continue even if the command reports failure: @@ -5436,46 +5433,30 @@ Action('@build $TARGET $SOURCES') # Ignores return value Action('-build $TARGET $SOURCES') - - - - - - - - - - - - list -If the first argument is a list, +If the action argument is a list, then a list of Action objects is returned. An Action object is created as necessary for each element in the list. If an element within the list is itself a list, -the internal list is the +the internal list taken as the command and arguments to be executed via the command line. This allows white space to be enclosed -in an argument by defining +in an argument rather than taken as a separator by defining a command in a list within a list: Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']]) - - - - function -If the first argument is a Python function, +If the action argument is a Python function, a function Action is returned. The Python function must accept three keyword arguments: @@ -5520,13 +5501,21 @@ def build_it(target=None, source=None, env=None): a = Action(build_it) - - - -If the action argument is not one of the above, + +If the action argument is not one of the above types, None is returned. + + + +As usual the environment method form &f-link-env-Action; +will expand &consvars; in any argument strings, +including the action argument, at the time it is called, +using the construction variables in the &consenv; through which +it was called. The global function form &f-link-Action; +delays variable expansion until the Action object is actually used. + The second argument to &f-Action; is optional and is used to define the output @@ -5535,17 +5524,17 @@ In the absence of this parameter, or if it's 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 argument must be either a Python function or a string: -In the first case, -it's a function that returns a string to be printed -to describe the action being executed. -The function may also be specified by the + + +If the output argument is a function, +it must return a string +describing the action being executed. +A function may also be specified using the strfunction -keyword argument. -Like a function to build a file, -the strfunction function -must accept three keyword arguments: +keyword argument. The function +must accept these three keyword arguments: source - @@ -5561,9 +5550,12 @@ and source arguments may be lists of Node objects if there is more than one target file or source file. + -In the second case, you provide the string itself. -This string may also be specified using the + +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. The string typically contains variables, notably @@ -5571,6 +5563,8 @@ The string typically contains variables, notably or consists of just a single variable, which is optionally defined somewhere else. SCons itself heavily uses the latter variant. + + Examples: @@ -5594,14 +5588,14 @@ s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'") l = Action(build_it, '$STRINGIT') -The third and succeeding arguments, if present, -may either be a &consvar; or a list of &consvars; +Any additional positional arguments, if present, +may either be &consvars; or lists of &consvars; whose values will be included in the signature of the Action when deciding whether a target should be rebuilt because the action changed. -The variables may also be specified using the +Such variables may also be specified using the varlist keyword parameter; -if both are present, they are combined. +both positional and keyword forms may be present, and will be combined. This is necessary whenever you want a target to be rebuilt when a specific &consvar; changes. This is not often needed for a string action, @@ -5625,7 +5619,7 @@ a = Action(build_it, varlist=['XXX']) The &Action; -global function +factory function can be passed the following optional keyword arguments to modify the Action object's behavior: @@ -5821,14 +5815,10 @@ although the implementation is slightly different. These functions do not actually perform the specified action at the time the function is called, -but instead return an Action object +but rather are factory functions which +return an Action object that can be executed at the -appropriate time. -(In Object-Oriented terminology, -these are actually -Action -Factory functions -that return Action objects.) +appropriate time. In practice, there are two natural ways @@ -5918,8 +5908,7 @@ Examples: Execute(Copy('foo.output', 'foo.input')) -env.Command('bar.out', 'bar.in', - Copy('$TARGET', '$SOURCE')) +env.Command('bar.out', 'bar.in', Copy('$TARGET', '$SOURCE')) @@ -5937,10 +5926,10 @@ the entire directory tree will be removed. If the must_exist -flag is set to a True value, -then a Python error will be thrown +flag is set to a true value, +then a Python error will be raised if the specified entry does not exist; -the default is False, +the default is false, that is, the Action will silently do nothing if the entry does not exist. Examples: @@ -5948,9 +5937,7 @@ Examples: Execute(Delete('/tmp/buildroot')) -env.Command('foo.out', 'foo.in', - [Delete('${TARGET.dir}'), - MyBuildAction]) +env.Command('foo.out', 'foo.in', [Delete('${TARGET.dir}'), MyBuildAction]) Execute(Delete('file_that_must_exist', must_exist=1)) @@ -5970,11 +5957,16 @@ Examples: Execute(Mkdir('/tmp/outputdir')) -env.Command('foo.out', 'foo.in', - [Mkdir('/tmp/builddir'), - Copy('/tmp/builddir/foo.in', '$SOURCE'), - "cd /tmp/builddir && make", - Copy('$TARGET', '/tmp/builddir/foo.out')]) +env.Command( + 'foo.out', + 'foo.in', + action=[ + Mkdir('/tmp/builddir'), + Copy('/tmp/builddir/foo.in', '$SOURCE'), + "cd /tmp/builddir && make", + Copy('$TARGET', '/tmp/builddir/foo.out'), + ], +) @@ -5995,9 +5987,11 @@ Examples: Execute(Move('file.destination', 'file.source')) -env.Command('output_file', 'input_file', - [MyBuildAction, - Move('$TARGET', 'file_created_by_MyBuildAction')]) +env.Command( + 'output_file', + 'input_file', + action=[MyBuildAction, Move('$TARGET', 'file_created_by_MyBuildAction')], +) @@ -6015,8 +6009,7 @@ Examples: Execute(Touch('file_to_be_touched')) -env.Command('marker', 'input_file', - action=[MyBuildAction, Touch('$TARGET')]) +env.Command('marker', 'input_file', action=[MyBuildAction, Touch('$TARGET')]) -- cgit v0.12 From 07b5fecb22ea478930e5e02daef96766625ae459 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Thu, 25 Jun 2020 06:32:12 -0600 Subject: [PR #3713] tweak manpage per review comments Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 7a12f3f..7b083f0 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -5443,7 +5443,7 @@ for each element in the list. If an element within the list is itself a list, -the internal list taken as the +the internal list is taken as the command and arguments to be executed via the command line. This allows white space to be enclosed @@ -5514,7 +5514,8 @@ will expand &consvars; in any argument strings, including the action argument, at the time it is called, using the construction variables in the &consenv; through which it was called. The global function form &f-link-Action; -delays variable expansion until the Action object is actually used. +delays variable expansion until +the Action object is actually used. The second argument to &f-Action; @@ -5937,9 +5938,16 @@ Examples: Execute(Delete('/tmp/buildroot')) -env.Command('foo.out', 'foo.in', [Delete('${TARGET.dir}'), MyBuildAction]) +env.Command( + 'foo.out', + 'foo.in', + action=[ + Delete('${TARGET.dir}'), + MyBuildAction, + ], +) -Execute(Delete('file_that_must_exist', must_exist=1)) +Execute(Delete('file_that_must_exist', must_exist=True)) -- cgit v0.12