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.

       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  propa-
       gate the value of PATH from your external environment as follows:

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

       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 necessary.  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 Clean() 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()

       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 WIN32 systems, ssccoonnss searches in order for the
       Microsoft Visual C++ tools, the MinGW tool chain,  the  Intel  compiler
       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 con-
       struction 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  Clean()
              function.


       --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.


       -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=pdb
              Re-run  SCons under the control of the pdb Python debugger.  The
              --debug=pdb argument will be stripped from the command-line, but
              all other arguments will be passed in-order to the SCons invoca-
              tion run by the debugger.


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


       --debug=dtree
              Print the dependency tree after each top-level target is  built.
              This prints out only derived files.


       --debug=time
              Prints  various  time profiling information: the time spent exe-
              cuting each build command, the total build time, the total  time
              spent  executing  build commands, the total time spent executing
              SConstruct and SConscript files, and the total time  spent  exe-
              cuting SCons itself.


       --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


       -e, --environment-overrides
              Variables  from  the execution environment override construction
              variables from the SConscript files.


       -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  can  cause  ssccoonnss  to miss
              changes in the  implicit  dependencies  in  cases  where  a  new
              implicit  dependency is added earlier in the implicit dependency
              search path (e.g. CPPPATH) than a  current  implicit  dependency
              with the same name.


       --implicit-deps-changed
              Force  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.


       -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 old a file must be before
              its  content  signature  is cached. 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 content signature cached. A nega-
              tive 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 cache the 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.


       --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.


       -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.)


       -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.


       --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=dependency, --warn=no-dependency
              Enables or disables warnings about dependencies.  These warnings
              are disabled by default.


       --warn=deprecated, --warn=no-deprecated
              Enables or disables warnings about use of  deprecated  features.
              These warnings are enabled by default.


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


       -Y _r_e_p_o_s_i_t_o_r_y, --repository=_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  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
       environment is created using the EEnnvviirroonnmmeenntt function:

              env = Environment()

       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MRROOOOTT  variable  from  the
       user's  external environment to the construction environment's EENNVV dic-
       tionary.  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ymmoouuss@@ccvvss..ssoouurrccee--
       f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 Win32 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 specified as an optional keyword argument:

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

       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 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
              c++
              cc
              dvipdf
              dvips
              f77
              g++
              g77
              gas
              gcc
              gnulink
              gs
              hpc++
              hpcc
              hplink
              icc
              icl
              ifl
              ilink
              jar
              javac
              javah
              latex
              lex
              link
              linkloc
              m4
              masm
              midl
              mingw
              mslib
              mslink
              msvc
              msvs
              nasm
              pdflatex
              pdftex
              qt
              rmic
              sgiar
              sgicc
              sgilink
              sunar
              sunc++
              suncc
              sunlink
              swig
              tar
              tex
              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 win32 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 target files) and ssoouurrccee (a list of source files).

       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'))

       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')

       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 nonstandard suffix:

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

       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.

       All builder methods return a Node or a list of Nodes, representing  the
       target  or  targets that will be built.  A list of Nodes is returned if
       there is more than one target, and a single Node is returned  if  there
       is  only  one  target.  A _N_o_d_e is an internal SCons object which repre-
       sents build targets or sources.

       The returned  Node(s)  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 = env.StaticObject('bar.c', CCFLAGS='-DBAR')
              env.Program(source = ['foo.c', bar_obj, '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.

       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 = env.StaticObject('bar.c', CCFLAGS='-DBAR')
              print "The path to bar_obj is:", str(bar_obj)

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


       CFile()

       env.CFile()
              Builds a C source file given a lex (.l) or yacc (.y) input file.
              The  suffix  specified by the $CFILESUFFIX construction variable
              (.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 (.ll), yacc (.yy) or uic
              (.ui) input file.  The suffix specified  by  the  $CXXFILESUFFIX
              construction variable (.cc 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 .dvi file from a .tex, .ltx or .latex input  file.   If
              the  source file suffix is .tex, 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
              ffiillee  and  invoke the $BIBTEX command line if the string bbiibbddaattaa
              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 .dvi (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')


       Jar()

       env.Jar()
              Builds a Java archive (.jar) file from a source tree  of  .class
              files.   If  the  $JAVACHDIR  value is set, the jjaarr command will
              change to the specified directory using the --CC option.   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')


       Java()

       env.Java()
              Builds  one or more Java class files from a source tree of .java
              files.  The class files will be placed underneath the  specified
              target  directory.   SCons  will parse each source .java file to
              find the classes (including inner classes) defined  within  that
              file, and from that figure out the target .class files that will
              be created.  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
              .class files will be placed in a directory reflecting the speci-
              fied package name.  For example, the file  _F_o_o_._j_a_v_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_u_b_/_d_i_r_/_F_o_o_._c_l_a_s_s class file.

              Example:

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


       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 either the
              names of .class files, or the objects  returned  from  the  JJaavvaa
              builder method.

              If  the construction variable JJAAVVAACCLLAASSSSDDIIRR 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 .class 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.


       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')


       MSVSProject()

       env.MSVSProject()
              Builds  Microsoft  Visual  Studio  project files.  This builds a
              Visual Studio project file, based on the version of Visual  Stu-
              dio  that is configured (either the latest installed version, or
              the version set by MMSSVVSS__VVEERRSSIIOONN in the Environment constructor).
              For  VS  6,  it  will generate ..ddsspp and ..ddssww files, for VS 7, it
              will generate ..vvccpprroojj and ..ssllnn files.

              It takes several lists  of  filenames  to  be  placed  into  the
              project  file, currently these are 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 the 'srcs' list is NOT added to the
              $SOURCES environment variable.  This is because it represents  a
              list  of  files  to be added to the project file, not the source
              used to build the project file (in this case,  the  'source'  is
              the SConscript file used to call MSVSProject).

              In  addition  to  these values (which are all optional, although
              not specifying any of them results in an  empty  project  file),
              the following values must be specified:

              target:  The  name of the target .dsp or .vcproj file.  The cor-
              rect suffix for the version of Visual Studio must be  used,  but
              the value

              env['MSVSPROJECTSUFFIX']

              will be defined to the correct value (see example below).

              variant:  The  name of this particular variant.  These are typi-
              cally things like "Debug" or "Release", but really can  be  any-
              thing  you  want.   Multiple calls to MSVSProject with different
              variants are allowed: all variants will be added to the  project
              file with their appropriate build targets and sources.

              buildtarget:  A  list of SCons.Node.FS objects which is returned
              from the command which builds the target.  This is used to  tell
              SCons what to build when the 'build' button is pressed inside of
              the IDE.

              Example Usage:

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

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

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


       Object()

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


       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  .pdf file from a .dvi input file (or, by extension, a
              .tex, .ltx, or .latex input file).  The suffix specified by  the
              $PDFSUFFIX  construction  variable  (.pdf  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  .ps  file from a .dvi input file (or, by extension, a
              .tex, .ltx, or .latex input file).  The suffix specified by  the
              $PSSUFFIX  construction variable (.ps 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++ or
              Fortran source files.  If any C, C++ 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 (speci-
              fied  by  the  $PROGPREFIX  construction  variable;  nothing  by
              default)  and  suffix (specified by the $PROGSUFFIX construction
              variable; by default, .exe 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_e_s (or _._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 .class 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 .class files, or the objects return from the
              JJaavvaa builder method.

              If  the construction variable JJAAVVAACCLLAASSSSDDIIRR 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 .class 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')


       SharedLibrary()

       env.SharedLibrary()
              Builds a shared library (.so on a POSIX system, .dll  on  WIN32)
              given  one  or  more  object  files  or C, C++ 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, lib on POSIX systems, nothing on
              Windows  systems) and suffix (specified by the $SHLIBSUFFIX con-
              struction variable; by default, .dll on Windows systems, .so  on
              POSIX  systems)  are  automatically  added  to the target if not
              already present.  Example:

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

              On WIN32 systems, the SShhaarreeddLLiibbrraarryy builder method  will  always
              build  an import (.lib) library in addition to the shared (.dll)
              library, adding a .lib library with the same basename  if  there
              is not already a .lib file explicitly listed in the targets.

              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  WIN32 systems, specifying "register=1" will cause the dll 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 "/s", to pre-
              vent dialogs from popping up and requiring user  attention  when
              it is run.  If you change $REGSVRFLAGS, be sure to include "/s".
              For example,

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


              will register "bar.dll" 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  options
              (e.g. -fPIC 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')


       StaticLibrary()

       env.StaticLibrary()
              Builds a static library given one or more object files or C, C++
              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, lib on POSIX  sys-
              tems,  nothing  on Windows systems) and suffix (specified by the
              $LIBSUFFIX construction variable; by default,  .lib  on  Windows
              systems,  .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++, or  Fortran
              source  files.   Source  files  must  have  one of the following
              extensions:

                .asm    assembly language file
                .ASM    assembly language file
                .c      C file
                .C      WIN32:  C file
                        POSIX:  C++ file
                .cc     C++ file
                .cpp    C++ file
                .cxx    C++ file
                .cxx    C++ file
                .c++    C++ file
                .C++    C++ file
                .f      Fortran file
                .F      WIN32:  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
                .s      assembly language file
                .S      WIN32:  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; 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')


       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.

              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 (.tlb) file from and input IDL
              file (.idl).  In addition, it will build the associated inteface
              stub  and  proxy  source  files.  It names them according to the
              base name of the .idl file.

              For example,

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

              Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.


       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.

              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')

       ssccoonnss automatically scans 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 exten-
       sions, 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, so the depen-
       dencies do not need to be specified explicitly.  In addition, all  tar-
       gets  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 con-
       struction environment (see below).


   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.

       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')
       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 con-
       struction 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.


       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])

       env.Alias(_a_l_i_a_s, [_t_a_r_g_e_t_s])
              Creates  one  or  more  phony targets that expand to one or more
              other targets.  Returns the Node object representing 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 targets to the alias.

              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'])


       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.)

              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.PrependENVPath('INCLUDE', include_path)
              print 'after:',env['ENV']['INCLUDE']

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


       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.

              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])
              This specifies a build directory _b_u_i_l_d___d_i_r in which to build all
              derived  files that would normally be built under _s_r_c___d_i_r.  Mul-
              tiple build directories can be set up for multiple  build  vari-
              ants,  for  example.   _s_r_c___d_i_r must be underneath the SConstruct
              file's directory,  and  _b_u_i_l_d___d_i_r  may  not  be  underneath  the
              _s_r_c___d_i_r _.

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

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

              Note that specifying a BBuuiillddDDiirr works most naturally with a sub-
              sidiary SConscript file in the source directory.   However,  you
              would then call the subsidiary SConscript file not in the source
              directory, but in the _b_u_i_l_d___d_i_r _, as if ssccoonnss had made a virtual
              copy  of  the  source tree regardless of the value of _d_u_p_l_i_c_a_t_e.
              This is how you tell ssccoonnss which variant of  a  source  tree  to
              build.  For example:

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


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


       Builder(_a_c_t_i_o_n,  [_m_u_l_t_i, _p_r_e_f_i_x, _s_u_f_f_i_x, _s_r_c___s_u_f_f_i_x, _s_r_c___b_u_i_l_d_e_r, _e_m_i_t_-
       _t_e_r])

       env.Builder(_a_c_t_i_o_n,  [_m_u_l_t_i,  _p_r_e_f_i_x,  _s_u_f_f_i_x, _s_r_c___s_u_f_f_i_x, _s_r_c___b_u_i_l_d_e_r,
       _e_m_i_t_t_e_r])
              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.


       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.

              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.


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

       env.Clean(_t_a_r_g_e_t, _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  target  is specified with the --cc command
              line option.  Multiple calls to CClleeaann() are legal, and create  a
              new  target  or  add files and directories to the clean list for
              the specified target.

              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:

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


       Command(_t_a_r_g_e_t, _s_o_u_r_c_e, _c_o_m_m_a_n_d_s)

       env.Command(_t_a_r_g_e_t, _s_o_u_r_c_e, _c_o_m_m_a_n_d_s)
              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.

              Note  that  an action can be an external command, specified as a
              string, or a  callable  Python  object;  see  "Action  Objects,"
              below.  Examples:

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

              env.Command('bar.out', 'bar.in',
                          ["rm -f $TARGET",
                           "$BAR_BUILD < $SOURCES > $TARGET"])

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

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


       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])

       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])
              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.Copy([_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.

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

              Additionally, a list of tools may be specified, as in the  Envi-
              ronment constructor:

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


       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:

              # 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'))


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

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

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

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

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


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


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

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

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


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

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


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

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


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

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

              EnsurePythonVersion(2,2)


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

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

              EnsureSConsVersion(0,9)


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

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


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

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


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

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

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

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

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

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


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


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

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


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

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

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


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

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


       GetLaunchDir()

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


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

       env.GetOption(_n_a_m_e)
              This  function  provides  a  way to query a select subset of the
              scons command line options from a SConscript  file.  See  _S_e_t_O_p_-
              _t_i_o_n() for a description of the options available.


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

       env.Help(_t_e_x_t)
              This  specifies  help  text  to be printed if the --hh argument is
              given to ssccoonnss.  ssccoonnss will exit after  printing  out  the  help
              text.


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

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

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


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

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

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


       Install(_d_i_r, _s_o_u_r_c_e)

       env.Install(_d_i_r, _s_o_u_r_c_e)
              Installs one or more files in a destination directory.  The file
              names remain the same.

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


       InstallAs(_t_a_r_g_e_t, _s_o_u_r_c_e)

       env.InstallAs(_t_a_r_g_e_t, _s_o_u_r_c_e)
              Installs  one  or  more  files  as specific file names, allowing
              changing a file name as part of  the  installation.   It  is  an
              error  if the target and source list different numbers of files.

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


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

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


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

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


       env.ParseConfig(_c_o_m_m_a_n_d, [_f_u_n_c_t_i_o_n])
              Calls the specified _f_u_n_c_t_i_o_n to modify the environment as speci-
              fied by the output of _c_o_m_m_a_n_d _.  The  default  _f_u_n_c_t_i_o_n  expects
              the  output of a typical _*_-_c_o_n_f_i_g _c_o_m_m_a_n_d (for example, ggttkk--ccoonn--
              ffiigg) and parses the returned --LL, --ll, --II and other  options  into
              the  LLIIBBPPAATTHH, LLIIBBSS, CCPPPPPPAATTHH and CCCCFFLLAAGGSS variables, respectively.


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

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

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


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

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

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

              env.Platform('posix')

              Note that the wwiinn3322 platform adds the SSYYSSTTEEMMRROOOOTT  variable  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ymmoouuss@@ccvvss..ssoouurrcceeffoorrggee..nneett:://ccvvssrroooott//ssccoonnss) will work
              on Win32 systems.


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

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


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

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


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

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

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


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

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

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


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

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


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

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

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

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


       Return(_v_a_r_s)
              This  tells ssccoonnss what variable(s) to use as the return value(s)
              of the current SConscript file. These variables will be returned
              to the "calling" SConscript file as the return value(s) of SSCCoonn--
              ssccrriipptt().  Multiple variable names should be passed to  RReettuurrnn()
              as a list. Example:

              Return("foo")
              Return(["foo", "bar"])


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

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


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

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

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


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

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

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

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

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

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

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

              The optional _b_u_i_l_d___d_i_r argument specifies that all of the target
              files (for example, object files  and  executables)  that  would
              normally  be  built  in the subdirectory in which _s_c_r_i_p_t resides
              should actually be built in _b_u_i_l_d___d_i_r.

              The optional _s_r_c___d_i_r argument specifies that  the  source  files
              from  which  the  target  files  should be built can be found in
              _s_r_c___d_i_r.

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

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

              Examples:

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


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

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

              SConscriptChdir(0)
              env.SConscriptChdir(0)

              in  which  case ssccoonnss will stay in the top-level directory while
              reading all SConscript  files.   (This  may  be  necessary  when
              building  from  repositories,  when all the directories in which
              SConscript files may be found don't necessarily exist  locally.)

              You  may  enable  and  disable  this  ability  by  calling SCon-
              scriptChdir() multiple times:

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


       SConsignFile([_f_i_l_e])

       env.SConsignFile([_f_i_l_e])
              This tells ssccoonnss to store all file signatures in  the  specified
              _f_i_l_e.  If the _f_i_l_e is omitted, ..ssccoonnssiiggnn..ddbbmm is used by default.
              If _f_i_l_e is not an absolute path name, the file is placed in  the
              same directory as the top-level SSCCoonnssttrruucctt file.  Examples:

              # Stores signatures in ".sconsign.dbm"
              # in the top-level SConstruct directory.
              SConsignFile()

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

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


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

       env.SetOption(_n_a_m_e, _v_a_l_u_e)
              This function provides a way to set a select subset of the scons
              command line options from a SConscript file.  The  options  sup-
              ported   are:  clean  which  cooresponds  to  -c,  --clean,  and
              --remove; implicit_cache which corresponds to  --implicit-cache;
              max_drift  which  corresponds to --max-drift; and num_jobs which
              corresponds to -j and --jobs. See the documentation for the cor-
              responding  command  line object for information about each spe-
              cific option. Example:

              SetOption('max_drift', 1)


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

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


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

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

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

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

              env.SourceCode('.', None)


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

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

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


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

       env.SourceSignatures(_t_y_p_e)
              This function tells SCons what type  of  signature  to  use  for
              source  files:  MMDD55  or ttiimmeessttaammpp.  If the environment method is
              used, the specified type of source signature is only  used  when
              deciding  whether targets built with that environment are up-to-
              date or must be rebuilt.  If the global function  is  used,  the
              specified  type of source signature becomes the default used for
              all decisions about whether targets are up-to-date.

              "MD5" means the signature of a source file is the  MD5  checksum
              of  its  contents.   "timestamp" means the signature of a source
              file is its timestamp (modification time).  When  using  "times-
              tamp"  signatures,  changes  in  the command line will not cause
              files to be rebuilt.  "MD5" signatures take longer  to  compute,
              but  are more accurate than "timestamp" signatures.  The default
              is "MD5".


       Split(_a_r_g)

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

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


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

       env.TargetSignatures(_t_y_p_e)
              This  function  tells  SCons  what type of signatures to use for
              target files: bbuuiilldd or ccoonntteenntt.  If the  environment  method  is
              used,  the  specified type of signature is only used for targets
              built with that environment.  If the global  function  is  used,
              the specified type of signature becomes the default used for all
              target files that don't have an explicit target  signature  type
              specified for their environments.

              "build" means the signature of a target file is made by concate-
              nating all of the signatures of all its source files.  "content"
              means  the  signature of a target file is an MD5 checksum of its
              contents.  "build" signatures are usually faster to compute, but
              "content"  signatures  can  prevent  unnecessary rebuilds when a
              target file is rebuilt to the exact same contents as the  previ-
              ous build.  The default is "build".


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

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

              env = Environment()
              t = Tool('msvc')
              t(env)  # adds 'msvc' to the TOOLS variable

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

              env.Tool('gcc')


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

       env.Value(_v_a_l_u_e)
              Returns a Node object representing the specified  Python  value.
              Value  nodes  can  be  used  as dependencies of targets.  If the
              result of calling ssttrr((value)) changes  between  SCons  runs,  any
              targets  depending  on VVaalluuee((value)) will be rebuilt.  When using
              timestamp source signatures, Value nodes' timestamps  are  equal
              to the system time when the node is created.

              def create(target, source, env):
                  f = open(str(target[0]), 'wb')
                  f.write('prefix=' + source[0].get_contents())

              prefix = ARGUMENTS.get('prefix', '/usr/local')
              env = Environment()
              env['BUILDERS']['Config'] = Builder(action = create)
              env.Config(target = 'package-config', source = Value(prefix))


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

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

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


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

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


       AR     The static library archiver.


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


       ARFLAGS
              General options passed to the static library archiver.


       AS     The assembler.


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


       ASFLAGS
              General options passed to the assembler.


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


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


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


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


       BITKEEPER
              The BitKeeper executable.


       BITKEEPERCOM
              The command line for fetching source files using BitKEeper.


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


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


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

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

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

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

              or this:

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


       CC     The C compiler.


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


       CCFLAGS
              General options that are passed to the C compiler.


       CFILESUFFIX
              The  suffix  for  C  source files.  This is used by the internal
              CFile builder when generating C files from Lex (.l) or YACC (.y)
              input files.  The default suffix, of course, is _._c (lower case).
              On case-insensitive systems (like Win32), SCons also  treats  _._C
              (upper case) files as C files.


       CCVERSION
              The  version  number  of the C compiler.  This may or may not be
              set, depending on the specific C compiler being used.


       _concat
              A function used to  produce  variables  like  $_CPPINCFLAGS.  It
              takes five arguments: a prefix to concatenate onto each element,
              a list of elements, a suffix to concatenate onto  each  element,
              an environment for variable interpolation, and an optional func-
              tion that will be called to transform the list before concatena-
              tion.

              env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',


       CPPDEFINES
              A  platform  independent specification of C preprocessor defini-
              tions.  The definitions will be added to command  lines  through
              the  automatically-generated $_CPPDEFFLAGS construction variable
              (see below), which is constructed according to the type of value
              of $CPPDEFINES:


              If  $CPPDEFINES is a string, the values of the $CPPDEFPREFIX and
              $CPPDEFSUFFIX construction variables will be added to the begin-
              ning and end.

              # Will add -Dxyz to POSIX compiler command lines,
              # and /Dxyz to Microsoft Visual C++ command lines.
              env = Environment(CPPDEFINES='xyz')


              If  $CPPDEFINES  is  a list, the values of the $CPPDEFPREFIX and
              $CPPDEFSUFFIX construction variables will  be  appended  to  the
              beginning  and  end of each element in the list.  If any element
              is a list or tuple, then  the  first  item  is  the  name  being
              defined and the second item is its value:

              # Will add -DB=2 -DA to POSIX compiler command lines,
              # and /DB=2 /DA to Microsoft Visual C++ command lines.
              env = Environment(CPPDEFINES=[('B', 2), 'A'])


              If  $CPPDEFINES is a dictionary, the values of the $CPPDEFPREFIX
              and $CPPDEFSUFFIX construction variables will be appended to the
              beginning  and end of each item from the dictionary.  The key of
              each dictionary item is a name being defined to  the  dictionary
              item's  corresponding value; if the value is NNoonnee, then the name
              is defined without an explicit value.  Note that  the  resulting
              flags  are  sorted  by  keyword  to ensure that the order of the
              options on the command line is consistent each time ssccoonnss
               is run.

              # Will add -DA -DB=2 to POSIX compiler command lines,
              # and /DA /DB=2 to Microsoft Visual C++ command lines.
              env = Environment(CPPDEFINES={'B':2, 'A':None})


       _CPPDEFFLAGS
              An automatically-generated construction variable containing  the
              C preprocessor command-line options to define values.  The value
              of $_CPPDEFFLAGS  is  created  by  appending  $CPPDEFPREFIX  and
              $CPPDEFSUFFIX  to  the  beginning  and  end of each directory in
              $CPPDEFINES.


       CPPDEFPREFIX
              The prefix used to specify preprocessor  definitions  on  the  C
              compiler  command  line.  This will be appended to the beginning
              of each definition in the $CPPDEFINES construction variable when
              the $_CPPDEFFLAGS variable is automatically generated.


       CPPDEFSUFFIX
              The  suffix  used  to  specify preprocessor definitions on the C
              compiler command line.  This will be appended to the end of each
              definition  in  the  $CPPDEFINES  construction variable when the
              $_CPPDEFFLAGS variable is automatically generated.


       CPPFLAGS
              User-specified C preprocessor options.  These will  be  included
              in  any command that uses the C preprocessor, including not just
              compilation of C and C++ source files via the $CCCOM,  $SHCCCOM,
              $CXXCOM  and $SHCXXCOM command lines, but also the $F77PPCOM and
              $SHF77PPCOM command lines used to compile a Fortran source file,
              and  the $ASPPCOM command line used to assemble an assembly lan-
              guage source file, after first running each file through  the  C
              preprocessor.   Note  that this variable does _n_o_t contain --II (or
              similar) include search path options that scons generates  auto-
              matically from $CPPPATH.  See __CCPPPPIINNCCFFLLAAGGSS, below, for the vari-
              able that expands to those options.


       _CPPINCFLAGS
              An automatically-generated construction variable containing  the
              C  preprocessor  command-line options for specifying directories
              to be searched for include files.  The value of $_CPPINCFLAGS is
              created  by appending $INCPREFIX and $INCSUFFIX to the beginning
              and end of each directory in $CPPPATH.


       CPPPATH
              The list of directories that the C preprocessor will search  for
              include  directories. The C/C++ implicit dependency scanner will
              search these directories for include files. Don't explicitly put
              include  directory  arguments in CCFLAGS or CXXFLAGS because the
              result will be non-portable and  the  directories  will  not  be
              searched  by  the  dependency  scanner. Note: directory names in
              CPPPATH will be looked-up relative to the  SConscript  directory
              when  they  are  used  in a command. To force ssccoonnss to look-up a
              directory relative to the root of the source tree use #:

              env = Environment(CPPPATH='#/include')


              The directory look-up can also be forced using the  DDiirr()  func-
              tion:

              include = Dir('include')
              env = Environment(CPPPATH=include)


              The  directory  list  will be added to command lines through the
              automatically-generated  $_CPPINCFLAGS  construction   variable,
              which  is  constructed by appending the values of the $INCPREFIX
              and $INCSUFFIX construction variables to the beginning  and  end
              of  each  directory  in  $CPPPATH.  Any command lines you define
              that  need   the   CPPPATH   directory   list   should   include
              $_CPPINCFLAGS:

              env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")


       CVS    The CVS executable.


       CVSCOFLAGS
              Options that are passed to the CVS checkout subcommand.


       CVSCOM The  command  line used to fetch source files from a CVS reposi-
              tory.


       CVSFLAGS
              General options that are passed to CVS.  By default, this is set
              to  "-d  $CVSREPOSITORY" to specify from where the files must be
              fetched.


       CVSREPOSITORY
              The path to the CVS  repository.   This  is  referenced  in  the
              default $CVSFLAGS value.


       CXX    The C++ compiler.


       CXXFILESUFFIX
              The  suffix  for C++ source files.  This is used by the internal
              CXXFile builder when generating C++ files from Lex (.ll) or YACC
              (.yy)  input  files.   The  default  suffix  is _._c_c.  SCons also
              treats files with the suffixes _._c_p_p, _._c_x_x, _._c_+_+, and _._C_+_+ as C++
              files.  On case-sensitive systems (Linux, UNIX, and other POSIX-
              alikes), SCons also treats _._C (upper case) files as C++ files.


       CXXCOM The command line used to compile a C++ source file to an  object
              file.  Any options specified in the $CXXFLAGS and $CPPFLAGS con-
              struction variables are included on this command line.


       CXXFLAGS
              General options that are passed to the C++ compiler.


       CXXVERSION
              The version number of the C++ compiler.  This may or may not  be
              set, depending on the specific C++ compiler being used.


       Dir    A  function  that converts a file name into a Dir instance rela-
              tive to the target being built.


       DVIPDF The TeX DVI file to PDF file converter.


       DVIPDFFLAGS
              General options passed to the TeX DVI  file  to  PDF  file  con-
              verter.


       DVIPDFCOM
              The  command line used to convert TeX DVI files into a PDF file.


       DVIPS  The TeX DVI file to PostScript converter.


       DVIPSFLAGS
              General options passed to the TeX DVI file  to  PostScript  con-
              verter.


       ENV    A  dictionary of environment variables to use when invoking com-
              mands.  Note that, by default,  ssccoonnss  does  _n_o_t  propagate  the
              environment in force when you execute ssccoonnss to the commands used
              to build target files.  This is so that builds will  be  guaran-
              teed  repeatable  regardless of the environment variables set at
              the time ssccoonnss is invoked.

              If you want to propagate your environment variables to the  com-
              mands executed to build target files, you must do so explicitly:

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

              Note that you can choose only to propagate  certain  environment
              variables.   A  common  example  is  the system PPAATTHH environment
              variable, so that ssccoonnss uses the same utilities as the  invoking
              shell (or other process):

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


       ESCAPE A  function  that will be called to escape shell special charac-
              ters in command lines. The function should  take  one  argument:
              the command line string to escape; and should return the escaped
              command line.


       F77    The Fortran compiler.


       F77COM The command line used to compile a Fortran  source  file  to  an
              object file.


       F77FLAGS
              General  user-specified  options  that are passed to the Fortran
              compiler.  Note that this variable does _n_o_t contain --II (or simi-
              lar)  include search path options that scons generates automati-
              cally from $F77PATH.  See __FF7777IINNCCFFLLAAGGSS, below, for the  variable
              that expands to those options.


       _F77INCFLAGS
              An  automatically-generated construction variable containing the
              Fortran compiler command-line options for specifying directories
              to be searched for include files.  The value of $_F77INCFLAGS is
              created by appending $INCPREFIX and $INCSUFFIX to the  beginning
              and end of each directory in $F77PATH.


       F77PATH
              The  list  of  directories that the Fortran compiler will search
              for include directories. The Fortran implicit dependency scanner
              will  search  these directories for include files. Don't explic-
              itly put include directory arguments  in  F77FLAGS  because  the
              result  will  be  non-portable  and  the directories will not be
              searched by the dependency scanner.  Note:  directory  names  in
              F77PATH  will  be looked-up relative to the SConscript directory
              when they are used in a command. To force  ssccoonnss  to  look-up  a
              directory relative to the root of the source tree use #:

              env = Environment(F77PATH='#/include')


              The  directory  look-up can also be forced using the DDiirr() func-
              tion:

              include = Dir('include')
              env = Environment(F77PATH=include)


              The directory list will be added to command  lines  through  the
              automatically-generated   $_F77INCFLAGS  construction  variable,
              which is constructed by appending the values of  the  $INCPREFIX
              and  $INCSUFFIX  construction variables to the beginning and end
              of each directory in $F77PATH.  Any  command  lines  you  define
              that   need   the   F77PATH   directory   list   should  include
              $_F77INCFLAGS:

              env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")


       F77PPCOM
              The command line used to compile a Fortran  source  file  to  an
              object  file  after first running the file through the C prepro-
              cessor.  Any options specified in the  $F77FLAGS  and  $CPPFLAGS
              construction variables are included on this command line.


       File   A  function that converts a file name into a File instance rela-
              tive to the target being built.


       GS     The Ghostscript program used to convert PostScript to PDF files.


       GSFLAGS
              General  options passed to the Ghostscript program when convert-
              ing PostScript to PDF files.


       GSCOM  The Ghostscript command line used to convert PostScript  to  PDF
              files.


       INCPREFIX
              The  prefix  used  to specify an include directory on the C com-
              piler command line.  This will be appended to the  beginning  of
              each  directory  in the $CPPPATH and $F77PATH construction vari-
              ables when the $_CPPINCFLAGS  and  $_F77INCFLAGS  variables  are
              automatically generated.


       INCSUFFIX
              The  suffix  used  to specify an include directory on the C com-
              piler command line.  This will be appended to the  end  of  each
              directory  in  the  $CPPPATH and $F77PATH construction variables
              when the $_CPPINCFLAGS and $_F77INCFLAGS variables are automati-
              cally generated.


       INSTALL
              A  function  to  be  called to install a file into a destination
              file name.  The default function copies the file into the desti-
              nation (and sets the destination file's mode and permission bits
              to match the source file's).  The function takes  the  following
              arguments:

              def install(dest, source, env):

              _d_e_s_t  is  the  path name of the destination file.  _s_o_u_r_c_e is the
              path name of the source file.  _e_n_v is the construction  environ-
              ment  (a  dictionary  of  construction values) in force for this
              file installation.


       JAR    The Java archive tool.


       JARCHDIR
              The directory to which  the  Java  archive  tool  should  change
              (using the --CC option).


       JARCOM The command line used to call the Java archive tool.


       JARFLAGS
              General  options  passed  to  the Java archive tool.  By default
              this is set to ccff to create the necessary _j_a_r file.


       JARSUFFIX
              The suffix for Java archives: ..jjaarr by default.


       JAVAC  The Java compiler.


       JAVACCOM
              The command line used to compile  a  directory  tree  containing
              Java  source  files  to  corresponding  Java  class  files.  Any
              options specified in the $JAVACFLAGS construction  variable  are
              included on this command line.


       JAVACFLAGS
              General options that are passed to the Java compiler.


       JAVACLASSDIR
              The  directory  in which Java class files may be found.  This is
              stripped from the beginning of any Java .class file  names  sup-
              plied to the JJaavvaaHH builder.


       JAVACLASSSUFFIX
              The suffix for Java class files; ..ccllaassss by default.


       JAVAH  The Java generator for C header and stub files.


       JAVAHCOM
              The  command  line used to generate C header and stub files from
              Java classes.  Any options specified  in  the  $JAVAHFLAGS  con-
              struction variable are included on this command line.


       JAVAHFLAGS
              General  options  passed to the C header and stub file generator
              for Java classes.


       JAVASUFFIX
              The suffix for Java files; ..jjaavvaa by default.


       LATEX  The LaTeX structured formatter and typesetter.


       LATEXCOM
              The command line used to call the LaTeX structured formatter and
              typesetter.


       LATEXFLAGS
              General  options  passed  to  the LaTeX structured formatter and
              typesetter.


       LEX    The lexical analyzer generator.


       LEXFLAGS
              General options passed to the lexical analyzer generator.


       LEXCOM The command line used to call the lexical analyzer generator  to
              generate a source file.


       _LIBDIRFLAGS
              An  automatically-generated construction variable containing the
              linker command-line options for  specifying  directories  to  be
              searched  for library.  The value of $_LIBDIRFLAGS is created by
              appending $LIBDIRPREFIX and $LIBDIRSUFFIX to the  beginning  and
              end of each directory in $LIBPATH.


       LIBDIRPREFIX
              The  prefix  used  to  specify a library directory on the linker
              command line.  This will be appended to the  beginning  of  each
              directory  in the $LIBPATH construction variable when the $_LIB-
              DIRFLAGS variable is automatically generated.


       LIBDIRSUFFIX
              The suffix used to specify a library  directory  on  the  linker
              command  line.   This will be appended to the end of each direc-
              tory in the  $LIBPATH  construction  variable  when  the  $_LIB-
              DIRFLAGS variable is automatically generated.


       _LIBFLAGS
              An  automatically-generated construction variable containing the
              linker command-line  options  for  specifying  libraries  to  be
              linked  with  the  resulting target.  The value of $_LIBFLAGS is
              created by appending $LIBLINKPREFIX and  $LIBLINKSUFFIX  to  the
              beginning and end of each directory in $LIBS.


       LIBLINKPREFIX
              The  prefix used to specify a library to link on the linker com-
              mand line.  This will be  appended  to  the  beginning  of  each
              library  in  the $LIBS construction variable when the $_LIBFLAGS
              variable is automatically generated.


       LIBLINKSUFFIX
              The suffix used to specify a library to link on the linker  com-
              mand  line.  This will be appended to the end of each library in
              the $LIBS construction variable when the $_LIBFLAGS variable  is
              automatically gene