phantom/bitcoin
1
0
Fork 0
mirror of https://github.com/bitcoin/bitcoin.git synced 2025-04-29 14:59:39 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

doc: Document fuzz build options

Browse source 
Co-Authored-By: Ryan Ofsky <ryan@ofsky.org>
This commit is contained in:
Anthony Towns 2025-04-22 17:11:03 +10:00
parent c1d01f59ac
commit 3669ecd4cc
1 changed files with 31 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

31
doc/fuzzing.md
View file

@ -143,6 +143,37 @@ If you find coverage increasing inputs when fuzzing you are highly encouraged to
Every single pull request submitted against the Bitcoin Core repo is automatically tested against all inputs in the [`bitcoin-core/qa-assets`](https://github.com/bitcoin-core/qa-assets) repo. Contributing new coverage increasing inputs is an easy way to help make Bitcoin Core more robust.
## Building and debugging fuzz tests
There are 3 ways fuzz tests can be built:
1. With `-DBUILD_FOR_FUZZING=ON` which forces on fuzz determinism (skipping
proof of work checks, disabling random number seeding, disabling clock time)
and causes `Assume()` checks to abort on failure.
This is the normal way to run fuzz tests and generate new inputs. Because
determinism is hardcoded on in this build, only the fuzz binary can be built
and all other binaries are disabled.
2. With `-DBUILD_FUZZ_BINARY=ON -DCMAKE_BUILD_TYPE=Debug` which causes
`Assume()` checks to abort on failure, and enables fuzz determinism, but
makes it optional.
Determinism is turned on in the fuzz binary by default, but can be turned off
by setting the `FUZZ_NONDETERMINISM` environment variable to any value, which
may be useful for running fuzz tests with code that deterministic execution
would otherwise skip.
Since `BUILD_FUZZ_BINARY`, unlike `BUILD_FOR_FUZZING`, does not hardcode on
determinism, this allows non-fuzz binaries to coexist in the same build,
making it possible to reproduce fuzz test failures in a normal build.
3. With `-DBUILD_FUZZ_BINARY=ON -DCMAKE_BUILD_TYPE=Release`. In this build, the
fuzz binary will build but refuse to run, because in release builds
determinism is forced off and `Assume()` checks do not abort, so running the
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