<?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.--log-level'>--log-level=LEVEL</term>
  <listitem>
  <para>It sets log level to LEVEL.</para>
  <para>LEVEL can be combined them with &#39;|&#39; like &quot;error|warning&quot;.</para>
  <para>You can add a level to the default level by prepending &quot;+&quot; to level like &quot;+trace|+info&quot;.</para>
  <para>You can remove a level from the default level by prepending &quot;-&quot; to level like &quot;-error|-warning&quot;.</para>
  <para>Here are available levels:</para>
  <itemizedlist>
  <listitem>
  <para>default: equals to &quot;critical|error|warning|message&quot;.</para>
</listitem>
  <listitem>
  <para>none: logs nothing.</para>
</listitem>
  <listitem>
  <para>critical: logs only critial information.</para>
</listitem>
  <listitem>
  <para>error: logs only error information.</para>
</listitem>
  <listitem>
  <para>warning: logs only warning information.</para>
</listitem>
  <listitem>
  <para>message: logs only normal messages.</para>
</listitem>
  <listitem>
  <para>info: logs only additional information.</para>
</listitem>
  <listitem>
  <para>debug: logs only debug information.</para>
</listitem>
  <listitem>
  <para>traces: logs only trace information.</para>
</listitem>
  <listitem>
  <para>all: logs all log information.</para>
</listitem>
</itemizedlist>
  <para>The default is &quot;default&quot;.</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&#39;s signal handling may cause a problem. In the case, you should disable Cutter&#39;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 &#39;none&#39; is specified, Cutter doesn&#39;t sort. If &#39;name&#39; is specified, Cutter sorts test cases by name in ascending order. If &#39;name-desc&#39; 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&#39;t read FILE on test collecting.</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id='cutter.--exclude-directory'>--exclude-directory=DIRECTORY</term>
  <listitem>
  <para>Cutter doesn&#39;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 - &#39;test_&#39; 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 &#39;yes&#39; or &#39;true&#39; is specified, Cutter uses colorized output by escape sequence. If &#39;no&#39; or &#39;false&#39; is specified, Cutter never use colorized output. If &#39;auto&#39; 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&#39;s reference manual.</para>
</refsect1>
</refentry>
