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