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=fortran-cxx-mix, --warn=no-fortran-cxx-mix
              Enables or disables the specific warning about  linking  Fortran
              and  C++  object  files  in a single executable, which can yield
              unpredictable behavior with some compilers.


       --warn=link, --warn=no-link
              Enables or disables warnings about link steps.


       --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
              sunf77
              sunf90
              sunf95
              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 begin-
              ning 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 packag-
              ing 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
              standard 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  addi-
              tional capabilities noted below); see the documentation for oopptt--
              ppaarrssee for a thorough discussion of its  option-processing  capa-
              bities.  (Note that although the ooppttppaarrssee module was not a stan-
              dard module until Python 2.3, ssccoonnss contains a  compatible  ver-
              sion of the module that is used to provide identical functional-
              ity 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 becomes 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.