<?xml version="1.0" encoding="UTF-8"?>
<refentry id="embuildstats">
  <refentryinfo>
    <productname>embuildstats</productname>
    <productnumber/>
  </refentryinfo>
  <refmeta>
    <refentrytitle>embuildstats</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class="source">EMDEBIAN-TOOLS</refmiscinfo>
    <refmiscinfo class="manual">EMDEBIAN-TOOLS</refmiscinfo>
  </refmeta>
  <refnamediv id="name">
    <refname>embuildstats</refname>
    <refpurpose>report tool to see an overview of your Emdebian builds</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>embuildstats</command>
      <group>
        <arg>-a</arg>
        <arg>--arch</arg>
      </group>
      <group>
        <arg>-v</arg>
        <arg>--verbose</arg>
      </group>
      <group>
        <arg>-q</arg>
        <arg>--quiet</arg>
      </group>
      <group>
        <arg>-p</arg>
        <arg>--pager</arg>
      </group>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>embuildstats</command>
      <group>
        <arg>-a</arg>
        <arg>--arch</arg>
      </group>
      <group>
        <arg>-v</arg>
        <arg>--verbose</arg>
      </group>
      <group>
        <arg>-q</arg>
        <arg>--quiet</arg>
      </group>
      <arg choice="req">-c|--csv</arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>embuildstats</command>
      <group>
        <arg>-a</arg>
        <arg>--arch</arg>
      </group>
      <group>
        <arg>-v</arg>
        <arg>--verbose</arg>
      </group>
      <group>
        <arg>-q</arg>
        <arg>--quiet</arg>
      </group>
      <arg choice="req">-x|--xml</arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>embuildstats</command>
      <group>
        <arg>-a</arg>
        <arg>--arch</arg>
      </group>
      <group>
        <arg>-v</arg>
        <arg>--verbose</arg>
      </group>
      <group>
        <arg>-q</arg>
        <arg>--quiet</arg>
      </group>
      <arg choice="req">-w|--html</arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>embuildstats</command>
      <group>
        <arg>-a</arg>
        <arg>--arch</arg>
      </group>
      <group>
        <arg>-v</arg>
        <arg>--verbose</arg>
      </group>
      <group>
        <arg>-q</arg>
        <arg>--quiet</arg>
      </group>
      <arg choice="req">-l|--lintian</arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1 id="description">
    <title>DESCRIPTION</title>
    <para>embuildstats checks your Emdebian work directory for emdebianised packages,
    build logs, .changes files and upload data and prepares a simple report.
    By default, the report is piped through <command>sensible-pager</command> but
    CSV, XML and HTML formats are also available.
    </para>
    <para>For more detailed information on a particular package, use
    <command>emsource</command> <option>--status</option> <userinput>PACKAGE</userinput>.
    </para>
    <para>For information on which source packages have new versions available,
    use <command>emtargetcmp</command>.</para>
    <para>Although error messages use the same colour output as other scripts in
    <emphasis>emdebian-tools</emphasis>, the report itself does not. If you would prefer
    alternative formats for the report, please ask (or submit a patch).
    </para>
    <para>The report columns (or tags) describe (left to right):
        </para>
    <orderedlist>
      <listitem>
        <para>Package name (source) in alphabetical order.</para>
      </listitem>
      <listitem>
        <para>Total number of emdebian patch files (including <filename>emdebian.*.patch</filename>
          and <filename>debian-patch.*.patch</filename> files). (Until Debian has a working
          implementation for translation packages - tdebs - the majority of these patches are to
          create the locale packages.)</para>
      </listitem>
      <listitem>
        <para>List of versions built with <command>emdebuild</command>. These versions are not
          necessarily successful builds, <command>embuildstats</command> just checks for the presence
          of a build log for this column. (See column 5.)</para>
      </listitem>
      <listitem>
        <para>List of versions built <emphasis>successfully</emphasis> with <command>empdebuild</command>
          (within an Emdebian chroot). These versions should be suitable for automated building.
          <command>embuildstats</command> checks for the presence of a build log and a
          <filename>.changes</filename> file for the same Emdebian version.</para>
      </listitem>
      <listitem>
        <para>List of versions with a <filename>.changes</filename> file for an Emdebian version.
          These are successful builds by <command>emdebuild</command>.</para>
      </listitem>
      <listitem>
        <para>List of versions of <filename>.changes</filename> files uploaded and the timestamp
          of the upload.
          </para>
      </listitem>
    </orderedlist>
  </refsect1>
  <refsect1 id="commands">
    <title>COMMANDS</title>
    <variablelist remap="TP">
      <varlistentry>
        <term><option>-p</option>|<option>--pager</option></term>
        <listitem>
          <para>Produce a tabular report and pipe to <command>sensible-pager</command>.
          Press '<userinput>q</userinput>' to quit. This is the default
          but the output cannot be redirected.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-c</option>|<option>--csv</option></term>
        <listitem>
          <para>Produce a report of comma separated values to <emphasis>STDOUT</emphasis>.
          The number of patch files is not included. Redirect to a file if preferred.
          </para>
          <programlisting>
