doc: update fuzz instructions when on macOS #31954

m3dwards commented at 8:45 PM on February 25, 2025: contributor

Fixes: #31049

Updates the instructions for fuzzing on macOS to use lld instead of ld.

Tested instructions on M1 Mac running 14.6.1

DrahtBot commented at 8:45 PM on February 25, 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/31954.

Reviews

See the guideline for information on the review process.

Type	Reviewers
ACK	l0rinc, brunoerg, hebasto
Concept ACK	jonatack
Stale ACK	Prabhat1308

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

DrahtBot added the label Docs on Feb 25, 2025

maflcko added the label macOS on Feb 25, 2025

jonatack commented at 10:57 PM on February 25, 2025: member

Concept ACK

Prabhat1308 commented at 4:12 AM on February 26, 2025: none

Running the build after these configurations on MacOs 15.3.1 M4 Pro, the fuzz tests are running but I do get these warnings on almost every object being built . Is this expected ?

4 warnings generated.
[ 12%] Linking CXX static library libbitcoin_cli.a
4 warnings generated.
[ 12%] Building CXX object src/test/fuzz/util/CMakeFiles/test_fuzz.dir/net.cpp.o
[ 12%] Built target bitcoin_cli
[ 12%] Building CXX object src/CMakeFiles/bitcoin_common.dir/base58.cpp.o
clang++: warning: argument unused during compilation: '-fuse-ld=lld' [-Wunused-command-line-argument]
clang++: warning: argument unused during compilation: '-fstack-clash-protection' [-Wunused-command-line-argument]
warning: unknown warning option '-Wduplicated-branches' [-Wunknown-warning-option]
warning: unknown warning option '-Wduplicated-cond' [-Wunknown-warning-option]
warning: unknown warning option '-Wlogical-op'; did you mean '-Wlong-long'? [-Wunknown-warning-option]
warning: unknown warning option '-Wbidi-chars=any' [-Wunknown-warning-option]
4 warnings generated.
clang++: warning: argument unused during compilation: '-fuse-ld=lld' [-Wunused-command-line-argument]
clang++: warning: argument unused during compilation: '-fstack-clash-protection' [-Wunused-command-line-argument]
warning: unknown warning option '-Wduplicated-branches' [-Wunknown-warning-option]
warning: unknown warning option '-Wduplicated-cond' [-Wunknown-warning-option]
warning: unknown warning option '-Wlogical-op'; did you mean '-Wlong-long'? [-Wunknown-warning-option]
warning: unknown warning option '-Wbidi-chars=any' [-Wunknown-warning-option]
[ 13%] Building CXX object src/CMakeFiles/bitcoin_consensus.dir/primitives/block.cpp.o
clang++: warning: argument unused during compilation: '-fuse-ld=lld' [-Wunused-command-line-argument]
clang++: warning: argument unused during compilation: '-fstack-clash-protection' [-Wunused-command-line-argument]
warning: unknown warning option '-Wduplicated-branches' [-Wunknown-warning-option]
warning: unknown warning option '-Wduplicated-cond' [-Wunknown-warning-option]
warning: unknown warning option '-Wlogical-op'; did you mean '-Wlong-long'? [-Wunknown-warning-option]
warning: unknown warning option '-Wbidi-chars=any' [-Wunknown-warning-option]
4 warnings generated.
[ 14%] Linking CXX static library libunivalue.a
4 warnings generated.
[ 14%] Building CXX object src/CMakeFiles/bitcoin_consensus.dir/primitives/transaction.cpp.o
clang++: warning: argument unused during compilation: '-fuse-ld=lld' [-Wunused-command-line-argument]
clang++: warning: argument unused during compilation: '-fstack-clash-protection' [-Wunused-command-line-argument]
warning: unknown warning option '-Wduplicated-branches' [-Wunknown-warning-option]
warning: unknown warning option '-Wduplicated-cond' [-Wunknown-warning-option]
warning: unknown warning option '-Wlogical-op'; did you mean '-Wlong-long'? [-Wunknown-warning-option]
warning: unknown warning option '-Wbidi-chars=any' [-Wunknown-warning-option]
[ 14%] Built target univalue
[ 14%] Building CXX object src/test/util/CMakeFiles/test_util.dir/setup_common.cpp.o
clang++: warning: argument unused during compilation: '-fuse-ld=lld' [-Wunused-command-line-argument]
clang++: warning: argument unused during compilation: '-fstack-clash-protection' [-Wunused-command-line-argument]
warning: unknown warning option '-Wduplicated-branches' [-Wunknown-warning-option]
warning: unknown warning option '-Wduplicated-cond' [-Wunknown-warning-option]
warning: unknown warning option '-Wlogical-op'; did you mean '-Wlong-long'? [-Wunknown-warning-option]
warning: unknown warning option '-Wbidi-chars=any' [-Wunknown-warning-option]
4 warnings generated.
[ 15%] Linking CXX static library libbitcoin_clientversion.a
4 warnings generated.
[ 15%] Built target bitcoin_clientversion
[ 15%] Building CXX object src/crypto/CMakeFiles/bitcoin_crypto.dir/ripemd160.cpp.o
[ 15%] Building CXX object CMakeFiles/leveldb.dir/src/leveldb/db/log_writer.cc.o
clang++: warning: argument unused during compilation: '-fuse-ld=lld' [-Wunused-command-line-argument]
clang++: warning: argument unused during compilation: '-fstack-clash-protection' [-Wunused-command-line-argument]
warning: unknown warning option '-Wduplicated-branches' [-Wunknown-warning-option]
warning: unknown warning option '-Wduplicated-cond' [-Wunknown-warning-option]
warning: unknown warning option '-Wlogical-op'; did you mean '-Wlong-long'? [-Wunknown-warning-option]
warning: unknown warning option '-Wbidi-chars=any' [-Wunknown-warning-option]
clang++: warning: argument unused during compilation: '-fuse-ld=lld' [-Wunused-command-line-argument]
clang++: warning: argument unused during compilation: '-fstack-clash-protection' [-Wunused-command-line-argument]
warning: unknown warning option '-Wduplicated-branches' [-Wunknown-warning-option]
warning: unknown warning option '-Wduplicated-cond' [-Wunknown-warning-option]
warning: unknown warning option '-Wlogical-op'; did you mean '-Wlong-long'? [-Wunknown-warning-option]
warning: unknown warning option '-Wbidi-chars=any' [-Wunknown-warning-option]
4 warnings generated.
4 warnings generated.

