summaryrefslogtreecommitdiff
path: root/docs/code-coverage.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/code-coverage.md')
-rw-r--r--docs/code-coverage.md95
1 files changed, 32 insertions, 63 deletions
diff --git a/docs/code-coverage.md b/docs/code-coverage.md
index 200a674bb0..3c4e226e0c 100644
--- a/docs/code-coverage.md
+++ b/docs/code-coverage.md
@@ -10,52 +10,28 @@ library on a local computer.
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.
+The tools used for code coverage are known to work on Ubuntu and Debian. They
+should work correctly on newer versions of Ubuntu, Debian 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.
+Previously, the code coverage scripts required specific versions of `lcov` and
+`llvm-cov` to be present. This is no longer true, so if you have no other need
+for them they can be removed. All of the required tools will be pulled into the
+Clang build tools directory by the script.
## 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.
+This step assumes that you have already checked out the PDFium source code. If
+you have not, please consult the Prerequisites section above.
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.
+command and adding `use_clang_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
@@ -67,23 +43,24 @@ existing `args.gn` as follows. If not using the default directory,
command.
```shell
-echo "use_coverage = true" >> out/Coverage/args.gn
+echo "use_clang_coverage = true" >> out/Coverage/args.gn
```
+Previous versions of code coverage used **use_coverage = true** in args.gn; this
+needs to be changed to **use_clang_coverage = true**
### Usage
Generating code coverage information is done via the
-`testing/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.
+`testing/tools/coverage/coverage_report.py` script. This script will download
+the Clang coverage tools if needed, build any binaries that it needs, perform
+test runs, collect coverage data, and generate a HTML coverage report. It is
+based on the Chromium coverage scripts, so will generate the same style of
+report.
-Running the script with no arguments, as below, will assume that you are
+Running the script with no arguments, as below, it 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.
+`./out/Coverage/` and that HTML should be outputted to `./coverage_report/`.
```shell
testing/tools/coverage/coverage_report.py
@@ -104,29 +81,21 @@ testing/tools/coverage/coverage_report.py \
--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
-testing/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`.
+To run different tests than the default set, including running just a single
+test, you can specify the test names on the command line. The list of supported
+tests can be found by running the script with `--help`.
-An example running the default tests explicitly:
+For example, running all of the tests that don't use pdfium_test:
```shell
testing/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.
+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. Alternatively,
+you can collect the profiling data that is generated from each run and manually
+invoke `tools/code_coverage/coverage.py` to generate a combined report.
There are additional developer debugging flags available, `--dry-run` and
`--verbose`. `--dry-run` will output a trace of commands that would have been