doc: clarify and cleanup macOS fuzzing notes #33921

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

Closes #33731

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	darosior, brunoerg, frankomosh, rkrux, ismaelsadeeq
Concept NACK	l0rinc
Concept ACK	janb84

If your review is incorrectly listed, please copy-paste <code></code> into the comment that the bot should ignore.

in doc/fuzzing.md:11 in 6e37b3b486 outdated

   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?

dergoegge commented at 12:14 PM on November 24, 2025:

Done

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

dergoegge commented at 12:13 PM on November 24, 2025:

It's not related to mac, so I put it back in. Although I'm not sure how useful it is to document this here, as it is documented more accurately in the afl++ docs already.

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

  cmake --build build_fuzz_nosan -j$(nproc)
  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?

dergoegge commented at 12:15 PM on November 24, 2025:

Kept something similar in the quickstart section at the top.

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:

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

dergoegge commented at 12:14 PM on November 24, 2025:

This comment led me to remove the steps entirely. They'll just invite bike-shedding over what works for different people, which is partly what we're trying to avoid with this effort in the first place.

l0rinc commented at 12:24 PM on November 24, 2025:

This comment led me to remove the steps entirely

Hmmm, so what happened to "best effort"?

which is partly what we're trying to avoid with this effort in the first place

I thought we were aiming to provide Mac users a way to have at least basic fuzzing support.

maflcko commented at 12:31 PM on November 24, 2025:

I think it is fine to keep the libfuzzer-nosan command, but no strong opinion. Seems like it works without the extra flags for most people, and any extra flags can be added in the future, if there is need to.

l0rinc commented at 12:32 PM on November 24, 2025:

Wouldn't the version with extra flags work for even more people?

marcofleon commented at 12:35 PM on November 24, 2025:

This works on my mac M3:

cmake -B fuzzbuild \
   -DCMAKE_C_COMPILER="$(brew --prefix llvm)/bin/clang" \
   -DCMAKE_CXX_COMPILER="$(brew --prefix llvm)/bin/clang++" \
   -DCMAKE_BUILD_TYPE=Debug \
   -DBUILD_FOR_FUZZING=ON \
   -DSANITIZERS=fuzzer \
   -DAPPEND_LDFLAGS=-Wl,-no_warn_duplicate_libraries

I remember copying this from the original documentation when we transitioned to cmake (before the presets). It seems like everyone has their own way to make it work, so whatever we put here likely won't work for somebody. I'm fine with removing them completely or just documenting some "basic" command to get people started. Whoever really needs to fuzz on mac will figure it out.

marcofleon commented at 12:39 PM on November 24, 2025:

Although, I thought the point was to reduce the number of issues that were constantly being opened wrt to mac fuzzing. In that case, I think it would make the most sense to have no instructions at all, as anything we put there will invite future issues/PRs.

maflcko commented at 12:56 PM on November 24, 2025:

Yeah, no strong opinion. I just thought that the fuzzer+sanitizer version never worked on recent macOS versions, so removing it makes sense. Though, the libfuzzer-nosan worked for almost everyone, so it seems fine to keep. Having to deal with a pull/issue for that every few months seems fine, but I don't really expect a flood of those.

l0rinc commented at 1:17 PM on November 24, 2025:

Although, I thought the point was to reduce the number of issues that were constantly being opened wrt to mac fuzzing

Wasn't the point to actually do a best effort of solving their problem instead of just silencing the issues?

This works on my mac M3:

Can you show the exact command because this is missing at least a backslash. As mentioned, having the latest dependencies and running:

cmake -B fuzzbuild \
   -DCMAKE_C_COMPILER="$(brew --prefix llvm)/bin/clang" \
   -DCMAKE_CXX_COMPILER="$(brew --prefix llvm)/bin/clang++" \
   -DCMAKE_BUILD_TYPE=Debug \
   -DBUILD_FOR_FUZZING=ON \
   -DSANITIZERS=fuzzer \
   -DAPPEND_LDFLAGS=-Wl,-no_warn_duplicate_libraries && \
  cmake --build fuzzbuild -j$(nproc)

Fails with:

In file included from /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/malloc/_malloc.h:44:
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/malloc/_malloc_type.h:93:52: error: unknown type name 'size_t';
      did you mean 'std::size_t'?
   93 | void * __sized_by_or_null(size) malloc_type_malloc(size_t size, malloc_type_id_t type_id) __result_use_check __alloc_size(1);
      |                                                    ^
/opt/homebrew/Cellar/llvm/21.1.5/bin/../include/c++/v1/__cstddef/size_t.h:20:7: note: 'std::size_t' declared here                                                                                
   20 | using size_t = decltype(sizeof(int));
      |       ^

But adding the mentioned

-DCMAKE_OSX_SYSROOT="$(xcrun --show-sdk-path)" \
-DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld -L$(brew --prefix llvm)/lib/c++"

<details> <summary>Full command</summary>

rm -rfd fuzzbuild && \
cmake -B fuzzbuild \
 -DCMAKE_C_COMPILER="$(brew --prefix llvm)/bin/clang" \
 -DCMAKE_CXX_COMPILER="$(brew --prefix llvm)/bin/clang++" \
 -DCMAKE_OSX_SYSROOT="$(xcrun --show-sdk-path)" \
 -DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld -L$(brew --prefix llvm)/lib/c++" \
 -DCMAKE_BUILD_TYPE=Debug \
 -DBUILD_FOR_FUZZING=ON \
 -DSANITIZERS=fuzzer \
 -DAPPEND_LDFLAGS=-Wl,-no_warn_duplicate_libraries && \
cmake --build fuzzbuild -j$(nproc) && \
FUZZ=coins_view_db fuzzbuild/bin/fuzz

