1SCONS-TIME(1)               General Commands Manual              SCONS-TIME(1)
2
3
4

NAME

6       scons-time - generate and display SCons timing information
7

SYNOPSIS

9       scons-time subcommand [ options...  ] [ arguments...  ]
10
11   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
16   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
20   Extracting Memory Statistics
21
22
23   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
27   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
31   Help Text
32       scons-time help SUBCOMMAND [...]
33

DESCRIPTION

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
42       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
53       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
61       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

OPTIONS

73       The scons-time command only supports a few global options:
74
75       -h, --help
76              Displays the global help text and exits, identical to the scons-
77              time help subcommand.
78
79       -V, --version
80              Displays the scons-time version and exits.
81
82       Most functionality is controlled by options to the individual
83       subcommands.  See the next section for information about individual
84       subcommand options.
85

SUBCOMMANDS

87       The scons-time command supports the following individual subcommands.
88
89   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
93       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
98       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
105       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
109       Options include:
110
111       -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
115       -f FILE, --file=FILE
116              Reads configuration information from the specified FILE.
117
118       -fmt=FORMAT, --format=FORMAT
119              Reports the output in the specified FORMAT.  The formats
120              currently supported are ascii (the default) and gnuplot.
121
122       --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
127       -h, --help
128              Displays help text for the scons-time func subcommand.
129
130       -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
135       -t NUMBER, --tail=NUMBER
136              Only extracts function timings from the last NUMBER files.
137
138   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
143   The mem Subcommand
144
145
146       The scons-time mem subcommand displays how much memory SCons uses.
147
148       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
154       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
158       -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
162       -f FILE, --file=FILE
163              Reads configuration information from the specified FILE.
164
165       -fmt=FORMAT, --format=FORMAT
166              Reports the output in the specified FORMAT.  The formats
167              currently supported are ascii (the default) and gnuplot.
168
169       -h, --help
170              Displays help text for the scons-time mem subcommand.
171
172       -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
177       --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
186       -t NUMBER, --tail=NUMBER
187              Only reports memory statistics from the last NUMBER files.
188
189   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
193       The scons-time obj subcommand displays how many objects of a specific
194       named type are created by SCons.
195
196       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
202       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
206       -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
210       -f FILE, --file=FILE
211              Reads configuration information from the specified FILE.
212
213       -fmt=FORMAT, --format=FORMAT
214              Reports the output in the specified FORMAT.  The formats
215              currently supported are ascii (the default) and gnuplot.
216
217       -h, --help
218              Displays help text for the scons-time obj subcommand.
219
220       -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
225       --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
233       -t NUMBER, --tail=NUMBER
234              Only reports object counts from the last NUMBER files.
235
236   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
243       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
253       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
257       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
263       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
269       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
274       Each invocation captures the output log file and a profile.
275
276       The scons-time run subcommand supports the following options:
277
278       --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
287       -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
295       -h, --help
296              Displays help text for the scons-time run subcommand.
297
298       -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
305       --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
309              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
314              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
321       Example:
322              % scons-time run --svn=http://scons.tigris.org/svn/trunk --num=1247,1249-1252 .
323
324              -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
334              --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
339              -q, --quiet
340                     Suppresses display of the command lines being executed.
341
342              -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
347              --scons=SCONS
348                     Specifies a path to the SCons script to be used for the
349                     timing runs.  The default is XXX
350
351              --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
361              -v, --verbose
362                     Displays the output from individual commands to the
363                     screen (in addition to capturing the output in log
364                     files).
365
366   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
370       The scons-time time subcommand displays SCons execution times as
371       reported by the scons --debug=time option.
372
373       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
379       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
383       -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
387       -f FILE, --file=FILE
388              Reads configuration information from the specified FILE.
389
390       -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
394       -h, --help
395              Displays help text for the scons-time time subcommand.
396
397       -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
402       -t NUMBER, --tail=NUMBER
403              Only reports object counts from the last NUMBER files.
404
405       --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

CONFIGURATION FILE

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
424       aegis  The Aegis executable for extracting deltas.  The default is sim‐
425              ply aegis.
426
427       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
432       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
439       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
445       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
450       prefix The file name prefix to be used when running or extracting tim‐
451              ing for this configuration.
452
453       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
457       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
461       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
466       scons_lib_dir
467
468       scons_wrapper
469
470       startup_targets
471
472       subdir The subdirectory of the project into which the scons-time script
473              should change before executing the SCons commands to time.
474
475       subversion_url
476              The Subversion URL from
477
478       svn    The subversion executable used to check out revisions of SCons
479              to be timed.  The default is simple svn.
480
481       svn_co_flag
482
483       tar
484
485       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
491       targets0
492
493       targets1
494
495       targets2
496
497       title
498
499       unzip
500
501       verbose
502
503       vertical_bars
504
505   Example
506       Here is an example scons-time configuration file for a hypothetical
507       sample project:
508
509              # 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
514              # The subdirectory name contains the project version number,
515              # so tell scons-time to chdir there before building.
516              subdir = 'project-1.2'
517
518              # 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
524              # 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
531              # Only time building the bin/project executable.
532              targets = 'bin/project'
533
534              # Time against SCons revisions of the branches/core branch
535              subversion_url = 'http://scons.tigris.org/svn/scons/branches/core'
536

ENVIRONMENT

538       The scons-time script uses the following environment variables:
539
540       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

SEE ALSO

546       gnuplot(1), scons(1)
547
548

AUTHORS

550       Steven Knight <knight at baldmt dot com>
551
552
553
554                                September 2011                   SCONS-TIME(1)
Impressum