therubyracer 0.4.6 → 0.4.7

data/ext/v8/upstream/scons/engine/SCons/dblite.py

@@ -0,0 +1,248 @@
+# dblite.py module contributed by Ralf W. Grosse-Kunstleve.
+# Extended for Unicode by Steven Knight.
+
+import cPickle
+import time
+import shutil
+import os
+import types
+import __builtin__
+
+keep_all_files = 00000
+ignore_corrupt_dbfiles = 0
+
+def corruption_warning(filename):
+    print "Warning: Discarding corrupt database:", filename
+
+if hasattr(types, 'UnicodeType'):
+    def is_string(s):
+        t = type(s)
+        return t is types.StringType or t is types.UnicodeType
+else:
+    def is_string(s):
+        return type(s) is types.StringType
+
+try:
+    unicode('a')
+except NameError:
+    def unicode(s): return s
+
+dblite_suffix = '.dblite'
+tmp_suffix = '.tmp'
+
+class dblite:
+
+  # Squirrel away references to the functions in various modules
+  # that we'll use when our __del__() method calls our sync() method
+  # during shutdown.  We might get destroyed when Python is in the midst
+  # of tearing down the different modules we import in an essentially
+  # arbitrary order, and some of the various modules's global attributes
+  # may already be wiped out from under us.
+  #
+  # See the discussion at:
+  #   http://mail.python.org/pipermail/python-bugs-list/2003-March/016877.html
+
+  _open = __builtin__.open
+  _cPickle_dump = cPickle.dump
+  _os_chmod = os.chmod
+  try:
+      _os_chown = os.chown
+  except AttributeError:
+      _os_chown = None
+  _os_rename = os.rename
+  _os_unlink = os.unlink
+  _shutil_copyfile = shutil.copyfile
+  _time_time = time.time
+
+  def __init__(self, file_base_name, flag, mode):
+    assert flag in (None, "r", "w", "c", "n")
+    if (flag is None): flag = "r"
+    base, ext = os.path.splitext(file_base_name)
+    if ext == dblite_suffix:
+      # There's already a suffix on the file name, don't add one.
+      self._file_name = file_base_name
+      self._tmp_name = base + tmp_suffix
+    else:
+      self._file_name = file_base_name + dblite_suffix
+      self._tmp_name = file_base_name + tmp_suffix
+    self._flag = flag
+    self._mode = mode
+    self._dict = {}
+    self._needs_sync = 00000
+    if self._os_chown is not None and (os.geteuid()==0 or os.getuid()==0):
+      # running as root; chown back to current owner/group when done
+      try:
+        statinfo = os.stat(self._file_name)
+        self._chown_to = statinfo.st_uid
+        self._chgrp_to = statinfo.st_gid
+      except OSError, e:
+        # db file doesn't exist yet.
+        # Check os.environ for SUDO_UID, use if set
+        self._chown_to = int(os.environ.get('SUDO_UID', -1))
+        self._chgrp_to = int(os.environ.get('SUDO_GID', -1))
+    else:
+      self._chown_to = -1        # don't chown
+      self._chgrp_to = -1        # don't chgrp
+    if (self._flag == "n"):
+      self._open(self._file_name, "wb", self._mode)
+    else:
+      try:
+        f = self._open(self._file_name, "rb")
+      except IOError, e:
+        if (self._flag != "c"):
+          raise e
+        self._open(self._file_name, "wb", self._mode)
+      else:
+        p = f.read()
+        if (len(p) > 0):
+          try:
+            self._dict = cPickle.loads(p)
+          except (cPickle.UnpicklingError, EOFError):
+            if (ignore_corrupt_dbfiles == 0): raise
+            if (ignore_corrupt_dbfiles == 1):
+              corruption_warning(self._file_name)
+
+  def __del__(self):
+    if (self._needs_sync):
+      self.sync()
+
+  def sync(self):
+    self._check_writable()
+    f = self._open(self._tmp_name, "wb", self._mode)
+    self._cPickle_dump(self._dict, f, 1)
+    f.close()
+    # Windows doesn't allow renaming if the file exists, so unlink
+    # it first, chmod'ing it to make sure we can do so.  On UNIX, we
+    # may not be able to chmod the file if it's owned by someone else
+    # (e.g. from a previous run as root).  We should still be able to
+    # unlink() the file if the directory's writable, though, so ignore
+    # any OSError exception  thrown by the chmod() call.
+    try: self._os_chmod(self._file_name, 0777)
+    except OSError: pass
+    self._os_unlink(self._file_name)
+    self._os_rename(self._tmp_name, self._file_name)
+    if self._os_chown is not None and self._chown_to > 0: # don't chown to root or -1
+      try:
+        self._os_chown(self._file_name, self._chown_to, self._chgrp_to)
+      except OSError:
+        pass
+    self._needs_sync = 00000
+    if (keep_all_files):
+      self._shutil_copyfile(
+        self._file_name,
+        self._file_name + "_" + str(int(self._time_time())))
+
+  def _check_writable(self):
+    if (self._flag == "r"):
+      raise IOError("Read-only database: %s" % self._file_name)
+
+  def __getitem__(self, key):
+    return self._dict[key]
+
+  def __setitem__(self, key, value):
+    self._check_writable()
+    if (not is_string(key)):
+      raise TypeError, "key `%s' must be a string but is %s" % (key, type(key))
+    if (not is_string(value)):
+      raise TypeError, "value `%s' must be a string but is %s" % (value, type(value))
+    self._dict[key] = value
+    self._needs_sync = 0001
+
+  def keys(self):
+    return self._dict.keys()
+
+  def has_key(self, key):
+    return key in self._dict
+
+  def __contains__(self, key):
+    return key in self._dict
+
+  def iterkeys(self):
+    return self._dict.iterkeys()
+
+  __iter__ = iterkeys
+
+  def __len__(self):
+    return len(self._dict)
+
+def open(file, flag=None, mode=0666):
+  return dblite(file, flag, mode)
+
+def _exercise():
+  db = open("tmp", "n")
+  assert len(db) == 0
+  db["foo"] = "bar"
+  assert db["foo"] == "bar"
+  db[unicode("ufoo")] = unicode("ubar")
+  assert db[unicode("ufoo")] == unicode("ubar")
+  db.sync()
+  db = open("tmp", "c")
+  assert len(db) == 2, len(db)
+  assert db["foo"] == "bar"
+  db["bar"] = "foo"
+  assert db["bar"] == "foo"
+  db[unicode("ubar")] = unicode("ufoo")
+  assert db[unicode("ubar")] == unicode("ufoo")
+  db.sync()
+  db = open("tmp", "r")
+  assert len(db) == 4, len(db)
+  assert db["foo"] == "bar"
+  assert db["bar"] == "foo"
+  assert db[unicode("ufoo")] == unicode("ubar")
+  assert db[unicode("ubar")] == unicode("ufoo")
+  try:
+    db.sync()
+  except IOError, e:
+    assert str(e) == "Read-only database: tmp.dblite"
+  else:
+    raise RuntimeError, "IOError expected."
+  db = open("tmp", "w")
+  assert len(db) == 4
+  db["ping"] = "pong"
+  db.sync()
+  try:
+    db[(1,2)] = "tuple"
+  except TypeError, e:
+    assert str(e) == "key `(1, 2)' must be a string but is <type 'tuple'>", str(e)
+  else:
+    raise RuntimeError, "TypeError exception expected"
+  try:
+    db["list"] = [1,2]
+  except TypeError, e:
+    assert str(e) == "value `[1, 2]' must be a string but is <type 'list'>", str(e)
+  else:
+    raise RuntimeError, "TypeError exception expected"
+  db = open("tmp", "r")
+  assert len(db) == 5
+  db = open("tmp", "n")
+  assert len(db) == 0
+  _open("tmp.dblite", "w")
+  db = open("tmp", "r")
+  _open("tmp.dblite", "w").write("x")
+  try:
+    db = open("tmp", "r")
+  except cPickle.UnpicklingError:
+    pass
+  else:
+    raise RuntimeError, "cPickle exception expected."
+  global ignore_corrupt_dbfiles
+  ignore_corrupt_dbfiles = 2
+  db = open("tmp", "r")
+  assert len(db) == 0
+  os.unlink("tmp.dblite")
+  try:
+    db = open("tmp", "w")
+  except IOError, e:
+    assert str(e) == "[Errno 2] No such file or directory: 'tmp.dblite'", str(e)
+  else:
+    raise RuntimeError, "IOError expected."
+  print "OK"
+
+if (__name__ == "__main__"):
+  _exercise()
+
+# Local Variables:
+# tab-width:4
+# indent-tabs-mode:nil
+# End:
+# vim: set expandtab tabstop=4 shiftwidth=4:

