1--- 2layout: default 3title: Code coverage 4parent: Advanced topics 5nav_order: 2 6permalink: /advanced-topics/code-coverage/ 7--- 8 9# Code Coverage 10{: .no_toc} 11 12For projects written in C/C++, Rust, Go, Swift or Java and other JVM-based languages, 13you can generate code coverage reports using Clang source-based code coverage. 14This page walks you through the basic steps. 15For more details on C/C++ coverage, see [Clang's documentation]. 16 17Code coverage reports generation for other languages is not supported yet. 18 19- TOC 20{:toc} 21--- 22 23## Pull the latest Docker images 24 25Docker images get regularly updated with a newer version of build tools, build 26configurations, scripts, and other changes. We recommend you pull the most 27recent images by running the following command: 28 29```bash 30$ python infra/helper.py pull_images 31``` 32 33## Build fuzz targets 34 35Code coverage report generation requires a special build configuration to be 36used. To create a code coverage build for your project, run these commands: 37 38```bash 39$ python infra/helper.py build_image $PROJECT_NAME 40$ python infra/helper.py build_fuzzers --sanitizer=coverage $PROJECT_NAME 41``` 42 43## Establish access to GCS 44 45To get a good understanding of fuzz testing quality, you should generate code 46coverage reports by running fuzz targets against the corpus 47aggregated by OSS-Fuzz. Set up `gsutil` and ensure that you have access to the 48corpora by doing the following: 49 50* Install the [gsutil tool]. 51* Check whether you have access to the corpus for your project: 52 53```bash 54$ gsutil ls gs://${PROJECT_NAME}-corpus.clusterfuzz-external.appspot.com/ 55``` 56 57If you see an authorization error from the command above, run this: 58 59```bash 60$ gcloud auth login 61``` 62 63and try again. Once `gsutil` works, you can run the report generation. 64 65## Generate code coverage reports 66 67### Full project report 68 69If you want to generate a code coverage report using the corpus aggregated on 70OSS-Fuzz, run this command: 71 72```bash 73$ python infra/helper.py coverage $PROJECT_NAME 74``` 75 76If you want to generate a code coverage report using the corpus you have 77locally, copy the corpus into the 78`build/corpus/$PROJECT_NAME/<fuzz_target_name>/` directories for each fuzz 79target, then run this command: 80 81```bash 82$ python infra/helper.py coverage --no-corpus-download $PROJECT_NAME 83``` 84 85### Single fuzz target 86 87You can generate a code coverage report for a particular fuzz target by using 88the `--fuzz-target` argument: 89 90```bash 91$ python infra/helper.py coverage --fuzz-target=<fuzz_target_name> $PROJECT_NAME 92``` 93 94In this mode, you can specify an arbitrary corpus location for the fuzz target 95(instead of the corpus downloaded from OSS-Fuzz) by using `--corpus-dir`: 96 97```bash 98$ python infra/helper.py coverage --fuzz-target=<fuzz_target_name> \ 99 --corpus-dir=<my_local_corpus_dir> $PROJECT_NAME 100``` 101 102### Additional arguments for `llvm-cov` (C/C++ only) 103 104You may want to use some of the options provided by the [llvm-cov tool], like 105`-ignore-filename-regex=`. You can pass these to the helper script after `--`: 106 107```bash 108$ python infra/helper.py coverage $PROJECT_NAME -- \ 109 -ignore-filename-regex=.*code/to/be/ignored/.* <other_extra_args> 110``` 111 112If you want to specify particular source files or directories to show in the 113report, list their paths at the end of the extra arguments sequence: 114 115```bash 116$ python infra/helper.py coverage zlib -- \ 117 <other_extra_args> /src/zlib/inftrees.c /src/zlib_uncompress_fuzzer.cc /src/zlib/zutil.c 118``` 119 120If you want OSS-Fuzz to use extra arguments when generating code coverage 121reports for your project, add the arguments into your `project.yaml` file as 122follows: 123 124```yaml 125coverage_extra_args: -ignore-filename-regex=.*crc.* -ignore-filename-regex=.*adler.* <other_extra_args> 126``` 127 128[Clang's documentation]: https://clang.llvm.org/docs/SourceBasedCodeCoverage.html 129[gsutil tool]: https://cloud.google.com/storage/docs/gsutil_install 130[llvm-cov tool]: https://llvm.org/docs/CommandGuide/llvm-cov.html 131