doc/user/environments.sgml

   1 <!--
   2
   3   __COPYRIGHT__
   4
   5   Permission is hereby granted, free of charge, to any person obtaining
   6   a copy of this software and associated documentation files (the
   7   "Software"), to deal in the Software without restriction, including
   8   without limitation the rights to use, copy, modify, merge, publish,
   9   distribute, sublicense, and/or sell copies of the Software, and to
  10   permit persons to whom the Software is furnished to do so, subject to
  11   the following conditions:
  12
  13   The above copyright notice and this permission notice shall be included
  14   in all copies or substantial portions of the Software.
  15
  16   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
  17   KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  18   WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  19   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  20   LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  21   OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  22   WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23
  24 -->
  25
  26 <!--
  27
  28 =head1 More on construction environments
  29
  30 As previously mentioned, a B<construction environment> is an object that
  31 has a set of keyword/value pairs and a set of methods, and which is used
  32 to tell Cons how target files should be built.  This section describes
  33 how Cons uses and expands construction environment values to control its
  34 build behavior.
  35
  36 =head2 Construction variable expansion
  37
  38 Construction variables from a construction environment are expanded
  39 by preceding the keyword with a C<%> (percent sign):
  40
  41   Construction variables:
  42         XYZZY => 'abracadabra',
  43
  44   The string:  "The magic word is:  %XYZZY!"
  45   expands to:  "The magic word is:  abracadabra!"
  46
  47 A construction variable name may be surrounded by C<{> and C<}> (curly
  48 braces), which are stripped as part of the expansion.  This can
  49 sometimes be necessary to separate a variable expansion from trailing
  50 alphanumeric characters:
  51
  52   Construction variables:
  53         OPT    => 'value1',
  54         OPTION => 'value2',
  55
  56   The string:  "%OPT %{OPT}ION %OPTION %{OPTION}"
  57   expands to:  "value1 value1ION value2 value2"
  58
  59 Construction variable expansion is recursive, that is, a string
  60 containing C<%->expansions after substitution will be re-expanded until
  61 no further substitutions can be made:
  62
  63   Construction variables:
  64         STRING => 'The result is:  %FOO',
  65         FOO    => '%BAR',
  66         BAR    => 'final value',
  67
  68   The string:  "The string says:  %STRING"
  69   expands to:  "The string says:  The result is:  final value"
  70
  71 If a construction variable is not defined in an environment, then the
  72 null string is substituted:
  73
  74   Construction variables:
  75         FOO => 'value1',
  76         BAR => 'value2',
  77
  78   The string:  "%FOO <%NO_VARIABLE> %BAR"
  79   expands to:  "value1 <> value2"
  80
  81 A doubled C<%%> will be replaced by a single C<%>:
  82
  83   The string:  "Here is a percent sign:  %%"
  84   expands to:  "Here is a percent sign: %"
  85
  86 =head2 Default construction variables
  87
  88 When you specify no arguments when creating a new construction
  89 environment:
  90
  91   $env = new cons();
  92
  93 Cons creates a reference to a new, default construction
  94 environment. This contains a number of construction variables and some
  95 methods. At the present writing, the default construction variables on a
  96 UNIX system are:
  97
  98   CC            => 'cc',
  99   CFLAGS        => '',
 100   CCCOM         => '%CC %CFLAGS %_IFLAGS -c %< -o %>',
 101   CXX           => '%CC',
 102   CXXFLAGS      => '%CFLAGS',
 103   CXXCOM        => '%CXX %CXXFLAGS %_IFLAGS -c %< -o %>',
 104   INCDIRPREFIX  => '-I',
 105   INCDIRSUFFIX  => '',
 106   LINK          => '%CXX',
 107   LINKCOM       => '%LINK %LDFLAGS -o %> %< %_LDIRS %LIBS',
 108   LINKMODULECOM => '%LD -r -o %> %<',
 109   LIBDIRPREFIX  => '-L',
 110   LIBDIRSUFFIX  => '',
 111   AR            => 'ar',
 112   ARFLAGS       => 'r',
 113   ARCOM         => ['%AR %ARFLAGS %> %<', '%RANLIB %>'],
 114   RANLIB        => 'ranlib',
 115   AS            => 'as',
 116   ASFLAGS       => '',
 117   ASCOM         => '%AS %ASFLAGS %< -o %>',
 118   LD            => 'ld',
 119   LDFLAGS       => '',
 120   PREFLIB       => 'lib',
 121   SUFLIB        => '.a',
 122   SUFLIBS       => '.so:.a',
 123   SUFOBJ        => '.o',
 124   SIGNATURE     => [ '*' => 'build' ],
 125   ENV           => { 'PATH' => '/bin:/usr/bin' },
 126
 127
 128 And on a Win32 system (Windows NT), the default construction variables
 129 are (unless the default rule style is set using the B<DefaultRules>
 130 method):
 131
 132   CC            => 'cl',
 133   CFLAGS        => '/nologo',
 134   CCCOM         => '%CC %CFLAGS %_IFLAGS /c %< /Fo%>',
 135   CXXCOM        => '%CXX %CXXFLAGS %_IFLAGS /c %< /Fo%>',
 136   INCDIRPREFIX  => '/I',
 137   INCDIRSUFFIX  => '',
 138   LINK          => 'link',
 139   LINKCOM       => '%LINK %LDFLAGS /out:%> %< %_LDIRS %LIBS',
 140   LINKMODULECOM => '%LD /r /o %> %<',
 141   LIBDIRPREFIX  => '/LIBPATH:',
 142   LIBDIRSUFFIX  => '',
 143   AR            => 'lib',
 144   ARFLAGS       => '/nologo ',
 145   ARCOM         => "%AR %ARFLAGS /out:%> %<",
 146   RANLIB        => '',
 147   LD            => 'link',
 148   LDFLAGS       => '/nologo ',
 149   PREFLIB       => '',
 150   SUFEXE        => '.exe',
 151   SUFLIB        => '.lib',
 152   SUFLIBS       => '.dll:.lib',
 153   SUFOBJ        => '.obj',
 154   SIGNATURE     => [ '*' => 'build' ],
 155
 156 These variables are used by the various methods associated with the
 157 environment. In particular, any method that ultimately invokes an external
 158 command will substitute these variables into the final command, as
 159 appropriate. For example, the C<Objects> method takes a number of source
 160 files and arranges to derive, if necessary, the corresponding object
 161 files:
 162
 163   Objects $env 'foo.c', 'bar.c';
 164
 165 This will arrange to produce, if necessary, F<foo.o> and F<bar.o>. The
 166 command invoked is simply C<%CCCOM>, which expands, through substitution,
 167 to the appropriate external command required to build each object. The
 168 substitution rules will be discussed in detail in the next section.
 169
 170 The construction variables are also used for other purposes. For example,
 171 C<CPPPATH> is used to specify a colon-separated path of include
 172 directories. These are intended to be passed to the C preprocessor and are
 173 also used by the C-file scanning machinery to determine the dependencies
 174 involved in a C Compilation.
 175
 176 Variables beginning with underscore are created by various methods,
 177 and should normally be considered ``internal'' variables. For example,
 178 when a method is called which calls for the creation of an object from
 179 a C source, the variable C<_IFLAGS> is created: this corresponds to the
 180 C<-I> switches required by the C compiler to represent the directories
 181 specified by C<CPPPATH>.
 182
 183 Note that, for any particular environment, the value of a variable is set
 184 once, and then never reset (to change a variable, you must create a new
 185 environment. Methods are provided for copying existing environments for this
 186 purpose). Some internal variables, such as C<_IFLAGS> are created on demand,
 187 but once set, they remain fixed for the life of the environment.
 188
 189 The C<CFLAGS>, C<LDFLAGS>, and C<ARFLAGS> variables all supply a place
 190 for passing options to the compiler, loader, and archiver, respectively.
 191
 192 The C<INCDIRPREFIX> and C<INCDIRSUFFIX> variables specify option
 193 strings to be appended to the beginning and end, respectively, of each
 194 include directory so that the compiler knows where to find F<.h> files.
 195 Similarly, the C<LIBDIRPREFIX> and C<LIBDIRSUFFIX> variables specify the
 196 option string to be appended to the beginning of and end, respectively,
 197 of each directory that the linker should search for libraries.
 198
 199 Another variable, C<ENV>, is used to determine the system environment during
 200 the execution of an external command. By default, the only environment
 201 variable that is set is C<PATH>, which is the execution path for a UNIX
 202 command. For the utmost reproducibility, you should really arrange to set
 203 your own execution path, in your top-level F<Construct> file (or perhaps by
 204 importing an appropriate construction package with the Perl C<use>
 205 command). The default variables are intended to get you off the ground.
 206
 207 =head2 Expanding variables in construction commands
 208
 209 Within a construction command, construction variables will be expanded
 210 according to the rules described above.  In addition to normal variable
 211 expansion from the construction environment, construction commands also
 212 expand the following pseudo-variables to insert the specific input and
 213 output files in the command line that will be executed:
 214
 215 =over 10
 216
 217 =item %>
 218
 219 The target file name.  In a multi-target command, this expands to the
 220 first target mentioned.)
 221
 222 =item %0
 223
 224 Same as C<%E<gt>>.
 225
 226 =item %1, %2, ..., %9
 227
 228 These refer to the first through ninth input file, respectively.
 229
 230 =item %E<lt>
 231
 232 The full set of input file names. If any of these have been used
 233 anywhere else in the current command line (via C<%1>, C<%2>, etc.), then
 234 those will be deleted from the list provided by C<%E<lt>>. Consider the
 235 following command found in a F<Conscript> file in the F<test> directory:
 236
 237   Command $env 'tgt', qw(foo bar baz), qq(
 238         echo %< -i %1 > %>
 239         echo %< -i %2 >> %>
 240         echo %< -i %3 >> %>
 241   );
 242
 243 If F<tgt> needed to be updated, then this would result in the execution of
 244 the following commands, assuming that no remapping has been established for
 245 the F<test> directory:
 246
 247   echo test/bar test/baz -i test/foo > test/tgt
 248   echo test/foo test/baz -i test/bar >> test/tgt
 249   echo test/foo test/bar -i test/baz >> test/tgt
 250
 251 =back
 252
 253 Any of the above pseudo-variables may be followed immediately by one of
 254 the following suffixes to select a portion of the expanded path name:
 255
 256   :a    the absolute path to the file name
 257   :b    the directory plus the file name stripped of any suffix
 258   :d    the directory
 259   :f    the file name
 260   :s    the file name suffix
 261   :F    the file name stripped of any suffix
 262   :S    the absolute path path to a Linked source file
 263
 264 Continuing with the above example, C<%E<lt>:f> would expand to C<foo bar baz>,
 265 and C<%E<gt>:d> would expand to C<test>.
 266
 267 There are additional C<%> elements which affect the command line(s):
 268
 269 =over 10
 270
 271 =item %[ %]
 272
 273 It is possible to programmatically rewrite part of the command by
 274 enclosing part of it between C<%[> and C<%]>.  This will call the
 275 construction variable named as the first word enclosed in the brackets
 276 as a Perl code reference; the results of this call will be used to
 277 replace the contents of the brackets in the command line.  For example,
 278 given an existing input file named F<tgt.in>:
 279
 280   @keywords = qw(foo bar baz);
 281   $env = new cons(X_COMMA => sub { join(",", @_) });
 282   Command $env 'tgt', 'tgt.in', qq(
 283         echo '# Keywords: %[X_COMMA @keywords %]' > %>
 284         cat %< >> %>
 285   );
 286
 287 This will execute:
 288
 289   echo '# Keywords: foo,bar,baz' > tgt
 290   cat tgt.in >> tgt
 291
 292 =item %( %)
 293
 294 Cons includes the text of the command line in the MD5 signature for a
 295 build, so that targets get rebuilt if you change the command line (to
 296 add or remove an option, for example).  Command-line text in between
 297 C<%(> and C<%)>, however, will be ignored for MD5 signature calculation.
 298
 299 Internally, Cons uses C<%(> and C<%)> around include and library
 300 directory options (C<-I> and C<-L> on UNIX systems, C</I> and
 301 C</LIBPATH> on Windows NT) to avoid rebuilds just because the directory
 302 list changes.  Rebuilds occur only if the changed directory list causes
 303 any included I<files> to change, and a changed include file is detected
 304 by the MD5 signature calculation on the actual file contents.
 305
 306 =back
 307
 308 XXX
 309
 310 DESCRIBE THE Literal() FUNCTION, TOO
 311
 312 XXX
 313
 314 =head2 Expanding construction variables in file names
 315
 316 Cons expands construction variables in the source and target file names
 317 passed to the various construction methods according to the expansion
 318 rules described above:
 319
 320   $env = new cons(
 321         DESTDIR =>      'programs',
 322         SRCDIR  =>      'src',
 323   );
 324   Program $env '%DESTDIR/hello', '%SRCDIR/hello.c';
 325
 326 This allows for flexible configuration, through the construction
 327 environment, of directory names, suffixes, etc.
 328
 329 =head1 Default construction methods
 330
 331 The list of default construction methods includes the following:
 332
 333
 334 =head2 The C<new> constructor
 335
 336 The C<new> method is a Perl object constructor. That is, it is not invoked
 337 via a reference to an existing construction environment B<reference>, but,
 338 rather statically, using the name of the Perl B<package> where the
 339 constructor is defined. The method is invoked like this:
 340
 341   $env = new cons(<overrides>);
 342
 343 The environment you get back is blessed into the package C<cons>, which
 344 means that it will have associated with it the default methods described
 345 below. Individual construction variables can be overridden by providing
 346 name/value pairs in an override list. Note that to override any command
 347 environment variable (i.e. anything under C<ENV>), you will have to override
 348 all of them. You can get around this difficulty by using the C<copy> method
 349 on an existing construction environment.
 350
 351
 352 =head2 The C<clone> method
 353
 354 The C<clone> method creates a clone of an existing construction environment,
 355 and can be called as in the following example:
 356
 357   $env2 = $env1->clone(<overrides>);
 358
 359 You can provide overrides in the usual manner to create a different
 360 environment from the original. If you just want a new name for the same
 361 environment (which may be helpful when exporting environments to existing
 362 components), you can just use simple assignment.
 363
 364
 365 =head2 The C<copy> method
 366
 367 The C<copy> method extracts the externally defined construction variables
 368 from an environment and returns them as a list of name/value
 369 pairs. Overrides can also be provided, in which case, the overridden values
 370 will be returned, as appropriate. The returned list can be assigned to a
 371 hash, as shown in the prototype, below, but it can also be manipulated in
 372 other ways:
 373
 374   %env = $env1->copy(<overrides>);
 375
 376 The value of C<ENV>, which is itself a hash, is also copied to a new hash,
 377 so this may be changed without fear of affecting the original
 378 environment. So, for example, if you really want to override just the
 379 C<PATH> variable in the default environment, you could do the following:
 380
 381   %cons = new cons()->copy();
 382   $cons{ENV}{PATH} = "<your path here>";
 383   $cons = new cons(%cons);
 384
 385 This will leave anything else that might be in the default execution
 386 environment undisturbed.
 387
 388 -->
 389
 390  <para>
 391
 392    It is rare that all of the software in a large,
 393    complicated system needs to be built the same way.
 394    For example, different source files may need different options
 395    enabled on the command line,
 396    or different executable programs need to be linked
 397    with different libraries.
 398    &SCons; accomodates these different build
 399    requirements by allowing you to create and
 400    configure multiple &consenvs;
 401    that control how the software is built.
 402    Technically, a &consenv; is an object
 403    that has a number of associated
 404    &consvars;, each with a name and a value.
 405    (A construction environment also has an attached
 406    set of &Builder; methods,
 407    about which we'll learn more later.)
 408
 409  </para>
 410
 411  <para>
 412
 413    A &consenv; is created by the &Environment; method:
 414
 415  </para>
 416
 417   <programlisting>
 418     env = Environment()
 419   </programlisting>
 420
 421  <para>
 422
 423    By default, &SCons; intializes every
 424    new construction environment
 425    with a set of &consvars;
 426    based on the tools that it finds on your system,
 427    plus the default set of builder methods
 428    necessary for using those tools.
 429    The construction variables
 430    are initialized with values describing
 431    the C compiler,
 432    the Fortran compiler,
 433    the linker,
 434    etc.,
 435    as well as the command lines to invoke them.
 436
 437  </para>
 438
 439  <para>
 440
 441    When you initialize a construction environment
 442    you can set the values of the
 443    environment's &consvars;
 444    to control how a program is built.
 445    For example:
 446
 447  </para>
 448
 449   <programlisting>
 450     env = Environment(CC = 'gcc',
 451                       CCFLAGS = '-O2')
 452
 453     env.Program('foo.c')
 454   </programlisting>
 455
 456  <para>
 457
 458    The construction environment in this example
 459    is still initialized with the same default
 460    construction variable values,
 461    except that the user has explicitly specified use of the
 462    GNU C compiler &gcc;,
 463    and further specifies that the <literal>-O2</literal>
 464    (optimization level two)
 465    flag should be used when compiling the object file.
 466    In other words, the explicit initializations of
 467    &cv-link-CC; and &cv-link-CCFLAGS;
 468    override the default values in the newly-created
 469    construction environment.
 470    So a run from this example would look like:
 471
 472  </para>
 473
 474  <screen>
 475     % <userinput>scons -Q</userinput>
 476     gcc -O2 -c -o foo.o foo.c
 477     gcc -o foo foo.o
 478  </screen>
 479
 480  <section>
 481  <title>Multiple &ConsEnvs;</title>
 482
 483    <para>
 484
 485    The real advantage of construction environments
 486    is that you can create as many different construction
 487    environments as you need,
 488    each tailored to a different way to build
 489    some piece of software or other file.
 490    If, for example, we need to build
 491    one program with the <literal>-O2</literal> flag
 492    and another with the <literal>-g</literal> (debug) flag,
 493    we would do this like so:
 494
 495    </para>
 496
 497    <programlisting>
 498       opt = Environment(CCFLAGS = '-O2')
 499       dbg = Environment(CCFLAGS = '-g')
 500
 501       opt.Program('foo', 'foo.c')
 502
 503       dbg.Program('bar', 'bar.c')
 504    </programlisting>
 505
 506    <screen>
 507       % <userinput>scons -Q</userinput>
 508       cc -g -c -o bar.o bar.c
 509       cc -o bar bar.o
 510       cc -O2 -c -o foo.o foo.c
 511       cc -o foo foo.o
 512    </screen>
 513
 514    <para>
 515
 516    We can even use multiple construction environments to build
 517    multiple versions of a single program.
 518    If you do this by simply trying to use the
 519    &b-link-Program; builder with both environments, though,
 520    like this:
 521
 522    </para>
 523
 524    <programlisting>
 525       opt = Environment(CCFLAGS = '-O2')
 526       dbg = Environment(CCFLAGS = '-g')
 527
 528       opt.Program('foo', 'foo.c')
 529
 530       dbg.Program('foo', 'foo.c')
 531    </programlisting>
 532
 533    <para>
 534
 535    Then &SCons; generates the following error:
 536
 537    </para>
 538
 539    <screen>
 540       % <userinput>scons -Q</userinput>
 541
 542       scons: *** Two environments with different actions were specified for the same target: foo.o
 543       File "SConstruct", line 6, in ?
 544    </screen>
 545
 546    <para>
 547
 548    This is because the two &b-Program; calls have
 549    each implicitly told &SCons; to generate an object file named
 550    <filename>foo.o</filename>,
 551    one with a &cv-link-CCFLAGS; value of
 552    <literal>-O2</literal>
 553    and one with a &cv-link-CCFLAGS; value of
 554    <literal>-g</literal>.
 555    &SCons; can't just decide that one of them
 556    should take precedence over the other,
 557    so it generates the error.
 558    To avoid this problem,
 559    we must explicitly specify
 560    that each environment compile
 561    <filename>foo.c</filename>
 562    to a separately-named object file
 563    using the &b-link-Object; builder, like so:
 564
 565    </para>
 566
 567    <programlisting>
 568       opt = Environment(CCFLAGS = '-O2')
 569       dbg = Environment(CCFLAGS = '-g')
 570
 571       o = opt.Object('foo-opt', 'foo.c')
 572       opt.Program(o)
 573
 574       d = dbg.Object('foo-dbg', 'foo.c')
 575       dbg.Program(d)
 576    </programlisting>
 577
 578    <para>
 579
 580    Notice that each call to the &b-Object; builder
 581    returns a value,
 582    an internal &SCons; object that
 583    represents the object file that will be built.
 584    We then use that object
 585    as input to the &b-Program; builder.
 586    This avoids having to specify explicitly
 587    the object file name in multiple places,
 588    and makes for a compact, readable
 589    &SConstruct; file.
 590    Our &SCons; output then looks like:
 591
 592    </para>
 593
 594    <screen>
 595       % <userinput>scons -Q</userinput>
 596       cc -g -c -o foo-dbg.o foo.c
 597       cc -o foo-dbg foo-dbg.o
 598       cc -O2 -c -o foo-opt.o foo.c
 599       cc -o foo-opt foo-opt.o
 600    </screen>
 601
 602  </section>
 603
 604  <section>
 605  <title>Copying &ConsEnvs;</title>
 606
 607    <para>
 608
 609    Sometimes you want more than one construction environment
 610    to share the same values for one or more variables.
 611    Rather than always having to repeat all of the common
 612    variables when you create each construction environment,
 613    you can use the &Copy; method
 614    to create a copy of a construction environment.
 615
 616    </para>
 617
 618    <para>
 619
 620    Like the &Environment; call that creates a construction environment,
 621    the &Copy; method takes &consvar; assignments,
 622    which will override the values in the copied construction environment.
 623    For example, suppose we want to use &gcc;
 624    to create three versions of a program,
 625    one optimized, one debug, and one with neither.
 626    We could do this by creating a "base" construction environment
 627    that sets &cv-link-CC; to &gcc;,
 628    and then creating two copies,
 629    one which sets &cv-link-CCFLAGS; for optimization
 630    and the other which sets &cv-CCFLAGS; for debugging:
 631
 632    </para>
 633
 634    <programlisting>
 635       env = Environment(CC = 'gcc')
 636       opt = env.Copy(CCFLAGS = '-O2')
 637       dbg = env.Copy(CCFLAGS = '-g')
 638
 639       env.Program('foo', 'foo.c')
 640
 641       o = opt.Object('foo-opt', 'foo.c')
 642       opt.Program(o)
 643
 644       d = dbg.Object('foo-dbg', 'foo.c')
 645       dbg.Program(d)
 646    </programlisting>
 647
 648    <para>
 649
 650    Then our output would look like:
 651
 652    </para>
 653
 654    <screen>
 655       % <userinput>scons -Q</userinput>
 656       gcc -c -o foo.o foo.c
 657       gcc -o foo foo.o
 658       gcc -g -c -o foo-dbg.o foo.c
 659       gcc -o foo-dbg foo-dbg.o
 660       gcc -O2 -c -o foo-opt.o foo.c
 661       gcc -o foo-opt foo-opt.o
 662    </screen>
 663
 664  </section>
 665
 666  <section>
 667  <title>Fetching Values From a &ConsEnv;</title>
 668
 669    <para>
 670
 671    You can fetch individual construction variables
 672    using the normal syntax
 673    for accessing individual named items in a Python dictionary:
 674
 675    </para>
 676
 677    <programlisting>
 678       env = Environment()
 679       print "CC is:", env['CC']
 680    </programlisting>
 681
 682    <para>
 683
 684    This example &SConstruct; file doesn't build anything,
 685    but because it's actually a Python script,
 686    it will print the value of &cv-link-CC; for us:
 687
 688    </para>
 689
 690    <screen>
 691       % <userinput>scons -Q</userinput>
 692       CC is: cc
 693       scons: `.' is up to date.
 694    </screen>
 695
 696    <para>
 697
 698    A construction environment, however,
 699    is actually an object with associated methods, etc.
 700    If you want to have direct access to only the
 701    dictionary of construction variables,
 702    you can fetch this using the &Dictionary; method:
 703
 704    </para>
 705
 706    <programlisting>
 707       env = Environment(FOO = 'foo', BAR = 'bar')
 708       dict = env.Dictionary()
 709       for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']:
 710           print "key = %s, value = %s" % (key, dict[key])
 711    </programlisting>
 712
 713    <para>
 714
 715    This &SConstruct; file
 716    will print the specified dictionary items for us on POSIX
 717    systems as follows:
 718
 719    </para>
 720
 721    <screen>
 722       % <userinput>scons -Q</userinput>
 723       key = OBJSUFFIX, value = .o
 724       key = LIBSUFFIX, value = .a
 725       key = PROGSUFFIX, value =
 726       scons: `.' is up to date.
 727    </screen>
 728
 729    <para>
 730
 731    And on Win32:
 732
 733    </para>
 734
 735    <screen>
 736       C:\><userinput>scons -Q</userinput>
 737       key = OBJSUFFIX, value = .obj
 738       key = LIBSUFFIX, value = .lib
 739       key = PROGSUFFIX, value = .exe
 740       scons: `.' is up to date.
 741    </screen>
 742
 743    <para>
 744
 745    If you want to loop through and print the values of
 746    all of the construction variables in a construction environment,
 747    the Python code to do that in sorted order might look something like:
 748
 749    </para>
 750
 751    <programlisting>
 752       env = Environment()
 753       dict = env.Dictionary()
 754       keys = dict.keys()
 755       keys.sort()
 756       for key in keys:
 757           print "construction variable = '%s', value = '%s'" % (key, dict[key])
 758    </programlisting>
 759
 760  </section>
 761
 762  <section>
 763  <title>Expanding Values From a &ConsEnv;</title>
 764
 765    <para>
 766
 767    Another way to get information from
 768    a construction environment.
 769    is to use the &subst; method
 770    on a string containing $-expansions
 771    of construction variable names.
 772    As a simple example,
 773    the example from the previous
 774    section that used
 775    <literal>env['CC']</literal>
 776    to fetch the value of &cv-link-CC;
 777    could also be written as:
 778
 779    </para>
 780
 781    <programlisting>
 782      env = Environment()
 783      print "CC is:", env.subst('$CC')
 784    </programlisting>
 785
 786    <para>
 787
 788    The real advantage of using
 789    &subst; to expand strings is
 790    that construction variables
 791    in the result get
 792    re-expanded until
 793    there are no expansions left in the string.
 794    So a simple fetch of a value like
 795    &cv-link-CCCOM;:
 796
 797    </para>
 798
 799    <programlisting>
 800      env = Environment(CCFLAGS = '-DFOO')
 801      print "CCCOM is:", env['CCCOM']
 802    </programlisting>
 803
 804    <para>
 805
 806    Will print the unexpanded value of &cv-CCCOM;,
 807    showing us the construction
 808    variables that still need to be expanded:
 809
 810    </para>
 811
 812    <screen>
 813      % <userinput>scons -Q</userinput>
 814      CCCOM is: $CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
 815      scons: `.' is up to date.
 816    </screen>
 817
 818    <para>
 819
 820    Calling the &subst; method on <varname>$CCOM</varname>,
 821    however:
 822
 823    </para>
 824
 825    <programlisting>
 826      env = Environment(CCFLAGS = '-DFOO')
 827      print "CCCOM is:", env.subst('$CCCOM')
 828    </programlisting>
 829
 830    <para>
 831
 832    Will recursively expand all of
 833    the $-prefixed construction variables,
 834    showing us the final output:
 835
 836    </para>
 837
 838    <screen>
 839      % <userinput>scons -Q</userinput>
 840      CCCOM is: gcc -DFOO -c -o
 841      scons: `.' is up to date.
 842    </screen>
 843
 844    <para>
 845
 846    (Note that because we're not expanding this
 847    in the context of building something
 848    there are no target or source files
 849    for &cv-link-TARGET; and &cv-link-SOURCES; to expand.
 850
 851    </para>
 852
 853  </section>
 854
 855  <section>
 856  <title>Modifying a &ConsEnv;</title>
 857
 858    <para>
 859
 860    &SCons; provides various methods that
 861    support modifying existing values in a construction environment.
 862
 863    </para>
 864
 865    <section>
 866    <title>Replacing Values in a &ConsEnv;</title>
 867
 868      <para>
 869
 870      You can replace existing construction variable values
 871      using the &Replace; method:
 872
 873      </para>
 874
 875      <programlisting>
 876         env = Environment(CCFLAGS = '-DDEFINE1')
 877         env.Replace(CCFLAGS = '-DDEFINE2')
 878         env.Program('foo.c')
 879      </programlisting>
 880
 881      <para>
 882
 883      The replacing value
 884      (<literal>-DDEFINE2</literal> in the above example)
 885      completely replaces the value in the
 886      construction environment:
 887
 888      </para>
 889
 890      <screen>
 891         % <userinput>scons -Q</userinput>
 892         cc -DDEFINE2 -c -o foo.o foo.c
 893         cc -o foo foo.o
 894      </screen>
 895
 896      <para>
 897
 898      You can safely call &Replace;
 899      for construction variables that
 900      don't exist in the construction environment:
 901
 902      </para>
 903
 904      <programlisting>
 905         env = Environment()
 906         env.Replace(NEW_VARIABLE = 'xyzzy')
 907         print "NEW_VARIABLE =", env['NEW_VARIABLE']
 908      </programlisting>
 909
 910      <para>
 911
 912      In this case,
 913      the construction variable simply
 914      gets added to the construction environment:
 915
 916      </para>
 917
 918      <screen>
 919         % <userinput>scons -Q</userinput>
 920         NEW_VARIABLE = xyzzy
 921         scons: `.' is up to date.
 922      </screen>
 923
 924      <para>
 925
 926      Because the variables
 927      aren't expanded until the construction environment
 928      is actually used to build the targets,
 929      and because &SCons; function and method calls
 930      are order-independent,
 931      the last replacement "wins"
 932      and is used to build all targets,
 933      regardless of the order in which
 934      the calls to Replace() are
 935      interspersed with calls to
 936      builder methods:
 937
 938      </para>
 939
 940      <programlisting>
 941         env = Environment(CCFLAGS = '-DDEFINE1')
 942         print "CCFLAGS =", env['CCFLAGS']
 943         env.Program('foo.c')
 944
 945         env.Replace(CCFLAGS = '-DDEFINE2')
 946         print "CCFLAGS =", env['CCFLAGS']
 947         env.Program('bar.c')
 948      </programlisting>
 949
 950      <para>
 951
 952      The timing of when the replacement
 953      actually occurs relative
 954      to when the targets get built
 955      becomes apparent
 956      if we run &scons; without the <literal>-Q</literal>
 957      option:
 958
 959      </para>
 960
 961      <screen>
 962         % <userinput>scons</userinput>
 963         scons: Reading SConscript files ...
 964         CCFLAGS = -DDEFINE1
 965         CCFLAGS = -DDEFINE2
 966         scons: done reading SConscript files.
 967         scons: Building targets ...
 968         cc -DDEFINE2 -c -o bar.o bar.c
 969         cc -o bar bar.o
 970         cc -DDEFINE2 -c -o foo.o foo.c
 971         cc -o foo foo.o
 972         scons: done building targets.
 973      </screen>
 974
 975      <para>
 976
 977      Because the replacement occurs while
 978      the &SConscript; files are being read,
 979      the &cv-link-CCFLAGS;
 980      variable has already been set to
 981      <literal>-DDEFINE2</literal>
 982      by the time the &foo_o; target is built,
 983      even though the call to the &Replace;
 984      method does not occur until later in
 985      the &SConscript; file.
 986
 987      </para>
 988
 989    </section>
 990
 991    <section>
 992    <title>Appending to the End of Values in a &ConsEnv;</title>
 993
 994      <para>
 995
 996      You can append a value to
 997      an existing construction variable
 998      using the &Append; method:
 999
1000      </para>
1001
1002      <programlisting>
1003         env = Environment(CCFLAGS = '-DMY_VALUE')
1004         env.Append(CCFLAGS = ' -DLAST')
1005         env.Program('foo.c')
1006      </programlisting>
1007
1008      <para>
1009
1010      &SCons; then supplies both the <literal>-DMY_VALUE</literal> and
1011      <literal>-DLAST</literal> flags when compiling the object file:
1012
1013      </para>
1014
1015      <screen>
1016         % <userinput>scons -Q</userinput>
1017         cc -DMY_VALUE -DLAST -c -o foo.o foo.c
1018         cc -o foo foo.o
1019      </screen>
1020
1021      <para>
1022
1023      If the construction variable doesn't already exist,
1024      the &Append; method will create it:
1025
1026      </para>
1027
1028      <programlisting>
1029         env = Environment()
1030         env.Append(NEW_VARIABLE = 'added')
1031         print "NEW_VARIABLE =", env['NEW_VARIABLE']
1032      </programlisting>
1033
1034      <para>
1035
1036      Which yields:
1037
1038      </para>
1039
1040      <screen>
1041         % <userinput>scons -Q</userinput>
1042         NEW_VARIABLE = added
1043         scons: `.' is up to date.
1044      </screen>
1045
1046    </section>
1047
1048    <section>
1049    <title>Appending to the Beginning of Values in a &ConsEnv;</title>
1050
1051      <para>
1052
1053      You can append a value to the beginning
1054      an existing construction variable
1055      using the &Prepend; method:
1056
1057      </para>
1058
1059      <programlisting>
1060         env = Environment(CCFLAGS = '-DMY_VALUE')
1061         env.Prepend(CCFLAGS = '-DFIRST ')
1062         env.Program('foo.c')
1063      </programlisting>
1064
1065      <para>
1066
1067      &SCons; then supplies both the <literal>-DFIRST</literal> and
1068      <literal>-DMY_VALUE</literal> flags when compiling the object file:
1069
1070      </para>
1071
1072      <screen>
1073         % <userinput>scons -Q</userinput>
1074         cc -DFIRST -DMY_VALUE -c -o foo.o foo.c
1075         cc -o foo foo.o
1076      </screen>
1077
1078      <para>
1079
1080      If the construction variable doesn't already exist,
1081      the &Prepend; method will create it:
1082
1083      </para>
1084
1085      <programlisting>
1086         env = Environment()
1087         env.Prepend(NEW_VARIABLE = 'added')
1088         print "NEW_VARIABLE =", env['NEW_VARIABLE']
1089      </programlisting>
1090
1091      <para>
1092
1093      Which yields:
1094
1095      </para>
1096
1097      <screen>
1098         % <userinput>scons -Q</userinput>
1099         NEW_VARIABLE = added
1100         scons: `.' is up to date.
1101      </screen>
1102
1103    </section>
1104
1105  </section>