Add documentation for code coverage support

BUG=pdfium:797

Change-Id: I70d1b2260db1f71b018505aaeca617c5366d9ae5
Reviewed-on: https://pdfium-review.googlesource.com/8050
Commit-Queue: Ryan Harrison <rharrison@chromium.org>
Reviewed-by: Tom Sepez <tsepez@chromium.org>
Reviewed-by: Henrique Nakashima <hnakashima@chromium.org>

1 files changed, 152 insertions, 0 deletions

diff --git a/docs/code-coverage.md b/docs/code-coverage.md
new file mode 100644
index 0000000000..3162b5886c
--- /dev/null
+++ b/docs/code-coverage.md
@@ -0,0 +1,152 @@
+# Code Coverage Support for PDFium
+
+[TOC]
+
+This guide explains how to generate code coverage information for the PDFium
+library on a local computer.
+
+## Prerequisites
+
+You will need the PDFium source code on your computer. You can see
+the [README](/README.md) for instructions on checking out PDFium's source.
+
+The tools used for code coverage are known to work on Ubuntu 14.04. They should
+work correctly on newer versions of Ubuntu and related Linux distros. They have
+not been tested on Windows and Mac.
+
+### lcov
+
+The code coverage scripts depend on having a version of `lcov` of 1.11 or
+greater available, which is enforced by the script. Unfortunately the default
+version of `lcov` for Ubuntu 14.04 is 1.10, thus you will need to install a
+newer version.
+
+You can build a newer version of `lcov` from source, which is
+available [here](http://ltp.sourceforge.net/coverage/lcov.php).
+
+If you don't want to build from source and use an RPM based Linux, not
+Ubuntu/Debian, then there are pre-built RPMs
+available [here](http://downloads.sourceforge.net/ltp/lcov-1.13-1.noarch.rpm).
+
+For Ubuntu/Debian users these RPMs can be converted to .deb using `alien`. More
+information about how to do this can be found in `man alien`.
+
+### llvm-cov
+
+The other external dependency for generating code coverage information is having
+a version of `llvm-cov` that supports the `gcov` command. This should be all
+versions of 3.5.0 or greater.
+
+Again, unfortunately, the default llvm-cov that comes with Ubuntu 14.04, 3.4, is
+lower then what is needed. The 14.04 repositories do support having multiple
+versions of the `llvm` package, and thus `llvm-cov`. Through your favourite
+package manager you should be able to install any version of `llvm` of 3.5 or
+greater and the coverage scripts should find it.
+
+## Generating Code Coverage
+
+### Setup
+
+This step assumes that you have already checked out the PDFium source code and
+installed the proper versions of the external tools. If you have not, please
+consult the above Prerequisites section.
+
+Before generating code coverage information, you will need to have a build
+directory with coverage enabled. This can be done by running the `gn args`
+command and adding `use_coverage = true` in the editor that is opened. If not
+using the default directory, `out/Coverage`, then replace it with the correct
+location in the following command.
+
+```shell
+gn args out/Coverage
+```
+
+If you already have a build directory, you can append the coverage flag to the
+existing `args.gn` as follows. If not using the default directory,
+`out/Coverage`, then replace it with the correct location in the following
+command.
+
+```shell
+echo "use_coverage = true" >> out/Coverage/args.gn
+```
+
+
+### Usage
+
+Generating code coverage information is done via the
+`tools/coverage/coverage_report.py` script. This script will build any binaries
+that it needs, perform test runs, collect coverage data, and finally generate a
+nice HTML coverage report.
+
+Running the script with no arguments, as below, will assume that you are
+currently at the root of your PDFium checkout, the build directory to use is
+`./out/Coverage/` and that HTML should be outputted to `./coverage_report/`. By
+default, it will also only run `pdfium_unittests` and `pdfium_embeddertests` for
+coverage data. This is because the other tests are known to take a long time to
+run, so they are not included in the defaults.
+
+```shell
+tools/coverage/coverage_report.py
+```
+
+If the current working directory is not the root of your PDFium checkout, then
+you will need to pass in `--source-directory` with the appropriate directory. If
+you are using a different build directory, then `--build-directory` will need to
+be passed in. Finally, if you want the HTML report in a different location then
+you will need to pass in `--output-directory`.
+
+An example of all these flags being used:
+
+```shell
+coverage_report.py --source-directory ~/pdfium/pdfium \
+                   --build-directory ~/pdfium/pdfium/out/Debug_with_Coverage \
+                   --output-directory ~/Documents/PDFium_coverage
+```
+
+To run different tests then the default set, there are two ways to achieve
+this. If you want to run everything, including tests that are known to take a
+long time, then you just need to add the `--slow` flag.
+
+```shell
+tools/coverage/coverage_report.py --slow
+```
+
+If you want more fine grained control, including running just a single test, you
+can specify the test names on the command line. The `--slow` flag is not needed
+if you are explicitly invoking tests. The list of supported tests can be found
+by running the script with `--help`.
+
+An example running the default tests explicitly:
+
+```shell
+tools/coverage/coverage_report.py pdfium_unittests pdfium_embeddertests
+```
+
+NOTE:
+At the present time, there is no mechanism for combining data from different
+invocations of `coverage_report.py`. Instead you must specify all of the tests
+to be included in the report in a single invocation.
+
+There are additional developer debugging flags available, `--dry-run` and
+`--verbose`. `--dry-run` will output a trace of commands that would have been
+run, but doesn't actually execute them. `--verbose` turns on outputting
+additional logging information.
+
+### Viewing
+
+Once the script has run, the output directory should contain a set of HTML files
+containing the coverage report.
+
+These files are static HTML, so you can point your browser at them directly on
+your local file system and they should render fine. You can also serve them via a
+web server if you want, but how to achieve that is beyond the scope of this
+documentation.
+
+## Issues
+
+For help with using the code coverage tools please contact the PDFium
+maintainers via the PDFium
+mailing [list](https://groups.google.com/forum/#!forum/pdfium).
+
+Please file bugs against the code coverage
+support [here](https://bugs.chromium.org/p/pdfium/issues/list).