data/ext/v8/upstream/scons/engine/SCons/exitfuncs.py

@@ -0,0 +1,77 @@
+"""SCons.exitfuncs
+
+Register functions which are executed when SCons exits for any reason.
+
+"""
+
+#
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+# KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+
+__revision__ = "src/engine/SCons/exitfuncs.py 4629 2010/01/17 22:23:21 scons"
+
+
+
+_exithandlers = []
+def _run_exitfuncs():
+    """run any registered exit functions
+
+    _exithandlers is traversed in reverse order so functions are executed
+    last in, first out.
+    """
+
+    while _exithandlers:
+        func, targs, kargs =  _exithandlers.pop()
+        apply(func, targs, kargs)
+
+def register(func, *targs, **kargs):
+    """register a function to be executed upon normal program termination
+
+    func - function to be called at exit
+    targs - optional arguments to pass to func
+    kargs - optional keyword arguments to pass to func
+    """
+    _exithandlers.append((func, targs, kargs))
+
+import sys
+
+try:
+    x = sys.exitfunc
+
+    # if x isn't our own exit func executive, assume it's another
+    # registered exit function - append it to our list...
+    if x != _run_exitfuncs:
+        register(x)
+
+except AttributeError:
+    pass
+
+# make our exit function get run by python when it exits:    
+sys.exitfunc = _run_exitfuncs
+
+del sys
+
+# Local Variables:
+# tab-width:4
+# indent-tabs-mode:nil
+# End:
+# vim: set expandtab tabstop=4 shiftwidth=4:

