Support overriding construction variables in builder call. (Anthony Roach)

1 files changed, 36 insertions, 1 deletions

diff --git a/doc/man/scons.1 b/doc/man/scons.1
index 7bb09bb..6ff35db 100644
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -812,6 +812,22 @@ env.Program(source = 'bar.c')
 env.Program('bar.c')
 .EE
 
+It is possible to override or add construction variables when calling a
+builder by passing additional keyword arguments. These overriden or added
+variables will only be in effect when building the target, so they will not
+effect other parts of the build. For example, if you want to add additional
+libraries for just one program:
+
+.ES
+env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
+.EE
+
+or generate a shared library with a nonstandard suffix:
+
+.ES
+env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
+.EE
+
 .B scons
 provides the following builders:
 
@@ -2334,13 +2350,22 @@ an Action object
 (see the next section);
 or a list of any of the above.
 
+An action function
+takes three arguments:
+.I source 
+- a list of source nodes, 
+.I target
+- a list of target nodes,
+.I env
+- the construction environment.
+
 .IP multi
 Specifies whether this builder is allowed to be called multiple times for
 the same target file(s). The default is 0, which means the builder
 can not be called multiple times for the same target file(s). Calling a
 builder multiple times for the same target simply adds additional source
 files to the target; it is not allowed to change the environment associated
-with the target, specify addition build arguments, or associate a different
+with the target, specify addition environment overrides, or associate a different
 builder with the target. 
 
 .IP prefix 
@@ -2364,6 +2389,16 @@ the list of targets to be built by this builder,
 and the list of sources for this builder.
 This allows the target and source lists to
 be manipulated before the target(s) are actually built.
+
+The emitter function
+takes three arguments:
+.I source 
+- a list of source nodes, 
+.I target
+- a list of target nodes,
+.I env
+- the construction environment.
+
 Example:
 
 .ES