⚗️ trying fastcov

test/thirdparty/fastcov/README.md

@@ -0,0 +1,46 @@
+# fastcov
+A massively parallel gcov wrapper for generating intermediate coverage formats *fast*
+
+The goal of fastcov is to generate code coverage intermediate formats *as fast as possible* (ideally < 1 second), even for large projects with hundreds of gcda objects. The intermediate formats may then be consumed by a report generator such as lcov's genhtml, or a dedicated front end such as coveralls. fastcov was originally designed to be a drop-in replacement for lcov (application coverage only, not kernel coverage).
+
+Currently the only intermediate formats supported are gcov json format and lcov info format. Adding support for other formats should require just a few lines of python to transform gcov json format to the desired shape.
+
+In order to achieve the massive speed gains, a few constraints apply:
+
+1. GCC version >= 9.0.0
+
+These versions of GCOV have support for JSON intermediate format as well as streaming report data straight to stdout
+
+2. Object files must be either be built:
+
+- Using absolute paths for all `-I` flags passed to the compiler
+- Invoking the compiler from the same root directory
+
+If you use CMake, you are almost certainly satisfying the second constraint (unless you care about `ExternalProject` coverage).
+
+## Sample Usage:
+```bash
+$ cd build_dir
+$ fastcov.py --zerocounters
+$ <run unit tests>
+$ fastcov.py --exclude /usr/include --lcov -o report.info
+$ genhtml -o code_coverage report.info
+```
+
+## Legacy fastcov
+
+It is possible to reap most of the benefits of fastcov for GCC version < 9.0.0 and >= 7.1.0. However, there will be a *potential* header file loss of correctness.
+
+`fastcov_legacy.py` can be used with pre GCC-9 down to GCC 7.1.0 but with a few penalties due to gcov limitations. This is because running gcov in parallel generates .gcov header reports in parallel which overwrite each other. This isn't a problem unless your header files have actual logic (i.e. header only library) that you want to measure coverage for. Use the `-F` flag to specify which gcda files should not be run in parallel in order to capture accurate header file data just for those. I don't plan on supporting `fastcov_legacy.py` aside from basic bug fixes.
+
+## Benchmarks
+
+Anecdotal testing on my own projects indicate that fastcov is over 100x faster than lcov and over 30x faster than gcovr:
+
+Project Size: ~250 .gcda, ~500 .gcov generated by gcov
+
+Time to process all gcda and parse all gcov:
+
+- fastcov: ~700ms
+- lcov:    ~90s
+- gcovr:   ~30s