doc/user/command-line.in

   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   <para>
  27
  28   &SCons; provides a number of ways
  29   for the writer of the &SConscript; files
  30   to give the users who will run &SCons;
  31   a great deal of control over the build execution.
  32   The arguments that the user can specify on
  33   the command line are broken down into three types:
  34
  35   </para>
  36
  37   <variablelist>
  38
  39     <varlistentry>
  40     <term>Options</term>
  41
  42     <listitem>
  43     <para>
  44
  45     Command-line options always begin with
  46     one or two <literal>-</literal> (hyphen) characters.
  47     &SCons; provides ways for you to examine
  48     and set options values from within your &SConscript; files,
  49     as well as the ability to define your own
  50     custom options.
  51     See <xref linkend="sect-command-line-options"></xref>, below.
  52
  53     </para>
  54     </listitem>
  55     </varlistentry>
  56
  57     <varlistentry>
  58     <term>Variables</term>
  59
  60     <listitem>
  61     <para>
  62
  63     Any command-line argument containing an <literal>=</literal>
  64     (equal sign) is considered a variable setting with the form
  65     <varname>variable</varname>=<varname>value</varname>
  66     &SCons; provides direct access to
  67     all of the command-line variable settings,
  68     the ability to apply command-line variable settings
  69     to construction environments,
  70     and functions for configuring
  71     specific types of variables
  72     (Boolean values, path names, etc.)
  73     with automatic validation of the user's specified values.
  74     See <xref linkend="sect-command-line-variables"></xref>, below.
  75
  76     </para>
  77     </listitem>
  78     </varlistentry>
  79
  80     <varlistentry>
  81     <term>Targets</term>
  82
  83     <listitem>
  84     <para>
  85
  86     Any command-line argument that is not an option
  87     or a variable setting
  88     (does not begin with a hyphen
  89     and does not contain an equal sign)
  90     is considered a target that the user
  91     (presumably) wants &SCons; to build.
  92     A list of Node objects representing
  93     the target or targets to build.
  94     &SCons; provides access to the list of specified targets,
  95     as well as ways to set the default list of targets
  96     from within the &SConscript; files.
  97     See <xref linkend="sect-command-line-targets"></xref>, below.
  98
  99     </para>
 100     </listitem>
 101     </varlistentry>
 102
 103   </variablelist>
 104
 105   <section id="sect-command-line-options">
 106   <title>Command-Line Options</title>
 107
 108     <para>
 109
 110     &SCons; has many <emphasis>command-line options</emphasis>
 111     that control its behavior.
 112     A &SCons; <emphasis>command-line option</emphasis>
 113     always begins with one or two <literal>-</literal> (hyphen)
 114     characters.
 115
 116     </para>
 117
 118     <section>
 119     <title>Not Having to Specify Command-Line Options Each Time:  the &SCONSFLAGS; Environment Variable</title>
 120
 121       <para>
 122
 123       Users may find themselves supplying
 124       the same command-line options every time
 125       they run &SCons;.
 126       For example, you might find it saves time
 127       to specify a value of <literal>-j 2</literal>
 128       to have &SCons; run up to two build commands in parallel.
 129       To avoid having to type <literal>-j 2</literal> by hand
 130       every time,
 131       you can set the external environment variable
 132       &SCONSFLAGS; to a string containing
 133       command-line options that you want &SCons; to use.
 134
 135       </para>
 136
 137       <para>
 138
 139       If, for example,
 140       you're using a POSIX shell that's
 141       compatible with the Bourne shell,
 142       and you always want &SCons; to use the
 143       <literal>-Q</literal> option,
 144       you can set the &SCONSFLAGS;
 145       environment as follows:
 146
 147       </para>
 148
 149       <scons_example name="SCONSFLAGS">
 150         <file name="SConstruct">
 151         def b(target, source, env):
 152             pass
 153         def s(target, source, env):
 154             return "    ... [build output] ..."
 155         a = Action(b, strfunction = s)
 156         env = Environment(BUILDERS = {'A' : Builder(action=a)})
 157         env.A('foo.out', 'foo.in')
 158         </file>
 159         <file name="foo.in">
 160         foo.in
 161         </file>
 162       </scons_example>
 163
 164       <scons_output example="SCONSFLAGS">
 165         <scons_output_command>scons</scons_output_command>
 166         <scons_output_command>export SCONSFLAGS="-Q"</scons_output_command>
 167         <scons_output_command environment="SCONSFLAGS=-Q">scons</scons_output_command>
 168       </scons_output>
 169
 170       <para>
 171
 172       Users of &csh;-style shells on POSIX systems
 173       can set the &SCONSFLAGS; environment as follows:
 174
 175       </para>
 176
 177       <screen>
 178         $ <userinput>setenv SCONSFLAGS "-Q"</userinput>
 179       </screen>
 180
 181       <para>
 182
 183       Windows users may typically want to set the
 184       &SCONSFLAGS; in the appropriate tab of the
 185       <literal>System Properties</literal> window.
 186
 187       </para>
 188
 189     </section>
 190
 191     <section>
 192     <title>Getting Values Set by Command-Line Options:  the &GetOption; Function</title>
 193
 194       <para>
 195
 196       &SCons; provides the &GetOption; function
 197       to get the values set by the various command-line options.
 198       One common use of this is to check whether or not
 199       the <literal>-h</literal> or <literal>--help</literal> option
 200       has been specified.
 201       Normally, &SCons; does not print its help text
 202       until after it has read all of the &SConscript; files,
 203       because it's possible that help text has been added
 204       by some subsidiary &SConscript; file deep in the
 205       source tree hierarchy.
 206       Of course, reading all of the &SConscript; files
 207       takes extra time.
 208
 209       </para>
 210
 211       <para>
 212
 213       If you know that your configuration does not define
 214       any additional help text in subsidiary &SConscript; files,
 215       you can speed up the command-line help available to users
 216       by using the &GetOption; function to load the
 217       subsidiary &SConscript; files only if the
 218       the user has <emphasis>not</emphasis> specified
 219       the <literal>-h</literal> or <literal>--help</literal> option,
 220       like so:
 221
 222       </para>
 223
 224       <sconstruct)
 225         if not GetOption('help'):
 226             SConscript('src/SConscript', export='env')
 227       </sconstruct>
 228
 229       <para>
 230
 231       In general, the string that you pass to the
 232       &GetOption; function to fetch the value of a command-line
 233       option setting is the same as the "most common" long option name
 234       (beginning with two hyphen characters),
 235       although there are some exceptions.
 236       The list of &SCons; command-line options
 237       and the &GetOption; strings for fetching them,
 238       are available in the
 239       <xref linkend="sect-command-line-option-strings"></xref> section,
 240       below.
 241
 242       </para>
 243
 244     </section>
 245
 246     <section>
 247     <title>Setting Values of Command-Line Options:  the &SetOption; Function</title>
 248
 249       <para>
 250
 251       You can also set the values of &SCons;
 252       command-line options from within the &SConscript; files
 253       by using the &SetOption; function.
 254       The strings that you use to set the values of &SCons;
 255       command-line options are available in the
 256       <xref linkend="sect-command-line-option-strings"></xref> section,
 257       below.
 258
 259       </para>
 260
 261       <para>
 262
 263       One use of the &SetOption; function is to
 264       specify a value for the <literal>-j</literal>
 265       or <literal>--jobs</literal> option,
 266       so that users get the improved performance
 267       of a parallel build without having to specify the option by hand.
 268       A complicating factor is that a good value
 269       for the <literal>-j</literal> option is
 270       somewhat system-dependent.
 271       One rough guideline is that the more processors
 272       your system has,
 273       the higher you want to set the
 274       <literal>-j</literal> value,
 275       in order to take advantage of the number of CPUs.
 276
 277       </para>
 278
 279       <para>
 280
 281       For example, suppose the administrators
 282       of your development systems
 283       have standardized on setting a
 284       <varname>NUM_CPU</varname> environment variable
 285       to the number of processors on each system.
 286       A little bit of Python code
 287       to access the environment variable
 288       and the &SetOption; function
 289       provide the right level of flexibility:
 290
 291       </para>
 292
 293       <scons_example name="SetOption">
 294         <file name="SConstruct" printme="1">
 295         import os
 296         num_cpu = int(os.environ.get('NUM_CPU', 2))
 297         SetOption('num_jobs', num_cpu)
 298         print "running with -j", GetOption('num_jobs')
 299         </file>
 300         <file name="foo.in">
 301         foo.in
 302         </file>
 303       </scons_example>
 304
 305       <para>
 306
 307       The above snippet of code
 308       sets the value of the <literal>--jobs</literal> option
 309       to the value specified in the
 310       <varname>$NUM_CPU</varname> environment variable.
 311       (This is one of the exception cases
 312       where the string is spelled differently from
 313       the from command-line option.
 314       The string for fetching or setting the <literal>--jobs</literal>
 315       value is <literal>num_jobs</literal>
 316       for historical reasons.)
 317       The code in this example prints the <literal>num_jobs</literal>
 318       value for illustrative purposes.
 319       It uses a default value of <literal>2</literal>
 320       to provide some minimal parallelism even on
 321       single-processor systems:
 322
 323       </para>
 324
 325       <scons_output example="SetOption">
 326         <scons_output_command>scons -Q</scons_output_command>
 327       </scons_output>
 328
 329       <para>
 330
 331       But if the <varname>$NUM_CPU</varname>
 332       environment variable is set,
 333       then we use that for the default number of jobs:
 334
 335       </para>
 336
 337       <scons_output example="SetOption">
 338         <scons_output_command>export NUM_CPU="4"</scons_output_command>
 339         <scons_output_command environment="NUM_CPU=4">scons -Q</scons_output_command>
 340       </scons_output>
 341
 342       <para>
 343
 344       But any explicit
 345       <literal>-j</literal> or <literal>--jobs</literal>
 346       value the user specifies an the command line is used first,
 347       regardless of whether or not
 348       the <varname>$NUM_CPU</varname> environment
 349       variable is set:
 350
 351       </para>
 352
 353       <scons_output example="SetOption">
 354         <scons_output_command>scons -Q -j 7</scons_output_command>
 355         <scons_output_command>export NUM_CPU="4"</scons_output_command>
 356         <scons_output_command environment="NUM_CPU=4">scons -Q -j 3</scons_output_command>
 357       </scons_output>
 358
 359     </section>
 360
 361     <section id="sect-command-line-option-strings">
 362     <title>Strings for Getting or Setting Values of &SCons; Command-Line Options</title>
 363
 364       <para>
 365
 366       The strings that you can pass to the &GetOption;
 367       and &SetOption; functions usually correspond to the
 368       first long-form option name
 369       (beginning with two hyphen characters:  <literal>--</literal>),
 370       after replacing any remaining hyphen characters
 371       with underscores.
 372
 373       </para>
 374
 375       <para>
 376
 377       The full list of strings and the variables they
 378       correspond to is as follows:
 379
 380       </para>
 381
 382       <informaltable>
 383       <tgroup cols="2" align="left">
 384
 385       <thead>
 386
 387       <row>
 388       <entry>String for &GetOption; and &SetOption;</entry>
 389       <entry>Command-Line Option(s)</entry>
 390       </row>
 391
 392       </thead>
 393
 394       <tbody>
 395
 396       <row>
 397       <entry><literal>cache_debug</literal></entry>
 398       <entry><option>--cache-debug</option></entry>
 399       </row>
 400
 401       <row>
 402       <entry><literal>cache_disable</literal></entry>
 403       <entry><option>--cache-disable</option></entry>
 404       </row>
 405
 406       <row>
 407       <entry><literal>cache_force</literal></entry>
 408       <entry><option>--cache-force</option></entry>
 409       </row>
 410
 411       <row>
 412       <entry><literal>cache_show</literal></entry>
 413       <entry><option>--cache-show</option></entry>
 414       </row>
 415
 416       <row>
 417       <entry><literal>clean</literal></entry>
 418       <entry><option>-c</option>,
 419            <option>--clean</option>,
 420            <option>--remove</option></entry>
 421       </row>
 422
 423       <row>
 424       <entry><literal>config</literal></entry>
 425       <entry><option>--config</option></entry>
 426       </row>
 427
 428       <row>
 429       <entry><literal>directory</literal></entry>
 430       <entry><option>-C</option>,
 431              <option>--directory</option></entry>
 432       </row>
 433
 434       <row>
 435       <entry><literal>diskcheck</literal></entry>
 436       <entry><option>--diskcheck</option></entry>
 437       </row>
 438
 439       <row>
 440       <entry><literal>duplicate</literal></entry>
 441       <entry><option>--duplicate</option></entry>
 442       </row>
 443
 444       <row>
 445       <entry><literal>file</literal></entry>
 446       <entry><option>-f</option>,
 447              <option>--file</option>,
 448              <option>--makefile </option>,
 449              <option>--sconstruct</option></entry>
 450       </row>
 451
 452       <row>
 453       <entry><literal>help</literal></entry>
 454       <entry><option>-h</option>,
 455              <option>--help</option></entry>
 456       </row>
 457
 458       <row>
 459       <entry><literal>ignore_errors</literal></entry>
 460       <entry><option>--ignore-errors</option></entry>
 461       </row>
 462
 463       <row>
 464       <entry><literal>implicit_cache</literal></entry>
 465       <entry><option>--implicit-cache</option></entry>
 466       </row>
 467
 468       <row>
 469       <entry><literal>implicit_deps_changed</literal></entry>
 470       <entry><option>--implicit-deps-changed</option></entry>
 471       </row>
 472
 473       <row>
 474       <entry><literal>implicit_deps_unchanged</literal></entry>
 475       <entry><option>--implicit-deps-unchanged</option></entry>
 476       </row>
 477
 478       <row>
 479       <entry><literal>interactive</literal></entry>
 480       <entry><option>--interact</option>,
 481              <option>--interactive</option></entry>
 482       </row>
 483
 484       <row>
 485       <entry><literal>keep_going</literal></entry>
 486       <entry><option>-k</option>,
 487              <option>--keep-going</option></entry>
 488       </row>
 489
 490       <row>
 491       <entry><literal>max_drift</literal></entry>
 492       <entry><option>--max-drift</option></entry>
 493       </row>
 494
 495       <row>
 496       <entry><literal>no_exec</literal></entry>
 497       <entry><option>-n</option>,
 498              <option>--no-exec</option>,
 499              <option>--just-print</option>,
 500              <option>--dry-run</option>,
 501              <option>--recon</option></entry>
 502       </row>
 503
 504       <row>
 505       <entry><literal>no_site_dir</literal></entry>
 506       <entry><option>--no-site-dir</option></entry>
 507       </row>
 508
 509       <row>
 510       <entry><literal>num_jobs</literal></entry>
 511       <entry><option>-j</option>,
 512              <option>--jobs</option></entry>
 513       </row>
 514
 515       <row>
 516       <entry><literal>profile_file</literal></entry>
 517       <entry><option>--profile</option></entry>
 518       </row>
 519
 520       <row>
 521       <entry><literal>question</literal></entry>
 522       <entry><option>-q</option>,
 523              <option>--question</option></entry>
 524       </row>
 525
 526       <row>
 527       <entry><literal>random</literal></entry>
 528       <entry><option>--random</option></entry>
 529       </row>
 530
 531       <row>
 532       <entry><literal>repository</literal></entry>
 533       <entry><option>-Y</option>,
 534              <option>--repository</option>,
 535              <option>--srcdir</option></entry>
 536       </row>
 537
 538       <row>
 539       <entry><literal>silent</literal></entry>
 540       <entry><option>-s</option>,
 541              <option>--silent</option>,
 542              <option>--quiet</option></entry>
 543       </row>
 544
 545       <row>
 546       <entry><literal>site_dir</literal></entry>
 547       <entry><option>--site-dir</option></entry>
 548       </row>
 549
 550       <row>
 551       <entry><literal>stack_size</literal></entry>
 552       <entry><option>--stack-size</option></entry>
 553       </row>
 554
 555       <row>
 556       <entry><literal>taskmastertrace_file</literal></entry>
 557       <entry><option>--taskmastertrace</option></entry>
 558       </row>
 559
 560       <row>
 561       <entry><literal>warn</literal></entry>
 562       <entry><option>--warn</option> <option>--warning</option></entry>
 563       </row>
 564
 565       </tbody>
 566
 567       </tgroup>
 568       </informaltable>
 569
 570     </section>
 571
 572     <section>
 573     <title>Adding Custom Command-Line Options:  the &AddOption; Function</title>
 574
 575       <para>
 576
 577       &SCons; also allows you to define your own
 578       command-line options with the &AddOption; function.
 579       The &AddOption; function takes the same arguments
 580       as the <function>optparse.add_option</function> function
 581       from the standard Python library.
 582       <footnote>
 583       <para>
 584       The &AddOption; function is,
 585       in fact, implemented using a subclass
 586       of the <classname>optparse.OptionParser</classname>.
 587       </para>
 588       </footnote>
 589       Once you have added a custom command-line option
 590       with the &AddOption; function,
 591       the value of the option (if any) is immediately available
 592       using the standard &GetOption; function.
 593       (The value can also be set using &SetOption;,
 594       although that's not very useful in practice
 595       because a default value can be specified in
 596       directly in the &AddOption; call.)
 597
 598       </para>
 599
 600       <para>
 601
 602       One useful example of using this functionality
 603       is to provide a <option>--prefix</option> for users:
 604
 605       </para>
 606
 607       <scons_example name="AddOption">
 608         <file name="SConstruct" printme="1">
 609         AddOption('--prefix',
 610                   dest='prefix',
 611                   type='string',
 612                   nargs=1,
 613                   action='store',
 614                   metavar='DIR',
 615                   help='installation prefix')
 616
 617         env = Environment(PREFIX = GetOption('prefix'))
 618
 619         installed_foo = env.Install('$PREFIX/usr/bin', 'foo.in')
 620         Default(installed_foo)
 621         </file>
 622         <file name="foo.in">
 623         foo.in
 624         </file>
 625       </scons_example>
 626
 627       <para>
 628
 629       The above code uses the &GetOption; function
 630       to set the <varname>$PREFIX</varname>
 631       construction variable to any
 632       value that the user specifies with a command-line
 633       option of <literal>--prefix</literal>.
 634       Because <varname>$PREFIX</varname>
 635       will expand to a null string if it's not initialized,
 636       running &SCons; without the
 637       option of <literal>--prefix</literal>
 638       will install the file in the
 639       <filename>/usr/bin/</filename> directory:
 640
 641       </para>
 642
 643       <scons_output example="AddOption">
 644         <scons_output_command>scons -Q -n</scons_output_command>
 645       </scons_output>
 646
 647       <para>
 648
 649       But specifying <literal>--prefix=/tmp/install</literal>
 650       on the command line causes the file to be installed in the
 651       <filename>/tmp/install/usr/bin/</filename> directory:
 652
 653       </para>
 654
 655       <scons_output example="AddOption">
 656         <scons_output_command>scons -Q -n --prefix=/tmp/install</scons_output_command>
 657       </scons_output>
 658
 659     </section>
 660
 661   </section>
 662
 663   <section id="sect-command-line-variables">
 664   <title>Command-Line <varname>variable</varname>=<varname>value</varname> Build Variables</title>
 665
 666     <para>
 667
 668     You may want to control various aspects
 669     of your build by allowing the user
 670     to specify <varname>variable</varname>=<varname>value</varname>
 671     values on the command line.
 672     For example, suppose you
 673     want users to be able to
 674     build a debug version of a program
 675     by running &SCons; as follows:
 676
 677     </para>
 678
 679     <screen>
 680       % <userinput>scons -Q debug=1</userinput>
 681     </screen>
 682
 683     <para>
 684
 685     &SCons; provides an &ARGUMENTS; dictionary
 686     that stores all of the
 687     <varname>variable</varname>=<varname>value</varname>
 688     assignments from the command line.
 689     This allows you to modify
 690     aspects of your build in response
 691     to specifications on the command line.
 692     (Note that unless you want to require
 693     that users <emphasis>always</emphasis>
 694     specify a variable,
 695     you probably want to use
 696     the Python
 697     <literal>ARGUMENTS.get()</literal> function,
 698     which allows you to specify a default value
 699     to be used if there is no specification
 700     on the command line.)
 701
 702     </para>
 703
 704     <para>
 705
 706     The following code sets the &cv-link-CCFLAGS; construction
 707     variable in response to the <varname>debug</varname>
 708     flag being set in the &ARGUMENTS; dictionary:
 709
 710     </para>
 711
 712     <scons_example name="ARGUMENTS">
 713        <file name="SConstruct" printme="1">
 714        env = Environment()
 715        debug = ARGUMENTS.get('debug', 0)
 716        if int(debug):
 717            env.Append(CCFLAGS = '-g')
 718        env.Program('prog.c')
 719        </file>
 720        <file name="prog.c">
 721        prog.c
 722        </file>
 723     </scons_example>
 724
 725     <para>
 726
 727     This results in the <varname>-g</varname>
 728     compiler option being used when
 729     <literal>debug=1</literal>
 730     is used on the command line:
 731
 732     </para>
 733
 734     <scons_output example="ARGUMENTS">
 735        <scons_output_command>scons -Q debug=0</scons_output_command>
 736        <scons_output_command>scons -Q debug=0</scons_output_command>
 737        <scons_output_command>scons -Q debug=1</scons_output_command>
 738        <scons_output_command>scons -Q debug=1</scons_output_command>
 739     </scons_output>
 740
 741     <para>
 742
 743     Notice that &SCons; keeps track of
 744     the last values used to build the object files,
 745     and as a result correctly rebuilds
 746     the object and executable files
 747     only when the value of the <literal>debug</literal>
 748     argument has changed.
 749
 750     </para>
 751
 752     <para>
 753
 754     The &ARGUMENTS; dictionary has two minor drawbacks.
 755     First, because it is a dictionary,
 756     it can only store one value for each specified keyword,
 757     and thus only "remembers" the last setting
 758     for each keyword on the command line.
 759     This makes the &ARGUMENTS; dictionary
 760     inappropriate if users should be able to
 761     specify multiple values
 762     on the command line for a given keyword.
 763     Second, it does not preserve
 764     the order in which the variable settings
 765     were specified,
 766     which is a problem if
 767     you want the configuration to
 768     behave differently in response
 769     to the order in which the build
 770     variable settings were specified on the command line.
 771
 772     </para>
 773
 774     <para>
 775
 776     To accomodate these requirements,
 777     &SCons; provides an &ARGLIST; variable
 778     that gives you direct access to
 779     <varname>variable</varname>=<varname>value</varname>
 780     settings on the command line,
 781     in the exact order they were specified,
 782     and without removing any duplicate settings.
 783     Each element in the &ARGLIST; variable
 784     is itself a two-element list
 785     containing the keyword and the value
 786     of the setting,
 787     and you must loop through,
 788     or otherwise select from,
 789     the elements of &ARGLIST; to
 790     process the specific settings you want
 791     in whatever way is appropriate for your configuration.
 792     For example,
 793     the following code to let the user
 794     add to the &CPPDEFINES; construction variable
 795     by specifying multiple
 796     <varname>define=</varname>
 797     settings on the command line:
 798
 799     </para>
 800
 801     <scons_example name="ARGLIST">
 802        <file name="SConstruct" printme="1">
 803        cppdefines = []
 804        for key, value in ARGLIST:
 805            if key == 'define':
 806                cppdefines.append(value)
 807        env = Environment(CPPDEFINES = cppdefines)
 808        env.Object('prog.c')
 809        </file>
 810        <file name="prog.c">
 811        prog.c
 812        </file>
 813     </scons_example>
 814
 815     <para>
 816
 817     Yields the following output:
 818
 819     </para>
 820
 821     <scons_output example="ARGLIST">
 822        <scons_output_command>scons -Q define=FOO</scons_output_command>
 823        <scons_output_command>scons -Q define=FOO define=BAR</scons_output_command>
 824     </scons_output>
 825
 826     <para>
 827
 828     Note that the &ARGLIST; and &ARGUMENTS;
 829     variables do not interfere with each other,
 830     but merely provide slightly different views
 831     into how the user specified
 832     <varname>variable</varname>=<varname>value</varname>
 833     settings on the command line.
 834     You can use both variables in the same
 835     &SCons; configuration.
 836     In general, the &ARGUMENTS; dictionary
 837     is more convenient to use,
 838     (since you can just fetch variable
 839     settings through a dictionary access),
 840     and the &ARGLIST; list
 841     is more flexible
 842     (since you can examine the
 843     specific order in which
 844     the user's command-line variabe settings).
 845
 846     </para>
 847
 848     <section>
 849     <title>Controlling Command-Line Build Variables</title>
 850
 851       <para>
 852
 853       Being able to use a command-line build variable like
 854       <literal>debug=1</literal> is handy,
 855       but it can be a chore to write specific Python code
 856       to recognize each such variable,
 857       check for errors and provide appropriate messages,
 858       and apply the values to a construction variable.
 859       To help with this,
 860       &SCons; supports a class to
 861       define such build variables easily,
 862       and a mechanism to apply the
 863       build variables to a construction environment.
 864       This allows you to control how the build variables affect
 865       construction environments.
 866
 867       </para>
 868
 869       <para>
 870
 871       For example, suppose that you want users to set
 872       a &RELEASE; construction variable on the
 873       command line whenever the time comes to build
 874       a program for release,
 875       and that the value of this variable
 876       should be added to the command line
 877       with the appropriate <literal>-D</literal> option
 878       (or other command line option)
 879       to pass the value to the C compiler.
 880       Here's how you might do that by setting
 881       the appropriate value in a dictionary for the
 882       &cv-link-CPPDEFINES; construction variable:
 883
 884       </para>
 885
 886       <scons_example name="Variables1">
 887         <file name="SConstruct" printme="1">
 888            vars = Variables()
 889            vars.Add('RELEASE', 'Set to 1 to build for release', 0)
 890            env = Environment(variables = vars,
 891                              CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
 892            env.Program(['foo.c', 'bar.c'])
 893         </file>
 894         <file name="foo.c">
 895         foo.c
 896         </file>
 897         <file name="bar.c">
 898         bar.c
 899         </file>
 900       </scons_example>
 901
 902       <para>
 903
 904       This &SConstruct; file first creates a &Variables; object
 905       (the <literal>vars = Variables()</literal> call),
 906       and then uses the object's &Add;
 907       method to indicate that the &RELEASE;
 908       variable can be set on the command line,
 909       and that its default value will be <literal>0</literal>
 910       (the third argument to the &Add; method).
 911       The second argument is a line of help text;
 912       we'll learn how to use it in the next section.
 913
 914       </para>
 915
 916       <para>
 917
 918       We then pass the created &Variables;
 919       object as a &variables; keyword argument
 920       to the &Environment; call
 921       used to create the construction environment.
 922       This then allows a user to set the
 923       &RELEASE; build variable on the command line
 924       and have the variable show up in
 925       the command line used to build each object from
 926       a C source file:
 927
 928       </para>
 929
 930       <scons_output example="Variables1">
 931         <scons_output_command>scons -Q RELEASE=1</scons_output_command>
 932       </scons_output>
 933
 934       <para>
 935
 936       NOTE:  Before &SCons; release 0.98.1, these build variables
 937       were known as "command-line build options."
 938       The class was actually named the &Options; class,
 939       and in the sections below,
 940       the various functions were named
 941       &BoolOption;, &EnumOption;, &ListOption;,
 942       &PathOption;, &PackageOption; and &AddOptions;.
 943       These older names still work,
 944       and you may encounter them in older
 945       &SConscript; fles,
 946       but their use is discouraged
 947       and will be officially deprecated some day.
 948
 949       </para>
 950
 951     </section>
 952
 953     <section>
 954     <title>Providing Help for Command-Line Build Variables</title>
 955
 956       <para>
 957
 958       To make command-line build variables most useful,
 959       you ideally want to provide
 960       some help text that will describe
 961       the available variables
 962       when the user runs <literal>scons -h</literal>.
 963       You could write this text by hand,
 964       but &SCons; provides an easier way.
 965       &Variables; objects support a
 966       &GenerateHelpText; method
 967       that will, as its name suggests,
 968       generate text that describes
 969       the various variables that
 970       have been added to it.
 971       You then pass the output from this method to
 972       the &Help; function:
 973
 974       </para>
 975
 976       <scons_example name="Variables_Help">
 977         <file name="SConstruct" printme="1">
 978            vars = Variables('custom.py')
 979            vars.Add('RELEASE', 'Set to 1 to build for release', 0)
 980            env = Environment(variables = vars)
 981            Help(vars.GenerateHelpText(env))
 982         </file>
 983       </scons_example>
 984
 985       <para>
 986
 987       &SCons; will now display some useful text
 988       when the <literal>-h</literal> option is used:
 989
 990       </para>
 991
 992       <scons_output example="Variables_Help">
 993         <scons_output_command>scons -Q -h</scons_output_command>
 994       </scons_output>
 995
 996       <para>
 997
 998       Notice that the help output shows the default value,
 999       and the current actual value of the build variable.
1000
1001       </para>
1002
1003     </section>
1004
1005     <section>
1006     <title>Reading Build Variables From a File</title>
1007
1008       <para>
1009
1010       Giving the user a way to specify the
1011       value of a build variable on the command line
1012       is useful,
1013       but can still be tedious
1014       if users must specify the variable
1015       every time they run &SCons;.
1016       We can let users provide customized build variable settings
1017       in a local file by providing a
1018       file name when we create the
1019       &Variables; object:
1020
1021       </para>
1022
1023       <scons_example name="Variables_custom_py_1">
1024         <file name="SConstruct" printme="1">
1025            vars = Variables('custom.py')
1026            vars.Add('RELEASE', 'Set to 1 to build for release', 0)
1027            env = Environment(variables = vars,
1028                              CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
1029            env.Program(['foo.c', 'bar.c'])
1030            Help(vars.GenerateHelpText(env))
1031         </file>
1032         <file name="foo.c">
1033         foo.c
1034         </file>
1035         <file name="bar.c">
1036         bar.c
1037         </file>
1038         <file name="custom.py">
1039         RELEASE = 1
1040         </file>
1041       </scons_example>
1042
1043       <para>
1044
1045       This then allows the user to control the &RELEASE;
1046       variable by setting it in the &custom_py; file:
1047
1048       </para>
1049
1050       <scons_example_file example="Variables_custom_py_1" name="custom.py"></scons_example_file>
1051
1052       <para>
1053
1054       Note that this file is actually executed
1055       like a Python script.
1056       Now when we run &SCons;:
1057
1058       </para>
1059
1060       <scons_output example="Variables_custom_py_1">
1061         <scons_output_command>scons -Q</scons_output_command>
1062       </scons_output>
1063
1064       <para>
1065
1066       And if we change the contents of &custom_py; to:
1067
1068       </para>
1069
1070       <scons_example name="Variables_custom_py_2">
1071         <file name="SConstruct">
1072            vars = Variables('custom.py')
1073            vars.Add('RELEASE', 'Set to 1 to build for release', 0)
1074            env = Environment(variables = vars,
1075                              CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
1076            env.Program(['foo.c', 'bar.c'])
1077            Help(vars.GenerateHelpText(env))
1078         </file>
1079         <file name="foo.c">
1080         foo.c
1081         </file>
1082         <file name="bar.c">
1083         bar.c
1084         </file>
1085         <file name="custom.py" printme="1">
1086         RELEASE = 0
1087         </file>
1088       </scons_example>
1089
1090       <para>
1091
1092       The object files are rebuilt appropriately
1093       with the new variable:
1094
1095       </para>
1096
1097       <scons_output example="Variables_custom_py_2">
1098         <scons_output_command>scons -Q</scons_output_command>
1099       </scons_output>
1100
1101     </section>
1102
1103     <section>
1104     <title>Pre-Defined Build Variable Functions</title>
1105
1106       <para>
1107
1108       &SCons; provides a number of functions
1109       that provide ready-made behaviors
1110       for various types of command-line build variables.
1111
1112       </para>
1113
1114       <section>
1115       <title>True/False Values:  the &BoolVariable; Build Variable Function</title>
1116
1117         <para>
1118
1119         It's often handy to be able to specify a
1120         variable that controls a simple Boolean variable
1121         with a &true; or &false; value.
1122         It would be even more handy to accomodate
1123         users who have different preferences for how to represent
1124         &true; or &false; values.
1125         The &BoolVariable; function
1126         makes it easy to accomodate these
1127         common representations of
1128         &true; or &false;.
1129
1130         </para>
1131
1132         <para>
1133
1134         The &BoolVariable; function takes three arguments:
1135         the name of the build variable,
1136         the default value of the build variable,
1137         and the help string for the variable.
1138         It then returns appropriate information for
1139         passing to the &Add; method of a &Variables; object, like so:
1140
1141         </para>
1142
1143         <scons_example name="BoolVariable">
1144           <file name="SConstruct" printme="1">
1145              vars = Variables('custom.py')
1146              vars.Add(BoolVariable('RELEASE', 'Set to build for release', 0))
1147              env = Environment(variables = vars,
1148                                CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
1149              env.Program('foo.c')
1150           </file>
1151           <file name="foo.c">
1152           foo.c
1153           </file>
1154         </scons_example>
1155
1156         <para>
1157
1158         With this build variable,
1159         the &RELEASE; variable can now be enabled by
1160         setting it to the value <literal>yes</literal>
1161         or <literal>t</literal>:
1162
1163         </para>
1164
1165         <scons_output example="BoolVariable">
1166           <scons_output_command>scons -Q RELEASE=yes foo.o</scons_output_command>
1167         </scons_output>
1168
1169         <scons_output example="BoolVariable">
1170           <scons_output_command>scons -Q RELEASE=t foo.o</scons_output_command>
1171         </scons_output>
1172
1173         <para>
1174
1175         Other values that equate to &true; include
1176         <literal>y</literal>,
1177         <literal>1</literal>,
1178         <literal>on</literal>
1179         and
1180         <literal>all</literal>.
1181
1182         </para>
1183
1184         <para>
1185
1186         Conversely, &RELEASE; may now be given a &false;
1187         value by setting it to
1188         <literal>no</literal>
1189         or
1190         <literal>f</literal>:
1191
1192         </para>
1193
1194         <scons_output example="BoolVariable">
1195           <scons_output_command>scons -Q RELEASE=no foo.o</scons_output_command>
1196         </scons_output>
1197
1198         <scons_output example="BoolVariable">
1199           <scons_output_command>scons -Q RELEASE=f foo.o</scons_output_command>
1200         </scons_output>
1201
1202         <para>
1203
1204         Other values that equate to &false; include
1205         <literal>n</literal>,
1206         <literal>0</literal>,
1207         <literal>off</literal>
1208         and
1209         <literal>none</literal>.
1210
1211         </para>
1212
1213         <para>
1214
1215         Lastly, if a user tries to specify
1216         any other value,
1217         &SCons; supplies an appropriate error message:
1218
1219         </para>
1220
1221         <scons_output example="BoolVariable">
1222           <scons_output_command>scons -Q RELEASE=bad_value foo.o</scons_output_command>
1223         </scons_output>
1224
1225       </section>
1226
1227       <section>
1228       <title>Single Value From a List:  the &EnumVariable; Build Variable Function</title>
1229
1230         <para>
1231
1232         Suppose that we want a user to be able to
1233         set a &COLOR; variable
1234         that selects a background color to be
1235         displayed by an application,
1236         but that we want to restrict the
1237         choices to a specific set of allowed colors.
1238         This can be set up quite easily
1239         using the &EnumVariable;,
1240         which takes a list of &allowed_values;
1241         in addition to the variable name,
1242         default value,
1243         and help text arguments:
1244
1245         </para>
1246
1247         <scons_example name="EnumVariable">
1248           <file name="SConstruct" printme="1">
1249              vars = Variables('custom.py')
1250              vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
1251                                  allowed_values=('red', 'green', 'blue')))
1252              env = Environment(variables = vars,
1253                                CPPDEFINES={'COLOR' : '"${COLOR}"'})
1254              env.Program('foo.c')
1255           </file>
1256           <file name="foo.c">
1257           foo.c
1258           </file>
1259         </scons_example>
1260
1261         <para>
1262
1263         The user can now explicity set the &COLOR; build variable
1264         to any of the specified allowed values:
1265
1266         </para>
1267
1268         <scons_output example="EnumVariable">
1269           <scons_output_command>scons -Q COLOR=red foo.o</scons_output_command>
1270           <scons_output_command>scons -Q COLOR=blue foo.o</scons_output_command>
1271           <scons_output_command>scons -Q COLOR=green foo.o</scons_output_command>
1272         </scons_output>
1273
1274         <para>
1275
1276         But, almost more importantly,
1277         an attempt to set &COLOR;
1278         to a value that's not in the list
1279         generates an error message:
1280
1281         </para>
1282
1283         <scons_output example="EnumVariable">
1284           <scons_output_command>scons -Q COLOR=magenta foo.o</scons_output_command>
1285         </scons_output>
1286
1287         <para>
1288
1289         The &EnumVariable; function also supports a way
1290         to map alternate names to allowed values.
1291         Suppose, for example,
1292         that we want to allow the user
1293         to use the word <literal>navy</literal> as a synonym for
1294         <literal>blue</literal>.
1295         We do this by adding a &map; dictionary
1296         that will map its key values
1297         to the desired legal value:
1298
1299         </para>
1300
1301         <scons_example name="EnumVariable_map">
1302           <file name="SConstruct" printme="1">
1303              vars = Variables('custom.py')
1304              vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
1305                                  allowed_values=('red', 'green', 'blue'),
1306                                  map={'navy':'blue'}))
1307              env = Environment(variables = vars,
1308                                CPPDEFINES={'COLOR' : '"${COLOR}"'})
1309              env.Program('foo.c')
1310           </file>
1311           <file name="foo.c">
1312           foo.c
1313           </file>
1314         </scons_example>
1315
1316         <para>
1317
1318         As desired, the user can then use
1319         <literal>navy</literal> on the command line,
1320         and &SCons; will translate it into <literal>blue</literal>
1321         when it comes time to use the &COLOR;
1322         variable to build a target:
1323
1324         </para>
1325
1326         <scons_output example="EnumVariable_map">
1327           <scons_output_command>scons -Q COLOR=navy foo.o</scons_output_command>
1328         </scons_output>
1329
1330         <para>
1331
1332         By default, when using the &EnumVariable; function,
1333         arguments that differ
1334         from the legal values
1335         only in case
1336         are treated as illegal values:
1337
1338         </para>
1339
1340         <scons_output example="EnumVariable">
1341           <scons_output_command>scons -Q COLOR=Red foo.o</scons_output_command>
1342           <scons_output_command>scons -Q COLOR=BLUE foo.o</scons_output_command>
1343           <scons_output_command>scons -Q COLOR=nAvY foo.o</scons_output_command>
1344         </scons_output>
1345
1346         <para>
1347
1348         The &EnumVariable; function can take an additional
1349         &ignorecase; keyword argument that,
1350         when set to <literal>1</literal>,
1351         tells &SCons; to allow case differences
1352         when the values are specified:
1353
1354         </para>
1355
1356         <scons_example name="EnumVariable_ic1">
1357           <file name="SConstruct" printme="1">
1358              vars = Variables('custom.py')
1359              vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
1360                                  allowed_values=('red', 'green', 'blue'),
1361                                  map={'navy':'blue'},
1362                                  ignorecase=1))
1363              env = Environment(variables = vars,
1364                                CPPDEFINES={'COLOR' : '"${COLOR}"'})
1365              env.Program('foo.c')
1366           </file>
1367           <file name="foo.c">
1368           foo.c
1369           </file>
1370         </scons_example>
1371
1372         <para>
1373
1374         Which yields the output:
1375
1376         </para>
1377
1378         <scons_output example="EnumVariable_ic1">
1379           <scons_output_command>scons -Q COLOR=Red foo.o</scons_output_command>
1380           <scons_output_command>scons -Q COLOR=BLUE foo.o</scons_output_command>
1381           <scons_output_command>scons -Q COLOR=nAvY foo.o</scons_output_command>
1382           <scons_output_command>scons -Q COLOR=green foo.o</scons_output_command>
1383         </scons_output>
1384
1385         <para>
1386
1387         Notice that an &ignorecase; value of <literal>1</literal>
1388         preserves the case-spelling that the user supplied.
1389         If you want &SCons; to translate the names
1390         into lower-case,
1391         regardless of the case used by the user,
1392         specify an &ignorecase; value of <literal>2</literal>:
1393
1394         </para>
1395
1396         <scons_example name="EnumVariable_ic2">
1397           <file name="SConstruct" printme="1">
1398              vars = Variables('custom.py')
1399              vars.Add(EnumVariable('COLOR', 'Set background color', 'red',
1400                                  allowed_values=('red', 'green', 'blue'),
1401                                  map={'navy':'blue'},
1402                                  ignorecase=2))
1403              env = Environment(variables = vars,
1404                                CPPDEFINES={'COLOR' : '"${COLOR}"'})
1405              env.Program('foo.c')
1406           </file>
1407           <file name="foo.c">
1408           foo.c
1409           </file>
1410         </scons_example>
1411
1412         <para>
1413
1414         Now &SCons; will use values of
1415         <literal>red</literal>,
1416         <literal>green</literal> or
1417         <literal>blue</literal>
1418         regardless of how the user spells
1419         those values on the command line:
1420
1421         </para>
1422
1423         <scons_output example="EnumVariable_ic2">
1424           <scons_output_command>scons -Q COLOR=Red foo.o</scons_output_command>
1425           <scons_output_command>scons -Q COLOR=nAvY foo.o</scons_output_command>
1426           <scons_output_command>scons -Q COLOR=GREEN foo.o</scons_output_command>
1427         </scons_output>
1428
1429       </section>
1430
1431       <section>
1432       <title>Multiple Values From a List:  the &ListVariable; Build Variable Function</title>
1433
1434         <para>
1435
1436         Another way in which you might want to allow users
1437         to control a build variable is to
1438         specify a list of one or more legal values.
1439         &SCons; supports this through the &ListVariable; function.
1440         If, for example, we want a user to be able to set a
1441         &COLORS; variable to one or more of the legal list of values:
1442
1443         </para>
1444
1445         <scons_example name="ListVariable">
1446           <file name="SConstruct" printme="1">
1447              vars = Variables('custom.py')
1448              vars.Add(ListVariable('COLORS', 'List of colors', 0,
1449                                  ['red', 'green', 'blue']))
1450              env = Environment(variables = vars,
1451                                CPPDEFINES={'COLORS' : '"${COLORS}"'})
1452              env.Program('foo.c')
1453           </file>
1454           <file name="foo.c">
1455           foo.c
1456           </file>
1457         </scons_example>
1458
1459         <para>
1460
1461         A user can now specify a comma-separated list
1462         of legal values,
1463         which will get translated into a space-separated
1464         list for passing to the any build commands:
1465
1466         </para>
1467
1468         <scons_output example="ListVariable">
1469           <scons_output_command>scons -Q COLORS=red,blue foo.o</scons_output_command>
1470           <scons_output_command>scons -Q COLORS=blue,green,red foo.o</scons_output_command>
1471         </scons_output>
1472
1473         <para>
1474
1475         In addition, the &ListVariable; function
1476         allows the user to specify explicit keywords of
1477         &all; or &none;
1478         to select all of the legal values,
1479         or none of them, respectively:
1480
1481         </para>
1482
1483         <scons_output example="ListVariable">
1484           <scons_output_command>scons -Q COLORS=all foo.o</scons_output_command>
1485           <scons_output_command>scons -Q COLORS=none foo.o</scons_output_command>
1486         </scons_output>
1487
1488         <para>
1489
1490         And, of course, an illegal value
1491         still generates an error message:
1492
1493         </para>
1494
1495         <scons_output example="ListVariable">
1496           <scons_output_command>scons -Q COLORS=magenta foo.o</scons_output_command>
1497         </scons_output>
1498
1499       </section>
1500
1501       <section>
1502       <title>Path Names:  the &PathVariable; Build Variable Function</title>
1503
1504         <para>
1505
1506         &SCons; supports a &PathVariable; function
1507         to make it easy to create a build variable
1508         to control an expected path name.
1509         If, for example, you need to
1510         define a variable in the preprocessor
1511         that controls the location of a
1512         configuration file:
1513
1514         </para>
1515
1516         <scons_example name="PathVariable">
1517           <file name="SConstruct" printme="1">
1518              vars = Variables('custom.py')
1519              vars.Add(PathVariable('CONFIG',
1520                                  'Path to configuration file',
1521                                  '__ROOT__/etc/my_config'))
1522              env = Environment(variables = vars,
1523                                CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'})
1524              env.Program('foo.c')
1525           </file>
1526           <file name="foo.c">
1527           foo.c
1528           </file>
1529           <file name="__ROOT__/etc/my_config">
1530           /opt/location
1531           </file>
1532           <file name="__ROOT__/usr/local/etc/other_config">
1533           /opt/location
1534           </file>
1535         </scons_example>
1536
1537         <para>
1538
1539         This then allows the user to
1540         override the &CONFIG; build variable
1541         on the command line as necessary:
1542
1543         </para>
1544
1545         <scons_output example="PathVariable">
1546           <scons_output_command>scons -Q foo.o</scons_output_command>
1547           <scons_output_command>scons -Q CONFIG=__ROOT__/usr/local/etc/other_config foo.o</scons_output_command>
1548         </scons_output>
1549
1550         <para>
1551
1552         By default, &PathVariable; checks to make sure
1553         that the specified path exists and generates an error if it
1554         doesn't:
1555
1556         </para>
1557
1558         <scons_output example="PathVariable">
1559           <scons_output_command>scons -Q CONFIG=__ROOT__/does/not/exist foo.o</scons_output_command>
1560         </scons_output>
1561
1562         <para>
1563
1564         &PathVariable; provides a number of methods
1565         that you can use to change this behavior.
1566         If you want to ensure that any specified paths are,
1567         in fact, files and not directories,
1568         use the &PathVariable_PathIsFile; method:
1569
1570         </para>
1571
1572         <scons_example name="PathIsFile">
1573           <file name="SConstruct" printme="1">
1574              vars = Variables('custom.py')
1575              vars.Add(PathVariable('CONFIG',
1576                                  'Path to configuration file',
1577                                  '__ROOT__/etc/my_config',
1578                                  PathVariable.PathIsFile))
1579              env = Environment(variables = vars,
1580                                CPPDEFINES={'CONFIG_FILE' : '"$CONFIG"'})
1581              env.Program('foo.c')
1582           </file>
1583           <file name="foo.c">
1584           foo.c
1585           </file>
1586           <file name="__ROOT__/etc/my_config">
1587           /opt/location
1588           </file>
1589         </scons_example>
1590
1591         <para>
1592
1593         Conversely, to ensure that any specified paths are
1594         directories and not files,
1595         use the &PathVariable_PathIsDir; method:
1596
1597         </para>
1598
1599         <scons_example name="PathIsDir">
1600           <file name="SConstruct" printme="1">
1601              vars = Variables('custom.py')
1602              vars.Add(PathVariable('DBDIR',
1603                                  'Path to database directory',
1604                                  '__ROOT__/var/my_dbdir',
1605                                  PathVariable.PathIsDir))
1606              env = Environment(variables = vars,
1607                                CPPDEFINES={'DBDIR' : '"$DBDIR"'})
1608              env.Program('foo.c')
1609           </file>
1610           <file name="foo.c">
1611           foo.c
1612           </file>
1613           <file name="__ROOT__/var/my_dbdir">
1614           /opt/location
1615           </file>
1616         </scons_example>
1617
1618         <para>
1619
1620         If you want to make sure that any specified paths
1621         are directories,
1622         and you would like the directory created
1623         if it doesn't already exist,
1624         use the &PathVariable_PathIsDirCreate; method:
1625
1626         </para>
1627
1628         <scons_example name="PathIsDirCreate">
1629           <file name="SConstruct" printme="1">
1630              vars = Variables('custom.py')
1631              vars.Add(PathVariable('DBDIR',
1632                                  'Path to database directory',
1633                                  '__ROOT__/var/my_dbdir',
1634                                  PathVariable.PathIsDirCreate))
1635              env = Environment(variables = vars,
1636                                CPPDEFINES={'DBDIR' : '"$DBDIR"'})
1637              env.Program('foo.c')
1638           </file>
1639           <file name="foo.c">
1640           foo.c
1641           </file>
1642           <file name="__ROOT__/var/my_dbdir">
1643           /opt/location
1644           </file>
1645         </scons_example>
1646
1647         <para>
1648
1649         Lastly, if you don't care whether the path exists,
1650         is a file, or a directory,
1651         use the &PathVariable_PathAccept; method
1652         to accept any path that the user supplies:
1653
1654         </para>
1655
1656         <scons_example name="PathAccept">
1657           <file name="SConstruct" printme="1">
1658              vars = Variables('custom.py')
1659              vars.Add(PathVariable('OUTPUT',
1660                                  'Path to output file or directory',
1661                                  None,
1662                                  PathVariable.PathAccept))
1663              env = Environment(variables = vars,
1664                                CPPDEFINES={'OUTPUT' : '"$OUTPUT"'})
1665              env.Program('foo.c')
1666           </file>
1667           <file name="foo.c">
1668           foo.c
1669           </file>
1670         </scons_example>
1671
1672       </section>
1673
1674       <section>
1675       <title>Enabled/Disabled Path Names: the &PackageVariable; Build Variable Function</title>
1676
1677         <para>
1678
1679         Sometimes you want to give users
1680         even more control over a path name variable,
1681         allowing them to explicitly enable or
1682         disable the path name
1683         by using <literal>yes</literal> or <literal>no</literal> keywords,
1684         in addition to allow them
1685         to supply an explicit path name.
1686         &SCons; supports the &PackageVariable;
1687         function to support this:
1688
1689         </para>
1690
1691         <scons_example name="PackageVariable">
1692           <file name="SConstruct" printme="1">
1693              vars = Variables('custom.py')
1694              vars.Add(PackageVariable('PACKAGE',
1695                                     'Location package',
1696                                     '__ROOT__/opt/location'))
1697              env = Environment(variables = vars,
1698                                CPPDEFINES={'PACKAGE' : '"$PACKAGE"'})
1699              env.Program('foo.c')
1700           </file>
1701           <file name="foo.c">
1702           foo.c
1703           </file>
1704           <file name="__ROOT__/opt/location">
1705           /opt/location
1706           </file>
1707           <file name="__ROOT__/usr/local/location">
1708           /opt/location
1709           </file>
1710         </scons_example>
1711
1712         <para>
1713
1714         When the &SConscript; file uses the &PackageVariable; funciton,
1715         user can now still use the default
1716         or supply an overriding path name,
1717         but can now explicitly set the
1718         specified variable to a value
1719         that indicates the package should be enabled
1720         (in which case the default should be used)
1721         or disabled:
1722
1723         </para>
1724
1725         <scons_output example="PackageVariable">
1726           <scons_output_command>scons -Q foo.o</scons_output_command>
1727           <scons_output_command>scons -Q PACKAGE=__ROOT__/usr/local/location foo.o</scons_output_command>
1728           <scons_output_command>scons -Q PACKAGE=yes foo.o</scons_output_command>
1729           <scons_output_command>scons -Q PACKAGE=no foo.o</scons_output_command>
1730         </scons_output>
1731
1732       </section>
1733
1734     </section>
1735
1736     <section>
1737     <title>Adding Multiple Command-Line Build Variables at Once</title>
1738
1739       <para>
1740
1741       Lastly, &SCons; provides a way to add
1742       multiple build variables to a &Variables; object at once.
1743       Instead of having to call the &Add; method
1744       multiple times,
1745       you can call the &AddVariables;
1746       method with a list of build variables
1747       to be added to the object.
1748       Each build variable is specified
1749       as either a tuple of arguments,
1750       just like you'd pass to the &Add; method itself,
1751       or as a call to one of the pre-defined
1752       functions for pre-packaged command-line build variables.
1753       in any order:
1754
1755       </para>
1756
1757       <scons_example name="AddVariables_1">
1758         <file name="SConstruct" printme="1">
1759           vars = Variables()
1760           vars.AddVariables(
1761               ('RELEASE', 'Set to 1 to build for release', 0),
1762               ('CONFIG', 'Configuration file', '/etc/my_config'),
1763               BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
1764               EnumVariable('debug', 'debug output and symbols', 'no',
1765                          allowed_values=('yes', 'no', 'full'),
1766                          map={}, ignorecase=0),  # case sensitive
1767               ListVariable('shared',
1768                          'libraries to build as shared libraries',
1769                          'all',
1770                          names = list_of_libs),
1771               PackageVariable('x11',
1772                             'use X11 installed here (yes = search some places)',
1773                             'yes'),
1774               PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
1775           )
1776         </file>
1777       </scons_example>
1778
1779       <para>
1780       </para>
1781
1782     </section>
1783
1784     <section>
1785     <title>Handling Unknown Command-Line Build Variables:  the &UnknownVariables; Function</title>
1786
1787       <para>
1788
1789       Users may, of course,
1790       occasionally misspell variable names in their command-line settings.
1791       &SCons; does not generate an error or warning
1792       for any unknown variables the users specifies on the command line.
1793       (This is in no small part because you may be
1794       processing the arguments directly using the &ARGUMENTS; dictionary,
1795       and therefore &SCons; can't know in the general case
1796       whether a given "misspelled" variable is
1797       really unknown and a potential problem,
1798       or something that your &SConscript; file
1799       will handle directly with some Python code.)
1800
1801       </para>
1802
1803       <para>
1804
1805       If, however, you're using a &Variables; object to
1806       define a specific set of command-line build variables
1807       that you expect users to be able to set,
1808       you may want to provide an error
1809       message or warning of your own
1810       if the user supplies a variable setting
1811       that is <emphasis>not</emphasis> among
1812       the defined list of variable names known to the &Variables; object.
1813       You can do this by calling the &UnknownVariables;
1814       method of the &Variables; object:
1815
1816       </para>
1817
1818       <scons_example name="UnknownVariables">
1819         <file name="SConstruct" printme="1">
1820            vars = Variables(None)
1821            vars.Add('RELEASE', 'Set to 1 to build for release', 0)
1822            env = Environment(variables = vars,
1823                              CPPDEFINES={'RELEASE_BUILD' : '${RELEASE}'})
1824            unknown = vars.UnknownVariables()
1825            if unknown:
1826                print "Unknown variables:", unknown.keys()
1827                Exit(1)
1828            env.Program('foo.c')
1829         </file>
1830         <file name="foo.c">
1831         foo.c
1832         </file>
1833       </scons_example>
1834
1835       <para>
1836
1837       The &UnknownVariables; method returns a dictionary
1838       containing the keywords and values
1839       of any variables the user specified on the command line
1840       that are <emphasis>not</emphasis>
1841       among the variables known to the &Variables; object
1842       (from having been specified using
1843       the &Variables; object's&Add; method).
1844       In the examble above,
1845       we check for whether the dictionary
1846       returned by the &UnknownVariables; is non-empty,
1847       and if so print the Python list
1848       containing the names of the unknwown variables
1849       and then call the &Exit; function
1850       to terminate &SCons;:
1851
1852       </para>
1853
1854       <scons_output example="UnknownVariables">
1855         <scons_output_command>scons -Q NOT_KNOWN=foo</scons_output_command>
1856       </scons_output>
1857
1858       <para>
1859
1860       Of course, you can process the items in the
1861       dictionary returned by the &UnknownVariables; function
1862       in any way appropriate to your build configuration,
1863       including just printing a warning message
1864       but not exiting,
1865       logging an error somewhere,
1866       etc.
1867
1868       </para>
1869
1870       <para>
1871
1872       Note that you must delay the call of &UnknownVariables;
1873       until after you have applied the &Variables; object
1874       to a construction environment
1875       with the <literal>variables=</literal>
1876       keyword argument of an &Environment; call.
1877
1878       </para>
1879
1880     </section>
1881
1882   </section>
1883
1884   <section id="sect-command-line-targets">
1885   <title>Command-Line Targets</title>
1886
1887     <section>
1888     <title>Fetching Command-Line Targets: the &COMMAND_LINE_TARGETS; Variable</title>
1889
1890       <para>
1891
1892       &SCons; supports a &COMMAND_LINE_TARGETS; variable
1893       that lets you fetch the list of targets that the
1894       user specified on the command line.
1895       You can use the targets to manipulate the
1896       build in any way you wish.
1897       As a simple example,
1898       suppose that you want to print a reminder
1899       to the user whenever a specific program is built.
1900       You can do this by checking for the
1901       target in the &COMMAND_LINE_TARGETS; list:
1902
1903       </para>
1904
1905       <scons_example name="COMMAND_LINE_TARGETS">
1906         <file name="SConstruct" printme="1">
1907         if 'bar' in COMMAND_LINE_TARGETS:
1908             print "Don't forget to copy `bar' to the archive!"
1909         Default(Program('foo.c'))
1910         Program('bar.c')
1911         </file>
1912         <file name="foo.c">
1913         foo.c
1914         </file>
1915         <file name="bar.c">
1916         foo.c
1917         </file>
1918       </scons_example>
1919
1920       <para>
1921
1922       Then, running &SCons; with the default target
1923       works as it always does,
1924       but explicity specifying the &bar; target
1925       on the command line generates the warning message:
1926
1927       </para>
1928
1929       <scons_output example="COMMAND_LINE_TARGETS">
1930         <scons_output_command>scons -Q</scons_output_command>
1931         <scons_output_command>scons -Q bar</scons_output_command>
1932       </scons_output>
1933
1934       <para>
1935
1936       Another practical use for the &COMMAND_LINE_TARGETS; variable
1937       might be to speed up a build
1938       by only reading certain subsidiary &SConscript;
1939       files if a specific target is requested.
1940
1941       </para>
1942
1943     </section>
1944
1945     <section>
1946     <title>Controlling the Default Targets:  the &Default; Function</title>
1947
1948       <para>
1949
1950       One of the most basic things you can control
1951       is which targets &SCons; will build by default--that is,
1952       when there are no targets specified on the command line.
1953       As mentioned previously,
1954       &SCons; will normally build every target
1955       in or below the current directory
1956       by default--that is, when you don't
1957       explicitly specify one or more targets
1958       on the command line.
1959       Sometimes, however, you may want
1960       to specify explicitly that only
1961       certain programs, or programs in certain directories,
1962       should be built by default.
1963       You do this with the &Default; function:
1964
1965       </para>
1966
1967       <scons_example name="Default1">
1968          <file name="SConstruct" printme="1">
1969          env = Environment()
1970          hello = env.Program('hello.c')
1971          env.Program('goodbye.c')
1972          Default(hello)
1973          </file>
1974          <file name="hello.c">
1975          hello.c
1976          </file>
1977          <file name="goodbye.c">
1978          goodbye.c
1979          </file>
1980       </scons_example>
1981
1982       <para>
1983
1984       This &SConstruct; file knows how to build two programs,
1985       &hello; and &goodbye;,
1986       but only builds the
1987       &hello; program by default:
1988
1989       </para>
1990
1991       <scons_output example="Default1">
1992          <scons_output_command>scons -Q</scons_output_command>
1993          <scons_output_command>scons -Q</scons_output_command>
1994          <scons_output_command>scons -Q goodbye</scons_output_command>
1995       </scons_output>
1996
1997       <para>
1998
1999       Note that, even when you use the &Default;
2000       function in your &SConstruct; file,
2001       you can still explicitly specify the current directory
2002       (<literal>.</literal>) on the command line
2003       to tell &SCons; to build
2004       everything in (or below) the current directory:
2005
2006       </para>
2007
2008       <scons_output example="Default1">
2009          <scons_output_command>scons -Q .</scons_output_command>
2010       </scons_output>
2011
2012       <para>
2013
2014       You can also call the &Default;
2015       function more than once,
2016       in which case each call
2017       adds to the list of targets to be built by default:
2018
2019       </para>
2020
2021       <scons_example name="Default2">
2022          <file name="SConstruct" printme="1">
2023          env = Environment()
2024          prog1 = env.Program('prog1.c')
2025          Default(prog1)
2026          prog2 = env.Program('prog2.c')
2027          prog3 = env.Program('prog3.c')
2028          Default(prog3)
2029          </file>
2030          <file name="prog1.c">
2031          prog1.c
2032          </file>
2033          <file name="prog2.c">
2034          prog2.c
2035          </file>
2036          <file name="prog3.c">
2037          prog3.c
2038          </file>
2039       </scons_example>
2040
2041       <para>
2042
2043       Or you can specify more than one target
2044       in a single call to the &Default; function:
2045
2046       </para>
2047
2048       <programlisting>
2049          env = Environment()
2050          prog1 = env.Program('prog1.c')
2051          prog2 = env.Program('prog2.c')
2052          prog3 = env.Program('prog3.c')
2053          Default(prog1, prog3)
2054       </programlisting>
2055
2056       <para>
2057
2058       Either of these last two examples
2059       will build only the
2060       <application>prog1</application>
2061       and
2062       <application>prog3</application>
2063       programs by default:
2064
2065       </para>
2066
2067       <scons_output example="Default2">
2068          <scons_output_command>scons -Q</scons_output_command>
2069          <scons_output_command>scons -Q .</scons_output_command>
2070       </scons_output>
2071
2072       <para>
2073
2074       You can list a directory as
2075       an argument to &Default;:
2076
2077       </para>
2078
2079       <scons_example name="Default3">
2080          <file name="SConstruct" printme="1">
2081          env = Environment()
2082          env.Program(['prog1/main.c', 'prog1/foo.c'])
2083          env.Program(['prog2/main.c', 'prog2/bar.c'])
2084          Default('prog1')
2085          </file>
2086          <directory name="prog1"></directory>
2087          <directory name="prog2"></directory>
2088          <file name="prog1/main.c">
2089          int main() { printf("prog1/main.c\n"); }
2090          </file>
2091          <file name="prog1/foo.c">
2092          int foo() { printf("prog1/foo.c\n"); }
2093          </file>
2094          <file name="prog2/main.c">
2095          int main() { printf("prog2/main.c\n"); }
2096          </file>
2097          <file name="prog2/bar.c">
2098          int bar() { printf("prog2/bar.c\n"); }
2099          </file>
2100       </scons_example>
2101
2102       <para>
2103
2104       In which case only the target(s) in that
2105       directory will be built by default:
2106
2107       </para>
2108
2109       <scons_output example="Default3">
2110          <scons_output_command>scons -Q</scons_output_command>
2111          <scons_output_command>scons -Q</scons_output_command>
2112          <scons_output_command>scons -Q .</scons_output_command>
2113       </scons_output>
2114
2115       <para>
2116
2117       Lastly, if for some reason you don't want
2118       any targets built by default,
2119       you can use the Python <literal>None</literal>
2120       variable:
2121
2122       </para>
2123
2124       <scons_example name="Default4">
2125          <file name="SConstruct" printme="1">
2126          env = Environment()
2127          prog1 = env.Program('prog1.c')
2128          prog2 = env.Program('prog2.c')
2129          Default(None)
2130          </file>
2131          <file name="prog1.c">
2132          prog1.c
2133          </file>
2134          <file name="prog2.c">
2135          prog2.c
2136          </file>
2137       </scons_example>
2138
2139       <para>
2140
2141       Which would produce build output like:
2142
2143       </para>
2144
2145       <scons_output example="Default4">
2146          <scons_output_command>scons -Q</scons_output_command>
2147          <scons_output_command>scons -Q .</scons_output_command>
2148       </scons_output>
2149
2150       <section>
2151       <title>Fetching the List of Default Targets: the &DEFAULT_TARGETS; Variable</title>
2152
2153         <para>
2154
2155         &SCons; supports a &DEFAULT_TARGETS; variable
2156         that lets you get at the current list of default targets.
2157         The &DEFAULT_TARGETS; variable has
2158         two important differences from the &COMMAND_LINE_TARGETS; variable.
2159         First, the &DEFAULT_TARGETS; variable is a list of
2160         internal &SCons; nodes,
2161         so you need to convert the list elements to strings
2162         if you want to print them or look for a specific target name.
2163         Fortunately, you can do this easily
2164         by using the Python <function>map</function> function
2165         to run the list through <function>str</function>:
2166
2167         </para>
2168
2169         <scons_example name="DEFAULT_TARGETS_1">
2170            <file name="SConstruct" printme="1">
2171            prog1 = Program('prog1.c')
2172            Default(prog1)
2173            print "DEFAULT_TARGETS is", map(str, DEFAULT_TARGETS)
2174            </file>
2175            <file name="prog1.c">
2176            prog1.c
2177            </file>
2178         </scons_example>
2179
2180         <para>
2181
2182         (Keep in mind that all of the manipulation of the
2183         &DEFAULT_TARGETS; list takes place during the
2184         first phase when &SCons; is reading up the &SConscript; files,
2185         which is obvious if
2186         we leave off the <literal>-Q</literal> flag when we run &SCons;:)
2187
2188         </para>
2189
2190         <scons_output example="DEFAULT_TARGETS_1">
2191            <scons_output_command>scons</scons_output_command>
2192         </scons_output>
2193
2194         <para>
2195
2196         Second,
2197         the contents of the &DEFAULT_TARGETS; list change
2198         in response to calls to the &Default: function,
2199         as you can see from the following &SConstruct; file:
2200
2201         </para>
2202
2203         <scons_example name="DEFAULT_TARGETS_2">
2204            <file name="SConstruct" printme="1">
2205            prog1 = Program('prog1.c')
2206            Default(prog1)
2207            print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)
2208            prog2 = Program('prog2.c')
2209            Default(prog2)
2210            print "DEFAULT_TARGETS is now", map(str, DEFAULT_TARGETS)
2211            </file>
2212            <file name="prog1.c">
2213            prog1.c
2214            </file>
2215            <file name="prog2.c">
2216            prog2.c
2217            </file>
2218         </scons_example>
2219
2220         <para>
2221
2222         Which yields the output:
2223
2224         </para>
2225
2226         <scons_output example="DEFAULT_TARGETS_2">
2227            <scons_output_command>scons</scons_output_command>
2228         </scons_output>
2229
2230         <para>
2231
2232         In practice, this simply means that you
2233         need to pay attention to the order in
2234         which you call the &Default; function
2235         and refer to the &DEFAULT_TARGETS; list,
2236         to make sure that you don't examine the
2237         list before you've added the default targets
2238         you expect to find in it.
2239
2240         </para>
2241
2242       </section>
2243
2244     </section>
2245
2246     <section>
2247     <title>Fetching the List of Build Targets, Regardless of Origin: the &BUILD_TARGETS; Variable</title>
2248
2249       <para>
2250
2251       We've already been introduced to the
2252       &COMMAND_LINE_TARGETS; variable,
2253       which contains a list of targets specified on the command line,
2254       and the &DEFAULT_TARGETS; variable,
2255       which contains a list of targets specified
2256       via calls to the &Default; method or function.
2257       Sometimes, however,
2258       you want a list of whatever targets
2259       &SCons; will try to build,
2260       regardless of whether the targets came from the
2261       command line or a &Default; call.
2262       You could code this up by hand, as follows:
2263
2264       </para>
2265
2266       <sconstruct>
2267         if COMMAND_LINE_TARGETS:
2268             targets = COMMAND_LINE_TARGETS
2269         else:
2270             targets = DEFAULT_TARGETS
2271       </sconstruct>
2272
2273       <para>
2274
2275       &SCons;, however, provides a convenient
2276       &BUILD_TARGETS; variable
2277       that eliminates the need for this by-hand manipulation.
2278       Essentially, the &BUILD_TARGETS; variable
2279       contains a list of the command-line targets,
2280       if any were specified,
2281       and if no command-line targets were specified,
2282       it contains a list of the targets specified
2283       via the &Default; method or function.
2284
2285       </para>
2286
2287       <para>
2288
2289       Because &BUILD_TARGETS; may contain a list of &SCons; nodes,
2290       you must convert the list elements to strings
2291       if you want to print them or look for a specific target name,
2292       just like the &DEFAULT_TARGETS; list:
2293
2294       </para>
2295
2296       <scons_example name="BUILD_TARGETS_1">
2297         <file name="SConstruct" printme="1">
2298         prog1 = Program('prog1.c')
2299         Program('prog2.c')
2300         Default(prog1)
2301         print "BUILD_TARGETS is", map(str, BUILD_TARGETS)
2302         </file>
2303         <file name="prog1.c">
2304         prog1.c
2305         </file>
2306         <file name="prog2.c">
2307         prog2.c
2308         </file>
2309       </scons_example>
2310
2311       <para>
2312
2313       Notice how the value of &BUILD_TARGETS;
2314       changes depending on whether a target is
2315       specified on the command line:
2316
2317       </para>
2318
2319       <scons_output example="BUILD_TARGETS_1">
2320         <scons_output_command>scons -Q</scons_output_command>
2321         <scons_output_command>scons -Q prog2</scons_output_command>
2322         <scons_output_command>scons -Q -c .</scons_output_command>
2323       </scons_output>
2324
2325     </section>
2326
2327   </section>