<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE refentry 
  PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="cutter">
<refmeta>
  <refentrytitle role="top_of_page" id="cutter.top_of_page">cutter</refentrytitle>
  <refmiscinfo>CUTTER Library</refmiscinfo>
</refmeta>
<refnamediv>
  <refname>cutter</refname>
  <refpurpose>xUnit family unit testing framework for C and C++</refpurpose>
</refnamediv>
<refsect1>
  <title>NAME</title>
  <para>cutter - xUnit family unit testing framework for C and C++</para>
</refsect1>

<refsect1>
  <title>SYNOPSIS</title>
  <para>
  <code>cutter</code>
   [
  <emphasis>option ...</emphasis>
  ] 
  <emphasis>test-directory</emphasis>
  
</para>
  <para>
  <code>cutter</code>
   --mode=analyze [
  <emphasis>option ...</emphasis>
  ] 
  <emphasis>log-directory</emphasis>
  
</para>
</refsect1>

<refsect1>
  <title>DESCRIPTION</title>
  <para>Cutter is a xUnit family unit testing framework for C and C++. Cutter provides programmers two important interfaces:</para>
  <orderedlist>
  <listitem>
  <para>easy to write API</para>
</listitem>
  <listitem>
  <para>easy to debug UI</para>
</listitem>
</orderedlist>
  <para>Cutter helps programmers to write their new tests, run their existing tests, get feedbacks from ran their tests.</para>
  <para>
  <emphasis>test-directory</emphasis>
   is a directory which has test_*.so. test_*.so are searched recursively.
</para>
  <para>
  <emphasis>log-directory</emphasis>
   is a directory which has Cutter log files. Cutter logs test results when --stream-directory option is specified.
</para>
</refsect1>

