Skip to content

Commit 3669ecd

Browse files
ajtownsryanofsky
andcommitted
doc: Document fuzz build options
Co-Authored-By: Ryan Ofsky <ryan@ofsky.org>
1 parent c1d01f5 commit 3669ecd

File tree

1 file changed

+31
-0
lines changed

1 file changed

+31
-0
lines changed

doc/fuzzing.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,37 @@ If you find coverage increasing inputs when fuzzing you are highly encouraged to
143143
144144
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.
145145
146+
## Building and debugging fuzz tests
147+
148+
There are 3 ways fuzz tests can be built:
149+
150+
1. With `-DBUILD_FOR_FUZZING=ON` which forces on fuzz determinism (skipping
151+
proof of work checks, disabling random number seeding, disabling clock time)
152+
and causes `Assume()` checks to abort on failure.
153+
154+
This is the normal way to run fuzz tests and generate new inputs. Because
155+
determinism is hardcoded on in this build, only the fuzz binary can be built
156+
and all other binaries are disabled.
157+
158+
2. With `-DBUILD_FUZZ_BINARY=ON -DCMAKE_BUILD_TYPE=Debug` which causes
159+
`Assume()` checks to abort on failure, and enables fuzz determinism, but
160+
makes it optional.
161+
162+
Determinism is turned on in the fuzz binary by default, but can be turned off
163+
by setting the `FUZZ_NONDETERMINISM` environment variable to any value, which
164+
may be useful for running fuzz tests with code that deterministic execution
165+
would otherwise skip.
166+
167+
Since `BUILD_FUZZ_BINARY`, unlike `BUILD_FOR_FUZZING`, does not hardcode on
168+
determinism, this allows non-fuzz binaries to coexist in the same build,
169+
making it possible to reproduce fuzz test failures in a normal build.
170+
171+
3. With `-DBUILD_FUZZ_BINARY=ON -DCMAKE_BUILD_TYPE=Release`. In this build, the
172+
fuzz binary will build but refuse to run, because in release builds
173+
determinism is forced off and `Assume()` checks do not abort, so running the
174+
tests would not be useful. This build is only useful for ensuring fuzz tests
175+
compile and link.
176+
146177
## macOS hints for libFuzzer
147178
148179
The default Clang/LLVM version supplied by Apple on macOS does not include

0 commit comments

Comments
 (0)