New upstream version 3.0.5upstream/3.0.5

1 files changed, 59 insertions, 2 deletions

diff --git a/doc/user/less-simple.xml b/doc/user/less-simple.xml
index c17bdae..6de1075 100644
--- a/doc/user/less-simple.xml
+++ b/doc/user/less-simple.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -644,4 +644,61 @@ Program('bar', bar_files)
 
   </section>
 
-</chapter>
+  <section>
+  <title>Overriding construction variables when calling a Builder</title>
+
+    <para>
+
+    It is possible to override or add construction variables
+    when calling a builder method by passing additional keyword arguments.
+    These overridden or added variables will only be in effect when
+    building the target, so they will not affect other parts of the build.
+    For example, if you want to add additional libraries for just one program:
+
+    </para>
+
+    <programlisting>
+env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
+    </programlisting>
+
+    <para>
+
+    or generate a shared library with a non-standard suffix:
+
+    </para>
+
+    <programlisting>
+env.SharedLibrary('word', 'word.cpp',
+                  SHLIBSUFFIX='.ocx',
+                  LIBSUFFIXES=['.ocx'])
+    </programlisting>
+
+    <para>
+
+    It is also possible to use the <literal>parse_flags</literal> keyword argument in an
+    override:
+
+    </para>
+
+    <para>
+
+    This example adds 'include' to &cv-link-CPPPATH;,
+    'EBUG' to &cv-link-CPPDEFINES;, and 'm' to &cv-link-LIBS;.
+
+    </para>
+
+    <programlisting>
+env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
+    </programlisting>
+
+    <para>
+
+    Within the call to the builder action the environment is not cloned,
+    instead an OverrideEnvironment() is created which is more
+    light weight than a whole Environment()
+
+    </para>
+
+  </section>
+
+</chapter>
\ No newline at end of file