in doc/fuzzing.md:156 in e93c0b0882 outdated

 152 | @@ -153,13 +153,18 @@ You may also need to take care of giving the correct path for `clang` and
 153 |  `clang++`, like `CC=/path/to/clang CXX=/path/to/clang++` if the non-systems
 154 |  `clang` does not come first in your path.
 155 |  
 156 | +Currently the default linker on macOS `ld` does not work with recent versions of `llvm` so you will need to install llvm's linker `lld` and use it with the CXX_FLAG `-fuse-ld=lld`.

l0rinc commented at 7:17 PM on February 26, 2025:

Can you add a tracking issue here to know when we can safely remove it

m3dwards commented at 9:40 PM on February 26, 2025:

Not sure I feel this is big enough to add to the issue list and I would be happy for the docs to be updated when someone notices again that it's not needed any more, especially as this workaround should continue to work in the future even if strictly not needed any more.

m3dwards commented at 9:40 PM on February 26, 2025:

But obviously if you feel differently, go ahead and make the issue.

l0rinc commented at 10:04 PM on February 26, 2025:

I meant the ld issue - not critical

in doc/fuzzing.md:162 in e93c0b0882 outdated

 157 | +
 158 |  Full configuration step that was tested on macOS with `brew` installed `llvm`:
 159 |  
 160 |  ```sh
 161 | +$ brew install llvm
 162 | +$ brew install lld

l0rinc commented at 7:19 PM on February 26, 2025:

we can likely do this in a single command:

$ brew install llvm lld

We also likely need to remove the command from https://github.com/bitcoin/bitcoin/blob/master/doc/fuzzing.md?plain=1#L150 now

m3dwards commented at 9:36 PM on February 26, 2025:

Taken

in doc/fuzzing.md:158 in e93c0b0882 outdated

 152 | @@ -153,13 +153,18 @@ You may also need to take care of giving the correct path for `clang` and
 153 |  `clang++`, like `CC=/path/to/clang CXX=/path/to/clang++` if the non-systems
 154 |  `clang` does not come first in your path.
 155 |  
 156 | +Currently the default linker on macOS `ld` does not work with recent versions of `llvm` so you will need to install llvm's linker `lld` and use it with the CXX_FLAG `-fuse-ld=lld`.
 157 | +
 158 |  Full configuration step that was tested on macOS with `brew` installed `llvm`:

l0rinc commented at 7:21 PM on February 26, 2025:

This seems to need an update - though I'd just remove the command from the comment:

Full configuration steps:

m3dwards commented at 9:37 PM on February 26, 2025:

Took something similar

in doc/fuzzing.md:167 in e93c0b0882 outdated

 163 |  $ cmake --preset=libfuzzer \
 164 |     -DCMAKE_C_COMPILER="$(brew --prefix llvm)/bin/clang" \
 165 |     -DCMAKE_CXX_COMPILER="$(brew --prefix llvm)/bin/clang++" \
 166 | -   -DAPPEND_LDFLAGS=-Wl,-no_warn_duplicate_libraries
 167 | +   -DAPPEND_LDFLAGS=-Wl,-no_warn_duplicate_libraries \
 168 | +   -DCMAKE_CXX_FLAGS="-fuse-ld=lld"

l0rinc commented at 7:23 PM on February 26, 2025:

I'm getting:

clang++: warning: argument unused during compilation: '-fuse-ld=lld' [-Wunused-command-line-argument]

m3dwards commented at 9:37 PM on February 26, 2025:

Resolved warnings

l0rinc changes_requested

l0rinc commented at 7:35 PM on February 26, 2025: contributor

Concept ACK

Finally fuzzing is working with these changes (tested on M4 Max with Clang 19.1.7), but we're still getting warnings - and a I left a few more suggestions

m3dwards force-pushed on Feb 26, 2025

m3dwards commented at 9:42 PM on February 26, 2025: contributor

@Prabhat1308 and @l0rinc, I've updated the instructions to achieve the same goal but without the warnings.

in doc/fuzzing.md:158 in 725c0fd95b outdated

 152 | @@ -153,13 +153,17 @@ You may also need to take care of giving the correct path for `clang` and
 153 |  `clang++`, like `CC=/path/to/clang CXX=/path/to/clang++` if the non-systems
 154 |  `clang` does not come first in your path.
 155 |  
 156 | -Full configuration step that was tested on macOS with `brew` installed `llvm`:
 157 | +Currently the default linker on macOS `ld` does not work with recent versions of `llvm` so you will need to install llvm's linker `lld` and use it with the CMAKE_EXE_LINKER_FLAG `-fuse-ld=lld`.
 158 | +
 159 | +Full configuration step for macOS:

l0rinc commented at 10:05 PM on February 26, 2025:

It's not exactly full, we still need:

$ cmake --build build_fuzz -j$(nproc)
$ FUZZ=process_message build_fuzz/src/test/fuzz/fuzz

m3dwards commented at 10:19 PM on February 26, 2025:

Technically, it is the full configuration step :)

l0rinc approved

l0rinc commented at 10:10 PM on February 26, 2025: contributor

ACK 725c0fd95b15157bd0ec141cc24d27818f536656

DrahtBot requested review from jonatack on Feb 26, 2025

Prabhat1308 commented at 10:26 PM on February 26, 2025: none

tACK 725c0fd

-Checked by running the fuzz tests on several fuzz targets . No warnings displayed now.

maflcko added this to the milestone 29.0 on Feb 27, 2025

in doc/fuzzing.md:165 in 725c0fd95b outdated

 162 | +$ brew install llvm lld
 163 |  $ cmake --preset=libfuzzer \
 164 |     -DCMAKE_C_COMPILER="$(brew --prefix llvm)/bin/clang" \
 165 |     -DCMAKE_CXX_COMPILER="$(brew --prefix llvm)/bin/clang++" \
 166 | -   -DAPPEND_LDFLAGS=-Wl,-no_warn_duplicate_libraries
 167 | +   -DAPPEND_LDFLAGS=-Wl,-no_warn_duplicate_libraries \

fanquake commented at 10:14 AM on March 4, 2025:

no_warn_duplicate_libraries isn't an lld option, so this can be dropped.

m3dwards commented at 12:21 PM on March 4, 2025:

Thanks, dropped.

l0rinc commented at 1:00 PM on March 4, 2025:

Nice, finally we can get rid of that (tested, seems to be working without the warning, good find)! Should we comment anything on https://github.com/llvm/llvm-project/issues/102630?

in doc/fuzzing.md:156 in 725c0fd95b outdated

 152 | @@ -153,13 +153,17 @@ You may also need to take care of giving the correct path for `clang` and
 153 |  `clang++`, like `CC=/path/to/clang CXX=/path/to/clang++` if the non-systems
 154 |  `clang` does not come first in your path.
 155 |  
 156 | -Full configuration step that was tested on macOS with `brew` installed `llvm`:
 157 | +Currently the default linker on macOS `ld` does not work with recent versions of `llvm` so you will need to install llvm's linker `lld` and use it with the CMAKE_EXE_LINKER_FLAG `-fuse-ld=lld`.

fanquake commented at 10:15 AM on March 4, 2025:

Rather than adding text that repeats the code below, we could just say something like: "Using lld is required to due to issues with Apples ld and LLVM".

m3dwards commented at 12:21 PM on March 4, 2025:

Changed to this

m3dwards force-pushed on Mar 4, 2025

in doc/fuzzing.md:156 in 4fae769791 outdated

 152 | @@ -153,13 +153,16 @@ You may also need to take care of giving the correct path for `clang` and
 153 |  `clang++`, like `CC=/path/to/clang CXX=/path/to/clang++` if the non-systems
 154 |  `clang` does not come first in your path.
 155 |  
 156 | -Full configuration step that was tested on macOS with `brew` installed `llvm`:
 157 | +Using lld is required to due to issues with Apples ld and LLVM.

l0rinc commented at 12:47 PM on March 4, 2025:

Typo, maybe something like:

Using `lld` is required due to issues with Apple's `ld` and `LLVM`.

m3dwards commented at 1:16 PM on March 4, 2025:

gah, taken!

Thanks for the spot.

m3dwards force-pushed on Mar 4, 2025

doc: update fuzz instructions when on macOS

Default linker on macOS does not work with recent versions of LLVM. Updated the instructions for fuzzing to use lld instead.

75486c8ed8

m3dwards force-pushed on Mar 4, 2025

l0rinc commented at 1:23 PM on March 4, 2025: contributor

ACK 75486c8ed87a480b9f0c4dc7a10f3cd4eee87b12

Compared to previous review, APPEND_LDFLAGS was removed and the description simplified to avoid repetition.

brunoerg approved

brunoerg commented at 4:37 PM on March 4, 2025: contributor

ACK 75486c8ed87a480b9f0c4dc7a10f3cd4eee87b12

I just tested it on macOS 14.3 and worked fine.

hebasto approved

hebasto commented at 5:58 PM on March 4, 2025: member

ACK 75486c8ed87a480b9f0c4dc7a10f3cd4eee87b12, tested on macOS 15.3.1 (Apple M1) + Clang 19.1.7.

hebasto requested review from dergoegge on Mar 4, 2025

glozow assigned hebasto on Mar 4, 2025

hebasto merged this on Mar 5, 2025

hebasto closed this on Mar 5, 2025

m3dwards deleted the branch on Mar 5, 2025

pablomartin4btc commented at 5:02 PM on March 5, 2025: member

tACK 75486c8ed87a480b9f0c4dc7a10f3cd4eee87b12

Managed to reproduce the issue in master (before merge) and this PR fixes it.

jonatack commented at 10:12 PM on March 7, 2025: member

Post-merge tested ACK using the following incantation with arm64 macos 15.3.1:

$ rm -rf ./build_fuzz/ && cmake -B ./build_fuzz -DAPPEND_CXXFLAGS="-std=c++23" --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" && cmake --build ./build_fuzz --parallel 11 --

$ FUZZ=process_message ./build_fuzz/src/test/fuzz/fuzz