diff options
Diffstat (limited to 'doc/man/scons-time.1')
| -rw-r--r-- | doc/man/scons-time.1 | 1017 |
1 files changed, 1017 insertions, 0 deletions
diff --git a/doc/man/scons-time.1 b/doc/man/scons-time.1 new file mode 100644 index 0000000..8231c9d --- /dev/null +++ b/doc/man/scons-time.1 @@ -0,0 +1,1017 @@ +.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 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 4577 2009/12/27 19:44:43 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 2009" +.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> |