<refsect1>
  <title>OPTIONS</title>
  <variablelist>
  <varlistentry>
  <term id="cutter.--version">--version</term>
  <listitem>
  <para>Cutter shows its own version and exits.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.--mode">--mode=[test|analyze]</term>
  <listitem>
  <para>It specifies run mode. Cutter runs tests when run mode is test. Cutter analyzes test results when run mode is analyze.</para>
  <para>The default is test.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.-s">-s DIRECTORY, --source-directory=DIRECTORY</term>
  <listitem>
  <para>Cutter prepends DIRECTORY to file name when test fails. This is for tolls (like Emacs) which have function jumping to error line.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.-t">-t TEST_CASE_NAME, --test-case=TEST_CASE_NAME</term>
  <listitem>
  <para>Cutter runs test cases that are matched with TEST_CASE_NAME. If TEST_CASE_NAME is surrounded by &quot;/&quot; (e.g. /test_/), TEST_CASE_NAME is handled as regular expression.</para>
  <para>This option can be specified n times. In the case, Cutter runs test cases that are matched with any TEST_CASE_NAME. (OR)</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.-n">-n TEST_NAME, --name=TEST_NAME</term>
  <listitem>
  <para>Cutter runs tests that are matched with TEST_NAME. If TEST_NAME is surrounded by &quot;/&quot; (e.g. /test_/), TEST_NAME is handled as regular expression.</para>
  <para>This option can be specified n times. In the case, Cutter runs test that are matched with any TEST_NAME. (OR)</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.-m">-m, --multi-thread</term>
  <listitem>
  <para>Cutter runs a test case in a new thread.</para>
  <para>The default is off.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.--max-threads">--max-threads=MAX_THREADS</term>
  <listitem>
  <para>Run test cases and iterated tests with MAX_THREADS threads concurrently at a maximum. -1 means no limit.</para>
  <para>The default is 10.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.--disable-signal-handling">--disable-signal-handling</term>
  <listitem>
  <para>Disable signal handling that provides aborting test by C-c, provides backtrace on SEGV and so on. If your test target uses signal, Cutter's signal handling may cause a problem. In the case, you should disable Cutter's signal handling by this option.</para>
  <para>The default is enabled.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.--test-case-order">--test-case-order=[none|name|name-desc]</term>
  <listitem>
  <para>It specifies test case order.</para>
  <para>If 'none' is specified, Cutter doesn't sort. If 'name' is specified, Cutter sorts test cases by name in ascending order. If 'name-desc' is specified, Cutter sorts test cases by name in descending order.</para>
  <para>The default is none.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.--exclude-file">--exclude-file=FILE</term>
  <listitem>
  <para>Cutter doesn't read FILE on test collecting.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.--exclude-directory">--exclude-directory=DIRECTORY</term>
  <listitem>
  <para>Cutter doesn't search tests under DIRECTORY.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.--fatal-failures">--fatal-failures</term>
  <listitem>
  <para>Cutter treats failures as fatal problem. It means that Cutter stops test run.</para>
  <para>The default is off.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.--keep-opening-modules">--keep-opening-modules</term>
  <listitem>
  <para>Cutter keeps opening loaded modules to resolve symbols for debugging.</para>
  <para>The default is off.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.--enable-convenience-attribute-definition">--enable-convenience-attribute-definition</term>
  <listitem>
  <para>It enables convenience but danger &quot;#{ATTRIBUTE_NAME}_#{TEST_NAME - 'test_' PREFIX}&quot; attribute set function.</para>
  <para>The default is off.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.--stop-before-test">--stop-before-test</term>
  <listitem>
  <para>It sets a breakpoint immediately before each test. You can dive into test function easily by running cutter on your debugger and stepping into the next function.</para>
  <para>The default is off.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.-u">-u[console|gtk], --ui=[console|gtk]</term>
  <listitem>
  <para>It specifies UI.</para>
  <para>The default is console UI.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.-v">-v[s|silent|n|normal|v|verbose], --verbose=[s|silent|n|normal|v|verbose]</term>
  <listitem>
  <para>It specifies verbose level.</para>
  <para>This option is only for console UI.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.-c">-c[yes|true|no|false|auto], --color=[yes|true|no|false|auto]</term>
  <listitem>
  <para>If 'yes' or 'true' is specified, Cutter uses colorized output by escape sequence. If 'no' or 'false' is specified, Cutter never use colorized output. If 'auto' or the option is omitted, Cutter uses colorized output if available.</para>
  <para>This option is only for console UI.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.--pdf-report">--pdf-report=FILE</term>
  <listitem>
  <para>Cutter outputs a test report to FILE as PDF format.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.--xml-report">--xml-report=FILE</term>
  <listitem>
  <para>Cutter outputs a test report to FILE as XML format.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.--stream">--stream=[xml]</term>
  <listitem>
  <para>It specifies stream backend. Stream backend streams test results.</para>
  <para>There is only XML stream backend for now.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.--stream-fd">--stream-fd=FILE_DESCRIPTOR</term>
  <listitem>
  <para>It specifies output file descriptor. The XML stream backend streams to FILE_DESCRIPTOR.</para>
  <para>This option is only for XML stream backend.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.--stream-directory">--stream-directory=DIRECTORY</term>
  <listitem>
  <para>It specifies output directory. The XML stream backend streams to a file under DIRECTORY.</para>
  <para>This option is only for XML stream backend.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.--question">-?, --help</term>
  <listitem>
  <para>Cutter shows common options.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.--help-stream">--help-stream</term>
  <listitem>
  <para>Cutter shows stream related options.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.--help-report">--help-report</term>
  <listitem>
  <para>Cutter shows report related options.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.--help-ui">--help-ui</term>
  <listitem>
  <para>Cutter shows UI related options.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="cutter.--help-all">--help-all</term>
  <listitem>
  <para>Cutter shows all options.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1>
  <title>EXIT STATUS</title>
  <para>The exit status is 0 if all tests are passed and non-0 otherwise.  Omission test result and notification test result are not treated as failure.</para>
</refsect1>

<refsect1>
  <title>FILES</title>
  <variablelist>
  <varlistentry>
  <term id="cutter./usr/local/share/doc/cutter/">/usr/local/share/doc/cutter/</term>
  <listitem>
  <para>The directory has Cutter documents. e.g. reference manual, tutorial and so on.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1>
  <title>EXAMPLE</title>
  <para>In the following example, cutter runs tests under tests/ directory and shows test progress verbosely.</para>
  <programlisting>% cutter -v v test/</programlisting>
  <para>In the following example, test results are saved under logs/ directory:</para>
  <programlisting>% cutter --stream=xml --stream-directory=logs/ test/</programlisting>
</refsect1>

<refsect1>
  <title>SEE ALSO</title>
  <para>GLib's reference manual.</para>
</refsect1>
</refentry>