"xdemineur"," 2.1.1-10em1"," 2.1.1-10em1"," 2.1.1-10em1 Tue Nov 27 20:13:58 2007"
          </programlisting>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-x</option>|<option>--xml</option></term>
        <listitem>
          <para>Produce an XML report to <emphasis>STDOUT</emphasis>.
          The number of patch files is not included. Redirect to a file if preferred.
          </para>
          <programlisting>
&lt;?xml version="1.0"?&gt;
&lt;stats&gt;
  &lt;package&gt;
   &lt;name&gt;package name&lt;/name&gt;
   &lt;build&gt;emdebuild version list&lt;/build&gt;
   &lt;changes&gt;empdebuild version list&lt;/changes&gt;
   &lt;uploads&gt;uploaded version with date&lt;/name&gt;
  &lt;/package&gt;
  &lt;package&gt;
   &lt;name&gt;package name&lt;/name&gt;
   &lt;build&gt;emdebuild version list&lt;/build&gt;
   &lt;changes&gt;empdebuild version list&lt;/changes&gt;
   &lt;uploads&gt;uploaded version with date&lt;/name&gt;
  &lt;/package&gt;
&lt;/stats&gt;
          </programlisting>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-w</option>|<option>--html</option></term>
        <listitem>
          <para>Produce a tabular report in HTML and print to <emphasis>STDOUT</emphasis>.
          Redirect to a file if preferred. (This is the same format as <option>--pager</option>
          wrapped in a basic HTML page and using <emphasis>&lt;pre&gt;</emphasis> for the
          table itself.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-l</option>|<option>--lintian</option></term>
        <listitem>
          <para>Identify the latest .changes file for each build and use lintian to
          check the packages against Emdebian Policy.
          </para>
          <para><emphasis>This can take a lot of time and work, even on a fast
          machine,</emphasis> depending on how many packages you have built locally.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1 id="options">
    <title>OPTIONS</title>
    <variablelist remap="TP">
      <varlistentry>
        <term><option>-a</option>|<option>--arch</option><replaceable> ARCH</replaceable></term>
        <listitem>
          <para>Produce a report for a specific architecture, overriding any <command>dpkg-cross</command>
        default.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-v</option>|<option>--verbose</option></term>
        <listitem>
          <para>be verbose - currently only used if there are errors.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-q</option>|<option>--quiet</option></term>
        <listitem>
          <para>be quiet (error messages only).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-h</option>|<option>--help</option></term>
        <listitem>
          <para>print the usage message and exit.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>--version</option>
        </term>
        <listitem>
          <para>print the usage message and exit.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1 id="files">
    <title>FILES</title>
    <para><command>embuildstats</command> uses your Emdebian work directory as the base for all
    searches. <command>emdebuild</command> stats are expected to be derived from <filename>$WORK/trunk/</filename>
    and <command>empdebuild</command> stats are expected to be derived from the
    <filename>$WORK/pbuilder/result/</filename> hierarchy. $WORK itself is defined by debconf for
    <emphasis>emdebian-tools</emphasis> or <filename>~/.apt-cross/emsource</filename>.</para>
  </refsect1>
  <refsect1>
    <title>Author</title>
    <para><command>embuildstats</command> was written
      by Neil Williams <email>codehelp@debian.org</email>.
    </para>
    <para>This  manual  page  was  written by Neil Williams
      <email>codehelp@debian.org</email>
    </para>
  </refsect1>
  <refsect1 id="embuildstatsseealso">
    <title>SEE ALSO</title>
    <para>See also <filename>emdebuild</filename> (1), <filename>empdebuild</filename> (1),
        <filename>emsource</filename> (1), <filename>emtargetcmp</filename> (1),
        <filename>dpkg-cross</filename> (1), <emphasis>emdebian-tools</emphasis> (1).
        </para>
  </refsect1>
</refentry>