1SCONS-TIME(1) General Commands Manual SCONS-TIME(1)
2
6 scons-time - generate and display SCons timing information
7
9 scons-time subcommand [ options... ] [ arguments... ]
10 Generating Timing Information
12 scons-time run [-hnqv] [--aegis=PROJECT] [-f FILE] [--number=NUMBER]
13 [--outdir=OUTDIR] [-p STRING] [--python=PYTHON] [-s DIR]
14 [--scons=SCONS] [--svn=URL] [ARGUMENTS]
15 Extracting Function Timings
17 scons-time func [-h] [--chdir=DIR] [-f FILE] [--fmt=FORMAT]
18 [--func=NAME] [-p STRING] [-t NUMBER] [--title= TITLE] [ARGUMENTS]
19 Extracting Memory Statistics
21 Extracting Object Counts
24 scons-time obj [-h] [--chdir=DIR] [-f FILE] [--fmt=FORMAT] [-p STRING]
25 [--stage=STAGE] [-t NUMBER] [--title=TITLE] [ARGUMENTS]
26 Extracting Execution Times
28 scons-time time [-h] [--chdir=DIR] [-f FILE] [--fmt=FORMAT] [-p STRING]
29 [-t NUMBER] [--title=TITLE] [--which=WHICH] [ARGUMENTS]
30 Help Text
32 scons-time help SUBCOMMAND [...]
33
35 The scons-time command runs an SCons configuration through a standard
36 set of profiled timings and can extract and graph information from the
37 resulting profiles and log files of those timings. The action to be
38 performed by the scons-time script is specified by a subcommand, the
39 first argument on the command line. See the SUBCOMMANDS section below
40 for information about the operation of specific subcommands.
41 The basic way to use scons-time is to run the scons-time run subcommand
43 (possibly multiple times) to generate profile and log file output, and
44 then use one of the other subcommands to display the results captured
45 in the profiles and log files for a particular kind of information:
46 function timings (the scons-time func subcommand), total memory used
47 (the scons-time mem subcommand), object counts (the scons-time obj
48 subcommand) and overall execution time (the scons-time time
49 subcommand). Options exist to place and find the profiles and log
50 files in separate directories, to generate the output in a format
51 suitable for graphing with the gnuplot(1) program, and so on.
52 There are two basic ways the scons-time run subcommand is intended to
54 be used to gather timing statistics for a configuration. One is to use
55 the --svn= option to test a configuration against a list of revisions
56 from the SCons Subversion repository. This will generate a profile and
57 timing log file for every revision listed with the --number= option,
58 and can be used to look at the impact of commited changes to the SCons
59 code base on a particular configuration over time.
60 The other way is to profile incremental changes to a local SCons code
62 base during a development cycle--that is, to look at the performance
63 impact of changes you're making in the local tree. In this mode, you
64 run the scons-time run subcommand without the --svn= option, in which
65 case it simply looks in the profile/log file output directory (the
66 current directory by default) and automatically figures out the next
67 run number for the output profile and log file. Used in this way, the
68 development cycle goes something like: make a change to SCons; run
69 scons-time run to profile it against a specific configuration; make
70 another change to SCons; run scons-time run again to profile it; etc.
71
73 The scons-time command only supports a few global options:
74 -h, --help
76 Displays the global help text and exits, identical to the scons-
77 time help subcommand.
78 -V, --version
80 Displays the scons-time version and exits.
81 Most functionality is controlled by options to the individual
83 subcommands. See the next section for information about individual
84 subcommand options.
85
87 The scons-time command supports the following individual subcommands.
88 The func Subcommand
90 scons-time func [-h] [--chdir=DIR] [-f FILE] [--fmt=FORMAT]
91 [--func=NAME] [-p STRING] [-t NUMBER] [--title= TITLE] [ARGUMENTS]
92 The scons-time func subcommand displays timing information for a
94 specific Python function within SCons. By default, it extracts
95 information about the _main() function, which includes the Python
96 profiler timing for all of SCons.
97 The scons-time func subcommand extracts function timing information
99 from all the specified file arguments, which should be Python profiler
100 output files. (Normally, these would be *.prof files generated by the
101 scons-time run subcommand, but they can actually be generated by any
102 Python profiler invocation.) All file name arguments will be globbed
103 for on-disk files.
104 If no arguments are specified, then function timing information will be
106 extracted from all *.prof files, or the subset of them with a prefix
107 specified by the -p option.
108 Options include:
110 -C DIRECTORY, --chdir=DIRECTORY
112 Changes to the specified DIRECTORY before looking for the
113 specified files (or files that match the specified patterns).
114 -f FILE, --file=FILE
116 Reads configuration information from the specified FILE.
117 -fmt=FORMAT, --format=FORMAT
119 Reports the output in the specified FORMAT. The formats
120 currently supported are ascii (the default) and gnuplot.
121 --func=NAME
123 Extracts timings for the specified function NAME. The default
124 is to report cumulative timings for the _main() function, which
125 contains the entire SCons run.
126 -h, --help
128 Displays help text for the scons-time func subcommand.
129 -p STRING, --prefix=STRING
131 Specifies the prefix string for profiles from which to extract
132 function timing information. This will be used to search for
133 profiles if no arguments are specified on the command line.
134 -t NUMBER, --tail=NUMBER
136 Only extracts function timings from the last NUMBER files.
137 The help Subcommand
139 scons-time help SUBCOMMAND [...] The help subcommand prints help text
140 for any other subcommands listed as later arguments on the command
141 line.
142 The mem Subcommand
144 The scons-time mem subcommand displays how much memory SCons uses.
147 The scons-time mem subcommand extracts memory use information from all
149 the specified file arguments, which should be files containing output
150 from running SCons with the --debug=memory option. (Normally, these
151 would be *.log files generated by the scons-time run subcommand.) All
152 file name arguments will be globbed for on-disk files.
153 If no arguments are specified, then memory information will be
155 extracted from all *.log files, or the subset of them with a prefix
156 specified by the -p option.
157 -C DIR, --chdir=DIR
159 Changes to the specified DIRECTORY before looking for the
160 specified files (or files that match the specified patterns).
161 -f FILE, --file=FILE
163 Reads configuration information from the specified FILE.
164 -fmt=FORMAT, --format=FORMAT
166 Reports the output in the specified FORMAT. The formats
167 currently supported are ascii (the default) and gnuplot.
168 -h, --help
170 Displays help text for the scons-time mem subcommand.
171 -p STRING, --prefix=STRING
173 Specifies the prefix string for log files from which to extract
174 memory usage information. This will be used to search for log
175 files if no arguments are specified on the command line.
176 --stage=STAGE
178 Prints the memory used at the end of the specified STAGE: pre-
179 read (before the SConscript files are read), post-read , (after
180 the SConscript files are read), pre-build (before any targets
181 are built) or post-build (after any targets are built). If no
182 --stage option is specified, the default behavior is post-build,
183 which reports the final amount of memory used by SCons during
184 each run.
185 -t NUMBER, --tail=NUMBER
187 Only reports memory statistics from the last NUMBER files.
188 The obj Subcommand
190 scons-time obj [-h] [--chdir=DIR] [-f FILE] [--fmt=FORMAT] [-p STRING]
191 [--stage=STAGE] [-t NUMBER] [--title=TITLE] [ARGUMENTS]
192 The scons-time obj subcommand displays how many objects of a specific
194 named type are created by SCons.
195 The scons-time obj subcommand extracts object counts from all the
197 specified file arguments, which should be files containing output from
198 running SCons with the --debug=count option. (Normally, these would be
199 *.log files generated by the scons-time run subcommand.) All file name
200 arguments will be globbed for on-disk files.
201 If no arguments are specified, then object counts will be extracted
203 from all *.log files, or the subset of them with a prefix specified by
204 the -p option.
205 -C DIR, --chdir=DIR
207 Changes to the specified DIRECTORY before looking for the
208 specified files (or files that match the specified patterns).
209 -f FILE, --file=FILE
211 Reads configuration information from the specified FILE.
212 -fmt=FORMAT, --format=FORMAT
214 Reports the output in the specified FORMAT. The formats
215 currently supported are ascii (the default) and gnuplot.
216 -h, --help
218 Displays help text for the scons-time obj subcommand.
219 -p STRING, --prefix=STRING
221 Specifies the prefix string for log files from which to extract
222 object counts. This will be used to search for log files if no
223 arguments are specified on the command line.
224 --stage=STAGE
226 Prints the object count at the end of the specified STAGE: pre-
227 read (before the SConscript files are read), post-read , (after
228 the SConscript files are read), pre-build (before any targets
229 are built) or post-build (after any targets are built). If no
230 --stage option is specified, the default behavior is post-build,
231 which reports the final object count during each run.
232 -t NUMBER, --tail=NUMBER
234 Only reports object counts from the last NUMBER files.
235 The run Subcommand
237 scons-time run [-hnqv] [--aegis=PROJECT] [-f FILE] [--number=NUMBER]
238 [--outdir=OUTDIR] [-p STRING] [--python=PYTHON] [-s DIR]
239 [--scons=SCONS] [--svn=URL] [ARGUMENTS] The scons-time run subcommand
240 is the basic subcommand for profiling a specific configuration against
241 a version of SCons.
242 The configuration to be tested is specified as a list of files or
244 directories that will be unpacked or copied into a temporary directory
245 in which SCons will be invoked. The scons-time run subcommand
246 understands file suffixes like .tar, .tar.gz, .tgz and .zip and will
247 unpack their contents into a temporary directory. If more than one
248 argument is specified, each one will be unpacked or copied into the
249 temporary directory "on top of" the previous archives or directories,
250 so the expectation is that multiple specified archives share the same
251 directory layout.
252 Once the file or directory arguments are unpacked or copied to the
254 temporary directory, the scons-time run subcommand runs the requested
255 version of SCons against the configuration three times:
256 Startup
258 SCons is run with the --help option so that just the SConscript
259 files are read, and then the default help text is printed. This
260 profiles just the perceived "overhead" of starting up SCons and
261 processing the SConscript files.
262 Full build
264 SCons is run to build everything specified in the configuration.
265 Specific targets to be passed in on the command l ine may be
266 specified by the targets keyword in a configuration file; see
267 below for details.
268 Rebuild
270 SCons is run again on the same just-built directory. If the
271 dependencies in the SCons configuration are correct, this should
272 be an up-to-date, "do nothing" rebuild.
273 Each invocation captures the output log file and a profile.
275 The scons-time run subcommand supports the following options:
277 --aegis=PROJECT
279 Specifies the Aegis PROJECT from which the version(s) of scons
280 being timed will be extracted. When --aegis is specified, the
281 --number=NUMBER option specifies delta numbers that will be
282 tested. Output from each invocation run will be placed in file
283 names that match the Aegis delta numbers. If the --number=
284 option is not specified, then the default behavior is to time
285 the tip of the specified PROJECT.
286 -f FILE, --file=FILE
288 Reads configuration information from the specified FILE. This
289 often provides a more convenient way to specify and collect
290 parameters associated with a specific timing configuration than
291 specifying them on the command line. See the CONFIGURATION FILE
292 section below for information about the configuration file
293 parameters.
294 -h, --help
296 Displays help text for the scons-time run subcommand.
297 -n, --no-exec
299 Do not execute commands, just printing the command-line
300 equivalents of what would be executed. Note that the scons-time
301 script actually executes its actions in Python, where possible,
302 for portability. The commands displayed are UNIX equivalents of
303 what it's doing.
304 --number=NUMBER
306 Specifies the run number to be used in the names of the log
307 files and profile outputs generated by this run.
308 When used in conjuction with the --aegis=PROJECT option, NUMBER
310 specifies one or more comma-separated Aegis delta numbers that
311 will be retrieved automatically from the specified Aegis
312 PROJECT.
313 When used in conjuction with the --svn=URL option, NUMBER
315 specifies one or more comma-separated Subversion revision
316 numbers that will be retrieved automatically from the Subversion
317 repository at the specified URL. Ranges of delta or revision
318 numbers may be specified be separating two numbers with a hyphen
319 (-).
320 Example:
322 % scons-time run --svn=http://scons.tigris.org/svn/trunk --num=1247,1249-1252 .
323 -p STRING, --prefix=STRING
325 Specifies the prefix string to be used for all of the log
326 files and profiles generated by this run. The default is
327 derived from the first specified argument: if the first
328 argument is a directory, the default prefix is the name
329 of the directory; if the first argument is an archive
330 (tar or zip file), the default prefix is the the base
331 name of the archive, that is, what remains after strip‐
332 ping the archive suffix (.tgz, .tar.gz or .zip).
333 --python=PYTHON
335 Specifies a path to the Python executable to be used for
336 the timing runs. The default is to use the same Python
337 executable that is running the scons-time command itself.
338 -q, --quiet
340 Suppresses display of the command lines being executed.
341 -s DIR, --subdir=DIR
343 Specifies the name of directory or subdirectory from
344 which the commands should be executed. The default is
345 XXX
346 --scons=SCONS
348 Specifies a path to the SCons script to be used for the
349 timing runs. The default is XXX
350 --svn=URL, --subversion=URL
352 Specifies the URL of the Subversion repository from which
353 the version(s) of scons being timed will be extracted.
354 When --svn is specified, the --number=NUMBER option spec‐
355 ifies revision numbers that will be tested. Output from
356 each invocation run will be placed in file names that
357 match the Subversion revision numbers. If the --number=
358 option is not specified, then the default behavior is to
359 time the HEAD of the specified URL.
360 -v, --verbose
362 Displays the output from individual commands to the
363 screen (in addition to capturing the output in log
364 files).
365 The time Subcommand
367 scons-time time [-h] [--chdir=DIR] [-f FILE] [--fmt=FORMAT] [-p STRING]
368 [-t NUMBER] [--title=TITLE] [--which=WHICH] [ARGUMENTS]
369 The scons-time time subcommand displays SCons execution times as
371 reported by the scons --debug=time option.
372 The scons-time time subcommand extracts SCons timing from all the spec‐
374 ified file arguments, which should be files containing output from run‐
375 ning SCons with the --debug=time option. (Normally, these would be
376 *.log files generated by the scons-time run subcommand.) All file name
377 arguments will be globbed for on-disk files.
378 If no arguments are specified, then execution timings will be extracted
380 from all *.log files, or the subset of them with a prefix specified by
381 the -p option.
382 -C DIR, --chdir=DIR
384 Changes to the specified DIRECTORY before looking for the speci‐
385 fied files (or files that match the specified patterns).
386 -f FILE, --file=FILE
388 Reads configuration information from the specified FILE.
389 -fmt=FORMAT, --format=FORMAT
391 Reports the output in the specified FORMAT. The formats cur‐
392 rently supported are ascii (the default) and gnuplot.
393 -h, --help
395 Displays help text for the scons-time time subcommand.
396 -p STRING, --prefix=STRING
398 Specifies the prefix string for log files from which to extract
399 execution timings. This will be used to search for log files if
400 no arguments are specified on the command line.
401 -t NUMBER, --tail=NUMBER
403 Only reports object counts from the last NUMBER files.
404 --which=WHICH
406 Prints the execution time for the specified WHICH value: total
407 (the total execution time), SConscripts (total execution time
408 for the SConscript files themselves), SCons (exectuion time in
409 SCons code itself) or commands (execution time of the commands
410 and other actions used to build targets). If no --which option
411 is specified, the default behavior is total, which reports the
412 total execution time for each run.
413
415 Various scons-time subcommands can read information from a specified
416 configuration file when passed the -f or --file options. The configu‐
417 ration file is actually executed as a Python script. Setting Python
418 variables in the configuration file controls the behavior of the scons-
419 time script more conveniently than having to specify command-line
420 options or arguments for every run, and provides a handy way to
421 "shrink-wrap" the necessary information for producing (and reporting)
422 consistent timing runs for a given configuration.
423 aegis The Aegis executable for extracting deltas. The default is sim‐
425 ply aegis.
426 aegis_project
428 The Aegis project from which deltas should be extracted. The
429 default is whatever is specified with the --aegis= command-line
430 option.
431 archive_list
433 A list of archives (files or directories) that will be copied to
434 the temporary directory in which SCons will be invoked. .tar,
435 .tar.gz, .tgz and .zip files will have their contents unpacked
436 in the temporary directory. Directory trees and files will be
437 copied as-is.
438 initial_commands
440 A list of commands that will be executed before the actual timed
441 scons runs. This can be used for commands that are necessary to
442 prepare the source tree-for example, creating a configuration
443 file that should not be part of the timed run.
444 key_location
446 The location of the key on Gnuplot graphing information gener‐
447 ated with the --format=gnuplot option. The default is bottom
448 left.
449 prefix The file name prefix to be used when running or extracting tim‐
451 ing for this configuration.
452 python The path name of the Python executable to be used when running
454 or extracting information for this configuration. The default
455 is the same version of Python used to run the SCons
456 scons The path name of the SCons script to be used when running or
458 extracting information for this configuration. The default is
459 simply scons.
460 scons_flags
462 The scons flags used when running SCons to collect timing infor‐
463 mation. The default value is --debug=count --debug=memory
464 --debug=time --debug=memoizer.
465 scons_lib_dir
467 scons_wrapper
469 startup_targets
471 subdir The subdirectory of the project into which the scons-time script
473 should change before executing the SCons commands to time.
474 subversion_url
476 The Subversion URL from
477 svn The subversion executable used to check out revisions of SCons
479 to be timed. The default is simple svn.
480 svn_co_flag
482 tar
484 targets
486 A string containing the targets that should be added to the com‐
487 mand line of every timed scons run. This can be used to
488 restrict what's being timed to a subset of the full build for
489 the configuration.
490 targets0
492 targets1
494 targets2
496 title
498 unzip
500 verbose
502 vertical_bars
504 Example
506 Here is an example scons-time configuration file for a hypothetical
507 sample project:
508 # The project doesn't use SCons natively (yet), so we're
510 # timing a separate set of SConscript files that we lay
511 # on top of the vanilla unpacked project tarball.
512 arguments = ['project-1.2.tgz', 'project-SConscripts.tar']
513 # The subdirectory name contains the project version number,
515 # so tell scons-time to chdir there before building.
516 subdir = 'project-1.2'
517 # Set the prefix so output log files and profiles are named:
519 # project-000-[012].{log,prof}
520 # project-001-[012].{log,prof}
521 # etc.
522 prefix = 'project'
523 # The SConscript files being tested don't do any SConf
525 # configuration, so run their normal ./configure script
526 # before we invoke SCons.
527 initial_commands = [
528 './configure',
529 ]
530 # Only time building the bin/project executable.
532 targets = 'bin/project'
533 # Time against SCons revisions of the branches/core branch
535 subversion_url = 'http://scons.tigris.org/svn/scons/branches/core'
536
538 The scons-time script uses the following environment variables:
539 PRESERVE
541 If this value is set, the scons-time script will not remove the
542 temporary directory or directories in which it builds the speci‐
543 fied configuration or downloads a specific version of SCons.
544
546 gnuplot(1), scons(1)
547
550 Steven Knight <knight at baldmt dot com>
551 May 2008 SCONS-TIME(1)