</details>

Makes it work again. It's not pretty, but it's how I understand "best-effort".

Can you please try if you can reproduce the above with latest xcode?

softwareupdate --install Xcode

marcofleon commented at 1:49 PM on November 24, 2025:

Sure, lgtm. As I said, I'm fine with including or not including a command for mac in the docs.

l0rinc commented at 2:08 PM on November 24, 2025:

Sure, lgtm

Thanks, let me know if you can reproduce the results above.

I'm fine with including or not including a command for mac in the docs.

I do feel strongly about having some kind of support for Macs, otherwise fuzzing will be even more of a black box as it is currently.

dergoegge commented at 11:02 AM on November 25, 2025:

I'm not going to add the steps back in. It's too much of a game of whack-a-mole which invites bike-shedding (what works for one person doesn't work for someone else, it depends on macOS version, brew version etc.) and it looks like people are perfectly capable of figuring out what works for them on their own.

l0rinc commented at 11:08 AM on November 25, 2025:

it depends on macOS version, brew version etc

What if we documented a solution that would work with latest xcode and clang and whatever else is needed? That shouldn't be too difficult and shouldn't involve "bike shedding" (I don't think it's the correct term here since it's not a "minor, easily understandable issues" at the expense of "neglecting more complex, important matters").

As mentioned, I strongly think we should have guidance for at least basic fuzzing support for Mac as well!

ismaelsadeeq commented at 4:26 PM on November 25, 2025:

I see your point @l0rinc but IMHO that should be in a separate PR? Tested independently and reviewed by contributors ensuring the guide works as expected. But prior to that we can merge this, and clear the ambiguity.

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

rkrux commented at 10:40 AM on November 24, 2025: contributor

ACK 6e37b3b4861733ca97ec5d27d0bf52d187b6a2c9

I do remember facing issues on Mac some time back that prompted me to create issue #33667.

Like mentioned in earlier couple comments, it'd be helpful to mention that Linux is recommended in the beginning "Quickstart guide" section.

doc: clarify and cleanup macOS fuzzing notes c34bc01b2f

dergoegge force-pushed on Nov 24, 2025

dergoegge commented at 12:16 PM on November 24, 2025: member

removed the macos steps (https://github.com/bitcoin/bitcoin/pull/33921#discussion_r2556067401)
added a reference to the macos notes section in the quickstart section

in doc/fuzzing.md:191 in c34bc01b2f

 206 | -   -DCMAKE_CXX_COMPILER="$(brew --prefix llvm)/bin/clang++" \
 207 | -   -DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld"
 208 | -```
 209 | +Support for fuzzing on macOS is not officially maintained by this project. If
 210 | +you are running into issues on macOS, we recommend fuzzing on Linux instead for
 211 | +best results. On macOS this can be done within Docker or a virtual machine.

janb84 commented at 1:41 PM on November 24, 2025:

NIT: non-blocking, maybe add nix-shell as an alternative because of native speed alternative.

best results. On macOS this can be done within Docker, a virtual machine or a nix-shell.

I'm running the fuzzer just fine on MacOS, Apple silicon in a nix-shell to the point that I'm actually questioning myself "am I doing it right?" seeing all the responses here and in #33731. ( Results are the same as a linux run, so i'm ok )

janb84 commented at 1:49 PM on November 24, 2025: contributor

Concept ACK c34bc01b2ff2fc91ed4020288c5fa15f0c5b075e

PR Changes fuzzng readme to nudge MacOS users to fuzz under linux.

Given the number of issues I think it's best to change the fuzzing.md to suggest the MacOS users to fuzz under Linux.

Have added small NIT given my personal experiences by using nix-shell to run the Fuzzing without trouble. (Not expecting that it will be added)

darosior approved

darosior commented at 3:16 PM on November 24, 2025: member

reACK c34bc01b2ff2fc91ed4020288c5fa15f0c5b075e

DrahtBot requested review from ismaelsadeeq on Nov 24, 2025

DrahtBot requested review from rkrux on Nov 24, 2025

DrahtBot requested review from janb84 on Nov 24, 2025

brunoerg approved

brunoerg commented at 4:06 PM on November 24, 2025: contributor

ACK c34bc01b2ff2fc91ed4020288c5fa15f0c5b075e

frankomosh commented at 5:47 AM on November 25, 2025: contributor

ACK c34bc01

rkrux commented at 10:31 AM on November 25, 2025: contributor

ACK c34bc01b2ff2fc91ed4020288c5fa15f0c5b075e

l0rinc commented at 11:21 AM on November 25, 2025: contributor

Concept ACK, I agree that we should clarify usage of fuzzing on a Mac.

However, approach NACK, as described in #33921 (review) (which was marked as resolved for some reason, so reposting here for visibility)

ismaelsadeeq commented at 4:22 PM on November 25, 2025: member

reACK c34bc01b2ff2fc91ed4020288c5fa15f0c5b075e

I think recommending to fuzz using docker is a good idea.

fanquake merged this on Nov 25, 2025

fanquake closed this on Nov 25, 2025

l0rinc commented at 5:12 PM on November 25, 2025: contributor

@fanquake, what was the urgency to merge here?