data/ext/v8/upstream/scons/os_spawnv_fix.diff

@@ -0,0 +1,83 @@
+? dist/src/Mac/IDE scripts/Hold option to open a script
+? dist/src/Mac/IDE scripts/Insert file name
+? dist/src/Mac/IDE scripts/Insert folder name
+? dist/src/Mac/IDE scripts/Search Python Documentation
+? dist/src/Mac/IDE scripts/Hack/Remove .pyc files
+? dist/src/Mac/IDE scripts/Hack/Toolbox Assistant
+Index: dist/src/Modules/posixmodule.c
+===================================================================
+RCS file: /cvsroot/python/python/dist/src/Modules/posixmodule.c,v
+retrieving revision 2.213
+diff -c -c -r2.213 posixmodule.c
+*** dist/src/Modules/posixmodule.c	2001/12/03 20:41:00	2.213
+--- dist/src/Modules/posixmodule.c	2001/12/05 00:52:58
+***************
+*** 1668,1674 ****
+  #ifdef HAVE_SPAWNV
+  static char posix_spawnv__doc__[] =
+  "spawnv(mode, path, args)\n\
+! Execute an executable path with arguments, replacing current process.\n\
+  \n\
+  	mode: mode of process creation\n\
+  	path: path of executable file\n\
+--- 1668,1674 ----
+  #ifdef HAVE_SPAWNV
+  static char posix_spawnv__doc__[] =
+  "spawnv(mode, path, args)\n\
+! Execute the program 'path' in a new process.\n\
+  \n\
+  	mode: mode of process creation\n\
+  	path: path of executable file\n\
+***************
+*** 1717,1724 ****
+  
+  	if (mode == _OLD_P_OVERLAY)
+  		mode = _P_OVERLAY;
+  	spawnval = _spawnv(mode, path, argvlist);
+! 
+  	PyMem_DEL(argvlist);
+  
+  	if (spawnval == -1)
+--- 1717,1727 ----
+  
+  	if (mode == _OLD_P_OVERLAY)
+  		mode = _P_OVERLAY;
++ 	
++ 	Py_BEGIN_ALLOW_THREADS
+  	spawnval = _spawnv(mode, path, argvlist);
+! 	Py_END_ALLOW_THREADS
+! 	
+  	PyMem_DEL(argvlist);
+  
+  	if (spawnval == -1)
+***************
+*** 1734,1740 ****
+  
+  static char posix_spawnve__doc__[] =
+  "spawnve(mode, path, args, env)\n\
+! Execute a path with arguments and environment, replacing current process.\n\
+  \n\
+  	mode: mode of process creation\n\
+  	path: path of executable file\n\
+--- 1737,1743 ----
+  
+  static char posix_spawnve__doc__[] =
+  "spawnve(mode, path, args, env)\n\
+! Execute the program 'path' in a new process.\n\
+  \n\
+  	mode: mode of process creation\n\
+  	path: path of executable file\n\
+***************
+*** 1830,1836 ****
+--- 1833,1843 ----
+  
+  	if (mode == _OLD_P_OVERLAY)
+  		mode = _P_OVERLAY;
++ 
++ 	Py_BEGIN_ALLOW_THREADS
+  	spawnval = _spawnve(mode, path, argvlist, envlist);
++ 	Py_END_ALLOW_THREADS
++ 
+  	if (spawnval == -1)
+  		(void) posix_error();
+  	else

data/ext/v8/upstream/scons/scons-time.1

