diff options
Diffstat (limited to 'doc/man/scons-time.1')
| -rw-r--r-- | doc/man/scons-time.1 | 1017 |
1 files changed, 0 insertions, 1017 deletions
diff --git a/doc/man/scons-time.1 b/doc/man/scons-time.1 deleted file mode 100644 index f29ed54..0000000 --- a/doc/man/scons-time.1 +++ /dev/null @@ -1,1017 +0,0 @@ -.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 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 2013/03/03 09:48:35 garyo -.\" -.\" 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 "March 2013" -.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> |