1SCONS-TIME(1)                     SCons 4.3.0                    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

GENERATING TIMING INFORMATION

12       scons-time run [-hnqv] [-f FILE] [--number=NUMBER] [--outdir=OUTDIR]
13       [-p STRING] [--python=PYTHON] [-s DIR] [--scons=SCONS] [--svn=URL]
14       [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       scons-time mem [-h] [--chdir=DIR] [-f FILE] [--fmt=FORMAT] [-p STRING]
22       [--stage=STAGE] [-t NUMBER] [--title=TITLE] [ARGUMENTS]
23
24   Extracting Object Counts
25       scons-time obj [-h] [--chdir=DIR] [-f FILE] [--fmt=FORMAT] [-p STRING]
26       [--stage=STAGE] [-t NUMBER] [--title=TITLE] [ARGUMENTS]
27
28   Extracting Execution Times
29       scons-time time [-h] [--chdir=DIR] [-f FILE] [--fmt=FORMAT] [-p STRING]
30       [-t NUMBER] [--title=TITLE] [--which=WHICH] [ARGUMENTS]
31
32   Help Text
33       scons-time help SUBCOMMAND [...]
34

DESCRIPTION

36       The scons-time command runs an SCons configuration through a standard
37       set of profiled timings and can extract and graph information from the
38       resulting profiles and log files of those timings. The action to be
39       performed by the scons-time script is specified by a subcommand, the
40       first argument on the command line. See the SUBCOMMANDS section below
41       for information about the operation of specific subcommands.
42
43       The basic way to use scons-time is to run the scons-time run subcommand
44       (possibly multiple times) to generate profile and log file output, and
45       then use one of the other subcommands to display the results captured
46       in the profiles and log files for a particular kind of information:
47       function timings (the scons-time func subcommand), total memory used
48       (the scons-time mem subcommand), object counts (the scons-time obj
49       subcommand) and overall execution time (the scons-time time
50       subcommand). Options exist to place and find the profiles and log files
51       in separate directories, to generate the output in a format suitable
52       for graphing with the gnuplot(1) program, and so on.
53
54       There are two basic ways the scons-time run subcommand is intended to
55       be used to gather timing statistics for a configuration. One is to use
56       the --svn= option to test a configuration against a list of revisions
57       from the SCons Subversion repository. This will generate a profile and
58       timing log file for every revision listed with the --number= option,
59       and can be used to look at the impact of committed changes to the SCons
60       code base on a particular configuration over time.
61
62       The other way is to profile incremental changes to a local SCons code
63       base during a development cycle--that is, to look at the performance
64       impact of changes you're making in the local tree. In this mode, you
65       run the scons-time run subcommand without the --svn= option, in which
66       case it simply looks in the profile/log file output directory (the
67       current directory by default) and automatically figures out the next
68       run number for the output profile and log file. Used in this way, the
69       development cycle goes something like: make a change to SCons; run
70       scons-time run to profile it against a specific configuration; make
71       another change to SCons; run scons-time run again to profile it; etc.
72

OPTIONS

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

SUBCOMMANDS

88       The scons-time command supports the following individual subcommands.
89
90   The func Subcommand
91       scons-time func [-h] [--chdir=DIR] [-f FILE] [--fmt=FORMAT]
92       [--func=NAME] [-p STRING] [-t NUMBER] [--title= TITLE] [ARGUMENTS]
93
94       The scons-time func subcommand displays timing information for a
95       specific Python function within SCons. By default, it extracts
96       information about the _main() function, which includes the Python
97       profiler timing for all of SCons.
98
99       The scons-time func subcommand extracts function timing information
100       from all the specified file arguments, which should be Python profiler
101       output files. (Normally, these would be *.prof files generated by the
102       scons-time run subcommand, but they can actually be generated by any
103       Python profiler invocation.) All file name arguments will be globbed
104       for on-disk files.
105
106       If no arguments are specified, then function timing information will be
107       extracted from all *.prof files, or the subset of them with a prefix
108       specified by the -p option.
109
110       Options include:
111
112       -C DIRECTORY, --chdir=DIRECTORY
113           Changes to the specified DIRECTORY before looking for the specified
114           files (or files that match the specified patterns).
115
116       -f FILE, --file=FILE
117           Reads configuration information from the specified FILE.
118
119       -fmt=FORMAT, --format=FORMAT
120           Reports the output in the specified FORMAT. The formats currently
121           supported are ascii (the default) and gnuplot.
122
123       --func=NAME
124           Extracts timings for the specified function NAME. The default is to
125           report cumulative timings for the _main() function, which contains
126           the entire SCons run.
127
128       -h, --help
129           Displays help text for the scons-time func subcommand.
130
131       -p STRING, --prefix=STRING
132           Specifies the prefix string for profiles from which to extract
133           function timing information. This will be used to search for
134           profiles if no arguments are specified on the command line.
135
136       -t NUMBER, --tail=NUMBER
137           Only extracts function timings from the last NUMBER files.
138
139   The help Subcommand
140       scons-time help SUBCOMMAND [...] The help subcommand prints help text
141       for any other subcommands listed as later arguments on the command
142       line.
143
144   The mem Subcommand
145       scons-time mem [-h] [--chdir=DIR] [-f FILE] [--fmt=FORMAT] [-p STRING]
146       [--stage=STAGE] [-t NUMBER] [--title=TITLE] [ARGUMENTS]
147
148       The scons-time mem subcommand displays how much memory SCons uses.
149
150       The scons-time mem subcommand extracts memory use information from all
151       the specified file arguments, which should be files containing output
152       from running SCons with the --debug=memory option. (Normally, these
153       would be *.log files generated by the scons-time run subcommand.) All
154       file name arguments will be globbed for on-disk files.
155
156       If no arguments are specified, then memory information will be
157       extracted from all *.log files, or the subset of them with a prefix
158       specified by the -p option.
159
160       -C DIR, --chdir=DIR
161           Changes to the specified DIRECTORY before looking for the specified
162           files (or files that match the specified patterns).
163
164       -f FILE, --file=FILE
165           Reads configuration information from the specified FILE.
166
167       -fmt=FORMAT, --format=FORMAT
168           Reports the output in the specified FORMAT. The formats currently
169           supported are ascii (the default) and gnuplot.
170
171       -h, --help
172           Displays help text for the scons-time mem subcommand.
173
174       -p STRING, --prefix=STRING
175           Specifies the prefix string for log files from which to extract
176           memory usage information. This will be used to search for log files
177           if no arguments are specified on the command line.
178
179       --stage=STAGE
180           Prints the memory used at the end of the specified STAGE: pre-read
181           (before the SConscript files are read), post-read , (after the
182           SConscript files are read), pre-build (before any targets are
183           built) or post-build (after any targets are built). If no --stage
184           option is specified, the default behavior is post-build, which
185           reports the final amount of memory used by SCons during each run.
186
187       -t NUMBER, --tail=NUMBER
188           Only reports memory statistics from the last NUMBER files.
189
190   The obj Subcommand
191       scons-time obj [-h] [--chdir=DIR] [-f FILE] [--fmt=FORMAT] [-p STRING]
192       [--stage=STAGE] [-t NUMBER] [--title=TITLE] [ARGUMENTS]
193
194       The scons-time obj subcommand displays how many objects of a specific
195       named type are created by SCons.
196
197       The scons-time obj subcommand extracts object counts from all the
198       specified file arguments, which should be files containing output from
199       running SCons with the --debug=count option. (Normally, these would be
200       *.log files generated by the scons-time run subcommand.) All file name
201       arguments will be globbed for on-disk files.
202
203       If no arguments are specified, then object counts will be extracted
204       from all *.log files, or the subset of them with a prefix specified by
205       the -p option.
206
207       -C DIR, --chdir=DIR
208           Changes to the specified DIRECTORY before looking for the specified
209           files (or files that match the specified patterns).
210
211       -f FILE, --file=FILE
212           Reads configuration information from the specified FILE.
213
214       -fmt=FORMAT, --format=FORMAT
215           Reports the output in the specified FORMAT. The formats currently
216           supported are ascii (the default) and gnuplot.
217
218       -h, --help
219           Displays help text for the scons-time obj subcommand.
220
221       -p STRING, --prefix=STRING
222           Specifies the prefix string for log files from which to extract
223           object counts. This will be used to search for log files if no
224           arguments are specified on the command line.
225
226       --stage=STAGE
227           Prints the object count at the end of the specified STAGE: pre-read
228           (before the SConscript files are read), post-read , (after the
229           SConscript files are read), pre-build (before any targets are
230           built) or post-build (after any targets are built). If no --stage
231           option is specified, the default behavior is post-build, which
232           reports the final object count during each run.
233
234       -t NUMBER, --tail=NUMBER
235           Only reports object counts from the last NUMBER files.
236
237   The run Subcommand
238       scons-time run [-hnqv] [-f FILE] [--number=NUMBER] [--outdir=OUTDIR]
239       [-p STRING] [--python=PYTHON] [-s DIR] [--scons=SCONS] [--svn=URL]
240       [ARGUMENTS] The scons-time run subcommand is the basic subcommand for
241       profiling a specific configuration against 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 below
267           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 be
272           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       -f FILE, --file=FILE
279           Reads configuration information from the specified FILE. This often
280           provides a more convenient way to specify and collect parameters
281           associated with a specific timing configuration than specifying
282           them on the command line. See the CONFIGURATION FILE section below
283           for information about the configuration file parameters.
284
285       -h, --help
286           Displays help text for the scons-time run subcommand.
287
288       -n, --no-exec
289           Do not execute commands, just printing the command-line equivalents
290           of what would be executed. Note that the scons-time script actually
291           executes its actions in Python, where possible, for portability.
292           The commands displayed are UNIX equivalents of what it's doing.
293
294       --number=NUMBER
295           Specifies the run number to be used in the names of the log files
296           and profile outputs generated by this run.
297
298       When used in conjunction with the --svn=URL option, NUMBER specifies
299       one or more comma-separated Subversion revision numbers that will be
300       retrieved automatically from the Subversion repository at the specified
301       URL. Ranges of delta or revision numbers may be specified be separating
302       two numbers with a hyphen (-).
303
304       Example:
305
306           % scons-time run --svn=http://scons.tigris.org/svn/trunk --num=1247,1249-1252 .
307
308       -p STRING, --prefix=STRING
309           Specifies the prefix string to be used for all of the log files and
310           profiles generated by this run. The default is derived from the
311           first specified argument: if the first argument is a directory, the
312           default prefix is the name of the directory; if the first argument
313           is an archive (tar or zip file), the default prefix is the the base
314           name of the archive, that is, what remains after stripping the
315           archive suffix (.tgz, .tar.gz or .zip).
316
317       --python=PYTHON
318           Specifies a path to the Python executable to be used for the timing
319           runs. The default is to use the same Python executable that is
320           running the scons-time command itself.
321
322       -q, --quiet
323           Suppresses display of the command lines being executed.
324
325       -s DIR, --subdir=DIR
326           Specifies the name of directory or subdirectory from which the
327           commands should be executed. The default is XXX
328
329       --scons=SCONS
330           Specifies a path to the SCons script to be used for the timing
331           runs. The default is XXX
332
333       --svn=URL, --subversion=URL
334           Specifies the URL of the Subversion repository from which the
335           version(s) of scons being timed will be extracted. When --svn is
336           specified, the --number=NUMBER option specifies revision numbers
337           that will be tested. Output from each invocation run will be placed
338           in file names that match the Subversion revision numbers. If the
339           --number= option is not specified, then the default behavior is to
340           time the HEAD of the specified URL.
341
342       -v, --verbose
343           Displays the output from individual commands to the screen (in
344           addition to capturing the output in log files).
345
346   The time Subcommand
347       scons-time time [-h] [--chdir=DIR] [-f FILE] [--fmt=FORMAT] [-p STRING]
348       [-t NUMBER] [--title=TITLE] [--which=WHICH] [ARGUMENTS]
349
350       The scons-time time subcommand displays SCons execution times as
351       reported by the scons --debug=time option.
352
353       The scons-time time subcommand extracts SCons timing from all the
354       specified file arguments, which should be files containing output from
355       running SCons with the --debug=time option. (Normally, these would be
356       *.log files generated by the scons-time run subcommand.) All file name
357       arguments will be globbed for on-disk files.
358
359       If no arguments are specified, then execution timings will be extracted
360       from all *.log files, or the subset of them with a prefix specified by
361       the -p option.
362
363       -C DIR, --chdir=DIR
364           Changes to the specified DIRECTORY before looking for the specified
365           files (or files that match the specified patterns).
366
367       -f FILE, --file=FILE
368           Reads configuration information from the specified FILE.
369
370       -fmt=FORMAT, --format=FORMAT
371           Reports the output in the specified FORMAT. The formats currently
372           supported are ascii (the default) and gnuplot.
373
374       -h, --help
375           Displays help text for the scons-time time subcommand.
376
377       -p STRING, --prefix=STRING
378           Specifies the prefix string for log files from which to extract
379           execution timings. This will be used to search for log files if no
380           arguments are specified on the command line.
381
382       -t NUMBER, --tail=NUMBER
383           Only reports object counts from the last NUMBER files.
384
385       --which=WHICH
386           Prints the execution time for the specified WHICH value: total (the
387           total execution time), SConscripts (total execution time for the
388           SConscript files themselves), SCons (exectuion time in SCons code
389           itself) or commands (execution time of the commands and other
390           actions used to build targets). If no --which option is specified,
391           the default behavior is total, which reports the total execution
392           time for each run.
393

CONFIGURATION FILE

395       Various scons-time subcommands can read information from a specified
396       configuration file when passed the -f or --file options. The
397       configuration file is actually executed as a Python script. Setting
398       Python variables in the configuration file controls the behavior of the
399       scons-time script more conveniently than having to specify command-line
400       options or arguments for every run, and provides a handy way to
401       "shrink-wrap" the necessary information for producing (and reporting)
402       consistent timing runs for a given configuration.
403
404       archive_list
405           A list of archives (files or directories) that will be copied to
406           the temporary directory in which SCons will be invoked.  .tar,
407           .tar.gz, .tgz and .zip files will have their contents unpacked in
408           the temporary directory. Directory trees and files will be copied
409           as-is.
410
411       initial_commands
412           A list of commands that will be executed before the actual timed
413           scons runs. This can be used for commands that are necessary to
414           prepare the source tree-for example, creating a configuration file
415           that should not be part of the timed run.
416
417       key_location
418           The location of the key on Gnuplot graphing information generated
419           with the --format=gnuplot option. The default is bottom left.
420
421       prefix
422           The file name prefix to be used when running or extracting timing
423           for this configuration.
424
425       python
426           The path name of the Python executable to be used when running or
427           extracting information for this configuration. The default is the
428           same version of Python used to run the SCons
429
430       scons
431           The path name of the SCons script to be used when running or
432           extracting information for this configuration. The default is
433           simply scons.
434
435       scons_flags
436           The scons flags used when running SCons to collect timing
437           information. The default value is --debug=count --debug=memory
438           --debug=time --debug=memoizer.
439
440       scons_lib_dir, scons_wrapper, startup_targets, subdir
441           The subdirectory of the project into which the scons-time script
442           should change before executing the SCons commands to time.
443
444       subversion_url
445           The Subversion URL from
446
447       svn
448           The subversion executable used to check out revisions of SCons to
449           be timed. The default is simple svn.
450
451       svn_co_flag, tar, targets
452           A string containing the targets that should be added to the command
453           line of every timed scons run. This can be used to restrict what's
454           being timed to a subset of the full build for the configuration.
455
456       targets0, targets1, targets2, title, unzip, verbose, vertical_bars
457
458   Example
459       Here is an example scons-time configuration file for a hypothetical
460       sample project:
461
462           # The project doesn't use SCons natively (yet), so we're
463           # timing a separate set of SConscript files that we lay
464           # on top of the vanilla unpacked project tarball.
465           arguments = ['project-1.2.tgz', 'project-SConscripts.tar']
466
467           # The subdirectory name contains the project version number,
468           # so tell scons-time to chdir there before building.
469           subdir = 'project-1.2'
470
471           # Set the prefix so output log files and profiles are named:
472           #     project-000-[012].{log,prof}
473           #     project-001-[012].{log,prof}
474           # etc.
475           prefix = 'project'
476
477           # The SConscript files being tested don't do any SConf
478           # configuration, so run their normal ./configure script
479           # before we invoke SCons.
480           initial_commands = [
481               './configure',
482           ]
483
484           # Only time building the bin/project executable.
485           targets = 'bin/project'
486
487           # Time against SCons revisions of the branches/core branch
488           subversion_url = 'http://scons.tigris.org/svn/scons/branches/core'
489

ENVIRONMENT

491       The scons-time script uses the following environment variables:
492
493       PRESERVE
494           If this value is set, the scons-time script will not remove the
495           temporary directory or directories in which it builds the specified
496           configuration or downloads a specific version of SCons.
497

SEE ALSO

499       gnuplot(1), scons(1)
500

AUTHORS

502       Steven Knight <knight at baldmt dot com>
503
504
505
506SCons 4.3.0                       01/22/2022                     SCONS-TIME(1)
Impressum