@@ -0,0 +1,1017 @@
+.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+.\"
+.\" Permission is hereby granted, free of charge, to any person obtaining
+.\" a copy of this software and associated documentation files (the
+.\" "Software"), to deal in the Software without restriction, including
+.\" without limitation the rights to use, copy, modify, merge, publish,
+.\" distribute, sublicense, and/or sell copies of the Software, and to
+.\" permit persons to whom the Software is furnished to do so, subject to
+.\" the following conditions:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+.\" KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+.\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+.\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+.\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+.\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+.\"
+.\" doc/man/scons-time.1 4629 2010/01/17 22:23:21 scons
+.\"
+.\" ES - Example Start - indents and turns off line fill
+.de ES
+.RS
+.nf
+..
+.\" EE - Example End - ends indent and turns line fill back on
+.de EE
+.RE
+.fi
+..
+'\"==========================================================================
+.de SF
+.B scons-time func
+[\fB-h\fR]
+[\fB--chdir=\fIDIR\fR]
+[\fB-f \fIFILE\fR]
+[\fB--fmt=\fIFORMAT\fR]
+[\fB--func=\fINAME\fR]
+[\fB-p \fISTRING\fR]
+[\fB-t \fINUMBER\fR]
+[\fB--title= TITLE\fR]
+[\fIARGUMENTS\fR]
+..
+'\"--------------------------------------------------------------------------
+.de SY
+.B scons-time mem
+[\fB-h\fR]
+[\fB--chdir=\fIDIR\fR]
+[\fB-f \fIFILE\fR]
+[\fB--fmt=\fIFORMAT\fR]
+[\fB-p \fISTRING\fR]
+[\fB--stage=\fISTAGE\fR]
+[\fB-t \fINUMBER\fR]
+[\fB--title=\fITITLE\fR]
+[\fIARGUMENTS\fR]
+..
+'\"--------------------------------------------------------------------------
+.de SO
+.B scons-time obj
+[\fB-h\fR]
+[\fB--chdir=\fIDIR\fR]
+[\fB-f \fIFILE\fR]
+[\fB--fmt=\fIFORMAT\fR]
+[\fB-p \fISTRING\fR]
+[\fB--stage=\fISTAGE\fR]
+[\fB-t \fINUMBER\fR]
+[\fB--title=\fITITLE\fR]
+[\fIARGUMENTS\fR]
+..
+'\"--------------------------------------------------------------------------
+.de SR
+.B scons-time run
+[\fB-hnqv\fR]
+[\fB--aegis=\fIPROJECT\fR]
+[\fB-f \fIFILE\fR]
+[\fB--number=\fINUMBER\fR]
+[\fB--outdir=\fIOUTDIR\fR]
+[\fB-p \fISTRING\fR]
+[\fB--python=\fIPYTHON\fR]
+[\fB-s \fIDIR\fR]
+[\fB--scons=\fISCONS\fR]
+[\fB--svn=\fIURL\fR]
+[\fIARGUMENTS\fR]
+..
+'\"--------------------------------------------------------------------------
+.de ST
+.B scons-time time
+[\fB-h\fR]
+[\fB--chdir=\fIDIR\fR]
+[\fB-f \fIFILE\fR]
+[\fB--fmt=\fIFORMAT\fR]
+[\fB-p \fISTRING\fR]
+[\fB-t \fINUMBER\fR]
+[\fB--title=\fITITLE\fR]
+[\fB--which=\fIWHICH\fR]
+[\fIARGUMENTS\fR]
+..
+.TH SCONS-TIME 1 "January 2010"
+.SH NAME
+scons-time \- generate and display SCons timing information
+'\"==========================================================================
+.SH SYNOPSIS
+.B scons-time
+.IR subcommand
+[
+.IR options ...
+]
+[
+.IR arguments ...
+]
+'\"--------------------------------------------------------------------------
+.SS "Generating Timing Information"
+.SR
+'\"--------------------------------------------------------------------------
+.SS "Extracting Function Timings"
+.SF
+'\"--------------------------------------------------------------------------
+.SS "Extracting Memory Statistics"
+.SY
+'\"--------------------------------------------------------------------------
+.SS "Extracting Object Counts"
+.SO
+'\"--------------------------------------------------------------------------
+.SS "Extracting Execution Times"
+.ST
+'\"--------------------------------------------------------------------------
+.SS "Help Text"
+.B scons-time help
+.I SUBCOMMAND
+[...]
+'\"==========================================================================
+.SH DESCRIPTION
+The 
+.B scons-time
+command runs an SCons configuration
+through a standard set of profiled timings
+and can extract and graph information from the
+resulting profiles and log files of those timings.
+The action to be performed by the
+.B scons-time
+script is specified
+by a subcommand, the first argument on the command line.
+See the
+.B SUBCOMMANDS
+section below for information about the operation
+of specific subcommands.
+.P
+The basic way to use
+.B scons-time
+is to run the
+.B scons-time run
+subcommand
+(possibly multiple times)
+to generate profile and log file output,
+and then use one of the other
+subcommands to display the results
+captured in the profiles and log files
+for a particular kind of information:
+function timings
+(the
+.B scons-time func
+subcommand),
+total memory used
+(the
+.B scons-time mem
+subcommand),
+object counts
+(the
+.B scons-time obj
+subcommand)
+and overall execution time
+(the
+.B scons-time time
+subcommand).
+Options exist to place and find the
+profiles and log files in separate directories,
+to generate the output in a format suitable
+for graphing with the
+.BR gnuplot (1)
+program,
+and so on.
+.P
+There are two basic ways the
+.B scons-time run
+subcommand
+is intended to be used
+to gather timing statistics
+for a configuration.
+One is to use the
+.B --svn=
+option to test a configuration against
+a list of revisions from the SCons Subversion repository.
+This will generate a profile and timing log file
+for every revision listed with the
+.B --number=
+option,
+and can be used to look at the
+impact of commited changes to the
+SCons code base on a particular
+configuration over time.
+.P
+The other way is to profile incremental changes to a
+local SCons code base during a development cycle--that is,
+to look at the performance impact of changes
+you're making in the local tree.
+In this mode,
+you run the
+.B scons-time run
+subcommand
+.I without
+the
+.B --svn=
+option,
+in which case it simply looks in the profile/log file output directory
+(the current directory by default)
+and automatically figures out the
+.I next
+run number for the output profile and log file.
+Used in this way,
+the development cycle goes something like:
+make a change to SCons;
+run
+.B scons-time run
+to profile it against a specific configuration;
+make another change to SCons;
+run
+.B scons-time run
+again to profile it;
+etc.
+'\"==========================================================================
+.SH OPTIONS
+The
+.B scons-time
+command only supports a few global options:
+.TP
+-h, --help
+Displays the global help text and exits,
+identical to the
+.B scons-time help
+subcommand.
+.TP
+-V, --version
+Displays the
+.B scons-time
+version and exits.
+.P
+Most functionality is controlled by options
+to the individual subcommands.
+See the next section for information
+about individual subcommand options.
+'\"==========================================================================
+.SH SUBCOMMANDS
+The
+.B scons-time
+command supports the following
+individual subcommands.
+'\"--------------------------------------------------------------------------
+.SS "The func Subcommand"
+.SF
+.P
+The
+.B scons-time func
+subcommand displays timing information
+for a specific Python function within SCons.
+By default, it extracts information about the
+.BR _main ()
+function,
+which includes the Python profiler timing
+for all of SCons.
+.P
+The
+.B scons-time func
+subcommand extracts function timing information
+from all the specified file arguments,
+which should be Python profiler output files.
+(Normally, these would be
+.B *.prof
+files generated by the
+.B scons-time run
+subcommand,
+but they can actually be generated
+by any Python profiler invocation.)
+All file name arguments will be
+globbed for on-disk files.
+.P
+If no arguments are specified,
+then function timing information
+will be extracted from all
+.B *.prof
+files,
+or the subset of them
+with a prefix specified by the
+.B -p
+option.
+.P
+Options include:
+.TP
+-C DIRECTORY, --chdir=DIRECTORY
+Changes to the specified
+.I DIRECTORY
+before looking for the specified files
+(or files that match the specified patterns).
+.TP
+-f FILE, --file=FILE
+Reads configuration information from the specified
+.IR FILE .
+.TP
+-fmt=FORMAT, --format=FORMAT
+Reports the output in the specified
+.IR FORMAT .
+The formats currently supported are
+.B ascii
+(the default)
+and
+.BR gnuplot .
+.TP
+--func=NAME
+Extracts timings for the specified function
+.IR NAME .
+The default is to report cumulative timings for the
+.BR _main ()
+function,
+which contains the entire SCons run.
+.TP
+-h, --help
+Displays help text for the
+.B scons-time func
+subcommand.
+.TP
+-p STRING, --prefix=STRING
+Specifies the prefix string for profiles
+from which to extract function timing information.
+This will be used to search for profiles
+if no arguments are specified on the command line.
+.TP
+-t NUMBER, --tail=NUMBER
+Only extracts function timings from the last
+.I NUMBER
+files.
+'\"--------------------------------------------------------------------------
+.SS "The help Subcommand"
+.B scons-time help
+.I SUBCOMMAND
+[...]
+The
+.B help
+subcommand prints help text for any
+other subcommands listed as later arguments on the command line.
+'\"--------------------------------------------------------------------------
+.SS "The mem Subcommand"
+.SY
+.P
+The
+.B scons-time mem
+subcommand displays how much memory SCons uses.
+.P
+The
+.B scons-time mem
+subcommand extracts memory use information
+from all the specified file arguments,
+which should be files containing output from
+running SCons with the
+.B --debug=memory
+option.
+(Normally, these would be
+.B *.log
+files generated by the
+.B scons-time run
+subcommand.)
+All file name arguments will be
+globbed for on-disk files.
+.P
+If no arguments are specified,
+then memory information
+will be extracted from all
+.B *.log
+files,
+or the subset of them
+with a prefix specified by the
+.B -p
+option.
+.P
+.TP
+-C DIR, --chdir=DIR
+Changes to the specified
+.I DIRECTORY
+before looking for the specified files
+(or files that match the specified patterns).
+.TP
+-f FILE, --file=FILE
+Reads configuration information from the specified
+.IR FILE .
+.TP
+-fmt=FORMAT, --format=FORMAT
+Reports the output in the specified
+.IR FORMAT .
+The formats currently supported are
+.B ascii
+(the default)
+and
+.BR gnuplot .
+.TP
+-h, --help
+Displays help text for the
+.B scons-time mem
+subcommand.
+.TP
+-p STRING, --prefix=STRING
+Specifies the prefix string for log files
+from which to extract memory usage information.
+This will be used to search for log files
+if no arguments are specified on the command line.
+.TP
+--stage=STAGE
+Prints the memory used at the end of the specified
+.IR STAGE :
+.B pre-read
+(before the SConscript files are read),
+.B post-read ,
+(after the SConscript files are read),
+.B pre-build
+(before any targets are built)
+or
+.B post-build
+(after any targets are built).
+If no
+.B --stage
+option is specified,
+the default behavior is
+.BR post-build ,
+which reports the final amount of memory
+used by SCons during each run.
+.TP
+-t NUMBER, --tail=NUMBER
+Only reports memory statistics from the last
+.I NUMBER
+files.
+'\"--------------------------------------------------------------------------
+.SS "The obj Subcommand"
+.SO
+.P
+The
+.B scons-time obj
+subcommand displays how many objects of a specific named type
+are created by SCons.
+.P
+The
+.B scons-time obj
+subcommand extracts object counts
+from all the specified file arguments,
+which should be files containing output from
+running SCons with the
+.B --debug=count
+option.
+(Normally, these would be
+.B *.log
+files generated by the
+.B scons-time run
+subcommand.)
+All file name arguments will be
+globbed for on-disk files.
+.P
+If no arguments are specified,
+then object counts
+will be extracted from all
+.B *.log
+files,
+or the subset of them
+with a prefix specified by the
+.B -p
+option.
+.TP
+-C DIR, --chdir=DIR
+Changes to the specified
+.I DIRECTORY
+before looking for the specified files
+(or files that match the specified patterns).
+.TP
+-f FILE, --file=FILE
+Reads configuration information from the specified
+.IR FILE .
+.TP
+-fmt=FORMAT, --format=FORMAT
+Reports the output in the specified
+.IR FORMAT .
+The formats currently supported are
+.B ascii
+(the default)
+and
+.BR gnuplot .
+.TP
+-h, --help
+Displays help text for the
+.B scons-time obj
+subcommand.
+.TP
+-p STRING, --prefix=STRING
+Specifies the prefix string for log files
+from which to extract object counts.
+This will be used to search for log files
+if no arguments are specified on the command line.
+.TP
+--stage=STAGE
+Prints the object count at the end of the specified
+.IR STAGE :
+.B pre-read
+(before the SConscript files are read),
+.B post-read ,
+(after the SConscript files are read),
+.B pre-build
+(before any targets are built)
+or
+.B post-build
+(after any targets are built).
+If no
+.B --stage
+option is specified,
+the default behavior is
+.BR post-build ,
+which reports the final object count during each run.
+.TP
+-t NUMBER, --tail=NUMBER
+Only reports object counts from the last
+.I NUMBER
+files.
+'\"--------------------------------------------------------------------------
+.SS "The run Subcommand"
+.SR
+The
+.B scons-time run
+subcommand is the basic subcommand
+for profiling a specific configuration
+against a version of SCons.
+.P
+The configuration to be tested
+is specified as a list of files
+or directories that will be unpacked or copied
+into a temporary directory
+in which SCons will be invoked.
+The
+.B scons-time run
+subcommand understands file suffixes like
+.BR .tar ,
+.BR .tar.gz ,
+.BR .tgz
+and
+.BR .zip
+and will unpack their contents into a temporary directory.
+If more than one argument is specified,
+each one will be unpacked or copied
+into the temporary directory "on top of"
+the previous archives or directories,
+so the expectation is that multiple
+specified archives share the same directory layout.
+.P
+Once the file or directory arguments are unpacked or
+copied to the temporary directory,
+the
+.B scons-time run
+subcommand runs the
+requested version of SCons
+against the configuration
+three times:
+.TP
+Startup
+SCons is run with the
+.B --help
+option so that just the SConscript files are read,
+and then the default help text is printed.
+This profiles just the perceived "overhead" of starting up SCons
+and processing the SConscript files.
+.TP
+Full build
+SCons is run to build everything specified in the configuration.
+Specific targets to be passed in on the command l ine
+may be specified by the
+.B targets
+keyword in a configuration file; see below for details.
+.TP
+Rebuild
+SCons is run again on the same just-built directory.
+If the dependencies in the SCons configuration are correct,
+this should be an up-to-date, "do nothing" rebuild.
+.P
+Each invocation captures the output log file and a profile.
+.P
+The
+.B scons-time run
+subcommand supports the following options:
+.TP
+--aegis=PROJECT
+Specifies the Aegis
+.I PROJECT
+from which the
+version(s) of
+.B scons
+being timed will be extracted.
+When
+.B --aegis
+is specified, the
+.BI --number= NUMBER
+option specifies delta numbers
+that will be tested.
+Output from each invocation run will be placed in file
+names that match the Aegis delta numbers.
+If the
+.B --number=
+option is not specified,
+then the default behavior is to time the
+tip of the specified
+.IR PROJECT .
+.TP
+-f FILE, --file=FILE
+Reads configuration information from the specified
+.IR FILE .
+This often provides a more convenient way to specify and
+collect parameters associated with a specific timing configuration
+than specifying them on the command line.
+See the
+.B CONFIGURATION FILE
+section below
+for information about the configuration file parameters.
+.TP
+-h, --help
+Displays help text for the
+.B scons-time run
+subcommand.
+.TP
+-n, --no-exec
+Do not execute commands,
+just printing the command-line equivalents of what would be executed.
+Note that the
+.B scons-time
+script actually executes its actions in Python,
+where possible,
+for portability.
+The commands displayed are UNIX
+.I equivalents
+of what it's doing.
+.TP
+--number=NUMBER
+Specifies the run number to be used in the names of
+the log files and profile outputs generated by this run.
+.IP
+When used in conjuction with the
+.BI --aegis= PROJECT
+option,
+.I NUMBER
+specifies one or more comma-separated Aegis delta numbers
+that will be retrieved automatically from the specified Aegis
+.IR PROJECT .
+.IP
+When used in conjuction with the
+.BI --svn= URL
+option,
+.I NUMBER
+specifies one or more comma-separated Subversion revision numbers
+that will be retrieved automatically from the Subversion
+repository at the specified
+.IR URL .
+Ranges of delta or revision numbers
+may be specified be separating two numbers
+with a hyphen
+.RB ( \- ).
+.P
+Example:
+.ES
+% scons-time run --svn=http://scons.tigris.org/svn/trunk --num=1247,1249-1252 .
+.EE
+.TP
+-p STRING, --prefix=STRING
+Specifies the prefix string to be used for all of the log files
+and profiles generated by this run.
+The default is derived from the first
+specified argument:
+if the first argument is a directory,
+the default prefix is the name of the directory;
+if the first argument is an archive
+(tar or zip file),
+the default prefix is the the base name of the archive,
+that is, what remains after stripping the archive suffix
+.RB ( .tgz ", " .tar.gz " or " .zip ).
+.TP
+--python=PYTHON
+Specifies a path to the Python executable to be used
+for the timing runs.
+The default is to use the same Python executable that
+is running the
+.B scons-time
+command itself.
+.TP
+-q, --quiet
+Suppresses display of the command lines being executed.
+.TP
+-s DIR, --subdir=DIR
+Specifies the name of directory or subdirectory
+from which the commands should be executed.
+The default is XXX
+.TP
+--scons=SCONS
+Specifies a path to the SCons script to be used
+for the timing runs.
+The default is XXX
+.TP
+--svn=URL, --subversion=URL
+Specifies the
+.I URL
+of the Subversion repository from which the
+version(s) of
+.B scons
+being timed will be extracted.
+When
+.B --svn
+is specified, the
+.BI --number= NUMBER
+option specifies revision numbers
+that will be tested.
+Output from each invocation run will be placed in file
+names that match the Subversion revision numbers.
+If the
+.B --number=
+option is not specified,
+then the default behavior is to time the
+.B HEAD
+of the specified
+.IR URL .
+.TP
+-v, --verbose
+Displays the output from individual commands to the screen
+(in addition to capturing the output in log files).
+'\"--------------------------------------------------------------------------
+.SS "The time Subcommand"
+.ST
+.P
+The
+.B scons-time time
+subcommand displays SCons execution times
+as reported by the
+.B scons --debug=time
+option.
+.P
+The
+.B scons-time time
+subcommand extracts SCons timing
+from all the specified file arguments,
+which should be files containing output from
+running SCons with the
+.B --debug=time
+option.
+(Normally, these would be
+.B *.log
+files generated by the
+.B scons-time run
+subcommand.)
+All file name arguments will be
+globbed for on-disk files.
+.P
+If no arguments are specified,
+then execution timings
+will be extracted from all
+.B *.log
+files,
+or the subset of them
+with a prefix specified by the
+.B -p
+option.
+.TP
+-C DIR, --chdir=DIR
+Changes to the specified
+.I DIRECTORY
+before looking for the specified files
+(or files that match the specified patterns).
+.TP
+-f FILE, --file=FILE
+Reads configuration information from the specified
+.IR FILE .
+.TP
+-fmt=FORMAT, --format=FORMAT
+Reports the output in the specified
+.IR FORMAT .
+The formats currently supported are
+.B ascii
+(the default)
+and
+.BR gnuplot .
+.TP
+-h, --help
+Displays help text for the
+.B scons-time time
+subcommand.
+.TP
+-p STRING, --prefix=STRING
+Specifies the prefix string for log files
+from which to extract execution timings.
+This will be used to search for log files
+if no arguments are specified on the command line.
+.TP
+-t NUMBER, --tail=NUMBER
+Only reports object counts from the last
+.I NUMBER
+files.
+.TP
+--which=WHICH
+Prints the execution time for the specified
+.IR WHICH
+value:
+.B total
+(the total execution time),
+.B SConscripts
+(total execution time for the SConscript files themselves),
+.B SCons
+(exectuion time in SCons code itself)
+or
+.B commands
+(execution time of the commands and other actions
+used to build targets).
+If no
+.B --which
+option is specified,
+the default behavior is
+.BR total ,
+which reports the total execution time for each run.
+'\"==========================================================================
+.SH CONFIGURATION FILE
+Various
+.B scons-time
+subcommands can read information from a specified
+configuration file when passed the
+.B \-f
+or
+.B \--file
+options.
+The configuration file is actually executed as a Python script.
+Setting Python variables in the configuration file
+controls the behavior of the
+.B scons-time
+script more conveniently than having to specify
+command-line options or arguments for every run,
+and provides a handy way to "shrink-wrap"
+the necessary information for producing (and reporting)
+consistent timing runs for a given configuration.
+.TP
+.B aegis
+The Aegis executable for extracting deltas.
+The default is simply
+.BR aegis .
+.TP
+.B aegis_project
+The Aegis project from which deltas should be extracted.
+The default is whatever is specified
+with the
+.B --aegis=
+command-line option.
+.TP
+.B archive_list
+A list of archives (files or directories)
+that will be copied to the temporary directory
+in which SCons will be invoked.
+.BR .tar ,
+.BR .tar.gz ,
+.BR .tgz
+and
+.BR .zip
+files will have their contents unpacked in
+the temporary directory.
+Directory trees and files will be copied as-is.
+.TP
+.B initial_commands
+A list of commands that will be executed
+before the actual timed
+.B scons
+runs.
+This can be used for commands that are necessary
+to prepare the source tree\-for example,
+creating a configuration file
+that should not be part of the timed run.
+.TP
+.B key_location
+The location of the key on Gnuplot graphing information
+generated with the
+.BR --format=gnuplot
+option.
+The default is
+.BR "bottom left" .
+.TP
+.B prefix
+The file name prefix to be used when
+running or extracting timing for this configuration.
+.TP
+.B python
+The path name of the Python executable
+to be used when running or extracting information
+for this configuration.
+The default is the same version of Python
+used to run the SCons
+.TP
+.B scons
+The path name of the SCons script to be used
+when running or extracting information
+for this configuration.
+The default is simply
+.BR scons .
+.TP
+.B scons_flags
+The
+.B scons
+flags used when running SCons to collect timing information.
+The default value is
+.BR "--debug=count --debug=memory --debug=time --debug=memoizer" .
+.TP
+.B scons_lib_dir
+.TP
+.B scons_wrapper
+.TP
+.B startup_targets
+.TP
+.B subdir
+The subdirectory of the project into which the
+.B scons-time
+script should change
+before executing the SCons commands to time.
+.TP
+.B subversion_url
+The Subversion URL from
+.TP
+.B svn
+The subversion executable used to
+check out revisions of SCons to be timed.
+The default is simple
+.BR svn .
+.TP
+.B svn_co_flag
+.TP
+.B tar
+.TP
+.B targets
+A string containing the targets that should be added to
+the command line of every timed
+.B scons
+run.
+This can be used to restrict what's being timed to a
+subset of the full build for the configuration.
+.TP
+.B targets0
+.TP
+.B targets1
+.TP
+.B targets2
+.TP
+.B title
+.TP
+.B unzip
+.TP
+.B verbose
+.TP
+.B vertical_bars
+'\"--------------------------------------------------------------------------
+.SS Example
+Here is an example
+.B scons-time
+configuration file
+for a hypothetical sample project:
+.P
+.ES
+# The project doesn't use SCons natively (yet), so we're
+# timing a separate set of SConscript files that we lay
+# on top of the vanilla unpacked project tarball.
+arguments = ['project-1.2.tgz', 'project-SConscripts.tar']
+
+# The subdirectory name contains the project version number,
+# so tell scons-time to chdir there before building.
+subdir = 'project-1.2'
+
+# Set the prefix so output log files and profiles are named:
+#     project-000-[012].{log,prof}
+#     project-001-[012].{log,prof}
+# etc.
+prefix = 'project'
+
+# The SConscript files being tested don't do any SConf
+# configuration, so run their normal ./configure script
+# before we invoke SCons.
+initial_commands = [
+    './configure',
+]
+
+# Only time building the bin/project executable.
+targets = 'bin/project'
+
+# Time against SCons revisions of the branches/core branch
+subversion_url = 'http://scons.tigris.org/svn/scons/branches/core'
+.EE
+'\"==========================================================================
+.SH ENVIRONMENT
+The
+.B scons-time
+script uses the following environment variables:
+.TP
+.B PRESERVE
+If this value is set,
+the
+.B scons-time
+script will
+.I not
+remove the temporary directory or directories
+in which it builds the specified configuration
+or downloads a specific version of SCons.
+'\"==========================================================================
+.SH "SEE ALSO"
+.BR gnuplot (1),
+.BR scons (1)
+
+.SH AUTHORS
+Steven Knight <knight at baldmt dot com>