diff options
author | Steven Knight <knight@baldmt.com> | 2004-08-16 13:43:09 (GMT) |
---|---|---|
committer | Steven Knight <knight@baldmt.com> | 2004-08-16 13:43:09 (GMT) |
commit | 74e2a97dc2ed0412ffb1a9c6dc810c1a1c4a4e67 (patch) | |
tree | 82a4927ce94fa90b9798accd2cfdbffb88ab2d51 /doc/user/environments.sgml | |
parent | 9a0aa47145dbaa02eccac8ba23c498a4e2a3a098 (diff) | |
download | SCons-74e2a97dc2ed0412ffb1a9c6dc810c1a1c4a4e67.zip SCons-74e2a97dc2ed0412ffb1a9c6dc810c1a1c4a4e67.tar.gz SCons-74e2a97dc2ed0412ffb1a9c6dc810c1a1c4a4e67.tar.bz2 |
Branch for documentation changes.
Diffstat (limited to 'doc/user/environments.sgml')
-rw-r--r-- | doc/user/environments.sgml | 363 |
1 files changed, 329 insertions, 34 deletions
diff --git a/doc/user/environments.sgml b/doc/user/environments.sgml index eb9bf5b..1ff2fb3 100644 --- a/doc/user/environments.sgml +++ b/doc/user/environments.sgml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003 Steven Knight + __COPYRIGHT__ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -410,7 +410,34 @@ environment undisturbed. <para> - A &consenv; is created by the &Environment; method. + A &consenv; is created by the &Environment; method: + + </para> + + <programlisting> + env = Environment() + </programlisting> + + <para> + + By default, &SCons; intializes every + new construction environment + with a set of &consvars; + based on the tools that it finds on your system, + plus the default set of builder methods + necessary for using those tools. + The construction variables + are initialized with values describing + the C compiler, + the Fortran compiler, + the linker, + etc., + as well as the command lines to invoke them. + + </para> + + <para> + When you initialize a construction environment you can set the values of the environment's &consvars; @@ -428,21 +455,26 @@ environment undisturbed. <para> - This example, rather than using the default, - explicitly specifies use of the + The construction environment in this example + is still initialized with the same default + construction variable values, + except that the user has explicitly specified use of the GNU C compiler &gcc;, and further specifies that the <literal>-O2</literal> (optimization level two) flag should be used when compiling the object file. + In other words, the explicit initializations of &CC; and &CCFLAGS; + override the default values in the newly-created + construction environment. So a run from this example would look like: </para> - <literallayout> + <screen> % <userinput>scons -Q</userinput> gcc -O2 -c -o foo.o foo.c gcc -o foo foo.o - </literallayout> + </screen> <section> <title>Multiple &ConsEnvs;</title> @@ -470,13 +502,13 @@ environment undisturbed. dbg.Program('bar', 'bar.c') </programlisting> - <literallayout> + <screen> % <userinput>scons -Q</userinput> cc -g -c -o bar.o bar.c cc -o bar bar.o cc -O2 -c -o foo.o foo.c cc -o foo foo.o - </literallayout> + </screen> <para> @@ -503,12 +535,12 @@ environment undisturbed. </para> - <literallayout> + <screen> % <userinput>scons -Q</userinput> scons: *** Two environments with different actions were specified for the same target: foo.o File "SConstruct", line 6, in ? - </literallayout> + </screen> <para> @@ -532,9 +564,6 @@ environment undisturbed. </para> <programlisting> - </programlisting> - - <programlisting> opt = Environment(CCFLAGS = '-O2') dbg = Environment(CCFLAGS = '-g') @@ -561,13 +590,13 @@ environment undisturbed. </para> - <literallayout> + <screen> % <userinput>scons -Q</userinput> cc -g -c -o foo-dbg.o foo.c cc -o foo-dbg foo-dbg.o cc -O2 -c -o foo-opt.o foo.c cc -o foo-opt foo-opt.o - </literallayout> + </screen> </section> @@ -621,7 +650,7 @@ environment undisturbed. </para> - <literallayout> + <screen> % <userinput>scons -Q</userinput> gcc -c -o foo.o foo.c gcc -o foo foo.o @@ -629,7 +658,7 @@ environment undisturbed. gcc -o foo-dbg foo-dbg.o gcc -O2 -c -o foo-opt.o foo.c gcc -o foo-opt foo-opt.o - </literallayout> + </screen> </section> @@ -657,17 +686,16 @@ environment undisturbed. </para> - <literallayout> + <screen> % <userinput>scons -Q</userinput> CC is: cc scons: `.' is up to date. - </literallayout> + </screen> <para> A construction environment, however, - is actually a Python object with - associated methods, etc. + is actually an object with associated methods, etc. If you want to have direct access to only the dictionary of construction variables, you can fetch this using the &Dictionary; method: @@ -689,13 +717,13 @@ environment undisturbed. </para> - <literallayout> + <screen> % <userinput>scons -Q</userinput> key = OBJSUFFIX, value = .o key = LIBSUFFIX, value = .a key = PROGSUFFIX, value = scons: `.' is up to date. - </literallayout> + </screen> <para> @@ -703,13 +731,123 @@ environment undisturbed. </para> - <literallayout> + <screen> C:\><userinput>scons -Q</userinput> key = OBJSUFFIX, value = .obj key = LIBSUFFIX, value = .lib key = PROGSUFFIX, value = .exe scons: `.' is up to date. - </literallayout> + </screen> + + <para> + + If you want to loop through and print the values of + all of the construction variables in a construction environment, + the Python code to do that in sorted order might look something like: + + </para> + + <programlisting> + env = Environment() + dict = env.Dictionary() + keys = dict.keys() + keys.sort() + for key in keys: + print "construction variable = '%s', value = '%s'" % (key, dict[key]) + </programlisting> + + </section> + + <section> + <title>Expanding Values From a &ConsEnv;</title> + + <para> + + Another way to get information from + a construction environment. + is to use the &subst; method + on a string containing $-expansions + of construction variable names. + As a simple example, + the example from the previous + section that used + <literal>env['CC']</literal> + to fetch the value of &CC; + could also be written as: + + </para> + + <programlisting> + env = Environment() + print "CC is:", env.subst('$CC') + </programlisting> + + <para> + + The real advantage of using + &subst; to expand strings is + that construction variables + in the result get + re-expanded until + there are no expansions left in the string. + So a simple fetch of a value like + <varname>$CCCOM</varname>: + + </para> + + <programlisting> + env = Environment(CCFLAGS = '-DFOO') + print "CCCOM is:", env['CCCOM'] + </programlisting> + + <para> + + Will print the unexpanded value of &CCCOM;, + showing us the construction + variables that still need to be expanded: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + CCCOM is: $CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES + scons: `.' is up to date. + </screen> + + <para> + + Calling the &subst; method on <varname>$CCOM</varname>, + however: + + </para> + + <programlisting> + env = Environment(CCFLAGS = '-DFOO') + print "CCCOM is:", env.subst('$CCCOM') + </programlisting> + + <para> + + Will recursively expand all of + the $-prefixed construction variables, + showing us the final output: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + CCCOM is: gcc -DFOO -c -o + scons: `.' is up to date. + </screen> + + <para> + + (Note that because we're not expanding this + in the context of building something + there are no target or source files + for <varname>$TARGET</varname> and <varname>$SOURCES</varname> to expand. + + </para> </section> @@ -735,24 +873,117 @@ environment undisturbed. <programlisting> env = Environment(CCFLAGS = '-DDEFINE1') + env.Replace(CCFLAGS = '-DDEFINE2') + env.Program('foo.c') + </programlisting> + + <para> + + The replacing value + (<literal>-DDEFINE2</literal> in the above example) + completely replaces the value in the + construction environment: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + cc -DDEFINE2 -c -o foo.o foo.c + cc -o foo foo.o + </screen> + + <para> + + You can safely call &Replace; + for construction variables that + don't exist in the construction environment: + + </para> + + <programlisting> + env = Environment() + env.Replace(NEW_VARIABLE = 'xyzzy') + print "NEW_VARIABLE =", env['NEW_VARIABLE'] + </programlisting> + + <para> + + In this case, + the construction variable simply + gets added to the construction environment: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + NEW_VARIABLE = xyzzy + scons: `.' is up to date. + </screen> + + <para> + + Because the variables + aren't expanded until the construction environment + is actually used to build the targets, + and because &SCons; function and method calls + are order-independent, + the last replacement "wins" + and is used to build all targets, + regardless of the order in which + the calls to Replace() are + interspersed with calls to + builder methods: + + </para> + + <programlisting> + env = Environment(CCFLAGS = '-DDEFINE1') + print "CCFLAGS =", env['CCFLAGS'] env.Program('foo.c') + env.Replace(CCFLAGS = '-DDEFINE2') + print "CCFLAGS =", env['CCFLAGS'] env.Program('bar.c') </programlisting> <para> - The replaced value completely overwrites + The timing of when the replacement + actually occurs relative + to when the targets get built + becomes apparent + if we run &scons; without the <literal>-Q</literal> + option: </para> - <literallayout> - % <userinput>scons -Q</userinput> + <screen> + % <userinput>scons</userinput> + scons: Reading SConscript files ... + CCFLAGS = -DDEFINE1 + CCFLAGS = -DDEFINE2 + scons: done reading SConscript files. + scons: Building targets ... cc -DDEFINE2 -c -o bar.o bar.c cc -o bar bar.o - cc -DDEFINE1 -c -o foo.o foo.c + cc -DDEFINE2 -c -o foo.o foo.c cc -o foo foo.o - </literallayout> + scons: done building targets. + </screen> + + <para> + + Because the replacement occurs while + the &SConscript; files are being read, + the <literal>$CCFLAGS</literal> + variable has already been set to + <literal>-DDEFINE2</literal> + by the time the &foo_o; target is built, + even though the call to the &Replace; + method does not occur until later in + the &SConscript; file. + + </para> </section> @@ -773,11 +1004,43 @@ environment undisturbed. env.Program('foo.c') </programlisting> - <literallayout> + <para> + + &SCons; then supplies both the <literal>-DMY_VALUE</literal> and + <literal>-DLAST</literal> flags when compiling the object file: + + </para> + + <screen> % <userinput>scons -Q</userinput> cc -DMY_VALUE -DLAST -c -o foo.o foo.c cc -o foo foo.o - </literallayout> + </screen> + + <para> + + If the construction variable doesn't already exist, + the &Append; method will create it: + + </para> + + <programlisting> + env = Environment() + env.Append(NEW_VARIABLE = 'added') + print "NEW_VARIABLE =", env['NEW_VARIABLE'] + </programlisting> + + <para> + + Which yields: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + NEW_VARIABLE = added + scons: `.' is up to date. + </screen> </section> @@ -798,11 +1061,43 @@ environment undisturbed. env.Program('foo.c') </programlisting> - <literallayout> + <para> + + &SCons; then supplies both the <literal>-DFIRST</literal> and + <literal>-DMY_VALUE</literal> flags when compiling the object file: + + </para> + + <screen> % <userinput>scons -Q</userinput> cc -DFIRST -DMY_VALUE -c -o foo.o foo.c cc -o foo foo.o - </literallayout> + </screen> + + <para> + + If the construction variable doesn't already exist, + the &Prepend; method will create it: + + </para> + + <programlisting> + env = Environment() + env.Prepend(NEW_VARIABLE = 'added') + print "NEW_VARIABLE =", env['NEW_VARIABLE'] + </programlisting> + + <para> + + Which yields: + + </para> + + <screen> + % <userinput>scons -Q</userinput> + NEW_VARIABLE = added + scons: `.' is up to date. + </screen> </section> |