clients/drcov/drcov.dox

/* **********************************************************
 * Copyright (c) 2013-2014 Google, Inc.  All rights reserved.
 * **********************************************************/

/*
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * * Redistributions of source code must retain the above copyright notice,
 *   this list of conditions and the following disclaimer.
 *
 * * Redistributions in binary form must reproduce the above copyright notice,
 *   this list of conditions and the following disclaimer in the documentation
 *   and/or other materials provided with the distribution.
 *
 * * Neither the name of Google, Inc. nor the names of its contributors may be
 *   used to endorse or promote products derived from this software without
 *   specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL GOOGLE, INC. OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 * DAMAGE.
 */

/**
***************************************************************************
***************************************************************************
\page page_drcov Code Coverage Tool

\p drcov is a DynamoRIO client tool that collects code coverage information.
 - \ref sec_drcov
 - \ref sec_drcov2lcov

\section sec_drcov The Code Coverage Client

The DynamoRIO tool \p drcov collects information about which basic blocks
have been executed.  It writes the results to a separate log file per process.

The runtime options for this tool include:
 - \b -dump_text:
    Dumps the log file in text format.
 - \b -dump_binary:
    On by default, dumps the log file in binary format.
 - \b -\[no_\]nudge_kills:
    Windows only. On by default.
    Uses nudge to notify the process for termination
    so that the exit event will be called.
 - \b -logdir dir:
    Sets log directory, which by default is ".".

\section sec_drcov2lcov Post-Processing

A post-processing tool \p drcov2lcov is provided to convert binary log files
generated by the drcov client to the lcov format.
The resulting files can be processed by
<a href="http://ltp.sourceforge.net/coverage/lcov.php">lcov</a>.

A help message about how to use drcov2lcov can be obtained by running
drcov2lcov with no arguments:
\code
drcov2lcov
usage: drcov2lcov [options]
      --help                          Print this message.
      --verbose <int>                 Verbose level.
      --warning <int>                 Warning level.
      --list <input list file>        The file with a list of drcov files to be processed.
      --dir <input directory>         The directory with all drcov.*.log files to be processed.
      --output <output file>          The output file.
      --mod_filter <module filter>    Only process the module whose path contains the filter string.
      --src_filter <source filter>    Only process the source file whose path contains the filter string.
      --reduce_set <reduce_set file>  Find a smaller set of log files from the inputs that have the same code coverage and write those file paths into <reduce_set file>.
\endcode

*/