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 From c9528b3d1d2645dbf9e495b1373b3190253901ed Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 28 Aug 2020 09:44:00 -0600 Subject: typo fix [skip appveyor] Signed-off-by: Mats Wichmann --- doc/user/builders-commands.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user/builders-commands.xml b/doc/user/builders-commands.xml index 9bbd962..495f05d 100644 --- a/doc/user/builders-commands.xml +++ b/doc/user/builders-commands.xml @@ -198,11 +198,11 @@ env.Command('${SOURCE.basename}.out', 'foo.in', action=build) 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, + 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. + to pass to &f-Command;, which gives you much more control. Here's an evolution of the example from above showing this approach: -- cgit v0.12 From 390e948c467a6d19f9f3d08db4e4bb90d3bc5a75 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 28 Aug 2020 09:48:54 -0600 Subject: and fix a "thinko" in new userguide example [skip appveyor] Signed-off-by: Mats Wichmann --- doc/generated/examples/builderscommands_ex5_1.xml | 2 +- doc/user/builders-commands.xml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/generated/examples/builderscommands_ex5_1.xml b/doc/generated/examples/builderscommands_ex5_1.xml index 3811242..67659c1 100644 --- a/doc/generated/examples/builderscommands_ex5_1.xml +++ b/doc/generated/examples/builderscommands_ex5_1.xml @@ -1,3 +1,3 @@ % scons -Q -Building foo.in +Building foo.out diff --git a/doc/user/builders-commands.xml b/doc/user/builders-commands.xml index 495f05d..7d47dae 100644 --- a/doc/user/builders-commands.xml +++ b/doc/user/builders-commands.xml @@ -215,7 +215,7 @@ def build(target, source, env): # Whatever it takes to build return None -act = Action(build, cmdstr="Building ${SOURCE}") +act = Action(build, cmdstr="Building ${TARGET}") env.Command('foo.out', 'foo.in', action=act) -- cgit v0.12 From b85cb312467893c60e07f3732971775967ce8fab Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sat, 29 Aug 2020 08:34:37 -0600 Subject: User Guide: don't link to tigris any more [ci skip] Troubleshooting section had a remaining link to tigris.org. Now points to scons website - not to github, because we don't encourage directly filing a bug before first discussing. Signed-off-by: Mats Wichmann --- doc/user/troubleshoot.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user/troubleshoot.xml b/doc/user/troubleshoot.xml index 7049deb..3906af6 100644 --- a/doc/user/troubleshoot.xml +++ b/doc/user/troubleshoot.xml @@ -69,8 +69,8 @@ odds are pretty good that someone else will run into the same problem, too. If so, please let the SCons development team know - (preferably by filing a bug report - or feature request at our project pages at tigris.org) + using the contact information at + so that we can use your feedback to try to come up with a better way to help you, and others, get the necessary insight into &SCons; behavior -- cgit v0.12 From d3685438664cea67dd581f2d89956bc498ac5d21 Mon Sep 17 00:00:00 2001 From: anatoly techtonik Date: Sat, 5 Sep 2020 17:16:52 +0300 Subject: README.rst Simplify docs for running from repo [skip ci] --- README.rst | 25 ++++++------------------- 1 file changed, 6 insertions(+), 19 deletions(-) diff --git a/README.rst b/README.rst index 79f730a..df74a59 100755 --- a/README.rst +++ b/README.rst @@ -98,33 +98,20 @@ Nothing special. Executing SCons Without Installing ================================== -You can execute the local SCons directly from the SCons subdirectory by first -setting the SCONS_LIB_DIR environment variable to the local SCons -subdirectory, and then executing the local scripts/scons.py script to -populate the build/scons/ subdirectory. You would do this as follows on a -Linux or UNIX system (using sh or a derivative like bash or ksh):: +You can execute the SCons directly from this repository. For Linux or UNIX:: - $ setenv MYSCONS=`pwd` - $ python $MYSCONS/scripts/scons.py [arguments] + $ python scripts/scons.py [arguments] Or on Windows:: - C:\scons>set MYSCONS=%cd% - C:\scons>python %MYSCONS%\scripts\scons.py [arguments] - -An alternative approach is to skip the above and use:: - - $ python scripts/scons.py [arguments] + C:\scons>python scripts\scons.py [arguments] - -You can use the -C option to have SCons change directory to another location -where you already have a build configuration set up:: +If you run SCons this way, it will execute `SConstruct` file for this repo, +which will build and pack SCons itself. Use the -C option to change directory +to your project:: $ python scripts/scons.py -C /some/other/location [arguments] -For simplicity in the following examples, we will only show the bootstrap.py -approach. - Installation ============ -- cgit v0.12 From 6825c691875d60c678cd7f8b7bd72afb19826b45 Mon Sep 17 00:00:00 2001 From: GIT Date: Mon, 7 Sep 2020 23:29:15 +0530 Subject: Update simple.xml I guess, double that is typo --- doc/user/simple.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user/simple.xml b/doc/user/simple.xml index 138ff54..8582613 100644 --- a/doc/user/simple.xml +++ b/doc/user/simple.xml @@ -459,7 +459,7 @@ int main() { printf("Goodbye, world!\n"); } we see the output from calling the print function in between the messages about reading the &SConscript; files, - indicating that that is when the + indicating that is when the Python statements are being executed: -- cgit v0.12