doc: clarify and cleanup macOS fuzzing notes #33921

pull dergoegge wants to merge 1 commits into bitcoin:master from dergoegge:2025-11-fuzzing-docs changing 1 files +10 −22

dergoegge commented at 2:29 pm on November 21, 2025: member
- Remove or consolidate macOS notes sprinkled throughout the doc into dedicated section
- Note that support for fuzzing on macOS is not maintained
- Provide best effort steps for fuzzing macOS
Closes #33731
doc: clarify and cleanup macOS fuzzing notes 6e37b3b486
DrahtBot added the label Docs on Nov 21, 2025
DrahtBot commented at 2:29 pm on November 21, 2025: contributor
The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/33921.

Reviews

See the guideline for information on the review process.

Type Reviewers

ACK ismaelsadeeq, darosior

Concept ACK l0rinc, brunoerg

If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

LLM Linter (✨ experimental)

Possible typos and grammar issues:
- provided on best effort basis -> provided on a best-effort basis [missing article “a” and standard phrasing uses “best-effort” as a compound adjective]
drahtbot_id_5_m

Type	Reviewers
ACK	ismaelsadeeq, darosior
Concept ACK	l0rinc, brunoerg

in doc/fuzzing.md:11 in 6e37b3b486

 7@@ -8,8 +8,6 @@ To quickly get started fuzzing Bitcoin Core using [libFuzzer](https://llvm.org/d
 8 $ git clone https://github.com/bitcoin/bitcoin
 9 $ cd bitcoin/
10 $ cmake --preset=libfuzzer
11-# macOS users: If you have problem with this step then make sure to read "macOS hints for

l0rinc commented at 2:34 pm on November 21, 2025:

can we specify in the beginning that we recommend linux and still provide the link to the mac section?

in doc/fuzzing.md:235 in 6e37b3b486

224-# Also, it might be required to run "afl-system-config" to adjust the shared
225-# memory parameters.
226 $ mkdir -p inputs/ outputs/
227 $ echo A > inputs/thin-air-input
228 $ FUZZ=bech32 ./AFLplusplus/afl-fuzz -i inputs/ -o outputs/ -- build_fuzz/bin/fuzz
229-# You may have to change a few kernel parameters to test optimally - afl-fuzz

l0rinc commented at 2:35 pm on November 21, 2025:

is this removal related to the mac cleanup? it seems this was before the Mac section originally https://github.com/bitcoin/bitcoin/commit/33dd764984def9371f324d3add19ee894a0260bf#diff-7ff2e1d1ed59fa96766a663236d71bfdd00b4af3321fde39f7dbf022bd968a0aL87-L88

in doc/fuzzing.md:194 in 6e37b3b486

197+Reproducing and debugging fuzz testcases on macOS is supported, by building the
198+fuzz binary without support for any specific fuzzing engine.
199 
200-Using `lld` is required due to issues with Apple's `ld` and `LLVM`.
201+You may still be able to fuzz on macOS using the following steps (provided on
202+best effort basis, only aimed at the latest macOS version, may be outdated):

maflcko commented at 2:37 pm on November 21, 2025:

provided on best effort basis -> provided on a best-effort basis [missing article "a" and standard phrasing uses "best-effort" as a compound adjective]

in doc/fuzzing.md:201 in 6e37b3b486

208 $ brew install llvm lld
209-$ cmake --preset=libfuzzer \
210+$ cmake --preset=libfuzzer-nosan \
211    -DCMAKE_C_COMPILER="$(brew --prefix llvm)/bin/clang" \
212    -DCMAKE_CXX_COMPILER="$(brew --prefix llvm)/bin/clang++" \
213    -DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld"

l0rinc commented at 2:37 pm on November 21, 2025:

since this is an alternative to the above linux one and since the build directory is changed now, should we add

0  cmake --build build_fuzz_nosan -j$(nproc)
1  FUZZ=coins_view_db build_fuzz_nosan/bin/fuzz

after this?

in doc/fuzzing.md:15 in 6e37b3b486
maflcko commented at 2:38 pm on November 21, 2025:

I think the note can be kept and moved here in this line?
maflcko approved
maflcko commented at 2:40 pm on November 21, 2025: member

lgtm. makes sense to just mention the stuff that is known to work and remove the stuff that is known to not work

in doc/fuzzing.md:198 in 6e37b3b486

205-
206-```sh
207+```
208 $ brew install llvm lld
209-$ cmake --preset=libfuzzer \
210+$ cmake --preset=libfuzzer-nosan \

l0rinc commented at 2:45 pm on November 21, 2025:

As described in #32084 (comment) this doesn’t seem to be enough for me, I’m getting a lot of failures locally on my non-intel-based Mac. It needs a few more parameters to avoid being tangled with local AppleClang:

0cmake --preset=libfuzzer-nosan \
1   -DCMAKE_C_COMPILER="$(brew --prefix llvm)/bin/clang" \
2   -DCMAKE_CXX_COMPILER="$(brew --prefix llvm)/bin/clang++" \
3   -DCMAKE_OSX_SYSROOT="$(xcrun --show-sdk-path)" \
4   -DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld -L$(brew --prefix llvm)/lib/c++"

l0rinc changes_requested
l0rinc commented at 2:47 pm on November 21, 2025: contributor

Concept ACK, but if we claim best-effort, we should cover the M series as well with latest AppleClang and latest LLVM.
ismaelsadeeq approved
ismaelsadeeq commented at 4:07 pm on November 21, 2025: member

ACK 6e37b3b4861733ca97ec5d27d0bf52d187b6a2c9
DrahtBot requested review from l0rinc on Nov 21, 2025
brunoerg commented at 6:02 pm on November 21, 2025: contributor

Concept ACK
darosior approved
darosior commented at 8:35 pm on November 21, 2025: member

ACK 6e37b3b4861733ca97ec5d27d0bf52d187b6a2c9

nit: i think it would be good to have a sentence that fuzzing support is only maintained for Linux platforms as the first line of the document, so readers know what to expect. It’s fine if it’s also repeated in the “MacOS notes” section.
DrahtBot requested review from brunoerg on Nov 21, 2025

Contributors
dergoegge DrahtBot l0rinc maflcko ismaelsadeeq brunoerg darosior

Review Requested
l0rinc brunoerg

Labels
Docs

doc: clarify and cleanup macOS fuzzing notes #33921

Code Coverage & Benchmarks

Reviews

LLM Linter (✨ experimental)