1018 lines
24 KiB
Groff
1018 lines
24 KiB
Groff
.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 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 3842 2008/12/20 22:59:52 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 "December 2008"
|
|
.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>
|