Commits

dirkbaechle  committed 204804d

- switching MAN pages from troff format to Docbook/refentry

  • Participants
  • Parent commits 4c37565

Comments (0)

Files changed (7)

File doc/man/MANIFEST

-scons.1
-sconsign.1
+scons.xml
+sconsign.xml

File doc/man/scons-time.1

-.\" __COPYRIGHT__
-.\"
-.\" 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.
-.\"
-.\" __FILE__ __REVISION__ __DATE__ __DEVELOPER__
-.\"
-.\" 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 "__MONTH_YEAR__"
-.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>

File doc/man/scons-time.xml

+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!-- lifted from troff+man by doclifter -->
+<refentry id='sconstime1'>
+<!--  __COPYRIGHT__ -->
+
+<!--  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. -->
+
+<!--  __FILE__ __REVISION__ __DATE__ __DEVELOPER__ -->
+
+<!--  ES \- Example Start \- indents and turns off line fill -->
+<!--  EE \- Example End \- ends indent and turns line fill back on -->
+<!-- '\"========================================================================== -->
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+<refmeta>
+<refentrytitle>SCONS-TIME</refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo class='source'>__MONTH_YEAR__</refmiscinfo>
+</refmeta>
+<refnamediv id='name'>
+<refname>scons-time</refname>
+<refpurpose>generate and display SCons timing information</refpurpose>
+</refnamediv>
+<refsynopsisdiv id='synopsis'>
+<cmdsynopsis>
+  <command>scons-time</command>    
+    <arg choice='plain'><replaceable>subcommand</replaceable></arg>
+    <arg choice='opt' rep='repeat'><replaceable>options</replaceable></arg>
+    <arg choice='opt' rep='repeat'><replaceable>arguments</replaceable></arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<!-- body begins here -->
+
+<refsect1 id='generating_timing_information'><title>Generating Timing Information</title>
+<para><emphasis remap='B'>scons-time run</emphasis>
+[<option>-hnqv</option>]
+[<option>--aegis=</option><replaceable>PROJECT</replaceable>]
+[<option>-f </option><emphasis remap='I'>FILE</emphasis>]
+[<option>--number=</option><replaceable>NUMBER</replaceable>]
+[<option>--outdir=</option><replaceable>OUTDIR</replaceable>]
+[<option>-p </option><emphasis remap='I'>STRING</emphasis>]
+[<option>--python=</option><replaceable>PYTHON</replaceable>]
+[<option>-s </option><emphasis remap='I'>DIR</emphasis>]
+[<option>--scons=</option><replaceable>SCONS</replaceable>]
+[<option>--svn=</option><replaceable>URL</replaceable>]
+[<emphasis remap='I'>ARGUMENTS</emphasis>]</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+
+<refsect2 id='extracting_function_timings'><title>Extracting Function Timings</title>
+<para><emphasis remap='B'>scons-time func</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis remap='I'>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>--func=</option><replaceable>NAME</replaceable>]
+[<option>-p </option><emphasis remap='I'>STRING</emphasis>]
+[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>]
+[<option>--title= TITLE</option>]
+[<emphasis remap='I'>ARGUMENTS</emphasis>]</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+</refsect2>
+
+<refsect2 id='extracting_memory_statistics'><title>Extracting Memory Statistics</title>
+<para><emphasis remap='B'>scons-time mem</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis remap='I'>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>-p </option><emphasis remap='I'>STRING</emphasis>]
+[<option>--stage=</option><replaceable>STAGE</replaceable>]
+[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>]
+[<option>--title=</option><replaceable>TITLE</replaceable>]
+[<emphasis remap='I'>ARGUMENTS</emphasis>]</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+</refsect2>
+
+<refsect2 id='extracting_object_counts'><title>Extracting Object Counts</title>
+<para><emphasis remap='B'>scons-time obj</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis remap='I'>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>-p </option><emphasis remap='I'>STRING</emphasis>]
+[<option>--stage=</option><replaceable>STAGE</replaceable>]
+[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>]
+[<option>--title=</option><replaceable>TITLE</replaceable>]
+[<emphasis remap='I'>ARGUMENTS</emphasis>]</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+</refsect2>
+
+<refsect2 id='extracting_execution_times'><title>Extracting Execution Times</title>
+<para><emphasis remap='B'>scons-time time</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis remap='I'>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>-p </option><emphasis remap='I'>STRING</emphasis>]
+[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>]
+[<option>--title=</option><replaceable>TITLE</replaceable>]
+[<option>--which=</option><replaceable>WHICH</replaceable>]
+[<emphasis remap='I'>ARGUMENTS</emphasis>]</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+</refsect2>
+
+<refsect2 id='help_text'><title>Help Text</title>
+<para><emphasis remap='B'>scons-time help</emphasis>
+<emphasis remap='I'>SUBCOMMAND</emphasis>
+[...]</para>
+<!-- '\"========================================================================== -->
+</refsect2>
+</refsect1>
+
+<refsect1 id='description'><title>DESCRIPTION</title>
+<para>The 
+<command>scons-time</command>
+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
+<command>scons-time</command>
+script is specified
+by a subcommand, the first argument on the command line.
+See the
+<link linkend="subcommands">SUBCOMMANDS</link>
+section below for information about the operation
+of specific subcommands.</para>
+
+<para>The basic way to use
+<command>scons-time</command>
+is to run the
+<emphasis remap='B'>scons-time run</emphasis>
+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
+<emphasis remap='B'>scons-time func</emphasis>
+subcommand),
+total memory used
+(the
+<emphasis remap='B'>scons-time mem</emphasis>
+subcommand),
+object counts
+(the
+<emphasis remap='B'>scons-time obj</emphasis>
+subcommand)
+and overall execution time
+(the
+<emphasis remap='B'>scons-time time</emphasis>
+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
+<citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+program,
+and so on.</para>
+
+<para>There are two basic ways the
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand
+is intended to be used
+to gather timing statistics
+for a configuration.
+One is to use the
+<option>--svn=</option>
+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
+<option>--number=</option>
+option,
+and can be used to look at the
+impact of commited changes to the
+SCons code base on a particular
+configuration over time.</para>
+
+<para>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
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand
+<emphasis remap='I'>without</emphasis>
+the
+<option>--svn=</option>
+option,
+in which case it simply looks in the profile/log file output directory
+(the current directory by default)
+and automatically figures out the
+<emphasis remap='I'>next</emphasis>
+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
+<emphasis remap='B'>scons-time run</emphasis>
+to profile it against a specific configuration;
+make another change to SCons;
+run
+<emphasis remap='B'>scons-time run</emphasis>
+again to profile it;
+etc.</para>
+<!-- '\"========================================================================== -->
+</refsect1>
+
+<refsect1 id='options'><title>OPTIONS</title>
+<para>The
+<command>scons-time</command>
+command only supports a few global options:</para>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>-h, --help</term>
+  <listitem>
+<para>Displays the global help text and exits,
+identical to the
+<emphasis remap='B'>scons-time help</emphasis>
+subcommand.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-V, --version</term>
+  <listitem>
+<para>Displays the
+<command>scons-time</command>
+version and exits.</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>Most functionality is controlled by options
+to the individual subcommands.
+See the next section for information
+about individual subcommand options.</para>
+<!-- '\"========================================================================== -->
+</refsect1>
+
+<refsect1 id='subcommands'><title>SUBCOMMANDS</title>
+<para>The
+<command>scons-time</command>
+command supports the following
+individual subcommands.</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+
+<refsect2 id='the_func_subcommand'><title>The func Subcommand</title>
+<para><emphasis remap='B'>scons-time func</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis remap='I'>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>--func=</option><replaceable>NAME</replaceable>]
+[<option>-p </option><emphasis remap='I'>STRING</emphasis>]
+[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>]
+[<option>--title= TITLE</option>]
+[<emphasis remap='I'>ARGUMENTS</emphasis>]</para>
+
+<para>The
+<emphasis remap='B'>scons-time func</emphasis>
+subcommand displays timing information
+for a specific Python function within SCons.
+By default, it extracts information about the
+<emphasis remap='B'>_main</emphasis>()
+function,
+which includes the Python profiler timing
+for all of SCons.</para>
+
+<para>The
+<emphasis remap='B'>scons-time func</emphasis>
+subcommand extracts function timing information
+from all the specified file arguments,
+which should be Python profiler output files.
+(Normally, these would be
+<emphasis remap='B'>*.prof</emphasis>
+files generated by the
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand,
+but they can actually be generated
+by any Python profiler invocation.)
+All file name arguments will be
+globbed for on-disk files.</para>
+
+<para>If no arguments are specified,
+then function timing information
+will be extracted from all
+<emphasis remap='B'>*.prof</emphasis>
+files,
+or the subset of them
+with a prefix specified by the
+<option>-p</option>
+option.</para>
+
+<para>Options include:</para>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>-C DIRECTORY, --chdir=DIRECTORY</term>
+  <listitem>
+<para>Changes to the specified
+<emphasis remap='I'>DIRECTORY</emphasis>
+before looking for the specified files
+(or files that match the specified patterns).</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-f FILE, --file=FILE</term>
+  <listitem>
+<para>Reads configuration information from the specified
+<emphasis remap='I'>FILE</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-fmt=FORMAT, --format=FORMAT</term>
+  <listitem>
+<para>Reports the output in the specified
+<emphasis remap='I'>FORMAT</emphasis>.
+The formats currently supported are
+<emphasis remap='B'>ascii</emphasis>
+(the default)
+and
+<emphasis remap='B'>gnuplot</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--func=NAME</term>
+  <listitem>
+<para>Extracts timings for the specified function
+<emphasis remap='I'>NAME</emphasis>.
+The default is to report cumulative timings for the
+<emphasis remap='B'>_main</emphasis>()
+function,
+which contains the entire SCons run.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-h, --help</term>
+  <listitem>
+<para>Displays help text for the
+<emphasis remap='B'>scons-time func</emphasis>
+subcommand.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-p STRING, --prefix=STRING</term>
+  <listitem>
+<para>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.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-t NUMBER, --tail=NUMBER</term>
+  <listitem>
+<para>Only extracts function timings from the last
+<emphasis remap='I'>NUMBER</emphasis>
+files.</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect2>
+
+<refsect2 id='the_help_subcommand'><title>The help Subcommand</title>
+<para><emphasis remap='B'>scons-time help</emphasis>
+<emphasis remap='I'>SUBCOMMAND</emphasis>
+[...]
+The
+<emphasis remap='B'>help</emphasis>
+subcommand prints help text for any
+other subcommands listed as later arguments on the command line.</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+</refsect2>
+
+<refsect2 id='the_mem_subcommand'><title>The mem Subcommand</title>
+<para><emphasis remap='B'>scons-time mem</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis remap='I'>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>-p </option><emphasis remap='I'>STRING</emphasis>]
+[<option>--stage=</option><replaceable>STAGE</replaceable>]
+[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>]
+[<option>--title=</option><replaceable>TITLE</replaceable>]
+[<emphasis remap='I'>ARGUMENTS</emphasis>]</para>
+
+<para>The
+<emphasis remap='B'>scons-time mem</emphasis>
+subcommand displays how much memory SCons uses.</para>
+
+<para>The
+<emphasis remap='B'>scons-time mem</emphasis>
+subcommand extracts memory use information
+from all the specified file arguments,
+which should be files containing output from
+running SCons with the
+<option>--debug=memory</option>
+option.
+(Normally, these would be
+<emphasis remap='B'>*.log</emphasis>
+files generated by the
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand.)
+All file name arguments will be
+globbed for on-disk files.</para>
+
+<para>If no arguments are specified,
+then memory information
+will be extracted from all
+<emphasis remap='B'>*.log</emphasis>
+files,
+or the subset of them
+with a prefix specified by the
+<option>-p</option>
+option.</para>
+
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>-C DIR, --chdir=DIR</term>
+  <listitem>
+<para>Changes to the specified
+<emphasis remap='I'>DIRECTORY</emphasis>
+before looking for the specified files
+(or files that match the specified patterns).</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-f FILE, --file=FILE</term>
+  <listitem>
+<para>Reads configuration information from the specified
+<emphasis remap='I'>FILE</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-fmt=FORMAT, --format=FORMAT</term>
+  <listitem>
+<para>Reports the output in the specified
+<emphasis remap='I'>FORMAT</emphasis>.
+The formats currently supported are
+<emphasis remap='B'>ascii</emphasis>
+(the default)
+and
+<emphasis remap='B'>gnuplot</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-h, --help</term>
+  <listitem>
+<para>Displays help text for the
+<emphasis remap='B'>scons-time mem</emphasis>
+subcommand.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-p STRING, --prefix=STRING</term>
+  <listitem>
+<para>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.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--stage=STAGE</term>
+  <listitem>
+<para>Prints the memory used at the end of the specified
+<emphasis remap='I'>STAGE</emphasis>:
+<emphasis remap='B'>pre-read</emphasis>
+(before the SConscript files are read),
+<emphasis remap='B'>post-read ,</emphasis>
+(after the SConscript files are read),
+<emphasis remap='B'>pre-build</emphasis>
+(before any targets are built)
+or
+<emphasis remap='B'>post-build</emphasis>
+(after any targets are built).
+If no
+<option>--stage</option>
+option is specified,
+the default behavior is
+<emphasis remap='B'>post-build</emphasis>,
+which reports the final amount of memory
+used by SCons during each run.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-t NUMBER, --tail=NUMBER</term>
+  <listitem>
+<para>Only reports memory statistics from the last
+<emphasis remap='I'>NUMBER</emphasis>
+files.</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect2>
+
+<refsect2 id='the_obj_subcommand'><title>The obj Subcommand</title>
+<para><emphasis remap='B'>scons-time obj</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis remap='I'>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>-p </option><emphasis remap='I'>STRING</emphasis>]
+[<option>--stage=</option><replaceable>STAGE</replaceable>]
+[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>]
+[<option>--title=</option><replaceable>TITLE</replaceable>]
+[<emphasis remap='I'>ARGUMENTS</emphasis>]</para>
+
+<para>The
+<emphasis remap='B'>scons-time obj</emphasis>
+subcommand displays how many objects of a specific named type
+are created by SCons.</para>
+
+<para>The
+<emphasis remap='B'>scons-time obj</emphasis>
+subcommand extracts object counts
+from all the specified file arguments,
+which should be files containing output from
+running SCons with the
+<option>--debug=count</option>
+option.
+(Normally, these would be
+<emphasis remap='B'>*.log</emphasis>
+files generated by the
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand.)
+All file name arguments will be
+globbed for on-disk files.</para>
+
+<para>If no arguments are specified,
+then object counts
+will be extracted from all
+<emphasis remap='B'>*.log</emphasis>
+files,
+or the subset of them
+with a prefix specified by the
+<option>-p</option>
+option.</para>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>-C DIR, --chdir=DIR</term>
+  <listitem>
+<para>Changes to the specified
+<emphasis remap='I'>DIRECTORY</emphasis>
+before looking for the specified files
+(or files that match the specified patterns).</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-f FILE, --file=FILE</term>
+  <listitem>
+<para>Reads configuration information from the specified
+<emphasis remap='I'>FILE</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-fmt=FORMAT, --format=FORMAT</term>
+  <listitem>
+<para>Reports the output in the specified
+<emphasis remap='I'>FORMAT</emphasis>.
+The formats currently supported are
+<emphasis remap='B'>ascii</emphasis>
+(the default)
+and
+<emphasis remap='B'>gnuplot</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-h, --help</term>
+  <listitem>
+<para>Displays help text for the
+<emphasis remap='B'>scons-time obj</emphasis>
+subcommand.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-p STRING, --prefix=STRING</term>
+  <listitem>
+<para>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.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--stage=STAGE</term>
+  <listitem>
+<para>Prints the object count at the end of the specified
+<emphasis remap='I'>STAGE</emphasis>:
+<emphasis remap='B'>pre-read</emphasis>
+(before the SConscript files are read),
+<emphasis remap='B'>post-read ,</emphasis>
+(after the SConscript files are read),
+<emphasis remap='B'>pre-build</emphasis>
+(before any targets are built)
+or
+<emphasis remap='B'>post-build</emphasis>
+(after any targets are built).
+If no
+<option>--stage</option>
+option is specified,
+the default behavior is
+<emphasis remap='B'>post-build</emphasis>,
+which reports the final object count during each run.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-t NUMBER, --tail=NUMBER</term>
+  <listitem>
+<para>Only reports object counts from the last
+<emphasis remap='I'>NUMBER</emphasis>
+files.</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect2>
+
+<refsect2 id='the_run_subcommand'><title>The run Subcommand</title>
+<para><emphasis remap='B'>scons-time run</emphasis>
+[<option>-hnqv</option>]
+[<option>--aegis=</option><replaceable>PROJECT</replaceable>]
+[<option>-f </option><emphasis remap='I'>FILE</emphasis>]
+[<option>--number=</option><replaceable>NUMBER</replaceable>]
+[<option>--outdir=</option><replaceable>OUTDIR</replaceable>]
+[<option>-p </option><emphasis remap='I'>STRING</emphasis>]
+[<option>--python=</option><replaceable>PYTHON</replaceable>]
+[<option>-s </option><emphasis remap='I'>DIR</emphasis>]
+[<option>--scons=</option><replaceable>SCONS</replaceable>]
+[<option>--svn=</option><replaceable>URL</replaceable>]
+[<emphasis remap='I'>ARGUMENTS</emphasis>]
+The
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand is the basic subcommand
+for profiling a specific configuration
+against a version of SCons.</para>
+
+<para>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
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand understands file suffixes like
+<markup>.tar</markup>,
+<markup>.tar.gz</markup>,
+<markup>.tgz</markup>
+and
+<markup>.zip</markup>
+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.</para>
+
+<para>Once the file or directory arguments are unpacked or
+copied to the temporary directory,
+the
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand runs the
+requested version of SCons
+against the configuration
+three times:</para>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>Startup</term>
+  <listitem>
+<para>SCons is run with the
+<option>--help</option>
+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.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Full build</term>
+  <listitem>
+<para>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
+<emphasis remap='B'>targets</emphasis>
+keyword in a configuration file; see below for details.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>Rebuild</term>
+  <listitem>
+<para>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.</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>Each invocation captures the output log file and a profile.</para>
+
+<para>The
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand supports the following options:</para>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>--aegis=PROJECT</term>
+  <listitem>
+<para>Specifies the Aegis
+<emphasis remap='I'>PROJECT</emphasis>
+from which the
+version(s) of
+<emphasis remap='B'>scons</emphasis>
+being timed will be extracted.
+When
+<option>--aegis</option>
+is specified, the
+<option>--number=</option><replaceable>NUMBER</replaceable>
+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
+<option>--number=</option>
+option is not specified,
+then the default behavior is to time the
+tip of the specified
+<emphasis remap='I'>PROJECT</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-f FILE, --file=FILE</term>
+  <listitem>
+<para>Reads configuration information from the specified
+<emphasis remap='I'>FILE</emphasis>.
+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
+<link linkend="configuration_file">CONFIGURATION FILE</link>
+section below
+for information about the configuration file parameters.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-h, --help</term>
+  <listitem>
+<para>Displays help text for the
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-n, --no-exec</term>
+  <listitem>
+<para>Do not execute commands,
+just printing the command-line equivalents of what would be executed.
+Note that the
+<command>scons-time</command>
+script actually executes its actions in Python,
+where possible,
+for portability.
+The commands displayed are UNIX
+<emphasis remap='I'>equivalents</emphasis>
+of what it's doing.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--number=NUMBER</term>
+  <listitem>
+<para>Specifies the run number to be used in the names of
+the log files and profile outputs generated by this run.</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>When used in conjuction with the
+<option>--aegis=</option><replaceable>PROJECT</replaceable>
+option,
+<emphasis remap='I'>NUMBER</emphasis>
+specifies one or more comma-separated Aegis delta numbers
+that will be retrieved automatically from the specified Aegis
+<emphasis remap='I'>PROJECT</emphasis>.</para>
+
+<para>When used in conjuction with the
+<option>--svn=</option><replaceable>URL</replaceable>
+option,
+<emphasis remap='I'>NUMBER</emphasis>
+specifies one or more comma-separated Subversion revision numbers
+that will be retrieved automatically from the Subversion
+repository at the specified
+<emphasis remap='I'>URL</emphasis>.
+Ranges of delta or revision numbers
+may be specified be separating two numbers
+with a hyphen
+(<emphasis remap='B'>-</emphasis>).</para>
+
+<para>Example:</para>
+<literallayout remap='.nf'>
+% scons-time run --svn=<ulink url='http://scons.tigris.org/svn/trunk'>http://scons.tigris.org/svn/trunk</ulink> --num=1247,1249-1252 .
+</literallayout> <!-- .fi -->
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>-p STRING, --prefix=STRING</term>
+  <listitem>
+<para>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
+(<markup>.tgz</markup>, <markup>.tar.gz</markup> or <markup>.zip</markup>).</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--python=PYTHON</term>
+  <listitem>
+<para>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
+<command>scons-time</command>
+command itself.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-q, --quiet</term>
+  <listitem>
+<para>Suppresses display of the command lines being executed.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-s DIR, --subdir=DIR</term>
+  <listitem>
+<para>Specifies the name of directory or subdirectory
+from which the commands should be executed.
+The default is XXX</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--scons=SCONS</term>
+  <listitem>
+<para>Specifies a path to the SCons script to be used
+for the timing runs.
+The default is XXX</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--svn=URL, --subversion=URL</term>
+  <listitem>
+<para>Specifies the
+<emphasis remap='I'>URL</emphasis>
+of the Subversion repository from which the
+version(s) of
+<emphasis remap='B'>scons</emphasis>
+being timed will be extracted.
+When
+<option>--svn</option>
+is specified, the
+<option>--number=</option><replaceable>NUMBER</replaceable>
+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
+<option>--number=</option>
+option is not specified,
+then the default behavior is to time the
+<emphasis remap='B'>HEAD</emphasis>
+of the specified
+<emphasis remap='I'>URL</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-v, --verbose</term>
+  <listitem>
+<para>Displays the output from individual commands to the screen
+(in addition to capturing the output in log files).</para>
+<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect2>
+
+<refsect2 id='the_time_subcommand'><title>The time Subcommand</title>
+<para><emphasis remap='B'>scons-time time</emphasis>
+[<option>-h</option>]
+[<option>--chdir=</option><replaceable>DIR</replaceable>]
+[<option>-f </option><emphasis remap='I'>FILE</emphasis>]
+[<option>--fmt=</option><replaceable>FORMAT</replaceable>]
+[<option>-p </option><emphasis remap='I'>STRING</emphasis>]
+[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>]
+[<option>--title=</option><replaceable>TITLE</replaceable>]
+[<option>--which=</option><replaceable>WHICH</replaceable>]
+[<emphasis remap='I'>ARGUMENTS</emphasis>]</para>
+
+<para>The
+<emphasis remap='B'>scons-time time</emphasis>
+subcommand displays SCons execution times
+as reported by the
+<userinput>scons --debug=time</userinput>
+option.</para>
+
+<para>The
+<emphasis remap='B'>scons-time time</emphasis>
+subcommand extracts SCons timing
+from all the specified file arguments,
+which should be files containing output from
+running SCons with the
+<option>--debug=time</option>
+option.
+(Normally, these would be
+<emphasis remap='B'>*.log</emphasis>
+files generated by the
+<emphasis remap='B'>scons-time run</emphasis>
+subcommand.)
+All file name arguments will be
+globbed for on-disk files.</para>
+
+<para>If no arguments are specified,
+then execution timings
+will be extracted from all
+<emphasis remap='B'>*.log</emphasis>
+files,
+or the subset of them
+with a prefix specified by the
+<option>-p</option>
+option.</para>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term>-C DIR, --chdir=DIR</term>
+  <listitem>
+<para>Changes to the specified
+<emphasis remap='I'>DIRECTORY</emphasis>
+before looking for the specified files
+(or files that match the specified patterns).</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-f FILE, --file=FILE</term>
+  <listitem>
+<para>Reads configuration information from the specified
+<emphasis remap='I'>FILE</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-fmt=FORMAT, --format=FORMAT</term>
+  <listitem>
+<para>Reports the output in the specified
+<emphasis remap='I'>FORMAT</emphasis>.
+The formats currently supported are
+<emphasis remap='B'>ascii</emphasis>
+(the default)
+and
+<emphasis remap='B'>gnuplot</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-h, --help</term>
+  <listitem>
+<para>Displays help text for the
+<emphasis remap='B'>scons-time time</emphasis>
+subcommand.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-p STRING, --prefix=STRING</term>
+  <listitem>
+<para>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.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>-t NUMBER, --tail=NUMBER</term>
+  <listitem>
+<para>Only reports object counts from the last
+<emphasis remap='I'>NUMBER</emphasis>
+files.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term>--which=WHICH</term>
+  <listitem>
+<para>Prints the execution time for the specified
+<emphasis remap='I'>WHICH</emphasis>
+value:
+<emphasis remap='B'>total</emphasis>
+(the total execution time),
+<emphasis remap='B'>SConscripts</emphasis>
+(total execution time for the SConscript files themselves),
+<emphasis remap='B'>SCons</emphasis>
+(exectuion time in SCons code itself)
+or
+<emphasis remap='B'>commands</emphasis>
+(execution time of the commands and other actions
+used to build targets).
+If no
+<option>--which</option>
+option is specified,
+the default behavior is
+<emphasis remap='B'>total</emphasis>,
+which reports the total execution time for each run.</para>
+<!-- '\"========================================================================== -->
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect2>
+</refsect1>
+
+<refsect1 id='configuration_file'><title>CONFIGURATION FILE</title>
+<para>Various
+<command>scons-time</command>
+subcommands can read information from a specified
+configuration file when passed the
+<option>-f</option>
+or
+<option>--file</option>
+options.
+The configuration file is actually executed as a Python script.
+Setting Python variables in the configuration file
+controls the behavior of the
+<command>scons-time</command>
+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.</para>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term><emphasis remap='B'>aegis</emphasis></term>
+  <listitem>
+<para>The Aegis executable for extracting deltas.
+The default is simply
+<emphasis remap='B'>aegis</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='B'>aegis_project</emphasis></term>
+  <listitem>
+<para>The Aegis project from which deltas should be extracted.
+The default is whatever is specified
+with the
+<option>--aegis=</option>
+command-line option.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='B'>archive_list</emphasis></term>
+  <listitem>
+<para>A list of archives (files or directories)
+that will be copied to the temporary directory
+in which SCons will be invoked.
+<markup>.tar</markup>,
+<markup>.tar.gz</markup>,
+<markup>.tgz</markup>
+and
+<markup>.zip</markup>
+files will have their contents unpacked in
+the temporary directory.
+Directory trees and files will be copied as-is.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='B'>initial_commands</emphasis></term>
+  <listitem>
+<para>A list of commands that will be executed
+before the actual timed
+<emphasis remap='B'>scons</emphasis>
+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.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='B'>key_location</emphasis></term>
+  <listitem>
+<para>The location of the key on Gnuplot graphing information
+generated with the
+<option>--format=gnuplot</option>
+option.
+The default is
+<emphasis remap='B'>bottom left</emphasis>.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><emphasis remap='B'>prefix</emphasis></term>
+  <listitem>
+<para>The file name prefix to be used when
+running or extracting timing for this configuration.</para>