summaryrefslogtreecommitdiff
path: root/doc/user/environments.xml
diff options
context:
space:
mode:
authorLuca Falavigna <dktrkranz@debian.org>2010-06-15 14:28:22 +0000
committerLuca Falavigna <dktrkranz@debian.org>2010-06-15 14:28:22 +0000
commit738149c9bfb9965d013d01ef99f9bb1c2819e7e8 (patch)
tree0397d9bf3b12c903dc73419585df231397ff343c /doc/user/environments.xml
parente7885e3af440eaef38a9301fd92a105afc8ddebb (diff)
Imported Upstream version 2.0.0upstream/2.0.0
Diffstat (limited to 'doc/user/environments.xml')
-rw-r--r--doc/user/environments.xml89
1 files changed, 81 insertions, 8 deletions
diff --git a/doc/user/environments.xml b/doc/user/environments.xml
index fafb120..5bb1089 100644
--- a/doc/user/environments.xml
+++ b/doc/user/environments.xml
@@ -672,11 +672,8 @@ environment, of directory names, suffixes, etc.
<programlisting>
env = Environment()
- dict = env.Dictionary()
- keys = dict.keys()
- keys.sort()
- for key in keys:
- print "construction variable = '%s', value = '%s'" % (key, dict[key])
+ for item in sorted(env.Dictionary().items()):
+ print "construction variable = '%s', value = '%s'" % item
</programlisting>
</section>
@@ -775,6 +772,83 @@ environment, of directory names, suffixes, etc.
</section>
<section>
+ <title>Handling Problems With Value Expansion</title>
+
+ <para>
+
+ If a problem occurs when expanding a construction variable,
+ by default it is expanded to <literal>''</literal>
+ (a null string), and will not cause scons to fail.
+
+ <programlisting>
+ env = Environment()
+ print "value is:", env.subst( '-&gt;$MISSING&lt;-' )
+ </programlisting>
+
+ <screen>
+ % <userinput>scons -Q</userinput>
+ value is: -&gt;&lt;-
+ scons: `.' is up to date.
+ </screen>
+
+ This default behaviour can be changed using the &AllowSubstExceptions;
+ function.
+ When a problem occurs with a variable expansion it generates
+ an exception, and the &AllowSubstExceptions; function controls
+ which of these exceptions are actually fatal and which are
+ allowed to occur safely. By default, &NameError; and &IndexError;
+ are the two exceptions that are allowed to occur: so instead of
+ causing scons to fail, these are caught, the variable expanded to
+ <literal>''</literal>
+ and scons execution continues.
+ To require that all construction variable names exist, and that
+ indexes out of range are not allowed, call &AllowSubstExceptions;
+ with no extra arguments.
+ </para>
+
+ <programlisting>
+ AllowSubstExceptions()
+ env = Environment()
+ print "value is:", env.subst( '-&gt;$MISSING&lt;-' )
+ </programlisting>
+
+ <screen>
+ % <userinput>scons -Q</userinput>
+ value is:
+ scons: *** NameError `MISSING' trying to evaluate `$MISSING'
+ File "/home/my/project/SConstruct", line 3, in &lt;module&gt;
+ </screen>
+
+ <para>
+ This can also be used to allow other exceptions that might occur,
+ most usefully with the <literal>${...}</literal> construction
+ variable syntax. For example, this would allow zero-division to
+ occur in a variable expansion in addition to the default exceptions
+ allowed
+ </para>
+
+ <programlisting>
+ AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
+ env = Environment()
+ print "value is:", env.subst( '-&gt;${1 / 0}&lt;-' )
+ </programlisting>
+
+ <screen>
+ % <userinput>scons -Q</userinput>
+ value is: -&gt;&lt;-
+ scons: `.' is up to date.
+ </screen>
+ <programlisting>
+ </programlisting>
+
+ <para>
+ If &AllowSubstExceptions; is called multiple times, each call
+ completely overwrites the previous list of allowed exceptions.
+ </para>
+
+ </section>
+
+ <section>
<title>Controlling the Default &ConsEnv;: the &DefaultEnvironment; Function</title>
<para>
@@ -1543,11 +1617,10 @@ environment, of directory names, suffixes, etc.
#!/usr/bin/env python
import os
import sys
- if len(sys.argv) > 1:
+ if len(sys.argv) &gt; 1:
keys = sys.argv[1:]
else:
- keys = os.environ.keys()
- keys.sort()
+ keys = sorted(os.environ.keys())
for key in keys:
print " " + key + "=" + os.environ[key]
</file>