diff options
Diffstat (limited to 'doc/man/scons-time.xml')
| -rw-r--r-- | doc/man/scons-time.xml | 1284 |
1 files changed, 1284 insertions, 0 deletions
diff --git a/doc/man/scons-time.xml b/doc/man/scons-time.xml new file mode 100644 index 0000000..026c24d --- /dev/null +++ b/doc/man/scons-time.xml @@ -0,0 +1,1284 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- lifted from troff+man by doclifter --> +<refentry id='sconstime1' + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<!-- Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation --> + +<!-- 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. --> + +<!-- doc/man/scons-time.xml 2014/03/02 14:18:15 garyo --> + +<!-- 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'>March 2014</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 role="bold">scons-time run</emphasis> +[<option>-hnqv</option>] +[<option>--aegis=</option><replaceable>PROJECT</replaceable>] +[<option>-f </option><emphasis>FILE</emphasis>] +[<option>--number=</option><replaceable>NUMBER</replaceable>] +[<option>--outdir=</option><replaceable>OUTDIR</replaceable>] +[<option>-p </option><emphasis>STRING</emphasis>] +[<option>--python=</option><replaceable>PYTHON</replaceable>] +[<option>-s </option><emphasis>DIR</emphasis>] +[<option>--scons=</option><replaceable>SCONS</replaceable>] +[<option>--svn=</option><replaceable>URL</replaceable>] +[<emphasis>ARGUMENTS</emphasis>]</para> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> + +<refsect2 id='extracting_function_timings'><title>Extracting Function Timings</title> +<para><emphasis role="bold">scons-time func</emphasis> +[<option>-h</option>] +[<option>--chdir=</option><replaceable>DIR</replaceable>] +[<option>-f </option><emphasis>FILE</emphasis>] +[<option>--fmt=</option><replaceable>FORMAT</replaceable>] +[<option>--func=</option><replaceable>NAME</replaceable>] +[<option>-p </option><emphasis>STRING</emphasis>] +[<option>-t </option><emphasis>NUMBER</emphasis>] +[<option>--title= TITLE</option>] +[<emphasis>ARGUMENTS</emphasis>]</para> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> +</refsect2> + +<refsect2 id='extracting_memory_statistics'><title>Extracting Memory Statistics</title> +<para><emphasis role="bold">scons-time mem</emphasis> +[<option>-h</option>] +[<option>--chdir=</option><replaceable>DIR</replaceable>] +[<option>-f </option><emphasis>FILE</emphasis>] +[<option>--fmt=</option><replaceable>FORMAT</replaceable>] +[<option>-p </option><emphasis>STRING</emphasis>] +[<option>--stage=</option><replaceable>STAGE</replaceable>] +[<option>-t </option><emphasis>NUMBER</emphasis>] +[<option>--title=</option><replaceable>TITLE</replaceable>] +[<emphasis>ARGUMENTS</emphasis>]</para> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> +</refsect2> + +<refsect2 id='extracting_object_counts'><title>Extracting Object Counts</title> +<para><emphasis role="bold">scons-time obj</emphasis> +[<option>-h</option>] +[<option>--chdir=</option><replaceable>DIR</replaceable>] +[<option>-f </option><emphasis>FILE</emphasis>] +[<option>--fmt=</option><replaceable>FORMAT</replaceable>] +[<option>-p </option><emphasis>STRING</emphasis>] +[<option>--stage=</option><replaceable>STAGE</replaceable>] +[<option>-t </option><emphasis>NUMBER</emphasis>] +[<option>--title=</option><replaceable>TITLE</replaceable>] +[<emphasis>ARGUMENTS</emphasis>]</para> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> +</refsect2> + +<refsect2 id='extracting_execution_times'><title>Extracting Execution Times</title> +<para><emphasis role="bold">scons-time time</emphasis> +[<option>-h</option>] +[<option>--chdir=</option><replaceable>DIR</replaceable>] +[<option>-f </option><emphasis>FILE</emphasis>] +[<option>--fmt=</option><replaceable>FORMAT</replaceable>] +[<option>-p </option><emphasis>STRING</emphasis>] +[<option>-t </option><emphasis>NUMBER</emphasis>] +[<option>--title=</option><replaceable>TITLE</replaceable>] +[<option>--which=</option><replaceable>WHICH</replaceable>] +[<emphasis>ARGUMENTS</emphasis>]</para> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> +</refsect2> + +<refsect2 id='help_text'><title>Help Text</title> +<para><emphasis role="bold">scons-time help</emphasis> +<emphasis>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 role="bold">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 role="bold">scons-time func</emphasis> +subcommand), +total memory used +(the +<emphasis role="bold">scons-time mem</emphasis> +subcommand), +object counts +(the +<emphasis role="bold">scons-time obj</emphasis> +subcommand) +and overall execution time +(the +<emphasis role="bold">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 role="bold">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 committed 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 role="bold">scons-time run</emphasis> +subcommand +<emphasis>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>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 role="bold">scons-time run</emphasis> +to profile it against a specific configuration; +make another change to SCons; +run +<emphasis role="bold">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> + <varlistentry> + <term>-h, --help</term> + <listitem> +<para>Displays the global help text and exits, +identical to the +<emphasis role="bold">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 role="bold">scons-time func</emphasis> +[<option>-h</option>] +[<option>--chdir=</option><replaceable>DIR</replaceable>] +[<option>-f </option><emphasis>FILE</emphasis>] +[<option>--fmt=</option><replaceable>FORMAT</replaceable>] +[<option>--func=</option><replaceable>NAME</replaceable>] +[<option>-p </option><emphasis>STRING</emphasis>] +[<option>-t </option><emphasis>NUMBER</emphasis>] +[<option>--title= TITLE</option>] +[<emphasis>ARGUMENTS</emphasis>]</para> + +<para>The +<emphasis role="bold">scons-time func</emphasis> +subcommand displays timing information +for a specific Python function within SCons. +By default, it extracts information about the +<emphasis role="bold">_main</emphasis>() +function, +which includes the Python profiler timing +for all of SCons.</para> + +<para>The +<emphasis role="bold">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 role="bold">*.prof</emphasis> +files generated by the +<emphasis role="bold">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 role="bold">*.prof</emphasis> +files, +or the subset of them +with a prefix specified by the +<option>-p</option> +option.</para> + +<para>Options include:</para> +<variablelist> + <varlistentry> + <term>-C DIRECTORY, --chdir=DIRECTORY</term> + <listitem> +<para>Changes to the specified +<emphasis>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>FILE</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-fmt=FORMAT, --format=FORMAT</term> + <listitem> +<para>Reports the output in the specified +<emphasis>FORMAT</emphasis>. +The formats currently supported are +<emphasis role="bold">ascii</emphasis> +(the default) +and +<emphasis role="bold">gnuplot</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>--func=NAME</term> + <listitem> +<para>Extracts timings for the specified function +<emphasis>NAME</emphasis>. +The default is to report cumulative timings for the +<emphasis role="bold">_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 role="bold">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>NUMBER</emphasis> +files.</para> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> + </listitem> + </varlistentry> +</variablelist> +</refsect2> + +<refsect2 id='the_help_subcommand'><title>The help Subcommand</title> +<para><emphasis role="bold">scons-time help</emphasis> +<emphasis>SUBCOMMAND</emphasis> +[...] +The +<emphasis role="bold">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 role="bold">scons-time mem</emphasis> +[<option>-h</option>] +[<option>--chdir=</option><replaceable>DIR</replaceable>] +[<option>-f </option><emphasis>FILE</emphasis>] +[<option>--fmt=</option><replaceable>FORMAT</replaceable>] +[<option>-p </option><emphasis>STRING</emphasis>] +[<option>--stage=</option><replaceable>STAGE</replaceable>] +[<option>-t </option><emphasis>NUMBER</emphasis>] +[<option>--title=</option><replaceable>TITLE</replaceable>] +[<emphasis>ARGUMENTS</emphasis>]</para> + +<para>The +<emphasis role="bold">scons-time mem</emphasis> +subcommand displays how much memory SCons uses.</para> + +<para>The +<emphasis role="bold">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 role="bold">*.log</emphasis> +files generated by the +<emphasis role="bold">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 role="bold">*.log</emphasis> +files, +or the subset of them +with a prefix specified by the +<option>-p</option> +option.</para> + +<variablelist> + <varlistentry> + <term>-C DIR, --chdir=DIR</term> + <listitem> +<para>Changes to the specified +<emphasis>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>FILE</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-fmt=FORMAT, --format=FORMAT</term> + <listitem> +<para>Reports the output in the specified +<emphasis>FORMAT</emphasis>. +The formats currently supported are +<emphasis role="bold">ascii</emphasis> +(the default) +and +<emphasis role="bold">gnuplot</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-h, --help</term> + <listitem> +<para>Displays help text for the +<emphasis role="bold">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>STAGE</emphasis>: +<emphasis role="bold">pre-read</emphasis> +(before the SConscript files are read), +<emphasis role="bold">post-read ,</emphasis> +(after the SConscript files are read), +<emphasis role="bold">pre-build</emphasis> +(before any targets are built) +or +<emphasis role="bold">post-build</emphasis> +(after any targets are built). +If no +<option>--stage</option> +option is specified, +the default behavior is +<emphasis role="bold">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>NUMBER</emphasis> +files.</para> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> + </listitem> + </varlistentry> +</variablelist> +</refsect2> + +<refsect2 id='the_obj_subcommand'><title>The obj Subcommand</title> +<para><emphasis role="bold">scons-time obj</emphasis> +[<option>-h</option>] +[<option>--chdir=</option><replaceable>DIR</replaceable>] +[<option>-f </option><emphasis>FILE</emphasis>] +[<option>--fmt=</option><replaceable>FORMAT</replaceable>] +[<option>-p </option><emphasis>STRING</emphasis>] +[<option>--stage=</option><replaceable>STAGE</replaceable>] +[<option>-t </option><emphasis>NUMBER</emphasis>] +[<option>--title=</option><replaceable>TITLE</replaceable>] +[<emphasis>ARGUMENTS</emphasis>]</para> + +<para>The +<emphasis role="bold">scons-time obj</emphasis> +subcommand displays how many objects of a specific named type +are created by SCons.</para> + +<para>The +<emphasis role="bold">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 role="bold">*.log</emphasis> +files generated by the +<emphasis role="bold">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 role="bold">*.log</emphasis> +files, +or the subset of them +with a prefix specified by the +<option>-p</option> +option.</para> +<variablelist> + <varlistentry> + <term>-C DIR, --chdir=DIR</term> + <listitem> +<para>Changes to the specified +<emphasis>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>FILE</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-fmt=FORMAT, --format=FORMAT</term> + <listitem> +<para>Reports the output in the specified +<emphasis>FORMAT</emphasis>. +The formats currently supported are +<emphasis role="bold">ascii</emphasis> +(the default) +and +<emphasis role="bold">gnuplot</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-h, --help</term> + <listitem> +<para>Displays help text for the +<emphasis role="bold">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>STAGE</emphasis>: +<emphasis role="bold">pre-read</emphasis> +(before the SConscript files are read), +<emphasis role="bold">post-read ,</emphasis> +(after the SConscript files are read), +<emphasis role="bold">pre-build</emphasis> +(before any targets are built) +or +<emphasis role="bold">post-build</emphasis> +(after any targets are built). +If no +<option>--stage</option> +option is specified, +the default behavior is +<emphasis role="bold">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>NUMBER</emphasis> +files.</para> +<!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> + </listitem> + </varlistentry> +</variablelist> +</refsect2> + +<refsect2 id='the_run_subcommand'><title>The run Subcommand</title> +<para><emphasis role="bold">scons-time run</emphasis> +[<option>-hnqv</option>] +[<option>--aegis=</option><replaceable>PROJECT</replaceable>] +[<option>-f </option><emphasis>FILE</emphasis>] +[<option>--number=</option><replaceable>NUMBER</replaceable>] +[<option>--outdir=</option><replaceable>OUTDIR</replaceable>] +[<option>-p </option><emphasis>STRING</emphasis>] +[<option>--python=</option><replaceable>PYTHON</replaceable>] +[<option>-s </option><emphasis>DIR</emphasis>] +[<option>--scons=</option><replaceable>SCONS</replaceable>] +[<option>--svn=</option><replaceable>URL</replaceable>] +[<emphasis>ARGUMENTS</emphasis>] +The +<emphasis role="bold">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 role="bold">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 role="bold">scons-time run</emphasis> +subcommand runs the +requested version of SCons +against the configuration +three times:</para> +<variablelist> + <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 role="bold">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 role="bold">scons-time run</emphasis> +subcommand supports the following options:</para> +<variablelist> + <varlistentry> + <term>--aegis=PROJECT</term> + <listitem> +<para>Specifies the Aegis +<emphasis>PROJECT</emphasis> +from which the +version(s) of +<emphasis role="bold">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>PROJECT</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-f FILE, --file=FILE</term> + <listitem> +<para>Reads configuration information from the specified +<emphasis>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 role="bold">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>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 conjunction with the +<option>--aegis=</option><replaceable>PROJECT</replaceable> +option, +<emphasis>NUMBER</emphasis> +specifies one or more comma-separated Aegis delta numbers +that will be retrieved automatically from the specified Aegis +<emphasis>PROJECT</emphasis>.</para> + +<para>When used in conjunction with the +<option>--svn=</option><replaceable>URL</replaceable> +option, +<emphasis>NUMBER</emphasis> +specifies one or more comma-separated Subversion revision numbers +that will be retrieved automatically from the Subversion +repository at the specified +<emphasis>URL</emphasis>. +Ranges of delta or revision numbers +may be specified be separating two numbers +with a hyphen +(<emphasis role="bold">-</emphasis>).</para> + +<para>Example:</para> +<literallayout class="monospaced"> +% 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> + <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>URL</emphasis> +of the Subversion repository from which the +version(s) of +<emphasis role="bold">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 role="bold">HEAD</emphasis> +of the specified +<emphasis>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 role="bold">scons-time time</emphasis> +[<option>-h</option>] +[<option>--chdir=</option><replaceable>DIR</replaceable>] +[<option>-f </option><emphasis>FILE</emphasis>] +[<option>--fmt=</option><replaceable>FORMAT</replaceable>] +[<option>-p </option><emphasis>STRING</emphasis>] +[<option>-t </option><emphasis>NUMBER</emphasis>] +[<option>--title=</option><replaceable>TITLE</replaceable>] +[<option>--which=</option><replaceable>WHICH</replaceable>] +[<emphasis>ARGUMENTS</emphasis>]</para> + +<para>The +<emphasis role="bold">scons-time time</emphasis> +subcommand displays SCons execution times +as reported by the +<userinput>scons --debug=time</userinput> +option.</para> + +<para>The +<emphasis role="bold">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 role="bold">*.log</emphasis> +files generated by the +<emphasis role="bold">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 role="bold">*.log</emphasis> +files, +or the subset of them +with a prefix specified by the +<option>-p</option> +option.</para> +<variablelist> + <varlistentry> + <term>-C DIR, --chdir=DIR</term> + <listitem> +<para>Changes to the specified +<emphasis>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>FILE</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-fmt=FORMAT, --format=FORMAT</term> + <listitem> +<para>Reports the output in the specified +<emphasis>FORMAT</emphasis>. +The formats currently supported are +<emphasis role="bold">ascii</emphasis> +(the default) +and +<emphasis role="bold">gnuplot</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>-h, --help</term> + <listitem> +<para>Displays help text for the +<emphasis role="bold">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>NUMBER</emphasis> +files.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>--which=WHICH</term> + <listitem> +<para>Prints the execution time for the specified +<emphasis>WHICH</emphasis> +value: +<emphasis role="bold">total</emphasis> +(the total execution time), +<emphasis role="bold">SConscripts</emphasis> +(total execution time for the SConscript files themselves), +<emphasis role="bold">SCons</emphasis> +(exectuion time in SCons code itself) +or +<emphasis role="bold">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 role="bold">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> + <varlistentry> + <term><emphasis role="bold">aegis</emphasis></term> + <listitem> +<para>The Aegis executable for extracting deltas. +The default is simply +<emphasis role="bold">aegis</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis role="bold">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 role="bold">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 role="bold">initial_commands</emphasis></term> + <listitem> +<para>A list of commands that will be executed +before the actual timed +<emphasis role="bold">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 role="bold">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 role="bold">bottom left</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis role="bold">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 role="bold">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 role="bold">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 role="bold">scons</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis role="bold">scons_flags</emphasis></term> + <listitem> +<para>The +<emphasis role="bold">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 role="bold">scons_lib_dir</emphasis></term> + <term><emphasis role="bold">scons_wrapper</emphasis></term> + <term><emphasis role="bold">startup_targets</emphasis></term> + <term><emphasis role="bold">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 role="bold">subversion_url</emphasis></term> + <listitem> +<para>The Subversion URL from</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis role="bold">svn</emphasis></term> + <listitem> +<para>The subversion executable used to +check out revisions of SCons to be timed. +The default is simple +<emphasis role="bold">svn</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis role="bold">svn_co_flag</emphasis></term> + <term><emphasis role="bold">tar</emphasis></term> + <term><emphasis role="bold">targets</emphasis></term> + <listitem> +<para>A string containing the targets that should be added to +the command line of every timed +<emphasis role="bold">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 role="bold">targets0</emphasis></term> + <term><emphasis role="bold">targets1</emphasis></term> + <term><emphasis role="bold">targets2</emphasis></term> + <term><emphasis role="bold">title</emphasis></term> + <term><emphasis role="bold">unzip</emphasis></term> + <term><emphasis role="bold">verbose</emphasis></term> + <term><emphasis role="bold">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 class="monospaced"> +# 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> + <varlistentry> + <term><emphasis role="bold">PRESERVE</emphasis></term> + <listitem> +<para>If this value is set, +the +<command>scons-time</command> +script will +<emphasis>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> + |