From 9e6c56eaa2369029deddbfb681c8750ac48e0946 Mon Sep 17 00:00:00 2001
From: Noah Jelich <12912633+njelich@users.noreply.github.com>
Date: Thu, 16 Jan 2025 08:24:52 -0800
Subject: [PATCH] Add AFL coverage instructions (#369)

---
 .github/.cspell/project-dictionary.txt |  1 +
 README.md                              | 19 +++++++++++++++++++
 2 files changed, 20 insertions(+)

diff --git a/.github/.cspell/project-dictionary.txt b/.github/.cspell/project-dictionary.txt
index df0cd03..e1e5994 100644
--- a/.github/.cspell/project-dictionary.txt
+++ b/.github/.cspell/project-dictionary.txt
@@ -10,6 +10,7 @@ fprofile
 instrprof
 libclang
 libhello
+LOOPCOUNT
 mcdc
 microkernel
 MSYSTEM
diff --git a/README.md b/README.md
index 56a04a7..c615c8b 100644
--- a/README.md
+++ b/README.md
@@ -21,6 +21,7 @@ This is a wrapper around rustc [`-C instrument-coverage`][instrument-coverage] a
   - [Merge coverages generated under different test conditions](#merge-coverages-generated-under-different-test-conditions)
   - [Get coverage of C/C++ code linked to Rust library/binary](#get-coverage-of-cc-code-linked-to-rust-librarybinary)
   - [Get coverage of external tests](#get-coverage-of-external-tests)
+  - [Get coverage of AFL fuzzers](#get-coverage-of-afl-fuzzers)
   - [Exclude file from coverage](#exclude-file-from-coverage)
   - [Exclude code from coverage](#exclude-code-from-coverage)
   - [Continuous Integration](#continuous-integration)
@@ -485,6 +486,24 @@ Note: To include coverage for doctests you also need to pass `--doctests` to bot
 > Invoke-Expression (cargo llvm-cov show-env --with-pwsh-env-prefix | Out-String)
 > ```
 
+### Get coverage of AFL fuzzers
+
+Cargo-llvm-cov can be used with [AFL.rs](https://github.com/rust-fuzz/afl.rs) similar to the way external tests are done, but with a few caveats.
+
+```sh
+# Set environment variables and clean workspace
+source <(cargo llvm-cov show-env --export-prefix)
+cargo llvm-cov clean --workspace
+# Build the fuzz target
+cargo afl build
+# Run the fuzzer, the AFL_FUZZER_LOOPCOUNT is needed, because otherwise .profraw files aren't emitted
+# To get coverage of current corpus, minimize it and set it as input, then run the fuzzer until it processes the corpus
+AFL_FUZZER_LOOPCOUNT=20 cargo afl fuzz -c - -i in -o out target/debug/fuzz-target
+# Generate report
+# If you pass `--release` to `cargo afl build`, you also need to pass `--release` to `cargo llvm-cov report`
+cargo llvm-cov report --lcov
+```
+
 ### Exclude file from coverage
 
 To exclude specific file patterns from the report, use the `--ignore-filename-regex` option.