doc: clarify and cleanup macOS fuzzing notes
What changed, and why it matters
This commit only edits documentation. It removes detailed macOS fuzzing setup instructions and replaces them with a note that macOS fuzzing is not officially supported, recommending Linux instead. No code, build scripts, or security behavior changed.
No security action needed. This is a documentation-only change.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff modifies doc/fuzzing.md only. It deletes the ‘macOS hints for libFuzzer’ section with brew/llvm/lld configuration steps and macOS-specific AFL++ hints, and adds a shorter ‘macOS notes’ section stating macOS fuzzing is not officially maintained and suggesting Linux/Docker/VMs. No source code, CMake presets, fuzz targets, or cryptographic logic is altered.
Changed components
doc/fuzzing.mdInspect captured patch +9 / −27
diff --git a/doc/fuzzing.md b/doc/fuzzing.md
index f4333a5b..564245b7 100644
--- a/doc/fuzzing.md
+++ b/doc/fuzzing.md
@@ -8,8 +8,6 @@ To quickly get started fuzzing Bitcoin Core using [libFuzzer](https://llvm.org/d
$ git clone https://github.com/bitcoin/bitcoin
$ cd bitcoin/
$ cmake --preset=libfuzzer
-# macOS users: If you have problem with this step then make sure to read "macOS hints for
-# libFuzzer" on https://github.com/bitcoin/bitcoin/blob/master/doc/fuzzing.md#macos-hints-for-libfuzzer
$ cmake --build build_fuzz
$ FUZZ=process_message build_fuzz/bin/fuzz
# abort fuzzing using ctrl-c
@@ -23,6 +21,9 @@ There is also a runner script to execute all fuzz targets. Refer to
For source-based coverage reports, see [developer notes](/doc/developer-notes.md#compiling-for-fuzz-coverage).
+macOS users: We recommend fuzzing on Linux, see [macOS notes](#macos-notes) for
+more information.
+
## Overview of Bitcoin Core fuzzing
[Google](https://github.com/google/fuzzing/) has a good overview of fuzzing in general, with contributions from key architects of some of the most-used fuzzers. [This paper](https://agroce.github.io/bitcoin_report.pdf) includes an external overview of the status of Bitcoin Core fuzzing, as of summer 2021. [John Regehr](https://blog.regehr.org/archives/1687) provides good advice on writing code that assists fuzzers in finding bugs, which is useful for developers to keep in mind.
@@ -183,29 +184,14 @@ There are 3 ways fuzz tests can be built:
tests would not be useful. This build is only useful for ensuring fuzz tests
compile and link.
-## macOS hints for libFuzzer
-
-The default Clang/LLVM version supplied by Apple on macOS does not include
-fuzzing libraries, so macOS users will need to install a full version, for
-example using `brew install llvm`.
-
-You may also need to take care of giving the correct path for `clang` and
-`clang++`, like `CC=/path/to/clang CXX=/path/to/clang++` if the non-systems
-`clang` does not come first in your path.
-
-Using `lld` is required due to issues with Apple's `ld` and `LLVM`.
+## macOS notes
-Full configuration step for macOS:
-
-```sh
-$ brew install llvm lld
-$ cmake --preset=libfuzzer \
- -DCMAKE_C_COMPILER="$(brew --prefix llvm)/bin/clang" \
- -DCMAKE_CXX_COMPILER="$(brew --prefix llvm)/bin/clang++" \
- -DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld"
-```
+Support for fuzzing on macOS is not officially maintained by this project. If
+you are running into issues on macOS, we recommend fuzzing on Linux instead for
+best results. On macOS this can be done within Docker or a virtual machine.
-Read the [libFuzzer documentation](https://llvm.org/docs/LibFuzzer.html) for more information. This [libFuzzer tutorial](https://github.com/google/fuzzing/blob/master/tutorial/libFuzzerTutorial.md) might also be of interest.
+Reproducing and debugging fuzz testcases on macOS is supported, by building the
+fuzz binary without support for any specific fuzzing engine.
# Fuzzing Bitcoin Core using afl++
@@ -225,10 +211,6 @@ $ cmake -B build_fuzz \
-DCMAKE_CXX_COMPILER="$(pwd)/AFLplusplus/afl-clang-lto++" \
-DBUILD_FOR_FUZZING=ON
$ cmake --build build_fuzz
-# For macOS you may need to ignore x86 compilation checks when running "cmake --build". If so,
-# try compiling using: AFL_NO_X86=1 cmake --build build_fuzz
-# Also, it might be required to run "afl-system-config" to adjust the shared
-# memory parameters.
$ mkdir -p inputs/ outputs/
$ echo A > inputs/thin-air-input
$ FUZZ=bech32 ./AFLplusplus/afl-fuzz -i inputs/ -o outputs/ -- build_fuzz/bin/fuzz
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.