tools/scons-1.2.0/scons-time.1

   1 .\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 The SCons Foundation
   2 .\"
   3 .\" Permission is hereby granted, free of charge, to any person obtaining
   4 .\" a copy of this software and associated documentation files (the
   5 .\" "Software"), to deal in the Software without restriction, including
   6 .\" without limitation the rights to use, copy, modify, merge, publish,
   7 .\" distribute, sublicense, and/or sell copies of the Software, and to
   8 .\" permit persons to whom the Software is furnished to do so, subject to
   9 .\" the following conditions:
  10 .\"
  11 .\" The above copyright notice and this permission notice shall be included
  12 .\" in all copies or substantial portions of the Software.
  13 .\"
  14 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
  15 .\" KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  16 .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  17 .\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  18 .\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  19 .\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  20 .\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  21 .\"
  22 .\" doc/man/scons-time.1 3842 2008/12/20 22:59:52 scons
  23 .\"
  24 .\" ES - Example Start - indents and turns off line fill
  25 .de ES
  26 .RS
  27 .nf
  28 ..
  29 .\" EE - Example End - ends indent and turns line fill back on
  30 .de EE
  31 .RE
  32 .fi
  33 ..
  34 '\"==========================================================================
  35 .de SF
  36 .B scons-time func
  37 [\fB-h\fR]
  38 [\fB--chdir=\fIDIR\fR]
  39 [\fB-f \fIFILE\fR]
  40 [\fB--fmt=\fIFORMAT\fR]
  41 [\fB--func=\fINAME\fR]
  42 [\fB-p \fISTRING\fR]
  43 [\fB-t \fINUMBER\fR]
  44 [\fB--title= TITLE\fR]
  45 [\fIARGUMENTS\fR]
  46 ..
  47 '\"--------------------------------------------------------------------------
  48 .de SY
  49 .B scons-time mem
  50 [\fB-h\fR]
  51 [\fB--chdir=\fIDIR\fR]
  52 [\fB-f \fIFILE\fR]
  53 [\fB--fmt=\fIFORMAT\fR]
  54 [\fB-p \fISTRING\fR]
  55 [\fB--stage=\fISTAGE\fR]
  56 [\fB-t \fINUMBER\fR]
  57 [\fB--title=\fITITLE\fR]
  58 [\fIARGUMENTS\fR]
  59 ..
  60 '\"--------------------------------------------------------------------------
  61 .de SO
  62 .B scons-time obj
  63 [\fB-h\fR]
  64 [\fB--chdir=\fIDIR\fR]
  65 [\fB-f \fIFILE\fR]
  66 [\fB--fmt=\fIFORMAT\fR]
  67 [\fB-p \fISTRING\fR]
  68 [\fB--stage=\fISTAGE\fR]
  69 [\fB-t \fINUMBER\fR]
  70 [\fB--title=\fITITLE\fR]
  71 [\fIARGUMENTS\fR]
  72 ..
  73 '\"--------------------------------------------------------------------------
  74 .de SR
  75 .B scons-time run
  76 [\fB-hnqv\fR]
  77 [\fB--aegis=\fIPROJECT\fR]
  78 [\fB-f \fIFILE\fR]
  79 [\fB--number=\fINUMBER\fR]
  80 [\fB--outdir=\fIOUTDIR\fR]
  81 [\fB-p \fISTRING\fR]
  82 [\fB--python=\fIPYTHON\fR]
  83 [\fB-s \fIDIR\fR]
  84 [\fB--scons=\fISCONS\fR]
  85 [\fB--svn=\fIURL\fR]
  86 [\fIARGUMENTS\fR]
  87 ..
  88 '\"--------------------------------------------------------------------------
  89 .de ST
  90 .B scons-time time
  91 [\fB-h\fR]
  92 [\fB--chdir=\fIDIR\fR]
  93 [\fB-f \fIFILE\fR]
  94 [\fB--fmt=\fIFORMAT\fR]
  95 [\fB-p \fISTRING\fR]
  96 [\fB-t \fINUMBER\fR]
  97 [\fB--title=\fITITLE\fR]
  98 [\fB--which=\fIWHICH\fR]
  99 [\fIARGUMENTS\fR]
 100 ..
 101 .TH SCONS-TIME 1 "December 2008"
 102 .SH NAME
 103 scons-time \- generate and display SCons timing information
 104 '\"==========================================================================
 105 .SH SYNOPSIS
 106 .B scons-time
 107 .IR subcommand
 108 [
 109 .IR options ...
 110 ]
 111 [
 112 .IR arguments ...
 113 ]
 114 '\"--------------------------------------------------------------------------
 115 .SS "Generating Timing Information"
 116 .SR
 117 '\"--------------------------------------------------------------------------
 118 .SS "Extracting Function Timings"
 119 .SF
 120 '\"--------------------------------------------------------------------------
 121 .SS "Extracting Memory Statistics"
 122 .SY
 123 '\"--------------------------------------------------------------------------
 124 .SS "Extracting Object Counts"
 125 .SO
 126 '\"--------------------------------------------------------------------------
 127 .SS "Extracting Execution Times"
 128 .ST
 129 '\"--------------------------------------------------------------------------
 130 .SS "Help Text"
 131 .B scons-time help
 132 .I SUBCOMMAND
 133 [...]
 134 '\"==========================================================================
 135 .SH DESCRIPTION
 136 The
 137 .B scons-time
 138 command runs an SCons configuration
 139 through a standard set of profiled timings
 140 and can extract and graph information from the
 141 resulting profiles and log files of those timings.
 142 The action to be performed by the
 143 .B scons-time
 144 script is specified
 145 by a subcommand, the first argument on the command line.
 146 See the
 147 .B SUBCOMMANDS
 148 section below for information about the operation
 149 of specific subcommands.
 150 .P
 151 The basic way to use
 152 .B scons-time
 153 is to run the
 154 .B scons-time run
 155 subcommand
 156 (possibly multiple times)
 157 to generate profile and log file output,
 158 and then use one of the other
 159 subcommands to display the results
 160 captured in the profiles and log files
 161 for a particular kind of information:
 162 function timings
 163 (the
 164 .B scons-time func
 165 subcommand),
 166 total memory used
 167 (the
 168 .B scons-time mem
 169 subcommand),
 170 object counts
 171 (the
 172 .B scons-time obj
 173 subcommand)
 174 and overall execution time
 175 (the
 176 .B scons-time time
 177 subcommand).
 178 Options exist to place and find the
 179 profiles and log files in separate directories,
 180 to generate the output in a format suitable
 181 for graphing with the
 182 .BR gnuplot (1)
 183 program,
 184 and so on.
 185 .P
 186 There are two basic ways the
 187 .B scons-time run
 188 subcommand
 189 is intended to be used
 190 to gather timing statistics
 191 for a configuration.
 192 One is to use the
 193 .B --svn=
 194 option to test a configuration against
 195 a list of revisions from the SCons Subversion repository.
 196 This will generate a profile and timing log file
 197 for every revision listed with the
 198 .B --number=
 199 option,
 200 and can be used to look at the
 201 impact of commited changes to the
 202 SCons code base on a particular
 203 configuration over time.
 204 .P
 205 The other way is to profile incremental changes to a
 206 local SCons code base during a development cycle--that is,
 207 to look at the performance impact of changes
 208 you're making in the local tree.
 209 In this mode,
 210 you run the
 211 .B scons-time run
 212 subcommand
 213 .I without
 214 the
 215 .B --svn=
 216 option,
 217 in which case it simply looks in the profile/log file output directory
 218 (the current directory by default)
 219 and automatically figures out the
 220 .I next
 221 run number for the output profile and log file.
 222 Used in this way,
 223 the development cycle goes something like:
 224 make a change to SCons;
 225 run
 226 .B scons-time run
 227 to profile it against a specific configuration;
 228 make another change to SCons;
 229 run
 230 .B scons-time run
 231 again to profile it;
 232 etc.
 233 '\"==========================================================================
 234 .SH OPTIONS
 235 The
 236 .B scons-time
 237 command only supports a few global options:
 238 .TP
 239 -h, --help
 240 Displays the global help text and exits,
 241 identical to the
 242 .B scons-time help
 243 subcommand.
 244 .TP
 245 -V, --version
 246 Displays the
 247 .B scons-time
 248 version and exits.
 249 .P
 250 Most functionality is controlled by options
 251 to the individual subcommands.
 252 See the next section for information
 253 about individual subcommand options.
 254 '\"==========================================================================
 255 .SH SUBCOMMANDS
 256 The
 257 .B scons-time
 258 command supports the following
 259 individual subcommands.
 260 '\"--------------------------------------------------------------------------
 261 .SS "The func Subcommand"
 262 .SF
 263 .P
 264 The
 265 .B scons-time func
 266 subcommand displays timing information
 267 for a specific Python function within SCons.
 268 By default, it extracts information about the
 269 .BR _main ()
 270 function,
 271 which includes the Python profiler timing
 272 for all of SCons.
 273 .P
 274 The
 275 .B scons-time func
 276 subcommand extracts function timing information
 277 from all the specified file arguments,
 278 which should be Python profiler output files.
 279 (Normally, these would be
 280 .B *.prof
 281 files generated by the
 282 .B scons-time run
 283 subcommand,
 284 but they can actually be generated
 285 by any Python profiler invocation.)
 286 All file name arguments will be
 287 globbed for on-disk files.
 288 .P
 289 If no arguments are specified,
 290 then function timing information
 291 will be extracted from all
 292 .B *.prof
 293 files,
 294 or the subset of them
 295 with a prefix specified by the
 296 .B -p
 297 option.
 298 .P
 299 Options include:
 300 .TP
 301 -C DIRECTORY, --chdir=DIRECTORY
 302 Changes to the specified
 303 .I DIRECTORY
 304 before looking for the specified files
 305 (or files that match the specified patterns).
 306 .TP
 307 -f FILE, --file=FILE
 308 Reads configuration information from the specified
 309 .IR FILE .
 310 .TP
 311 -fmt=FORMAT, --format=FORMAT
 312 Reports the output in the specified
 313 .IR FORMAT .
 314 The formats currently supported are
 315 .B ascii
 316 (the default)
 317 and
 318 .BR gnuplot .
 319 .TP
 320 --func=NAME
 321 Extracts timings for the specified function
 322 .IR NAME .
 323 The default is to report cumulative timings for the
 324 .BR _main ()
 325 function,
 326 which contains the entire SCons run.
 327 .TP
 328 -h, --help
 329 Displays help text for the
 330 .B scons-time func
 331 subcommand.
 332 .TP
 333 -p STRING, --prefix=STRING
 334 Specifies the prefix string for profiles
 335 from which to extract function timing information.
 336 This will be used to search for profiles
 337 if no arguments are specified on the command line.
 338 .TP
 339 -t NUMBER, --tail=NUMBER
 340 Only extracts function timings from the last
 341 .I NUMBER
 342 files.
 343 '\"--------------------------------------------------------------------------
 344 .SS "The help Subcommand"
 345 .B scons-time help
 346 .I SUBCOMMAND
 347 [...]
 348 The
 349 .B help
 350 subcommand prints help text for any
 351 other subcommands listed as later arguments on the command line.
 352 '\"--------------------------------------------------------------------------
 353 .SS "The mem Subcommand"
 354 .SY
 355 .P
 356 The
 357 .B scons-time mem
 358 subcommand displays how much memory SCons uses.
 359 .P
 360 The
 361 .B scons-time mem
 362 subcommand extracts memory use information
 363 from all the specified file arguments,
 364 which should be files containing output from
 365 running SCons with the
 366 .B --debug=memory
 367 option.
 368 (Normally, these would be
 369 .B *.log
 370 files generated by the
 371 .B scons-time run
 372 subcommand.)
 373 All file name arguments will be
 374 globbed for on-disk files.
 375 .P
 376 If no arguments are specified,
 377 then memory information
 378 will be extracted from all
 379 .B *.log
 380 files,
 381 or the subset of them
 382 with a prefix specified by the
 383 .B -p
 384 option.
 385 .P
 386 .TP
 387 -C DIR, --chdir=DIR
 388 Changes to the specified
 389 .I DIRECTORY
 390 before looking for the specified files
 391 (or files that match the specified patterns).
 392 .TP
 393 -f FILE, --file=FILE
 394 Reads configuration information from the specified
 395 .IR FILE .
 396 .TP
 397 -fmt=FORMAT, --format=FORMAT
 398 Reports the output in the specified
 399 .IR FORMAT .
 400 The formats currently supported are
 401 .B ascii
 402 (the default)
 403 and
 404 .BR gnuplot .
 405 .TP
 406 -h, --help
 407 Displays help text for the
 408 .B scons-time mem
 409 subcommand.
 410 .TP
 411 -p STRING, --prefix=STRING
 412 Specifies the prefix string for log files
 413 from which to extract memory usage information.
 414 This will be used to search for log files
 415 if no arguments are specified on the command line.
 416 .TP
 417 --stage=STAGE
 418 Prints the memory used at the end of the specified
 419 .IR STAGE :
 420 .B pre-read
 421 (before the SConscript files are read),
 422 .B post-read ,
 423 (after the SConscript files are read),
 424 .B pre-build
 425 (before any targets are built)
 426 or
 427 .B post-build
 428 (after any targets are built).
 429 If no
 430 .B --stage
 431 option is specified,
 432 the default behavior is
 433 .BR post-build ,
 434 which reports the final amount of memory
 435 used by SCons during each run.
 436 .TP
 437 -t NUMBER, --tail=NUMBER
 438 Only reports memory statistics from the last
 439 .I NUMBER
 440 files.
 441 '\"--------------------------------------------------------------------------
 442 .SS "The obj Subcommand"
 443 .SO
 444 .P
 445 The
 446 .B scons-time obj
 447 subcommand displays how many objects of a specific named type
 448 are created by SCons.
 449 .P
 450 The
 451 .B scons-time obj
 452 subcommand extracts object counts
 453 from all the specified file arguments,
 454 which should be files containing output from
 455 running SCons with the
 456 .B --debug=count
 457 option.
 458 (Normally, these would be
 459 .B *.log
 460 files generated by the
 461 .B scons-time run
 462 subcommand.)
 463 All file name arguments will be
 464 globbed for on-disk files.
 465 .P
 466 If no arguments are specified,
 467 then object counts
 468 will be extracted from all
 469 .B *.log
 470 files,
 471 or the subset of them
 472 with a prefix specified by the
 473 .B -p
 474 option.
 475 .TP
 476 -C DIR, --chdir=DIR
 477 Changes to the specified
 478 .I DIRECTORY
 479 before looking for the specified files
 480 (or files that match the specified patterns).
 481 .TP
 482 -f FILE, --file=FILE
 483 Reads configuration information from the specified
 484 .IR FILE .
 485 .TP
 486 -fmt=FORMAT, --format=FORMAT
 487 Reports the output in the specified
 488 .IR FORMAT .
 489 The formats currently supported are
 490 .B ascii
 491 (the default)
 492 and
 493 .BR gnuplot .
 494 .TP
 495 -h, --help
 496 Displays help text for the
 497 .B scons-time obj
 498 subcommand.
 499 .TP
 500 -p STRING, --prefix=STRING
 501 Specifies the prefix string for log files
 502 from which to extract object counts.
 503 This will be used to search for log files
 504 if no arguments are specified on the command line.
 505 .TP
 506 --stage=STAGE
 507 Prints the object count at the end of the specified
 508 .IR STAGE :
 509 .B pre-read
 510 (before the SConscript files are read),
 511 .B post-read ,
 512 (after the SConscript files are read),
 513 .B pre-build
 514 (before any targets are built)
 515 or
 516 .B post-build
 517 (after any targets are built).
 518 If no
 519 .B --stage
 520 option is specified,
 521 the default behavior is
 522 .BR post-build ,
 523 which reports the final object count during each run.
 524 .TP
 525 -t NUMBER, --tail=NUMBER
 526 Only reports object counts from the last
 527 .I NUMBER
 528 files.
 529 '\"--------------------------------------------------------------------------
 530 .SS "The run Subcommand"
 531 .SR
 532 The
 533 .B scons-time run
 534 subcommand is the basic subcommand
 535 for profiling a specific configuration
 536 against a version of SCons.
 537 .P
 538 The configuration to be tested
 539 is specified as a list of files
 540 or directories that will be unpacked or copied
 541 into a temporary directory
 542 in which SCons will be invoked.
 543 The
 544 .B scons-time run
 545 subcommand understands file suffixes like
 546 .BR .tar ,
 547 .BR .tar.gz ,
 548 .BR .tgz
 549 and
 550 .BR .zip
 551 and will unpack their contents into a temporary directory.
 552 If more than one argument is specified,
 553 each one will be unpacked or copied
 554 into the temporary directory "on top of"
 555 the previous archives or directories,
 556 so the expectation is that multiple
 557 specified archives share the same directory layout.
 558 .P
 559 Once the file or directory arguments are unpacked or
 560 copied to the temporary directory,
 561 the
 562 .B scons-time run
 563 subcommand runs the
 564 requested version of SCons
 565 against the configuration
 566 three times:
 567 .TP
 568 Startup
 569 SCons is run with the
 570 .B --help
 571 option so that just the SConscript files are read,
 572 and then the default help text is printed.
 573 This profiles just the perceived "overhead" of starting up SCons
 574 and processing the SConscript files.
 575 .TP
 576 Full build
 577 SCons is run to build everything specified in the configuration.
 578 Specific targets to be passed in on the command l ine
 579 may be specified by the
 580 .B targets
 581 keyword in a configuration file; see below for details.
 582 .TP
 583 Rebuild
 584 SCons is run again on the same just-built directory.
 585 If the dependencies in the SCons configuration are correct,
 586 this should be an up-to-date, "do nothing" rebuild.
 587 .P
 588 Each invocation captures the output log file and a profile.
 589 .P
 590 The
 591 .B scons-time run
 592 subcommand supports the following options:
 593 .TP
 594 --aegis=PROJECT
 595 Specifies the Aegis
 596 .I PROJECT
 597 from which the
 598 version(s) of
 599 .B scons
 600 being timed will be extracted.
 601 When
 602 .B --aegis
 603 is specified, the
 604 .BI --number= NUMBER
 605 option specifies delta numbers
 606 that will be tested.
 607 Output from each invocation run will be placed in file
 608 names that match the Aegis delta numbers.
 609 If the
 610 .B --number=
 611 option is not specified,
 612 then the default behavior is to time the
 613 tip of the specified
 614 .IR PROJECT .
 615 .TP
 616 -f FILE, --file=FILE
 617 Reads configuration information from the specified
 618 .IR FILE .
 619 This often provides a more convenient way to specify and
 620 collect parameters associated with a specific timing configuration
 621 than specifying them on the command line.
 622 See the
 623 .B CONFIGURATION FILE
 624 section below
 625 for information about the configuration file parameters.
 626 .TP
 627 -h, --help
 628 Displays help text for the
 629 .B scons-time run
 630 subcommand.
 631 .TP
 632 -n, --no-exec
 633 Do not execute commands,
 634 just printing the command-line equivalents of what would be executed.
 635 Note that the
 636 .B scons-time
 637 script actually executes its actions in Python,
 638 where possible,
 639 for portability.
 640 The commands displayed are UNIX
 641 .I equivalents
 642 of what it's doing.
 643 .TP
 644 --number=NUMBER
 645 Specifies the run number to be used in the names of
 646 the log files and profile outputs generated by this run.
 647 .IP
 648 When used in conjuction with the
 649 .BI --aegis= PROJECT
 650 option,
 651 .I NUMBER
 652 specifies one or more comma-separated Aegis delta numbers
 653 that will be retrieved automatically from the specified Aegis
 654 .IR PROJECT .
 655 .IP
 656 When used in conjuction with the
 657 .BI --svn= URL
 658 option,
 659 .I NUMBER
 660 specifies one or more comma-separated Subversion revision numbers
 661 that will be retrieved automatically from the Subversion
 662 repository at the specified
 663 .IR URL .
 664 Ranges of delta or revision numbers
 665 may be specified be separating two numbers
 666 with a hyphen
 667 .RB ( \- ).
 668 .P
 669 Example:
 670 .ES
 671 % scons-time run --svn=http://scons.tigris.org/svn/trunk --num=1247,1249-1252 .
 672 .EE
 673 .TP
 674 -p STRING, --prefix=STRING
 675 Specifies the prefix string to be used for all of the log files
 676 and profiles generated by this run.
 677 The default is derived from the first
 678 specified argument:
 679 if the first argument is a directory,
 680 the default prefix is the name of the directory;
 681 if the first argument is an archive
 682 (tar or zip file),
 683 the default prefix is the the base name of the archive,
 684 that is, what remains after stripping the archive suffix
 685 .RB ( .tgz ", " .tar.gz " or " .zip ).
 686 .TP
 687 --python=PYTHON
 688 Specifies a path to the Python executable to be used
 689 for the timing runs.
 690 The default is to use the same Python executable that
 691 is running the
 692 .B scons-time
 693 command itself.
 694 .TP
 695 -q, --quiet
 696 Suppresses display of the command lines being executed.
 697 .TP
 698 -s DIR, --subdir=DIR
 699 Specifies the name of directory or subdirectory
 700 from which the commands should be executed.
 701 The default is XXX
 702 .TP
 703 --scons=SCONS
 704 Specifies a path to the SCons script to be used
 705 for the timing runs.
 706 The default is XXX
 707 .TP
 708 --svn=URL, --subversion=URL
 709 Specifies the
 710 .I URL
 711 of the Subversion repository from which the
 712 version(s) of
 713 .B scons
 714 being timed will be extracted.
 715 When
 716 .B --svn
 717 is specified, the
 718 .BI --number= NUMBER
 719 option specifies revision numbers
 720 that will be tested.
 721 Output from each invocation run will be placed in file
 722 names that match the Subversion revision numbers.
 723 If the
 724 .B --number=
 725 option is not specified,
 726 then the default behavior is to time the
 727 .B HEAD
 728 of the specified
 729 .IR URL .
 730 .TP
 731 -v, --verbose
 732 Displays the output from individual commands to the screen
 733 (in addition to capturing the output in log files).
 734 '\"--------------------------------------------------------------------------
 735 .SS "The time Subcommand"
 736 .ST
 737 .P
 738 The
 739 .B scons-time time
 740 subcommand displays SCons execution times
 741 as reported by the
 742 .B scons --debug=time
 743 option.
 744 .P
 745 The
 746 .B scons-time time
 747 subcommand extracts SCons timing
 748 from all the specified file arguments,
 749 which should be files containing output from
 750 running SCons with the
 751 .B --debug=time
 752 option.
 753 (Normally, these would be
 754 .B *.log
 755 files generated by the
 756 .B scons-time run
 757 subcommand.)
 758 All file name arguments will be
 759 globbed for on-disk files.
 760 .P
 761 If no arguments are specified,
 762 then execution timings
 763 will be extracted from all
 764 .B *.log
 765 files,
 766 or the subset of them
 767 with a prefix specified by the
 768 .B -p
 769 option.
 770 .TP
 771 -C DIR, --chdir=DIR
 772 Changes to the specified
 773 .I DIRECTORY
 774 before looking for the specified files
 775 (or files that match the specified patterns).
 776 .TP
 777 -f FILE, --file=FILE
 778 Reads configuration information from the specified
 779 .IR FILE .
 780 .TP
 781 -fmt=FORMAT, --format=FORMAT
 782 Reports the output in the specified
 783 .IR FORMAT .
 784 The formats currently supported are
 785 .B ascii
 786 (the default)
 787 and
 788 .BR gnuplot .
 789 .TP
 790 -h, --help
 791 Displays help text for the
 792 .B scons-time time
 793 subcommand.
 794 .TP
 795 -p STRING, --prefix=STRING
 796 Specifies the prefix string for log files
 797 from which to extract execution timings.
 798 This will be used to search for log files
 799 if no arguments are specified on the command line.
 800 .TP
 801 -t NUMBER, --tail=NUMBER
 802 Only reports object counts from the last
 803 .I NUMBER
 804 files.
 805 .TP
 806 --which=WHICH
 807 Prints the execution time for the specified
 808 .IR WHICH
 809 value:
 810 .B total
 811 (the total execution time),
 812 .B SConscripts
 813 (total execution time for the SConscript files themselves),
 814 .B SCons
 815 (exectuion time in SCons code itself)
 816 or
 817 .B commands
 818 (execution time of the commands and other actions
 819 used to build targets).
 820 If no
 821 .B --which
 822 option is specified,
 823 the default behavior is
 824 .BR total ,
 825 which reports the total execution time for each run.
 826 '\"==========================================================================
 827 .SH CONFIGURATION FILE
 828 Various
 829 .B scons-time
 830 subcommands can read information from a specified
 831 configuration file when passed the
 832 .B \-f
 833 or
 834 .B \--file
 835 options.
 836 The configuration file is actually executed as a Python script.
 837 Setting Python variables in the configuration file
 838 controls the behavior of the
 839 .B scons-time
 840 script more conveniently than having to specify
 841 command-line options or arguments for every run,
 842 and provides a handy way to "shrink-wrap"
 843 the necessary information for producing (and reporting)
 844 consistent timing runs for a given configuration.
 845 .TP
 846 .B aegis
 847 The Aegis executable for extracting deltas.
 848 The default is simply
 849 .BR aegis .
 850 .TP
 851 .B aegis_project
 852 The Aegis project from which deltas should be extracted.
 853 The default is whatever is specified
 854 with the
 855 .B --aegis=
 856 command-line option.
 857 .TP
 858 .B archive_list
 859 A list of archives (files or directories)
 860 that will be copied to the temporary directory
 861 in which SCons will be invoked.
 862 .BR .tar ,
 863 .BR .tar.gz ,
 864 .BR .tgz
 865 and
 866 .BR .zip
 867 files will have their contents unpacked in
 868 the temporary directory.
 869 Directory trees and files will be copied as-is.
 870 .TP
 871 .B initial_commands
 872 A list of commands that will be executed
 873 before the actual timed
 874 .B scons
 875 runs.
 876 This can be used for commands that are necessary
 877 to prepare the source tree\-for example,
 878 creating a configuration file
 879 that should not be part of the timed run.
 880 .TP
 881 .B key_location
 882 The location of the key on Gnuplot graphing information
 883 generated with the
 884 .BR --format=gnuplot
 885 option.
 886 The default is
 887 .BR "bottom left" .
 888 .TP
 889 .B prefix
 890 The file name prefix to be used when
 891 running or extracting timing for this configuration.
 892 .TP
 893 .B python
 894 The path name of the Python executable
 895 to be used when running or extracting information
 896 for this configuration.
 897 The default is the same version of Python
 898 used to run the SCons
 899 .TP
 900 .B scons
 901 The path name of the SCons script to be used
 902 when running or extracting information
 903 for this configuration.
 904 The default is simply
 905 .BR scons .
 906 .TP
 907 .B scons_flags
 908 The
 909 .B scons
 910 flags used when running SCons to collect timing information.
 911 The default value is
 912 .BR "--debug=count --debug=memory --debug=time --debug=memoizer" .
 913 .TP
 914 .B scons_lib_dir
 915 .TP
 916 .B scons_wrapper
 917 .TP
 918 .B startup_targets
 919 .TP
 920 .B subdir
 921 The subdirectory of the project into which the
 922 .B scons-time
 923 script should change
 924 before executing the SCons commands to time.
 925 .TP
 926 .B subversion_url
 927 The Subversion URL from
 928 .TP
 929 .B svn
 930 The subversion executable used to
 931 check out revisions of SCons to be timed.
 932 The default is simple
 933 .BR svn .
 934 .TP
 935 .B svn_co_flag
 936 .TP
 937 .B tar
 938 .TP
 939 .B targets
 940 A string containing the targets that should be added to
 941 the command line of every timed
 942 .B scons
 943 run.
 944 This can be used to restrict what's being timed to a
 945 subset of the full build for the configuration.
 946 .TP
 947 .B targets0
 948 .TP
 949 .B targets1
 950 .TP
 951 .B targets2
 952 .TP
 953 .B title
 954 .TP
 955 .B unzip
 956 .TP
 957 .B verbose
 958 .TP
 959 .B vertical_bars
 960 '\"--------------------------------------------------------------------------
 961 .SS Example
 962 Here is an example
 963 .B scons-time
 964 configuration file
 965 for a hypothetical sample project:
 966 .P
 967 .ES
 968 # The project doesn't use SCons natively (yet), so we're
 969 # timing a separate set of SConscript files that we lay
 970 # on top of the vanilla unpacked project tarball.
 971 arguments = ['project-1.2.tgz', 'project-SConscripts.tar']
 972
 973 # The subdirectory name contains the project version number,
 974 # so tell scons-time to chdir there before building.
 975 subdir = 'project-1.2'
 976
 977 # Set the prefix so output log files and profiles are named:
 978 #     project-000-[012].{log,prof}
 979 #     project-001-[012].{log,prof}
 980 # etc.
 981 prefix = 'project'
 982
 983 # The SConscript files being tested don't do any SConf
 984 # configuration, so run their normal ./configure script
 985 # before we invoke SCons.
 986 initial_commands = [
 987     './configure',
 988 ]
 989
 990 # Only time building the bin/project executable.
 991 targets = 'bin/project'
 992
 993 # Time against SCons revisions of the branches/core branch
 994 subversion_url = 'http://scons.tigris.org/svn/scons/branches/core'
 995 .EE
 996 '\"==========================================================================
 997 .SH ENVIRONMENT
 998 The
 999 .B scons-time
1000 script uses the following environment variables:
1001 .TP
1002 .B PRESERVE
1003 If this value is set,
1004 the
1005 .B scons-time
1006 script will
1007 .I not
1008 remove the temporary directory or directories
1009 in which it builds the specified configuration
1010 or downloads a specific version of SCons.
1011 '\"==========================================================================
1012 .SH "SEE ALSO"
1013 .BR gnuplot (1),
1014 .BR scons (1)
1015
1016 .SH AUTHORS
1017 Steven Knight <knight at baldmt dot com>