diff options
Diffstat (limited to 'doc/man/scons-time.xml')
| -rw-r--r-- | doc/man/scons-time.xml | 1283 |
1 files changed, 1283 insertions, 0 deletions
diff --git a/doc/man/scons-time.xml b/doc/man/scons-time.xml new file mode 100644 index 0000000..6227e25 --- /dev/null +++ b/doc/man/scons-time.xml @@ -0,0 +1,1283 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!-- lifted from troff+man by doclifter --> +<refentry id='sconstime1'> +<!-- __COPYRIGHT__ --> + +<!-- Permission is hereby granted, free of charge, to any person obtaining --> +<!-- a copy of this software and associated documentation files (the --> +<!-- "Software"), to deal in the Software without restriction, including --> +<!-- without limitation the rights to use, copy, modify, merge, publish, --> +<!-- distribute, sublicense, and/or sell copies of the Software, and to --> +<!-- permit persons to whom the Software is furnished to do so, subject to --> +<!-- the following conditions: --> + +<!-- The above copyright notice and this permission notice shall be included --> +<!-- in all copies or substantial portions of the Software. --> + +<!-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY --> +<!-- KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE --> +<!-- WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND --> +<!-- NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE --> +<!-- LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION --> +<!-- OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION --> +<!-- WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. --> + +<!-- __FILE__ __REVISION__ __DATE__ __DEVELOPER__ --> + +<!-- ES \- Example Start \- indents and turns off line fill --> +<!-- EE \- Example End \- ends indent and turns line fill back on --> +<!-- '\"========================================================================== --> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> +<refmeta> +<refentrytitle>SCONS-TIME</refentrytitle> +<manvolnum>1</manvolnum> +<refmiscinfo class='source'>__MONTH_YEAR__</refmiscinfo> +</refmeta> +<refnamediv id='name'> +<refname>scons-time</refname> +<refpurpose>generate and display SCons timing information</refpurpose> +</refnamediv> +<refsynopsisdiv id='synopsis'> +<cmdsynopsis> + <command>scons-time</command> + <arg choice='plain'><replaceable>subcommand</replaceable></arg> + <arg choice='opt' rep='repeat'><replaceable>options</replaceable></arg> + <arg choice='opt' rep='repeat'><replaceable>arguments</replaceable></arg> +</cmdsynopsis> +</refsynopsisdiv> + +<!-- body begins here --> + +<refsect1 id='generating_timing_information'><title>Generating Timing Information</title> +<para><emphasis remap='B'>scons-time run</emphasis> +[<option>-hnqv</option>] +[<option>--aegis=</option><replaceable>PROJECT</replaceable>] +[<option>-f </option><emphasis remap='I'>FILE</emphasis>] +[<option>--number=</option><replaceable>NUMBER</replaceable>] +[<option>--outdir=</option><replaceable>OUTDIR</replaceable>] +[<option>-p </option><emphasis remap='I'>STRING</emphasis>] +[<option>--python=</option><replaceable>PYTHON</replaceable>] +[<option>-s </option><emphasis remap='I'>DIR</emphasis>] +[<option>--scons=</option><replaceable>SCONS</replaceable>] +[<option>--svn=</option><replaceable>URL</replaceable>] +[<emphasis remap='I'>ARGUMENTS</emphasis>]</para> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> + +<refsect2 id='extracting_function_timings'><title>Extracting Function Timings</title> +<para><emphasis remap='B'>scons-time func</emphasis> +[<option>-h</option>] +[<option>--chdir=</option><replaceable>DIR</replaceable>] +[<option>-f </option><emphasis remap='I'>FILE</emphasis>] +[<option>--fmt=</option><replaceable>FORMAT</replaceable>] +[<option>--func=</option><replaceable>NAME</replaceable>] +[<option>-p </option><emphasis remap='I'>STRING</emphasis>] +[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>] +[<option>--title= TITLE</option>] +[<emphasis remap='I'>ARGUMENTS</emphasis>]</para> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> +</refsect2> + +<refsect2 id='extracting_memory_statistics'><title>Extracting Memory Statistics</title> +<para><emphasis remap='B'>scons-time mem</emphasis> +[<option>-h</option>] +[<option>--chdir=</option><replaceable>DIR</replaceable>] +[<option>-f </option><emphasis remap='I'>FILE</emphasis>] +[<option>--fmt=</option><replaceable>FORMAT</replaceable>] +[<option>-p </option><emphasis remap='I'>STRING</emphasis>] +[<option>--stage=</option><replaceable>STAGE</replaceable>] +[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>] +[<option>--title=</option><replaceable>TITLE</replaceable>] +[<emphasis remap='I'>ARGUMENTS</emphasis>]</para> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> +</refsect2> + +<refsect2 id='extracting_object_counts'><title>Extracting Object Counts</title> +<para><emphasis remap='B'>scons-time obj</emphasis> +[<option>-h</option>] +[<option>--chdir=</option><replaceable>DIR</replaceable>] +[<option>-f </option><emphasis remap='I'>FILE</emphasis>] +[<option>--fmt=</option><replaceable>FORMAT</replaceable>] +[<option>-p </option><emphasis remap='I'>STRING</emphasis>] +[<option>--stage=</option><replaceable>STAGE</replaceable>] +[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>] +[<option>--title=</option><replaceable>TITLE</replaceable>] +[<emphasis remap='I'>ARGUMENTS</emphasis>]</para> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> +</refsect2> + +<refsect2 id='extracting_execution_times'><title>Extracting Execution Times</title> +<para><emphasis remap='B'>scons-time time</emphasis> +[<option>-h</option>] +[<option>--chdir=</option><replaceable>DIR</replaceable>] +[<option>-f </option><emphasis remap='I'>FILE</emphasis>] +[<option>--fmt=</option><replaceable>FORMAT</replaceable>] +[<option>-p </option><emphasis remap='I'>STRING</emphasis>] +[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>] +[<option>--title=</option><replaceable>TITLE</replaceable>] +[<option>--which=</option><replaceable>WHICH</replaceable>] +[<emphasis remap='I'>ARGUMENTS</emphasis>]</para> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> +</refsect2> + +<refsect2 id='help_text'><title>Help Text</title> +<para><emphasis remap='B'>scons-time help</emphasis> +<emphasis remap='I'>SUBCOMMAND</emphasis> +[...]</para> +<!-- '\"========================================================================== --> +</refsect2> +</refsect1> + +<refsect1 id='description'><title>DESCRIPTION</title> +<para>The +<command>scons-time</command> +command runs an SCons configuration +through a standard set of profiled timings +and can extract and graph information from the +resulting profiles and log files of those timings. +The action to be performed by the +<command>scons-time</command> +script is specified +by a subcommand, the first argument on the command line. +See the +<link linkend="subcommands">SUBCOMMANDS</link> +section below for information about the operation +of specific subcommands.</para> + +<para>The basic way to use +<command>scons-time</command> +is to run the +<emphasis remap='B'>scons-time run</emphasis> +subcommand +(possibly multiple times) +to generate profile and log file output, +and then use one of the other +subcommands to display the results +captured in the profiles and log files +for a particular kind of information: +function timings +(the +<emphasis remap='B'>scons-time func</emphasis> +subcommand), +total memory used +(the +<emphasis remap='B'>scons-time mem</emphasis> +subcommand), +object counts +(the +<emphasis remap='B'>scons-time obj</emphasis> +subcommand) +and overall execution time +(the +<emphasis remap='B'>scons-time time</emphasis> +subcommand). +Options exist to place and find the +profiles and log files in separate directories, +to generate the output in a format suitable +for graphing with the +<citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry> +program, +and so on.</para> + +<para>There are two basic ways the +<emphasis remap='B'>scons-time run</emphasis> +subcommand +is intended to be used +to gather timing statistics +for a configuration. +One is to use the +<option>--svn=</option> +option to test a configuration against +a list of revisions from the SCons Subversion repository. +This will generate a profile and timing log file +for every revision listed with the +<option>--number=</option> +option, +and can be used to look at the +impact of commited changes to the +SCons code base on a particular +configuration over time.</para> + +<para>The other way is to profile incremental changes to a +local SCons code base during a development cycle--that is, +to look at the performance impact of changes +you're making in the local tree. +In this mode, +you run the +<emphasis remap='B'>scons-time run</emphasis> +subcommand +<emphasis remap='I'>without</emphasis> +the +<option>--svn=</option> +option, +in which case it simply looks in the profile/log file output directory +(the current directory by default) +and automatically figures out the +<emphasis remap='I'>next</emphasis> +run number for the output profile and log file. +Used in this way, +the development cycle goes something like: +make a change to SCons; +run +<emphasis remap='B'>scons-time run</emphasis> +to profile it against a specific configuration; +make another change to SCons; +run +<emphasis remap='B'>scons-time run</emphasis> +again to profile it; +etc.</para> +<!-- '\"========================================================================== --> +</refsect1> + +<refsect1 id='options'><title>OPTIONS</title> +<para>The +<command>scons-time</command> +command only supports a few global options:</para> +<variablelist remap='TP'> + <varlistentry> + <term>-h, --help</term> + <listitem> +<para>Displays the global help text and exits, +identical to the +<emphasis remap='B'>scons-time help</emphasis> +subcommand.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-V, --version</term> + <listitem> +<para>Displays the +<command>scons-time</command> +version and exits.</para> + </listitem> + </varlistentry> +</variablelist> + +<para>Most functionality is controlled by options +to the individual subcommands. +See the next section for information +about individual subcommand options.</para> +<!-- '\"========================================================================== --> +</refsect1> + +<refsect1 id='subcommands'><title>SUBCOMMANDS</title> +<para>The +<command>scons-time</command> +command supports the following +individual subcommands.</para> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> + +<refsect2 id='the_func_subcommand'><title>The func Subcommand</title> +<para><emphasis remap='B'>scons-time func</emphasis> +[<option>-h</option>] +[<option>--chdir=</option><replaceable>DIR</replaceable>] +[<option>-f </option><emphasis remap='I'>FILE</emphasis>] +[<option>--fmt=</option><replaceable>FORMAT</replaceable>] +[<option>--func=</option><replaceable>NAME</replaceable>] +[<option>-p </option><emphasis remap='I'>STRING</emphasis>] +[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>] +[<option>--title= TITLE</option>] +[<emphasis remap='I'>ARGUMENTS</emphasis>]</para> + +<para>The +<emphasis remap='B'>scons-time func</emphasis> +subcommand displays timing information +for a specific Python function within SCons. +By default, it extracts information about the +<emphasis remap='B'>_main</emphasis>() +function, +which includes the Python profiler timing +for all of SCons.</para> + +<para>The +<emphasis remap='B'>scons-time func</emphasis> +subcommand extracts function timing information +from all the specified file arguments, +which should be Python profiler output files. +(Normally, these would be +<emphasis remap='B'>*.prof</emphasis> +files generated by the +<emphasis remap='B'>scons-time run</emphasis> +subcommand, +but they can actually be generated +by any Python profiler invocation.) +All file name arguments will be +globbed for on-disk files.</para> + +<para>If no arguments are specified, +then function timing information +will be extracted from all +<emphasis remap='B'>*.prof</emphasis> +files, +or the subset of them +with a prefix specified by the +<option>-p</option> +option.</para> + +<para>Options include:</para> +<variablelist remap='TP'> + <varlistentry> + <term>-C DIRECTORY, --chdir=DIRECTORY</term> + <listitem> +<para>Changes to the specified +<emphasis remap='I'>DIRECTORY</emphasis> +before looking for the specified files +(or files that match the specified patterns).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-f FILE, --file=FILE</term> + <listitem> +<para>Reads configuration information from the specified +<emphasis remap='I'>FILE</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-fmt=FORMAT, --format=FORMAT</term> + <listitem> +<para>Reports the output in the specified +<emphasis remap='I'>FORMAT</emphasis>. +The formats currently supported are +<emphasis remap='B'>ascii</emphasis> +(the default) +and +<emphasis remap='B'>gnuplot</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>--func=NAME</term> + <listitem> +<para>Extracts timings for the specified function +<emphasis remap='I'>NAME</emphasis>. +The default is to report cumulative timings for the +<emphasis remap='B'>_main</emphasis>() +function, +which contains the entire SCons run.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-h, --help</term> + <listitem> +<para>Displays help text for the +<emphasis remap='B'>scons-time func</emphasis> +subcommand.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-p STRING, --prefix=STRING</term> + <listitem> +<para>Specifies the prefix string for profiles +from which to extract function timing information. +This will be used to search for profiles +if no arguments are specified on the command line.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-t NUMBER, --tail=NUMBER</term> + <listitem> +<para>Only extracts function timings from the last +<emphasis remap='I'>NUMBER</emphasis> +files.</para> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> + </listitem> + </varlistentry> +</variablelist> +</refsect2> + +<refsect2 id='the_help_subcommand'><title>The help Subcommand</title> +<para><emphasis remap='B'>scons-time help</emphasis> +<emphasis remap='I'>SUBCOMMAND</emphasis> +[...] +The +<emphasis remap='B'>help</emphasis> +subcommand prints help text for any +other subcommands listed as later arguments on the command line.</para> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> +</refsect2> + +<refsect2 id='the_mem_subcommand'><title>The mem Subcommand</title> +<para><emphasis remap='B'>scons-time mem</emphasis> +[<option>-h</option>] +[<option>--chdir=</option><replaceable>DIR</replaceable>] +[<option>-f </option><emphasis remap='I'>FILE</emphasis>] +[<option>--fmt=</option><replaceable>FORMAT</replaceable>] +[<option>-p </option><emphasis remap='I'>STRING</emphasis>] +[<option>--stage=</option><replaceable>STAGE</replaceable>] +[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>] +[<option>--title=</option><replaceable>TITLE</replaceable>] +[<emphasis remap='I'>ARGUMENTS</emphasis>]</para> + +<para>The +<emphasis remap='B'>scons-time mem</emphasis> +subcommand displays how much memory SCons uses.</para> + +<para>The +<emphasis remap='B'>scons-time mem</emphasis> +subcommand extracts memory use information +from all the specified file arguments, +which should be files containing output from +running SCons with the +<option>--debug=memory</option> +option. +(Normally, these would be +<emphasis remap='B'>*.log</emphasis> +files generated by the +<emphasis remap='B'>scons-time run</emphasis> +subcommand.) +All file name arguments will be +globbed for on-disk files.</para> + +<para>If no arguments are specified, +then memory information +will be extracted from all +<emphasis remap='B'>*.log</emphasis> +files, +or the subset of them +with a prefix specified by the +<option>-p</option> +option.</para> + +<variablelist remap='TP'> + <varlistentry> + <term>-C DIR, --chdir=DIR</term> + <listitem> +<para>Changes to the specified +<emphasis remap='I'>DIRECTORY</emphasis> +before looking for the specified files +(or files that match the specified patterns).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-f FILE, --file=FILE</term> + <listitem> +<para>Reads configuration information from the specified +<emphasis remap='I'>FILE</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-fmt=FORMAT, --format=FORMAT</term> + <listitem> +<para>Reports the output in the specified +<emphasis remap='I'>FORMAT</emphasis>. +The formats currently supported are +<emphasis remap='B'>ascii</emphasis> +(the default) +and +<emphasis remap='B'>gnuplot</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-h, --help</term> + <listitem> +<para>Displays help text for the +<emphasis remap='B'>scons-time mem</emphasis> +subcommand.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-p STRING, --prefix=STRING</term> + <listitem> +<para>Specifies the prefix string for log files +from which to extract memory usage information. +This will be used to search for log files +if no arguments are specified on the command line.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>--stage=STAGE</term> + <listitem> +<para>Prints the memory used at the end of the specified +<emphasis remap='I'>STAGE</emphasis>: +<emphasis remap='B'>pre-read</emphasis> +(before the SConscript files are read), +<emphasis remap='B'>post-read ,</emphasis> +(after the SConscript files are read), +<emphasis remap='B'>pre-build</emphasis> +(before any targets are built) +or +<emphasis remap='B'>post-build</emphasis> +(after any targets are built). +If no +<option>--stage</option> +option is specified, +the default behavior is +<emphasis remap='B'>post-build</emphasis>, +which reports the final amount of memory +used by SCons during each run.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-t NUMBER, --tail=NUMBER</term> + <listitem> +<para>Only reports memory statistics from the last +<emphasis remap='I'>NUMBER</emphasis> +files.</para> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> + </listitem> + </varlistentry> +</variablelist> +</refsect2> + +<refsect2 id='the_obj_subcommand'><title>The obj Subcommand</title> +<para><emphasis remap='B'>scons-time obj</emphasis> +[<option>-h</option>] +[<option>--chdir=</option><replaceable>DIR</replaceable>] +[<option>-f </option><emphasis remap='I'>FILE</emphasis>] +[<option>--fmt=</option><replaceable>FORMAT</replaceable>] +[<option>-p </option><emphasis remap='I'>STRING</emphasis>] +[<option>--stage=</option><replaceable>STAGE</replaceable>] +[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>] +[<option>--title=</option><replaceable>TITLE</replaceable>] +[<emphasis remap='I'>ARGUMENTS</emphasis>]</para> + +<para>The +<emphasis remap='B'>scons-time obj</emphasis> +subcommand displays how many objects of a specific named type +are created by SCons.</para> + +<para>The +<emphasis remap='B'>scons-time obj</emphasis> +subcommand extracts object counts +from all the specified file arguments, +which should be files containing output from +running SCons with the +<option>--debug=count</option> +option. +(Normally, these would be +<emphasis remap='B'>*.log</emphasis> +files generated by the +<emphasis remap='B'>scons-time run</emphasis> +subcommand.) +All file name arguments will be +globbed for on-disk files.</para> + +<para>If no arguments are specified, +then object counts +will be extracted from all +<emphasis remap='B'>*.log</emphasis> +files, +or the subset of them +with a prefix specified by the +<option>-p</option> +option.</para> +<variablelist remap='TP'> + <varlistentry> + <term>-C DIR, --chdir=DIR</term> + <listitem> +<para>Changes to the specified +<emphasis remap='I'>DIRECTORY</emphasis> +before looking for the specified files +(or files that match the specified patterns).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-f FILE, --file=FILE</term> + <listitem> +<para>Reads configuration information from the specified +<emphasis remap='I'>FILE</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-fmt=FORMAT, --format=FORMAT</term> + <listitem> +<para>Reports the output in the specified +<emphasis remap='I'>FORMAT</emphasis>. +The formats currently supported are +<emphasis remap='B'>ascii</emphasis> +(the default) +and +<emphasis remap='B'>gnuplot</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-h, --help</term> + <listitem> +<para>Displays help text for the +<emphasis remap='B'>scons-time obj</emphasis> +subcommand.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-p STRING, --prefix=STRING</term> + <listitem> +<para>Specifies the prefix string for log files +from which to extract object counts. +This will be used to search for log files +if no arguments are specified on the command line.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>--stage=STAGE</term> + <listitem> +<para>Prints the object count at the end of the specified +<emphasis remap='I'>STAGE</emphasis>: +<emphasis remap='B'>pre-read</emphasis> +(before the SConscript files are read), +<emphasis remap='B'>post-read ,</emphasis> +(after the SConscript files are read), +<emphasis remap='B'>pre-build</emphasis> +(before any targets are built) +or +<emphasis remap='B'>post-build</emphasis> +(after any targets are built). +If no +<option>--stage</option> +option is specified, +the default behavior is +<emphasis remap='B'>post-build</emphasis>, +which reports the final object count during each run.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-t NUMBER, --tail=NUMBER</term> + <listitem> +<para>Only reports object counts from the last +<emphasis remap='I'>NUMBER</emphasis> +files.</para> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> + </listitem> + </varlistentry> +</variablelist> +</refsect2> + +<refsect2 id='the_run_subcommand'><title>The run Subcommand</title> +<para><emphasis remap='B'>scons-time run</emphasis> +[<option>-hnqv</option>] +[<option>--aegis=</option><replaceable>PROJECT</replaceable>] +[<option>-f </option><emphasis remap='I'>FILE</emphasis>] +[<option>--number=</option><replaceable>NUMBER</replaceable>] +[<option>--outdir=</option><replaceable>OUTDIR</replaceable>] +[<option>-p </option><emphasis remap='I'>STRING</emphasis>] +[<option>--python=</option><replaceable>PYTHON</replaceable>] +[<option>-s </option><emphasis remap='I'>DIR</emphasis>] +[<option>--scons=</option><replaceable>SCONS</replaceable>] +[<option>--svn=</option><replaceable>URL</replaceable>] +[<emphasis remap='I'>ARGUMENTS</emphasis>] +The +<emphasis remap='B'>scons-time run</emphasis> +subcommand is the basic subcommand +for profiling a specific configuration +against a version of SCons.</para> + +<para>The configuration to be tested +is specified as a list of files +or directories that will be unpacked or copied +into a temporary directory +in which SCons will be invoked. +The +<emphasis remap='B'>scons-time run</emphasis> +subcommand understands file suffixes like +<markup>.tar</markup>, +<markup>.tar.gz</markup>, +<markup>.tgz</markup> +and +<markup>.zip</markup> +and will unpack their contents into a temporary directory. +If more than one argument is specified, +each one will be unpacked or copied +into the temporary directory "on top of" +the previous archives or directories, +so the expectation is that multiple +specified archives share the same directory layout.</para> + +<para>Once the file or directory arguments are unpacked or +copied to the temporary directory, +the +<emphasis remap='B'>scons-time run</emphasis> +subcommand runs the +requested version of SCons +against the configuration +three times:</para> +<variablelist remap='TP'> + <varlistentry> + <term>Startup</term> + <listitem> +<para>SCons is run with the +<option>--help</option> +option so that just the SConscript files are read, +and then the default help text is printed. +This profiles just the perceived "overhead" of starting up SCons +and processing the SConscript files.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Full build</term> + <listitem> +<para>SCons is run to build everything specified in the configuration. +Specific targets to be passed in on the command l ine +may be specified by the +<emphasis remap='B'>targets</emphasis> +keyword in a configuration file; see below for details.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Rebuild</term> + <listitem> +<para>SCons is run again on the same just-built directory. +If the dependencies in the SCons configuration are correct, +this should be an up-to-date, "do nothing" rebuild.</para> + </listitem> + </varlistentry> +</variablelist> + +<para>Each invocation captures the output log file and a profile.</para> + +<para>The +<emphasis remap='B'>scons-time run</emphasis> +subcommand supports the following options:</para> +<variablelist remap='TP'> + <varlistentry> + <term>--aegis=PROJECT</term> + <listitem> +<para>Specifies the Aegis +<emphasis remap='I'>PROJECT</emphasis> +from which the +version(s) of +<emphasis remap='B'>scons</emphasis> +being timed will be extracted. +When +<option>--aegis</option> +is specified, the +<option>--number=</option><replaceable>NUMBER</replaceable> +option specifies delta numbers +that will be tested. +Output from each invocation run will be placed in file +names that match the Aegis delta numbers. +If the +<option>--number=</option> +option is not specified, +then the default behavior is to time the +tip of the specified +<emphasis remap='I'>PROJECT</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-f FILE, --file=FILE</term> + <listitem> +<para>Reads configuration information from the specified +<emphasis remap='I'>FILE</emphasis>. +This often provides a more convenient way to specify and +collect parameters associated with a specific timing configuration +than specifying them on the command line. +See the +<link linkend="configuration_file">CONFIGURATION FILE</link> +section below +for information about the configuration file parameters.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-h, --help</term> + <listitem> +<para>Displays help text for the +<emphasis remap='B'>scons-time run</emphasis> +subcommand.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-n, --no-exec</term> + <listitem> +<para>Do not execute commands, +just printing the command-line equivalents of what would be executed. +Note that the +<command>scons-time</command> +script actually executes its actions in Python, +where possible, +for portability. +The commands displayed are UNIX +<emphasis remap='I'>equivalents</emphasis> +of what it's doing.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>--number=NUMBER</term> + <listitem> +<para>Specifies the run number to be used in the names of +the log files and profile outputs generated by this run.</para> + </listitem> + </varlistentry> +</variablelist> + +<para>When used in conjuction with the +<option>--aegis=</option><replaceable>PROJECT</replaceable> +option, +<emphasis remap='I'>NUMBER</emphasis> +specifies one or more comma-separated Aegis delta numbers +that will be retrieved automatically from the specified Aegis +<emphasis remap='I'>PROJECT</emphasis>.</para> + +<para>When used in conjuction with the +<option>--svn=</option><replaceable>URL</replaceable> +option, +<emphasis remap='I'>NUMBER</emphasis> +specifies one or more comma-separated Subversion revision numbers +that will be retrieved automatically from the Subversion +repository at the specified +<emphasis remap='I'>URL</emphasis>. +Ranges of delta or revision numbers +may be specified be separating two numbers +with a hyphen +(<emphasis remap='B'>-</emphasis>).</para> + +<para>Example:</para> +<literallayout remap='.nf'> +% scons-time run --svn=<ulink url='http://scons.tigris.org/svn/trunk'>http://scons.tigris.org/svn/trunk</ulink> --num=1247,1249-1252 . +</literallayout> <!-- .fi --> +<variablelist remap='TP'> + <varlistentry> + <term>-p STRING, --prefix=STRING</term> + <listitem> +<para>Specifies the prefix string to be used for all of the log files +and profiles generated by this run. +The default is derived from the first +specified argument: +if the first argument is a directory, +the default prefix is the name of the directory; +if the first argument is an archive +(tar or zip file), +the default prefix is the the base name of the archive, +that is, what remains after stripping the archive suffix +(<markup>.tgz</markup>, <markup>.tar.gz</markup> or <markup>.zip</markup>).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>--python=PYTHON</term> + <listitem> +<para>Specifies a path to the Python executable to be used +for the timing runs. +The default is to use the same Python executable that +is running the +<command>scons-time</command> +command itself.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-q, --quiet</term> + <listitem> +<para>Suppresses display of the command lines being executed.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-s DIR, --subdir=DIR</term> + <listitem> +<para>Specifies the name of directory or subdirectory +from which the commands should be executed. +The default is XXX</para> + </listitem> + </varlistentry> + <varlistentry> + <term>--scons=SCONS</term> + <listitem> +<para>Specifies a path to the SCons script to be used +for the timing runs. +The default is XXX</para> + </listitem> + </varlistentry> + <varlistentry> + <term>--svn=URL, --subversion=URL</term> + <listitem> +<para>Specifies the +<emphasis remap='I'>URL</emphasis> +of the Subversion repository from which the +version(s) of +<emphasis remap='B'>scons</emphasis> +being timed will be extracted. +When +<option>--svn</option> +is specified, the +<option>--number=</option><replaceable>NUMBER</replaceable> +option specifies revision numbers +that will be tested. +Output from each invocation run will be placed in file +names that match the Subversion revision numbers. +If the +<option>--number=</option> +option is not specified, +then the default behavior is to time the +<emphasis remap='B'>HEAD</emphasis> +of the specified +<emphasis remap='I'>URL</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-v, --verbose</term> + <listitem> +<para>Displays the output from individual commands to the screen +(in addition to capturing the output in log files).</para> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> + </listitem> + </varlistentry> +</variablelist> +</refsect2> + +<refsect2 id='the_time_subcommand'><title>The time Subcommand</title> +<para><emphasis remap='B'>scons-time time</emphasis> +[<option>-h</option>] +[<option>--chdir=</option><replaceable>DIR</replaceable>] +[<option>-f </option><emphasis remap='I'>FILE</emphasis>] +[<option>--fmt=</option><replaceable>FORMAT</replaceable>] +[<option>-p </option><emphasis remap='I'>STRING</emphasis>] +[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>] +[<option>--title=</option><replaceable>TITLE</replaceable>] +[<option>--which=</option><replaceable>WHICH</replaceable>] +[<emphasis remap='I'>ARGUMENTS</emphasis>]</para> + +<para>The +<emphasis remap='B'>scons-time time</emphasis> +subcommand displays SCons execution times +as reported by the +<userinput>scons --debug=time</userinput> +option.</para> + +<para>The +<emphasis remap='B'>scons-time time</emphasis> +subcommand extracts SCons timing +from all the specified file arguments, +which should be files containing output from +running SCons with the +<option>--debug=time</option> +option. +(Normally, these would be +<emphasis remap='B'>*.log</emphasis> +files generated by the +<emphasis remap='B'>scons-time run</emphasis> +subcommand.) +All file name arguments will be +globbed for on-disk files.</para> + +<para>If no arguments are specified, +then execution timings +will be extracted from all +<emphasis remap='B'>*.log</emphasis> +files, +or the subset of them +with a prefix specified by the +<option>-p</option> +option.</para> +<variablelist remap='TP'> + <varlistentry> + <term>-C DIR, --chdir=DIR</term> + <listitem> +<para>Changes to the specified +<emphasis remap='I'>DIRECTORY</emphasis> +before looking for the specified files +(or files that match the specified patterns).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-f FILE, --file=FILE</term> + <listitem> +<para>Reads configuration information from the specified +<emphasis remap='I'>FILE</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-fmt=FORMAT, --format=FORMAT</term> + <listitem> +<para>Reports the output in the specified +<emphasis remap='I'>FORMAT</emphasis>. +The formats currently supported are +<emphasis remap='B'>ascii</emphasis> +(the default) +and +<emphasis remap='B'>gnuplot</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-h, --help</term> + <listitem> +<para>Displays help text for the +<emphasis remap='B'>scons-time time</emphasis> +subcommand.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-p STRING, --prefix=STRING</term> + <listitem> +<para>Specifies the prefix string for log files +from which to extract execution timings. +This will be used to search for log files +if no arguments are specified on the command line.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-t NUMBER, --tail=NUMBER</term> + <listitem> +<para>Only reports object counts from the last +<emphasis remap='I'>NUMBER</emphasis> +files.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>--which=WHICH</term> + <listitem> +<para>Prints the execution time for the specified +<emphasis remap='I'>WHICH</emphasis> +value: +<emphasis remap='B'>total</emphasis> +(the total execution time), +<emphasis remap='B'>SConscripts</emphasis> +(total execution time for the SConscript files themselves), +<emphasis remap='B'>SCons</emphasis> +(exectuion time in SCons code itself) +or +<emphasis remap='B'>commands</emphasis> +(execution time of the commands and other actions +used to build targets). +If no +<option>--which</option> +option is specified, +the default behavior is +<emphasis remap='B'>total</emphasis>, +which reports the total execution time for each run.</para> +<!-- '\"========================================================================== --> + </listitem> + </varlistentry> +</variablelist> +</refsect2> +</refsect1> + +<refsect1 id='configuration_file'><title>CONFIGURATION FILE</title> +<para>Various +<command>scons-time</command> +subcommands can read information from a specified +configuration file when passed the +<option>-f</option> +or +<option>--file</option> +options. +The configuration file is actually executed as a Python script. +Setting Python variables in the configuration file +controls the behavior of the +<command>scons-time</command> +script more conveniently than having to specify +command-line options or arguments for every run, +and provides a handy way to "shrink-wrap" +the necessary information for producing (and reporting) +consistent timing runs for a given configuration.</para> +<variablelist remap='TP'> + <varlistentry> + <term><emphasis remap='B'>aegis</emphasis></term> + <listitem> +<para>The Aegis executable for extracting deltas. +The default is simply +<emphasis remap='B'>aegis</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='B'>aegis_project</emphasis></term> + <listitem> +<para>The Aegis project from which deltas should be extracted. +The default is whatever is specified +with the +<option>--aegis=</option> +command-line option.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='B'>archive_list</emphasis></term> + <listitem> +<para>A list of archives (files or directories) +that will be copied to the temporary directory +in which SCons will be invoked. +<markup>.tar</markup>, +<markup>.tar.gz</markup>, +<markup>.tgz</markup> +and +<markup>.zip</markup> +files will have their contents unpacked in +the temporary directory. +Directory trees and files will be copied as-is.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='B'>initial_commands</emphasis></term> + <listitem> +<para>A list of commands that will be executed +before the actual timed +<emphasis remap='B'>scons</emphasis> +runs. +This can be used for commands that are necessary +to prepare the source tree-for example, +creating a configuration file +that should not be part of the timed run.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='B'>key_location</emphasis></term> + <listitem> +<para>The location of the key on Gnuplot graphing information +generated with the +<option>--format=gnuplot</option> +option. +The default is +<emphasis remap='B'>bottom left</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='B'>prefix</emphasis></term> + <listitem> +<para>The file name prefix to be used when +running or extracting timing for this configuration.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='B'>python</emphasis></term> + <listitem> +<para>The path name of the Python executable +to be used when running or extracting information +for this configuration. +The default is the same version of Python +used to run the SCons</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='B'>scons</emphasis></term> + <listitem> +<para>The path name of the SCons script to be used +when running or extracting information +for this configuration. +The default is simply +<emphasis remap='B'>scons</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='B'>scons_flags</emphasis></term> + <listitem> +<para>The +<emphasis remap='B'>scons</emphasis> +flags used when running SCons to collect timing information. +The default value is +<option>--debug=count --debug=memory --debug=time --debug=memoizer</option>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='B'>scons_lib_dir</emphasis></term> + <term><emphasis remap='B'>scons_wrapper</emphasis></term> + <term><emphasis remap='B'>startup_targets</emphasis></term> + <term><emphasis remap='B'>subdir</emphasis></term> + <listitem> +<para>The subdirectory of the project into which the +<command>scons-time</command> +script should change +before executing the SCons commands to time.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='B'>subversion_url</emphasis></term> + <listitem> +<para>The Subversion URL from</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='B'>svn</emphasis></term> + <listitem> +<para>The subversion executable used to +check out revisions of SCons to be timed. +The default is simple +<emphasis remap='B'>svn</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='B'>svn_co_flag</emphasis></term> + <term><emphasis remap='B'>tar</emphasis></term> + <term><emphasis remap='B'>targets</emphasis></term> + <listitem> +<para>A string containing the targets that should be added to +the command line of every timed +<emphasis remap='B'>scons</emphasis> +run. +This can be used to restrict what's being timed to a +subset of the full build for the configuration.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='B'>targets0</emphasis></term> + <term><emphasis remap='B'>targets1</emphasis></term> + <term><emphasis remap='B'>targets2</emphasis></term> + <term><emphasis remap='B'>title</emphasis></term> + <term><emphasis remap='B'>unzip</emphasis></term> + <term><emphasis remap='B'>verbose</emphasis></term> + <term><emphasis remap='B'>vertical_bars</emphasis></term> + <listitem> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> +<para></para> <!-- FIXME: blank list item --> + </listitem> + </varlistentry> +</variablelist> + +<refsect2 id='example'><title>Example</title> +<para>Here is an example +<command>scons-time</command> +configuration file +for a hypothetical sample project:</para> + +<literallayout remap='.nf'> +# The project doesn't use SCons natively (yet), so we're +# timing a separate set of SConscript files that we lay +# on top of the vanilla unpacked project tarball. +arguments = ['project-1.2.tgz', 'project-SConscripts.tar'] + +# The subdirectory name contains the project version number, +# so tell scons-time to chdir there before building. +subdir = 'project-1.2' + +# Set the prefix so output log files and profiles are named: +# project-000-[012].{log,prof} +# project-001-[012].{log,prof} +# etc. +prefix = 'project' + +# The SConscript files being tested don't do any SConf +# configuration, so run their normal ./configure script +# before we invoke SCons. +initial_commands = [ + './configure', +] + +# Only time building the bin/project executable. +targets = 'bin/project' + +# Time against SCons revisions of the branches/core branch +subversion_url = '<ulink url='http://scons.tigris.org/svn/scons/branches/core'>http://scons.tigris.org/svn/scons/branches/core</ulink>' +</literallayout> <!-- .fi --> +<!-- '\"========================================================================== --> +</refsect2> +</refsect1> + +<refsect1 id='environment'><title>ENVIRONMENT</title> +<para>The +<command>scons-time</command> +script uses the following environment variables:</para> +<variablelist remap='TP'> + <varlistentry> + <term><emphasis remap='B'>PRESERVE</emphasis></term> + <listitem> +<para>If this value is set, +the +<command>scons-time</command> +script will +<emphasis remap='I'>not</emphasis> +remove the temporary directory or directories +in which it builds the specified configuration +or downloads a specific version of SCons.</para> +<!-- '\"========================================================================== --> + </listitem> + </varlistentry> +</variablelist> +</refsect1> + +<refsect1 id='see_also'><title>SEE ALSO</title> +<para><citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +<citerefentry><refentrytitle>scons</refentrytitle><manvolnum>1</manvolnum></citerefentry></para> + +</refsect1> + +<refsect1 id='authors'><title>AUTHORS</title> +<para>Steven Knight <knight at baldmt dot com></para> +</refsect1> +</refentry> + |