doc/user/environments.sgml

   1 <!--
   2
   3   Copyright (c) 2001, 2002, 2003 Steven Knight
   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 &consenv; 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;
 414    method which you have already seen.
 415    What you haven't seen, though,
 416    is that when you initialize a &consenv;,
 417    you can set the values of the
 418    environment's &consvars;
 419    to control how a program is built.
 420    For example:
 421
 422  </para>
 423
 424  <programlisting>
 425     env = Environment(CC = 'gcc',
 426                       CCFLAGS = '-O2')
 427
 428     env.Program('foo.c')
 429  </programlisting>
 430
 431  <para>
 432
 433    This example, rather than using the default,
 434    explicitly specifies use of the
 435    GNU C compiler &gcc;,
 436    and further specifies that the <literal>-O2</literal>
 437    (optimization level two)
 438    flag should be used when compiling the object file.
 439    So a run from this example would look like:
 440
 441  </para>
 442
 443  <literallayout>
 444     % <userinput>scons</userinput>
 445     gcc -c -O2 foo.c -o foo.o
 446     gcc -o foo foo.o
 447  </literallayout>
 448
 449  <section>
 450  <title>Multiple &ConsEnvs;</title>
 451
 452    <para>
 453
 454    So far,
 455    all of our examples have
 456    created a single &consenv; named
 457    <literal>env</literal>.
 458    <literal>env</literal>, however,
 459    is simply a Python variable name,
 460    and you can use any other variable name that you like.
 461    For example:
 462
 463    </para>
 464
 465    <programlisting>
 466       my_env = Environment(CC = 'gcc',
 467                            CCFLAGS = '-O2')
 468
 469       my_env.Program('foo.c')
 470    </programlisting>
 471
 472    <para>
 473
 474    This opens up the possibility of
 475    using multiple &consenvs;,
 476    each with a separate variable name.
 477    We can then use these separate &consenvs;
 478    to build different programs in different ways:
 479
 480    </para>
 481
 482    <programlisting>
 483       opt = Environment(CCFLAGS = '-O2')
 484       dbg = Environment(CCFLAGS = '-g')
 485
 486       opt.Program('foo', 'foo.c')
 487
 488       dbg.Program('bar', 'bar.c')
 489    </programlisting>
 490
 491    <literallayout>
 492       % <userinput>scons</userinput>
 493       cc -c -O2 bar.c -o bar.o
 494       cc -o bar bar.o
 495       cc -c -g foo.c -o foo.o
 496       cc -o foo foo.o
 497    </literallayout>
 498
 499    <para>
 500
 501    We can even use multiple &consenvs; to build
 502    multiple versions of a single program.
 503    If you do this by simply trying to use the
 504    &Program; builder with both environments, though,
 505    like this:
 506
 507    </para>
 508
 509    <programlisting>
 510       opt = Environment(CCFLAGS = '-O2')
 511       dbg = Environment(CCFLAGS = '-g')
 512
 513       opt.Program('foo', 'foo.c')
 514
 515       dbg.Program('foo', 'foo.c')
 516    </programlisting>
 517
 518    <para>
 519
 520    Then &SCons; generates the following error:
 521
 522    </para>
 523
 524    <literallayout>
 525       % <userinput>scons</userinput>
 526       scons: *** Two different environments were specified for the same target:  foo.o
 527       File "SConstruct", line 6, in ?
 528    </literallayout>
 529
 530    <para>
 531
 532    This is because the two &Program; calls have
 533    each implicitly told &SCons; to generate an object file named
 534    <filename>foo.o</filename>,
 535    one with a &CCFLAGS; value of
 536    <literal>-O2</literal>
 537    and one with a &CCFLAGS; value of
 538    <literal>-g</literal>.
 539    To avoid this problem,
 540    we must explicitly specify
 541    that each environment compile
 542    <filename>foo.c</filename>
 543    to a separately-named object file
 544    using the &Object; call, like so:
 545
 546    </para>
 547
 548    <programlisting>
 549       opt = Environment(CCFLAGS = '-O2')
 550       dbg = Environment(CCFLAGS = '-g')
 551
 552       o = opt.Object('foo-opt', 'foo.c')
 553       opt.Program(o)
 554
 555       d = dbg.Object('foo-dbg', 'foo.c')
 556       dbg.Program(d)
 557    </programlisting>
 558
 559    <para>
 560
 561    Notice that each call to the &Object; builder
 562    returns a value,
 563    an internal &SCons; object that
 564    represents the file that will be built.
 565    We then use that object
 566    as input to the &Program; builder.
 567    This avoids having to specify explicitly
 568    the object file name in multiple places,
 569    and makes for a compact, readable
 570    &SConstruct; file.
 571    Our &SCons; output then looks like:
 572
 573    </para>
 574
 575    <literallayout>
 576       % <userinput>scons</userinput>
 577       cc -c -g foo.c -o foo-dbg.o
 578       cc -o foo-dbg foo-dbg.o
 579       cc -c -O2 foo.c -o foo-opt.o
 580       cc -o foo-opt foo-opt.o
 581    </literallayout>
 582
 583  </section>
 584
 585  <section>
 586  <title>Copying &ConsEnvs;</title>
 587
 588    <para>
 589
 590    Sometimes you want more than one &consenv;
 591    to share the same values for one or more variables.
 592    Rather than always having to repeat all of the common
 593    variables when you create each &consenv;,
 594    you can use the &Copy; method
 595    to create a copy of a &consenv;.
 596
 597    </para>
 598
 599    <para>
 600
 601    Like the &Environment; call that creates a &consenv;,
 602    the &Copy; method takes &consvar; assignments,
 603    which will override the values in the copied &consenv;.
 604    For example, suppose we want to use &gcc;
 605    to create three versions of a program,
 606    one optimized, one debug, and one with neither.
 607    We could do this by creating a "base" &consenv;
 608    that sets &CC; to &gcc;,
 609    and then creating two copies,
 610    one which sets &CCFLAGS; for optimization
 611    and the other with sets &CCFLAGS; for debugging:
 612
 613    </para>
 614
 615    <programlisting>
 616       env = Environment(CC = 'gcc')
 617       opt = env.Copy(CCFLAGS = '-O2')
 618       dbg = env.Copy(CCFLAGS = '-g')
 619
 620       e = opt.Object('foo', 'foo.c')
 621
 622       o = opt.Object('foo-opt', 'foo.c')
 623       opt.Program(o)
 624
 625       d = dbg.Object('foo-dbg', 'foo.c')
 626       dbg.Program(d)
 627    </programlisting>
 628
 629    <para>
 630
 631    Then our output would look like:
 632
 633    </para>
 634
 635    <literallayout>
 636       % <userinput>scons</userinput>
 637       gcc -c foo.c -o foo.o
 638       gcc -o foo foo.o
 639       gcc -c -g foo.c -o foo-dbg.o
 640       gcc -o foo-dbg foo-dbg.o
 641       gcc -c -O2 foo.c -o foo-opt.o
 642       gcc -o foo-opt foo-opt.o
 643    </literallayout>
 644
 645  </section>
 646
 647  <section>
 648  <title>Fetching Values From a &ConsEnv;</title>
 649
 650    <para>
 651
 652    You can fetch individual construction variables
 653    using the normal syntax
 654    for accessing individual named items in a Python dictionary:
 655
 656    </para>
 657
 658    <programlisting>
 659       env = Environment()
 660       print "CC is:", env['CC']
 661    </programlisting>
 662
 663    <para>
 664
 665    This example &SConstruct; file doesn't build anything,
 666    but because it's actually a Python script,
 667    it will print the value of &CC; for us:
 668
 669    </para>
 670
 671    <literallayout>
 672       % <userinput>scons</userinput>
 673       CC is: cc
 674    </literallayout>
 675
 676    <para>
 677
 678    A &consenv;, however,
 679    is actually a Python object with
 680    associated methods, etc.
 681    If you want to have direct access to only the
 682    dictionary of construction variables,
 683    you can fetch this using the &Dictionary; method:
 684
 685    </para>
 686
 687    <programlisting>
 688       env = Environment(FOO = 'foo', BAR = 'bar')
 689       dict = env.Dictionary()
 690       for key, value in dict.items():
 691           print "key = %s, value = %s % (key, value)
 692    </programlisting>
 693
 694    <para>
 695
 696    This &SConstruct; file
 697    will print the dictionary items for us as follows:
 698
 699    </para>
 700
 701    <literallayout>
 702       % <userinput>scons</userinput>
 703       key = FOO, value = foo
 704       key = BAR, value = bar
 705    </literallayout>
 706
 707  </section>
 708
 709  <section>
 710  <title>Modifying a &ConsEnv;</title>
 711
 712    <para>
 713
 714    &SCons; provides various methods that
 715    support modifying existing values in a &consenv;.
 716
 717    </para>
 718
 719    <section>
 720    <title>Replacing Values in a &ConsEnv;</title>
 721
 722      <para>
 723
 724      You can replace existing construction variable values
 725      using the &Replace; method:
 726
 727      </para>
 728
 729      <programlisting>
 730         env = Environment(CCFLAGS = '-DDEFINE1)
 731         env.Program('foo.c')
 732         env.Replace(CCFLAGS = '-DDEFINE2')
 733         env.Program('bar.c')
 734      </programlisting>
 735
 736      <para>
 737
 738      The replaced value completely overwrites
 739
 740      </para>
 741
 742      <literallayout>
 743         % <userinput>scons</userinput>
 744         gcc -DDEFINE2 -c bar.c -o bar.o
 745         gcc -o bar bar.o
 746         gcc -DDEFINE2 -c foo.c -o foo.o
 747         gcc -o foo foo.o
 748      </literallayout>
 749
 750    </section>
 751
 752    <section>
 753    <title>Appending to the End of Values in a &ConsEnv;</title>
 754
 755      <para>
 756
 757      You can append a value to
 758      an existing construction variable
 759      using the &Append; method:
 760
 761      </para>
 762
 763      <programlisting>
 764         env = Environment(CCFLAGS = '-DMY_VALUE')
 765         env.Append(CCFLAGS = ' -DLAST')
 766         env.Program('foo.c')
 767      </programlisting>
 768
 769      <literallayout>
 770         % <userinput>scons</userinput>
 771         gcc -DMY_VALUE -DLAST -c foo.c -o foo.o
 772         gcc -o foo foo.o
 773      </literallayout>
 774
 775    </section>
 776
 777    <section>
 778    <title>Appending to the Beginning of Values in a &ConsEnv;</title>
 779
 780      <para>
 781
 782      You can append a value to the beginning
 783      an existing construction variable
 784      using the &Prepend; method:
 785
 786      </para>
 787
 788      <programlisting>
 789         env = Environment(CCFLAGS = '-DMY_VALUE')
 790         env.Prepend(CCFLAGS = '-DFIRST ')
 791         env.Program('foo.c')
 792      </programlisting>
 793
 794      <literallayout>
 795         % <userinput>scons</userinput>
 796         gcc -DFIRST -DMY_VALUE -c foo.c -o foo.o
 797         gcc -o foo foo.o
 798      </literallayout>
 799
 800    </section>
 801
 802  </section>