doc/man/scons-time.xml

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