Add some details to the llvm-cov documentation. <rdar://problem/15819496>

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@208098 91177308-0d34-0410-b5e6-96231b3b80d8

docs/CommandGuide/llvm-cov.rst

@@ -4,32 +4,115 @@ llvm-cov - emit coverage information
 SYNOPSIS
 --------
 
-:program:`llvm-cov` [-gcno=filename] [-gcda=filename] [dump]
+:program:`llvm-cov` [options] SOURCEFILE
 
 DESCRIPTION
 -----------
 
-The experimental :program:`llvm-cov` tool reads in description file generated
-by compiler and coverage data file generated by instrumented program.  This
-program assumes that the description and data file uses same format as gcov
-files.
+The :program:`llvm-cov` tool reads code coverage data files and displays the
+coverage information for a specified source file. It is compatible with the
+``gcov`` tool from version 4.2 of ``GCC`` and may also be compatible with
+some later versions of ``gcov``.
+
+To use llvm-cov, you must first build an instrumented version of your
+application that collects coverage data as it runs. Compile with the
+``-fprofile-arcs`` and ``-ftest-coverage`` options to add the
+instrumentation. (Alternatively, you can use the ``--coverage`` option, which
+includes both of those other options.) You should compile with debugging
+information (``-g``) and without optimization (``-O0``); otherwise, the
+coverage data cannot be accurately mapped back to the source code.
+
+At the time you compile the instrumented code, a ``.gcno`` data file will be
+generated for each object file. These ``.gcno`` files contain half of the
+coverage data. The other half of the data comes from ``.gcda`` files that are
+generated when you run the instrumented program, with a separate ``.gcda``
+file for each object file. Each time you run the program, the execution counts
+are summed into any existing ``.gcda`` files, so be sure to remove any old
+files if you do not want their contents to be included.
+
+By default, the ``.gcda`` files are written into the same directory as the
+object files, but you can override that by setting the ``GCOV_PREFIX`` and
+``GCOV_PREFIX_STRIP`` environment variables. The ``GCOV_PREFIX_STRIP``
+variable specifies a number of directory components to be removed from the
+start of the absolute path to the object file directory. After stripping those
+directories, the prefix from the ``GCOV_PREFIX`` variable is added. These
+environment variables allow you to run the instrumented program on a machine
+where the original object file directories are not accessible, but you will
+then need to copy the ``.gcda`` files back to the object file directories
+where llvm-cov expects to find them.
+
+Once you have generated the coverage data files, run llvm-cov for each main
+source file where you want to examine the coverage results. This should be run
+from the same directory where you previously ran the compiler. The results for
+the specified source file are written to a file named by appending a ``.gcov``
+suffix. A separate output file is also created for each file included by the
+main source file, also with a ``.gcov`` suffix added.
+
+The basic content of an llvm-cov output file is a copy of the source file with
+an execution count and line number prepended to every line. The execution
+count is shown as ``-`` if a line does not contain any executable code. If
+a line contains code but that code was never executed, the count is displayed
+as ``#####``.
+
 
 OPTIONS
 -------
 
-.. option:: -gcno=filename
+.. option:: -a, --all-blocks
 
- This option selects input description file generated by compiler while
- instrumenting program.
+ Display all basic blocks. If there are multiple blocks for a single line of
+ source code, this option causes llvm-cov to show the count for each block
+ instead of just one count for the entire line.
 
-.. option:: -gcda=filename
+.. option:: -b, --branch-probabilities
 
- This option selects coverage data file generated by instrumented compiler.
+ Display conditional branch probabilities and a summary of branch information. 
 
-.. option:: -dump
+.. option:: -c, --branch-counts
 
- This options enables output dump that is suitable for a developer to help
- debug :program:`llvm-cov` itself.
+ Display branch counts instead of probabilities (requires -b).
+
+.. option:: -f, --function-summaries
+
+ Show a summary of coverage for each function instead of just one summary for
+ an entire source file.
+
+.. option:: --help
+
+ Display available options (--help-hidden for more).
+
+.. option:: -l, --long-file-names
+
+ For coverage output of files included from the main source file, add the
+ main file name followed by ``##`` as a prefix to the output file names. This
+ can be combined with the --preserve-paths option to use complete paths for
+ both the main file and the included file.
+
+.. option:: -o=<DIR|FILE>, --object-directory=<DIR>, --object-file=<FILE>
+
+ Find objects in DIR or based on FILE's path. If you specify a particular
+ object file, the coverage data files are expected to have the same base name
+ with ``.gcno`` and ``.gcda`` extensions. If you specify a directory, the
+ files are expected in that directory with the same base name as the source
+ file.
+
+.. option:: -p, --preserve-paths
+
+ Preserve path components when naming the coverage output files. In addition
+ to the source file name, include the directories from the path to that
+ file. The directories are separate by ``#`` characters, with ``.`` directories
+ removed and ``..`` directories replaced by ``^`` characters. When used with
+ the --long-file-names option, this applies to both the main file name and the
+ included file name.
+
+.. option:: -u, --unconditional-branches
+
+ Include unconditional branches in the output for the --branch-probabilities
+ option.
+
+.. option:: -version
+
+ Display the version of llvm-cov.
 
 EXIT STATUS
 -----------