summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorGreg Noel <GregNoel@tigris.org>2008-10-04 15:37:28 (GMT)
committerGreg Noel <GregNoel@tigris.org>2008-10-04 15:37:28 (GMT)
commit091232eb5b0dde383133d38aee899fa4cfa9555c (patch)
tree4bec9c97245ae244d8b6e042ce99af75b66e1512
parent805092f39b1e9f4827e200f1feab9d6e562fff11 (diff)
downloadSCons-091232eb5b0dde383133d38aee899fa4cfa9555c.zip
SCons-091232eb5b0dde383133d38aee899fa4cfa9555c.tar.gz
SCons-091232eb5b0dde383133d38aee899fa4cfa9555c.tar.bz2
documentation changes for Action() refactoring
-rw-r--r--doc/man/scons.181
1 files changed, 42 insertions, 39 deletions
diff --git a/doc/man/scons.1 b/doc/man/scons.1
index 2d2cc95..4f1d316 100644
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -2323,9 +2323,9 @@ include:
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
-.RI Action( action ", [" strfunction ", " varlist ])
+.RI Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])"
.TP
-.RI env.Action( action ", [" strfunction ", " varlist ])
+.IR env .Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])"
Creates an Action object for
the specified
.IR action .
@@ -2335,13 +2335,12 @@ below, for a complete explanation of the arguments and behavior.
Note that the
.BR env.Action ()
form of the invocation will expand
-construction variables in any arguments strings,
+construction variables in any argument strings,
including the
.I action
-argument,
-at the time it is called
+argument, at the time it is called
using the construction variables in the
-.B env
+.I env
construction environment through which
.BR env.Action ()
was called.
@@ -8428,18 +8427,15 @@ the object is simply returned.
.IP String
If the first argument is a string,
a command-line Action is returned.
-Note that the command line string
+Note that the command-line string
may be preceded by an
.B @
(at-sign)
-to suppress printing of the
-specified command line,
+to suppress printing of the specified command line,
or by a
.B \-
(hyphen)
-to ignore the exit status from
-the specified command.
-Examples:
+to ignore the exit status from the specified command:
.ES
Action('$CC -c -o $TARGET $SOURCES')
@@ -8447,10 +8443,9 @@ Action('$CC -c -o $TARGET $SOURCES')
# Doesn't print the line being executed.
Action('@build $TARGET $SOURCES')
-# Ignores
+# Ignores return value
Action('-build $TARGET $SOURCES')
.EE
-
.\" XXX From Gary Ruben, 23 April 2002:
.\" What would be useful is a discussion of how you execute command
.\" shell commands ie. what is the process used to spawn the shell, pass
@@ -8460,7 +8455,6 @@ Action('-build $TARGET $SOURCES')
.\" a build system. I'm sure you can do a better job of organising the
.\" documentation than they have :-)
-
.IP List
If the first argument is a list,
then a list of Action objects is returned.
@@ -8483,7 +8477,7 @@ Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
.IP Function
If the first argument is a Python function,
a function Action is returned.
-The Python function takes three keyword arguments,
+The Python function must take three keyword arguments,
.B target
(a Node object representing the target file),
.B source
@@ -8528,19 +8522,22 @@ If the action argument is not one of the above,
None is returned.
.PP
-The second, optional argument
-is used to define the output which is printed
-when the Action is actually performed.
-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 is 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 second argument is optional and is used to define the output
+which is printed when the Action is actually performed.
+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.
+
+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
+.IR strfunction =
+keyword argument.
Like a function to build a file,
-this function takes three arguments:
+this function must take three keyword arguments:
.B target
(a Node object representing the target file),
.B source
@@ -8556,6 +8553,9 @@ 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.
+The string may also be specified by the
+.IR cmdstr =
+keyword argument.
The string typically contains variables, notably
$TARGET(S) and $SOURCE(S), or consists of just a single
variable, which is optionally defined somewhere else.
@@ -8583,17 +8583,20 @@ s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
l = Action(build_it, '$STRINGIT')
.EE
-The third, also optional argument
-is a list of construction variables
-whose values will be included
-in the signature of the Action
-when deciding whether a target should
-be rebuilt because the action changed.
-This is necessary whenever you want a target to
-be rebuilt when a specific
-construction variable changes,
-because the underlying Python code for a function
-will not change when the value of the construction variable does.
+The third and succeeding arguments, if present,
+may either be a construction variable or a list of construction variables
+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 by a
+.IR varlist =
+keyword parameter;
+if both are present, they are combined.
+This is necessary whenever you want a target to be rebuilt
+when a specific construction variable changes.
+This is not often needed for a string action,
+as the expanded variables will normally be part of the command line,
+but may be needed if a Python function action uses
+the value of a construction variable when generating the command line.
.ES
def build_it(target, source, env):