diff options
Diffstat (limited to 'docs/code-coverage.md')
| -rw-r--r-- | docs/code-coverage.md | 95 |
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 |