SCONS(1)                                                              SCONS(1)



NNAAMMEE
       scons - a software construction tool

SSYYNNOOPPSSIISS
       ssccoonnss [ _o_p_t_i_o_n_s...  ] [ _n_a_m_e=_v_a_l...  ] [ _t_a_r_g_e_t_s...  ]

DDEESSCCRRIIPPTTIIOONN
       The ssccoonnss utility builds software (or other files) by determining which
       component pieces must be rebuilt and executing the  necessary  commands
       to rebuild them.

       By  default, ssccoonnss searches for a file named _S_C_o_n_s_t_r_u_c_t, _S_c_o_n_s_t_r_u_c_t, or
       _s_c_o_n_s_t_r_u_c_t (in that order) in the current directory and reads its  con-
       figuration  from  the  first file found.  An alternate file name may be
       specified via the --ff option.

       The _S_C_o_n_s_t_r_u_c_t file can specify subsidiary  configuration  files  using
       the  SSCCoonnssccrriipptt(())  function.  By convention, these subsidiary files are
       named _S_C_o_n_s_c_r_i_p_t, although any name may be used.  (Because of this nam-
       ing  convention, the term "SConscript files" is sometimes used to refer
       generically to all ssccoonnss configuration files, regardless of actual file
       name.)

       The  configuration  files  specify  the  target  files to be built, and
       (optionally) the rules to  build  those  targets.   Reasonable  default
       rules  exist  for  building common software components (executable pro-
       grams, object files, libraries), so that for  most  software  projects,
       only the target and input files need be specified.

       Before  reading  the  _S_C_o_n_s_t_r_u_c_t file, ssccoonnss adds looks for a dir named
       _s_i_t_e___s_c_o_n_s in the dir containing the  _S_C_o_n_s_t_r_u_c_t  file;  it  adds  that
       _s_i_t_e___s_c_o_n_s  to  sys.path,  reads  the file _s_i_t_e___s_c_o_n_s_/_s_i_t_e___i_n_i_t_._p_y, and
       adds the directory _s_i_t_e___s_c_o_n_s_/_s_i_t_e___t_o_o_l_s to the  default  toolpath,  if
       those  exist.   See  the  _-_-_n_o_-_s_i_t_e_-_d_i_r and _-_-_s_i_t_e_-_d_i_r options for more
       details.

       ssccoonnss reads and executes the SConscript files as Python scripts, so you
       may  use  normal  Python  scripting capabilities (such as flow control,
       data manipulation, and imported Python libraries) to handle complicated
       build  situations.  ssccoonnss, however, reads and executes all of the SCon-
       script files _b_e_f_o_r_e it begins building any targets.  To make this obvi-
       ous, ssccoonnss prints the following messages about what it is doing:

              $ scons foo.out
              scons: Reading SConscript files ...
              scons: done reading SConscript files.
              scons: Building targets  ...
              cp foo.in foo.out
              scons: done building targets.
              $

       The  status  messages (everything except the line that reads "cp foo.in
       foo.out") may be suppressed using the --QQ option.

       ssccoonnss does not automatically propagate the external environment used to
       execute  ssccoonnss  to the commands used to build target files.  This is so
       that builds will be guaranteed repeatable regardless of the environment
       variables  set  at  the time ssccoonnss is invoked.  This also means that if
       the compiler or other commands that you want to use to build your  tar-
       get  files  are  not  in standard system locations, ssccoonnss will not find
       them unless you explicitly set the PATH  to  include  those  locations.
       Whenever   you  create  an  ssccoonnss  construction  environment,  you  can
       propagate the value of PATH from your external environment as follows:

              import os
              env = Environment(ENV = {'PATH' : os.environ['PATH']})

       Similarly, if the commands  use  external  environment  variables  like
       $PATH,  $HOME,  $JAVA_HOME, $LANG, $SHELL, $TERM, etc., these variables
       can also be explicitly propagated:

              import os
              env = Environment(ENV = {'PATH' : os.environ['PATH'],
                                       'HOME' : os.environ['HOME']})

       Or you may explicitly propagate the invoking user's  complete  external
       environment:

              import os
              env = Environment(ENV = os.environ)

       This  comes at the expense of making your build dependent on the user's
       environment being set correctly, but it may be more convenient for many
       configurations.

       ssccoonnss  can scan known input files automatically for dependency informa-
       tion (for example, #include statements in C  or  C++  files)  and  will
       rebuild  dependent  files  appropriately  whenever any "included" input
       file changes.  ssccoonnss supports the ability to define  new  scanners  for
       unknown input file types.

       ssccoonnss knows how to fetch files automatically from SCCS or RCS subdirec-
       tories using SCCS, RCS or BitKeeper.

       ssccoonnss is normally executed in a top-level directory containing a  _S_C_o_n_-
       _s_t_r_u_c_t file, optionally specifying as command-line arguments the target
       file or files to be built.

       By default, the command

              scons

       will build  all  target  files  in  or  below  the  current  directory.
       Explicit  default targets (to be built when no targets are specified on
       the command line) may be  defined  the  SConscript  file(s)  using  the
       DDeeffaauulltt(()) function, described below.

       Even  when  DDeeffaauulltt(())  targets are specified in the SConscript file(s),
       all target files in or below the current  directory  may  be  built  by
       explicitly specifying the current directory (.)  as a command-line tar-
       get:

              scons .

       Building all target files, including any files outside of  the  current
       directory,  may  be specified by supplying a command-line target of the
       root directory (on POSIX systems):

              scons /

       or the path name(s) of the volume(s) in which all the targets should be
       built (on Windows systems):

              scons C:\ D:\

       To build only specific targets, supply them as command-line arguments:

              scons foo bar

       in  which case only the specified targets will be built (along with any
       derived files on which they depend).

       Specifying "cleanup" targets in SConscript files is not usually  neces-
       sary.   The  --cc flag removes all files necessary to build the specified
       target:

              scons -c .

       to remove all target files, or:

              scons -c build export

       to remove target files under build and  export.   Additional  files  or
       directories  to  remove  can  be  specified using the CClleeaann(()) function.
       Conversely, targets that would normally be removed by the --cc invocation
       can be prevented from being removed by using the NNooCClleeaann() function.

       A  subset  of a hierarchical tree may be built by remaining at the top-
       level directory (where the _S_C_o_n_s_t_r_u_c_t file lives)  and  specifying  the
       subdirectory as the target to be built:

              scons src/subdir

       or  by  changing directory and invoking scons with the --uu option, which
       traverses up the directory hierarchy  until  it  finds  the  _S_C_o_n_s_t_r_u_c_t
       file, and then builds targets relatively to the current subdirectory:

              cd src/subdir
              scons -u .

       ssccoonnss  supports  building  multiple targets in parallel via a --jj option
       that takes, as its argument, the number of simultaneous tasks that  may
       be spawned:

              scons -j 4

       builds four targets in parallel, for example.

       ssccoonnss can maintain a cache of target (derived) files that can be shared
       between multiple builds.  When caching is enabled in a SConscript file,
       any target files built by ssccoonnss will be copied to the cache.  If an up-
       to-date target file is found in the cache, it will  be  retrieved  from
       the  cache  instead  of being rebuilt locally.  Caching behavior may be
       disabled and controlled in other ways by  the  ----ccaacchhee--ffoorrccee,  ----ccaacchhee--
       ddiissaabbllee, and ----ccaacchhee--sshhooww command-line options.  The ----rraannddoomm option is
       useful to prevent multiple builds  from  trying  to  update  the  cache
       simultaneously.

       Values of variables to be passed to the SConscript file(s) may be spec-
       ified on the command line:

              scons debug=1 .

       These variables are available in SConscript files through the ARGUMENTS
       dictionary,  and  can  be  used in the SConscript file(s) to modify the
       build in any way:

              if ARGUMENTS.get('debug', 0):
                  env = Environment(CCFLAGS = '-g')
              else:
                  env = Environment()

       The command-line variable arguments are also available in  the  ARGLIST
       list,  indexed  by their order on the command line.  This allows you to
       process them in order rather than by name,  if  necessary.   ARGLIST[0]
       returns  a tuple containing (argname, argvalue).  A Python exception is
       thrown if you try to access a list member that does not exist.

       ssccoonnss requires Python version 1.5.2 or later.  There should be no other
       dependencies or requirements to run ssccoonnss..

       By  default,  ssccoonnss knows how to search for available programming tools
       on various systems.  On Windows systems, ssccoonnss searches  in  order  for
       the  Microsoft  Visual  C++ tools, the MinGW tool chain, the Intel com-
       piler tools, and the PharLap ETS  compiler.   On  OS/2  systems,  ssccoonnss
       searches  in  order  for the OS/2 compiler, the GCC tool chain, and the
       Microsoft Visual C++ tools, On SGI IRIX, IBM AIX, Hewlett  Packard  HP-
       UX,  and  Sun  Solaris  systems, ssccoonnss searches for the native compiler
       tools (MIPSpro, Visual Age, aCC, and Forte tools respectively) and  the
       GCC  tool  chain.   On  all other platforms, including POSIX (Linux and
       UNIX) platforms, ssccoonnss searches in order for the GCC  tool  chain,  the
       Microsoft  Visual C++ tools, and the Intel compiler tools.  You may, of
       course, override these default values by appropriate  configuration  of
       Environment construction variables.


OOPPTTIIOONNSS
       In  general,  ssccoonnss supports the same command-line options as GNU mmaakkee,
       and many of those supported by ccoonnss.


       -b     Ignored for compatibility with non-GNU versions of mmaakkee..


       -c, --clean, --remove
              Clean up by removing all target files for which  a  construction
              command  is  specified.   Also  remove  any files or directories
              associated to the construction command using the  CClleeaann()  func-
              tion.   Will  not  remove any targets specified by the NNooCClleeaann()
              function.


       --cache-debug=_f_i_l_e
              Print  debug  information  about  the  CCaacchheeDDiirr()   derived-file
              caching  to  the  specified  _f_i_l_e.  If _f_i_l_e is -- (a hyphen), the
              debug information are  printed  to  the  standard  output.   The
              printed  messages  describe  what signature file names are being
              looked for in, retrieved from,  or  written  to  the  CCaacchheeDDiirr()
              directory tree.


       --cache-disable, --no-cache
              Disable the derived-file caching specified by CCaacchheeDDiirr().  ssccoonnss
              will neither retrieve files from the cache nor copy files to the
              cache.


       --cache-force, --cache-populate
              When  using CCaacchheeDDiirr(), populate a cache by copying any already-
              existing, up-to-date derived files to the cache, in addition  to
              files  built  by  this invocation.  This is useful to populate a
              new cache with all the current derived files, or to add  to  the
              cache any derived files recently built with caching disabled via
              the ----ccaacchhee--ddiissaabbllee option.


       --cache-show
              When using CCaacchheeDDiirr() and retrieving a  derived  file  from  the
              cache,  show  the command that would have been executed to build
              the file, instead of the usual report,  "Retrieved  `file'  from
              cache."   This  will  produce  consistent output for build logs,
              regardless of whether a target file  was  rebuilt  or  retrieved
              from the cache.


       --config=_m_o_d_e
              This specifies how the CCoonnffiigguurree call should use or generate the
              results of configuration tests.  The option should be  specified
              from among the following choices:


       --config=auto
              scons  will  use its normal dependency mechanisms to decide if a
              test must be rebuilt or not.  This saves time by not running the
              same  configuration  tests every time you invoke scons, but will
              overlook changes in system header  files  or  external  commands
              (such  as  compilers)  if  you  don't  specify those dependecies
              explicitly.  This is the default behavior.


       --config=force
              If this option is specified, all configuration tests will be re-
              run  regardless  of  whether the cached results are out of date.
              This can be used to explicitly force the configuration tests  to
              be  updated in response to an otherwise unconfigured change in a
              system header file or compiler.


       --config=cache
              If this option is specified,  no  configuration  tests  will  be
              rerun and all results will be taken from cache.  Note that scons
              will still consider it an error if --config=cache  is  specified
              and a necessary test does not yet have any results in the cache.


       -C _d_i_r_e_c_t_o_r_y,  --directory=_d_i_r_e_c_t_o_r_y
              Change to the specified _d_i_r_e_c_t_o_r_y before searching for the _S_C_o_n_-
              _s_t_r_u_c_t,  _S_c_o_n_s_t_r_u_c_t, or _s_c_o_n_s_t_r_u_c_t file, or doing anything else.
              Multiple --CC options are interpreted  relative  to  the  previous
              one,  and  the right-most --CC option wins. (This option is nearly
              equivalent to  --ff  ddiirreeccttoorryy//SSCCoonnssttrruucctt,  except  that  it  will
              search  for  _S_C_o_n_s_t_r_u_c_t, _S_c_o_n_s_t_r_u_c_t, or _s_c_o_n_s_t_r_u_c_t in the speci-
              fied directory.)



       -D     Works exactly the same way as the --uu option except for  the  way
              default  targets  are  handled.  When this option is used and no
              targets are specified on the command line, all  default  targets
              are  built, whether or not they are below the current directory.


       --debug=_t_y_p_e
              Debug the build process.  _t_y_p_e specifies what type of debugging:


       --debug=count
              Print  how  many objects are created of the various classes used
              internally by SCons before  and  after  reading  the  SConscript
              files  and  before and after building targets.  This is not sup-
              ported when run under Python versions  earlier  than  2.1,  when
              SCons is executed with the Python --OO (optimized) option, or when
              the SCons modules have been compiled with optimization (that is,
              when executing from **..ppyyoo files).


       --debug=dtree
              A  synonym  for  the  newer ----ttrreeee==ddeerriivveedd option.  This will be
              deprecated in some future release and ultimately removed.


       --debug=explain
              Print an explanation of  precisely  why  ssccoonnss  is  deciding  to
              (re-)build  any  targets.   (Note:  this does not print anything
              for targets that are _n_o_t rebuilt.)


       --debug=findlibs
              Instruct the scanner that searches for libraries to print a mes-
              sage  about each potential library name it is searching for, and
              about the actual libraries it finds.


       --debug=includes
              Print the include tree after each  top-level  target  is  built.
              This  is  generally  used to find out what files are included by
              the sources of a given derived file:

              $ scons --debug=includes foo.o


       --debug=memoizer
              Prints a summary of hits  and  misses  using  the  Memoizer,  an
              internal  subsystem that counts how often SCons uses cached val-
              ues in memory instead of  recomputing  them  each  time  they're
              needed.  Only available when using Python 2.2 or later.


       --debug=memory
              Prints  how  much memory SCons uses before and after reading the
              SConscript files and before and after building targets.


       --debug=nomemoizer
              A deprecated option preserved for backwards compatibility.


       --debug=objects
              Prints a list of the various objects of the various classes used
              internally  by SCons.  This only works when run under Python 2.1
              or later.


       --debug=pdb
              Re-run SCons under the control of the pdb Python debugger.


       --debug=presub
              Print the raw command line used to build each target before  the
              construction  environment variables are substituted.  Also shows
              which targets are being built by  this  command.   Output  looks
              something like this:
              $ scons --debug=presub
              Building myprog.o with action(s):
                $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES


       --debug=stacktrace
              Prints  an internal Python stack trace when encountering an oth-
              erwise unexplained error.


       --debug=stree
              A synonym for the newer ----ttrreeee==aallll,,ssttaattuuss option.  This will  be
              deprecated in some future release and ultimately removed.


       --debug=time
              Prints  various  time profiling information: the time spent exe-
              cuting each individual build command; the total build time (time
              SCons  ran  from beginning to end); the total time spent reading
              and executing SConscript  files;  the  total  time  spent  SCons
              itself  spend running (that is, not counting reading and execut-
              ing SConscript files); and both the total time  spent  executing
              all build commands and the elapsed wall-clock time spent execut-
              ing those build commands.  (When ssccoonnss is executed  without  the
              --jj  option,  the  elapsed  wall-clock  time  will  typically  be
              slightly longer than the total  time  spent  executing  all  the
              build  commands, due to the SCons processing that takes place in
              between executing each command.  When ssccoonnss is executed _w_i_t_h the
              --jj option, and your build configuration allows good paralleliza-
              tion,  the  elapsed  wall-clock  time  should  be  significantly
              smaller  than  the total time spent executing all the build com-
              mands, since multiple build commands and intervening SCons  pro-
              cessing should take place in parallel.)


       --debug=tree
              A  synonym for the newer ----ttrreeee==aallll option.  This will be depre-
              cated in some future release and ultimately removed.


       --diskcheck=_t_y_p_e_s
              Enable specific checks for whether or not there  is  a  file  on
              disk  where the SCons configuration expects a directory (or vice
              versa), and whether or  not  RCS  or  SCCS  sources  exist  when
              searching  for source and include files.  The _t_y_p_e_s argument can
              be set to: aallll, to enable all  checks  explicitly  (the  default
              behavior);  nnoonnee,  to  disable  all such checks; mmaattcchh, to check
              that files and directories on disk match SCons' expected config-
              uration;  rrccss,  to  check for the existence of an RCS source for
              any missing source or include files;  ssccccss,  to  check  for  the
              existence  of  an  SCCS source for any missing source or include
              files.  Multiple checks can be specified  separated  by  commas;
              for example, ----ddiisskkcchheecckk==ssccccss,,rrccss would still check for SCCS and
              RCS sources, but disable the check for on-disk matches of  files
              and directories.  Disabling some or all of these checks can pro-
              vide a performance boost for large configurations, or  when  the
              configuration  will  check  for  files and/or directories across
              networked or shared file systems, at the slight  increased  risk
              of  an  incorrect build or of not handling errors gracefully (if
              include files really should be found in SCCS or RCS,  for  exam-
              ple,  or  if a file really does exist where the SCons configura-
              tion expects a directory).


       --duplicate=_O_R_D_E_R
              There are three ways to duplicate files in a  build  tree:  hard
              links,  soft  (symbolic) links and copies. The default behaviour
              of SCons is to prefer hard links to soft links  to  copies.  You
              can  specify  different behaviours with this option.  _O_R_D_E_R must
              be one of _h_a_r_d_-_s_o_f_t_-_c_o_p_y (the  default),  _s_o_f_t_-_h_a_r_d_-_c_o_p_y,  _h_a_r_d_-
              _c_o_p_y,  _s_o_f_t_-_c_o_p_y or _c_o_p_y.  SCons will attempt to duplicate files
              using the mechanisms in the specified order.



       -f _f_i_l_e, --file=_f_i_l_e, --makefile=_f_i_l_e, --sconstruct=_f_i_l_e
              Use _f_i_l_e as the initial SConscript file.


       -h, --help
              Print a local help message for this build, if one is defined  in
              the SConscript file(s), plus a line that describes the --HH option
              for command-line option help.   If  no  local  help  message  is
              defined,  prints  the  standard  help message about command-line
              options.  Exits after displaying the appropriate message.


       -H, --help-options
              Print the standard help message about command-line  options  and
              exit.


       -i, --ignore-errors
              Ignore all errors from commands executed to rebuild files.


       -I _d_i_r_e_c_t_o_r_y, --include-dir=_d_i_r_e_c_t_o_r_y
              Specifies a _d_i_r_e_c_t_o_r_y to search for imported Python modules.  If
              several --II options are used, the directories are searched in the
              order specified.


       --implicit-cache
              Cache  implicit  dependencies.   This  causes  ssccoonnss  to use the
              implicit (scanned) dependencies from the last time  it  was  run
              instead  of  scanning the files for implicit dependencies.  This
              can significantly speed up SCons, but with the following limita-
              tions:

              ssccoonnss  will  not  detect  changes  to implicit dependency search
              paths (e.g.  CCPPPPPPAATTHH, LLIIBBPPAATTHH) that would ordinarily cause  dif-
              ferent versions of same-named files to be used.

              ssccoonnss  will  miss  changes in the implicit dependencies in cases
              where a new implicit dependency is added earlier in the implicit
              dependency  search  path (e.g.  CCPPPPPPAATTHH, LLIIBBPPAATTHH) than a current
              implicit dependency with the same name.


       --implicit-deps-changed
              Forces SCons to ignore the cached  implicit  dependencies.  This
              causes  the  implicit dependencies to be rescanned and recached.
              This implies ----iimmpplliicciitt--ccaacchhee.


       --implicit-deps-unchanged
              Force SCons to ignore  changes  in  the  implicit  dependencies.
              This  causes  cached  implicit  dependencies  to always be used.
              This implies ----iimmpplliicciitt--ccaacchhee.


       --interactive
              Starts SCons in interactive mode.  The SConscript files are read
              once  and  a  ssccoonnss>>>>>>  prompt  is  printed.  Targets may now be
              rebuilt by typing commands at interactive prompt without  having
              to re-read the SConscript files and re-initialize the dependency
              graph from scratch.

              SCons interactive mode supports the following commands:


                 bbuuiilldd_[_O_P_T_I_O_N_S_] _[_T_A_R_G_E_T_S_] _._._.
                       Builds the specified _T_A_R_G_E_T_S (and  their  dependencies)
                       with  the  specified SCons command-line _O_P_T_I_O_N_S.  bb and
                       ssccoonnss are synonyms.

                       The following SCons  command-line  options  affect  the
                       bbuuiilldd command:

                       --cache-debug=FILE
                       --cache-disable, --no-cache
                       --cache-force, --cache-populate
                       --cache-show
                       --debug=TYPE
                       -i, --ignore-errors
                       -j N, --jobs=N
                       -k, --keep-going
                       -n, --no-exec, --just-print, --dry-run, --recon
                       -Q
                       -s, --silent, --quiet
                       -s, --silent, --quiet
                       --taskmastertrace=FILE
                       --tree=OPTIONS


                       Any other SCons command-line options that are specified
                       do not cause errors but have no  effect  on  the  bbuuiilldd
                       command  (mainly because they affect how the SConscript
                       files are read, which only happens once at  the  begin-
                       ning of interactive mode).


                 cclleeaann_[_O_P_T_I_O_N_S_] _[_T_A_R_G_E_T_S_] _._._.
                       Cleans  the  specified _T_A_R_G_E_T_S (and their dependencies)
                       with the specified options.  cc is a synonym.  This com-
                       mand is itself a synonym for bbuuiilldd ----cclleeaann


                 eexxiitt  Exits  SCons  interactive  mode.   You can also exit by
                       terminating input (CTRL+D on  UNIX  or  Linux  systems,
                       CTRL+Z on Windows systems).


                 hheellpp_[_C_O_M_M_A_N_D_]
                       Provides a help message about the commands available in
                       SCons interactive mode.  If _C_O_M_M_A_N_D is specified, hh and
                       ??  are synonyms.


                 sshheellll_[_C_O_M_M_A_N_D_L_I_N_E_]
                       Executes  the  specified _C_O_M_M_A_N_D_L_I_N_E in a subshell.  If
                       no _C_O_M_M_A_N_D_L_I_N_E is specified, executes  the  interactive
                       command  interpreter specified in the SSHHEELLLL environment
                       variable (on UNIX and Linux  systems)  or  the  CCOOMMSSPPEECC
                       environment  variable  (on  Windows systems).  sshh and !!
                       are synonyms.


                 vveerrssiioonn
                       Prints SCons version information.


              An empty line repeats  the  last  typed  command.   Command-line
              editing can be used if the rreeaaddlliinnee module is available.

              $ scons --interactive
              scons: Reading SConscript files ...
              scons: done reading SConscript files.
              scons>>> build -n prog
              scons>>> exit


       -j _N, --jobs=_N
              Specifies  the  number of jobs (commands) to run simultaneously.
              If there is more than one --jj option, the last one is  effective.


       -k, --keep-going
              Continue  as  much  as possible after an error.  The target that
              failed and those that depend on it will not be remade, but other
              targets specified on the command line will still be processed.




       -m     Ignored for compatibility with non-GNU versions of mmaakkee.


       --max-drift=_S_E_C_O_N_D_S
              Set the maximum expected drift in the modification time of files
              to _S_E_C_O_N_D_S.  This value determines  how  long  a  file  must  be
              unmodified  before  its  cached  content  signature will be used
              instead of calculating a new content signature (MD5 checksum) of
              the file's contents.  The default value is 2 days, which means a
              file must have a modification time of at least two days  ago  in
              order  to  have  its  cached content signature used.  A negative
              value means to never cache the content signature and  to  ignore
              the  cached value if there already is one. A value of 0 means to
              always use the cached signature, no matter how old the file  is.


       -n, --just-print, --dry-run, --recon
              No  execute.  Print the commands that would be executed to build
              any out-of-date target files, but do not execute the commands.


       --no-site-dir
              Prevents the automatic addition of the standard  _s_i_t_e___s_c_o_n_s  dir
              to  _s_y_s_._p_a_t_h.  Also prevents loading the _s_i_t_e___s_c_o_n_s_/_s_i_t_e___i_n_i_t_._p_y
              module if it exists, and prevents  adding  _s_i_t_e___s_c_o_n_s_/_s_i_t_e___t_o_o_l_s
              to the toolpath.



       --profile=_f_i_l_e
              Run  SCons under the Python profiler and save the results in the
              specified _f_i_l_e.  The results may be analyzed  using  the  Python
              pstats module.


       -q, --question
              Do not run any commands, or print anything.  Just return an exit
              status that is zero if the specified targets are already  up  to
              date, non-zero otherwise.

       -Q     Quiets  SCons  status  messages  about reading SConscript files,
              building targets and entering directories.   Commands  that  are
              executed to rebuild target files are still printed.



       --random
              Build  dependencies  in  a  random  order.   This is useful when
              building multiple trees simultaneously with caching enabled,  to
              prevent  multiple  builds from simultaneously trying to build or
              retrieve the same target files.


       -s, --silent, --quiet
              Silent.  Do not print commands that are executed to rebuild tar-
              get files.  Also suppresses SCons status messages.


       -S, --no-keep-going, --stop
              Ignored for compatibility with GNU mmaakkee.


       --site-dir=_d_i_r
              Uses  the  named  dir  as  the  site dir rather than the default
              _s_i_t_e___s_c_o_n_s dir.  This dir will get prepended  to  _s_y_s_._p_a_t_h,  the
              module  _d_i_r/site_init.py  will  get  loaded  if  it  exists, and
              _d_i_r/site_tools will get added to the default toolpath.


       --stack-size=_K_I_L_O_B_Y_T_E_S
              Set the size stack used to run threads to _K_I_L_O_B_Y_T_E_S.  This value
              determines  the  stack  size  of  the  threads used to run jobs.
              These are the threads that execute the actions of  the  builders
              for  the  nodes that are out-of-date.  Note that this option has
              no effect unless the nnuumm__jjoobbss option, which  corresponds  to  -j
              and  --jobs, is larger than one.  Using a stack size that is too
              small may cause stack overflow errors.  This usually shows up as
              segmentation  faults  that  cause scons to abort before building
              anything.  Using a stack size that is too large will cause scons
              to  use  more  memory than required and may slow down the entire
              build process.

              The default value is to use a stack size of 256 kilobytes, which
              should  be  appropriate  for  most uses.  You should not need to
              increase this value unless you encounter stack overflow  errors.


       -t, --touch
              Ignored  for  compatibility  with GNU mmaakkee.  (Touching a file to
              make it appear up-to-date is unnecessary when using ssccoonnss.)


       --taskmastertrace=_f_i_l_e
              Prints trace information to the specified  _f_i_l_e  about  how  the
              internal  Taskmaster  object evaluates and controls the order in
              which Nodes are built.  A file name of -- may be used to  specify
              the standard output.


       -tree=_o_p_t_i_o_n_s
              Prints a tree of the dependencies after each top-level target is
              built.  This prints out some or all of the tree, in various for-
              mats, depending on the _o_p_t_i_o_n_s specified:


       --tree=all
              Print  the entire dependency tree after each top-level target is
              built.  This prints out the complete dependency tree,  including
              implicit dependencies and ignored dependencies.


       --tree=derived
              Restricts  the  tree  output to only derived (target) files, not
              source files.


       --tree=status
              Prints status information for each displayed node.


       --tree=prune
              Prunes the tree to avoid repeating  dependency  information  for
              nodes  that  have  already  been  displayed.   Any node that has
              already been displayed will have its  name  printed  in  [[ssqquuaarree
              bbrraacckkeettss]],  as an indication that the dependencies for that node
              can be found by searching for the relevant output higher  up  in
              the tree.


              Multiple options may be specified, separated by commas:

              # Prints only derived files, with status information:
              scons --tree=derived,status

              # Prints all dependencies of target, with status information
              # and pruning dependencies of already-visited Nodes:
              scons --tree=all,prune,status target


       -u, --up, --search-up
              Walks  up  the  directory  structure until an _S_C_o_n_s_t_r_u_c_t _, _S_c_o_n_-
              _s_t_r_u_c_t or _s_c_o_n_s_t_r_u_c_t file is found, and uses that as the top  of
              the  directory tree.  If no targets are specified on the command
              line, only targets at or below the  current  directory  will  be
              built.


       -U     Works  exactly  the same way as the --uu option except for the way
              default targets are handled.  When this option is  used  and  no
              targets  are  specified on the command line, all default targets
              that are defined in the SConscript(s) in the  current  directory
              are  built,  regardless  of what directory the resultant targets
              end up in.


       -v, --version
              Print the ssccoonnss version, copyright information, list of authors,
              and any other relevant information.  Then exit.


       -w, --print-directory
              Print  a  message  containing  the  working directory before and
              after other processing.


       --no-print-directory
              Turn off -w, even if it was turned on implicitly.


       --warn=_t_y_p_e, --warn=no-_t_y_p_e
              Enable or disable warnings.  _t_y_p_e specifies the type of warnings
              to be enabled or disabled:


       --warn=all, --warn=no-all
              Enables or disables all warnings.


       --warn=cache-write-error, --warn=no-cache-write-error
              Enables or disables warnings about errors trying to write a copy
              of a built file to a specified CCaacchheeDDiirr().  These  warnings  are
              disabled by default.


       --warn=corrupt-sconsign, --warn=no-corrupt-sconsign
              Enables  or disables warnings about unfamiliar signature data in
              ..ssccoonnssiiggnn files.  These warnings are enabled by default.


       --warn=dependency, --warn=no-dependency
              Enables or disables warnings about dependencies.  These warnings
              are disabled by default.


       --warn=deprecated, --warn=no-deprecated
              Enables  or  disables  all warnings about use of deprecated fea-
              tures.  These warnings are enabled  by  default.   Warnings  for
              some  specific  deprecated  features  may be enabled or disabled
              individually; see below.

              --warn=deprecated-copy,  --warn=no-deprecated-copy  Enables   or
              disables warnings about use of the deprecated eennvv..CCooppyy(()) method.

              --warn=deprecated-source-signatures,       --warn=no-deprecated-
              source-signatures  Enables or disables warnings about use of the
              deprecated SourceSignatures() function or eennvv..SSoouurrcceeSSiiggnnaattuurreess(())
              method.

              --warn=deprecated-target-signatures,   --warn=no-deprecated-tar-
              get-signatures Enables or disables warnings  about  use  of  the
              deprecated TargetSignatures() function or eennvv..TTaarrggeettSSiiggnnaattuurreess(())
              method.


       --warn=duplicate-environment, --warn=no-duplicate-environment
              Enables or disables warnings about missing SConscript files.


       --warn=misleading-keywords, --warn=no-misleading-keywords
              Enables or disables warnings about use of  the  misspelled  key-
              words ttaarrggeettss and ssoouurrcceess when calling Builders.  (Note the last
              ss characters, the correct  spellings  are  ttaarrggeett  and  ssoouurrccee..))
              These warnings are enabled by default.


       --warn=missing-sconscript, --warn=no-missing-sconscript
              Enables  or  disables warnings about attempts to specify a build
              of a target with two different  construction  environments  that
              use the same action.  These warnings are enabled by default.


       --warn=no-md5-module, --warn=no-no-md5-module
              Enables  or  disables  warnings  about the version of Python not
              having an MD5 checksum module  available.   These  warnings  are
              enabled by default.


       --warn=no-metaclass-support, --warn=no-no-metaclass-support
              Enables  or  disables  warnings  about the version of Python not
              supporting metaclasses when the ----ddeebbuugg==mmeemmooiizzeerr option is used.
              These warnings are enabled by default.


       --warn=no-object-count, --warn=no-no-object-count
              Enables  or  disables  warnings about the ----ddeebbuugg==oobbjjeecctt feature
              not working when ssccoonnss is run with the python --OO option or  from
              optimized Python (.pyo) modules.


       --warn=no-parallel-support, --warn=no-no-parallel-support
              Enables  or  disables  warnings  about the version of Python not
              being able to support parallel builds  when  the  --jj  option  is
              used.  These warnings are enabled by default.


       --warn=python-version, --warn=no-python-version
              Enables  or disables the warning about running SCons with a dep-
              recated version  of  Python.   These  warnings  are  enabled  by
              default.


       --warn=reserved-variable, --warn=no-reserved-variable
              Enables  or disables warnings about attempts to set the reserved
              construction variable names TTAARRGGEETT, TTAARRGGEETTSS, SSOOUURRCCEE or  SSOOUURRCCEESS.
              These warnings are disabled by default.


       --warn=stack-size, --warn=no-stack-size
              Enables  or  disables  warnings  about requests to set the stack
              size that could not be honored.  These warnings are  enabled  by
              default.



       -Y _r_e_p_o_s_i_t_o_r_y, --repository=_r_e_p_o_s_i_t_o_r_y, --srcdir=_r_e_p_o_s_i_t_o_r_y
              Search  the  specified repository for any input and target files
              not found in the local directory hierarchy.  Multiple --YY options
              may be specified, in which case the repositories are searched in
              the order specified.


CCOONNFFIIGGUURRAATTIIOONN FFIILLEE RREEFFEERREENNCCEE
   CCoonnssttrruuccttiioonn EEnnvviirroonnmmeennttss
       A construction environment is the basic means by which  the  SConscript
       files communicate build information to ssccoonnss.  A new construction envi-
       ronment is created using the EEnnvviirroonnmmeenntt function:

              env = Environment()

       Variables, called _c_o_n_s_t_r_u_c_t_i_o_n _v_a_r_i_a_b_l_e_s, may be set in a  construction
       environment  either  by  specifyng  them as keywords when the object is
       created or by assigning them a value after the object is created:

              env = Environment(FOO = 'foo')
              env['BAR'] = 'bar'

       As a convenience, construction variables may also be set or modified by
       the  _p_a_r_s_e___f_l_a_g_s  keyword argument, which applies the PPaarrsseeFFllaaggss method
       (described below) to the argument value after all other  processing  is
       completed.   This is useful either if the exact content of the flags is
       unknown (for example, read from a control file) or  if  the  flags  are
       distributed to a number of construction variables.

              env = Environment(parse_flags = '-Iinclude -DEBUG -lm')

       This  example  adds 'include' to CCPPPPPPAATTHH, 'EBUG' to CCPPPPDDEEFFIINNEESS, and 'm'
       to LLIIBBSS.

       By default, a new construction environment is initialized with a set of
       builder methods and construction variables that are appropriate for the
       current platform.  An optional platform keyword argument may be used to
       specify that an environment should be initialized for a different plat-
       form:

              env = Environment(platform = 'cygwin')
              env = Environment(platform = 'os2')
              env = Environment(platform = 'posix')
              env = Environment(platform = 'win32')

       Specifying a platform initializes the  appropriate  construction  vari-
       ables  in  the environment to use and generate file names with prefixes
       and suffixes appropriate for the platform.

       Note that the wwiinn3322 platform adds the SSYYSSTTEEMMDDRRIIVVEE and SSYYSSTTEEMMRROOOOTT  vari-
       ables from the user's external environment to the construction environ-
       ment's EENNVV dictionary.  This is so that any executed commands that  use
       sockets  to  connect  with other systems (such as fetching source files
       from  external  CVS  repository  specifications  like   ::ppsseerrvveerr::aannoonnyy--
       mmoouuss@@ccvvss..ssoouurrcceeffoorrggee..nneett:://ccvvssrroooott//ssccoonnss)  will work on Windows systems.

       The platform argument may be function or callable object, in which case
       the Environment() method will call the specified argument to update the
       new construction environment:

              def my_platform(env):
                  env['VAR'] = 'xyzzy'

              env = Environment(platform = my_platform)

       Additionally, a specific set of tools  with  which  to  initialize  the
       environment may be specified as an optional keyword argument:

              env = Environment(tools = ['msvc', 'lex'])

       Non-built-in tools may be specified using the toolpath argument:

              env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])

       This  looks  for a tool specification in tools/foo.py (as well as using
       the ordinary default tools for the platform).  foo.py should  have  two
       functions:  generate(env,  **kw) and exists(env).  The ggeenneerraattee(()) func-
       tion modifies the passed-in environment to set up variables so that the
       tool  can  be  executed; it may use any keyword arguments that the user
       supplies (see below) to vary its initialization.  The eexxiissttss(()) function
       should  return  a  true  value  if the tool is available.  Tools in the
       toolpath are used before any of the built-in ones.  For example, adding
       gcc.py to the toolpath would override the built-in gcc tool.  Also note
       that the toolpath is stored in the environment for use by  later  calls
       to CClloonnee() and TTooooll() methods:

              base = Environment(toolpath=['custom_path'])
              derived = base.Clone(tools=['custom_tool'])
              derived.CustomBuilder()

       The  elements  of  the  tools  list  may  also be functions or callable
       objects, in which case the Environment() method will call the specified
       elements to update the new construction environment:

              def my_tool(env):
                  env['XYZZY'] = 'xyzzy'

              env = Environment(tools = [my_tool])

       The  individual  elements of the tools list may also themselves be two-
       element lists of the form (_t_o_o_l_n_a_m_e, _k_w___d_i_c_t).  SCons searches for  the
       _t_o_o_l_n_a_m_e  specification  file  as  described above, and passes _k_w___d_i_c_t,
       which must be a dictionary, as keyword arguments to the tool's ggeenneerraattee
       function.   The  ggeenneerraattee  function can use the arguments to modify the
       tool's behavior by setting up the environment in different ways or oth-
       erwise changing its initialization.

              # in tools/my_tool.py:
              def generate(env, **kw):
                # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
                env['MY_TOOL'] = kw.get('arg1', '1')
              def exists(env):
                return 1

              # in SConstruct:
              env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
                                toolpath=['tools'])

       The tool definition (i.e. my_tool()) can use the PLATFORM variable from
       the environment it receives to customize the tool for  different  plat-
       forms.

       If no tool list is specified, then SCons will auto-detect the installed
       tools using the PATH variable in the ENV construction variable and  the
       platform  name  when  the Environment is constructed. Changing the PATH
       variable after the Environment is constructed will not cause the  tools
       to be redetected.

       SCons supports the following tool specifications out of the box:

              386asm
              aixc++
              aixcc
              aixf77
              aixlink
              ar
              as
              bcc32
              c++
              cc
              cvf
              dmd
              dvipdf
              dvips
              f77
              f90
              f95
              fortran
              g++
              g77
              gas
              gcc
              gfortran
              gnulink
              gs
              hpc++
              hpcc
              hplink
              icc
              icl
              ifl
              ifort
              ilink
              ilink32
              intelc
              jar
              javac
              javah
              latex
              lex
              link
              linkloc
              m4
              masm
              midl
              mingw
              mslib
              mslink
              msvc
              msvs
              mwcc
              mwld
              nasm
              pdflatex
              pdftex
              qt
              rmic
              rpcgen
              sgiar
              sgic++
              sgicc
              sgilink
              sunar
              sunc++
              suncc
              sunlink
              swig
              tar
              tex
              tlib
              yacc
              zip

       Additionally,  there  is  a  "tool"  named ddeeffaauulltt which configures the
       environment with a default set of tools for the current platform.

       On posix and cygwin platforms the GNU tools (e.g. gcc) are preferred by
       SCons, on Windows the Microsoft tools (e.g. msvc) followed by MinGW are
       preferred by SCons, and in OS/2 the IBM tools (e.g. icc) are  preferred
       by SCons.


   BBuuiillddeerr MMeetthhooddss
       Build  rules  are  specified  by  calling  a construction environment's
       builder methods.  The arguments to the builder methods  are  ttaarrggeett  (a
       list  of targets to be built, usually file names) and ssoouurrccee (a list of
       sources to be built, usually file names).

       Because long lists of file names can lead to a lot  of  quoting,  ssccoonnss
       supplies  a SSpplliitt(()) global function and a same-named environment method
       that split a single string into a list, separated on strings of  white-
       space characters.  (These are similar to the string.split() method from
       the standard Python library,  but  work  even  if  the  input  isn't  a
       string.)

       Like all Python arguments, the target and source arguments to a builder
       method can be  specified  either  with  or  without  the  "target"  and
       "source" keywords.  When the keywords are omitted, the target is first,
       followed by the source.  The following are equivalent examples of call-
       ing the Program builder method:

              env.Program('bar', ['bar.c', 'foo.c'])
              env.Program('bar', Split('bar.c foo.c'))
              env.Program('bar', env.Split('bar.c foo.c'))
              env.Program(source =  ['bar.c', 'foo.c'], target = 'bar')
              env.Program(target = 'bar', Split('bar.c foo.c'))
              env.Program(target = 'bar', env.Split('bar.c foo.c'))
              env.Program('bar', source = string.split('bar.c foo.c'))

       Target and source file names that are not absolute path names (that is,
       do not begin with // on POSIX systems or oonn  WWiinnddoowwss  ssyysstteemmss,,  with  or
       without  an  optional  drive  letter)  are  interpreted relative to the
       directory containing the SSCCoonnssccrriipptt file  being  read.   An  initial  ##
       (hash  mark)  on  a  path  name means that the rest of the file name is
       interpreted relative to the directory containing  the  top-level  SSCCoonn--
       ssttrruucctt file, even if the ## is followed by a directory separator charac-
       ter (slash or backslash).

       Examples:

              # The comments describing the targets that will be built
              # assume these calls are in a SConscript file in the
              # a subdirectory named "subdir".

              # Builds the program "subdir/foo" from "subdir/foo.c":
              env.Program('foo', 'foo.c')

              # Builds the program "/tmp/bar" from "subdir/bar.c":
              env.Program('/tmp/bar', 'bar.c')

              # An initial '#' or '#/' are equivalent; the following
              # calls build the programs "foo" and "bar" (in the
              # top-level SConstruct directory) from "subdir/foo.c" and
              # "subdir/bar.c", respectively:
              env.Program('#foo', 'foo.c')
              env.Program('#/bar', 'bar.c')

              # Builds the program "other/foo" (relative to the top-level
              # SConstruct directory) from "subdir/foo.c":
              env.Program('#other/foo', 'foo.c')

       When the target shares the same base name as the source  and  only  the
       suffix  varies,  and if the builder method has a suffix defined for the
       target file type, then the target argument may be  omitted  completely,
       and  ssccoonnss  will deduce the target file name from the source file name.
       The following examples all build the executable program bbaarr  (on  POSIX
       systems) or bbaarr..eexxee (on Windows systems) from the bar.c source file:

              env.Program(target = 'bar', source = 'bar.c')
              env.Program('bar', source = 'bar.c')
              env.Program(source = 'bar.c')
              env.Program('bar.c')

       As a convenience, a ssrrccddiirr keyword argument may be specified when call-
       ing a Builder.  When specified, all source file strings  that  are  not
       absolute  paths  will  be interpreted relative to the specified ssrrccddiirr.
       The following example will build the bbuuiilldd//pprroogg (or  bbuuiilldd//pprroogg..eexxee  on
       Windows) program from the files ssrrcc//ff11..cc and ssrrcc//ff22..cc:

              env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')

       It is possible to override or add construction variables when calling a
       builder method by passing additional keyword arguments.  These overrid-
       den or added variables will only be in effect when building the target,
       so they will not affect other parts of the build. For example,  if  you
       want to add additional libraries for just one program:

              env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])

       or generate a shared library with a non-standard suffix:

              env.SharedLibrary('word', 'word.cpp',
                                SHLIBSUFFIX='.ocx',
                                LIBSUFFIXES=['.ocx'])

       (Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
       if you want SCons to search automatically for dependencies on the  non-
       standard library names; see the descriptions of these variables, below,
       for more information.)

       It is also possible to use the _p_a_r_s_e___f_l_a_g_s keyword argument in an over-
       ride:

              env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')

       This  example  adds 'include' to CCPPPPPPAATTHH, 'EBUG' to CCPPPPDDEEFFIINNEESS, and 'm'
       to LLIIBBSS.

       Although the builder methods defined by ssccoonnss are, in fact, methods  of
       a  construction  environment object, they may also be called without an
       explicit environment:

              Program('hello', 'hello.c')
              SharedLibrary('word', 'word.cpp')

       In this case, the methods are called internally using  a  default  con-
       struction  environment that consists of the tools and values that ssccoonnss
       has determined are appropriate for the local system.

       Builder methods that can be called without an explicit environment  may
       be called from custom Python modules that you import into an SConscript
       file by adding the following to the Python module:

              from SCons.Script import *

       All builder methods return a list-like  object  containing  Nodes  that
       represent  the  target  or  targets  that  will be built.  A _N_o_d_e is an
       internal SCons object which represents build targets or sources.

       The returned Node-list object can be passed to other builder methods as
       source(s)  or  passed  to any SCons function or method where a filename
       would normally be accepted.  For example, if it were necessary to add a
       specific --DD flag when compiling one specific object file:

              bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
              env.Program(source = ['foo.c', bar_obj_list, 'main.c'])

       Using  a  Node  in this way makes for a more portable build by avoiding
       having to specify a platform-specific object suffix  when  calling  the
       Program() builder method.

       Note  that  Builder  calls  will automatically "flatten" the source and
       target file lists, so it's all right to have the bar_obj list return by
       the  StaticObject() call in the middle of the source file list.  If you
       need to manipulate a list of lists returned by Builders directly  using
       Python, you can either build the list by hand:

              foo = Object('foo.c')
              bar = Object('bar.c')
              objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
              for object in objects:
                  print str(object)

       Or  you  can  use  the FFllaatttteenn() function supplied by scons to create a
       list containing just the Nodes, which may be more convenient:

              foo = Object('foo.c')
              bar = Object('bar.c')
              objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
              for object in objects:
                  print str(object)

       Note also that because Builder calls return a list-like object, not  an
       actual Python list, you should _n_o_t use the Python ++== operator to append
       Builder results to a Python list.  Because the list and the object  are
       different types, Python will not update the original list in place, but
       will instead create a new Node-list object containing the concatenation
       of the list elements and the Builder results.  This will cause problems
       for any other Python variables in your SCons configuration  that  still
       hold  on  to a reference to the original list.  Instead, use the Python
       ..eexxtteenndd(()) method to make sure the list is updated in-place.  Example:

              object_files = []

              # Do NOT use += as follows:
              #
              #    object_files += Object('bar.c')
              #
              # It will not update the object_files list in place.
              #
              # Instead, use the .extend() method:
              object_files.extend(Object('bar.c'))


       The path name for a Node's file may be used by passing the Node to  the
       Python-builtin ssttrr(()) function:

              bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
              print "The path to bar_obj is:", str(bar_obj_list[0])

       Note  again  that  because  the Builder call returns a list, we have to
       access the first element in the list ((bbaarr__oobbjj__lliisstt[[00]])) to  get  at  the
       Node that actually represents the object file.

       Builder  calls support a cchhddiirr keyword argument that specifies that the
       Builder's action(s) should be executed after  changing  directory.   If
       the  cchhddiirr  argument is a string or a directory Node, scons will change
       to the specified directory.  If the cchhddiirr is not a string or  Node  and
       is non-zero, then scons will change to the target file's directory.

              # scons will change to the "sub" subdirectory
              # before executing the "cp" command.
              env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
                          "cp dir/foo.in dir/foo.out",
                          chdir='sub')

              # Because chdir is not a string, scons will change to the
              # target's directory ("sub/dir") before executing the
              # "cp" command.
              env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
                          "cp foo.in foo.out",
                          chdir=1)

       Note  that  scons  will  _n_o_t automatically modify its expansion of con-
       struction variables like $$TTAARRGGEETT and $$SSOOUURRCCEE when using the chdir  key-
       word  argument--that is, the expanded file names will still be relative
       to the top-level SConstruct directory, and consequently incorrect rela-
       tive  to  the  chdir directory.  If you use the chdir keyword argument,
       you will typically need to supply a different command line using expan-
       sions  like  $${{TTAARRGGEETT..ffiillee}} and $${{SSOOUURRCCEE..ffiillee}} to use just the filename
       portion of the targets and source.

       ssccoonnss provides the following builder methods:



       CFile()

       env.CFile()
              Builds a C source file given a lex (..ll) or yacc (..yy) input file.
              The  suffix  specified by the $CFILESUFFIX construction variable
              (..cc by default) is automatically added to the target  if  it  is
              not already present.  Example:

              # builds foo.c
              env.CFile(target = 'foo.c', source = 'foo.l')
              # builds bar.c
              env.CFile(target = 'bar', source = 'bar.y')


       CXXFile()

       env.CXXFile()
              Builds  a  C++ source file given a lex (..llll) or yacc (..yyyy) input
              file.  The suffix specified by the  $CXXFILESUFFIX  construction
              variable  (..cccc  by default) is automatically added to the target
              if it is not already present.  Example:

              # builds foo.cc
              env.CXXFile(target = 'foo.cc', source = 'foo.ll')
              # builds bar.cc
              env.CXXFile(target = 'bar', source = 'bar.yy')


       DVI()

       env.DVI()
              Builds a ..ddvvii file from a ..tteexx, ..llttxx or ..llaatteexx input  file.   If
              the  source file suffix is ..tteexx, ssccoonnss will examine the contents
              of the file; if  the  string  ooccuummeennttccllaassss  or  ooccuummeennttssttyyllee  is
              found,  the file is assumed to be a LaTeX file and the target is
              built by invoking the $LATEXCOM  command  line;  otherwise,  the
              $TEXCOM  command line is used.  If the file is a LaTeX file, the
              DDVVII() builder method will also examine the contents of the  ..aauuxx
              file  and  invoke the $BIBTEX command line if the string bbiibbddaattaa
              is found, start $MAKEINDEX to generate an index if a  ..iinndd  file
              is  found and will examine the contents ..lloogg file and re-run the
              $LATEXCOM command if the log file says it is necessary.

              The suffix ..ddvvii (hard-coded within TeX itself) is  automatically
              added to the target if it is not already present.  Examples:

              # builds from aaa.tex
              env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
              # builds bbb.dvi
              env.DVI(target = 'bbb', source = 'bbb.ltx')
              # builds from ccc.latex
              env.DVI(target = 'ccc.dvi', source = 'ccc.latex')


       Install()

       env.Install()
              Installs  one  or more source files or directories in the speci-
              fied target, which must be a directory.  The names of the speci-
              fied source files or directories remain the same within the des-
              tination directory.

              env.Install('/usr/local/bin', source = ['foo', 'bar'])


       InstallAs()

       env.InstallAs()
              Installs one or more source files  or  directories  to  specific
              names, allowing changing a file or directory name as part of the
              installation.  It is an error if the target and source arguments
              list different numbers of files or directories.

              env.InstallAs(target = '/usr/local/bin/foo',
                            source = 'foo_debug')
              env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
                            source = ['libFOO.a', 'libBAR.a'])


       Jar()

       env.Jar()
              Builds  a  Java  archive  (..jjaarr) file from the specified list of
              sources.  Any directories in the source list  will  be  searched
              for  ..ccllaassss  files).  Any ..jjaavvaa files in the source list will be
              compiled  to ..ccllaassss files by calling the JJaavvaa() Builder.

              If the $JARCHDIR value is set, the jjaarr command  will  change  to
              the  specified  directory  using the --CC option.  If $JARCHDIR is
              not set explicitly, &SCons; will use the top of any subdirectory
              tree in which Java ..ccllaassss were built by the JJaavvaa() Builder.

              If  the  contents  any of the source files begin with the string
              MMaanniiffeesstt--VVeerrssiioonn, the file is assumed to be a  manifest  and  is
              passed to the jjaarr command with the mm option set.

              env.Jar(target = 'foo.jar', source = 'classes')

              env.Jar(target = 'bar.jar',
                      source = ['bar1.java', 'bar2.java'])


       Java()

       env.Java()
              Builds  one  or  more  Java class files.  The sources may be any
              combination of explicit ..jjaavvaa files, or  directory  trees  which
              will be scanned for ..jjaavvaa files.

              SCons  will  parse  each  source  ..jjaavvaa file to find the classes
              (including inner classes) defined within  that  file,  and  from
              that  figure  out  the target ..ccllaassss files that will be created.
              The class files will be placed underneath the  specified  target
              directory.

              SCons will also search each Java file for the Java package name,
              which it assumes can be found  on  a  line  beginning  with  the
              string  ppaacckkaaggee  in the first column; the resulting ..ccllaassss files
              will be placed in a directory reflecting the  specified  package
              name.   For  example, the file FFoooo..jjaavvaa defining a single public
              _F_o_o class and containing a package name of _s_u_b_._d_i_r will generate
              a corresponding ssuubb//ddiirr//FFoooo..ccllaassss class file.

              Example:

              env.Java(target = 'classes', source = 'src')
              env.Java(target = 'classes', source = ['src1', 'src2'])
              env.Java(target = 'classes', source = ['File1.java', 'File2.java'])


       JavaH()

       env.JavaH()
              Builds  C  header  and source files for implementing Java native
              methods.  The target can be either  a  directory  in  which  the
              header  files  will be written, or a header file name which will
              contain all of the definitions.  The source can be the names  of
              ..ccllaassss  files,  the  names  of  ..jjaavvaa  files to be compiled into
              ..ccllaassss files by  calling  the  JJaavvaa()  builder  method,  or  the
              objects returned from the JJaavvaa() builder method.

              If the construction variable $JAVACLASSDIR is set, either in the
              environment or in the call to the JJaavvaaHH() builder method itself,
              then  the  value  of  the  variable  will  be  stripped from the
              beginning of any ..ccllaassss file names.

              Examples:

              # builds java_native.h
              classes = env.Java(target = 'classdir', source = 'src')
              env.JavaH(target = 'java_native.h', source = classes)

              # builds include/package_foo.h and include/package_bar.h
              env.JavaH(target = 'include',
                        source = ['package/foo.class', 'package/bar.class'])

              # builds export/foo.h and export/bar.h
              env.JavaH(target = 'export',
                        source = ['classes/foo.class', 'classes/bar.class'],
                        JAVACLASSDIR = 'classes')


       Library()

       env.Library()
              A synonym for the SSttaattiiccLLiibbrraarryy() builder method.


       LoadableModule()

       env.LoadableModule()
              On most systems, this is the same as SShhaarreeddLLiibbrraarryy().  On Mac OS
              X (Darwin) platforms, this creates a loadable module bundle.


       M4()

       env.M4()
              Builds  an  output  file  from  an  M4  input file.  This uses a
              default $M4FLAGS value of --EE, which considers all warnings to be
              fatal  and stops on the first warning when using the GNU version
              of m4.  Example:

              env.M4(target = 'foo.c', source = 'foo.c.m4')


       Moc()

       env.Moc()
              Builds an output file from a moc input file. Moc input files are
              either header files or cxx files. This builder is only available
              after using the tool 'qt'. See  the  $QTDIR  variable  for  more
              information.  Example:

              env.Moc('foo.h') # generates moc_foo.cc
              env.Moc('foo.cpp') # generates foo.moc


       MSVSProject()

       env.MSVSProject()
              Builds  a  Microsoft  Visual Studio project file, and by default
              builds a solution file as well.

              This builds a Visual Studio project file, based on  the  version
              of Visual Studio that is configured (either the latest installed
              version, or the version specified by $MSVS_VERSION in the  Envi-
              ronment  constructor).   For Visual Studio 6, it will generate a
              ..ddsspp file.  For Visual Studio 7 (.NET) and  later  versions,  it
              will generate a ..vvccpprroojj file.

              By  default,  this also generates a solution file for the speci-
              fied project, a ..ddssww file for Visual Studio 6 or a ..ssllnn file for
              Visual Studio 7 (.NET).  This behavior may be disabled by speci-
              fying aauuttoo__bbuuiilldd__ssoolluuttiioonn==00  when  you  call  MMSSVVSSPPrroojjeecctt(),  in
              which  case you presumably want to build the solution file(s) by
              calling the MMSSVVSSSSoolluuttiioonn() Builder (see below).

              It takes several lists  of  filenames  to  be  placed  into  the
              project file.  These are currently limited to ssrrccss, iinnccss, llooccaall--
              iinnccss, rreessoouurrcceess, and mmiisscc.  These are  pretty  self-explanatory,
              but  it  should  be  noted  that  these  lists  are added to the
              $SOURCES construction variable as strings,  NOT  as  SCons  File
              Nodes.  This is because they represent file names to be added to
              the project file, not the source files used to build the project
              file.

              The above filename lists are all optional, although at least one
              must be specified for the resulting  project  file  to  be  non-
              empty.

              In  addition  to the above lists of values, the following values
              may be specified:

              ttaarrggeett: The name of the target ..ddsspp or ..vvccpprroojj file.   The  cor-
              rect  suffix  for the version of Visual Studio must be used, but
              the $MSVSPROJECTSUFFIX construction variable will be defined  to
              the correct value (see example below).

              vvaarriiaanntt: The name of this particular variant.  For Visual Studio
              7 projects, this can also be a list of variant names.  These are
              typically  things  like  "Debug" or "Release", but really can be
              anything you want.  For Visual Studio 7 projects, they may  also
              specify a target platform separated from the variant name by a ||
              (vertical pipe) character: DDeebbuugg||XXbbooxx.  The default target plat-
              form  is  Win32.  Multiple calls to MMSSVVSSPPrroojjeecctt() with different
              variants are allowed; all variants will be added to the  project
              file with their appropriate build targets and sources.

              bbuuiillddttaarrggeett:  An  optional  string,  node, or list of strings or
              nodes (one per build variant), to tell the Visual Studio  debug-
              ger what output target to use in what build variant.  The number
              of bbuuiillddttaarrggeett entries must match the number of vvaarriiaanntt entries.

              rruunnffiillee:  The  name  of  the file that Visual Studio 7 and later
              will run and debug.  This appears as the  value  of  the  OOuuttppuutt
              field  in  the resutling Visual Studio project file.  If this is
              not specified, the default is the same as the  specified  bbuuiilldd--
              ttaarrggeett value.

              Example usage:

              barsrcs = ['bar.cpp'],
              barincs = ['bar.h'],
              barlocalincs = ['StdAfx.h']
              barresources = ['bar.rc','resource.h']
              barmisc = ['bar_readme.txt']

              dll = env.SharedLibrary(target = 'bar.dll',
                                      source = barsrcs)

              env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
                              srcs = barsrcs,
                              incs = barincs,
                              localincs = barlocalincs,
                              resources = barresources,
                              misc = barmisc,
                              buildtarget = dll,
                              variant = 'Release')


       MSVSSolution()

       env.MSVSSolution()
              Builds a Microsoft Visual Studio solution file.

              This  builds a Visual Studio solution file, based on the version
              of Visual Studio that is configured (either the latest installed
              version,  or  the version specified by $MSVS_VERSION in the con-
              struction environment).  For Visual Studio 6, it will generate a
              ..ddssww  file.  For Visual Studio 7 (.NET), it will generate a ..ssllnn
              file.

              The following values must be specified:

              ttaarrggeett: The name of the target .dsw or .sln file.   The  correct
              suffix  for  the  version of Visual Studio must be used, but the
              value $MSVSSOLUTIONSUFFIX will be defined to the  correct  value
              (see example below).

              vvaarriiaanntt: The name of this particular variant, or a list of vari-
              ant names (the latter is only supported for MSVS  7  solutions).
              These are typically things like "Debug" or "Release", but really
              can be anything you want. For MSVS 7 they may also specify  tar-
              get platform, like this "Debug|Xbox". Default platform is Win32.

              pprroojjeeccttss: A  list  of  project  file  names,  or  Project  nodes
              returned  by  calls  to  the MMSSVVSSPPrroojjeecctt() Builder, to be placed
              into the solution file.  It should  be  noted  that  these  file
              names are NOT added to the $SOURCES environment variable in form
              of files, but rather as strings.   This is because  they  repre-
              sent file names to be added to the solution file, not the source
              files used to build the solution file.

              (NOTE: Currently only one project is supported per solution.)

              Example Usage:

              env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'],
                               projects = ['bar' + env['MSVSPROJECTSUFFIX']],
                               variant = 'Release')


       Object()

       env.Object()
              A synonym for the SSttaattiiccOObbjjeecctt() builder method.


       Package()

       env.Package()
              Builds software  distribution  packages.   Packages  consist  of
              files  to  install and packaging information.  The former may be
              specified with the &source; parameter and may be  left  out,  in
              which  case  the  &FindInstalledFiles; function will collect all
              files    that    have    an     IInnssttaallll()orIInnssttaallllAAss()BBuuiillddeerrat-
              tached.IIffthe&&ttaarrggeett;;,,is  not  specified  it will be deduced from
              additional information given to this Builder.

              The packaging information is specified with  the  help  of  con-
              struction  variables  documented  below.   This  information  is
              called a tag to stress that some of them can also be attached to
              files with the &Tag; function.  The mandatory ones will complain
              if they were not specified.  They vary depending on chosen  tar-
              get packager.

              The  target packager may be selected with the "PACKAGETYPE" com-
              mand line option or with the $PACKAGETYPE construction variable.
              Currently the following packagers available:

               * msi - Microsoft Installer
               * rpm - Redhat Package Manger
               * ipkg - Itsy Package Management System
               * tarbz2 - compressed tar
               * targz - compressed tar
               * zip - zip file
               * src_tarbz2 - compressed tar source
               * src_targz - compressed tar source
               * src_zip - zip file source

              An  updated  list  is  always available under the "package_type"
              option when  running  "scons  --help"  on  a  project  that  has
              packaging activated.
              env = Environment(tools=['default', 'packaging'])
              env.Install('/bin/', 'my_program')
              env.Package( NAME           = 'foo',
                           VERSION        = '1.2.3',
                           PACKAGEVERSION = 0,
                           PACKAGETYPE    = 'rpm',
                           LICENSE        = 'gpl',
                           SUMMARY        = 'balalalalal',
                           DESCRIPTION    = 'this should be really really long',
                           X_RPM_GROUP    = 'Application/fu',
                           SOURCE_URL     = 'http://foo.org/foo-1.2.3.tar.gz'
                      )


       PCH()

       env.PCH()
              Builds  a Microsoft Visual C++ precompiled header.  Calling this
              builder method returns a list of two targets:  the  PCH  as  the
              first  element,  and the object file as the second element. Nor-
              mally the object file is ignored.  This builder method  is  only
              provided  when  Microsoft  Visual  C++ is being used as the com-
              piler.  The PCH builder method is generally used  in  conjuction
              with  the PCH construction variable to force object files to use
              the precompiled header:

              env['PCH'] = env.PCH('StdAfx.cpp')[0]


       PDF()

       env.PDF()
              Builds a ..ppddff file from a ..ddvvii input file (or, by  extension,  a
              ..tteexx,  ..llttxx, or ..llaatteexx input file).  The suffix specified by the
              $PDFSUFFIX construction variable  (..ppddff  by  default)  is  added
              automatically to the target if it is not already present.  Exam-
              ple:

              # builds from aaa.tex
              env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
              # builds bbb.pdf from bbb.dvi
              env.PDF(target = 'bbb', source = 'bbb.dvi')


       PostScript()

       env.PostScript()
              Builds a ..ppss file from a ..ddvvii input file (or,  by  extension,  a
              ..tteexx,  ..llttxx, or ..llaatteexx input file).  The suffix specified by the
              $PSSUFFIX construction variable (..ppss by default) is added  auto-
              matically to the target if it is not already present.  Example:

              # builds from aaa.tex
              env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
              # builds bbb.ps from bbb.dvi
              env.PostScript(target = 'bbb', source = 'bbb.dvi')


       Program()

       env.Program()
              Builds  an  executable given one or more object files or C, C++,
              D, or Fortran source files.  If any C, C++, D or Fortran  source
              files are specified, then they will be automatically compiled to
              object files using the OObbjjeecctt() builder method; see that builder
              method's  description  for  a list of legal source file suffixes
              and how they are interpreted.  The target executable file prefix
              (specified  by the $PROGPREFIX construction variable; nothing by
              default) and suffix (specified by the  $PROGSUFFIX  construction
              variable;  by default, ..eexxee on Windows systems, nothing on POSIX
              systems) are automatically added to the target  if  not  already
              present.  Example:

              env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])


       RES()

       env.RES()
              Builds  a  Microsoft  Visual  C++  resource  file.  This builder
              method is only provided when Microsoft Visual C++  or  MinGW  is
              being used as the compiler. The ..rreess (or ..oo for MinGW) suffix is
              added to the target name if  no  other  suffix  is  given.   The
              source  file  is  scanned for implicit dependencies as though it
              were a C file.  Example:

              env.RES('resource.rc')


       RMIC()

       env.RMIC()
              Builds stub and skeleton class files  for  remote  objects  from
              Java  ..ccllaassss files.  The target is a directory relative to which
              the stub and skeleton class files will be written.   The  source
              can be the names of ..ccllaassss files, or the objects return from the
              JJaavvaa() builder method.

              If the construction variable $JAVACLASSDIR is set, either in the
              environment  or in the call to the RRMMIICC() builder method itself,
              then the value of the variable will be stripped from the  begin-
              ning of any ..ccllaassss file names.

              classes = env.Java(target = 'classdir', source = 'src')
              env.RMIC(target = 'outdir1', source = classes)

              env.RMIC(target = 'outdir2',
                       source = ['package/foo.class', 'package/bar.class'])

              env.RMIC(target = 'outdir3',
                       source = ['classes/foo.class', 'classes/bar.class'],
                       JAVACLASSDIR = 'classes')


       RPCGenClient()

       env.RPCGenClient()
              Generates an RPC client stub (__ccllnntt..cc) file from a specified RPC
              (..xx) source file.  Because rpcgen only builds  output  files  in
              the  local directory, the command will be executed in the source
              file's directory by default.

              # Builds src/rpcif_clnt.c
              env.RPCGenClient('src/rpcif.x')


       RPCGenHeader()

       env.RPCGenHeader()
              Generates an RPC header (..hh) file  from  a  specified  RPC  (..xx)
              source  file.   Because  rpcgen  only builds output files in the
              local directory, the command will  be  executed  in  the  source
              file's directory by default.

              # Builds src/rpcif.h
              env.RPCGenHeader('src/rpcif.x')


       RPCGenService()

       env.RPCGenService()
              Generates  an RPC server-skeleton (__ssvvcc..cc) file from a specified
              RPC (..xx) source file.  Because rpcgen only builds  output  files
              in  the  local  directory,  the  command will be executed in the
              source file's directory by default.

              # Builds src/rpcif_svc.c
              env.RPCGenClient('src/rpcif.x')


       RPCGenXDR()

       env.RPCGenXDR()
              Generates an RPC XDR routine (__xxddrr..cc) file from a specified  RPC
              (..xx)  source  file.   Because rpcgen only builds output files in
              the local directory, the command will be executed in the  source
              file's directory by default.

              # Builds src/rpcif_xdr.c
              env.RPCGenClient('src/rpcif.x')


       SharedLibrary()

       env.SharedLibrary()
              Builds a shared library (..ssoo on a POSIX system, ..ddllll on Windows)
              given one or more object files or C, C++, D  or  Fortran  source
              files.   If  any source files are given, then they will be auto-
              matically compiled to object files.  The static  library  prefix
              and  suffix (if any) are automatically added to the target.  The
              target library file prefix (specified by the  $SHLIBPREFIX  con-
              struction variable; by default, lliibb on POSIX systems, nothing on
              Windows systems) and suffix (specified by the $SHLIBSUFFIX  con-
              struction  variable; by default, ..ddllll on Windows systems, ..ssoo on
              POSIX systems) are automatically added  to  the  target  if  not
              already present.  Example:

              env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])

              On  Windows  systems,  the  SShhaarreeddLLiibbrraarryy()  builder method will
              always build an import (..lliibb) library in addition to the  shared
              (..ddllll)  library, adding a ..lliibb library with the same basename if
              there is not already a ..lliibb file explicitly listed in  the  tar-
              gets.

              Any object files listed in the ssoouurrccee must have been built for a
              shared  library  (that  is,  using  the  SShhaarreeddOObbjjeecctt()  builder
              method).  ssccoonnss will raise an error if there is any mismatch.

              On Windows systems, specifying rreeggiisstteerr==11 will cause the ..ddllll to
              be registered after it is built  using  REGSVR32.   The  command
              that  is  run  ("regsvr32"  by default) is determined by $REGSVR
              construction variable, and the flags passed  are  determined  by
              $REGSVRFLAGS.   By default, $REGSVRFLAGS includes the //ss option,
              to prevent dialogs from popping up and requiring user  attention
              when  it is run.  If you change $REGSVRFLAGS, be sure to include
              the //ss option.  For example,

              env.SharedLibrary(target = 'bar',
                                source = ['bar.cxx', 'foo.obj'],
                                register=1)

              will register bbaarr..ddllll as a COM object when it  is  done  linking
              it.


       SharedObject()

       env.SharedObject()
              Builds an object file for inclusion in a shared library.  Source
              files must have one of the  same  set  of  extensions  specified
              above  for the SSttaattiiccOObbjjeecctt() builder method.  On some platforms
              building a shared object  requires  additional  compiler  option
              (e.g. --ffPPIICC for gcc) in addition to those needed to build a nor-
              mal (static) object, but on some platforms there is  no  differ-
              ence  between  a  shared  object and a normal (static) one. When
              there is a difference, SCons will only allow shared  objects  to
              be linked into a shared library, and will use a different suffix
              for shared objects. On platforms where there is  no  difference,
              SCons  will  allow both normal (static) and shared objects to be
              linked into a shared library, and will use the same  suffix  for
              shared and normal (static) objects.  The target object file pre-
              fix (specified by the  $SHOBJPREFIX  construction  variable;  by
              default,  the  same  as $OBJPREFIX) and suffix (specified by the
              $SHOBJSUFFIX construction variable) are automatically  added  to
              the target if not already present.  Examples:

              env.SharedObject(target = 'ddd', source = 'ddd.c')
              env.SharedObject(target = 'eee.o', source = 'eee.cpp')
              env.SharedObject(target = 'fff.obj', source = 'fff.for')

              Note that the source files will be scanned according to the suf-
              fix mappings in the SSoouurrcceeFFiilleeSSccaannnneerr object.  See  the  section
              "Scanner Objects," below, for a more information.


       StaticLibrary()

       env.StaticLibrary()
              Builds  a  static  library  given one or more object files or C,
              C++, D or Fortran source files.  If any source files are  given,
              then  they  will be automatically compiled to object files.  The
              static library prefix and  suffix  (if  any)  are  automatically
              added  to the target.  The target library file prefix (specified
              by the $LIBPREFIX construction  variable;  by  default,  lliibb  on
              POSIX systems, nothing on Windows systems) and suffix (specified
              by the $LIBSUFFIX construction variable;  by  default,  ..lliibb  on
              Windows systems, ..aa on POSIX systems) are automatically added to
              the target if not already present.  Example:

              env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])

              Any object files listed in the ssoouurrccee must have been built for a
              static  library  (that  is,  using  the  SSttaattiiccOObbjjeecctt()  builder
              method).  ssccoonnss will raise an error if there is any mismatch.


       StaticObject()

       env.StaticObject()
              Builds a static object file from one or more C, C++, D, or  For-
              tran  source files.  Source files must have one of the following
              extensions:

                .asm    assembly language file
                .ASM    assembly language file
                .c      C file
                .C      Windows:  C file
                        POSIX:  C++ file
                .cc     C++ file
                .cpp    C++ file
                .cxx    C++ file
                .cxx    C++ file
                .c++    C++ file
                .C++    C++ file
                .d      D file
                .f      Fortran file
                .F      Windows:  Fortran file
                        POSIX:  Fortran file + C pre-processor
                .for    Fortran file
                .FOR    Fortran file
                .fpp    Fortran file + C pre-processor
                .FPP    Fortran file + C pre-processor
                .m      Object C file
                .mm     Object C++ file
                .s      assembly language file
                .S      Windows:  assembly language file
                        POSIX:  assembly language file + C pre-processor
                .spp    assembly language file + C pre-processor
                .SPP    assembly language file + C pre-processor

              The target object file prefix (specified by the $OBJPREFIX  con-
              struction variable; nothing by default) and suffix (specified by
              the $OBJSUFFIX construction variable; ..oobbjj on  Windows  systems,
              ..oo  on  POSIX  systems) are automatically added to the target if
              not already present.  Examples:

              env.StaticObject(target = 'aaa', source = 'aaa.c')
              env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
              env.StaticObject(target = 'ccc.obj', source = 'ccc.f')

              Note that the source files will be scanned according to the suf-
              fix  mappings  in  SSoouurrcceeFFiilleeSSccaannnneerr  object.   See  the section
              "Scanner Objects," below, for a more information.


       Tar()

       env.Tar()
              Builds a tar archive of the specified files and/or  directories.
              Unlike  most  builder  methods,  the TTaarr() builder method may be
              called multiple times for a given target; each  additional  call
              adds to the list of entries that will be built into the archive.
              Any source directories will be scanned for changes  to  any  on-
              disk  files, regardless of whether or not ssccoonnss knows about them
              from other Builder or function calls.

              env.Tar('src.tar', 'src')

              # Create the stuff.tar file.
              env.Tar('stuff', ['subdir1', 'subdir2'])
              # Also add "another" to the stuff.tar file.
              env.Tar('stuff', 'another')

              # Set TARFLAGS to create a gzip-filtered archive.
              env = Environment(TARFLAGS = '-c -z')
              env.Tar('foo.tar.gz', 'foo')

              # Also set the suffix to .tgz.
              env = Environment(TARFLAGS = '-c -z',
                                TARSUFFIX = '.tgz')
              env.Tar('foo')


       TypeLibrary()

       env.TypeLibrary()
              Builds a Windows type library (..ttllbb) file from an input IDL file
              (..iiddll).  In addition, it will build the associated inteface stub
              and proxy source files, naming them according to the  base  name
              of the ..iiddll file.  For example,

              env.TypeLibrary(source="foo.idl")

              Will  create  ffoooo..ttllbb,  ffoooo..hh,  ffoooo__ii..cc,  ffoooo__pp..cc and ffoooo__ddaattaa..cc
              files.


       Uic()

       env.Uic()
              Builds a header file, an implementation file and a moc file from
              an  ui  file.   and returns the corresponding nodes in the above
              order.  This builder is only  available  after  using  the  tool
              'qt'.  Note:  you can specify ..uuii files directly as source files
              to the  PPrrooggrraamm(),  LLiibbrraarryy()andSShhaarreeddLLiibbrraarryy()bbuuiillddeerrss  without
              using  this  builder.  Using  this builder lets you override the
              standard naming conventions (be  careful:  prefixes  are  always
              prepended  to  names of built files; if you don't want prefixes,
              you may set them to ``).   See  the  $QTDIR  variable  for  more
              information.  Example:

              env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
              env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
                      source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']


       Zip()

       env.Zip()
              Builds  a zip archive of the specified files and/or directories.
              Unlike most builder methods, the ZZiipp()  builder  method  may  be
              called  multiple  times for a given target; each additional call
              adds to the list of entries that will be built into the archive.
              Any  source  directories  will be scanned for changes to any on-
              disk files, regardless of whether or not ssccoonnss knows about  them
              from other Builder or function calls.

              env.Zip('src.zip', 'src')

              # Create the stuff.zip file.
              env.Zip('stuff', ['subdir1', 'subdir2'])
              # Also add "another" to the stuff.tar file.
              env.Zip('stuff', 'another')

       All  targets  of builder methods automatically depend on their sources.
       An explicit dependency can be specified using the DDeeppeennddss method  of  a
       construction environment (see below).

       In  addition,  ssccoonnss  automatically scans source files for various pro-
       gramming languages, so the dependencies do not  need  to  be  specified
       explicitly.   By  default,  SCons can C source files, C++ source files,
       Fortran source files with ..FF (POSIX systems only), ..ffpppp,, or  ..FFPPPP  file
       extensions,  and  assembly language files with ..SS (POSIX systems only),
       ..sspppp,, or ..SSPPPP files extensions for C preprocessor dependencies.   SCons
       also  has  default  support  for  scanning D source files, You can also
       write your own Scanners to  add  support  for  additional  source  file
       types.   These  can  be added to the default Scanner object used by the
       OObbjjeecctt() SSttaattiiccOObbjjeecctt() and SShhaarreeddOObbjjeecctt() Builders by adding  them  to
       the SSoouurrcceeFFiilleeSSccaannnneerr object as follows:

       See  the section "Scanner Objects," below, for a more information about
       defining your own Scanner objects.


   MMeetthhooddss aanndd FFuunnccttiioonnss ttoo DDoo TThhiinnggss
       In addition to Builder methods, ssccoonnss provides a number of  other  con-
       struction  environment  methods  and global functions to manipulate the
       build configuration.

       Usually, a construction environment method and global function with the
       same  name  both  exist so that you don't have to remember whether to a
       specific bit of functionality must be called with  or  without  a  con-
       struction environment.  In the following list, if you call something as
       a global function it looks like:
              Function(_a_r_g_u_m_e_n_t_s)
       and if you call something through a construction environment  it  looks
       like:
              env.Function(_a_r_g_u_m_e_n_t_s)
       If  you  can  call  the functionality in both ways, then both forms are
       listed.

       Global functions may be called from  custom  Python  modules  that  you
       import  into  an  SConscript file by adding the following to the Python
       module:

              from SCons.Script import *

       Except where otherwise noted, the same-named  construction  environment
       method  and  global function provide the exact same functionality.  The
       only difference is that, where appropriate, calling  the  functionality
       through  a  construction environment will substitute construction vari-
       ables into any supplied strings.  For example:

              env = Environment(FOO = 'foo')
              Default('$FOO')
              env.Default('$FOO')

       In the above example, the first call to the global  DDeeffaauulltt(())  function
       will  actually  add a target named $$FFOOOO to the list of default targets,
       while the second call to  the  eennvv..DDeeffaauulltt(())  construction  environment
       method  will expand the value and add a target named ffoooo to the list of
       default targets.  For more on construction variable expansion, see  the
       next section on construction variables.

       Construction  environment  methods  and  global  functions supported by
       ssccoonnss include:


       Action(_a_c_t_i_o_n, [_s_t_r_f_u_n_c_t_i_o_n, _v_a_r_l_i_s_t])

       env.Action(_a_c_t_i_o_n, [_s_t_r_f_u_n_c_t_i_o_n, _v_a_r_l_i_s_t])
              Creates an Action object for the specified _a_c_t_i_o_n.  See the sec-
              tion  "Action Objects," below, for a complete explanation of the
              arguments and behavior.

              Note that the eennvv..AAccttiioonn() form of the  invocation  will  expand
              construction  variables  in any arguments strings, including the
              _a_c_t_i_o_n argument, at the time it is called using the construction
              variables  in  the  eennvv  construction  environment through which
              eennvv..AAccttiioonn() was called.  The AAccttiioonn() form delays all  variable
              expansion until the Action object is actually used.


       AddMethod(_o_b_j_e_c_t_,function_, _[name_]_)

       env.AddMethod(_f_u_n_c_t_i_o_n, [_n_a_m_e])
              When  called with the AAddddMMeetthhoodd() form, adds the specified _f_u_n_c_-
              _t_i_o_n to the specified _o_b_j_e_c_t as the specified method _n_a_m_e.  When
              called  with  the eennvv..AAddddMMeetthhoodd() form, adds the specified _f_u_n_c_-
              _t_i_o_n to the construction environment _e_n_v as the specified method
              _n_a_m_e.   In  both  cases, if _n_a_m_e is omitted or NNoonnee, the name of
              the specified _f_u_n_c_t_i_o_n itself is used for the method name.

              Examples:

              # Note that the first argument to the function to
              # be attached as a method must be the object through
              # which the method will be called; the Python
              # convention is to call it 'self'.
              def my_method(self, arg):
                  print "my_method() got", arg

              # Use the global AddMethod() function to add a method
              # to the Environment class.  This
              AddMethod(Environment, my_method)
              env = Environment()
              env.my_method('arg')

              # Add the function as a method, using the function
              # name for the method call.
              env = Environment()
              env.AddMethod(my_method, 'other_method_name')
              env.other_method_name('another arg')


       AddOption(_a_r_g_u_m_e_n_t_s)
              This function adds a new command-line option to  be  recognized.
              The  specified  _a_r_g_u_m_e_n_t_s are the same as supported by the stan-
              dard Python ooppttppaarrssee..aadddd__ooppttiioonn() method (with a few  additional
              capabilities  noted  below);  see the documentation for ooppttppaarrssee
              for a thorough discussion of its  option-processing  capabities.
              (Note  that although the ooppttppaarrssee module was not a standard mod-
              ule until Python 2.3, ssccoonnss contains a compatible version of the
              module  that is used to provide identical functionality when run
              by earlier Python versions.)

              In addition to the arguments and values supported  by  the  oopptt--
              ppaarrssee..aadddd__ooppttiioonn  (())  method,  the  SCons  AAddddOOppttiioonn()  function
              allows you to set the nnaarrggss keyword value to ''??''  (a string with
              just  the  question  mark)  to  indicate that the specified long
              option(s) take(s) an _o_p_t_i_o_n_a_l argument.  When nnaarrggss  ==  ''??''   is
              passed  to  the AAddddOOppttiioonn() function, the ccoonnsstt keyword argument
              may be used to supply the "default" value that  should  be  used
              when  the  option  is  specified  on the command line without an
              explicit argument.

              If no ddeeffaauulltt== keyword argument is supplied when calling  AAddddOOpp--
              ttiioonn(), the option will have a default value of NNoonnee.

              Once  a new command-line option has been added with AAddddOOppttiioonn(),
              the option value may be accessed using GGeettOOppttiioonn() or eennvv..GGeettOOpp--
              ttiioonn().   The  value  may  also  be  set,  using  SSeettOOppttiioonn() or
              eennvv..SSeettOOppttiioonn(), if conditions in a SSCCoonnssccrriipptt require  overrid-
              ing any default value.  Note, however, that a value specified on
              the command line will _a_l_w_a_y_s override a value set by  any  SCon-
              script file.

              Any  specified  hheellpp== strings for the new option(s) will be dis-
              played by the --HH or --hh options (the latter only if no other help
              text  is  specified in the SConscript files).  The help text for
              the local options specified by AAddddOOppttiioonn() will appear below the
              SCons  options  themselves, under a separate LLooccaall OOppttiioonnss head-
              ing.  The options will appear in the help text in the  order  in
              which the AAddddOOppttiioonn() calls occur.

              Example:

              AddOption('--prefix',
                        dest='prefix',
                        nargs=1, type='string',
                        action='store',
                        metavar='DIR',
                        help='installation prefix')
              env = Environment(PREFIX = GetOption('prefix'))


       AddPostAction(_t_a_r_g_e_t, _a_c_t_i_o_n)

       env.AddPostAction(_t_a_r_g_e_t, _a_c_t_i_o_n)
              Arranges  for  the  specified  _a_c_t_i_o_n  to be performed after the
              specified _t_a_r_g_e_t has been built.  The specified action(s) may be
              an  Action  object,  or  anything  that can be converted into an
              Action object (see below).


       AddPreAction(_t_a_r_g_e_t, _a_c_t_i_o_n)

       env.AddPreAction(_t_a_r_g_e_t, _a_c_t_i_o_n)
              Arranges for the specified _a_c_t_i_o_n to  be  performed  before  the
              specified  _t_a_r_g_e_t  is  built.  The specified action(s) may be an
              Action object, or anything that can be converted into an  Action
              object (see below).


       Alias(_a_l_i_a_s, [_t_a_r_g_e_t_s, [_a_c_t_i_o_n]])

       env.Alias(_a_l_i_a_s, [_t_a_r_g_e_t_s, [_a_c_t_i_o_n]])
              Creates  one  or  more  phony targets that expand to one or more
              other targets.  An optional _a_c_t_i_o_n (command) or list of  actions
              can  be  specified that will be executed whenever the any of the
              alias targets are out-of-date.  Returns the Node  object  repre-
              senting  the  alias,  which  exists  outside of any file system.
              This Node object, or the alias name, may be used as a dependency
              of  any  other  target,  including  another alias.  AAlliiaass can be
              called multiple times for the same alias to add additional  tar-
              gets  to  the  alias, or additional actions to the list for this
              alias.

              Examples:

              Alias('install')
              Alias('install', '/usr/bin')
              Alias(['install', 'install-lib'], '/usr/local/lib')

              env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
              env.Alias('install', ['/usr/local/man'])

              env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")


       AllowSubstExceptions([_e_x_c_e_p_t_i_o_n, ...])
              Specifies the exceptions that will  be  allowed  when  expanding
              construction  variables.   By default, any construction variable
              expansions that generate a  NNaammeeEErrrroorr  or  IInnddeexxEErrrroorr  exception
              will expand to a '''' (a null string) and not cause scons to fail.
              All exceptions not in the specified list will generate an  error
              message and terminate processing.

              If AAlllloowwSSuubbssttEExxcceeppttiioonnss is called multiple times, each call com-
              pletely overwrites the previous list of allowed exceptions.

              Example:

              # Requires that all construction variable names exist.
              # (You may wish to do this if you want to enforce strictly
              # that all construction variables must be defined before use.)
              AllowSubstExceptions()

              # Also allow a string containing a zero-division expansion
              # like '${1 / 0}' to evalute to ''.
              AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)


       AlwaysBuild(_t_a_r_g_e_t, ...)

       env.AlwaysBuild(_t_a_r_g_e_t, ...)
              Marks each given _t_a_r_g_e_t so that it is always assumed to  be  out
              of  date,  and will always be rebuilt if needed.  Note, however,
              that AAllwwaayyssBBuuiilldd() does not add its  target(s)  to  the  default
              target list, so the targets will only be built if they are spec-
              ified on the command line, or are a dependent of a target speci-
              fied  on  the  command line--but they will _a_l_w_a_y_s be built if so
              specified.  Multiple targets can be passed in to a  single  call
              to AAllwwaayyssBBuuiilldd().


       env.Append(_k_e_y=_v_a_l, [...])
              Appends  the specified keyword arguments to the end of construc-
              tion variables in the environment.  If the Environment does  not
              have  the specified construction variable, it is simply added to
              the environment.  If the values of the construction variable and
              the keyword argument are the same type, then the two values will
              be simply added together.  Otherwise, the construction  variable
              and the value of the keyword argument are both coerced to lists,
              and the lists are added together.  (See also the Prepend method,
              below.)

              Example:

              env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])


       env.AppendENVPath(_n_a_m_e, _n_e_w_p_a_t_h, [_e_n_v_n_a_m_e, _s_e_p])
              This  appends  new path elements to the given path in the speci-
              fied external environment (EENNVV by default).  This will only  add
              any particular path once (leaving the last one it encounters and
              ignoring the rest, to preserve path order), and to  help  assure
              this,  will  normalize  all  paths  (using  ooss..ppaatthh..nnoorrmmppaatthh and
              ooss..ppaatthh..nnoorrmmccaassee).  This can also  handle  the  case  where  the
              given  old path variable is a list instead of a string, in which
              case a list will be returned instead of a string.

              Example:

              print 'before:',env['ENV']['INCLUDE']
              include_path = '/foo/bar:/foo'
              env.AppendENVPath('INCLUDE', include_path)
              print 'after:',env['ENV']['INCLUDE']

              yields:
              before: /foo:/biz
              after: /biz:/foo/bar:/foo


       env.AppendUnique(_k_e_y=_v_a_l, [...])
              Appends the specified keyword arguments to the end of  construc-
              tion  variables in the environment.  If the Environment does not
              have the specified construction variable, it is simply added  to
              the environment.  If the construction variable being appended to
              is a list, then any value(s) that already exist in the construc-
              tion variable will _n_o_t be added again to the list.

              Example:

              env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])


       env.BitKeeper()
              A  factory  function that returns a Builder object to be used to
              fetch source files using BitKeeper.   The  returned  Builder  is
              intended to be passed to the SSoouurrcceeCCooddee function.

              Example:

              env.SourceCode('.', env.BitKeeper())


       BuildDir(_b_u_i_l_d___d_i_r, _s_r_c___d_i_r, [_d_u_p_l_i_c_a_t_e])

       env.BuildDir(_b_u_i_l_d___d_i_r, _s_r_c___d_i_r, [_d_u_p_l_i_c_a_t_e])
              Synonyms  for  VVaarriiaannttDDiirr(()) and eennvv..VVaarriiaannttDDiirr(()).  The _b_u_i_l_d___d_i_r
              argument bedomes the _v_a_r_i_a_n_t___d_i_r  argument  of  VVaarriiaannttDDiirr(())  or
              eennvv..VVaarriiaannttDDiirr(()).   (This  will  be  officially  deprecated some
              day.)


       Builder(_a_c_t_i_o_n, [_a_r_g_u_m_e_n_t_s])

       env.Builder(_a_c_t_i_o_n, [_a_r_g_u_m_e_n_t_s])
              Creates a Builder object for the specified _a_c_t_i_o_n.  See the sec-
              tion "Builder Objects," below, for a complete explanation of the
              arguments and behavior.

              Note that the eennvv..BBuuiillddeerr() form of the invocation  will  expand
              construction  variables  in any arguments strings, including the
              _a_c_t_i_o_n argument, at the time it is called using the construction
              variables  in  the  eennvv  construction  environment through which
              eennvv..BBuuiillddeerr() was called.  The BBuuiillddeerr() form delays  all  vari-
              able  expansion  until  after  the  Builder  object  is actually
              called.


       CacheDir(_c_a_c_h_e___d_i_r)

       env.CacheDir(_c_a_c_h_e___d_i_r)
              Specifies that ssccoonnss will maintain a cache of derived  files  in
              _c_a_c_h_e___d_i_r _.  The derived files in the cache will be shared among
              all the builds using the same  CCaacchheeDDiirr()  call.   Specifying  a
              _c_a_c_h_e___d_i_r of NNoonnee disables derived file caching.

              Calling  eennvv..CCaacchheeDDiirr()  will  only affect targets built through
              the specified construction environment.  Calling CCaacchheeDDiirr() sets
              a  global default that will be used by all targets built through
              construction environments that do  _n_o_t  have  an  eennvv..CCaacchheeDDiirr()
              specified.

              When  a  CCaacchheeDDiirr() is being used and ssccoonnss finds a derived file
              that needs to be rebuilt, it will first look in the cache to see
              if  a  derived  file has already been built from identical input
              files and an identical build action (as  incorporated  into  the
              MD5  build signature).  If so, ssccoonnss will retrieve the file from
              the cache.  If the derived file is not  present  in  the  cache,
              ssccoonnss will rebuild it and then place a copy of the built file in
              the cache (identified by its MD5 build signature),  so  that  it
              may  be  retrieved  by  other builds that need to build the same
              derived file from identical inputs.

              Use of a specified CCaacchheeDDiirr(()) may be disabled for any invocation
              by using the ----ccaacchhee--ddiissaabbllee option.

              If  the ----ccaacchhee--ffoorrccee option is used, ssccoonnss will place a copy of
              _a_l_l derived files in the cache, even if they already existed and
              were not built by this invocation.  This is useful to populate a
              cache the first time CCaacchheeDDiirr() is added to a  build,  or  after
              using the ----ccaacchhee--ddiissaabbllee option.

              When using CCaacchheeDDiirr(), ssccoonnss will report, "Retrieved `file' from
              cache," unless the ----ccaacchhee--sshhooww option is being used.  When  the
              ----ccaacchhee--sshhooww  option  is  used, ssccoonnss will print the action that
              _w_o_u_l_d have been used to build the file, without  any  indication
              that  the  file  was actually retrieved from the cache.  This is
              useful to generate build logs that are equivalent regardless  of
              whether  a  given  derived  file  has  been  built  in-place  or
              retrieved from the cache.

              The NNooCCaacchhee() method can be used to disable caching of  specific
              files.  This can be useful if inputs and/or outputs of some tool
              are impossible to predict or prohibitively large.


       Clean(_t_a_r_g_e_t_s, _f_i_l_e_s___o_r___d_i_r_s)

       env.Clean(_t_a_r_g_e_t_s, _f_i_l_e_s___o_r___d_i_r_s)
              This specifies a list of files or directories  which  should  be
              removed  whenever  the targets are specified with the --cc command
              line option.  The specified targets may be a list or an individ-
              ual target.  Multiple calls to CClleeaann() are legal, and create new
              targets or add files and directories to the clean list  for  the
              specified targets.

              Multiple files or directories should be specified either as sep-
              arate arguments to the CClleeaann() method, or as  a  list.   CClleeaann()
              will  also  accept  the  return value of any of the construction
              environment Builder methods.  Examples:

              The related NNooCClleeaann() function overrides calling CClleeaann() for the
              same  target,  and any targets passed to both functions will _n_o_t
              be removed by the --cc option.

              Examples:

              Clean('foo', ['bar', 'baz'])
              Clean('dist', env.Program('hello', 'hello.c'))
              Clean(['foo', 'bar'], 'something_else_to_clean')


       Command(_t_a_r_g_e_t, _s_o_u_r_c_e, _a_c_t_i_o_n, [_k_e_y=_v_a_l, ...])

       env.Command(_t_a_r_g_e_t, _s_o_u_r_c_e, _a_c_t_i_o_n, [_k_e_y=_v_a_l, ...])
              Executes a specific action (or list of actions) to build a  tar-
              get file or files.  This is more convenient than defining a sep-
              arate Builder object for a single special-case build.

              As a special case, the ssoouurrccee__ssccaannnneerr keyword  argument  can  be
              used  to  specify a Scanner object that will be used to scan the
              sources.  (The global DDiirrSSccaannnneerr object can be used  if  any  of
              the sources will be directories that must be scanned on-disk for
              changes to files that aren't already specified in other  Builder
              of function calls.)

              Any  other  keyword  arguments specified override any same-named
              existing construction variables.

              An action can be an external command, specified as a string,  or
              a  callable Python object; see "Action Objects," below, for more
              complete information.  Also note that  a  string  specifying  an
              external  command  may be preceded by an @@ (at-sign) to suppress
              printing the command in question, or by a -- (hyphen)  to  ignore
              the exit status of the external command.

              Examples:

              env.Command('foo.out', 'foo.in',
                          "$FOO_BUILD < $SOURCES > $TARGET")

              env.Command('bar.out', 'bar.in',
                          ["rm -f $TARGET",
                           "$BAR_BUILD < $SOURCES > $TARGET"],
                          ENV = {'PATH' : '/usr/local/bin/'})

              def rename(env, target, source):
                  import os
                  os.rename('.tmp', str(target[0]))

              env.Command('baz.out', 'baz.in',
                          ["$BAZ_BUILD < $SOURCES > .tmp",
                        rename ])


              Note  that  the  CCoommmmaanndd()  function  will  usually  assume,  by
              default, that the specified targets and/or sources are Files, if
              no other part of the configuration identifies what type of entry
              it is.  If necessary, you can explicitly specify that targets or
              source  nodes  should  be  treated  as directoriese by using the
              DDiirr() or eennvv..DDiirr() functions.

              Examples:

              env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')

              env['DISTDIR'] = 'destination/directory'
              env.Command(env.Dir('$DISTDIR')), None, make_distdir)


              (Also note that SCons  will  usually  automatically  create  any
              directory necessary to hold a target file, so you normally don't
              need to create directories by hand.)


       Configure(_e_n_v, [_c_u_s_t_o_m___t_e_s_t_s, _c_o_n_f___d_i_r, _l_o_g___f_i_l_e, _c_o_n_f_i_g___h])

       env.Configure([_c_u_s_t_o_m___t_e_s_t_s, _c_o_n_f___d_i_r, _l_o_g___f_i_l_e, _c_o_n_f_i_g___h])
              Creates a Configure object for integrated functionality  similar
              to  GNU  autoconf.  See the section "Configure Contexts," below,
              for a complete explanation of the arguments and behavior.


       env.Clone([_k_e_y=_v_a_l, ...])
              Return a separate copy of a construction environment.  If  there
              are  any  keyword  arguments  specified,  they  are added to the
              returned copy, overwriting any existing values for the keywords.

              Example:

              env2 = env.Clone()
              env3 = env.Clone(CCFLAGS = '-g')

              Additionally,  a  list of tools and a toolpath may be specified,
              as in the Environment constructor:

              def MyTool(env): env['FOO'] = 'bar'
              env4 = env.Clone(tools = ['msvc', MyTool])

       The _p_a_r_s_e___f_l_a_g_s keyword argument is also recognized:

              # create an environment for compiling programs that use wxWidgets
              wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')


       env.Copy([_k_e_y=_v_a_l, ...])
              A now-deprecated synonym for eennvv..CClloonnee(()).


       env.CVS(_r_e_p_o_s_i_t_o_r_y, _m_o_d_u_l_e)
              A factory function that returns a Builder object to be  used  to
              fetch  source  files  from  the  specified  CVS _r_e_p_o_s_i_t_o_r_y.  The
              returned Builder is intended to  be  passed  to  the  SSoouurrcceeCCooddee
              function.

              The  optional specified _m_o_d_u_l_e will be added to the beginning of
              all repository path names; this can  be  used,  in  essence,  to
              strip initial directory names from the repository path names, so
              that you only have to replicate part of the repository directory
              hierarchy in your local build directory.

              Examples:

              # Will fetch foo/bar/src.c
              # from /usr/local/CVSROOT/foo/bar/src.c.
              env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))

              # Will fetch bar/src.c
              # from /usr/local/CVSROOT/foo/bar/src.c.
              env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))

              # Will fetch src.c
              # from /usr/local/CVSROOT/foo/bar/src.c.
              env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))


       Decider(_f_u_n_c_t_i_o_n)

       env.Decider(_f_u_n_c_t_i_o_n)
              Specifies  that  all  up-to-date  decisions  for  targets  built
              through this construction environment will  be  handled  by  the
              specified  _f_u_n_c_t_i_o_n.   The  _f_u_n_c_t_i_o_n can be one of the following
              strings that specify the type of decision function  to  be  per-
              formed:


                 ttiimmeessttaammpp--nneewweerr  Specifies  that a target shall be considered
                       out of date and rebuilt if the  dependency's  timestamp
                       is newer than the target file's timestamp.  This is the
                       behavior of the classic Make utility, and mmaakkee  can  be
                       used a synonym for ttiimmeessttaammpp--nneewweerr.


                 ttiimmeessttaammpp--mmaattcchh  Specifies  that a target shall be considered
                       out of date and rebuilt if the  dependency's  timestamp
                       is  different than the timestamp recorded the last time
                       the target was built.  This provides behavior very sim-
                       ilar  to the classic Make utility (in particular, files
                       are not opened up so that their contents can be  check-
                       summed)  except that the target will also be rebuilt if
                       a dependency file has been restored to a  version  with
                       an _e_a_r_l_i_e_r timestamp, such as can happen when restoring
                       files from backup archives.


                 MMDD55 Specifies that a target shall be considered out  of  date
                       and  rebuilt  if  the  dependency's content has changed
                       sine the last time the target was built, as  determined
                       be  performing an MD5 checksum on the dependency's con-
                       tents and comparing it to  the  checksum  recorded  the
                       last time the target was built.  ccoonntteenntt can be used as
                       a synonym for MMDD55.


                 MMDD55--ttiimmeessttaammpp Specifies that a target shall be considered out
                       of  date  and  rebuilt  if the dependency's content has
                       changed sine the last time the target was built, except
                       that  dependencies  with  a  timestamp that matches the
                       last time the target was rebuilt will be assumed to  be
                       up-to-date  and  _n_o_t  rebuilt.   This provides behavior
                       very similar to the MMDD55 behavior of always checksumming
                       file contents, with an optimization of not checking the
                       contents of files  whose  timestamps  haven't  changed.
                       The  drawback is that SCons will _n_o_t detect if a file's
                       content has changed but its timestamp is the  same,  as
                       might  happen in an automated script that runs a build,
                       updates a file, and runs the build again, all within  a
                       single second.


              Examples:

              # Use exact timestamp matches by default.
              Decider('timestamp-match')

              # Use MD5 content signatures for any targets built
              # with the attached construction environment.
              env.Decider('content')


              In  addition to the above already-available functions, the _f_u_n_c_-
              _t_i_o_n argument may be an actual Python function  that  takes  the
              following three arguments:


                 dependency
                        The  Node  (file)  which should cause the _t_a_r_g_e_t to be
                        rebuilt if it has "changed" since the last tme  _t_a_r_g_e_t
                        _w_a_s _b_u_i_l_t_.


                 target The Node (file) being built.  In the normal case, this
                        is what should  get  rebuilt  if  the  _d_e_p_e_n_d_e_n_c_y  has
                        "changed."


                 prev_ni
                        Stored  information  about the state of the _d_e_p_e_n_d_e_n_c_y
                        the last time the _t_a_r_g_e_t was built.  This can be  con-
                        sulted  to  match various file characteristics such as
                        the timestamp, size, or content signature.


              The _f_u_n_c_t_i_o_n should return a TTrruuee (non-zero) value if the _d_e_p_e_n_-
              _d_e_n_c_y  has  "changed"  since  the last time the _t_a_r_g_e_t was built
              (indicating that the target _s_h_o_u_l_d be rebuilt), and FFaallssee (zero)
              otherwise  (indicating  that  the target should _n_o_t be rebuilt).
              Note that the decision can be made using whatever  criteria  are
              appopriate.   Ignoring  some or all of the function arguments is
              perfectly normal.

              Example:

              def my_decider(dependency, target, prev_ni):
                  return not os.path.exists(str(target))

              env.Decider(my_decider)


       Default(_t_a_r_g_e_t_s)

       env.Default(_t_a_r_g_e_t_s)
              This specifies a list of default targets, which will be built by
              ssccoonnss  if  no  explicit  targets  are given on the command line.
              Multiple calls to DDeeffaauulltt() are legal, and add to  the  list  of
              default targets.

              Multiple  targets  should  be specified as separate arguments to
              the DDeeffaauulltt() method, or as a list.  DDeeffaauulltt() will also  accept
              the Node returned by any of a construction environment's builder
              methods.

              Examples:

              Default('foo', 'bar', 'baz')
              env.Default(['a', 'b', 'c'])
              hello = env.Program('hello', 'hello.c')
              env.Default(hello)

              An argument to DDeeffaauulltt() of NNoonnee will clear all default targets.
              Later  calls  to  DDeeffaauulltt() will add to the (now empty) default-
              target list like normal.

              The current list of targets added using the  DDeeffaauulltt()  function
              or method is available in the DDEEFFAAUULLTT__TTAARRGGEETTSS list; see below.


       DefaultEnvironment([_a_r_g_s])
              Creates  and  returns a default construction environment object.
              This construction environment is used  internally  by  SCons  in
              order  to execute many of the global functions in this list, and
              to fetch source files transparently from source code  management
              systems.


       Depends(_t_a_r_g_e_t, _d_e_p_e_n_d_e_n_c_y)

       env.Depends(_t_a_r_g_e_t, _d_e_p_e_n_d_e_n_c_y)
              Specifies  an  explicit  dependency;  the target file(s) will be
              rebuilt whenever  the  dependency  file(s)  has  changed.   This
              should  only  be necessary for cases where the dependency is not
              caught by a Scanner for the file.

              Example:

              env.Depends('foo', 'other-input-file-for-foo')


       env.Dictionary([_v_a_r_s])
              Returns a dictionary object containing copies of all of the con-
              struction  variables in the environment.  If there are any vari-
              able names specified, only the specified construction  variables
              are returned in the dictionary.

              Example:

              dict = env.Dictionary()
              cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')


       Dir(_n_a_m_e, [_d_i_r_e_c_t_o_r_y])

       env.Dir(_n_a_m_e, [_d_i_r_e_c_t_o_r_y])
              This  returns  a  Directory  Node, an object that represents the
              specified directory _n_a_m_e.  _n_a_m_e can be a  relative  or  absolute
              path.   _d_i_r_e_c_t_o_r_y  is an optional directory that will be used as
              the parent directory.  If no _d_i_r_e_c_t_o_r_y is specified, the current
              script's directory is used as the parent.

              If _n_a_m_e is a list, SCons returns a list of Dir nodes.  Construc-
              tion variables are expanded in _n_a_m_e.

              Directory Nodes can be used anywhere you would supply  a  string
              as  a directory name to a Builder method or function.  Directory
              Nodes have attributes and methods that are useful in many situa-
              tions; see "File and Directory Nodes," below.


       env.Dump([_k_e_y])
              Returns  a  pretty  printable representation of the environment.
              _k_e_y, if not _N_o_n_e, should be a string containing the name of  the
              variable of interest.

              This SConstruct:
              env=Environment()
              print env.Dump('CCCOM')

              will print:

              env=Environment()
              print env.Dump()

              will print:
              { 'AR': 'ar',
                'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES0RANLIB $RANLIBFLAGS $TARGET',
                'ARFLAGS': ['r'],
                'AS': 'as',
                'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
                'ASFLAGS': [],
                ...


       EnsurePythonVersion(_m_a_j_o_r, _m_i_n_o_r)

       env.EnsurePythonVersion(_m_a_j_o_r, _m_i_n_o_r)
              Ensure  that  the  Python version is at least _m_a_j_o_r._m_i_n_o_r.  This
              function will print out an error message and exit SCons  with  a
              non-zero  exit  code  if  the  actual Python version is not late
              enough.

              Example:

              EnsurePythonVersion(2,2)


       EnsureSConsVersion(_m_a_j_o_r, _m_i_n_o_r, [_r_e_v_i_s_i_o_n])

       env.EnsureSConsVersion(_m_a_j_o_r, _m_i_n_o_r, [_r_e_v_i_s_i_o_n])
              Ensure that the  SCons  version  is  at  least  _m_a_j_o_r_._m_i_n_o_r,  or
              _m_a_j_o_r_._m_i_n_o_r_._r_e_v_i_s_i_o_n.   if _r_e_v_i_s_i_o_n is specified.  This function
              will print out an error message and exit SCons with  a  non-zero
              exit code if the actual SCons version is not late enough.

              Examples:

              EnsureSConsVersion(0,14)

              EnsureSConsVersion(0,96,90)


       Environment([_k_e_y=_v_a_l_u_e, ...])

       env.Environment([_k_e_y=_v_a_l_u_e, ...])
              Return a new construction environment initialized with the spec-
              ified _k_e_y=_v_a_l_u_e pairs.


       Execute(_a_c_t_i_o_n, [_s_t_r_f_u_n_c_t_i_o_n, _v_a_r_l_i_s_t])

       env.Execute(_a_c_t_i_o_n, [_s_t_r_f_u_n_c_t_i_o_n, _v_a_r_l_i_s_t])
              Executes an Action object.   The  specified  _a_c_t_i_o_n  may  be  an
              Action  object  (see  the section "Action Objects," below, for a
              complete explanation of the arguments and behavior), or  it  may
              be a command-line string, list of commands, or executable Python
              function, each of which will be converted into an Action  object
              and  then  executed.   The  exit  value of the command or return
              value of the Python function will be returned.


       Exit([_v_a_l_u_e])

       env.Exit([_v_a_l_u_e])
              This tells ssccoonnss to exit immediately with the  specified  _v_a_l_u_e.
              A  default  exit value of 00 (zero) is used if no value is speci-
              fied.


       Export(_v_a_r_s)

       env.Export(_v_a_r_s)
              This tells ssccoonnss to export a list of variables from the  current
              SConscript  file  to  all  other SConscript files.  The exported
              variables are kept in a global collection, so  subsequent  calls
              to  EExxppoorrtt() will over-write previous exports that have the same
              name.  Multiple variable names can be passed to EExxppoorrtt() as sep-
              arate  arguments  or  as a list. A dictionary can be used to map
              variables to a different name when exported.  Both  local  vari-
              ables and global variables can be exported.

              Examples:

              env = Environment()
              # Make env available for all SConscript files to Import().
              Export("env")

              package = 'my_name'
              # Make env and package available for all SConscript files:.
              Export("env", "package")

              # Make env and package available for all SConscript files:
              Export(["env", "package"])

              # Make env available using the name debug:.
              Export({"debug":env})


              Note that the SSCCoonnssccrriipptt() function supports an _e_x_p_o_r_t_s argument
              that makes it easier to to export a variable or set of variables
              to  a  single SConscript file.  See the description of the SSCCoonn--
              ssccrriipptt() function, below.


       File(_n_a_m_e, [_d_i_r_e_c_t_o_r_y])

       env.File(_n_a_m_e, [_d_i_r_e_c_t_o_r_y])
              This returns a File Node, an object that represents  the  speci-
              fied  file  _n_a_m_e.   _n_a_m_e  can  be  a  relative or absolute path.
              _d_i_r_e_c_t_o_r_y is an optional directory that will be used as the par-
              ent directory.

              If  _n_a_m_e  is  a  list, SCons returns a list of File nodes.  Con-
              struction variables are expanded in _n_a_m_e.

              File Nodes can be used anywhere you would supply a string  as  a
              file  name  to  a  Builder  method or function.  File Nodes have
              attributes and methods that are useful in many  situations;  see
              "File and Directory Nodes," below.


       FindFile(_f_i_l_e, _d_i_r_s)

       env.FindFile(_f_i_l_e, _d_i_r_s)
              Search  for  _f_i_l_e  in the path specified by _d_i_r_s.  _f_i_l_e may be a
              list of file names or a single file name. In addition to search-
              ing  for  files  that exist in the filesytem, this function also
              searches for derived files that have not yet been built.

              Example:

              foo = env.FindFile('foo', ['dir1', 'dir2'])


       FindInstalledFiles(_)

       env.FindInstalledFiles(_)
              Returns the list of targets set up by the IInnssttaallll(())  or  IInnssttaall--
              llAAss(()) builders.

              This  function  serves as a convenient method to select the con-
              tents of a binary package.

              Example:

              Install( '/bin', [ 'executable_a', 'executable_b' ] )

              # will return the file node list
              # [ '/bin/executable_a', '/bin/executable_b' ]
              FindInstalledFiles()

              Install( '/lib', [ 'some_library' ] )

              # will return the file node list
              # [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
              FindInstalledFiles()


       FindSourceFiles(_n_o_d_e=_'_"_._"_')

       env.FindSourceFiles(_n_o_d_e=_'_"_._"_')

              Returns the list of nodes which serve as the source of the built
              files.  It does so by inspecting the dependency tree starting at
              the optional argument nnooddee which defaults to the '"."'-node.  It
              will  then  return  all  leaves of nnooddee..  These are all children
              which have no further children.

              This function is a convenient method to select the contents of a
              Source Package.

              Example:

              Program( 'src/main_a.c' )
              Program( 'src/main_b.c' )
              Program( 'main_c.c' )

              # returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
              FindSourceFiles()

              # returns ['src/main_b.c', 'src/main_a.c' ]
              FindSourceFiles( 'src' )


              As  you  can  see  build  support files (SConstruct in the above
              example) will also be returned by this function.


       FindPathDirs(_v_a_r_i_a_b_l_e)
              Returns a function (actually a callable Python object)  intended
              to  be  used  as  the  ppaatthh__ffuunnccttiioonn  of  a Scanner object.  The
              returned object will look up the specified _v_a_r_i_a_b_l_e  in  a  con-
              struction  environment  and  treat  the  construction variable's
              value as a list of directory paths that should be searched (like
              CCPPPPPPAATTHH, LLIIBBPPAATTHH, etc.).

              Note that use of FFiinnddPPaatthhDDiirrss() is generally preferable to writ-
              ing your own ppaatthh__ffuunnccttiioonn for the  following  reasons:  1)  The
              returned  list will contain all appropriate directories found in
              source trees (when VVaarriiaannttDDiirr() is used) or in code repositories
              (when  RReeppoossiittoorryy()  or  the --YY option are used).  2) scons will
              identify expansions of _v_a_r_i_a_b_l_e that evaluate to the  same  list
              of directories as, in fact, the same list, and avoid re-scanning
              the directories for files, when possible.

              Example:

              def my_scan(node, env, path, arg):
                  # Code to scan file contents goes here...
                  return include_files

              scanner = Scanner(name = 'myscanner',
                                function = my_scan,
                                path_function = FindPathDirs('MYPATH'))


       Flatten(_s_e_q_u_e_n_c_e)

       env.Flatten(_s_e_q_u_e_n_c_e)
              Takes a sequence (that is, a Python list or tuple) that may con-
              tain  nested  sequences  and returns a flattened list containing
              all of the individual elements in any  sequence.   This  can  be
              helpful  for collecting the lists returned by calls to Builders;
              other Builders will automatically  flatten  lists  specified  as
              input, but direct Python manipulation of these lists does not.

              Examples:

              foo = Object('foo.c')
              bar = Object('bar.c')

              # Because `foo' and `bar' are lists returned by the Object() Builder,
              # `objects' will be a list containing nested lists:
              objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']

              # Passing such a list to another Builder is all right because
              # the Builder will flatten the list automatically:
              Program(source = objects)

              # If you need to manipulate the list directly using Python, you need to
              # call Flatten() yourself, or otherwise handle nested lists:
              for object in Flatten(objects):
                  print str(object)


       GetBuildFailures()
              Returns  a  list of exceptions for the actions that failed while
              attempting to build targets.  Each element in the returned  list
              is a BBuuiillddEErrrroorr object with the following attributes that record
              various aspects of the build failure:

              ..nnooddee The node that was  being  built  when  the  build  failure
              occurred.

              ..ssttaattuuss  The  numeric  exit  status  returned  by the command or
              Python function that failed when trying to build  the  specified
              Node.

              ..eerrrrssttrr  The  SCons  error  string describing the build failure.
              (This is often a generic message like "Error 2" to indicate that
              an executed command exited with a status of 2.)

              ..ffiilleennaammee The name of the file or directory that actually caused
              the failure.  This may be different from  the  ..nnooddee  attribute.
              For  example, if an attempt to build a target named ssuubb//ddiirr//ttaarr--
              ggeett fails because the ssuubb//ddiirr directory could  not  be  created,
              then  the  ..nnooddee attribute will be ssuubb//ddiirr//ttaarrggeett but the ..ffiillee--
              nnaammee attribute will be ssuubb//ddiirr.

              ..eexxeeccuuttoorr The SCons Executor object for the  target  Node  being
              built.   This  can be used to retrieve the construction environ-
              ment used for the failed action.

              ..aaccttiioonn The actual SCons Action object that failed.   This  will
              be  one specific action out of the possible list of actions that
              would have been executed to build the target.

              ..ccoommmmaanndd The actual  expanded  command  that  was  executed  and
              failed, after expansion of $$TTAARRGGEETT, $$SSOOUURRCCEE, and other construc-
              tion variables.

              Note that the GGeettBBuuiillddFFaaiilluurreess() function will always return  an
              empty  list  until  any  build failure has occurred, which means
              that GGeettBBuuiillddFFaaiilluurreess() will always return an empty  list  while
              the  SSCCoonnssccrriipptt  files are being read.  Its primary intended use
              is for functions that will be executed  before  SCons  exits  by
              passing  them to the standard Python aatteexxiitt..rreeggiisstteerr() function.
              Example:

              import atexit

              def print_build_failures():
                  from SCons.Script import GetBuildFailures
                  for bf in GetBuildFailures():
                      print "%s failed: %s" % (bf.node, bf.errstr)

              atexit.register(print_build_failures)


       GetBuildPath(_f_i_l_e, [_._._.])

       env.GetBuildPath(_f_i_l_e, [_._._.])
              Returns the ssccoonnss path name (or names) for  the  specified  _f_i_l_e
              (or  files).   The specified _f_i_l_e or files may be ssccoonnss Nodes or
              strings representing path names.


       GetLaunchDir()

       env.GetLaunchDir()
              Returns the absolute path name of the directory from which ssccoonnss
              was initially invoked.  This can be useful when using the --uu, --UU
              or --DD options, which internally change to the directory in which
              the SSCCoonnssttrruucctt file is found.


       GetOption(_n_a_m_e)

       env.GetOption(_n_a_m_e)
              This function provides a way to query the value of SCons options
              set on scons command line (or set using  the  _S_e_t_O_p_t_i_o_n()  func-
              tion).  The options supported are:


                 ccaacchhee__ddeebbuugg

                 which corresponds to --cache_debug;

                 ccaacchhee__ddiissaabbllee
                       which corresponds to --cache_disable;

                 ccaacchhee__ffoorrccee
                       which corresponds to --cache_force;

                 ccaacchhee__sshhooww
                       which corresponds to --cache_show;

                 cclleeaann which corresponds to -c, --clean and --remove;

                 ccoonnffiigg
                       which corresponds to --config;

                 ddiirreeccttoorryy
                       which corresponds to -C and --directory;

                 ddiisskkcchheecckk
                       which corresponds to --diskcheck

                 dduupplliiccaattee
                       which corresponds to --duplicate;

                 ffiillee  which corresponds to -f, --file, --makefile and --scon-
                       struct;

                 hheellpp  which corresponds to -h and --help;

                 iiggnnoorree__eerrrroorrss
                       which corresponds to --ignore-errors;

                 iimmpplliicciitt__ccaacchhee
                       which corresponds to --implicit-cache;

                 iimmpplliicciitt__ddeeppss__cchhaannggeedd
                       which corresponds to --implicit-deps-changed;

                 iimmpplliicciitt__ddeeppss__uunncchhaannggeedd
                       which corresponds to --implicit-deps-unchanged;

                 iinntteerraaccttiivvee
                       which corresponds to --interact and --interactive;

                 kkeeeepp__ggooiinngg
                       which corresponds to -k and --keep-going;

                 mmaaxx__ddrriifftt
                       which corresponds to --max-drift;

                 nnoo__eexxeecc
                       which  corresponds  to  -n,  --no-exec,   --just-print,
                       --dry-run and --recon;

                 nnoo__ssiittee__ddiirr
                       which corresponds to --no-site-dir;

                 nnuumm__jjoobbss
                       which corresponds to -j and --jobs;

                 pprrooffiillee__ffiillee
                       which corresponds to --profile;

                 qquueessttiioonn
                       which corresponds to -q and --question;

                 rraannddoomm
                       which corresponds to --random;

                 rreeppoossiittoorryy
                       which corresponds to -Y, --repository and --srcdir;

                 ssiilleenntt
                       which corresponds to -s, --silent and --quiet;

                 ssiittee__ddiirr
                       which corresponds to --site-dir;

                 ssttaacckk__ssiizzee
                       which corresponds to --stack-size;

                 ttaasskkmmaasstteerrttrraaccee__ffiillee
                       which corresponds to --taskmastertrace; and

                 wwaarrnn  which corresponds to --warn and --warning.


              See  the documentation for the corresponding command line object
              for information about each specific option.


       Glob(_p_a_t_t_e_r_n, [_o_n_d_i_s_k, _s_o_u_r_c_e, _s_t_r_i_n_g_s])

       env.Glob(_p_a_t_t_e_r_n, [_o_n_d_i_s_k, _s_o_u_r_c_e, _s_t_r_i_n_g_s])
              Returns Nodes (or strings) that  match  the  specified  _p_a_t_t_e_r_n,
              relative  to  the directory of the current SSCCoonnssccrriipptt file.  The
              eennvv..GGlloobb()  form  performs  string  substition  on  _p_a_t_t_e_r_n  and
              returns whatever matches the resulting expanded pattern.

              The  specified  _p_a_t_t_e_r_n uses Unix shell style metacharacters for
              matching:

                *       matches everything
                ?       matches any single character
                [seq]   matches any character in seq
                [!seq]  matches any char not in seq


              Character matches do _n_o_t span directory separators.

              The GGlloobb() knows about repositories (see the RReeppoossiittoorryy()  func-
              tion) and source directories (see the VVaarriiaannttDDiirr() function) and
              returns a Node (or string, if so configured) in the local (SCon-
              script) directory if matching Node is found anywhere in a corre-
              sponding repository or source directory.

              The oonnddiisskk argument may be set to FFaallssee (or any  other  non-true
              value)  to  disable the search for matches on disk, thereby only
              returning matches among already-configured File  or  Dir  Nodes.
              The  default  behavior  is to return corresponding Nodes for any
              on-disk matches found.

              The ssoouurrccee argument may be set to TTrruuee (or any equivalent value)
              to specify that, when the local directory is a VVaarriiaannttDDiirr(), the
              returned Nodes should be from the  corresponding  source  direc-
              tory, not the local directory.

              The  ssttrriinnggss  argument  may  be  set  to TTrruuee (or any equivalent
              value) to have the GGlloobb() function return  strings,  not  Nodes,
              that  represent  the matched files or directories.  The returned
              strings will be relative to the  local  (SConscript)  directory.
              (Note  that This may make it easier to perform arbitrary manipu-
              lation of file names, but if the returned strings are passed  to
              a  different SSCCoonnssccrriipptt file, any Node translation will be rela-
              tive to the other SSCCoonnssccrriipptt directory, not the  original  SSCCoonn--
              ssccrriipptt directory.)

              Example:

              Program('foo', Glob('*.c'))



       Help(_t_e_x_t)

       env.Help(_t_e_x_t)
              This  specifies  help  text  to be printed if the --hh argument is
              given to ssccoonnss.  If HHeellpp is called multiple times, the  text  is
              appended together in the order that HHeellpp is called.


       Ignore(_t_a_r_g_e_t, _d_e_p_e_n_d_e_n_c_y)

       env.Ignore(_t_a_r_g_e_t, _d_e_p_e_n_d_e_n_c_y)
              The  specified  dependency file(s) will be ignored when deciding
              if the target file(s) need to be rebuilt.

              Examples:

              env.Ignore('foo', 'foo.c')
              env.Ignore('bar', ['bar1.h', 'bar2.h'])


       Import(_v_a_r_s)

       env.Import(_v_a_r_s)
              This tells ssccoonnss to import a list of variables into the  current
              SConscript  file.  This will import variables that were exported
              with EExxppoorrtt() or in the _e_x_p_o_r_t_s argument to SSCCoonnssccrriipptt().  Vari-
              ables  exported by SSCCoonnssccrriipptt() have precedence.  Multiple vari-
              able names can be passed to IImmppoorrtt() as separate arguments or as
              a list. The variable "*" can be used to import all variables.

              Examples:

              Import("env")
              Import("env", "variable")
              Import(["env", "variable"])
              Import("*")


       Literal(_s_t_r_i_n_g)

       env.Literal(_s_t_r_i_n_g)
              The  specified  _s_t_r_i_n_g will be preserved as-is and not have con-
              struction variables expanded.


       Local(_t_a_r_g_e_t_s)

       env.Local(_t_a_r_g_e_t_s)
              The specified _t_a_r_g_e_t_s will have copies made in the  local  tree,
              even  if  an  already  up-to-date  copy  exists in a repository.
              Returns a list of the target Node or Nodes.


       env.MergeFlags(_a_r_g, [_u_n_i_q_u_e])
              Merges the specified _a_r_g values  to  the  construction  envrion-
              ment's  construction  variables.   If  the _a_r_g argument is not a
              dictionary, it is converted to one by  calling  eennvv..PPaarrsseeFFllaaggss(())
              on  the  argument  before  the values are merged.  Note that _a_r_g
              must be a single value, so multiple strings must be passed in as
              a list, not as separate arguments to eennvv..MMeerrggeeFFllaaggss().

              By  default,  duplicate values are eliminated; you can, however,
              specify uunniiqquuee==00 to allow duplicate values to  be  added.   When
              eliminating  duplicate  values,  any construction variables that
              end with the string PPAATTHH keep the left-most unique  value.   All
              other construction variables keep the right-most unique value.

              Examples:

              # Add an optimization flag to $CCFLAGS.
              env.MergeFlags('-O3')

              # Combine the flags returned from running pkg-config with an optimization
              # flag and merge the result into the construction variables.
              env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])

              # Combine an optimization flag with the flags returned from running pkg-config
              # twice and merge the result into the construction variables.
              env.MergeFlags(['-O3',
                             '!pkg-config gtk+-2.0 --cflags --libs',
                             '!pkg-config libpng12 --cflags --libs'])


       NoCache(_t_a_r_g_e_t, ...)

       env.NoCache(_t_a_r_g_e_t, ...)
              Specifies  a  list  of files which should _n_o_t be cached whenever
              the CCaacchheeDDiirr() method has been activated.  The specified targets
              may be a list or an individual target.

              Multiple  files should be specified either as separate arguments
              to the NNooCCaacchhee() method, or as  a  list.   NNooCCaacchhee()  will  also
              accept  the  return value of any of the construction environment
              Builder methods.

              Calling NNooCCaacchhee() on directories and other non-File  Node  types
              has no effect because only File Nodes are cached.

              Examples:

              NoCache('foo.elf')
              NoCache(env.Program('hello', 'hello.c'))


       NoClean(_t_a_r_g_e_t, ...)

       env.NoClean(_t_a_r_g_e_t, ...)
              Specifies  a  list  of  files or directories which should _n_o_t be
              removed whenever the targets (or their dependencies) are  speci-
              fied with the --cc command line option.  The specified targets may
              be a list or an individual target.  Multiple calls to  NNooCClleeaann()
              are  legal, and prevent each specified target from being removed
              by calls to the --cc option.

              Multiple files or directories should be specified either as sep-
              arate   arguments  to  the  NNooCClleeaann()  method,  or  as  a  list.
              NNooCClleeaann() will also accept the return value of any of  the  con-
              struction environment Builder methods.

              Calling NNooCClleeaann() for a target overrides calling CClleeaann() for the
              same target, and any targets passed to both functions  will  _n_o_t
              be removed by the --cc option.

              Examples:

              NoClean('foo.elf')
              NoClean(env.Program('hello', 'hello.c'))


       env.ParseConfig(_c_o_m_m_a_n_d, [_f_u_n_c_t_i_o_n, _u_n_i_q_u_e])
              Calls the specified _f_u_n_c_t_i_o_n to modify the environment as speci-
              fied by the  output  of  _c_o_m_m_a_n_d  _.   The  default  _f_u_n_c_t_i_o_n  is
              eennvv..MMeerrggeeFFllaaggss(), which expects the output of a typical _*_-_c_o_n_f_i_g
              _c_o_m_m_a_n_d (for example, ggttkk--ccoonnffiigg) and adds the  options  to  the
              appropriate  construction variables.  By default, duplicate val-
              ues are not added to any construction variables; you can specify
              uunniiqquuee==00 to allow duplicate values to be added.

              Interpreted  options  and the construction variables they affect
              are as specified for the  eennvv..PPaarrsseeFFllaaggss()  method  (which  thie
              method  calls).   See  that  method's  description, below, for a
              table of options and construction variables.


       ParseDepends(_f_i_l_e_n_a_m_e, [_m_u_s_t___e_x_i_s_t, _o_n_l_y___o_n_e])

       env.ParseDepends(_f_i_l_e_n_a_m_e, [_m_u_s_t___e_x_i_s_t, _o_n_l_y___o_n_e])
              Parses the contents of the  specified  _f_i_l_e_n_a_m_e  as  a  list  of
              dependencies  in  the  style  of  MMaakkee  or mmkkddeepp, and explicitly
              establishes all of the listed dependencies.

              By default, it is not an error if the  specified  _f_i_l_e_n_a_m_e  does
              not  exist.   The  optional  _m_u_s_t___e_x_i_s_t argument may be set to a
              non-zero value to have scons throw an exception and generate  an
              error  if the file does not exist, or is otherwise inaccessible.

              The optional _o_n_l_y___o_n_e argument may be set to a non-zero value to
              have scons thrown an exception and generate an error if the file
              contains dependency information for more than one target.   This
              can provide a small sanity check for files intended to be gener-
              ated by, for example, the ggcccc --MM flag,  which  should  typically
              only  write  dependency  information  for one output file into a
              corresponding ..dd file.

              The _f_i_l_e_n_a_m_e and all of the files listed therein will be  inter-
              preted  relative  to  the directory of the _S_C_o_n_s_c_r_i_p_t file which
              calls the PPaarrsseeDDeeppeennddss function.


       env.ParseFlags(_f_l_a_g_s, ...)
              Parses one or more strings containing typical command-line flags
              for  GCC tool chains and returns a dictionary with the flag val-
              ues separated into the appropriate SCons construction variables.
              This  is intended as a companion to the eennvv..MMeerrggeeFFllaaggss() method,
              but allows for the values in the returned dictionary to be modi-
              fied,  if  necessary,  before merging them into the construction
              environment.  (Note that eennvv..MMeerrggeeFFllaaggss() will call this  method
              if its argument is not a dictionary, so it is usually not neces-
              sary to call eennvv..PPaarrsseeFFllaaggss() directly unless you want to manip-
              ulate the values.)

              If the first character in any string is an exclamation mark (!),
              the rest of the string is executed as a command, and the  output
              from  the command is parsed as GCC tool chain command-line flags
              and added to the resulting dictionary.

              Flag values are translated accordig to  the  prefix  found,  and
              added to the following construction variables:

              -arch               CCFLAGS, LINKFLAGS
              -D                  CPPDEFINES
              -framework          FRAMEWORKS
              -frameworkdir=      FRAMEWORKPATH
              -include            CCFLAGS
              -isysroot           CCFLAGS, LINKFLAGS
              -I                  CPPPATH
              -l                  LIBS
              -L                  LIBPATH
              -mno-cygwin         CCFLAGS, LINKFLAGS
              -mwindows           LINKFLAGS
              -pthread            CCFLAGS, LINKFLAGS
              -std=               CFLAGS
              -Wa,                ASFLAGS, CCFLAGS
              -Wl,-rpath=         RPATH
              -Wl,-R,             RPATH
              -Wl,-R              RPATH
              -Wl,                LINKFLAGS
              -Wp,                CPPFLAGS
              -                   CCFLAGS
              +                   CCFLAGS, LINKFLAGS


              Any  other strings not associated with options are assumed to be
              the names of libraries and added to the LLIIBBSS construction  vari-
              able.

              Examples (all of which produce the same result):

              dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
              dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
              dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
              dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')


       env.Perforce()
              A  factory  function that returns a Builder object to be used to
              fetch source files from the Perforce source code management sys-
              tem.   The  returned  Builder  is  intended  to be passed to the
              SSoouurrcceeCCooddee function.

              Example:

              env.SourceCode('.', env.Perforce())

              Perforce uses a number of external environment variables for its
              operation.  Consequently, this function adds the following vari-
              ables from the user's external environment to  the  construction
              environment's  ENV  dictionary: P4CHARSET, P4CLIENT, P4LANGUAGE,
              P4PASSWD, P4PORT, P4USER, SYSTEMROOT, USER, and USERNAME.


       Platform(_s_t_r_i_n_g)
              Returns a callable object that can be used to initialize a  con-
              struction environment using the platform keyword of the Environ-
              ment() method.

              Example:

              env = Environment(platform = Platform('win32'))

       env.Platform(_s_t_r_i_n_g)
              Applies the callable object for the specified platform _s_t_r_i_n_g to
              the environment through which the method was called.

              env.Platform('posix')

              Note that the wwiinn3322 platform adds the SSYYSSTTEEMMDDRRIIVVEE and SSYYSSTTEEMMRROOOOTT
              variables from the user's external environment to the  construc-
              tion environment's EENNVV dictionary.  This is so that any executed
              commands that use sockets to connect with other systems (such as
              fetching  source  files  from external CVS repository specifica-
              tions     like      ::ppsseerrvveerr::aannoonnyymmoouuss@@ccvvss..ssoouurrcceeffoorrggee..nneett:://ccvvss--
              rroooott//ssccoonnss) will work on Windows systems.


       Progress(_c_a_l_l_a_b_l_e, [_i_n_t_e_r_v_a_l])

       Progress(_s_t_r_i_n_g, [_i_n_t_e_r_v_a_l, _f_i_l_e, _o_v_e_r_w_r_i_t_e])

       Progress(_l_i_s_t___o_f___s_t_r_i_n_g_s, [_i_n_t_e_r_v_a_l, _f_i_l_e, _o_v_e_r_w_r_i_t_e])
              Allows  SCons to show progress made during the build by display-
              ing a string or calling a function while evaluating Nodes  (e.g.
              files).

              If the first specified argument is a Python callable (a function
              or an object that has a ____ccaallll____() method), the function will be
              called  once  every  _i_n_t_e_r_v_a_l  times  a  Node is evaluated.  The
              callable will be passed the evaluated Node as its only argument.
              (For  future  compatibility,  it's a good idea to also add **aarrggss
              and ****kkww as arguments to your function  or  method.   This  will
              prevent  the code from breaking if SCons ever changes the inter-
              face to call the  function  with  additional  arguments  in  the
              future.)

              An  example  of  a simple custom progress function that prints a
              string containing the Node name every 10 Nodes:

              def my_progress_function(node, *args, **kw):
                  print 'Evaluating node %s!' % node
              Progress(my_progress_function, interval=10)

              A more complicated example of a custom progress  display  object
              that  prints  a  string  containing  a count every 100 evaluated
              Nodes.  Note the use of \\rr (a carriage return)  at  the  end  so
              that the string will overwrite itself on a display:

              import sys
              class ProgressCounter:
                  count = 0
                  def __call__(self, node, *args, **kw):
                      self.count += 100
                      sys.stderr.write('Evaluated %s nodes\r' % self.count)
              Progress(ProgressCounter(), interval=100)

              If the first argument PPrrooggrreessss() is a string, the string will be
              displayed every _i_n_t_e_r_v_a_l evaluated Nodes.   The  default  is  to
              print  the string on standard output; an alternate output stream
              may be specified with the ffiillee== argument.   The  following  will
              print  a  series  of dots on the error output, one dot for every
              100 evaluated Nodes:

              import sys
              Progress('.', interval=100, file=sys.stderr)

              If the string contains the verbatim substring $$TTAARRGGEETT,,  it  will
              be  replaced with the Node.  Note that, for performance reasons,
              this is _n_o_t a regular SCons variable substition, so you can  not
              use  other variables or use curly braces.  The following example
              will print the name of every evaluated Node, using  a  \\rr  (car-
              riage  return)  to  cause  each  line to overwritten by the next
              line, and the oovveerrwwrriittee== keyword argument to make sure the  pre-
              viously-printed file name is overwritten with blank spaces:

              import sys
              Progress('$TARGET\r', overwrite=True)

              If  the  first argument to PPrrooggrreessss() is a list of strings, then
              each string in the list will be displayed  in  rotating  fashion
              every _i_n_t_e_r_v_a_l evaluated Nodes.  This can be used to implement a
              "spinner" on the user's screen as follows:

              Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)


       Precious(_t_a_r_g_e_t, ...)

       env.Precious(_t_a_r_g_e_t, ...)
              Marks each given _t_a_r_g_e_t as precious so it is not deleted  before
              it  is  rebuilt. Normally ssccoonnss deletes a target before building
              it.  Multiple targets can be passed in to a single call to  PPrree--
              cciioouuss().


       env.Prepend(_k_e_y=_v_a_l, [...])
              Appends the specified keyword arguments to the beginning of con-
              struction variables in the environment.  If the Environment does
              not have the specified construction variable, it is simply added
              to the environment.  If the values of the construction  variable
              and  the keyword argument are the same type, then the two values
              will be simply  added  together.   Otherwise,  the  construction
              variable  and the value of the keyword argument are both coerced
              to lists, and the lists  are  added  together.   (See  also  the
              Append method, above.)

              Example:

              env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])


       env.PrependENVPath(_n_a_m_e, _n_e_w_p_a_t_h, [_e_n_v_n_a_m_e, _s_e_p])
              This  appends  new path elements to the given path in the speci-
              fied external environment (EENNVV by default).  This will only  add
              any  particular  path  once (leaving the first one it encounters
              and ignoring the rest, to preserve  path  order),  and  to  help
              assure  this,  will  normalize all paths (using ooss..ppaatthh..nnoorrmmppaatthh
              and ooss..ppaatthh..nnoorrmmccaassee).  This can also handle the case where  the
              given  old path variable is a list instead of a string, in which
              case a list will be returned instead of a string.

              Example:

              print 'before:',env['ENV']['INCLUDE']
              include_path = '/foo/bar:/foo'
              env.PrependENVPath('INCLUDE', include_path)
              print 'after:',env['ENV']['INCLUDE']

       The above exmaple will print:

              before: /biz:/foo
              after: /foo/bar:/foo:/biz


       env.PrependUnique(_k_e_y=_v_a_l, [...])
              Appends the specified keyword arguments to the beginning of con-
              struction variables in the environment.  If the Environment does
              not have the specified construction variable, it is simply added
              to the environment.  If the construction variable being appended
              to is a list, then any value(s) that already exist in  the  con-
              struction variable will _n_o_t be added again to the list.

              Example:

              env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])


       env.RCS()
              A  factory  function that returns a Builder object to be used to
              fetch source files from RCS.  The returned Builder  is  intended
              to be passed to the SSoouurrcceeCCooddee function:

              Examples:

              env.SourceCode('.', env.RCS())

              Note  that ssccoonnss will fetch source files from RCS subdirectories
              automatically, so configuring RCS as demonstrated in  the  above
              example  should only be necessary if you are fetching from RCS,v
              files in the same directory as the source files, or if you  need
              to explicitly specify RCS for a specific subdirectory.


       env.Replace(_k_e_y=_v_a_l, [...])
              Replaces  construction  variables  in  the  Environment with the
              specified keyword arguments.

              Example:

              env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')


       Repository(_d_i_r_e_c_t_o_r_y)

       env.Repository(_d_i_r_e_c_t_o_r_y)
              Specifies that _d_i_r_e_c_t_o_r_y is a  repository  to  be  searched  for
              files.   Multiple  calls to RReeppoossiittoorryy() are legal, and each one
              adds to the list of repositories that will be searched.

              To ssccoonnss, a repository is a copy of the source  tree,  from  the
              top-level directory on down, which may contain both source files
              and derived files that can be used to build targets in the local
              source  tree.  The canonical example would be an official source
              tree maintained by an integrator.  If  the  repository  contains
              derived  files,  then  the  derived files should have been built
              using ssccoonnss, so that the repository contains the necessary  sig-
              nature  information  to  allow  ssccoonnss  to  figure out when it is
              appropriate to use  the  repository  copy  of  a  derived  file,
              instead of building one locally.

              Note  that  if  an  up-to-date  derived file already exists in a
              repository, ssccoonnss will _n_o_t make a copy in  the  local  directory
              tree.  In order to guarantee that a local copy will be made, use
              the LLooccaall(()) method.


       Requires(_t_a_r_g_e_t, _p_r_e_r_e_q_u_i_s_i_t_e)

       env.Requires(_t_a_r_g_e_t, _p_r_e_r_e_q_u_i_s_i_t_e)
              Specifies an order-only relationship between the specified  tar-
              get file(s) and the specified prerequisite file(s).  The prereq-
              uisite file(s) will be (re)built, if necessary, _b_e_f_o_r_e the  tar-
              get  file(s),  but  the target file(s) do not actually depend on
              the prerequisites and will not be  rebuilt  simply  because  the
              prerequisite file(s) change.

              Example:

              env.Requires('foo', 'file-that-must-be-built-before-foo')


       Return([_v_a_r_s... , _s_t_o_p_=])
              By  default,  this  stops processing the current SConscript file
              and returns to the calling SConscript file  the  values  of  the
              variables  named in the _v_a_r_s string arguments.  Multiple strings
              contaning variable names may be passed to RReettuurrnn().  Any strings
              that contain white space

              The  optional ssttoopp== keyword argument may be set to a false value
              to continue processing the rest of the SConscript file after the
              RReettuurrnn()  call.   This  was  the default behavior prior to SCons
              0.98.  However, the values returned are still the values of  the
              variables in the named _v_a_r_s at the point RReettuurrnn() is called.

              Examples:

              # Returns without returning a value.
              Return()

              # Returns the value of the 'foo' Python variable.
              Return("foo")

              # Returns the values of the Python variables 'foo' and 'bar'.
              Return("foo", "bar")

              # Returns the values of Python variables 'val1' and 'val2'.
              Return('val1 val2')


       Scanner(_f_u_n_c_t_i_o_n, [_a_r_g_u_m_e_n_t, _k_e_y_s, _p_a_t_h___f_u_n_c_t_i_o_n, _n_o_d_e___c_l_a_s_s, _n_o_d_e___f_a_c_-
       _t_o_r_y, _s_c_a_n___c_h_e_c_k, _r_e_c_u_r_s_i_v_e])

       env.Scanner(_f_u_n_c_t_i_o_n,   [_a_r_g_u_m_e_n_t,   _k_e_y_s,  _p_a_t_h___f_u_n_c_t_i_o_n,  _n_o_d_e___c_l_a_s_s,
       _n_o_d_e___f_a_c_t_o_r_y, _s_c_a_n___c_h_e_c_k, _r_e_c_u_r_s_i_v_e])
              Creates  a  Scanner  object for the specified _f_u_n_c_t_i_o_n.  See the
              section "Scanner Objects," below, for a complete explanation  of
              the arguments and behavior.


       env.SCCS()
              A  factory  function that returns a Builder object to be used to
              fetch source files from SCCS.  The returned Builder is  intended
              to be passed to the SSoouurrcceeCCooddee function.

              Example:

              env.SourceCode('.', env.SCCS())

              Note that ssccoonnss will fetch source files from SCCS subdirectories
              automatically, so configuring SCCS as demonstrated in the  above
              example should only be necessary if you are fetching from _s_._S_C_C_S
              files in the same directory as the source files, or if you  need
              to explicitly specify SCCS for a specific subdirectory.


       SConscript(_s_c_r_i_p_t_s, [_e_x_p_o_r_t_s, _v_a_r_i_a_n_t___d_i_r, _s_r_c___d_i_r, _d_u_p_l_i_c_a_t_e])

       env.SConscript(_s_c_r_i_p_t_s, [_e_x_p_o_r_t_s, _v_a_r_i_a_n_t___d_i_r, _s_r_c___d_i_r, _d_u_p_l_i_c_a_t_e])

       SConscript(dirs=_s_u_b_d_i_r_s,  [name=_s_c_r_i_p_t,  _e_x_p_o_r_t_s, _v_a_r_i_a_n_t___d_i_r, _s_r_c___d_i_r,
       _d_u_p_l_i_c_a_t_e])

       env.SConscript(dirs=_s_u_b_d_i_r_s,    [name=_s_c_r_i_p_t,   _e_x_p_o_r_t_s,   _v_a_r_i_a_n_t___d_i_r,
       _s_r_c___d_i_r, _d_u_p_l_i_c_a_t_e])
              This  tells  ssccoonnss  to execute one or more subsidiary SConscript
              (configuration) files.  There are two ways  to  call  the  SSCCoonn--
              ssccrriipptt() function.

              The first way you can call SSCCoonnssccrriipptt() is to explicitly specify
              one or more _s_c_r_i_p_t_s as the first argument.  A single script  may
              be  specified as a string; multiple scripts must be specified as
              a list (either explicitly or  as  created  by  a  function  like
              SSpplliitt()).

              The second way you can call SSCCoonnssccrriipptt() is to specify a list of
              (sub)directory names as a  dirs=_s_u_b_d_i_r_s  keyword  argument.   In
              this case, ssccoonnss will, by default, execute a subsidiary configu-
              ration file named SSCCoonnssccrriipptt in each of the  specified  directo-
              ries.  You may specify a name other than SSCCoonnssccrriipptt by supplying
              an optional name=_s_c_r_i_p_t keyword argument.

              The optional _e_x_p_o_r_t_s argument provides a list of variable  names
              or  a  dictionary  of  named  values to export to the _s_c_r_i_p_t_(_s_).
              These variables are  locally  exported  only  to  the  specified
              _s_c_r_i_p_t_(_s_),  and  do not affect the global pool of variables used
              by the EExxppoorrtt() function.  The subsidiary _s_c_r_i_p_t_(_s_) must use the
              IImmppoorrtt() function to import the variables.

              The optional _v_a_r_i_a_n_t___d_i_r argument specifies that all of the tar-
              get files (for example, object files and executables) that would
              normally  be  built  in the subdirectory in which _s_c_r_i_p_t resides
              should actually be built in _v_a_r_i_a_n_t___d_i_r.  _v_a_r_i_a_n_t___d_i_r is  inter-
              preted relative to the directory of the calling SConscript file.

              The optional _s_r_c___d_i_r argument specifies that  the  source  files
              from  which  the  target  files  should be built can be found in
              _s_r_c___d_i_r.  _s_r_c___d_i_r is interpreted relative to  the  directory  of
              the calling SConscript file.

              By  default, ssccoonnss will link or copy (depending on the platform)
              all the source files into  the  variant  directory  tree.   This
              behavior may be disabled by setting the optional _d_u_p_l_i_c_a_t_e argu-
              ment to 0 (it is set to 1 by default), in which case ssccoonnss  will
              refer  directly  to  the  source files in their source directory
              when building target files.   (Setting  _d_u_p_l_i_c_a_t_e=0  is  usually
              safe, and always more efficient than the default of _d_u_p_l_i_c_a_t_e=1,
              but it may cause build problems in certain  end-cases,  such  as
              compiling from source files that are generated by the build.)

              Any variables returned by _s_c_r_i_p_t using RReettuurrnn() will be returned
              by the call to SSCCoonnssccrriipptt().

              Examples:

              SConscript('subdir/SConscript')
              foo = SConscript('sub/SConscript', exports='env')
              SConscript('dir/SConscript', exports=['env', 'variable'])
              SConscript('src/SConscript', variant_dir='build', duplicate=0)
              SConscript('bld/SConscript', src_dir='src', exports='env variable')
              SConscript(dirs=['sub1', 'sub2'])
              SConscript(dirs=['sub3', 'sub4'], name='MySConscript')


       SConscriptChdir(_v_a_l_u_e)

       env.SConscriptChdir(_v_a_l_u_e)
              By default, ssccoonnss changes its working directory to the directory
              in  which  each subsidiary SConscript file lives.  This behavior
              may be disabled by specifying either:

              SConscriptChdir(0)
              env.SConscriptChdir(0)

              in which case ssccoonnss will stay in the top-level  directory  while
              reading  all  SConscript  files.   (This  may  be necessary when
              building from repositories, when all the  directories  in  which
              SConscript  files may be found don't necessarily exist locally.)
              You may  enable  and  disable  this  ability  by  calling  SCon-
              scriptChdir() multiple times.

              Example:

              env = Environment()
              SConscriptChdir(0)
              SConscript('foo/SConscript')  # will not chdir to foo
              env.SConscriptChdir(1)
              SConscript('bar/SConscript')  # will chdir to bar


       SConsignFile([_f_i_l_e,_d_b_m___m_o_d_u_l_e])

       env.SConsignFile([_f_i_l_e,_d_b_m___m_o_d_u_l_e])
              This  tells  ssccoonnss to store all file signatures in the specified
              database _f_i_l_e.  If the _f_i_l_e name is omitted, ..ssccoonnssiiggnn  is  used
              by default.  (The actual file name(s) stored on disk may have an
              appropriated suffix appended by the _d_b_m___m_o_d_u_l_e.)  If _f_i_l_e is not
              an  absolute path name, the file is placed in the same directory
              as the top-level SSCCoonnssttrruucctt file.

              If _f_i_l_e is NNoonnee, then ssccoonnss will store file signatures in a sep-
              arate  ..ssccoonnssiiggnn  file  in  each  directory,  not  in one global
              database file.  (This was the default behavior  prior  to  SCons
              0.96.91 and 0.97.)

              The  optional  _d_b_m___m_o_d_u_l_e  argument can be used to specify which
              Python  database  module  The  default  is  to  use   a   custom
              SSCCoonnss..ddbblliittee  module  that  uses pickled Python data structures,
              and which works on all Python versions from 1.5.2 on.

              Examples:

              # Explicitly stores signatures in ".sconsign.dblite"
              # in the top-level SConstruct directory (the
              # default behavior).
              SConsignFile()

              # Stores signatures in the file "etc/scons-signatures"
              # relative to the top-level SConstruct directory.
              SConsignFile("etc/scons-signatures")

              # Stores signatures in the specified absolute file name.
              SConsignFile("/home/me/SCons/signatures")

              # Stores signatures in a separate .sconsign file
              # in each directory.
              SConsignFile(None)


       env.SetDefault(key_=val_, _[_._._._]_)
              Sets construction variables to default values specified with the
              keyword arguments if (and only if) the variables are not already
              set.  The following statements are equivalent:

              env.SetDefault(FOO = 'foo')

              if not env.has_key('FOO'): env['FOO'] = 'foo'


       SetOption(_n_a_m_e, _v_a_l_u_e)

       env.SetOption(_n_a_m_e, _v_a_l_u_e)
              This function provides a way to set a select subset of the scons
              command  line  options  from a SConscript file. The options sup-
              ported are:


                 cclleeaann which corresponds to -c, --clean and --remove;

                 dduupplliiccaattee
                       which corresponds to --duplicate;

                 hheellpp  which corresponds to -h and --help;

                 iimmpplliicciitt__ccaacchhee
                       which corresponds to --implicit-cache;

                 mmaaxx__ddrriifftt
                       which corresponds to --max-drift;

                 nnoo__eexxeecc
                       which  corresponds  to  -n,  --no-exec,   --just-print,
                       --dry-run and --recon;

                 nnuumm__jjoobbss
                       which corresponds to -j and --jobs;

                 rraannddoomm
                       which corresponds to --random; and

                 ssttaacckk__ssiizzee
                       which corresponds to --stack-size.


              See  the documentation for the corresponding command line object
              for information about each specific option.

              Example:

              SetOption('max_drift', 1)


       SideEffect(_s_i_d_e___e_f_f_e_c_t, _t_a_r_g_e_t)

       env.SideEffect(_s_i_d_e___e_f_f_e_c_t, _t_a_r_g_e_t)
              Declares _s_i_d_e___e_f_f_e_c_t as a side effect of building _t_a_r_g_e_t.   Both
              _s_i_d_e___e_f_f_e_c_t and _t_a_r_g_e_t can be a list, a file name, or a node.  A
              side effect is a target that is created  as  a  side  effect  of
              building other targets.  For example, a Windows PDB file is cre-
              ated as a side effect of building the .obj files  for  a  static
              library.   If  a  target is a side effect of multiple build com-
              mands, ssccoonnss will ensure that only one set of commands  is  exe-
              cuted at a time.  Consequently, you only need to use this method
              for side-effect targets that are built as a result  of  multiple
              build commands.


       SourceCode(_e_n_t_r_i_e_s, _b_u_i_l_d_e_r)

       env.SourceCode(_e_n_t_r_i_e_s, _b_u_i_l_d_e_r)
              Arrange  for  non-existent  source  files  to  be fetched from a
              source code management system using the specified _b_u_i_l_d_e_r.   The
              specified _e_n_t_r_i_e_s may be a Node, string or list of both, and may
              represent either individual source files or directories in which
              source files can be found.

              For  any  non-existent  source  files,  ssccoonnss will search up the
              directory tree and use the first SSoouurrcceeCCooddee  builder  it  finds.
              The  specified _b_u_i_l_d_e_r may be NNoonnee, in which case ssccoonnss will not
              use a builder to fetch source files for the  specified  _e_n_t_r_i_e_s,
              even  if a SSoouurrcceeCCooddee builder has been specified for a directory
              higher up the tree.

              ssccoonnss will, by default, fetch files from SCCS or RCS subdirecto-
              ries without explicit configuration.  This takes some extra pro-
              cessing time to search for the necessary source code  management
              files  on disk.  You can avoid these extra searches and speed up
              your build a little by disabling these searches as follows:

              env.SourceCode('.', None)


              Note that if the specified _b_u_i_l_d_e_r is one you create by hand, it
              must  have  an  associated  construction environment to use when
              fetching a source file.

              ssccoonnss provides a set of canned  factory  functions  that  return
              appropriate  Builders for various popular source code management
              systems.  Canonical examples of invocation include:

              env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
              env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
              env.SourceCode('/', env.RCS())
              env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
              env.SourceCode('no_source.c', None)


       env.subst(_i_n_p_u_t, [_r_a_w, _t_a_r_g_e_t, _s_o_u_r_c_e, _c_o_n_v])
              Performs construction variable interpolation  on  the  specified
              string or sequence argument _i_n_p_u_t.

              By default, leading or trailing white space will be removed from
              the result.  and all sequences of white space will be compressed
              to  a single space character.  Additionally, any $$(( and $$)) char-
              acter sequences will be stripped from the returned  string,  The
              optional  _r_a_w  argument  may be set to 11 if you want to preserve
              white space and $$((-$$)) sequences.  The _r_a_w argument may be set to
              22  if  you  want  to  strip all characters between any $$(( and $$))
              pairs (as is done for signature calculation).

              If the input is a sequence (list or tuple), the individual  ele-
              ments  of the sequence will be expanded, and the results will be
              returned as a list.

              The optional _t_a_r_g_e_t and _s_o_u_r_c_e keyword arguments must be set  to
              lists  of target and source nodes, respectively, if you want the
              $$TTAARRGGEETT, $$TTAARRGGEETTSS, $$SSOOUURRCCEE and  $$SSOOUURRCCEESS  to  be  available  for
              expansion.   This  is  usually  necessary  if  you  are  calling
              eennvv..ssuubbsstt() from within a  Python  function  used  as  an  SCons
              action.

              Returned  string  values  or  sequence elements are converted to
              their string representation by default.  The optional _c_o_n_v argu-
              ment  may  specify  a  conversion  function that will be used in
              place of the default.  For example, if you want  Python  objects
              (including  SCons  Nodes)  to be returned as Python objects, you
              can use the Python llaammbbddaa idiom to pass in an  unnamed  function
              that simply returns its unconverted argument.

              Example:

              print env.subst("The C compiler is: $CC")

              def compile(target, source, env):
                  sourceDir = env.subst("${SOURCE.srcdir}",
                                        target=target,
                                        source=source)

              source_nodes = env.subst('$EXPAND_TO_NODELIST',
                                       conv=lambda x: x)



       SourceSignatures(_t_y_p_e)

       env.SourceSignatures(_t_y_p_e)
              Note:  Although it is not yet officially deprecated, use of this
              function is discouraged.  See the DDeecciiddeerr() function for a  more
              flexible  and  straightforward way to configure SCons' decision-
              making.

              The SSoouurrcceeSSiiggnnaattuurreess() function tells ssccoonnss how to decide  if  a
              source  file (a file that is not built from any other files) has
              changed since the last time it was used to  build  a  particular
              target file.  Legal values are MMDD55 or ttiimmeessttaammpp.

              If  the environment method is used, the specified type of source
              signature is only used when deciding whether targets built  with
              that  environment  are  up-to-date  or  must be rebuilt.  If the
              global function is used, the specified type of source  signature
              becomes the default used for all decisions about whether targets
              are up-to-date.

              MMDD55 means ssccoonnss decides that a source file has  changed  if  the
              MD5  checksum of its contents has changed since the last time it
              was used to rebuild a particular target file.

              ttiimmeessttaammpp means ssccoonnss decides that a source file has changed  if
              its  timestamp  (modification  time)  has changed since the last
              time it was used to rebuild a  particular  target  file.   (Note
              that  although  this  is  similar  to  the  behavior of Make, by
              default it will also rebuild if the dependency is _o_l_d_e_r than the
              last time it was used to rebuild the target file.)

              There  is  no  different  between  the  two behaviors for Python
              VVaalluuee() node objects.

              MMDD55 signatures take longer to compute,  but  are  more  accurate
              than ttiimmeessttaammpp signatures.  The default value is MMDD55.

              Note  that the default TTaarrggeettSSiiggnnaattuurreess() setting (see below) is
              to use this SSoouurrcceeSSiiggnnaattuurreess() setting for any target files that
              are  used  to  build other target files.  Consequently, changing
              the value of SSoouurrcceeSSiiggnnaattuurreess() will, by default, affect the up-
              to-date  decision for all files in the build (or all files built
              with a specific construction environment  when  eennvv..SSoouurrcceeSSiiggnnaa--
              ttuurreess() is used).


       Split(_a_r_g)

       env.Split(_a_r_g)
              Returns  a  list  of  file  names or other objects.  If arg is a
              string, it will be split on strings  of  white-space  characters
              within  the string, making it easier to write long lists of file
              names.  If arg is already a list,  the  list  will  be  returned
              untouched.   If  arg  is  any  other  type of object, it will be
              returned as a list containing just the object.

              Example:

              files = Split("f1.c f2.c f3.c")
              files = env.Split("f4.c f5.c f6.c")
              files = Split("""
                   f7.c
                   f8.c
                   f9.c
              """)


       Tag(_n_o_d_e, _t_a_g_s)
              Annotates file or directory Nodes with information about how the
              PPaacckkaaggee()  Builder  should  package  those files or directories.
              All tags are optional.

              Examples:

              # makes sure the built library will be installed with 0644 file
              # access mode
              Tag( Library( 'lib.c' ), UNIX_ATTR="0644" )

              # marks file2.txt to be a documentation file
              Tag( 'file2.txt', DOC )
       </summary> </builder>


       TargetSignatures(_t_y_p_e)

       env.TargetSignatures(_t_y_p_e)
              Note:  Although it is not yet officially deprecated, use of this
              function  is discouraged.  See the DDeecciiddeerr() function for a more
              flexible and straightforward way to configure  SCons'  decision-
              making.

              The  TTaarrggeettSSiiggnnaattuurreess()  function tells ssccoonnss how to decide if a
              target file (a file that _i_s built  from  any  other  files)  has
              changed since the last time it was used to build some other tar-
              get file.  Legal values are bbuuiilldd; ccoonntteenntt (or its synonym MMDD55);
              ttiimmeessttaammpp; or ssoouurrccee.

              If  the environment method is used, the specified type of target
              signature is only used for targets built with that  environment.
              If  the global function is used, the specified type of signature
              becomes the default used for all target files that don't have an
              explicit target signature type specified for their environments.

              ccoonntteenntt (or its synonym MMDD55) means ssccoonnss decides that  a  target
              file has changed if the MD5 checksum of its contents has changed
              since the last time it was used to  rebuild  some  other  target
              file.   This  means  ssccoonnss  will open up MD5 sum the contents of
              target files after they're built, and may decide  that  it  does
              not  need  to  rebuild  "downstream"  target files if a file was
              rebuilt with exactly the same contents as the last time.

              ttiimmeessttaammpp means ssccoonnss decides that a target file has changed  if
              its  timestamp  (modification  time)  has changed since the last
              time it was used to rebuild some other target file.  (Note  that
              although  this is similar to the behavior of Make, by default it
              will also rebuild if the dependency is _o_l_d_e_r than the last  time
              it was used to rebuild the target file.)

              ssoouurrccee  means  ssccoonnss  decides  that a target file has changed as
              specified by the corresponding SSoouurrcceeSSiiggnnaattuurreess()  setting  (MMDD55
              or ttiimmeessttaammpp).  This means that ssccoonnss will treat all input files
              to a target the same way, regardless of whether they are  source
              files or have been built from other files.

              bbuuiilldd  means  ssccoonnss decides that a target file has changed if it
              has been rebuilt in this invocation or if its content or  times-
              tamp have changed as specified by the corresponding SSoouurrcceeSSiiggnnaa--
              ttuurreess() setting.  This "propagates" the status of a rebuilt file
              so  that other "downstream" target files will always be rebuilt,
              even if the contents or the timestamp have not changed.

              bbuuiilldd signatures are fastest because ccoonntteenntt (or MMDD55) signatures
              take  longer  to  compute,  but are more accurate than ttiimmeessttaammpp
              signatures, and can prevent  unnecessary  "downstream"  rebuilds
              when  a target file is rebuilt to the exact same contents as the
              previous build.  The ssoouurrccee setting provides the most consistent
              behavior when other target files may be rebuilt from both source
              and target input files.  The default value is ssoouurrccee.

              Because the default setting is ssoouurrccee, using  SSoouurrcceeSSiiggnnaattuurreess()
              is  generally  preferable to TTaarrggeettSSiiggnnaattuurreess(),, so that the up-
              to-date decision will be consistent for all files (or all  files
              built  with  a  specific construction environment).  Use of TTaarr--
              ggeettSSiiggnnaattuurreess() provides specific control for how  built  target
              files affect their "downstream" dependencies.


       Tool(_s_t_r_i_n_g[,_t_o_o_l_p_a_t_h, _*_*_k_w])
              Returns  a callable object that can be used to initialize a con-
              struction environment using the tools keyword  of  the  Environ-
              ment()  method.   The  object  may be called with a construction
              environment as an argument, in which case the  object  will  add
              the  necessary variables to the construction environment and the
              name of the tool will be added to the $$TTOOOOLLSS construction  vari-
              able.

              Additional keyword arguments are passed to the tool's ggeenneerraattee(())
              method.

              Examples:

              env = Environment(tools = [ Tool('msvc') ])

              env = Environment()
              t = Tool('msvc')
              t(env)  # adds 'msvc' to the TOOLS variable
              u = Tool('opengl', toolpath = ['tools'])
              u(env)  # adds 'opengl' to the TOOLS variable

       env.Tool(_s_t_r_i_n_g[,_t_o_o_l_p_a_t_h, _*_*_k_w])
              Applies the callable object for the specified tool _s_t_r_i_n_g to the
              environment through which the method was called.

              Additional keyword arguments are passed to the tool's ggeenneerraattee(())
              method.

              env.Tool('gcc')
              env.Tool('opengl', toolpath = ['build/tools'])


       Value(_v_a_l_u_e, [_b_u_i_l_t___v_a_l_u_e])

       env.Value(_v_a_l_u_e, [_b_u_i_l_t___v_a_l_u_e])
              Returns a Node object representing the specified  Python  value.
              Value  Nodes  can  be  used  as dependencies of targets.  If the
              result of calling ssttrr((value)) changes  between  SCons  runs,  any
              targets  depending  on  VVaalluuee((value))  will be rebuilt.  (This is
              true even when using timestamps to decide if  files  are  up-to-
              date.)   When  using  timestamp  source signatures, Value Nodes'
              timestamps are equal to the system time when the  Node  is  cre-
              ated.

              The  returned Value Node object has a wwrriittee() method that can be
              used to "build" a Value  Node  by  setting  a  new  value.   The
              optional  _b_u_i_l_t___v_a_l_u_e  argument  can be specified when the Value
              Node is created to indicate the Node should already  be  consid-
              ered  "built."  There is a corresponding rreeaadd() method that will
              return the built value of the Node.

              Examples:

              env = Environment()

              def create(target, source, env):
                  # A function that will write a 'prefix=$SOURCE'
                  # string into the file name specified as the
                  # $TARGET.
                  f = open(str(target[0]), 'wb')
                  f.write('prefix=' + source[0].get_contents())

              # Fetch the prefix= argument, if any, from the command
              # line, and use /usr/local as the default.
              prefix = ARGUMENTS.get('prefix', '/usr/local')

              # Attach a .Config() builder for the above function action
              # to the construction environment.
              env['BUILDERS']['Config'] = Builder(action = create)
              env.Config(target = 'package-config', source = Value(prefix))

              def build_value(target, source, env):
                  # A function that "builds" a Python Value by updating
                  # the the Python value with the contents of the file
                  # specified as the source of the Builder call ($SOURCE).
                  target[0].write(source[0].get_contents())

              output = env.Value('before')
              input = env.Value('after')

              # Attach a .UpdateValue() builder for the above function
              # action to the construction environment.
              env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
              env.UpdateValue(target = Value(output), source = Value(input))


       VariantDir(_v_a_r_i_a_n_t___d_i_r, _s_r_c___d_i_r, [_d_u_p_l_i_c_a_t_e])

       env.VariantDir(_v_a_r_i_a_n_t___d_i_r, _s_r_c___d_i_r, [_d_u_p_l_i_c_a_t_e])
              This specifies a variant directory tree _v_a_r_i_a_n_t___d_i_r in which  to
              build  all  derived  files  that  would  normally be built under
              _s_r_c___d_i_r.  Multiple directory trees can be set  up  for  multiple
              build  variants.   _s_r_c___d_i_r  must  be  underneath  the SConstruct
              file's directory, and _v_a_r_i_a_n_t___d_i_r  may  not  be  underneath  the
              _s_r_c___d_i_r _.

              The  default behavior is for ssccoonnss to duplicate all of the files
              in the tree underneath _s_r_c___d_i_r into _v_a_r_i_a_n_t___d_i_r, and then  build
              the  derived  files within the copied tree.  (The duplication is
              performed by linking or copying, depending on the platform;  see
              also  the  _-_-_d_u_p_l_i_c_a_t_e  option.)  This guarantees correct builds
              regardless of whether intermediate source  files  are  generated
              during  the  build, where preprocessors or other scanners search
              for included files, or whether  individual  compilers  or  other
              invoked  tools  are  hard-coded to put derived files in the same
              directory as source files.

              This behavior of making a complete copy of the source  tree  may
              be disabled by setting _d_u_p_l_i_c_a_t_e to 0.  This will cause ssccoonnss to
              invoke Builders using the path names of source files in  _s_r_c___d_i_r
              and the path names of derived files within _v_a_r_i_a_n_t___d_i_r.  This is
              always more efficient than _d_u_p_l_i_c_a_t_e=1, and is usually safe  for
              most  builds.   Specifying _d_u_p_l_i_c_a_t_e=0, however, may cause build
              problems if source files are generated during the build,  or  if
              any  invoked  tools  are  hard-coded to put derived files in the
              same directory as the source files.

              Note that specifying a VVaarriiaannttDDiirr works most  naturally  with  a
              subsidiary  SConscript  file  in the source directory.  However,
              you would then call the subsidiary SConscript file  not  in  the
              source  directory, but in the _v_a_r_i_a_n_t___d_i_r _, as if ssccoonnss had made
              a virtual copy of the source tree regardless  of  the  value  of
              _d_u_p_l_i_c_a_t_e.  This is how you tell ssccoonnss which variant of a source
              tree to build.  For example:

              VariantDir('build-variant1', 'src')
              SConscript('build-variant1/SConscript')
              VariantDir('build-variant2', 'src')
              SConscript('build-variant2/SConscript')


              See also the SSCCoonnssccrriipptt() function, described below, for another
              way to specify a variant directory in conjunction with calling a
              subsidiary SConscript file.)


       WhereIs(_p_r_o_g_r_a_m, [_p_a_t_h, _p_a_t_h_e_x_t, _r_e_j_e_c_t])

       env.WhereIs(_p_r_o_g_r_a_m, [_p_a_t_h, _p_a_t_h_e_x_t, _r_e_j_e_c_t])

              Searches for the specified  executable  _p_r_o_g_r_a_m_,  returning  the
              full path name to the program if it is found, and returning None
              if not.  Searches the specified _p_a_t_h_, the value of  the  calling
              environment's  PATH  (env['ENV']['PATH']), or the user's current
              external PATH (os.environ['PATH']) by default.  On Windows  sys-
              tems,  searches  for  executable  programs  with any of the file
              extensions listed in the specified _p_a_t_h_e_x_t_, the calling environ-
              ment's  PATHEXT  (env['ENV']['PATHEXT'])  or  the user's current
              PATHEXT (os.environ['PATHEXT']) by default.  Will not select any
              path name or names in the specified _r_e_j_e_c_t list, if any.


   SSCCoonnssccrriipptt VVaarriiaabblleess
       In  addition to the global functions and methods, ssccoonnss supports a num-
       ber of Python variables that can be used in SConscript files to  affect
       how  you  want  the  build  to  be  performed.   These variables may be
       accessed from custom Python modules that you import into an  SConscript
       file by adding the following to the Python module:

              from SCons.Script import *


       ARGLIST
              A  list  _k_e_y_w_o_r_d=_v_a_l_u_e  arguments specified on the command line.
              Each element in  the  list  is  a  tuple  containing  the  (_k_e_y_-
              _w_o_r_d,_v_a_l_u_e)  of  the  argument.   The separate _k_e_y_w_o_r_d and _v_a_l_u_e
              elements of the tuple can be accessed by subscripting  for  ele-
              ment [[00]] and [[11]] of the tuple, respectively.

              Example:

              print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
              print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
              third_tuple = ARGLIST[2]
              print "third keyword, value =", third_tuple[0], third_tuple[1]
              for key, value in ARGLIST:
                  # process key and value


       ARGUMENTS
              A dictionary of all the _k_e_y_w_o_r_d=_v_a_l_u_e arguments specified on the
              command line.  The dictionary is not in order, and  if  a  given
              keyword  has  more  than one value assigned to it on the command
              line, the last (right-most) value is the one  in  the  AARRGGUUMMEENNTTSS
              dictionary.

              Example:

              if ARGUMENTS.get('debug', 0):
                  env = Environment(CCFLAGS = '-g')
              else:
                  env = Environment()


       BUILD_TARGETS
              A  list  of  the targets which ssccoonnss will actually try to build,
              regardless of whether they were specified on the command line or
              via the DDeeffaauulltt() function or method.  The elements of this list
              may be strings _o_r nodes, so you should run the list through  the
              Python  ssttrr  function  to make sure any Node path names are con-
              verted to strings.

              Because this list may be taken from the list of  targets  speci-
              fied using the DDeeffaauulltt() function or method, the contents of the
              list may change on each successive call to DDeeffaauulltt().   See  the
              DDEEFFAAUULLTT__TTAARRGGEETTSS list, below, for additional information.

              Example:

              if 'foo' in BUILD_TARGETS:
                  print "Don't forget to test the `foo' program!"
              if 'special/program' in BUILD_TARGETS:
                  SConscript('special')

              Note  that the BBUUIILLDD__TTAARRGGEETTSS list only contains targets expected
              listed on the command line or via calls to the  DDeeffaauulltt()  func-
              tion  or method.  It does _n_o_t contain all dependent targets that
              will be built as a result of making  the  sure  the  explicitly-
              specified targets are up to date.


       COMMAND_LINE_TARGETS
              A  list of the targets explicitly specified on the command line.
              If there are no targets specified on the command line, the  list
              is  empty.   This  can  be  used,  for example, to take specific
              actions only when a certain  target  or  targets  is  explicitly
              being built.

              Example:

              if 'foo' in COMMAND_LINE_TARGETS:
                  print "Don't forget to test the `foo' program!"
              if 'special/program' in COMMAND_LINE_TARGETS:
                  SConscript('special')


       DEFAULT_TARGETS
              A  list  of  the target _n_o_d_e_s that have been specified using the
              DDeeffaauulltt() function or method.  The  elements  of  the  list  are
              nodes,  so  you need to run them through the Python ssttrr function
              to get at the path name for each Node.

              Example:

              print str(DEFAULT_TARGETS[0])
              if 'foo' in map(str, DEFAULT_TARGETS):
                  print "Don't forget to test the `foo' program!"

              The contents of the DDEEFFAAUULLTT__TTAARRGGEETTSS list change on on each  suc-
              cessive call to the DDeeffaauulltt() function:

              print map(str, DEFAULT_TARGETS)   # originally []
              Default('foo')
              print map(str, DEFAULT_TARGETS)   # now a node ['foo']
              Default('bar')
              print map(str, DEFAULT_TARGETS)   # now a node ['foo', 'bar']
              Default(None)
              print map(str, DEFAULT_TARGETS)   # back to []

              Consequently,  be  sure to use DDEEFFAAUULLTT__TTAARRGGEETTSS only after you've
              made all of your DDeeffaauulltt() calls, or else simply be  careful  of
              the  order  of these statements in your SConscript files so that
              you don't look for a specific default target before  it's  actu-
              ally been added to the list.


   CCoonnssttrruuccttiioonn VVaarriiaabblleess
       A construction environment has an associated dictionary of _c_o_n_s_t_r_u_c_t_i_o_n
       _v_a_r_i_a_b_l_e_s that are used by built-in or user-supplied build rules.  Con-
       struction  variables must follow the same rules for Python identifiers:
       the initial character must be an underscore or letter, followed by  any
       number of underscores, letters, or digits.

       A  number of useful construction variables are automatically defined by
       scons for each supported platform, and  additional  construction  vari-
       ables  can be defined by the user. The following is a list of the auto-
       matically defined construction variables:



       AR     The static library archiver.


       ARCHITECTURE
              Specifies the system architecture for which the package is being
              built.  The default is the system architecture of the machine on
              which SCons is running.  This is used to fill in  the  AArrcchhiitteecc--
              ttuurree::  field in an Ipkg ccoonnttrrooll file, and as part of the name of
              a generated RPM file.


       ARCOM  The command line used to generate a static library  from  object
              files.


       ARCOMSTR
              The  string  displayed  when an object file is generated from an
              assembly-language source file.  If this is not set, then  $ARCOM
              (the command line) is displayed.

              env = Environment(ARCOMSTR = "Archiving $TARGET")


       ARFLAGS
              General options passed to the static library archiver.


       AS     The assembler.


       ASCOM  The  command line used to generate an object file from an assem-
              bly-language source file.


       ASCOMSTR
              The string displayed when an object file is  generated  from  an
              assembly-language  source file.  If this is not set, then $ASCOM
              (the command line) is displayed.

              env = Environment(ASCOMSTR = "Assembling $TARGET")


       ASFLAGS
              General options passed to the assembler.


       ASPPCOM
              The command line used to assemble  an  assembly-language  source
              file  into  an  object file after first running the file through
              the C preprocessor.  Any options specified in the  $ASFLAGS  and
              $CPPFLAGS  construction  variables  are included on this command
              line.


       ASPPCOMSTR
              The string displayed when an object file is  generated  from  an
              assembly-language  source  file  after  first  running  the file
              through the C preprocessor.  If this is not set,  then  $ASPPCOM
              (the command line) is displayed.

              env = Environment(ASPPCOMSTR = "Assembling $TARGET")


       ASPPFLAGS
              General  options  when an assembling an assembly-language source
              file into an object file after first running  the  file  through
              the  C  preprocessor.   The  default  is  to  use  the  value of
              $ASFLAGS.


       BIBTEX The bibliography generator for the TeX formatter and  typesetter
              and the LaTeX structured formatter and typesetter.


       BIBTEXCOM
              The command line used to call the bibliography generator for the
              TeX formatter and typesetter and the LaTeX structured  formatter
              and typesetter.


       BIBTEXCOMSTR
              The  string  displayed when generating a bibliography for TeX or
              LaTeX.  If this is not set, then $BIBTEXCOM (the  command  line)
              is displayed.

              env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")


       BIBTEXFLAGS
              General options passed to the bibliography generator for the TeX
              formatter and typesetter and the LaTeX structured formatter  and
              typesetter.


       BITKEEPER
              The BitKeeper executable.


       BITKEEPERCOM
              The command line for fetching source files using BitKeeper.


       BITKEEPERCOMSTR
              The  string  displayed  when  fetching  a source file using Bit-
              Keeper.  If this is not set,  then  $BITKEEPERCOM  (the  command
              line) is displayed.


       BITKEEPERGET
              The  command  ($BITKEEPER)  and  subcommand  for fetching source
              files using BitKeeper.


       BITKEEPERGETFLAGS
              Options that are passed to the BitKeeper ggeett subcommand.


       BUILDERS
              A dictionary mapping the names of the builders available through
              this  environment to underlying Builder objects.  Builders named
              Alias, CFile, CXXFile, DVI, Library,  Object,  PDF,  PostScript,
              and  Program  are  available by default.  If you initialize this
              variable when an Environment is created:

              env = Environment(BUILDERS = {'NewBuilder' : foo})

              the default Builders will no longer be available.  To use a  new
              Builder object in addition to the default Builders, add your new
              Builder object like this:

              env = Environment()
              env.Append(BUILDERS = {'NewBuilder' : foo})

              or this:

              env = Environment()
              env['BUILDERS]['NewBuilder'] = foo


       CC     The C compiler.


       CCCOM  The command line used to compile a C source file to  a  (static)
              object file.  Any options specified in the $CFLAGS, $CCFLAGS and
              $CPPFLAGS construction variables are included  on  this  command
              line.


       CCCOMSTR
              The  string  displayed  when  a  C  source file is compiled to a
              (static) object file.  If this is not set, then $CCCOM (the com-
              mand line) is displayed.

              env = Environment(CCCOMSTR = "Compiling static object $TARGET")


       CCFLAGS
              General options that are passed to the C and C++ compilers.


       CCPCHFLAGS
              Options  added  to the compiler command line to support building
              with precompiled headers.  The default value expands expands  to
              the  appropriate  Microsoft Visual C++ command-line options when
              the $PCH construction variable is set.


       CCPDBFLAGS
              Options added to the compiler command line  to  support  storing
              debugging  information  in a Microsoft Visual C++ PDB file.  The
              default value expands expands to  appropriate  Microsoft  Visual
              C++  command-line options when the $PDB construction variable is
              set.

              The Visual C++ compiler option that SCons  uses  by  default  to
              generate PDB information is //ZZ77.  This works correctly with par-
              allel (--jj) builds because it embeds the debug information in the
              intermediate  object  files,  as opposed to sharing a single PDB
              file between multiple object files.  This is also the  only  way
              to  get debug information embedded into a static library.  Using
              the  //ZZii  instead  may  yield  improved  link-time  performance,
              although parallel builds will no longer work.

              You can generate PDB files with the //ZZii switch by overriding the
              default $CCPDBFLAGS variable as follows:

              import SCons.Util
              env['CCPDBFLAGS'] = SCons.Util.CLVar(['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}'])

              An alternative would be to use the  //ZZii  to  put  the  debugging
              information  in  a  separate  ..ppddbb  file for each object file by
              overriding the $CCPDBFLAGS variable as follows:

              env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb'


       CCVERSION
              The version number of the C compiler.  This may or  may  not  be
              set, depending on the specific C compiler being used.


       CFILESUFFIX
              The  suffix  for  C  source files.  This is used by the internal
              CFile builder when generating C files from Lex (.l) or YACC (.y)
              input files.  The default suffix, of course, is ..cc (lower case).
              On case-insensitive systems (like Windows), SCons also treats ..CC
              (upper case) files as C files.


       CFLAGS General  options  that are passed to the C compiler (C only; not
              C++).


       CHANGE_SPECFILE
              A hook for modifying the file that controls the packaging  build
              (the ..ssppeecc for RPM, the ccoonnttrrooll for Ipkg, the ..wwxxss for MSI).  If
              set, the function will be called after the  SCons  template  for
              the file has been written.  XXX


       CHANGELOG
              The name of a file containing the change log text to be included
              in the package.  This is included as the %%cchhaannggeelloogg  section  of
              the RPM ..ssppeecc file.


       _concat
              A  function  used  to  produce  variables like $_CPPINCFLAGS. It
              takes four or five arguments: a prefix to concatenate onto  each
              element,  a  list of elements, a suffix to concatenate onto each
              element, an  environment  for  variable  interpolation,  and  an
              optional  function  that  will  be  called to transform the list
              before concatenation.

              env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',


       CONFIGUREDIR
              The name of the directory in which Configure context test  files
              are written.  The default is ..ssccoonnff__tteemmpp in the top-level direc-
              tory containing the SSCCoonnssttrruucctt file.


       CONFIGURELOG
              The name of the Configure context log file.  The default is ccoonn--
              ffiigg..lloogg  in  the  top-level  directory containing the SSCCoonnssttrruucctt
              file.


       _CPPDEFFLAGS
              An automatically-generated construction variable containing  the
              C preprocessor command-line options to define values.  The value
              of $_CPPDEFFLAGS  is  created  by  appending  $CPPDEFPREFIX  and
              $CPPDEFSUFFIX  to  the  beginning  and  end of each directory in
              $CPPDEFINES.


       CPPDEFINES
              A platform independent specification of C  preprocessor  defini-
              tions.   The  definitions will be added to command lines through
              the automatically-generated $_CPPDEFFLAGS construction  variable
              (see above), which is constructed according to the type of value
              of $CPPDEFINES:

              If $CPPDEFINES is a string, the values of the $CPPDEFPREFIX  and
              $CPPDEFSUFFIX construction variables will be added to the begin-
              ning and end.

              # Will add -Dxyz to POSIX compiler command lines,
              # and /Dxyz to Microsoft Visual C++ command lines.
              env = Environment(CPPDEFINES='xyz')

              If $CPPDEFINES is a list, the values of  the  $CPPDEFPREFIX  and
              $CPPDEFSUFFIX  construction  variables  will  be appended to the
              beginning and end of each element in the list.  If  any  element
              is  a  list  or  tuple,  then  the  first item is the name being
              defined and the second item is its value:

              # Will add -DB=2 -DA to POSIX compiler command lines,
              # and /DB=2 /DA to Microsoft Visual C++ command lines.
              env = Environment(CPPDEFINES=[('B', 2), 'A'])

              If $CPPDEFINES is a dictionary, the values of the  $CPPDEFPREFIX
              and $CPPDEFSUFFIX construction variables will be appended to the
              beginning and end of each item from the dictionary.  The key  of
              each  dictionary  item is a name being defined to the dictionary
              item's corresponding value; if the value is NNoonnee, then the  name
              is  defined  without an explicit value.  Note that the resulting
              flags are sorted by keyword to ensure  that  the  order  of  the
              options  on  the  command  line is consistent each time ssccoonnss is
              run.

              # Will add -DA -DB=2 to POSIX compiler command lines,
              # and /DA /DB=2 to Microsoft Visual C++ command lines.
              env = Environment(CPPDEFINES={'B':2, 'A':None})


       CPPDEFPREFIX
              The prefix used to specify preprocessor  definitions  on  the  C
              compiler  command  line.  This will be appended to the beginning
              of each definition in the $CPPDEFINES construction variable when
              the $_CPPDEFFLAGS variable is automatically generated.


       CPPDEFSUFFIX
              The  suffix  used  to  specify preprocessor definitions on the C
              compiler command line.  This will be appended to the end of each
              definition  in  the  $CPPDEFINES  construction variable when the
              $_CPPDEFFLAGS variable is automatically generated.


       CPPFLAGS
              User-specified C preprocessor options.  These will  be  included
              in  any command that uses the C preprocessor, including not just
              compilation of C and C++ source files via the $CCCOM,  $SHCCCOM,
              $CXXCOM and $SHCXXCOM command lines, but also the $FORTRANPPCOM,
              $SHFORTRANPPCOM, $F77PPCOM and $SHF77PPCOM command lines used to
              compile  a  Fortran  source  file, and the $ASPPCOM command line
              used to assemble an assembly language source file,  after  first
              running  each  file  through the C preprocessor.  Note that this
              variable does _n_o_t contain --II (or similar)  include  search  path
              options  that  scons generates automatically from $CPPPATH.  See
              $_CPPINCFLAGS, below, for the variable  that  expands  to  those
              options.


       _CPPINCFLAGS
              An  automatically-generated construction variable containing the
              C preprocessor command-line options for  specifying  directories
              to be searched for include files.  The value of $_CPPINCFLAGS is
              created by appending $INCPREFIX and $INCSUFFIX to the  beginning
              and end of each directory in $CPPPATH.


       CPPPATH
              The  list of directories that the C preprocessor will search for
              include directories. The C/C++ implicit dependency scanner  will
              search these directories for include files. Don't explicitly put
              include directory arguments in CCFLAGS or CXXFLAGS  because  the
              result  will  be  non-portable  and  the directories will not be
              searched by the dependency scanner.  Note:  directory  names  in
              CPPPATH  will  be looked-up relative to the SConscript directory
              when they are used in a command. To force  ssccoonnss  to  look-up  a
              directory relative to the root of the source tree use #:

              env = Environment(CPPPATH='#/include')

              The  directory  look-up can also be forced using the DDiirr() func-
              tion:

              include = Dir('include')
              env = Environment(CPPPATH=include)

              The directory list will be added to command  lines  through  the
              automatically-generated   $_CPPINCFLAGS  construction  variable,
              which is constructed by appending the values of  the  $INCPREFIX
              and  $INCSUFFIX  construction variables to the beginning and end
              of each directory in $CPPPATH.  Any  command  lines  you  define
              that   need   the   CPPPATH   directory   list   should  include
              $_CPPINCFLAGS:

              env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")


       CPPSUFFIXES
              The list of suffixes of files that will be scanned for C prepro-
              cessor implicit dependencies (#include lines).  The default list
              is:

              [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
               ".h", ".H", ".hxx", ".hpp", ".hh",
               ".F", ".fpp", ".FPP",
               ".m", ".mm",
               ".S", ".spp", ".SPP"]


       CVS    The CVS executable.


       CVSCOFLAGS
              Options that are passed to the CVS checkout subcommand.


       CVSCOM The command line used to fetch source files from a  CVS  reposi-
              tory.


       CVSCOMSTR
              The  string  displayed  when  fetching  a source file from a CVS
              repository.  If this is not set, then $CVSCOM (the command line)
              is displayed.


       CVSFLAGS
              General options that are passed to CVS.  By default, this is set
              to --dd $$CCVVSSRREEPPOOSSIITTOORRYY to specify from where  the  files  must  be
              fetched.


       CVSREPOSITORY
              The  path  to  the  CVS  repository.   This is referenced in the
              default $CVSFLAGS value.


       CXX    The C++ compiler.


       CXXCOM The command line used to compile a C++ source file to an  object
              file.  Any options specified in the $CXXFLAGS and $CPPFLAGS con-
              struction variables are included on this command line.


       CXXCOMSTR
              The string displayed when a C++ source file  is  compiled  to  a
              (static)  object  file.   If  this is not set, then $CXXCOM (the
              command line) is displayed.

              env = Environment(CXXCOMSTR = "Compiling static object $TARGET")


       CXXFILESUFFIX
              The suffix for C++ source files.  This is used by  the  internal
              CXXFile builder when generating C++ files from Lex (.ll) or YACC
              (.yy) input files.  The  default  suffix  is  ..cccc.   SCons  also
              treats files with the suffixes ..ccpppp, ..ccxxxx, ..cc++++, and ..CC++++ as C++
              files, and files with ..mmmm suffixes as Objective C++  files.   On
              case-sensitive  systems  (Linux,  UNIX, and other POSIX-alikes),
              SCons also treats ..CC (upper case) files as C++ files.


       CXXFLAGS
              General options  that  are  passed  to  the  C++  compiler.   By
              default,  this  includes  the value of $CCFLAGS, so that setting
              $CCFLAGS affects both C and C++ compilation.  If you want to add
              C++-specific  flags,  you  must  set  or  override  the value of
              $CXXFLAGS.


       CXXVERSION
              The version number of the C++ compiler.  This may or may not  be
              set, depending on the specific C++ compiler being used.


       DESCRIPTION
              A  long  description  of  the  project  being packaged.  This is
              included in the relevant section of the file that  controls  the
              packaging build.


       DESCRIPTION_lang
              A  language-specific  long  description  for the specified _l_a_n_g.
              This is used to populate a %%ddeessccrriippttiioonn --ll  section  of  an  RPM
              ..ssppeecc file.


       Dir    A  function  that converts a string into a Dir instance relative
              to the target being built.


       Dirs   A function that converts a list of strings into a  list  of  Dir
              instances relative to the target being built.


       DSUFFIXES
              The  list of suffixes of files that will be scanned for imported
              D package files.  The default list is:

              ['.d']


       DVIPDF The TeX DVI file to PDF file converter.


       DVIPDFCOM
              The command line used to convert TeX DVI files into a PDF  file.


       DVIPDFCOMSTR
              The string displayed when a TeX DVI file is converted into a PDF
              file.  If this is not set, then $DVIPDFCOM (the command line) is
              displayed.


       DVIPDFFLAGS
              General  options  passed  to  the  TeX DVI file to PDF file con-
              verter.


       DVIPS  The TeX DVI file to PostScript converter.


       DVIPSFLAGS
              General options passed to the TeX DVI file  to  PostScript  con-
              verter.


       ENV    A  dictionary of environment variables to use when invoking com-
              mands. When $ENV is used in a command all list  values  will  be
              joined  using the path separator and any other non-string values
              will simply be coerced to a  string.   Note  that,  by  default,
              ssccoonnss  does _n_o_t propagate the environment in force when you exe-
              cute ssccoonnss to the commands used to build target files.  This  is
              so  that  builds will be guaranteed repeatable regardless of the
              environment variables set at the time ssccoonnss is invoked.

              If you want to propagate your environment variables to the  com-
              mands executed to build target files, you must do so explicitly:

              import os
              env = Environment(ENV = os.environ)

              Note that you can choose only to propagate  certain  environment
              variables.   A  common  example  is  the system PPAATTHH environment
              variable, so that ssccoonnss uses the same utilities as the  invoking
              shell (or other process):

              import os
              env = Environment(ENV = {'PATH' : os.environ['PATH']})


       ESCAPE A  function  that will be called to escape shell special charac-
              ters in command lines. The function should  take  one  argument:
              the command line string to escape; and should return the escaped
              command line.


       F77    The Fortran 77 compiler.  You should normally set  the  $FORTRAN
              variable,  which  specifies the default Fortran compiler for all
              Fortran versions.  You only need to set $F77 if you need to  use
              a specific compiler or compiler version for Fortran 77 files.


       F77COM The  command line used to compile a Fortran 77 source file to an
              object file.  You only need to set $F77COM if you need to use  a
              specific command line for Fortran 77 files.  You should normally
              set the $FORTRANCOM variable, which specifies the  default  com-
              mand line for all Fortran versions.


       F77COMSTR
              The  string  displayed when a Fortran 77 source file is compiled
              to an object file.  If this is not set, then  $F77COM  or  $FOR-
              TRANCOM (the command line) is displayed.


       F77FLAGS
              General user-specified options that are passed to the Fortran 77
              compiler.  Note that this variable does _n_o_t contain --II (or simi-
              lar)  include search path options that scons generates automati-
              cally from $F77PATH.  See $_F77INCFLAGS below, for the  variable
              that  expands  to those options.  You only need to set $F77FLAGS
              if you need to define  specific  user  options  for  Fortran  77
              files.   You  should  normally  set  the $FORTRANFLAGS variable,
              which specifies the user-specified options passed to the default
              Fortran compiler for all Fortran versions.


       _F77INCFLAGS
              An  automatically-generated construction variable containing the
              Fortran 77 compiler command-line options for specifying directo-
              ries   to   be   searched  for  include  files.   The  value  of
              $_F77INCFLAGS is created by appending $INCPREFIX and  $INCSUFFIX
              to the beginning and end of each directory in $F77PATH.


       F77PATH
              The list of directories that the Fortran 77 compiler will search
              for include directories. The implicit  dependency  scanner  will
              search these directories for include files. Don't explicitly put
              include directory arguments in $F77FLAGS because the result will
              be  non-portable and the directories will not be searched by the
              dependency scanner. Note: directory names in  $F77PATH  will  be
              looked-up  relative  to  the  SConscript directory when they are
              used in a command. To force ssccoonnss to look-up a  directory  rela-
              tive  to the root of the source tree use #: You only need to set
              $F77PATH if you need to define a specific include path for  For-
              tran  77  files.  You should normally set the $FORTRANPATH vari-
              able, which specifies the include path for the  default  Fortran
              compiler for all Fortran versions.

              env = Environment(F77PATH='#/include')

              The  directory  look-up can also be forced using the DDiirr() func-
              tion:

              include = Dir('include')
              env = Environment(F77PATH=include)

              The directory list will be added to command  lines  through  the
              automatically-generated   $_F77INCFLAGS  construction  variable,
              which is constructed by appending the values of  the  $INCPREFIX
              and  $INCSUFFIX  construction variables to the beginning and end
              of each directory in $F77PATH.  Any  command  lines  you  define
              that   need   the   F77PATH   directory   list   should  include
              $_F77INCFLAGS:

              env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")


       F77PPCOM
              The command line used to compile a Fortran 77 source file to  an
              object  file  after first running the file through the C prepro-
              cessor.  Any options specified in the  $F77FLAGS  and  $CPPFLAGS
              construction  variables  are included on this command line.  You
              only need to set $F77PPCOM if you need to use a specific  C-pre-
              processor  command  line  for Fortran 77 files.  You should nor-
              mally  set  the  $FORTRANPPCOM  variable,  which  specifies  the
              default C-preprocessor command line for all Fortran versions.


       F77PPCOMSTR
              The  string  displayed when a Fortran 77 source file is compiled
              to an object file after first running the  file  through  the  C
              preprocessor.  If this is not set, then $F77PPCOM or $FORTRANPP-
              COM (the command line) is displayed.


       F90    The Fortran 90 compiler.  You should normally set  the  $FORTRAN
              variable,  which  specifies the default Fortran compiler for all
              Fortran versions.  You only need to set $F90 if you need to  use
              a specific compiler or compiler version for Fortran 90 files.


       F90COM The  command line used to compile a Fortran 90 source file to an
              object file.  You only need to set $F90COM if you need to use  a
              specific command line for Fortran 90 files.  You should normally
              set the $FORTRANCOM variable, which specifies the  default  com-
              mand line for all Fortran versions.


       F90COMSTR
              The  string  displayed when a Fortran 90 source file is compiled
              to an object file.  If this is not set, then  $F90COM  or  $FOR-
              TRANCOM (the command line) is displayed.


       F90FLAGS
              General user-specified options that are passed to the Fortran 90
              compiler.  Note that this variable does _n_o_t contain --II (or simi-
              lar)  include search path options that scons generates automati-
              cally from $F90PATH.  See $_F90INCFLAGS below, for the  variable
              that  expands  to those options.  You only need to set $F90FLAGS
              if you need to define  specific  user  options  for  Fortran  90
              files.   You  should  normally  set  the $FORTRANFLAGS variable,
              which specifies the user-specified options passed to the default
              Fortran compiler for all Fortran versions.


       _F90INCFLAGS
              An  automatically-generated construction variable containing the
              Fortran 90 compiler command-line options for specifying directo-
              ries   to   be   searched  for  include  files.   The  value  of
              $_F90INCFLAGS is created by appending $INCPREFIX and  $INCSUFFIX
              to the beginning and end of each directory in $F90PATH.


       F90PATH
              The list of directories that the Fortran 90 compiler will search
              for include directories. The implicit  dependency  scanner  will
              search these directories for include files. Don't explicitly put
              include directory arguments in $F90FLAGS because the result will
              be  non-portable and the directories will not be searched by the
              dependency scanner. Note: directory names in  $F90PATH  will  be
              looked-up  relative  to  the  SConscript directory when they are
              used in a command. To force ssccoonnss to look-up a  directory  rela-
              tive  to the root of the source tree use #: You only need to set
              $F90PATH if you need to define a specific include path for  For-
              tran  90  files.  You should normally set the $FORTRANPATH vari-
              able, which specifies the include path for the  default  Fortran
              compiler for all Fortran versions.

              env = Environment(F90PATH='#/include')

              The  directory  look-up can also be forced using the DDiirr() func-
              tion:

              include = Dir('include')
              env = Environment(F90PATH=include)

              The directory list will be added to command  lines  through  the
              automatically-generated   $_F90INCFLAGS  construction  variable,
              which is constructed by appending the values of  the  $INCPREFIX
              and  $INCSUFFIX  construction variables to the beginning and end
              of each directory in $F90PATH.  Any  command  lines  you  define
              that   need   the   F90PATH   directory   list   should  include
              $_F90INCFLAGS:

              env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")


       F90PPCOM
              The command line used to compile a Fortran 90 source file to  an
              object  file  after first running the file through the C prepro-
              cessor.  Any options specified in the  $F90FLAGS  and  $CPPFLAGS
              construction  variables  are included on this command line.  You
              only need to set $F90PPCOM if you need to use a specific  C-pre-
              processor  command  line  for Fortran 90 files.  You should nor-
              mally  set  the  $FORTRANPPCOM  variable,  which  specifies  the
              default C-preprocessor command line for all Fortran versions.


       F90PPCOMSTR
              The  string  displayed when a Fortran 90 source file is compiled
              after first running the file through  the  C  preprocessor.   If
              this  is  not  set, then $F90PPCOM or $FORTRANPPCOM (the command
              line) is displayed.


       F95    The Fortran 95 compiler.  You should normally set  the  $FORTRAN
              variable,  which  specifies the default Fortran compiler for all
              Fortran versions.  You only need to set $F95 if you need to  use
              a specific compiler or compiler version for Fortran 95 files.


       F95COM The  command line used to compile a Fortran 95 source file to an
              object file.  You only need to set $F95COM if you need to use  a
              specific command line for Fortran 95 files.  You should normally
              set the $FORTRANCOM variable, which specifies the  default  com-
              mand line for all Fortran versions.


       F95COMSTR
              The  string  displayed when a Fortran 95 source file is compiled
              to an object file.  If this is not set, then  $F95COM  or  $FOR-
              TRANCOM (the command line) is displayed.


       F95FLAGS
              General user-specified options that are passed to the Fortran 95
              compiler.  Note that this variable does _n_o_t contain --II (or simi-
              lar)  include search path options that scons generates automati-
              cally from $F95PATH.  See $_F95INCFLAGS below, for the  variable
              that  expands  to those options.  You only need to set $F95FLAGS
              if you need to define  specific  user  options  for  Fortran  95
              files.   You  should  normally  set  the $FORTRANFLAGS variable,
              which specifies the user-specified options passed to the default
              Fortran compiler for all Fortran versions.


       _F95INCFLAGS
              An  automatically-generated construction variable containing the
              Fortran 95 compiler command-line options for specifying directo-
              ries   to   be   searched  for  include  files.   The  value  of
              $_F95INCFLAGS is created by appending $INCPREFIX and  $INCSUFFIX
              to the beginning and end of each directory in $F95PATH.


       F95PATH
              The list of directories that the Fortran 95 compiler will search
              for include directories. The implicit  dependency  scanner  will
              search these directories for include files. Don't explicitly put
              include directory arguments in $F95FLAGS because the result will
              be  non-portable and the directories will not be searched by the
              dependency scanner. Note: directory names in  $F95PATH  will  be
              looked-up  relative  to  the  SConscript directory when they are
              used in a command. To force ssccoonnss to look-up a  directory  rela-
              tive  to the root of the source tree use #: You only need to set
              $F95PATH if you need to define a specific include path for  For-
              tran  95  files.  You should normally set the $FORTRANPATH vari-
              able, which specifies the include path for the  default  Fortran
              compiler for all Fortran versions.

              env = Environment(F95PATH='#/include')

              The  directory  look-up can also be forced using the DDiirr() func-
              tion:

              include = Dir('include')
              env = Environment(F95PATH=include)

              The directory list will be added to command  lines  through  the
              automatically-generated   $_F95INCFLAGS  construction  variable,
              which is constructed by appending the values of  the  $INCPREFIX
              and  $INCSUFFIX  construction variables to the beginning and end
              of each directory in $F95PATH.  Any  command  lines  you  define
              that   need   the   F95PATH   directory   list   should  include
              $_F95INCFLAGS:

              env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")


       F95PPCOM
              The command line used to compile a Fortran 95 source file to  an
              object  file  after first running the file through the C prepro-
              cessor.  Any options specified in the  $F95FLAGS  and  $CPPFLAGS
              construction  variables  are included on this command line.  You
              only need to set $F95PPCOM if you need to use a specific  C-pre-
              processor  command  line  for Fortran 95 files.  You should nor-
              mally  set  the  $FORTRANPPCOM  variable,  which  specifies  the
              default C-preprocessor command line for all Fortran versions.


       F95PPCOMSTR
              The  string  displayed when a Fortran 95 source file is compiled
              to an object file after first running the  file  through  the  C
              preprocessor.  If this is not set, then $F95PPCOM or $FORTRANPP-
              COM (the command line) is displayed.


       File   A function that converts a string into a File instance  relative
              to the target being built.


       FORTRAN
              The default Fortran compiler for all versions of Fortran.


       FORTRANCOM
              The  command  line  used  to compile a Fortran source file to an
              object file.  By default, any options specified in the $FORTRAN-
              FLAGS,  $CPPFLAGS,  $_CPPDEFFLAGS,  $_FORTRANMODFLAG, and $_FOR-
              TRANINCFLAGS construction variables are included on this command
              line.


       FORTRANCOMSTR
              The  string  displayed when a Fortran source file is compiled to
              an object file.  If this is not set, then $FORTRANCOM (the  com-
              mand line) is displayed.


       FORTRANFLAGS
              General  user-specified  options  that are passed to the Fortran
              compiler.  Note that this variable does _n_o_t contain --II (or simi-
              lar)  include or module search path options that scons generates
              automatically  from  $FORTRANPATH.   See  $_FORTRANINCFLAGS  and
              $_FORTRANMODFLAG,  below,  for  the  variables that expand those
              options.


       _FORTRANINCFLAGS
              An automatically-generated construction variable containing  the
              Fortran compiler command-line options for specifying directories
              to be searched for include files and module files.  The value of
              $_FORTRANINCFLAGS  is created by prepending/appending $INCPREFIX
              and $INCSUFFIX to the beginning and end  of  each  directory  in
              $FORTRANPATH.


       FORTRANMODDIR
              Directory  location  where the Fortran compiler should place any
              module files it generates.  This variable is empty, by  default.
              Some  Fortran compilers will internally append this directory in
              the search path for module files, as well.


       FORTRANMODDIRPREFIX
              The prefix used to specify a module  directory  on  the  Fortran
              compiler  command  line.  This will be appended to the beginning
              of the directory in the  $FORTRANMODDIR  construction  variables
              when  the $_FORTRANMODFLAG variables is automatically generated.


       FORTRANMODDIRSUFFIX
              The suffix used to specify a module  directory  on  the  Fortran
              compiler  command  line.  This will be appended to the beginning
              of the directory in the  $FORTRANMODDIR  construction  variables
              when  the $_FORTRANMODFLAG variables is automatically generated.


       _FORTRANMODFLAG
              An automatically-generated construction variable containing  the
              Fortran  compiler  command-line option for specifying the direc-
              tory location where the Fortran compiler should place any module
              files  that  happen  to  get  generated during compilation.  The
              value of $_FORTRANMODFLAG  is  created  by  prepending/appending
              $FORTRANMODDIRPREFIX  and  $FORTRANMODDIRSUFFIX to the beginning
              and end of the directory in $FORTRANMODDIR.


       FORTRANMODPREFIX
              The module file prefix used  by  the  Fortran  compiler.   SCons
              assumes  that  the  Fortran  compiler follows the quasi-standard
              naming convention for module files  of  mmoodduullee__nnaammee..mmoodd.   As  a
              result, this variable is left empty, by default.  For situations
              in which the compiler does not  necessarily  follow  the  normal
              convention,  the  user may use this variable.  Its value will be
              appended to every module file name as scons attempts to  resolve
              dependencies.


       FORTRANMODSUFFIX
              The  module  file  suffix  used  by the Fortran compiler.  SCons
              assumes that the Fortran  compiler  follows  the  quasi-standard
              naming  convention  for  module  files of mmoodduullee__nnaammee..mmoodd.  As a
              result, this variable is set to ".mod", by default.  For  situa-
              tions in which the compiler does not necessarily follow the nor-
              mal convention, the user may use this variable.  Its value  will
              be  appended  to  every  module  file  name as scons attempts to
              resolve dependencies.


       FORTRANPATH
              The list of directories that the Fortran  compiler  will  search
              for  include  files  and  (for some compilers) module files. The
              Fortran implicit dependency scanner will search  these  directo-
              ries  for  include  files  (but  not module files since they are
              autogenerated and, as such, may not actually exist at  the  time
              the  scan  takes  place). Don't explicitly put include directory
              arguments in  FORTRANFLAGS  because  the  result  will  be  non-
              portable  and the directories will not be searched by the depen-
              dency scanner. Note: directory  names  in  FORTRANPATH  will  be
              looked-up  relative  to  the  SConscript directory when they are
              used in a command. To force ssccoonnss to look-up a  directory  rela-
              tive to the root of the source tree use #:

              env = Environment(FORTRANPATH='#/include')

              The  directory  look-up can also be forced using the DDiirr() func-
              tion:

              include = Dir('include')
              env = Environment(FORTRANPATH=include)

              The directory list will be added to command  lines  through  the
              automatically-generated $_FORTRANINCFLAGS construction variable,
              which is constructed by appending the values of  the  $INCPREFIX
              and  $INCSUFFIX  construction variables to the beginning and end
              of each directory in $FORTRANPATH.  Any command lines you define
              that  need  the FORTRANPATH directory list should include $_FOR-
              TRANINCFLAGS:

              env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")


       FORTRANPPCOM
              The command line used to compile a Fortran  source  file  to  an
              object   file  after  first  running  the  file  through  the  C
              preprocessor.  By default, any options specified  in  the  $FOR-
              TRANFLAGS,   $CPPFLAGS,   $_CPPDEFFLAGS,  $_FORTRANMODFLAG,  and
              $_FORTRANINCFLAGS construction variables are  included  on  this
              command line.


       FORTRANPPCOMSTR
              The  string  displayed when a Fortran source file is compiled to
              an object file after first running the file throught the C  pre-
              processor.   If this is not set, then $FORTRANPPCOM (the command
              line) is displayed.


       FORTRANSUFFIXES
              The list of suffixes of files that will be scanned  for  Fortran
              implicit  dependencies  (INCLUDE lines and USE statements).  The
              default list is:

              [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
              ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]


       FRAMEWORKPATH
              On Mac OS X with gcc, a list containing the paths to search  for
              frameworks.   Used  by  the  compiler  to  find  framework-style
              includes like #include <Fmwk/Header.h>.  Used by the  linker  to
              find  user-specified  frameworks when linking (see $FRAMEWORKS).
              For example:

               env.AppendUnique(FRAMEWORKPATH='#myframeworkdir')

              will add

                ... -Fmyframeworkdir

              to the compiler and linker command lines.


       _FRAMEWORKPATH
              On Mac OS X with gcc,  an  automatically-generated  construction
              variable  containing the linker command-line options correspond-
              ing to $FRAMEWORKPATH.


       FRAMEWORKPATHPREFIX
              On Mac OS X with gcc, the prefix to be used for  the  FRAMEWORK-
              PATH entries.  (see $FRAMEWORKPATH).  The default value is --FF.


       FRAMEWORKPREFIX
              On  Mac  OS  X  with  gcc,  the prefix to be used for linking in
              frameworks (see $FRAMEWORKS).  The default value is  --ffrraammeewwoorrkk.


       _FRAMEWORKS
              On  Mac  OS  X with gcc, an automatically-generated construction
              variable containing the linker command-line options for  linking
              with FRAMEWORKS.


       FRAMEWORKS
              On Mac OS X with gcc, a list of the framework names to be linked
              into a program or shared library or bundle.  The  default  value
              is the empty list.  For example:

               env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration'))



       FRAMEWORKSFLAGS
              On  Mac  OS X with gcc, general user-supplied frameworks options
              to be added at the end of a command  line  building  a  loadable
              module.   (This  has  been largely superceded by the $FRAMEWORK-
              PATH,  $FRAMEWORKPATHPREFIX,  $FRAMEWORKPREFIX  and  $FRAMEWORKS
              variables described above.)


       GS     The Ghostscript program used to convert PostScript to PDF files.


       GSCOM  The Ghostscript command line used to convert PostScript  to  PDF
              files.


       GSCOMSTR
              The  string  displayed  when  Ghostscript  is  used to convert a
              PostScript file to a PDF file.  If this is not set, then  $GSCOM
              (the command line) is displayed.


       GSFLAGS
              General  options passed to the Ghostscript program when convert-
              ing PostScript to PDF files.


       IDLSUFFIXES
              The list of suffixes of files  that  will  be  scanned  for  IDL
              implicit  dependencies  (#include or import lines).  The default
              list is:

              [".idl", ".IDL"]


       IMPLICIT_COMMAND_DEPENDENCIES
              Controls whether or not SCons will add implicit dependencies for
              the commands executed to build targets.

              By default, SCons will add to each target an implicit dependency
              on the command represented by the first argument on any  command
              line it executes.  The specific file for the dependency is found
              by searching the _P_A_T_H variable in the _E_N_V  environment  used  to
              execute the command.

              If  the  construction variable $IMPLICIT_COMMAND_DEPENDENCIES is
              set to a false value (NNoonnee, FFaallssee, 00, etc.), then  the  implicit
              dependency will not be added to the targets built with that con-
              struction environment.

              env = Environment(IMPLICIT_COMMAND_DEPENDENCIES = 0)


       INCPREFIX
              The prefix used to specify an include directory on  the  C  com-
              piler  command  line.  This will be appended to the beginning of
              each directory in the  $CPPPATH  and  $FORTRANPATH  construction
              variables when the $_CPPINCFLAGS and $_FORTRANINCFLAGS variables
              are automatically generated.


       INCSUFFIX
              The suffix used to specify an include directory on  the  C  com-
              piler  command  line.   This will be appended to the end of each
              directory in the $CPPPATH and  $FORTRANPATH  construction  vari-
              ables when the $_CPPINCFLAGS and $_FORTRANINCFLAGS variables are
              automatically generated.


       INSTALL
              A function to be called to install a  file  into  a  destination
              file name.  The default function copies the file into the desti-
              nation (and sets the destination file's mode and permission bits
              to  match  the source file's).  The function takes the following
              arguments:

              def install(dest, source, env):

              _d_e_s_t is the path name of the destination file.   _s_o_u_r_c_e  is  the
              path  name of the source file.  _e_n_v is the construction environ-
              ment (a dictionary of construction values)  in  force  for  this
              file installation.


       INSTALLSTR
              The string displayed when a file is installed into a destination
              file name.  The default is:
              Install file: "$SOURCE" as "$TARGET"


       INTEL_C_COMPILER_VERSION
              Set by the "intelc" Tool to the  major  version  number  of  the
              Intel C compiler selected for use.


       JAR    The Java archive tool.


       JARCHDIR
              The  directory  to  which  the  Java  archive tool should change
              (using the --CC option).


       JARCOM The command line used to call the Java archive tool.


       JARCOMSTR
              The string displayed when the Java archive  tool  is  called  If
              this is not set, then $JARCOM (the command line) is displayed.

              env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")


       JARFLAGS
              General  options  passed  to  the Java archive tool.  By default
              this is set to ccff to create the necessary jjaarr file.


       JARSUFFIX
              The suffix for Java archives: ..jjaarr by default.


       JAVABOOTCLASSPATH
              Specifies the list of directories that  will  be  added  to  the
              &javac;  command  line via the --bboooottccllaassssppaatthh option.  The indi-
              vidual directory names will be separated by the  operating  sys-
              tem's  path separate character (:: on UNIX/Linux/POSIX, ;; on Win-
              dows).


       JAVAC  The Java compiler.


       JAVACCOM
              The command line used to compile  a  directory  tree  containing
              Java  source  files  to  corresponding  Java  class  files.  Any
              options specified in the $JAVACFLAGS construction  variable  are
              included on this command line.


       JAVACCOMSTR
              The  string  displayed  when  compiling a directory tree of Java
              source files to corresponding Java class files.  If this is  not
              set, then $JAVACCOM (the command line) is displayed.

              env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")


       JAVACFLAGS
              General options that are passed to the Java compiler.


       JAVACLASSDIR
              The  directory  in which Java class files may be found.  This is
              stripped from the beginning of any Java .class file  names  sup-
              plied to the JJaavvaaHH builder.


       JAVACLASSPATH
              Specifies the list of directories that will be searched for Java
              ..ccllaassss file.  The directories in this list will be added to  the
              &javac;  and  &javah;  command  lines via the --ccllaassssppaatthh option.
              The individual directory names will be separated by the  operat-
              ing  system's  path separate character (:: on UNIX/Linux/POSIX, ;;
              on Windows).

              Note that this currently just adds the specified  directory  via
              the  --ccllaassssppaatthh  option.   &SCons; does not currently search the
              $JAVACLASSPATH directories for dependency ..ccllaassss files.


       JAVACLASSSUFFIX
              The suffix for Java class files; ..ccllaassss by default.


       JAVAH  The Java generator for C header and stub files.


       JAVAHCOM
              The command line used to generate C header and stub  files  from
              Java   classes.    Any  options  specified  in  the  $JAVAHFLAGS
              construction variable are included on this command line.


       JAVAHCOMSTR
              The string displayed when C header and stub files are  generated
              from Java classes.  If this is not set, then $JAVAHCOM (the com-
              mand line) is displayed.

              env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES")


       JAVAHFLAGS
              General options passed to the C header and stub  file  generator
              for Java classes.


       JAVASOURCEPATH
              Specifies  the  list  of  directories  that will be searched for
              input ..jjaavvaa file.  The directories in this list will be added to
              the  &javac; command line via the --ssoouurrcceeppaatthh option.  The indi-
              vidual directory names will be separated by the  operating  sys-
              tem's  path separate character (:: on UNIX/Linux/POSIX, ;; on Win-
              dows).

              Note that this currently just adds the specified  directory  via
              the  --ssoouurrcceeppaatthh  option.  &SCons; does not currently search the
              $JAVASOURCEPATH directories for dependency ..jjaavvaa files.


       JAVASUFFIX
              The suffix for Java files; ..jjaavvaa by default.


       JAVAVERSION
              Specifies the Java version being used  by  the  JJaavvaa()  builder.
              This  is  _n_o_t  currently  used to select one version of the Java
              compiler vs. another.  Instead, you should set this  to  specify
              the  version  of  Java  supported by your &javac; compiler.  The
              default is 11..44.

              This is sometimes necessary because Java 1.5  changed  the  file
              names that are created for nested anonymous inner classes, which
              can cause a mismatch with the files that &SCons; expects will be
              generated  by the &javac; compiler.  Setting $JAVAVERSION to 11..55
              (or 11..66, as appropriate) can make &SCons; realize  that  a  Java
              1.5 or 1.6 build is actually up to date.


       LATEX  The LaTeX structured formatter and typesetter.


       LATEXCOM
              The command line used to call the LaTeX structured formatter and
              typesetter.


       LATEXCOMSTR
              The string displayed when calling the LaTeX structured formatter
              and typesetter.  If this is not set, then $LATEXCOM (the command
              line) is displayed.

              env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")


       LATEXFLAGS
              General options passed to the  LaTeX  structured  formatter  and
              typesetter.


       LATEXRETRIES
              The  maximum  number  of  times that LaTeX will be re-run if the
              ..lloogg generated by the $LATEXCOM command indicates that there are
              undefined  references.   The  default is to try to resolve unde-
              fined references by re-running LaTeX up to three times.


       LATEXSUFFIXES
              The list of suffixes of files that will  be  scanned  for  LaTeX
              implicit  dependencies (\\iinncclluuddee or \\iimmppoorrtt files).  The default
              list is:

              [".tex", ".ltx", ".latex"]


       LDMODULE
              The linker for building loadable modules.  By default,  this  is
              the same as $SHLINK.


       LDMODULECOM
              The  command  line  for building loadable modules.  On Mac OS X,
              this uses the  $LDMODULE,  $LDMODULEFLAGS  and  $FRAMEWORKSFLAGS
              variables.  On other systems, this is the same as $SHLINK.


       LDMODULECOMSTR
              The string displayed when building loadable modules.  If this is
              not set, then $LDMODULECOM (the command line) is displayed.


       LDMODULEFLAGS
              General user options passed to the linker for building  loadable
              modules.


       LDMODULEPREFIX
              The  prefix  used  for loadable module file names.  On Mac OS X,
              this is null; on other systems, this is the same  as  $SHLIBPRE-
              FIX.


       LDMODULESUFFIX
              The  suffix  used  for loadable module file names.  On Mac OS X,
              this is null; on other systems, this is the same  as  $SHLIBSUF-
              FIX.


       LEX    The lexical analyzer generator.


       LEXCOM The  command line used to call the lexical analyzer generator to
              generate a source file.


       LEXCOMSTR
              The string displayed when generating a  source  file  using  the
              lexical  analyzer  generator.   If this is not set, then $LEXCOM
              (the command line) is displayed.

              env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")


       LEXFLAGS
              General options passed to the lexical analyzer generator.


       _LIBDIRFLAGS
              An automatically-generated construction variable containing  the
              linker  command-line  options  for  specifying directories to be
              searched for library.  The value of $_LIBDIRFLAGS is created  by
              appending  $LIBDIRPREFIX  and $LIBDIRSUFFIX to the beginning and
              end of each directory in $LIBPATH.


       LIBDIRPREFIX
              The prefix used to specify a library  directory  on  the  linker
              command  line.   This  will be appended to the beginning of each
              directory in the $LIBPATH construction variable when the  $_LIB-
              DIRFLAGS variable is automatically generated.


       LIBDIRSUFFIX
              The  suffix  used  to  specify a library directory on the linker
              command line.  This will be appended to the end of  each  direc-
              tory  in  the  $LIBPATH  construction  variable  when the $_LIB-
              DIRFLAGS variable is automatically generated.


       _LIBFLAGS
              An automatically-generated construction variable containing  the
              linker  command-line  options  for  specifying  libraries  to be
              linked with the resulting target.  The value  of  $_LIBFLAGS  is
              created  by  appending  $LIBLINKPREFIX and $LIBLINKSUFFIX to the
              beginning and end of each filename in $LIBS.


       LIBLINKPREFIX
              The prefix used to specify a library to link on the linker  com-
              mand  line.   This  will  be  appended  to the beginning of each
              library in the $LIBS construction variable when  the  $_LIBFLAGS
              variable is automatically generated.


       LIBLINKSUFFIX
              The  suffix used to specify a library to link on the linker com-
              mand line.  This will be appended to the end of each library  in
              the  $LIBS construction variable when the $_LIBFLAGS variable is
              automatically generated.


       LIBPATH
              The list of directories that will  be  searched  for  libraries.
              The  implicit  dependency  scanner will search these directories
              for include files. Don't explicitly put include directory  argu-
              ments  in  $LINKFLAGS or $SHLINKFLAGS because the result will be
              non-portable and the directories will not  be  searched  by  the
              dependency  scanner.  Note:  directory  names in LIBPATH will be
              looked-up relative to the SConscript  directory  when  they  are
              used  in  a command. To force ssccoonnss to look-up a directory rela-
              tive to the root of the source tree use #:

              env = Environment(LIBPATH='#/libs')

              The directory look-up can also be forced using the  DDiirr()  func-
              tion:

              libs = Dir('libs')
              env = Environment(LIBPATH=libs)

              The  directory  list  will be added to command lines through the
              automatically-generated  $_LIBDIRFLAGS  construction   variable,
              which  is constructed by appending the values of the $LIBDIRPRE-
              FIX and $LIBDIRSUFFIX construction variables  to  the  beginning
              and  end  of  each directory in $LIBPATH.  Any command lines you
              define that need  the  LIBPATH  directory  list  should  include
              $_LIBDIRFLAGS:

              env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")


       LIBPREFIX
              The  prefix  used  for  (static)  library file names.  A default
              value is set for each platform (posix, win32,  os2,  etc.),  but
              the  value  is overridden by individual tools (ar, mslib, sgiar,
              sunar, tlib, etc.)  to reflect the names of the  libraries  they
              create.


       LIBPREFIXES
              A  list  of  all  legal  prefixes  for library file names.  When
              searching for library dependencies, SCons will  look  for  files
              with  these prefixes, the base library name, and suffixes in the
              $LIBSUFFIXES list.


       LIBS   A list of one or more libraries that will  be  linked  with  any
              executable programs created by this environment.

              The  library  list  will  be  added to command lines through the
              automatically-generated $_LIBFLAGS construction variable,  which
              is constructed by appending the values of the $LIBLINKPREFIX and
              $LIBLINKSUFFIX construction variables to the beginning  and  end
              of  each  filename  in $LIBS.  Any command lines you define that
              need the LIBS library list should include $_LIBFLAGS:

              env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")

              If you add a File object to the $LIBS list,  the  name  of  that
              file will be added to $_LIBFLAGS, and thus the link line, as is,
              without $LIBLINKPREFIX or $LIBLINKSUFFIX.  For example:

              env.Append(LIBS=File('/tmp/mylib.so'))

              In all cases, scons will add dependencies  from  the  executable
              program to all the libraries in this list.


       LIBSUFFIX
              The  suffix  used  for  (static)  library file names.  A default
              value is set for each platform (posix, win32,  os2,  etc.),  but
              the  value  is overridden by individual tools (ar, mslib, sgiar,
              sunar, tlib, etc.)  to reflect the names of the  libraries  they
              create.


       LIBSUFFIXES
              A  list  of  all  legal  suffixes  for library file names.  When
              searching for library dependencies, SCons will  look  for  files
              with  prefixes, in the $LIBPREFIXES list, the base library name,
              and these suffixes.


       LICENSE
              The abbreviated name of the license under which this project  is
              released   (gpl,   lpgl,   bsd   etc.).    See  http://www.open-
              source.org/licenses/alphabetical for a list of license names.


       LINK   The linker.


       LINKCOM
              The command line used to link object files into an executable.


       LINKCOMSTR
              The string displayed when object files are linked into  an  exe-
              cutable.   If  this is not set, then $LINKCOM (the command line)
              is displayed.

              env = Environment(LINKCOMSTR = "Linking $TARGET")


       LINKFLAGS
              General user options passed to the linker.  Note that this vari-
              able should _n_o_t contain --ll (or similar) options for linking with
              the libraries listed in  $LIBS,  nor  --LL  (or  similar)  library
              search  path  options  that  scons  generates automatically from
              $LIBPATH.  See $_LIBFLAGS above, for the variable  that  expands
              to  library-link options, and $_LIBDIRFLAGS above, for the vari-
              able that expands to library search path options.


       M4     The M4 macro preprocessor.


       M4COM  The command line used to pass files through the M4 macro prepro-
              cessor.


       M4COMSTR
              The  string displayed when a file is passed through the M4 macro
              preprocessor.  If this is not  set,  then  $M4COM  (the  command
              line) is displayed.


       M4FLAGS
              General options passed to the M4 macro preprocessor.


       MAKEINDEX
              The makeindex generator for the TeX formatter and typesetter and
              the LaTeX structured formatter and typesetter.


       MAKEINDEXCOM
              The command line used to call the makeindex  generator  for  the
              TeX  formatter and typesetter and the LaTeX structured formatter
              and typesetter.


       MAKEINDEXCOMSTR
              The string displayed when calling the  makeindex  generator  for
              the  TeX  formatter and typesetter and the LaTeX structured for-
              matter and typesetter.  If this is not set,  then  $MAKEINDEXCOM
              (the command line) is displayed.


       MAKEINDEXFLAGS
              General  options  passed  to the makeindex generator for the TeX
              formatter and typesetter and the LaTeX structured formatter  and
              typesetter.


       MAXLINELENGTH
              The  maximum number of characters allowed on an external command
              line.  On Win32 systems, link lines longer than this many  char-
              acters are linked via a temporary file name.


       MIDL   The Microsoft IDL compiler.


       MIDLCOM
              The  command  line  used to pass files to the Microsoft IDL com-
              piler.


       MIDLCOMSTR
              The string displayed when the Microsoft IDL copmiler is  called.
              If  this  is  not  set, then $MIDLCOM (the command line) is dis-
              played.


       MIDLFLAGS
              General options passed to the Microsoft IDL compiler.


       MSVS   When the Microsoft Visual Studio tools are initialized, they set
              up this dictionary with the following keys:

              VVEERRSSIIOONN:  the  version  of  MSVS  being  used  (can  be  set via
              MSVS_VERSION)

              VVEERRSSIIOONNSS: the available versions of MSVS installed

              VVCCIINNSSTTAALLLLDDIIRR: installed directory of Visual C++

              VVSSIINNSSTTAALLLLDDIIRR: installed directory of Visual Studio

              FFRRAAMMEEWWOORRKKDDIIRR: installed directory of the .NET framework

              FFRRAAMMEEWWOORRKKVVEERRSSIIOONNSS: list of installed versions of the .NET frame-
              work, sorted latest to oldest.

              FFRRAAMMEEWWOORRKKVVEERRSSIIOONN: latest installed version of the .NET framework

              FFRRAAMMEEWWOORRKKSSDDKKDDIIRR: installed location of the .NET SDK.

              PPLLAATTFFOORRMMSSDDKKDDIIRR: installed location of the Platform SDK.

              PPLLAATTFFOORRMMSSDDKK__MMOODDUULLEESS: dictionary of installed Platform  SDK  mod-
              ules,  where  the  dictionary  keys are keywords for the various
              modules, and the values are 2-tuples  where  the  first  is  the
              release date, and the second is the version number.

              If a value isn't set, it wasn't available in the registry.


       MSVS_IGNORE_IDE_PATHS
              Tells  the  MS  Visual Studio tools to use minimal INCLUDE, LIB,
              and PATH settings, instead of the settings from the IDE.

              For Visual Studio, SCons will (by default) automatically  deter-
              mine where MSVS is installed, and use the LIB, INCLUDE, and PATH
              variables set by the IDE.  You can  override  this  behavior  by
              setting  these variables after Environment initialization, or by
              setting MMSSVVSS__IIGGNNOORREE__IIDDEE__PPAATTHHSS == 11 in the Environment initializa-
              tion.   Specifying this will not leave these unset, but will set
              them to a minimal set of paths needed to run the tools  success-
              fully.

              For VS6, the mininimal set is:
                 INCLUDE:'<VSDir>\VC98\ATL\include;<VSDir>\VC98\MFC\include;<VSDir>\VC98\include'
                 LIB:'<VSDir>\VC98\MFC\lib;<VSDir>\VC98\lib'
                 PATH:'<VSDir>\Common\MSDev98\bin;<VSDir>\VC98\bin'
       For VS7, it is:
                 INCLUDE:'<VSDir>\Vc7\atlmfc\include;<VSDir>\Vc7\include'
                 LIB:'<VSDir>\Vc7\atlmfc\lib;<VSDir>\Vc7\lib'
                 PATH:'<VSDir>\Common7\Tools\bin;<VSDir>\Common7\Tools;<VSDir>\Vc7\bin'

              Where '<VSDir>' is the installed location of Visual Studio.


       MSVS_PROJECT_BASE_PATH
              The  string  placed in a generated Microsoft Visual Studio solu-
              tion file as the value of the SSccccPPrroojjeeccttFFiilleePPaatthhRReellaattiivviizzeeddFFrroomm--
              CCoonnnneeccttiioonn00   and   SSccccPPrroojjeeccttFFiilleePPaatthhRReellaattiivviizzeeddFFrroommCCoonnnneeccttiioonn11
              attributes  of  the  GGlloobbaallSSeeccttiioonn((SSoouurrcceeCCooddeeCCoonnttrrooll))   section.
              There is no default value.


       MSVS_PROJECT_GUID
              The string placed in a generated Microsoft Visual Studio project
              file as the value of the PPrroojjeeccttGGUUIIDD attribute.  The  string  is
              also  placed in the SSoolluuttiioonnUUnniiqquueeIIDD attribute of the GGlloobbaallSSeecc--
              ttiioonn((SSoouurrcceeCCooddeeCCoonnttrrooll)) section of the Microsoft  Visual  Studio
              solution file.  There is no default value.


       MSVS_SCC_AUX_PATH
              The  path  name  placed  in  a generated Microsoft Visual Studio
              project file as the value of the  SSccccAAuuxxPPaatthh  attribute  if  the
              MMSSVVSS__SSCCCC__PPRROOVVIIDDEERR  construction  variable is also set.  There is
              no default value.


       MSVS_SCC_LOCAL_PATH
              The path name placed in  a  generated  Microsoft  Visual  Studio
              project  file  as the value of the SSccccLLooccaallPPaatthh attribute if the
              MMSSVVSS__SSCCCC__PPRROOVVIIDDEERR construction variable is also set.   The  path
              name  is  also  placed  in  the  SSccccLLooccaallPPaatthh00 and SSccccLLooccaallPPaatthh11
              attributes of the  GGlloobbaallSSeeccttiioonn((SSoouurrcceeCCooddeeCCoonnttrrooll))  section  of
              the  Microsoft Visual Studio solution file.  There is no default
              value.


       MSVS_SCC_PROJECT_NAME
              The project name placed in a generated Microsoft  Visual  Studio
              project  file  as  the  value  of  the SSccccPPrroojjeeccttNNaammee attribute.
              There is no default value.


       MSVS_SCC_PROVIDER
              The string placed in a generated Microsoft Visual Studio project
              file  as  the value of the SSccccPPrroovviiddeerr attribute.  The string is
              also placed in the  SSccccPPrroovviiddeerr11  attribute  of  the  GGlloobbaallSSeecc--
              ttiioonn((SSoouurrcceeCCooddeeCCoonnttrrooll))  section  of the Microsoft Visual Studio
              solution file.  There is no default value.


       MSVS_USE_MFC_DIRS
              Tells the MS Visual Studio tool(s) to use the MFC directories in
              its    default   paths   for   compiling   and   linking.    The
              $MSVS_USE_MFC_DIRS variable has no effect if the IINNCCLLUUDDEE or  LLIIBB
              environment variables are set explictly.

              Under  Visual  Studio version 6, setting $MSVS_USE_MFC_DIRS to a
              non-zero value adds the AATTLL\\AATTLL and MMFFCC\\MMFFCC directories  to  the
              default  IINNCCLLUUDDEE  external  environment  variable,  and adds the
              MMFFCC\\MMFFCC directory to the default LLIIBB external environment  vari-
              able.

              Under  Visual  Studio version 7, setting $MSVS_USE_MFC_DIRS to a
              non-zero value adds the aattllmmffcc\\aattllmmffcc directory to  the  default
              IINNCCLLUUDDEE    external   environment   variable,   and   adds   the
              aattllmmffcc\\aattllmmffcc directory to the default LLIIBB external  environment
              variable.

              Under  Visual  Studio version 8, setting $MSVS_USE_MFC_DIRS to a
              non-zero value will, by default, add the aattllmmffcc\\aattllmmffcc directory
              to  the  default  IINNCCLLUUDDEE external environment variable, and the
              aattllmmffcc\\aattllmmffcc directory to the default LLIIBB external  environment
              variable.   If, however, the [[''MMSSVVSS'']][[''PPLLAATTFFOORRMMSSDDKKDDIIRR'']] variable
              is set, then the mmffcc and the aattll  subdirectories  of  the  PPLLAATT--
              FFOORRMMSSDDKKDDIIRR  are added to the default value of the IINNCCLLUUDDEE exter-
              nal environment variable, and  the  default  value  of  the  LLIIBB
              external environment variable is left untouched.


       MSVS_VERSION
              Sets the preferred version of MSVS to use.

              SCons  will  (by  default)  select  the  latest  version of MSVS
              installed on your machine.  So, if you have version 6  and  ver-
              sion 7 (MSVS .NET) installed, it will prefer version 7.  You can
              override this by specifying the  MMSSVVSS__VVEERRSSIIOONN  variable  in  the
              Environment  initialization,  setting it to the appropriate ver-
              sion ('6.0' or '7.0', for example).  If the given version  isn't
              installed, tool initialization will fail.


       MSVSBUILDCOM
              The  build  command  line placed in a generated Microsoft Visual
              Studio project file.  The  default  is  to  have  Visual  Studio
              invoke SCons with any specified build targets.


       MSVSCLEANCOM
              The  clean  command  line placed in a generated Microsoft Visual
              Studio project file.  The  default  is  to  have  Visual  Studio
              invoke SCons with the -c option to remove any specified targets.


       MSVSENCODING
              The encoding string placed in a generated Microsoft Visual  Stu-
              dio project file.  The default is encoding WWiinnddoowwss--11225522.


       MSVSPROJECTCOM
              The  action  used  to  generate  Microsoft Visual Studio project
              files.


       MSVSPROJECTSUFFIX
              The suffix used for Microsoft Visual Studio project (DSP) files.
              The  default  value  is ..vvccpprroojj when using Visual Studio version
              7.x (.NET) or later version, and ..ddsspp when  using  earlier  ver-
              sions of Visual Studio.


       MSVSREBUILDCOM
              The  rebuild command line placed in a generated Microsoft Visual
              Studio project file.  The  default  is  to  have  Visual  Studio
              invoke SCons with any specified rebuild targets.


       MSVSSCONS
              The  SCons  used  in  generated  Microsoft Visual Studio project
              files.  The default is the version of SCons being used to gener-
              ate the project file.


       MSVSSCONSCOM
              The  default  SCons  command  used in generated Microsoft Visual
              Studio project files.


       MSVSSCONSCRIPT
              The sconscript file (that is,  SSCCoonnssttrruucctt  or  SSCCoonnssccrriipptt  file)
              that will be invoked by Visual Studio project files (through the
              $MSVSSCONSCOM variable).  The default  is  the  same  sconscript
              file  that  contains  the  call  to  MMSSVVSSPPrroojjeecctt()  to build the
              project file.


       MSVSSCONSFLAGS
              The SCons  flags  used  in  generated  Microsoft  Visual  Studio
              project files.


       MSVSSOLUTIONCOM
              The  action  used  to  generate Microsoft Visual Studio solution
              files.


       MSVSSOLUTIONSUFFIX
              The suffix used  for  Microsoft  Visual  Studio  solution  (DSW)
              files.   The default value is ..ssllnn when using Visual Studio ver-
              sion 7.x (.NET), and ..ddssww when using earlier versions of  Visual
              Studio.


       MWCW_VERSION
              The  version  number of the MetroWerks CodeWarrior C compiler to
              be used.


       MWCW_VERSIONS
              A list of installed versions of  the  MetroWerks  CodeWarrior  C
              compiler on this system.


       NAME   Specfies the name of the project to package.


       no_import_lib
              When  set  to  non-zero,  suppresses creation of a corresponding
              Windows static import lib by the SShhaarreeddLLiibbrraarryy builder when used
              with  MinGW,  Microsoft  Visual Studio or Metrowerks.  This also
              suppresses  creation  of  an  export  (.exp)  file  when   using
              Microsoft Visual Studio.


       OBJPREFIX
              The prefix used for (static) object file names.


       OBJSUFFIX
              The suffix used for (static) object file names.


       P4     The Perforce executable.


       P4COM  The command line used to fetch source files from Perforce.


       P4COMSTR
              The  string displayed when fetching a source file from Perforce.
              If this is not set, then $P4COM (the command line) is displayed.


       P4FLAGS
              General options that are passed to Perforce.


       PACKAGEROOT
              Specifies  the  directory  where  all files in resulting archive
              will be placed if applicable.  The default value is "$NAME-$VER-
              SION".


       PACKAGETYPE
              Selects  the  package type to build.  Currently these are avail-
              able:

               * msi - Microsoft Installer
               * rpm - Redhat Package Manger
               * ipkg - Itsy Package Management System
               * tarbz2 - compressed tar
               * targz - compressed tar
               * zip - zip file
               * src_tarbz2 - compressed tar source
               * src_targz - compressed tar source
               * src_zip - zip file source

              This may be overridden  with  the  "package_type"  command  line
              option.


       PACKAGEVERSION
              The  version  of the package (not the underlying project).  This
              is currently only used by the rpm packager  and  should  reflect
              changes  in  the  packaging,  not  the  underlying  project code
              itself.


       PCH    The Microsoft Visual C++ precompiled header that  will  be  used
              when  compiling  object files. This variable is ignored by tools
              other than Microsoft Visual C++.  When this variable is  defined
              SCons  will add options to the compiler command line to cause it
              to use the precompiled header, and will also set up  the  depen-
              dencies for the PCH file.  Example:

              env['PCH'] = 'StdAfx.pch'


       PCHCOM The  command  line used by the PPCCHH() builder to generated a pre-
              compiled header.


       PCHCOMSTR
              The string displayed when generating a precompiled  header.   If
              this is not set, then $PCHCOM (the command line) is displayed.


       PCHPDBFLAGS
              A  construction  variable that, when expanded, adds the //yyDD flag
              to the command line only if the $PDB  construction  variable  is
              set.


       PCHSTOP
              This  variable  specifies  how  much of a source file is precom-
              piled. This variable is ignored by tools  other  than  Microsoft
              Visual  C++,  or  when  the PCH variable is not being used. When
              this variable is define it must be a string that is the name  of
              the  header  that is included at the end of the precompiled por-
              tion of the source files, or the empty string  if  the  "#pragma
              hrdstop" construct is being used:

              env['PCHSTOP'] = 'StdAfx.h'


       PDB    The  Microsoft  Visual  C++  PDB  file that will store debugging
              information for object files, shared  libraries,  and  programs.
              This  variable  is  ignored by tools other than Microsoft Visual
              C++.  When this variable is defined SCons will  add  options  to
              the  compiler  and linker command line to cause them to generate
              external debugging information, and will also set up the  depen-
              dencies for the PDB file.  Example:

              env['PDB'] = 'hello.pdb'

              The  Visual  C++  compiler  switch that SCons uses by default to
              generate PDB information is //ZZ77.  This works correctly with par-
              allel (--jj) builds because it embeds the debug information in the
              intermediate object files, as opposed to sharing  a  single  PDB
              file  between  multiple object files.  This is also the only way
              to get debug information embedded into a static library.   Using
              the  //ZZii  instead  may  yield  improved  link-time  performance,
              although parallel builds will no longer work.  You can  generate
              PDB  files  with  the  //ZZii  switch  by  overriding  the  default
              $CCPDBFLAGS variable; see the entry for that variable  for  spe-
              cific examples.


       PDFCOM A deprecated synonym for $DVIPDFCOM.


       PDFLATEX
              The &pdflatex; utility.


       PDFLATEXCOM
              The command line used to call the &pdflatex; utility.


       PDFLATEXCOMSTR
              The  string  displayed  when calling the &pdflatex; utility.  If
              this is not set, then $PDFLATEXCOM (the command  line)  is  dis-
              played.

              env = Environment(PDFLATEX;COMSTR = "Building $TARGET from LaTeX input $SOURCES")


       PDFLATEXFLAGS
              General options passed to the &pdflatex; utility.


       PDFPREFIX
              The prefix used for PDF file names.


       PDFSUFFIX
              The suffix used for PDF file names.


       PDFTEX The &pdftex; utility.


       PDFTEXCOM
              The command line used to call the &pdftex; utility.


       PDFTEXCOMSTR
              The string displayed when calling the &pdftex; utility.  If this
              is not set, then $PDFTEXCOM (the command line) is displayed.

              env = Environment(PDFTEXCOMSTR = "Building $TARGET from TeX input $SOURCES")


       PDFTEXFLAGS
              General options passed to the &pdftex; utility.


       PKGCHK On Solaris systems, the package-checking program  that  will  be
              used (along with $PKGINFO) to look for installed versions of the
              Sun PRO C++ compiler.  The default is //uussrr//ssbbiinn//ppggkkcchhkk.


       PKGINFO
              On Solaris systems, the package information program that will be
              used  (along with $PKGCHK) to look for installed versions of the
              Sun PRO C++ compiler.  The default is ppkkggiinnffoo.


       PLATFORM
              The name of the platform used to create the Environment.  If  no
              platform  is  specified  when  the Environment is created, ssccoonnss
              autodetects the platform.

              env = Environment(tools = [])
              if env['PLATFORM'] == 'cygwin':
                  Tool('mingw')(env)
              else:
                  Tool('msvc')(env)


       PRINT_CMD_LINE_FUNC
              A Python function used to print the command lines  as  they  are
              executed (assuming command printing is not disabled by the --qq or
              --ss options or their equivalents).  The function should take four
              arguments: _s, the command being executed (a string), _t_a_r_g_e_t, the
              target being built (file node, list, or string name(s)), _s_o_u_r_c_e,
              the  source(s)  used  (file  node, list, or string name(s)), and
              _e_n_v, the environment being used.

              The function must do the printing itself.  The default implemen-
              tation, used if this variable is not set or is None, is:
              def print_cmd_line(s, target, source, env):
                sys.stdout.write(s + "\n")

              Here's an example of a more interesting function:

              def print_cmd_line(s, target, source, env):
                 sys.stdout.write("Building %s -> %s...\n" %
                  (' and '.join([str(x) for x in source]),
                   ' and '.join([str(x) for x in target])))
              env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
              env.Program('foo', 'foo.c')

              This   just  prints  "Building  _t_a_r_g_e_t_n_a_m_e  from  _s_o_u_r_c_e_n_a_m_e..."
              instead of the actual commands.  Such a function could also  log
              the actual commands to a log file, for example.


       PROGPREFIX
              The prefix used for executable file names.


       PROGSUFFIX
              The suffix used for executable file names.


       PSCOM  The command line used to convert TeX DVI files into a PostScript
              file.


       PSCOMSTR
              The string displayed when a TeX DVI file  is  converted  into  a
              PostScript  file.   If this is not set, then $PSCOM (the command
              line) is displayed.


       PSPREFIX
              The prefix used for PostScript file names.


       PSSUFFIX
              The prefix used for PostScript file names.


       QT_AUTOSCAN
              Turn off scanning for mocable files.  Use  the  Moc  Builder  to
              explicitely specify files to run moc on.


       QT_BINPATH
              The path where the qt binaries are installed.  The default value
              is '$QTDIR/bin'.


       QT_CPPPATH
              The path where the qt header files are installed.   The  default
              value  is  '$QTDIR/include'.   Note: If you set this variable to
              None, the tool won't change the $CPPPATH construction  variable.


       QT_DEBUG
              Prints  lots  of  debugging  information  while scanning for moc
              files.


       QT_LIB Default value is 'qt'. You may want  to  set  this  to  'qt-mt'.
              Note:  If  you  set this variable to None, the tool won't change
              the $LIBS variable.


       QT_LIBPATH
              The path where the qt  libraries  are  installed.   The  default
              value  is '$QTDIR/lib'.  Note: If you set this variable to None,
              the tool won't change the $LIBPATH construction variable.


       QT_MOC Default value is '$QT_BINPATH/moc'.


       QT_MOCCXXPREFIX
              Default value is ''. Prefix for moc output files, when source is
              a cxx file.


       QT_MOCCXXSUFFIX
              Default  value  is  '.moc'.  Suffix  for  moc output files, when
              source is a cxx file.


       QT_MOCFROMCXXCOM
              Command to generate a moc file from a cpp file.


       QT_MOCFROMCXXCOMSTR
              The string displayed when generating a moc file from a cpp file.
              If this is not set, then $QT_MOCFROMCXXCOM (the command line) is
              displayed.


       QT_MOCFROMCXXFLAGS
              Default value is '-i'. These flags are passed to moc, when mocc-
              ing a C++ file.


       QT_MOCFROMHCOM
              Command to generate a moc file from a header.


       QT_MOCFROMHCOMSTR
              The string displayed when generating a moc file from a cpp file.
              If this is not set, then $QT_MOCFROMHCOM (the command  line)  is
              displayed.


       QT_MOCFROMHFLAGS
              Default value is ''. These flags are passed to moc, when moccing
              a header file.


       QT_MOCHPREFIX
              Default value is 'moc_'.  Prefix  for  moc  output  files,  when
              source is a header.


       QT_MOCHSUFFIX
              Default  value is '$CXXFILESUFFIX'. Suffix for moc output files,
              when source is a header.


       QT_UIC Default value is '$QT_BINPATH/uic'.


       QT_UICCOM
              Command to generate header files from .ui files.


       QT_UICCOMSTR
              The string displayed  when  generating  header  files  from  .ui
              files.   If  this is not set, then $QT_UICCOM (the command line)
              is displayed.


       QT_UICDECLFLAGS
              Default value is ''. These flags are passed to uic, when  creat-
              ing a a h file from a .ui file.


       QT_UICDECLPREFIX
              Default value is ''. Prefix for uic generated header files.


       QT_UICDECLSUFFIX
              Default value is '.h'. Suffix for uic generated header files.


       QT_UICIMPLFLAGS
              Default  value is ''. These flags are passed to uic, when creat-
              ing a cxx file from a .ui file.


       QT_UICIMPLPREFIX
              Default value is 'uic_'. Prefix for uic generated implementation
              files.


       QT_UICIMPLSUFFIX
              Default  value  is  '$CXXFILESUFFIX'.  Suffix  for uic generated
              implementation files.


       QT_UISUFFIX
              Default value is '.ui'. Suffix of designer input files.


       QTDIR  The qt tool tries to take this from os.environ.   It  also  ini-
              tializes  all  QT_*  construction variables listed below.  (Note
              that all paths  are  constructed  with  python's  os.path.join()
              method,  but  are  listed here with the '/' separator for easier
              reading.)  In addition, the construction  environment  variables
              $CPPPATH,  $LIBPATH  and $LIBS may be modified and the variables
              PROGEMITTER, SHLIBEMITTER and LIBEMITTER are  modified.  Because
              the build-performance is affected when using this tool, you have
              to explicitly specify it at Environment creation:

              Environment(tools=['default','qt'])

              The qt tool supports the following operations:

              _A_u_t_o_m_a_t_i_c _m_o_c _f_i_l_e _g_e_n_e_r_a_t_i_o_n _f_r_o_m _h_e_a_d_e_r  _f_i_l_e_s_.   You  do  not
              have  to specify moc files explicitly, the tool does it for you.
              However, there are a few preconditions to  do  so:  Your  header
              file must have the same filebase as your implementation file and
              must stay in the same directory. It must have one  of  the  suf-
              fixes  .h,  .hpp,  .H, .hxx, .hh. You can turn off automatic moc
              file generation by setting QT_AUTOSCAN to 0.  See also the  cor-
              responding builder method MMoocc(())

              _A_u_t_o_m_a_t_i_c  _m_o_c _f_i_l_e _g_e_n_e_r_a_t_i_o_n _f_r_o_m _c_x_x _f_i_l_e_s_.  As stated in the
              qt documentation, include the moc file at the  end  of  the  cxx
              file. Note that you have to include the file, which is generated
              by  the   transformation   ${QT_MOCCXXPREFIX}<basename>${QT_MOC-
              CXXSUFFIX},  by  default  <basename>.moc. A warning is generated
              after building the moc file, if you do not include  the  correct
              file.  If  you  are  using  VariantDir,  you may need to specify
              duplicate=1. You can turn off automatic moc file  generation  by
              setting  QT_AUTOSCAN  to  0.  See  also  the corresponding MMoocc()
              builder method.

              _A_u_t_o_m_a_t_i_c _h_a_n_d_l_i_n_g _o_f _._u_i _f_i_l_e_s_.  The implementation files  gen-
              erated  from  .ui files are handled much the same as yacc or lex
              files. Each .ui file given as a source of  Program,  Library  or
              SharedLibrary  will  generate three files, the declaration file,
              the implementation file and a moc file. Because there  are  also
              generated  headers, you may need to specify duplicate=1 in calls
              to VariantDir.  See also the corresponding UUiicc() builder method.


       RANLIB The archive indexer.


       RANLIBCOM
              The command line used to index a static library archive.


       RANLIBCOMSTR
              The  string  displayed when a static library archive is indexed.
              If this is not  set,  then  $RANLIBCOM  (the  command  line)  is
              displayed.

              env = Environment(RANLIBCOMSTR = "Indexing $TARGET")


       RANLIBFLAGS
              General options passed to the archive indexer.


       RC     The  resource  compiler  used  to  build  a Microsoft Visual C++
              resource file.


       RCCOM  The command line used to build a Microsoft Visual  C++  resource
              file.


       RCCOMSTR
              The  string  displayed  when  invoking  the resource compiler to
              build a Microsoft Visual C++ resource file.  If this is not set,
              then $RCCOM (the command line) is displayed.


       RCFLAGS
              The flags passed to the resource compiler by the RES builder.


       RCINCFLAGS
              An  automatically-generated construction variable containing the
              command-line options for specifying directories to  be  searched
              by  the  resource compiler.  The value of $RCINCFLAGS is created
              by appending $RCINCPREFIX and $RCINCSUFFIX to the beginning  and
              end of each directory in $CPPPATH.


       RCINCPREFIX
              The  prefix  (flag)  used to specify an include directory on the
              resource compiler command line.  This will be  appended  to  the
              beginning  of  each directory in the $CPPPATH construction vari-
              able when the $RCINCFLAGS variable is expanded.


       RCINCSUFFIX
              The suffix used to specify an include directory on the  resource
              compiler command line.  This will be appended to the end of each
              directory  in  the  $CPPPATH  construction  variable  when   the
              $RCINCFLAGS variable is expanded.


       RCS    The  RCS  executable.   Note  that this variable is not actually
              used for the command to fetch source files  from  RCS;  see  the
              $RCS_CO construction variable, below.


       RCS_CO The  RCS  "checkout" executable, used to fetch source files from
              RCS.


       RCS_COCOM
              The command line used to fetch (checkout) source files from RCS.


       RCS_COCOMSTR
              The  string  displayed when fetching a source file from RCS.  If
              this is not set, then $RCS_COCOM  (the  command  line)  is  dis-
              played.


       RCS_COFLAGS
              Options that are passed to the $RCS_CO command.


       RDirs  A  function  that converts a string into a list of Dir instances
              by searching the repositories.


       REGSVR The program used on Windows systems to  register  a  newly-built
              DLL  library  whenever  the  SShhaarreeddLLiibbrraarryy() builder is passed a
              keyword argument of rreeggiisstteerr==11.


       REGSVRCOM
              The command line used on Windows systems to  register  a  newly-
              built DLL library whenever the SShhaarreeddLLiibbrraarryy() builder is passed
              a keyword argument of rreeggiisstteerr==11.


       REGSVRCOMSTR
              The string displayed when registering a  newly-built  DLL  file.
              If  this  is  not  set,  then  $REGSVRCOM  (the command line) is
              displayed.


       REGSVRFLAGS
              Flags passed to the DLL registration program on Windows  systems
              when  a newly-built DLL library is registered.  By default, this
              includes the //ss that prevents dialog boxes from popping  up  and
              requiring user attention.


       RMIC   The Java RMI stub compiler.


       RMICCOM
              The  command  line used to compile stub and skeleton class files
              from Java classes that contain RMI implementations.  Any options
              specified  in  the $RMICFLAGS construction variable are included
              on this command line.


       RMICCOMSTR
              The string displayed when  compiling  stub  and  skeleton  class
              files  from  Java  classes that contain RMI implementations.  If
              this is not set, then $RMICCOM (the command line) is  displayed.

              env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")


       RMICFLAGS
              General options passed to the Java RMI stub compiler.


       _RPATH An  automatically-generated construction variable containing the
              rpath flags to be  used  when  linking  a  program  with  shared
              libraries.  The value of $_RPATH is created by appending $RPATH-
              PREFIX and $RPATHSUFFIX to the beginning and end of each  direc-
              tory in $RPATH.


       RPATH  A list of paths to search for shared libraries when running pro-
              grams.  Currently only used in the GNU (gnulink), IRIX (sgilink)
              and  Sun (sunlink) linkers.  Ignored on platforms and toolchains
              that don't support it.  Note that the paths added to  RPATH  are
              not  transformed  by  ssccoonnss in any way:  if you want an absolute
              path, you must make it absolute yourself.


       RPATHPREFIX
              The prefix used to specify a directory to be searched for shared
              libraries  when  running programs.  This will be appended to the
              beginning of each directory in the $RPATH construction  variable
              when the $_RPATH variable is automatically generated.


       RPATHSUFFIX
              The suffix used to specify a directory to be searched for shared
              libraries when running programs.  This will be appended  to  the
              end  of  each directory in the $RPATH construction variable when
              the $_RPATH variable is automatically generated.


       RPCGEN The RPC protocol compiler.


       RPCGENCLIENTFLAGS
              Options passed to the  RPC  protocol  compiler  when  generating
              client side stubs.  These are in addition to any flags specified
              in the $RPCGENFLAGS construction variable.


       RPCGENFLAGS
              General options passed to the RPC protocol compiler.


       RPCGENHEADERFLAGS
              Options passed to the RPC protocol compiler  when  generating  a
              header  file.   These  are in addition to any flags specified in
              the $RPCGENFLAGS construction variable.


       RPCGENSERVICEFLAGS
              Options passed to the  RPC  protocol  compiler  when  generating
              server side stubs.  These are in addition to any flags specified
              in the $RPCGENFLAGS construction variable.


       RPCGENXDRFLAGS
              Options passed to the RPC protocol compiler when generating  XDR
              routines.   These  are in addition to any flags specified in the
              $RPCGENFLAGS construction variable.


       SCANNERS
              A list of the available implicit dependency scanners.  New  file
              scanners  may  be  added by appending to this list, although the
              more flexible approach is to associate scanners with a  specific
              Builder.   See  the  sections  "Builder  Objects"  and  "Scanner
              Objects," below, for more information.


       SCCS   The SCCS executable.


       SCCSCOM
              The command line used to fetch source files from SCCS.


       SCCSCOMSTR
              The string displayed when fetching a  source  file  from  a  CVS
              repository.   If  this  is  not  set, then $SCCSCOM (the command
              line) is displayed.


       SCCSFLAGS
              General options that are passed to SCCS.


       SCCSGETFLAGS
              Options that are passed specifically to the SCCS  "get"  subcom-
              mand.  This can be set, for example, to --ee to check out editable
              files from SCCS.


       SCONS_HOME
              The (optional) path to the SCons library directory,  initialized
              from  the  external  environment.   If set, this is used to con-
              struct a shorter and more efficient search path in  the  $MSVSS-
              CONS  command line executed from Microsoft Visual Studio project
              files.


       SHCC   The C compiler used for generating shared-library objects.


       SHCCCOM
              The command line used to compile a C source file  to  a  shared-
              library  object  file.   Any options specified in the $SHCFLAGS,
              $SHCCFLAGS and $CPPFLAGS construction variables are included  on
              this command line.


       SHCCCOMSTR
              The  string  displayed  when  a  C  source file is compiled to a
              shared object file.  If this is not set, then $SHCCCOM (the com-
              mand line) is displayed.

              env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")


       SHCCFLAGS
              Options  that  are passed to the C and C++ compilers to generate
              shared-library objects.


       SHCFLAGS
              Options that are passed to the C compiler  (only;  not  C++)  to
              generate shared-library objects.


       SHCXX  The C++ compiler used for generating shared-library objects.


       SHCXXCOM
              The  command line used to compile a C++ source file to a shared-
              library object file.  Any options specified in  the  $SHCXXFLAGS
              and  $CPPFLAGS  construction variables are included on this com-
              mand line.


       SHCXXCOMSTR
              The string displayed when a C++ source file  is  compiled  to  a
              shared  object  file.   If  this is not set, then $SHCXXCOM (the
              command line) is displayed.

              env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")


       SHCXXFLAGS
              Options that are passed to the C++ compiler to generate  shared-
              library objects.


       SHELL  A  string  naming  the  shell program that will be passed to the
              $SPAWN function.  See the $SPAWN construction variable for  more
              information.


       SHF77  The  Fortran  77  compiler  used  for  generating shared-library
              objects.  You should normally set the $SHFORTRAN variable, which
              specifies the default Fortran compiler for all Fortran versions.
              You only need to set $SHF77 if you need to use a  specific  com-
              piler or compiler version for Fortran 77 files.


       SHF77COM
              The  command  line used to compile a Fortran 77 source file to a
              shared-library object file.  You only need to set  $SHF77COM  if
              you  need  to  use a specific command line for Fortran 77 files.
              You should normally set the $SHFORTRANCOM variable, which speci-
              fies the default command line for all Fortran versions.


       SHF77COMSTR
              The  string  displayed when a Fortran 77 source file is compiled
              to a shared-library object file.   If  this  is  not  set,  then
              $SHF77COM or $SHFORTRANCOM (the command line) is displayed.


       SHF77FLAGS
              Options  that are passed to the Fortran 77 compiler to generated
              shared-library objects.  You only need to set $SHF77FLAGS if you
              need  to define specific user options for Fortran 77 files.  You
              should normally set the $SHFORTRANFLAGS variable,  which  speci-
              fies  the  user-specified  options passed to the default Fortran
              compiler for all Fortran versions.


       SHF77PPCOM
              The command line used to compile a Fortran 77 source file  to  a
              shared-library  object file after first running the file through
              the C preprocessor.  Any options specified  in  the  $SHF77FLAGS
              and  $CPPFLAGS  construction variables are included on this com-
              mand line.  You only need to set $SHF77PPCOM if you need to  use
              a  specific  C-preprocessor  command  line for Fortran 77 files.
              You should normally  set  the  $SHFORTRANPPCOM  variable,  which
              specifies  the  default C-preprocessor command line for all For-
              tran versions.


       SHF77PPCOMSTR
              The string displayed when a Fortran 77 source file  is  compiled
              to  a  shared-library  object  file after first running the file
              through  the  C  preprocessor.   If  this  is  not   set,   then
              $SHF77PPCOM  or $SHFORTRANPPCOM (the command line) is displayed.


       SHF90  The Fortran  90  compiler  used  for  generating  shared-library
              objects.  You should normally set the $SHFORTRAN variable, which
              specifies the default Fortran compiler for all Fortran versions.
              You  only  need to set $SHF90 if you need to use a specific com-
              piler or compiler version for Fortran 90 files.


       SHF90COM
              The command line used to compile a Fortran 90 source file  to  a
              shared-library  object  file.  You only need to set $SHF90COM if
              you need to use a specific command line for  Fortran  90  files.
              You should normally set the $SHFORTRANCOM variable, which speci-
              fies the default command line for all Fortran versions.


       SHF90COMSTR
              The string displayed when a Fortran 90 source file  is  compiled
              to  a  shared-library  object  file.   If  this is not set, then
              $SHF90COM or $SHFORTRANCOM (the command line) is displayed.


       SHF90FLAGS
              Options that are passed to the Fortran 90 compiler to  generated
              shared-library objects.  You only need to set $SHF90FLAGS if you
              need to define specific user options for Fortran 90 files.   You
              should  normally  set the $SHFORTRANFLAGS variable, which speci-
              fies the user-specified options passed to  the  default  Fortran
              compiler for all Fortran versions.


       SHF90PPCOM
              The  command  line used to compile a Fortran 90 source file to a
              shared-library object file after first running the file  through
              the  C  preprocessor.   Any options specified in the $SHF90FLAGS
              and $CPPFLAGS construction variables are included on  this  com-
              mand  line.  You only need to set $SHF90PPCOM if you need to use
              a specific C-preprocessor command line  for  Fortran  90  files.
              You  should  normally  set  the  $SHFORTRANPPCOM variable, which
              specifies the default C-preprocessor command line for  all  For-
              tran versions.


       SHF90PPCOMSTR
              The  string  displayed when a Fortran 90 source file is compiled
              to a shared-library object file after  first  running  the  file
              through   the   C  preprocessor.   If  this  is  not  set,  then
              $SHF90PPCOM or $SHFORTRANPPCOM (the command line) is  displayed.


       SHF95  The  Fortran  95  compiler  used  for  generating shared-library
              objects.  You should normally set the $SHFORTRAN variable, which
              specifies the default Fortran compiler for all Fortran versions.
              You only need to set $SHF95 if you need to use a  specific  com-
              piler or compiler version for Fortran 95 files.


       SHF95COM
              The  command  line used to compile a Fortran 95 source file to a
              shared-library object file.  You only need to set  $SHF95COM  if
              you  need  to  use a specific command line for Fortran 95 files.
              You should normally set the $SHFORTRANCOM variable, which speci-
              fies the default command line for all Fortran versions.


       SHF95COMSTR
              The  string  displayed when a Fortran 95 source file is compiled
              to a shared-library object file.   If  this  is  not  set,  then
              $SHF95COM or $SHFORTRANCOM (the command line) is displayed.


       SHF95FLAGS
              Options  that are passed to the Fortran 95 compiler to generated
              shared-library objects.  You only need to set $SHF95FLAGS if you
              need  to define specific user options for Fortran 95 files.  You
              should normally set the $SHFORTRANFLAGS variable,  which  speci-
              fies  the  user-specified  options passed to the default Fortran
              compiler for all Fortran versions.


       SHF95PPCOM
              The command line used to compile a Fortran 95 source file  to  a
              shared-library  object file after first running the file through
              the C preprocessor.  Any options specified  in  the  $SHF95FLAGS
              and  $CPPFLAGS  construction variables are included on this com-
              mand line.  You only need to set $SHF95PPCOM if you need to  use
              a  specific  C-preprocessor  command  line for Fortran 95 files.
              You should normally  set  the  $SHFORTRANPPCOM  variable,  which
              specifies  the  default C-preprocessor command line for all For-
              tran versions.


       SHF95PPCOMSTR
              The string displayed when a Fortran 95 source file  is  compiled
              to  a  shared-library  object  file after first running the file
              through  the  C  preprocessor.   If  this  is  not   set,   then
              $SHF95PPCOM  or $SHFORTRANPPCOM (the command line) is displayed.


       SHFORTRAN
              The default Fortran compiler used for generating  shared-library
              objects.


       SHFORTRANCOM
              The  command  line  used  to  compile a Fortran source file to a
              shared-library object file.


       SHFORTRANCOMSTR
              The string displayed when a Fortran source file is compiled to a
              shared-library  object  file.   If this is not set, then $SHFOR-
              TRANCOM (the command line) is displayed.


       SHFORTRANFLAGS
              Options that are passed to  the  Fortran  compiler  to  generate
              shared-library objects.


       SHFORTRANPPCOM
              The  command  line  used  to  compile a Fortran source file to a
              shared-library object file after first running the file  through
              the  C  preprocessor.   Any options specified in the $SHFORTRAN-
              FLAGS and $CPPFLAGS construction variables are included on  this
              command line.


       SHFORTRANPPCOMSTR
              The string displayed when a Fortran source file is compiled to a
              shared-library object file after first running the file throught
              the  C  preprocessor.   If this is not set, then $SHFORTRANPPCOM
              (the command line) is displayed.


       SHLIBPREFIX
              The prefix used for shared library file names.


       SHLIBSUFFIX
              The suffix used for shared library file names.


       SHLINK The linker for programs that use shared libraries.


       SHLINKCOM
              The command line used to link programs using shared libaries.


       SHLINKCOMSTR
              The string displayed when programs using  shared  libraries  are
              linked.   If this is not set, then $SHLINKCOM (the command line)
              is displayed.

              env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")


       SHLINKFLAGS
              General user options passed to the  linker  for  programs  using
              shared libraries.  Note that this variable should _n_o_t contain --ll
              (or similar) options for linking with the  libraries  listed  in
              $LIBS,  nor  --LL  (or  similar)  include search path options that
              scons generates automatically  from  $LIBPATH.   See  $_LIBFLAGS
              above,  for  the  variable that expands to library-link options,
              and $_LIBDIRFLAGS  above,  for  the  variable  that  expands  to
              library search path options.


       SHOBJPREFIX
              The prefix used for shared object file names.


       SHOBJSUFFIX
              The suffix used for shared object file names.


       SOURCE A  reserved  variable name that may not be set or used in a con-
              struction environment.  (See "Variable Substitution," below.)


       SOURCE_URL
              The URL (web address) of the location from which the project was
              retrieved.   This  is  used  to fill in the SSoouurrccee:: field in the
              controlling information for Ipkg and RPM packages.


       SOURCES
              A reserved variable name that may not be set or used in  a  con-
              struction environment.  (See "Variable Substitution," below.)


       SPAWN  A  command  interpreter  function that will be called to execute
              command line strings. The function  must  expect  the  following
              arguments:

              def spawn(shell, escape, cmd, args, env):

              _s_h  is  a  string  naming the shell program to use.  _e_s_c_a_p_e is a
              function that can be called to escape shell  special  characters
              in  the command line.  _c_m_d is the path to the command to be exe-
              cuted.  _a_r_g_s is the arguments to the command.  _e_n_v is a  dictio-
              nary of the environment variables in which the command should be
              executed.


       SUMMARY
              A short summary of what the project is about.  This is  used  to
              fill  in  the  SSuummmmaarryy:: field in the controlling information for
              Ipkg and RPM packages, and as  the  DDeessccrriippttiioonn::  field  in  MSI
              packages.


       SWIG   The scripting language wrapper and interface generator.


       SWIGCFILESUFFIX
              The  suffix  that  will  be used for intermediate C source files
              generated by the scripting language wrapper and interface gener-
              ator.  The default value is __wwrraapp$CFILESUFFIX.  By default, this
              value is used whenever the --cc++++ option is _n_o_t specified as  part
              of the $SWIGFLAGS construction variable.


       SWIGCOM
              The command line used to call the scripting language wrapper and
              interface generator.


       SWIGCOMSTR
              The string displayed when calling the scripting language wrapper
              and interface generator.  If this is not set, then $SWIGCOM (the
              command line) is displayed.


       SWIGCXXFILESUFFIX
              The suffix that will be used for intermediate C++  source  files
              generated by the scripting language wrapper and interface gener-
              ator.  The default value is __wwrraapp$CFILESUFFIX.  By default, this
              value  is  used whenever the --cc++++ option is specified as part of
              the $SWIGFLAGS construction variable.


       SWIGFLAGS
              General options passed to the  scripting  language  wrapper  and
              interface  generator.   This  is  where  you should set --ppyytthhoonn,
              --ppeerrll55, --ttccll, or whatever other options you want to  specify  to
              SWIG.   If you set the --cc++++ option in this variable, ssccoonnss will,
              by default, generate a C++ intermediate  source  file  with  the
              extension that is specified as the $CXXFILESUFFIX variable.


       _SWIGINCFLAGS
              An  automatically-generated construction variable containing the
              SWIG command-line  options  for  specifying  directories  to  be
              searched  for  included  files.   The value of $_SWIGINCFLAGS is
              created by appending $SWIGINCPREFIX and  $SWIGINCSUFFIX  to  the
              beginning and end of each directory in $SWIGPATH.


       SWIGINCPREFIX
              The prefix used to specify an include directory on the SWIG com-
              mand line.  This will be  appended  to  the  beginning  of  each
              directory  in  the  $SWIGPATH  construction  variable  when  the
              $_SWIGINCFLAGS variable is automatically generated.


       SWIGINCSUFFIX
              The suffix used to specify an include directory on the SWIG com-
              mand  line.   This will be appended to the end of each directory
              in the $SWIGPATH construction variable when  the  $_SWIGINCFLAGS
              variable is automatically generated.


       SWIGOUTDIR
              Specifies  the  output directory in which the scripting language
              wrapper and interface generator should place generated language-
              specific  files.   This  will  be  used by SCons to identify the
              files that will be generated by the &swig; call, and  translated
              into the sswwiigg --oouuttddiirr option on the command line.


       SWIGPATH
              The  list of directories that the scripting language wrapper and
              interface generate will search for  included  files.   The  SWIG
              implicit  dependency  scanner  will search these directories for
              include files.  The default is to use the same path specified as
              $CPPPATH.

              Don't  explicitly  put include directory arguments in SWIGFLAGS;
              the result will be non-portable and the directories will not  be
              searched  by  the  dependency scanner.  Note: directory names in
              SWIGPATH will be looked-up relative to the SConscript  directory
              when  they  are  used in a command.  To force ssccoonnss to look-up a
              directory relative to the root of the source tree use #:

              env = Environment(SWIGPATH='#/include')

              The directory look-up can also be forced using the  DDiirr()  func-
              tion:

              include = Dir('include')
              env = Environment(SWIGPATH=include)

              The  directory  list  will be added to command lines through the
              automatically-generated  $_SWIGINCFLAGS  construction  variable,
              which is constructed by appending the values of the $SWIGINCPRE-
              FIX and $SWIGINCSUFFIX construction variables to  the  beginning
              and  end  of each directory in $SWIGPATH.  Any command lines you
              define that need the  SWIGPATH  directory  list  should  include
              $_SWIGINCFLAGS:

              env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SORUCES")


       TAR    The tar archiver.


       TARCOM The command line used to call the tar archiver.


       TARCOMSTR
              The   string  displayed  when  archiving  files  using  the  tar
              archiver.  If this is not set, then $TARCOM (the  command  line)
              is displayed.

              env = Environment(TARCOMSTR = "Archiving $TARGET")


       TARFLAGS
              General options passed to the tar archiver.


       TARGET A  reserved  variable name that may not be set or used in a con-
              struction environment.  (See "Variable Substitution," below.)


       TARGETS
              A reserved variable name that may not be set or used in  a  con-
              struction environment.  (See "Variable Substitution," below.)


       TARSUFFIX
              The suffix used for tar file names.


       TEMPFILEPREFIX
              The  prefix  for  a  temporary file used to execute lines longer
              than $MAXLINELENGTH.  The default is '@'.  This may be  set  for
              toolchains that use other values, such as '-@' for the diab com-
              piler or '-via' for ARM toolchain.


       TEX    The TeX formatter and typesetter.


       TEXCOM The command line used to call the TeX formatter and  typesetter.


       TEXCOMSTR
              The string displayed when calling the TeX formatter and typeset-
              ter.  If this is not set, then $TEXCOM  (the  command  line)  is
              displayed.

              env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")


       TEXFLAGS
              General options passed to the TeX formatter and typesetter.


       TEXINPUTS
              List  of  directories  that  the  LaTeX programm will search for
              include directories.  The LaTeX implicit dependency scanner will
              search these directories for \include and \import files.


       TOOLS  A  list of the names of the Tool specifications that are part of
              this construction environment.


       VENDOR The person or organization who  supply  the  packaged  software.
              This  is  used  to  fill in the VVeennddoorr:: field in the controlling
              information for RPM packages, and the MMaannuuffaaccttuurreerr:: field in the
              controlling information for MSI packages.


       VERSION
              The version of the project, specified as a string.


       WIN32_INSERT_DEF
              A deprecated synonym for $WINDOWS_INSERT_DEF.


       WIN32DEFPREFIX
              A deprecated synonym for $WINDOWSDEFPREFIX.


       WIN32DEFSUFFIX
              A deprecated synonym for $WINDOWSDEFSUFFIX.


       WIN32EXPPREFIX
              A deprecated synonym for $WINDOWSEXPSUFFIX.


       WIN32EXPSUFFIX
              A deprecated synonym for $WINDOWSEXPSUFFIX.


       WINDOWS_INSERT_DEF
              When  this  is  set to true, a library build of a Windows shared
              library (..ddllllfile) will also build a corresponding ..ddeeff file  at
              the  same  time, if a ..ddeeff file is not already listed as a build
              target.  The default is 0 (do not build a ..ddeeff file).


       WINDOWS_INSERT_MANIFEST
              When this is set to true, ssccoonnss will be aware of  the  ..mmaanniiffeesstt
              files generated by Microsoft Visua C/C++ 8.


       WINDOWSDEFPREFIX
              The prefix used for Windows ..ddeefffile names.


       WINDOWSDEFSUFFIX
              The suffix used for Windows ..ddeeff file names.


       WINDOWSEXPPREFIX
              The prefix used for Windows ..eexxpp file names.


       WINDOWSEXPSUFFIX
              The suffix used for Windows ..eexxpp file names.


       WINDOWSPROGMANIFESTPREFIX
              The prefix used for executable program ..mmaanniiffeesstt files generated
              by Microsoft Visual C/C++.


       WINDOWSPROGMANIFESTSUFFIX
              The suffix used for executable program ..mmaanniiffeesstt files generated
              by Microsoft Visual C/C++.


       WINDOWSSHLIBMANIFESTPREFIX
              The  prefix used for shared library ..mmaanniiffeesstt files generated by
              Microsoft Visual C/C++.


       WINDOWSSHLIBMANIFESTSUFFIX
              The suffix used for shared library ..mmaanniiffeesstt files generated  by
              Microsoft Visual C/C++.


       X_IPK_DEPENDS
              This  is  used  to fill in the DDeeppeennddss:: field in the controlling
              information for Ipkg packages.


       X_IPK_DESCRIPTION
              This is used to fill in the DDeessccrriippttiioonn:: field in  the  control-
              ling  information for Ipkg packages.  The default value is $$SSUUMM--
              MMAARRYY\\$$SSUUMMMMAARRYY

       X_IPK_MAINTAINER
              This is used to fill in the MMaaiinnttaaiinneerr:: field in the controlling
              information for Ipkg packages.


       X_IPK_PRIORITY
              This  is  used to fill in the PPrriioorriittyy:: field in the controlling
              information for Ipkg packages.


       X_IPK_SECTION
              This is used to fill in the SSeeccttiioonn:: field  in  the  controlling
              information for Ipkg packages.


       X_MSI_LANGUAGE
              This  is used to fill in the LLaanngguuaaggee:: attribute in the control-
              ling information for MSI packages.


       X_MSI_LICENSE_TEXT
              The text of the software license in RTF format.  Carriage return
              characters  will  be  replaced  with  the  RTF  equivalent  \ar.


       X_MSI_UPGRADE_CODE
              TODO


       X_RPM_AUTOREQPROV
              This is used to fill in the AAuuttooRReeqqPPrroovv:: field in the RPM  ..ssppeecc
              file.


       X_RPM_BUILD
              internal, but overridable


       X_RPM_BUILDREQUIRES
              This  is  used  to  fill  in the BBuuiillddRReeqquuiirreess:: field in the RPM
              ..ssppeecc file.


       X_RPM_BUILDROOT
              internal, but overridable


       X_RPM_CLEAN
              internal, but overridable


       X_RPM_CONFLICTS
              This is used to fill in the CCoonnfflliiccttss:: field in  the  RPM  ..ssppeecc
              file.


       X_RPM_DEFATTR
              This  value  is  used as the default attributes for the files in
              the RPM package.  The default value is ((--,,rroooott,,rroooott)).


       X_RPM_DISTRIBUTION
              This is used to fill in the DDiissttrriibbuuttiioonn:: field in the RPM ..ssppeecc
              file.


       X_RPM_EPOCH
              This  is  used  to  fill  in the EEppoocchh:: field in the controlling
              information for RPM packages.


       X_RPM_EXCLUDEARCH
              This is used to fill in the EExxcclluuddeeAArrcchh:: field in the RPM  ..ssppeecc
              file.


       X_RPM_EXLUSIVEARCH
              This  is  used  to  fill  in the EExxcclluussiivveeAArrcchh:: field in the RPM
              ..ssppeecc file.


       X_RPM_GROUP
              This is used to fill in the GGrroouupp:: field in the RPM ..ssppeecc  file.


       X_RPM_GROUP_lang
              This  is used to fill in the GGrroouupp((llaanngg)):: field in the RPM ..ssppeecc
              file.  Note that _l_a_n_g is not literal and should be  replaced  by
              the appropriate language code.


       X_RPM_ICON
              This is used to fill in the IIccoonn:: field in the RPM ..ssppeecc file.


       X_RPM_INSTALL
              internal, but overridable


       X_RPM_PACKAGER
              This  is  used  to  fill in the PPaacckkaaggeerr:: field in the RPM ..ssppeecc
              file.


       X_RPM_POSTINSTALL
              This is used to fill in the %%ppoosstt::  section  in  the  RPM  ..ssppeecc
              file.


       X_RPM_POSTUNINSTALL
              This  is  used  to fill in the %%ppoossttuunn:: section in the RPM ..ssppeecc
              file.


       X_RPM_PREFIX
              This is used to fill in the PPrreeffiixx:: field in the RPM ..ssppeecc file.


       X_RPM_PREINSTALL
              This is used to fill in the %%pprree:: section in the RPM ..ssppeecc file.


       X_RPM_PREP
              internal, but overridable


       X_RPM_PREUNINSTALL
              This is used to fill in the %%pprreeuunn:: section  in  the  RPM  ..ssppeecc
              file.


       X_RPM_PROVIDES
              This  is  used  to  fill in the PPrroovviiddeess:: field in the RPM ..ssppeecc
              file.


       X_RPM_REQUIRES
              This is used to fill in the RReeqquuiirreess:: field  in  the  RPM  ..ssppeecc
              file.


       X_RPM_SERIAL
              This is used to fill in the SSeerriiaall:: field in the RPM ..ssppeecc file.


       X_RPM_URL
              This is used to fill in the UUrrll:: field in the RPM ..ssppeecc file.


       YACC   The parser generator.


       YACCCOM
              The command line used to call the parser generator to generate a
              source file.


       YACCCOMSTR
              The  string  displayed  when  generating a source file using the
              parser generator.  If this is not set, then $YACCCOM  (the  com-
              mand line) is displayed.

              env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")


       YACCFLAGS
              General  options  passed to the parser generator.  If $YACCFLAGS
              contains a --dd option, SCons assumes that the call will also cre-
              ate a .h file (if the yacc source file ends in a .y suffix) or a
              .hpp file (if the yacc source file ends in a .yy suffix)


       YACCHFILESUFFIX
              The suffix of the C header file generated by the parser  genera-
              tor when the --dd option is used.  Note that setting this variable
              does not cause the parser generator to generate  a  header  file
              with  the  specified  suffix,  it exists to allow you to specify
              what suffix the parser generator will use  of  its  own  accord.
              The default value is ..hh.


       YACCHXXFILESUFFIX
              The suffix of the C++ header file generated by the parser gener-
              ator when the --dd option is used.  Note that setting  this  vari-
              able  does  not  cause the parser generator to generate a header
              file with the specified suffix, it exists to allow you to  spec-
              ify what suffix the parser generator will use of its own accord.
              The default value is ..hhpppp, except on Mac OS X, where the default
              is  $${{TTAARRGGEETT..ssuuffffiixx}}..hh.  because the default &bison; parser gen-
              erator just appends ..hh to the name of the generated C++ file.


       YACCVCGFILESUFFIX
              The suffix of the file containing the VCG grammar automaton def-
              inition  when  the  ----ggrraapphh==  option is used.  Note that setting
              this variable does not cause the parser generator to generate  a
              VCG  file  with  the specified suffix, it exists to allow you to
              specify what suffix the parser generator will  use  of  its  own
              accord.  The default value is ..vvccgg.


       ZIP    The zip compression and file packaging utility.


       ZIPCOM The  command  line used to call the zip utility, or the internal
              Python function used to create a zip archive.


       ZIPCOMPRESSION
              The _c_o_m_p_r_e_s_s_i_o_n flag from the Python zziippffiillee module used by  the
              internal  Python  function to control whether the zip archive is
              compressed or not.  The default value  is  zziippffiillee..ZZIIPP__DDEEFFLLAATTEEDD,
              which  creates  a  compressed  zip  archive.   This value has no
              effect when using Python 1.5.2 or if the zziippffiillee module is  oth-
              erwise unavailable.


       ZIPCOMSTR
              The string displayed when archiving files using the zip utility.
              If this is not set, then $ZIPCOM (the command line  or  internal
              Python function) is displayed.

              env = Environment(ZIPCOMSTR = "Zipping $TARGET")


       ZIPFLAGS
              General options passed to the zip utility.


       ZIPSUFFIX
              The suffix used for zip file names.


       Construction  variables  can  be retrieved and set using the DDiiccttiioonnaarryy
       method of the construction environment:

              dict = env.Dictionary()
              dict["CC"] = "cc"

       or using the [] operator:

              env["CC"] = "cc"

       Construction variables can also be passed to the construction  environ-
       ment constructor:

              env = Environment(CC="cc")

       or when copying a construction environment using the CClloonnee method:

              env2 = env.Clone(CC="cl.exe")


   CCoonnffiigguurree CCoonntteexxttss
       ssccoonnss  supports  _c_o_n_f_i_g_u_r_e _c_o_n_t_e_x_t_s_, an integrated mechanism similar to
       the various AC_CHECK macros in GNU autoconf for testing for  the  exis-
       tence  of  C  header  files,  libraries, etc.  In contrast to autoconf,
       ssccoonnss does not maintain an explicit cache of  the  tested  values,  but
       uses  its  normal  dependency tracking to keep the checked values up to
       date. However, users may override this behaviour with the ----ccoonnffiigg com-
       mand line option.

       The following methods can be used to perform checks:


       Configure(_e_n_v,  [_c_u_s_t_o_m___t_e_s_t_s,  _c_o_n_f___d_i_r,  _l_o_g___f_i_l_e,  _c_o_n_f_i_g___h,  _c_l_e_a_n,
       _h_e_l_p_]_)

       env.Configure([_c_u_s_t_o_m___t_e_s_t_s,   _c_o_n_f___d_i_r,   _l_o_g___f_i_l_e,  _c_o_n_f_i_g___h,  _c_l_e_a_n,
       _h_e_l_p_]_)
              This  creates  a configure context, which can be used to perform
              checks.  _e_n_v specifies the environment for building  the  tests.
              This  environment  may be modified when performing checks.  _c_u_s_-
              _t_o_m___t_e_s_t_s is a dictionary containing custom tests.  See also the
              section  about  custom tests below.  By default, no custom tests
              are added to the configure context.  _c_o_n_f___d_i_r specifies a direc-
              tory  where  the test cases are built.  Note that this directory
              is not used for building normal targets.  The default  value  is
              the  directory  #/.sconf_temp.   _l_o_g___f_i_l_e specifies a file which
              collects the output from commands that are executed to check for
              the  existence  of header files, libraries, etc.  The default is
              the file #/config.log.  If you are using the VVaarriiaannttDDiirr  method,
              you may want to specify a subdirectory under your variant direc-
              tory.  _c_o_n_f_i_g___h specifies a C header file where the  results  of
              tests  will  be  written,  e.g.  #define  HAVE_STDIO_H,  #define
              HAVE_LIBM, etc.  The default is to not write  a  ccoonnffiigg..hh  file.
              You can specify the same ccoonnffiigg..hh file in multiple calls to Con-
              figure, in which case ssccoonnss will concatenate all results in  the
              specified  file.   Note  that  SCons  uses its normal dependency
              checking to decide if it's necessary to  rebuild  the  specified
              _c_o_n_f_i_g___h  file.  This means that the file is not necessarily re-
              built each time scons is run, but is only rebuilt  if  its  con-
              tents will have changed and some target that depends on the _c_o_n_-
              _f_i_g___h file is being built.

              The optional cclleeaann and hheellpp arguments can be  used  to  suppress
              execution  of  the  configuration  tests  when the --cc//----cclleeaann or
              --HH//--hh//----hheellpp options are used, respectively.  The default behav-
              ior  is  always  to  execute  configure context tests, since the
              results of the tests may  affect  the  list  of  targets  to  be
              cleaned  or the help text.  If the configure tests do not affect
              these, then you may add the cclleeaann==FFaallssee or hheellpp==FFaallssee  arguments
              (or both) to avoid unnecessary test execution.

       A created CCoonnffiigguurree instance has the following associated methods:


       Configure.Finish(_s_e_l_f)
              This  method  should  be called after configuration is done.  It
              returns the environment as modified by the configuration  checks
              performed.   After  this method is called, no further checks can
              be performed with this configuration context.  However, you  can
              create  a  new  Configure  context to perform additional checks.
              Only one context should be active at a time.

              The following Checks are predefined.   (This  list  will  likely
              grow larger as time goes by and developers contribute new useful
              tests.)


       Configure.CheckHeader(_s_e_l_f, _h_e_a_d_e_r, [_i_n_c_l_u_d_e___q_u_o_t_e_s, _l_a_n_g_u_a_g_e])
              Checks if _h_e_a_d_e_r is usable in the  specified  language.   _h_e_a_d_e_r
              may  be  a  list, in which case the last item in the list is the
              header file to be checked,  and  the  previous  list  items  are
              header files whose ##iinncclluuddee lines should precede the header line
              being checked for.  The optional argument _i_n_c_l_u_d_e___q_u_o_t_e_s must be
              a  two  character  string, where the first character denotes the
              opening quote and  the  second  character  denotes  the  closing
              quote.   By default, both characters  are " (double quote).  The
              optional argument _l_a_n_g_u_a_g_e should be either CC or CC++++ and selects
              the compiler to be used for the check.  Returns 1 on success and
              0 on failure.


       Configure.CheckCHeader(_s_e_l_f, _h_e_a_d_e_r, [_i_n_c_l_u_d_e___q_u_o_t_e_s])
              This is a wrapper around CCoonnffiigguurree..CChheecckkHHeeaaddeerr which  checks  if
              _h_e_a_d_e_r  is  usable  in the C language.  _h_e_a_d_e_r may be a list, in
              which case the last item in the list is the header  file  to  be
              checked,  and  the  previous  list  items are header files whose
              ##iinncclluuddee lines should precede the header line being checked for.
              The  optional  argument  _i_n_c_l_u_d_e___q_u_o_t_e_s  must be a two character
              string, where the first character denotes the opening quote  and
              the  second character denotes the closing quote (both default to
              ").  Returns 1 on success and 0 on failure.


       Configure.CheckCXXHeader(_s_e_l_f, _h_e_a_d_e_r, [_i_n_c_l_u_d_e___q_u_o_t_e_s])
              This is a wrapper around CCoonnffiigguurree..CChheecckkHHeeaaddeerr which  checks  if
              _h_e_a_d_e_r  is usable in the C++ language.  _h_e_a_d_e_r may be a list, in
              which case the last item in the list is the header  file  to  be
              checked,  and  the  previous  list  items are header files whose
              ##iinncclluuddee lines should precede the header line being checked for.
              The  optional  argument  _i_n_c_l_u_d_e___q_u_o_t_e_s  must be a two character
              string, where the first character denotes the opening quote  and
              the  second character denotes the closing quote (both default to
              ").  Returns 1 on success and 0 on failure.


       Configure.CheckFunc(_s_e_l_f, _f_u_n_c_t_i_o_n___n_a_m_e, [_h_e_a_d_e_r, _l_a_n_g_u_a_g_e])
              Checks if the specified C or C++ function is  available.   _f_u_n_c_-
              _t_i_o_n___n_a_m_e  is  the  name  of  the  function  to  check for.  The
              optional _h_e_a_d_e_r argument is a string that will be placed at  the
              top of the test file that will be compiled to check if the func-
              tion exists; the default is:
              #ifdef __cplusplus
              extern "C"
              #endif
              char function_name();
       The optional _l_a_n_g_u_a_g_e argument should be CC or CC++++ and selects the  com-
       piler to be used for the check; the default is "C".


       Configure.CheckLib(_s_e_l_f,    [_l_i_b_r_a_r_y,    _s_y_m_b_o_l,    _h_e_a_d_e_r,   _l_a_n_g_u_a_g_e,
       _a_u_t_o_a_d_d_=_1])
              Checks if _l_i_b_r_a_r_y provides _s_y_m_b_o_l.  If the value of _a_u_t_o_a_d_d is 1
              and the library  provides  the  specified  _s_y_m_b_o_l,  appends  the
              library  to the LIBS construction environment variable.  _l_i_b_r_a_r_y
              may also be None (the default), in which case _s_y_m_b_o_l is  checked
              with  the  current LIBS variable, or a list of library names, in
              which case each library in the list will be checked for  _s_y_m_b_o_l.
              If  _s_y_m_b_o_l is not set or is NNoonnee, then CCoonnffiigguurree..CChheecckkLLiibb() just
              checks if you can  link  against  the  specified  _l_i_b_r_a_r_y.   The
              optional  _l_a_n_g_u_a_g_e  argument  should be CC or CC++++ and selects the
              compiler to be used for the check;  the  default  is  "C".   The
              default  value  for _a_u_t_o_a_d_d is 1.  This method returns 1 on suc-
              cess and 0 on error.


       Configure.CheckLibWithHeader(_s_e_l_f, _l_i_b_r_a_r_y,  _h_e_a_d_e_r,  _l_a_n_g_u_a_g_e,  [_c_a_l_l,
       _a_u_t_o_a_d_d])

              In contrast to the Configure.CheckLib call, this call provides a
              more  sophisticated  way  to  check  against  libraries.  Again,
              _l_i_b_r_a_r_y specifies the library or a list of libraries  to  check.
              _h_e_a_d_e_r  specifies  a header to check for.  _h_e_a_d_e_r may be a list,
              in which case the last item in the list is the header file to be
              checked,  and  the  previous  list  items are header files whose
              ##iinncclluuddee lines should precede the header line being checked for.
              _l_a_n_g_u_a_g_e  may  be  one  of  'C','c','CXX','cxx','C++' and 'c++'.
              _c_a_l_l can be any valid expression (with a trailing ';').  If _c_a_l_l
              is  not set, the default simply checks that you can link against
              the specified _l_i_b_r_a_r_y.  _a_u_t_o_a_d_d specifies  whether  to  add  the
              library  to  the  environment (only if the check succeeds). This
              method returns 1 on success and 0 on error.


       Configure.CheckType(_s_e_l_f, _t_y_p_e___n_a_m_e, [_i_n_c_l_u_d_e_s, _l_a_n_g_u_a_g_e])
              Checks  for  the  existence  of  a  type  defined  by   ttyyppeeddeeff.
              _t_y_p_e___n_a_m_e  specifies the typedef name to check for.  _i_n_c_l_u_d_e_s is
              a string containing one or more  ##iinncclluuddee  lines  that  will  be
              inserted into the program that will be run to test for the exis-
              tence of the type.  The optional _l_a_n_g_u_a_g_e argument should  be  CC
              or  CC++++  and  selects the compiler to be used for the check; the
              default is "C".

       Example of a typical Configure usage:

              env = Environment()
              conf = Configure( env )
              if not conf.CheckCHeader( 'math.h' ):
                  print 'We really need math.h!'
                  Exit(1)
              if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
                  # do stuff for qt - usage, e.g.
                  conf.env.Append( CPPFLAGS = '-DWITH_QT' )
              env = conf.Finish()


       Configure.CheckTypeSize(_s_e_l_f, _t_y_p_e___n_a_m_e, [_h_e_a_d_e_r, _l_a_n_g_u_a_g_e, _e_x_p_e_c_t])
              Checks for the size of a type  defined  by  ttyyppeeddeeff.   _t_y_p_e___n_a_m_e
              specifies  the  typedef  name to check for.  The optional _h_e_a_d_e_r
              argument is a string that will be placed at the top of the  test
              file  that will be compiled to check if the function exists; the
              default is empty.  The optional _l_a_n_g_u_a_g_e argument should be CC or
              CC++++  and  selects  the  compiler  to  be used for the check; the
              default is "C".  The optional _e_x_p_e_c_t argument should be an inte-
              ger.   If  this  argument  is used, the function will only check
              whether the type given in type_name has the  expected  size  (in
              bytes).   For  example,  CChheecckkTTyyppeeSSiizzee((''sshhoorrtt'',, eexxppeecctt == 22)) will
              return success only if short is two bytes.



       Configure.CheckDeclaration(_s_e_l_f, _s_y_m_b_o_l, [_i_n_c_l_u_d_e_s, _l_a_n_g_u_a_g_e])
              Checks if the specified  _s_y_m_b_o_l  is  declared.   _i_n_c_l_u_d_e_s  is  a
              string  containing  one  or  more  ##iinncclluuddee  lines  that will be
              inserted into the program that will be run to test for the exis-
              tence  of  the type.  The optional _l_a_n_g_u_a_g_e argument should be CC
              or CC++++ and selects the compiler to be used for  the  check;  the
              default is "C".


       Configure.Define(self_, symbol_, _[value_, comment_]_)
              This function does not check for anything, but defines a prepro-
              cessor symbol that will be added  to  the  configuration  header
              file.  It is the equivalent of AC_DEFINE, and defines the symbol
              _n_a_m_e with the optional vvaalluuee and the optional comment ccoommmmeenntt.


              Examples:

              env = Environment()
              conf = Configure( env )

              # Puts the following line in the config header file:
              #    #define A_SYMBOL
              conf.Define('A_SYMBOL')

              # Puts the following line in the config header file:
              #    #define A_SYMBOL 1
              conf.Define('A_SYMBOL', 1)


              Be careful about quoting string values, though:

              env = Environment()
              conf = Configure( env )

              # Puts the following line in the config header file:
              #    #define A_SYMBOL YA
              conf.Define('A_SYMBOL', "YA")

              # Puts the following line in the config header file:
              #    #define A_SYMBOL "YA"
              conf.Define('A_SYMBOL', '"YA"')


              For comment:

              env = Environment()
              conf = Configure( env )

              # Puts the following lines in the config header file:
              #    /* Set to 1 if you have a symbol */
              #    #define A_SYMBOL 1
              conf.Define('A_SYMBOL', 1, 'Set to 1 if you have a symbol')

       You can define your own custom checks.  in addition to  the  predefined
       checks.   These  are  passed in a dictionary to the Configure function.
       This dictionary maps the names of the checks  to  user  defined  Python
       callables  (either Python functions or class instances implementing the
       _____c_a_l_l____ method).  The first argument of the call is always a _C_h_e_c_k_C_o_n_-
       _t_e_x_t  instance followed by the arguments, which must be supplied by the
       user of the check.  These CheckContext instances define  the  following
       methods:


       CheckContext.Message(_s_e_l_f, _t_e_x_t)

              Usually  called  before the check is started.  _t_e_x_t will be dis-
              played to the user, e.g. 'Checking for library X...'


       CheckContext.Result(_s_e_l_f_,, _r_e_s)

              Usually called after the check is done.  _r_e_s can  be  either  an
              integer  or  a  string.  In  the former case, 'ok' (res != 0) or
              'failed' (res == 0) is displayed to the user, in the latter case
              the given string is displayed.


       CheckContext.TryCompile(_s_e_l_f, _t_e_x_t, _e_x_t_e_n_s_i_o_n)
              Checks  if  a file with the specified _e_x_t_e_n_s_i_o_n (e.g. '.c') con-
              taining _t_e_x_t can be  compiled  using  the  environment's  OObbjjeecctt
              builder. Returns 1 on success and 0 on failure.


       CheckContext.TryLink(_s_e_l_f, _t_e_x_t, _e_x_t_e_n_s_i_o_n)
              Checks,  if a file with the specified _e_x_t_e_n_s_i_o_n (e.g. '.c') con-
              taining _t_e_x_t can be compiled  using  the  environment's  PPrrooggrraamm
              builder. Returns 1 on success and 0 on failure.


       CheckContext.TryRun(_s_e_l_f, _t_e_x_t, _e_x_t_e_n_s_i_o_n)
              Checks,  if a file with the specified _e_x_t_e_n_s_i_o_n (e.g. '.c') con-
              taining _t_e_x_t can be compiled  using  the  environment's  PPrrooggrraamm
              builder. On success, the program is run. If the program executes
              successfully (that is, its return status is 0), a tuple _(_1_, _o_u_t_-
              _p_u_t_S_t_r_)  is  returned, where _o_u_t_p_u_t_S_t_r is the standard output of
              the program.  If the program fails execution (its return  status
              is non-zero), then (0, '') is returned.


       CheckContext.TryAction(_s_e_l_f, _a_c_t_i_o_n, [_t_e_x_t, _e_x_t_e_n_s_i_o_n])
              Checks  if  the  specified  _a_c_t_i_o_n  with an optional source file
              (contents _t_e_x_t , extension _e_x_t_e_n_s_i_o_n = ''  )  can  be  executed.
              _a_c_t_i_o_n may be anything which can be converted to a ssccoonnss Action.
              On success, _(_1_, _o_u_t_p_u_t_S_t_r_) is returned, where _o_u_t_p_u_t_S_t_r  is  the
              content of the target file.  On failure _(_0_, _'_'_) is returned.


       CheckContext.TryBuild(_s_e_l_f, _b_u_i_l_d_e_r, [_t_e_x_t, _e_x_t_e_n_s_i_o_n])
              Low  level implementation for testing specific builds; the meth-
              ods above are based on this method.  Given the Builder  instance
              _b_u_i_l_d_e_r  and  the  optional  _t_e_x_t of a source file with optional
              _e_x_t_e_n_s_i_o_n, this method returns 1 on success and 0 on failure. In
              addition,  _s_e_l_f_._l_a_s_t_T_a_r_g_e_t  is  set to the build target node, if
              the build was successful.

       Example for implementing and using custom tests:

              def CheckQt(context, qtdir):
                  context.Message( 'Checking for qt ...' )
                  lastLIBS = context.env['LIBS']
                  lastLIBPATH = context.env['LIBPATH']
                  lastCPPPATH= context.env['CPPPATH']
                  context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
                  ret = context.TryLink("""
              #include <qapp.h>
              int main(int argc, char **argv) {
                QApplication qapp(argc, argv);
                return 0;
              }
              """)
                  if not ret:
                      context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
                  context.Result( ret )
                  return ret

              env = Environment()
              conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
              if not conf.CheckQt('/usr/lib/qt'):
                  print 'We really need qt!'
                  Exit(1)
              env = conf.Finish()


   CCoonnssttrruuccttiioonn VVaarriiaabbllee OOppttiioonnss
       Often when building software, various options need to be  specified  at
       build  time that are not known when the SConstruct/SConscript files are
       written. For example, libraries needed for the build  may  be  in  non-
       standard  locations,  or  site-specific compiler options may need to be
       passed to the compiler.  ssccoonnss provides an Options object for  overrid-
       ding construction variables on the command line:
              $ scons VARIABLE=foo
       The  variable  values  can also be specified in a text-based SConscript
       file.  To create an Options object, call the Options() function:


       Options([_f_i_l_e_s], [_a_r_g_s])
              This creates an Options object that will read construction vari-
              ables from the file or list of filenames specified in _f_i_l_e_s.  If
              no files are specified, or the _f_i_l_e_s argument is NNoonnee,  then  no
              files  will be read.  The optional argument _a_r_g_s is a dictionary
              of values that will override anything read  from  the  specified
              files;  it is primarily intended to be passed the AARRGGUUMMEENNTTSS dic-
              tionary that holds variables  specified  on  the  command  line.
              Example:

              opts = Options('custom.py')
              opts = Options('overrides.py', ARGUMENTS)
              opts = Options(None, {FOO:'expansion', BAR:7})

       Options objects have the following methods:


       Add(_k_e_y, [_h_e_l_p, _d_e_f_a_u_l_t, _v_a_l_i_d_a_t_o_r, _c_o_n_v_e_r_t_e_r])
              This  adds  a  customizable construction variable to the Options
              object.  _k_e_y is the name of the variable.  _h_e_l_p is the help text
              for the variable.  _d_e_f_a_u_l_t is the default value of the variable;
              if the default value is NNoonnee and  there  is  no  explicit  value
              specified,  the  construction  variable will _n_o_t be added to the
              construction environment.  _v_a_l_i_d_a_t_o_r is called to  validate  the
              value  of  the  variable,  and should take three arguments: key,
              value, and  environment.   The  recommended  way  to  handle  an
              invalid  value  is  to  raise  an exception (see example below).
              _c_o_n_v_e_r_t_e_r is called to convert the value before  putting  it  in
              the  environment,  and  should take either a value, or the value
              and environment, as parameters.  The  _c_o_n_v_e_r_t_e_r  must  return  a
              value,  which will be converted into a string before being vali-
              dated by the _v_a_l_i_d_a_t_o_r (if any) and then added to  the  environ-
              ment.

              Examples:

              opts.Add('CC', 'The C compiler')

              def validate_color(key, val, env):
                  if not val in ['red', 'blue', 'yellow']:
                      raise "Invalid color value '%s'" % val
              opts.Add('COLOR', validator=valid_color)


       AddOptions(_l_i_s_t)
              A  wrapper  script  that adds multiple customizable construction
              variables to an Options object.  _l_i_s_t is a list of tuple or list
              objects that contain the arguments for an individual call to the
              AAdddd method.

              opt.AddOptions(
                     ('debug', '', 0),
                     ('CC', 'The C compiler'),
                     ('VALIDATE', 'An option for testing validation',
                      'notset', validator, None),
                  )


       Update(_e_n_v, [_a_r_g_s])
              This updates a construction environment _e_n_v with the  customized
              construction  variables.   Any  specified variables that are _n_o_t
              configured for the Options object  will  be  saved  and  may  be
              retrieved with the UUnnkknnoowwnnOOppttiioonnss() method, below.

              Normally this method is not called directly, but is called indi-
              rectly by passing the Options object to the Environment()  func-
              tion:

              env = Environment(options=opts)


              The text file(s) that were specified when the Options object was
              created are executed  as  Python  scripts,  and  the  values  of
              (global)  Python variables set in the file are added to the con-
              struction environment.

              Example:

              CC = 'my_cc'


       UnknownOptions(_)
              Returns a dictionary containing any variables that  were  speci-
              fied  either  in  the  files  or  the  dictionary with which the
              Options object was intialized, but for which the Options  object
              was not configured.

              env = Environment(options=opts)
              for key, value in opts.UnknownOptions():
                  print "unknown variable:  %s=%s" % (key, value)


       Save(_f_i_l_e_n_a_m_e, _e_n_v)
              This  saves  the  currently set options into a script file named
              _f_i_l_e_n_a_m_e that can be used on the next  invocation  to  automati-
              cally  load the current settings.  This method combined with the
              Options method can be used to support caching of options between
              runs.

              env = Environment()
              opts = Options(['options.cache', 'custom.py'])
              opts.Add(...)
              opts.Update(env)
              opts.Save('options.cache', env)


       GenerateHelpText(_e_n_v, [_s_o_r_t])
              This  generates help text documenting the customizable construc-
              tion variables suitable to passing in to  the  Help()  function.
              _e_n_v is the construction environment that will be used to get the
              actual  values  of  customizable  variables.  Calling  with   an
              optional _s_o_r_t function will cause the output to be sorted by the
              specified argument.  The specific _s_o_r_t function should take  two
              arguments  and  return  -1, 0 or 1 (like the standard Python _c_m_p
              function).

              Help(opts.GenerateHelpText(env))
              Help(opts.GenerateHelpText(env, sort=cmp))


       FormatOptionHelpText(_e_n_v, _o_p_t, _h_e_l_p, _d_e_f_a_u_l_t, _a_c_t_u_a_l)
              This method returns a formatted string containing the  printable
              help  text  for one option.  It is normally not called directly,
              but is called by the _G_e_n_e_r_a_t_e_H_e_l_p_T_e_x_t()  method  to  create  the
              returned help text.  It may be overridden with your own function
              that takes the arguments specified above and returns a string of
              help text formatted to your liking.  Note that the _G_e_n_e_r_a_t_e_H_e_l_p_-
              _T_e_x_t() will not put any  blank  lines  or  extra  characters  in
              between  the  entries,  so  you must add those characters to the
              returned string if you want the entries separated.

              def my_format(env, opt, help, default, actual):
                  fmt = "104s: default=%s actual=%s (%s)0
                  return fmt % (opt, default. actual, help)
              opts.FormatOptionHelpText = my_format

       To make it more convenient to work  with  customizable  Options,  ssccoonnss
       provides  a  number  of  functions  that make it easy to set up various
       types of Options:


       BoolOption(_k_e_y, _h_e_l_p, _d_e_f_a_u_l_t)
              Return a tuple of arguments to set up  a  Boolean  option.   The
              option  will use the specified name _k_e_y, have a default value of
              _d_e_f_a_u_l_t, and display the specified _h_e_l_p text.  The  option  will
              interpret the values yy, yyeess, tt, ttrruuee, 11, oonn and aallll as true, and
              the values nn, nnoo, ff, ffaallssee, 00, ooffff and nnoonnee as false.


       EnumOption(_k_e_y, _h_e_l_p, _d_e_f_a_u_l_t, _a_l_l_o_w_e_d___v_a_l_u_e_s, [_m_a_p, _i_g_n_o_r_e_c_a_s_e])
              Return a tuple of arguments to set up an option whose value  may
              be  one  of  a  specified  list of legal enumerated values.  The
              option will use the specified name _k_e_y, have a default value  of
              _d_e_f_a_u_l_t,  and  display the specified _h_e_l_p text.  The option will
              only support those  values  in  the  _a_l_l_o_w_e_d___v_a_l_u_e_s  list.   The
              optional  _m_a_p  argument is a dictionary that can be used to con-
              vert input values into specific legal values in the _a_l_l_o_w_e_d___v_a_l_-
              _u_e_s  list.  If the value of _i_g_n_o_r_e___c_a_s_e is 00 (the default), then
              the values are case-sensitive.  If the value of  _i_g_n_o_r_e___c_a_s_e  is
              11,  then  values will be matched case-insensitive.  If the value
              of _i_g_n_o_r_e___c_a_s_e is 11, then values will be  matched  case-insensi-
              tive, and all input values will be converted to lower case.


       ListOption(_k_e_y, _h_e_l_p, _d_e_f_a_u_l_t, _n_a_m_e_s, [_,map_]_)
              Return  a tuple of arguments to set up an option whose value may
              be one or more of a specified list of legal  enumerated  values.
              The option will use the specified name _k_e_y, have a default value
              of _d_e_f_a_u_l_t, and display the specified  _h_e_l_p  text.   The  option
              will  only  support  the  values aallll, nnoonnee, or the values in the
              _n_a_m_e_s list.  More than one value may be specified, with all val-
              ues  separated by commas.  The default may be a string of comma-
              separated default values, or a list of the default values.   The
              optional  _m_a_p  argument is a dictionary that can be used to con-
              vert input values into specific legal values in the _n_a_m_e_s  list.


       PackageOption(_k_e_y, _h_e_l_p, _d_e_f_a_u_l_t)
              Return a tuple of arguments to set up an option whose value is a
              path name of a package that may be enabled, disabled or given an
              explicit path name.  The option will use the specified name _k_e_y,
              have a default value of _d_e_f_a_u_l_t, and display the specified  _h_e_l_p
              text.   The option will support the values yyeess, ttrruuee, oonn, eennaabbllee
              or sseeaarrcchh, in which case the specified _d_e_f_a_u_l_t will be used,  or
              the option may be set to an arbitrary string (typically the path
              name to a package that is being enabled).  The option will  also
              support  the  values nnoo, ffaallssee, ooffff or ddiissaabbllee to disable use of
              the specified option.


       PathOption(_k_e_y, _h_e_l_p, _d_e_f_a_u_l_t, [_v_a_l_i_d_a_t_o_r])
              Return a tuple of arguments to set up an option whose  value  is
              expected  to  be a path name.  The option will use the specified
              name _k_e_y, have a default value of _d_e_f_a_u_l_t, and display the spec-
              ified  _h_e_l_p text.  An additional _v_a_l_i_d_a_t_o_r may be specified that
              will be called to verify that the specified path is  acceptable.
              SCons  supplies  the  following  ready-made  validators: PPaatthhOOpp--
              ttiioonn..PPaatthhEExxiissttss (the default), which verifies that the specified
              path  exists;  PPaatthhOOppttiioonn..PPaatthhIIssFFiillee,  which  verifies  that the
              specified path is an existing file; PPaatthhOOppttiioonn..PPaatthhIIssDDiirr,  which
              verifies  that  the  specified  path  is  an existing directory;
              PPaatthhOOppttiioonn..PPaatthhIIssDDiirrCCrreeaattee, which verifies  that  the  specified
              path  is  a directory and will create the specified directory if
              the path does not exist; and PPaatthhOOppttiioonn..PPaatthhAAcccceepptt, which simply
              accepts  the specific path name argument without validation, and
              which is suitable if you want your users to be able to specify a
              directory  path  that  will be created as part of the build pro-
              cess, for example.  You may supply your own _v_a_l_i_d_a_t_o_r  function,
              which  must  take  three arguments (_k_e_y, the name of the options
              variable to be set; _v_a_l, the specified value being checked;  and
              _e_n_v, the construction environment) and should raise an exception
              if the specified value is not acceptable.

       These functions make it convenient to create a number of  options  with
       consistent behavior in a single call to the AAddddOOppttiioonnss method:

              opts.AddOptions(
                  BoolOption('warnings', 'compilation with -Wall and similiar', 1),
                  EnumOption('debug', 'debug output and symbols', 'no'
                             allowed_values=('yes', 'no', 'full'),
                             map={}, ignorecase=0),  # case sensitive
                  ListOption('shared',
                             'libraries to build as shared libraries',
                             'all',
                             names = list_of_libs),
                  PackageOption('x11',
                                'use X11 installed here (yes = search some places)',
                                'yes'),
                  PathOption('qtdir', 'where the root of Qt is installed', qtdir),
                  PathOption('foopath', 'where the foo library is installed', foopath,
                             PathOption.PathIsDir),

              )


   FFiillee aanndd DDiirreeccttoorryy NNooddeess
       The _F_i_l_e() and _D_i_r() functions return _F_i_l_e and _D_i_r Nodes, respectively.
       python objects, respectively.  Those objects have several  user-visible
       attributes and methods that are often useful:


       path   The  build  path  of  the given file or directory.  This path is
              relative to the top-level directory (where the  SSCCoonnssttrruucctt  file
              is  found).   The  build  path is the same as the source path if
              _v_a_r_i_a_n_t___d_i_r is not being used.


       abspath
              The absolute build path of the given file or directory.


       srcnode()
              The _s_r_c_n_o_d_e() method returns another _F_i_l_e or _D_i_r  object  repre-
              senting the _s_o_u_r_c_e path of the given _F_i_l_e or _D_i_r.  The

              # Get the current build dir's path, relative to top.
              Dir('.').path
              # Current dir's absolute path
              Dir('.').abspath
              # Next line is always '.', because it is the top dir's path relative to itself.
              Dir('#.').path
              File('foo.c').srcnode().path   # source path of the given source file.

              # Builders also return File objects:
              foo = env.Program('foo.c')
              print "foo will be built in %s"%foo.path

       A  _D_i_r  Node or _F_i_l_e Node can also be used to create file and subdirec-
       tory Nodes relative to the generating Node.  A _D_i_r Node will place  the
       new  Nodes  within the directory it represents.  A _F_i_l_e node will place
       the new Nodes within its parent directory (that is, "beside"  the  file
       in  question).   If  _d is a _D_i_r (directory) Node and _f is a _F_i_l_e (file)
       Node, then these methods are available:


       _d.Dir(_n_a_m_e)
              Returns a directory Node for a subdirectory of _d named _n_a_m_e.


       _d.File(_n_a_m_e)
              Returns a file Node for a file within _d named _n_a_m_e.


       _d.Entry(_n_a_m_e)
              Returns an unresolved Node within _d named _n_a_m_e.


       _f.Dir(_n_a_m_e)
              Returns a directory named _n_a_m_e within the parent directory of _f.


       _f.File(_n_a_m_e)
              Returns a file named _n_a_m_e within the parent directory of _f.


       _f.Entry(_n_a_m_e)
              Returns  an  unresolved Node named _n_a_m_e within the parent direc-
              tory of _f.

       For example:

              # Get a Node for a file within a directory
              incl = Dir('include')
              f = incl.File('header.h')

              # Get a Node for a subdirectory within a directory
              dist = Dir('project-3.2.1)
              src = dist.Dir('src')

              # Get a Node for a file in the same directory
              cfile = File('sample.c')
              hfile = cfile.File('sample.h')

              # Combined example
              docs = Dir('docs')
              html = docs.Dir('html')
              index = html.File('index.html')
              css = index.File('app.css')


EEXXTTEENNDDIINNGG SSCCOONNSS
   BBuuiillddeerr OObbjjeeccttss
       ssccoonnss can be extended to build different types of targets by adding new
       Builder  objects to a construction environment.  _I_n _g_e_n_e_r_a_l, you should
       only need to add a new Builder object when you want to build a new type
       of file or other external target.  If you just want to invoke a differ-
       ent compiler or other tool to build a Program, Object, Library, or  any
       other  type  of  output  file  for  which ssccoonnss already has an existing
       Builder, it is generally much easier to use those existing Builders  in
       a construction environment that sets the appropriate construction vari-
       ables (CC, LINK, etc.).

       Builder objects are created using the BBuuiillddeerr  function.   The  BBuuiillddeerr
       function accepts the following arguments:


       action The  command  line  string  used  to  build  the target from the
              source.  aaccttiioonn can also be: a list of strings representing  the
              command to be executed and its arguments (suitable for enclosing
              white space in an argument), a dictionary  mapping  source  file
              name suffixes to any combination of command line strings (if the
              builder should accept multiple source file extensions), a Python
              function;  an Action object (see the next section); or a list of
              any of the above.

              An action function takes three arguments: _s_o_u_r_c_e  -  a  list  of
              source  nodes,  _t_a_r_g_e_t  - a list of target nodes, _e_n_v - the con-
              struction environment.


       prefix The prefix that will be prepended to the target file name.  This
              may be specified as a:


                 * _s_t_r_i_n_g,


                 *  _c_a_l_l_a_b_l_e  _o_b_j_e_c_t - a function or other callable that takes
                       two arguments (a construction environment and a list of
                       sources) and returns a prefix,


                 *  _d_i_c_t_i_o_n_a_r_y  -  specifies  a mapping from a specific source
                       suffix (of the first source specified) to a correspond-
                       ing  target  prefix.  Both the source suffix and target
                       prefix specifications may use environment variable sub-
                       stitution,  and  the target prefix (the 'value' entries
                       in the dictionary) may also be a callable object.   The
                       default  target prefix may be indicated by a dictionary
                       entry with a key value of None.


              b = Builder("build_it < $SOURCE > $TARGET"
                          prefix = "file-")

              def gen_prefix(env, sources):
                  return "file-" + env['PLATFORM'] + '-'
              b = Builder("build_it < $SOURCE > $TARGET",
                          prefix = gen_prefix)

              b = Builder("build_it < $SOURCE > $TARGET",
                          suffix = { None: "file-",
                                     "$SRC_SFX_A": gen_prefix })


       suffix The suffix that will be appended to the target file name.   This
              may be specified in the same manner as the prefix above.  If the
              suffix is a string, then ssccoonnss will append a '.' to  the  begin-
              ning  of  the  suffix  if  it's  not  already there.  The string
              returned by callable object (or obtained from the dictionary) is
              untouched  and  must append its own '.'  to the beginning if one
              is desired.

              b = Builder("build_it < $SOURCE > $TARGET"
                          suffix = "-file")

              def gen_suffix(env, sources):
                  return "." + env['PLATFORM'] + "-file"
              b = Builder("build_it < $SOURCE > $TARGET",
                          suffix = gen_suffix)

              b = Builder("build_it < $SOURCE > $TARGET",
                          suffix = { None: ".sfx1",
                                     "$SRC_SFX_A": gen_suffix })


       ensure_suffix
              When set to any true value, causes ssccoonnss to add the target  suf-
              fix  specified  by the _s_u_f_f_i_x keyword to any target strings that
              have a different suffix.  (The  default  behavior  is  to  leave
              untouched  any  target  file name that looks like it already has
              any suffix.)

              b1 = Builder("build_it < $SOURCE > $TARGET"
                           suffix = ".out")
              b2 = Builder("build_it < $SOURCE > $TARGET"
                           suffix = ".out",
                           ensure_suffix)
              env = Environment()
              env['BUILDERS']['B1'] = b1
              env['BUILDERS']['B2'] = b2

              # Builds "foo.txt" because ensure_suffix is not set.
              env.B1('foo.txt', 'foo.in')

              # Builds "bar.txt.out" because ensure_suffix is set.
              env.B2('bar.txt', 'bar.in')


       src_suffix
              The expected source file name suffix.  This may be a string or a
              list of strings.


       target_scanner
              A Scanner object that will be invoked to find implicit dependen-
              cies for this target file.  This keyword argument should be used
              for  Scanner  objects that find implicit dependencies based only
              on the target file and the  construction  environment,  _n_o_t  for
              implicit (See the section "Scanner Objects," below, for informa-
              tion about creating Scanner objects.)


       source_scanner
              A Scanner object that will be invoked to  find  implicit  depen-
              dences in any source files used to build this target file.  This
              is where you  would  specify  a  scanner  to  find  things  like
              ##iinncclluuddee  lines in source files.  The pre-built DDiirrSSccaannnneerr Scan-
              ner object may be used to indicate that this Builder should scan
              directory trees for on-disk changes to files that ssccoonnss does not
              know about from other Builder or function calls.  (See the  sec-
              tion  "Scanner  Objects,"  below, for information about creating
              your own Scanner objects.)


       target_factory
              A factory function that the Builder will use to turn any targets
              specified  as  strings  into  SCons  Nodes.   By  default, SCons
              assumes that all targets are files.  Other useful target_factory
              values  include DDiirr, for when a Builder creates a directory tar-
              get, and EEnnttrryy, for when a Builder can create either a  file  or
              directory target.

              Example:

              MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
              env = Environment()
              env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
              env.MakeDirectory('new_directory', [])


              Note that the call to the MakeDirectory Builder needs to specify
              an empty source list to make the string represent the  builder's
              target;  without  that,  it  would  assume  the  argument is the
              source, and would try to deduce the target name from  it,  which
              in  the absence of an automatically-added prefix or suffix would
              lead to a matching target and source name and a circular  depen-
              dency.


       source_factory
              A factory function that the Builder will use to turn any sources
              specified as  strings  into  SCons  Nodes.   By  default,  SCons
              assumes  that all source are files.  Other useful source_factory
              values include DDiirr, for when a Builder uses  a  directory  as  a
              source,  and EEnnttrryy, for when a Builder can use files or directo-
              ries (or both) as sources.

              Example:

              CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
              env = Environment()
              env.Append(BUILDERS = {'Collect':CollectBuilder})
              env.Collect('archive', ['directory_name', 'file_name'])


       emitter
              A function or list of functions to  manipulate  the  target  and
              source  lists  before  dependencies are established and the tar-
              get(s) are actually built.  eemmiitttteerr can also be  a  string  con-
              taining a construction variable to expand to an emitter function
              or list of functions, or a dictionary mapping source  file  suf-
              fixes  to  emitter  functions.   (Only  the  suffix of the first
              source file is used to select the actual emitter  function  from
              an emitter dictionary.)

              An  emitter  function  takes three arguments: _s_o_u_r_c_e - a list of
              source nodes, _t_a_r_g_e_t - a list of target nodes, _e_n_v  -  the  con-
              struction  environment.  An emitter must return a tuple contain-
              ing two lists, the list of targets to be built by this  builder,
              and the list of sources for this builder.

              Example:

              def e(target, source, env):
                  return (target + ['foo.foo'], source + ['foo.src'])

              # Simple association of an emitter function with a Builder.
              b = Builder("my_build < $TARGET > $SOURCE",
                          emitter = e)

              def e2(target, source, env):
                  return (target + ['bar.foo'], source + ['bar.src'])

              # Simple association of a list of emitter functions with a Builder.
              b = Builder("my_build < $TARGET > $SOURCE",
                          emitter = [e, e2])

              # Calling an emitter function through a construction variable.
              env = Environment(MY_EMITTER = e)
              b = Builder("my_build < $TARGET > $SOURCE",
                          emitter = '$MY_EMITTER')

              # Calling a list of emitter functions through a construction variable.
              env = Environment(EMITTER_LIST = [e, e2])
              b = Builder("my_build < $TARGET > $SOURCE",
                          emitter = '$EMITTER_LIST')

              # Associating multiple emitters with different file
              # suffixes using a dictionary.
              def e_suf1(target, source, env):
                  return (target + ['another_target_file'], source)
              def e_suf2(target, source, env):
                  return (target, source + ['another_source_file'])
              b = Builder("my_build < $TARGET > $SOURCE",
                          emitter = {'.suf1' : e_suf1,
                                     '.suf2' : e_suf2})


       multi  Specifies  whether this builder is allowed to be called multiple
              times for the same target file(s). The default is 0, which means
              the builder can not be called multiple times for the same target
              file(s). Calling a builder multiple times for  the  same  target
              simply  adds  additional  source  files to the target; it is not
              allowed to change the environment associated  with  the  target,
              specify addition environment overrides, or associate a different
              builder with the target.


       env    A construction environment that can be used to fetch source code
              using this Builder.  (Note that this environment is _n_o_t used for
              normal builds of normal target files, which use the  environment
              that was used to call the Builder for the target file.)


       generator
              A  function that returns a list of actions that will be executed
              to  build  the  target(s)  from  the  source(s).   The  returned
              action(s)  may be an Action object, or anything that can be con-
              verted into an Action object (see the next section).

              The generator function takes four arguments: _s_o_u_r_c_e - a list  of
              source  nodes,  _t_a_r_g_e_t  - a list of target nodes, _e_n_v - the con-
              struction environment, _f_o_r___s_i_g_n_a_t_u_r_e  -  a  Boolean  value  that
              specifies whether the generator is being called for generating a
              build signature (as opposed to actually executing the  command).
              Example:

              def g(source, target, env, for_signature):
                  return [["gcc", "-c", "-o"] + target + source]

              b = Builder(generator=g)


              The _g_e_n_e_r_a_t_o_r and _a_c_t_i_o_n arguments must not both be used for the
              same Builder.


       src_builder
              Specifies a builder to use when a source file name  suffix  does
              not  match  any of the suffixes of the builder. Using this argu-
              ment produces a multi-stage builder.


       single_source
              Specifies that this builder expects exactly one source file  per
              call.  Giving  more  than  one source files without target files
              results in implicitely calling the builder multiple times  (once
              for  each  source  given). Giving multiple source files together
              with target files results in a UserError exception.


              The _g_e_n_e_r_a_t_o_r and _a_c_t_i_o_n arguments must not both be used for the
              same Builder.


       source_ext_match
              When  the specified _a_c_t_i_o_n argument is a dictionary, the default
              behavior when a builder is passed multiple source  files  is  to
              make sure that the extensions of all the source files match.  If
              it is legal for this builder to be called with a list of  source
              files with different extensions, this check can be suppressed by
              setting ssoouurrccee__eexxtt__mmaattcchh to NNoonnee or some other  non-true  value.
              When  ssoouurrccee__eexxtt__mmaattcchh  is disable, ssccoonnss will use the suffix of
              the first specified source file to select the appropriate action
              from the _a_c_t_i_o_n dictionary.

              In  the  following example, the setting of ssoouurrccee__eexxtt__mmaattcchh pre-
              vents ssccoonnss from exiting with an error  due  to  the  mismatched
              suffixes of ffoooo..iinn and ffoooo..eexxttrraa.

              b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
                          source_ext_match = None)

              env = Environment(BUILDERS = {'MyBuild':b})
              env.MyBuild('foo.out', ['foo.in', 'foo.extra'])


       env    A construction environment that can be used to fetch source code
              using this Builder.  (Note that this environment is _n_o_t used for
              normal  builds of normal target files, which use the environment
              that was used to call the Builder for the target file.)

              b = Builder(action="build < $SOURCE > $TARGET")
              env = Environment(BUILDERS = {'MyBuild' : b})
              env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')


       chdir  A directory from which scons will execute the  action(s)  speci-
              fied  for  this Builder.  If the cchhddiirr argument is a string or a
              directory Node, scons will change to  the  specified  directory.
              If the cchhddiirr is not a string or Node and is non-zero, then scons
              will change to the target file's directory.

              Note that scons will _n_o_t automatically modify its  expansion  of
              construction  variables  like $$TTAARRGGEETT and $$SSOOUURRCCEE when using the
              chdir keyword argument--that is, the expanded  file  names  will
              still  be  relative  to  the top-level SConstruct directory, and
              consequently  incorrect  relative  to   the   chdir   directory.
              Builders  created using chdir keyword argument, will need to use
              construction  variable  expansions   like   $${{TTAARRGGEETT..ffiillee}}   and
              $${{SSOOUURRCCEE..ffiillee}}  to  use just the filename portion of the targets
              and source.

              b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
                          chdir=1)
              env = Environment(BUILDERS = {'MyBuild' : b})
              env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')

       WWAARRNNIINNGG:: Python only keeps one current directory location  for  all  of
       the  threads.   This means that use of the cchhddiirr argument will _n_o_t work
       with the SCons --jj option, because individual worker threads spawned  by
       SCons interfere with each other when they start changing directory.

       Any additional keyword arguments supplied when a Builder object is cre-
       ated (that is, when the Builder() function is called) will  be  set  in
       the  executing  construction  environment  when  the  Builder object is
       called.  The canonical example here would  be  to  set  a  construction
       variable to the repository of a source code system.

       Any  additional  keyword  arguments  supplied  when a Builder _o_b_j_e_c_t is
       called will only be associated with the target created by that particu-
       lar Builder call (and any other files built as a result of the call).

       These  extra  keyword  arguments are passed to the following functions:
       command generator functions, function Actions, and emitter functions.


   AAccttiioonn OObbjjeeccttss
       The BBuuiillddeerr(()) function will turn its aaccttiioonn keyword  argument  into  an
       appropriate  internal  Action  object.   You  can also explicity create
       Action objects using the AAccttiioonn() global function, which  can  then  be
       passed  to  the  BBuuiillddeerr()  function.  This can be used to configure an
       Action object more flexibly, or it may simply be  more  efficient  than
       letting each separate Builder object create a separate Action when mul-
       tiple Builder objects need to do the same thing.

       The AAccttiioonn() global function returns  an  appropriate  object  for  the
       action represented by the type of the first argument:


       Action If the first argument is already an Action object, the object is
              simply returned.


       String If the first argument is a  string,  a  command-line  Action  is
              returned.   Note that the command line string may be preceded by
              an @@ (at-sign) to suppress printing  of  the  specified  command
              line,  or  by  a  --  (hyphen) to ignore the exit status from the
              specified command.  Examples:

              Action('$CC -c -o $TARGET $SOURCES')

              # Doesn't print the line being executed.
              Action('@build $TARGET $SOURCES')

              # Ignores
              Action('-build $TARGET $SOURCES')




       List   If the first argument is a list, then a list of  Action  objects
              is  returned.  An Action object is created as necessary for each
              element in the list.  If an element _w_i_t_h_i_n the list is itself  a
              list,  the internal list is the command and arguments to be exe-
              cuted via the command line.   This  allows  white  space  to  be
              enclosed in an argument by defining a command in a list within a
              list:

              Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])


       Function
              If the first argument is a Python function, a function Action is
              returned.   The  Python  function takes three keyword arguments,
              ttaarrggeett (a Node object representing the target file),  ssoouurrccee  (a
              Node object representing the source file) and eennvv (the construc-
              tion environment used for building the target file).  The ttaarrggeett
              and  ssoouurrccee  arguments  may be lists of Node objects if there is
              more than one target file or source file.  The actual target and
              source file name(s) may be retrieved from their Node objects via
              the built-in Python str() function:

              target_file_name = str(target)
              source_file_names = map(lambda x: str(x), source)

              The function should return 00 or NNoonnee to  indicate  a  successful
              build  of  the target file(s).  The function may raise an excep-
              tion or return a non-zero exit status to indicate an  unsuccess-
              ful build.

              def build_it(target = None, source = None, env = None):
                  # build the target from the source
                  return 0

              a = Action(build_it)

       If the action argument is not one of the above, None is returned.


       The  second,  optional  argument  is used to define the output which is
       printed when the Action is actually performed.  In the absence of  this
       parameter,  or  if  it's an empty string, a default output depending on
       the type of the action is used. For example, a command-line action will
       print the executed command. The argument is either a python function or
       a string.

       In the first case, it's a function that returns a string to be  printed
       to  describe  the  action  being  executed.  Like a function to build a
       file, this function takes three arguments: ttaarrggeett (a Node object repre-
       senting the target file), ssoouurrccee (a Node object representing the source
       file) and eennvv (a construction  environment).   The  ttaarrggeett  and  ssoouurrccee
       arguments may be lists of Node objects if there is more than one target
       file or source file.

       In the second case, you provide the string itself.   The  string  typi-
       cally   contains  variables,  notably  $TARGET(S)  and  $SOURCE(S),  or
       consists of just a single variable, which is optionally  defined  some-
       where else.  SCons itself heavily uses the latter variant.

       Examples:

              def build_it(target, source, env):
                  # build the target from the source
                  return 0

              def string_it(target, source, env):
                  return "building '%s' from '%s'" % (target[0], source[0])

              # Use a positional argument.
              f = Action(build_it, string_it)
              s = Action(build_it, "building '$TARGET' from '$SOURCE'")

              # Alternatively, use a keyword argument.
              f = Action(build_it, strfunction=string_it)
              s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")

              # You can provide a configurable variable.
              l = Action(build_it, '$STRINGIT')

       The  third,  also optional argument is a list of construction variables
       whose values will be included in  the  signature  of  the  Action  when
       deciding whether a target should be rebuilt because the action changed.
       This is necessary whenever you want a target to be rebuilt when a  spe-
       cific construction variable changes, because the underlying Python code
       for a function will not change when the value of the construction vari-
       able does.

              def build_it(target, source, env):
                  # build the target from the 'XXX' construction variable
                  open(target[0], 'w').write(env['XXX'])
                  return 0

              # Use positional arguments.
              a = Action(build_it, '$STRINGIT', ['XXX'])

              # Alternatively, use a keyword argument.
              a = Action(build_it, varlist=['XXX'])

       The  AAccttiioonn() global function also takes a cchhddiirr keyword argument which
       specifies that scons will execute the  action  after  changing  to  the
       specified  directory.  If the chdir argument is a string or a directory
       Node, scons will change to the specified directory.  If the chdir argu-
       ment is not a string or Node and is non-zero, then scons will change to
       the target file's directory.

       Note that scons will _n_o_t automatically modify  its  expansion  of  con-
       struction  variables like $$TTAARRGGEETT and $$SSOOUURRCCEE when using the chdir key-
       word argument--that is, the expanded file names will still be  relative
       to the top-level SConstruct directory, and consequently incorrect rela-
       tive to the chdir directory.   Builders  created  using  chdir  keyword
       argument, will need to use construction variable expansions like $${{TTAARR--
       GGEETT..ffiillee}} and $${{SSOOUURRCCEE..ffiillee}} to use just the filename  portion  of  the
       targets and source.

              a = Action("build < ${SOURCE.file} > ${TARGET.file}",
                         chdir=1)

       The  AAccttiioonn()  global function also takes an eexxiittssttaattffuunncc keyword argu-
       ment which specifies a function that is  passed  the  exit  status  (or
       return  value) from the specified action and can return an arbitrary or
       modified value.  This can be used, for  example,  to  specify  that  an
       Action object's return value should be ignored and SCons should, there-
       fore, consider that the action always suceeds:

              def always_succeed(s):
                  # Always return 0, which indicates success.
                  return 0
              a = Action("build < ${SOURCE.file} > ${TARGET.file}",
                         exitstatfunc=always_succeed)


   MMiisscceellllaanneeoouuss AAccttiioonn FFuunnccttiioonnss
       ssccoonnss supplies a number of functions that arrange  for  various  common
       file and directory manipulations to be performed.  These are similar in
       concept to "tasks" in the Ant build tool, although  the  implementation
       is  slightly  different.   These  functions do not actually perform the
       specified action at the time the function is called, but instead return
       an  Action  object  that  can be executed at the appropriate time.  (In
       Object-Oriented terminology, these are actually  Action  _F_a_c_t_o_r_y  func-
       tions that return Action objects.)

       In practice, there are two natural ways that these Action Functions are
       intended to be used.

       First, if you need to perform the action at  the  time  the  SConscript
       file is being read, you can use the EExxeeccuuttee global function to do so:
              Execute(Touch('file'))

       Second, you can use these functions to supply Actions in a list for use
       by the CCoommmmaanndd method.  This can allow you to perform more  complicated
       sequences  of  file  manipulation  without relying on platform-specific
       external commands: that
              env = Environment(TMPBUILD = '/tmp/builddir')
              env.Command('foo.out', 'foo.in',
                          [Mkdir('$TMPBUILD'),
                           Copy('$TMPBUILD', '${SOURCE.dir}'),
                           "cd $TMPBUILD && make",
                           Delete('$TMPBUILD')])


       Chmod(_d_e_s_t, _m_o_d_e)
              Returns an Action object that changes  the  permissions  on  the
              specified  _d_e_s_t  file or directory to the specified _m_o_d_e.  Exam-
              ples:

              Execute(Chmod('file', 0755))

              env.Command('foo.out', 'foo.in',
                          [Copy('$TARGET', '$SOURCE'),
                           Chmod('$TARGET', 0755)])


       Copy(_d_e_s_t, _s_r_c)
              Returns an Action object that will copy the _s_r_c source  file  or
              directory to the _d_e_s_t destination file or directory.  Examples:

              Execute(Copy('foo.output', 'foo.input'))

              env.Command('bar.out', 'bar.in',
                          Copy('$TARGET', '$SOURCE'))


       Delete(_e_n_t_r_y, [_m_u_s_t___e_x_i_s_t])
              Returns an Action that deletes the specified _e_n_t_r_y, which may be
              a file or a directory tree.  If a directory  is  specified,  the
              entire  directory  tree will be removed.  If the _m_u_s_t___e_x_i_s_t flag
              is set, then a Python error will  be  thrown  if  the  specified
              entry  does not exist; the default is mmuusstt__eexxiisstt==00, that is, the
              Action will silently do nothing if the  entry  does  not  exist.
              Examples:

              Execute(Delete('/tmp/buildroot'))

              env.Command('foo.out', 'foo.in',
                          [Delete('${TARGET.dir}'),
                           MyBuildAction])

              Execute(Delete('file_that_must_exist', must_exist=1))


       Mkdir(_d_i_r)
              Returns  an  Action  that  creates the specified directory _d_i_r _.
              Examples:

              Execute(Mkdir('/tmp/outputdir'))

              env.Command('foo.out', 'foo.in',
                          [Mkdir('/tmp/builddir',
                           Copy('$SOURCE', '/tmp/builddir')
                           "cd /tmp/builddir && ])



       Move(_d_e_s_t, _s_r_c)
              Returns an Action that moves the specified _s_r_c file or directory
              to the specified _d_e_s_t file or directory.  Examples:

              Execute(Move('file.destination', 'file.source'))

              env.Command('output_file', 'input_file',
                          [MyBuildAction,
                           Move('$TARGET', 'file_created_by_MyBuildAction')])


       Touch(_f_i_l_e)
              Returns  an  Action  that  updates  the modification time on the
              specified _f_i_l_e.  Examples:

              Execute(Touch('file_to_be_touched'))

              env.Command('marker', 'input_file',
                          [MyBuildAction,
                           Touch('$TARGET')])


   VVaarriiaabbllee SSuubbssttiittuuttiioonn
       Before executing a command, ssccoonnss performs construction variable inter-
       polation  on  the  strings  that  make up the command line of builders.
       Variables are introduced by a $$  prefix.   Besides  construction  vari-
       ables,  scons  provides the following variables for each command execu-
       tion:


       TARGET The file name of the target being built, or the file name of the
              first target if multiple targets are being built.


       TARGETS
              The file names of all targets being built.


       SOURCE The  file  name  of the source of the build command, or the file
              name of the first source if multiple sources are being built.


       SOURCES
              The file names of the sources of the build command.

              (Note that the above variables are reserved and may not  be  set
              in a construction environment.)


       For  example, given the construction variable CC='cc', targets=['foo'],
       and sources=['foo.c', 'bar.c']:

              action='$CC -c -o $TARGET $SOURCES'

       would produce the command line:

              cc -c -o foo foo.c bar.c

       Variable names may be surrounded by curly braces ({}) to  separate  the
       name from the trailing characters.  Within the curly braces, a variable
       name may have a Python slice subscript appended to select one  or  more
       items from a list.  In the previous example, the string:

              ${SOURCES[1]}

       would produce:

              bar.c

       Additionally,  a variable name may have the following special modifiers
       appended within the enclosing curly braces to modify  the  interpolated
       string:


       base   The base path of the file name, including the directory path but
              excluding any suffix.


       dir    The name of the directory in which the file exists.


       file   The file name, minus any directory portion.


       filebase
              Just the basename of the file, minus any suffix  and  minus  the
              directory.


       suffix Just the file suffix.


       abspath
              The absolute path name of the file.


       posix  The  POSIX  form  of  the  path, with directories separated by //
              (forward slashes) not backslashes.  This is sometimes  necessary
              on  Windows  systems  when  a  path  references  a file on other
              (POSIX) systems.


       srcpath
              The directory and file name to the source file  linked  to  this
              file  through  VariantDir.   If  this file isn't linked, it just
              returns the directory and filename unchanged.


       srcdir The directory containing the source file  linked  to  this  file
              through  VariantDir.  If this file isn't linked, it just returns
              the directory part of the filename.


       rsrcpath
              The directory and file name to the source file  linked  to  this
              file through VariantDir.  If the file does not exist locally but
              exists in a Repository, the path in the Repository is  returned.
              If  this  file  isn't  linked, it just returns the directory and
              filename unchanged.


       rsrcdir
              The Repository directory containing the source  file  linked  to
              this  file  through  VariantDir.   If this file isn't linked, it
              just returns the directory part of the filename.


       For example, the specified target will expand as follows for the corre-
       sponding modifiers:

              $TARGET              => sub/dir/file.x
              ${TARGET.base}       => sub/dir/file
              ${TARGET.dir}        => sub/dir
              ${TARGET.file}       => file.x
              ${TARGET.filebase}   => file
              ${TARGET.suffix}     => .x
              ${TARGET.abspath}    => /top/dir/sub/dir/file.x

              SConscript('src/SConscript', variant_dir='sub/dir')
              $SOURCE              => sub/dir/file.x
              ${SOURCE.srcpath}    => src/file.x
              ${SOURCE.srcdir}     => src

              Repository('/usr/repository')
              $SOURCE              => sub/dir/file.x
              ${SOURCE.rsrcpath}   => /usr/repository/src/file.x
              ${SOURCE.rsrcdir}    => /usr/repository/src

       Note  that  curly  braces  braces may also be used to enclose arbitrary
       Python code to be evaluated.  (In fact, this is how the above modifiers
       are  substituted, they are simply attributes of the Python objects that
       represent TARGET, SOURCES, etc.)  See the section "Python Code  Substi-
       tution," below, for more thorough examples of how this can be used.

       Lastly,  a  variable  name may be a callable Python function associated
       with a construction variable in the environment.  The  function  should
       take  four  arguments: _t_a_r_g_e_t - a list of target nodes, _s_o_u_r_c_e - a list
       of source nodes, _e_n_v - the construction environment, _f_o_r___s_i_g_n_a_t_u_r_e -  a
       Boolean  value  that specifies whether the function is being called for
       generating a build signature.  SCons will insert  whatever  the  called
       function returns into the expanded string:

              def foo(target, source, env, for_signature):
                  return "bar"

              # Will expand $BAR to "bar baz"
              env=Environment(FOO=foo, BAR="$FOO baz")

       You can use this feature to pass arguments to a Python function by cre-
       ating a callable class that stores one or more arguments in an  object,
       and  then uses them when the ____ccaallll____(()) method is called.  Note that in
       this case, the entire variable expansion  must  be  enclosed  by  curly
       braces  so that the arguments will be associated with the instantiation
       of the class:

              class foo:
                  def __init__(self, arg):
                      self.arg = arg

                  def __call__(self, target, source, env, for_signature):
                      return self.arg + " bar"

              # Will expand $BAR to "my argument bar baz"
              env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")


       The special pseudo-variables $$(( and $$)) may be used to surround parts of
       a  command  line  that  may  change _w_i_t_h_o_u_t causing a rebuild--that is,
       which are not included in the signature of target files built with this
       command.   All  text between $$(( and $$)) will be removed from the command
       line before it is added to file signatures, and the $$(( and $$))  will  be
       removed before the command is executed.  For example, the command line:

              echo Last build occurred $( $TODAY $). > $TARGET


       would execute the command:

              echo Last build occurred $TODAY. > $TARGET


       but the command signature added to any target files would be:

              echo Last build occurred  . > $TARGET


   PPyytthhoonn CCooddee SSuubbssttiittuuttiioonn
       Any python code within $${{-}} pairs gets evaluated by python 'eval', with
       the python globals set to the current environment's set of construction
       variables.  So in the following case:
              env['COND'] = 0
              env.Command('foo.out', 'foo.in',
                 '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''')
       the command executed will be either
              echo FOO > foo.out
       or
              echo BAR > foo.out
       according to the current value of env['COND'] when the command is  exe-
       cuted.   The evaluation occurs when the target is being built, not when
       the SConscript is being read.  So if env['COND'] is  changed  later  in
       the SConscript, the final value will be used.

       Here's a more interesting example.  Note that all of COND, FOO, and BAR
       are environment variables, and their values are  substituted  into  the
       final  command.   FOO is a list, so its elements are interpolated sepa-
       rated by spaces.

              env=Environment()
              env['COND'] = 0
              env['FOO'] = ['foo1', 'foo2']
              env['BAR'] = 'barbar'
              env.Command('foo.out', 'foo.in',
                  'echo ${COND==1 and FOO or BAR} > $TARGET')

              # Will execute this:
              #  echo foo1 foo2 > foo.out

       SCons uses the following rules when converting  construction  variables
       into command lines:


       String When  the  value is a string it is interpreted as a space delim-
              ited list of command line arguments.


       List   When the value is a list it is interpreted as a list of  command
              line  arguments.  Each  element  of  the  list is converted to a
              string.


       Other  Anything that is not a list or string is converted to  a  string
              and interpreted as a single command line argument.


       Newline
              Newline  characters  (\n)  delimit lines. The newline parsing is
              done after all other parsing, so it is not  possible  for  argu-
              ments  (e.g. file names) to contain embedded newline characters.
              This limitation will likely go  away  in  a  future  version  of
              SCons.


   SSccaannnneerr OObbjjeeccttss
       You  can  use  the  SSccaannnneerr function to define objects to scan new file
       types for implicit dependencies.  Scanner accepts the  following  argu-
       ments:


       function
              This  can  be either: 1) a Python function that will process the
              Node (file) and return a list of strings (file names) represent-
              ing  the  implicit  dependencies found in the contents; or: 2) a
              dictionary that maps keys (typically the file  suffix,  but  see
              below  for  more  discussion)  to  other Scanners that should be
              called.

              If the argument is actually a Python function, the function must
              take three or four arguments:

                  def scanner_function(node, env, path):

                  def scanner_function(node, env, path, arg=None):

              The  nnooddee  argument  is the internal SCons node representing the
              file.  Use  ssttrr((nnooddee))  to  fetch  the  name  of  the  file,  and
              nnooddee..ggeett__ccoonntteennttss(())  to  fetch  contents of the file.  Note that
              the file is _n_o_t  guaranteed  to  exist  before  the  scanner  is
              called, so the scanner function should check that if there's any
              chance that the scanned file might not exist  (for  example,  if
              it's built from other files).

              The  eennvv  argument is the construction environment for the scan.
              Fetch values from it using the eennvv..DDiiccttiioonnaarryy(()) method.

              The ppaatthh argument is a tuple (or list) of directories  that  can
              be  searched for files.  This will usually be the tuple returned
              by the ppaatthh__ffuunnccttiioonn argument (see below).

              The aarrgg argument is the argument supplied when the  scanner  was
              created, if any.


       name   The  name  of  the Scanner.  This is mainly used to identify the
              Scanner internally.


       argument
              An optional argument that, if specified, will be passed  to  the
              scanner function (described above) and the path function (speci-
              fied below).


       skeys  An optional list that can be used  to  determine  which  scanner
              should  be used for a given Node.  In the usual case of scanning
              for file names, this argument will be a list of suffixes for the
              different  file  types  that this Scanner knows how to scan.  If
              the argument is a string, then it will be expanded into  a  list
              by the current environment.


       path_function
              A Python function that takes four or five arguments: a construc-
              tion environment, a Node for the directory containing the  SCon-
              script  file  in  which  the first target was defined, a list of
              target nodes, a list of source nodes, and an  optional  argument
              supplied  when  the  scanner  was  created.   The  ppaatthh__ffuunnccttiioonn
              returns a tuple of directories that can be searched for files to
              be  returned  by  this  Scanner  object.   (Note  that the FFiinndd--
              PPaatthhDDiirrss()  function  can  be  used  to  return   a   ready-made
              ppaatthh__ffuunnccttiioonn for a given construction variable name, instead of
              having to write your own function from scratch.)


       node_class
              The class of Node  that  should  be  returned  by  this  Scanner
              object.   Any  strings  or other objects returned by the scanner
              function that are not of this class  will  be  run  through  the
              nnooddee__ffaaccttoorryy function.


       node_factory
              A  Python  function  that will take a string or other object and
              turn it into the appropriate class of Node  to  be  returned  by
              this Scanner object.


       scan_check
              An  optional  Python  function  that takes two arguments, a Node
              (file) and a construction environment, and returns  whether  the
              Node  should,  in fact, be scanned for dependencies.  This check
              can be used to eliminate unnecessary calls to the scanner  func-
              tion  when,  for  example,  the underlying file represented by a
              Node does not yet exist.


       recursive
              An optional flag that specifies whether this scanner  should  be
              re-invoked  on  the  dependency  files  returned by the scanner.
              When this flag is not set, the Node subsystem will  only  invoke
              the  scanner  on  the  file being scanned, and not (for example)
              also on the files specified by the #include lines  in  the  file
              being  scanned.   _r_e_c_u_r_s_i_v_e may be a callable function, in which
              case it will be called with a list of  Nodes  found  and  should
              return  a list of Nodes that should be scanned recursively; this
              can be used to select a specific subset of Nodes for  additional
              scanning.

              Note  that  ssccoonnss  has a global SSoouurrcceeFFiilleeSSccaannnneerr object that is
              used  by  the  OObbjjeecctt(),  SShhaarreeddOObbjjeecctt(),   and   SSttaattiiccOObbjjeecctt()
              builders  to  decide  which scanner should be used for different
              file extensions.  You can using the  SSoouurrcceeFFiilleeSSccaannnneerr..aadddd__ssccaann--
              nneerr() method to add your own Scanner object to the ssccoonnss infras-
              tructure that builds target programs or libraries from a list of
              source files of different types:

              def xyz_scan(node, env, path):
                  contents = node.get_contents()
                  # Scan the contents and return the included files.

              XYZScanner = Scanner(xyz_scan)

              SourceFileScanner.add_scanner('.xyx', XYZScanner)

              env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])


SSYYSSTTEEMM--SSPPEECCIIFFIICC BBEEHHAAVVIIOORR
       SCons and its configuration files are very portable, due largely to its
       implementation in Python.  There are, however, a few portability issues
       waiting to trap the unwary.

   ..CC ffiillee ssuuffffiixx
       SCons  handles  the upper-case ..CC file suffix differently, depending on
       the capabilities of the underlying system.  On a case-sensitive  system
       such  as  Linux  or UNIX, SCons treats a file with a ..CC suffix as a C++
       source file.  On a  case-insensitive  system  such  as  Windows,  SCons
       treats a file with a ..CC suffix as a C source file.

   ..FF ffiillee ssuuffffiixx
       SCons  handles  the upper-case ..FF file suffix differently, depending on
       the capabilities of the underlying system.  On a case-sensitive  system
       such  as  Linux or UNIX, SCons treats a file with a ..FF suffix as a For-
       tran source file that is to be first run through the standard C prepro-
       cessor.   On  a case-insensitive system such as Windows, SCons treats a
       file with a ..FF suffix as a Fortran source file that should _n_o_t  be  run
       through the C preprocessor.

   WWiinnddoowwss:: CCyyggwwiinn TToooollss aanndd CCyyggwwiinn PPyytthhoonn vvss.. WWiinnddoowwss PPyytthhoonnss
       Cygwin  supplies  a set of tools and utilities that let users work on a
       Windows system using a more POSIX-like environment.  The Cygwin  tools,
       including  Cygwin  Python,  do  this, in part, by sharing an ability to
       interpret UNIX-like path names.  For example,  the  Cygwin  tools  will
       internally  translate  a  Cygwin path name like /cygdrive/c/mydir to an
       equivalent Windows pathname of C:/mydir (equivalent to C:\mydir).

       Versions of Python that are built for native Windows execution, such as
       the  python.org  and  ActiveState versions, do not have the Cygwin path
       name semantics.  This means that using  a  native  Windows  version  of
       Python  to  build  compiled  programs  using Cygwin tools (such as gcc,
       bison, and flex) may yield unpredictable results.  "Mixing  and  match-
       ing" in this way can be made to work, but it requires careful attention
       to the use of path names in your SConscript files.

       In practice, users can sidestep the issue  by  adopting  the  following
       rules:  When  using  gcc, use the Cygwin-supplied Python interpreter to
       run SCons; when using Microsoft Visual C/C++  (or  some  other  Windows
       compiler)  use  the  python.org or ActiveState version of Python to run
       SCons.

   WWiinnddoowwss:: ssccoonnss..bbaatt ffiillee
       On Windows systems, SCons is executed via  a  wrapper  ssccoonnss..bbaatt  file.
       This has (at least) two ramifications:

       First,  Windows command-line users that want to use variable assignment
       on the command line may have to put double quotes  around  the  assign-
       ments:

              scons "FOO=BAR" "BAZ=BLEH"

       Second, the Cygwin shell does not recognize this file as being the same
       as an ssccoonnss command issued at the command-line prompt.   You  can  work
       around this either by executing ssccoonnss..bbaatt from the Cygwin command line,
       or by creating a wrapper shell script named ssccoonnss ..


   MMiinnGGWW
       The MinGW bin directory must be in your PATH  environment  variable  or
       the  PATH  variable  under  the  ENV construction variable for SCons to
       detect and use the MinGW tools. When running under the  native  Windows
       Python  interpreter,  SCons will prefer the MinGW tools over the Cygwin
       tools, if they are both installed, regardless of the order of  the  bin
       directories  in  the  PATH  variable.  If  you have both MSVC and MinGW
       installed and you want to use MinGW instead  of  MSVC,  then  you  must
       explictly tell SCons to use MinGW by passing

              tools=['mingw']

       to the Environment() function, because SCons will prefer the MSVC tools
       over the MinGW tools.


EEXXAAMMPPLLEESS
       To help you get started using SCons,  this  section  contains  a  brief
       overview of some common tasks.


   BBaassiicc CCoommppiillaattiioonn FFrroomm aa SSiinnggllee SSoouurrccee FFiillee
              env = Environment()
              env.Program(target = 'foo', source = 'foo.c')

       Note:   Build  the file by specifying the target as an argument ("scons
       foo" or "scons foo.exe").  or by specifying a dot ("scons .").


   BBaassiicc CCoommppiillaattiioonn FFrroomm MMuullttiippllee SSoouurrccee FFiilleess
              env = Environment()
              env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))


   SSeettttiinngg aa CCoommppiillaattiioonn FFllaagg
              env = Environment(CCFLAGS = '-g')
              env.Program(target = 'foo', source = 'foo.c')


   SSeeaarrcchh TThhee LLooccaall DDiirreeccttoorryy FFoorr ..hh FFiilleess
       Note:  You do _n_o_t need to set CCFLAGS to specify -I  options  by  hand.
       SCons will construct the right -I options from CPPPATH.

              env = Environment(CPPPATH = ['.'])
              env.Program(target = 'foo', source = 'foo.c')


   SSeeaarrcchh MMuullttiippllee DDiirreeccttoorriieess FFoorr ..hh FFiilleess
              env = Environment(CPPPATH = ['include1', 'include2'])
              env.Program(target = 'foo', source = 'foo.c')


   BBuuiillddiinngg aa SSttaattiicc LLiibbrraarryy
              env = Environment()
              env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
              env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])


   BBuuiillddiinngg aa SShhaarreedd LLiibbrraarryy
              env = Environment()
              env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
              env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))


   LLiinnkkiinngg aa LLooccaall LLiibbrraarryy IInnttoo aa PPrrooggrraamm
              env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
              env.Library(target = 'mylib', source = Split('l1.c l2.c'))
              env.Program(target = 'prog', source = ['p1.c', 'p2.c'])


   DDeeffiinniinngg YYoouurr OOwwnn BBuuiillddeerr OObbjjeecctt
       Notice  that  when you invoke the Builder, you can leave off the target
       file suffix, and SCons will add it automatically.

              bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
                            suffix = '.pdf',
                            src_suffix = '.tex')
              env = Environment(BUILDERS = {'PDFBuilder' : bld})
              env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')

              # The following creates "bar.pdf" from "bar.tex"
              env.PDFBuilder(target = 'bar', source = 'bar')

       Note also that the above initialization overwrites the default  Builder
       objects, so the Environment created above can not be used call Builders
       like env.Program(), env.Object(), env.StaticLibrary(), etc.


   AAddddiinngg YYoouurr OOwwnn BBuuiillddeerr OObbjjeecctt ttoo aann EEnnvviirroonnmmeenntt
              bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
                            suffix = '.pdf',
                            src_suffix = '.tex')
              env = Environment()
              env.Append(BUILDERS = {'PDFBuilder' : bld})
              env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
              env.Program(target = 'bar', source = 'bar.c')

       You also can use other Pythonic techniques to add to the BUILDERS  con-
       struction variable, such as:

              env = Environment()
              env['BUILDERS]['PDFBuilder'] = bld


   DDeeffiinniinngg YYoouurr OOwwnn SSccaannnneerr OObbjjeecctt
       The   following   example   shows  an  extremely  simple  scanner  (the
       kkffiillee__ssccaann() function) that doesn't use a search path at all and simply
       returns  the  file  names  present  on any iinncclluuddee lines in the scanned
       file.  This would implicitly assume that all included files live in the
       top-level directory:

              import re

              include_re = re.compile(r'^include\s+(\S+)$', re.M)

              def kfile_scan(node, env, path, arg):
                  contents = node.get_contents()
                  includes = include_re.findall(contents)
                  return includes

              kscan = Scanner(name = 'kfile',
                              function = kfile_scan,
                              argument = None,
                              skeys = ['.k'])
              scanners = Environment().Dictionary('SCANNERS')
              env = Environment(SCANNERS = scanners + [kscan])

              env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')

              bar_in = File('bar.in')
              env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
              bar_in.target_scanner = kscan

       Here  is  a  similar  but more complete example that searches a path of
       directories (specified as the MMYYPPAATTHH construction variable)  for  files
       that actually exist:

              include_re = re.compile(r'^include\s+(\S+)$', re.M)

              def my_scan(node, env, path, arg):
                 contents = node.get_contents()
                 includes = include_re.findall(contents)
                 if includes == []:
                      return []
                  results = []
                  for inc in includes:
                      for dir in path:
                          file = dir + os.sep + inc
                          if os.path.exists(file):
                              results.append(file)
                              break
                  return results

              scanner = Scanner(name = 'myscanner',
                               function = my_scan,
                               argument = None,
                               skeys = ['.x'],
                               path_function = FindPathDirs('MYPATH'),
                               )
              scanners = Environment().Dictionary('SCANNERS')
              env = Environment(SCANNERS = scanners + [scanner])

       The  FFiinnddPPaatthhDDiirrss()  function  used  in  the previous example returns a
       function (actually a callable Python object) that will return a list of
       directories  specified  in  the  $$MMYYPPAATTHH construction variable.  If you
       need to customize how the search path is  derived,  you  would  provide
       your  own  ppaatthh__ffuunnccttiioonn  argument when creating the Scanner object, as
       follows:

              # MYPATH is a list of directories to search for files in
              def pf(env, dir, target, source, arg):
                  top_dir = Dir('#').abspath
                  results = []
                  if env.has_key('MYPATH'):
                      for p in env['MYPATH']:
                          results.append(top_dir + os.sep + p)
                  return results

              scanner = Scanner(name = 'myscanner',
                               function = my_scan,
                               argument = None,
                               skeys = ['.x'],
                               path_function = pf,
                               )


   CCrreeaattiinngg aa HHiieerraarrcchhiiccaall BBuuiilldd
       Notice that the file names specified  in  a  subdirectory's  SConscript
       file are relative to that subdirectory.

              SConstruct:

                  env = Environment()
                  env.Program(target = 'foo', source = 'foo.c')

                  SConscript('sub/SConscript')

              sub/SConscript:

                  env = Environment()
                  # Builds sub/foo from sub/foo.c
                  env.Program(target = 'foo', source = 'foo.c')

                  SConscript('dir/SConscript')

              sub/dir/SConscript:

                  env = Environment()
                  # Builds sub/dir/foo from sub/dir/foo.c
                  env.Program(target = 'foo', source = 'foo.c')


   SShhaarriinngg VVaarriiaabblleess BBeettwweeeenn SSCCoonnssccrriipptt FFiilleess
       You  must  explicitly  Export() and Import() variables that you want to
       share between SConscript files.

              SConstruct:

                  env = Environment()
                  env.Program(target = 'foo', source = 'foo.c')

                  Export("env")
                  SConscript('subdirectory/SConscript')

              subdirectory/SConscript:

                  Import("env")
                  env.Program(target = 'foo', source = 'foo.c')


   BBuuiillddiinngg MMuullttiippllee VVaarriiaannttss FFrroomm tthhee SSaammee SSoouurrccee
       Use the variant_dir keyword argument  to  the  SConscript  function  to
       establish  one  or  more  separate  variant build directory trees for a
       given source directory:

              SConstruct:

                  cppdefines = ['FOO']
                  Export("cppdefines")
                  SConscript('src/SConscript', variant_dir='foo')

                  cppdefines = ['BAR']
                  Export("cppdefines")
                  SConscript('src/SConscript', variant_dir='bar')

              src/SConscript:

                  Import("cppdefines")
                  env = Environment(CPPDEFINES = cppdefines)
                  env.Program(target = 'src', source = 'src.c')

       Note the use of the Export() method to set the "cppdefines" variable to
       a different value each time we call the SConscript function.


   HHiieerraarrcchhiiccaall BBuuiilldd ooff TTwwoo LLiibbrraarriieess LLiinnkkeedd WWiitthh aa PPrrooggrraamm
              SConstruct:

                  env = Environment(LIBPATH = ['#libA', '#libB'])
                  Export('env')
                  SConscript('libA/SConscript')
                  SConscript('libB/SConscript')
                  SConscript('Main/SConscript')

              libA/SConscript:

                  Import('env')
                  env.Library('a', Split('a1.c a2.c a3.c'))

              libB/SConscript:

                  Import('env')
                  env.Library('b', Split('b1.c b2.c b3.c'))

              Main/SConscript:

                  Import('env')
                  e = env.Copy(LIBS = ['a', 'b'])
                  e.Program('foo', Split('m1.c m2.c m3.c'))

       The '#' in the LIBPATH directories specify that they're relative to the
       top-level directory, so they don't turn into "Main/libA"  when  they're
       used in Main/SConscript.

       Specifying  only  'a'  and  'b'  for  the library names allows SCons to
       append the appropriate library prefix and suffix for the current  plat-
       form (for example, 'liba.a' on POSIX systems,


   CCuussttoommiizziinngg ccoonnssttrruuccttiioonn vvaarriiaabblleess ffrroomm tthhee ccoommmmaanndd lliinnee..
       The following would allow the C compiler to be specified on the command
       line or in the file custom.py.

              opts = Options('custom.py')
              opts.Add('CC', 'The C compiler.')
              env = Environment(options=opts)
              Help(opts.GenerateHelpText(env))

       The user could specify the C compiler on the command line:

              scons "CC=my_cc"

       or in the custom.py file:

              CC = 'my_cc'

       or get documentation on the options:

              $ scons -h

              CC: The C compiler.
                  default: None
                  actual: cc



   UUssiinngg MMiiccrroossoofftt VViissuuaall CC++++ pprreeccoommppiilleedd hheeaaddeerrss
       Since windows.h includes everything and the kitchen sink, it  can  take
       quite some time to compile it over and over again for a bunch of object
       files, so Microsoft provides a mechanism to compile a  set  of  headers
       once  and  then  include  the previously compiled headers in any object
       file. This technology is called precompiled headers. The general recipe
       is  to  create  a file named "StdAfx.cpp" that includes a single header
       named "StdAfx.h", and then include every header you want to  precompile
       in  "StdAfx.h",  and  finally include "StdAfx.h" as the first header in
       all the source files you are compiling to object files. For example:

       StdAfx.h:
              #include <windows.h>
              #include <my_big_header.h>

       StdAfx.cpp:
              #include <StdAfx.h>

       Foo.cpp:
              #include <StdAfx.h>

              /* do some stuff */

       Bar.cpp:
              #include <StdAfx.h>

              /* do some other stuff */

       SConstruct:
              env=Environment()
              env['PCHSTOP'] = 'StdAfx.h'
              env['PCH'] = env.PCH('StdAfx.cpp')[0]
              env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])

       For more information see the document for the PCH builder, and the  PCH
       and  PCHSTOP construction variables. To learn about the details of pre-
       compiled headers consult the MSDN documention for /Yc, /Yu, and /Yp.


   UUssiinngg MMiiccrroossoofftt VViissuuaall CC++++ eexxtteerrnnaall ddeebbuuggggiinngg iinnffoorrmmaattiioonn
       Since including debugging information in programs and shared  libraries
       can  cause  their  size to increase significantly, Microsoft provides a
       mechanism for including the debugging information in an  external  file
       called  a  PDB file. SCons supports PDB files through the PDB construc-
       tion variable.

       SConstruct:
              env=Environment()
              env['PDB'] = 'MyApp.pdb'
              env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])

       For more information see the document for the  PDB  construction  vari-
       able.


EENNVVIIRROONNMMEENNTT
       SCONS_LIB_DIR
              Specifies  the  directory  that contains the SCons Python module
              directory (e.g. /home/aroach/scons-src-0.01/src/engine).


       SCONSFLAGS
              A string of options that will be used by scons  in  addition  to
              those passed on the command line.


SSEEEE AALLSSOO
       ssccoonnss User Manual, ssccoonnss Design Document, ssccoonnss source code.


AAUUTTHHOORRSS
       Steven Knight <knight@baldmt.com>
       Anthony Roach <aroach@electriceyeball.com>




                                  March 2008                          SCONS(1)
