Update fuzzing README from #3806 (#4107)

This commit is contained in:
Gerard Guillemas Martos 2024-05-28 17:31:10 +02:00 committed by GitHub
parent f79a946cbe
commit 5cbe400e4c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -3,7 +3,7 @@ Surrealdb maintains a set of fuzz testing harnesses that are managed by
[cargo-fuzz](https://github.com/rust-fuzz/cargo-fuzz).
To build and run the fuzzer we will need to;
- Install a specific version of the nightly compiler
- Install the nightly compiler
- Install cargo fuzz
- Build a fuzz friendly version of surrealdb with our harnesses
@ -14,23 +14,13 @@ version of rustc we can't instrument our fuzz-harnesses with coverage feedback.
Because of this we need to use some of the more bleeding edge features
available in the nightly release.
Unfortunately for us the nightly release is a little unstable and there
was a [bug](https://github.com/rust-lang/rust/issues/110475) in the
latest version of the nightly compiler that prevents use from compiling
some of surrealdb's dependencies. To workaround this issue we've carefully
picked a version of the nightly compiler that works with both cargo-fuzz
and our dependencies. This version is `nightly-2023-04-21`. To install
this version we simply need to run;
`rustup install nightly-2023-04-21`
## Installing cargo-fuzz
Full details on the different install options are available, in the
[cargo-fuzz book](https://rust-fuzz.github.io/book/cargo-fuzz/setup.html).
but for the sake of brevity you can just install the basics with the
command below.
`cargo +nightly-2023-04-21 install cargo-fuzz`
`cargo +nightly install cargo-fuzz`
## Building the fuzzers
Now that we've install cargo-fuzz we can go ahead and build our fuzzers.
@ -38,20 +28,20 @@ Now that we've install cargo-fuzz we can go ahead and build our fuzzers.
cd lib
# -O: Optimised build
# --debug-assertions: Catch common bugs, e.g. integer overflow.
cargo +nightly-2023-04-21 fuzz build -O --debug-assertions
cargo +nightly fuzz build -O --debug-assertions
````
## Running the fuzzer
Now that the fuzzer has successfully built we can actually run them. To
list the available fuzz harnesses we can use the command.
```
cargo +nightly-2023-04-21 fuzz list
cargo +nightly fuzz list
```
Once we know what fuzzer (in this case fuzz_executor) we want to run we
can it using the command;
```
cargo +nightly-2023-04-21 fuzz run -O --debug-assertions fuzz_executor
cargo +nightly fuzz run -O --debug-assertions fuzz_executor
```
The previous command will run the fuzzer in libfuzzer's default mode,
@ -62,7 +52,7 @@ up we can make use of all cores, and use a dictionary file. e.g.
# use nproc to match the number of processors on our local
# machine.
# -dict: Make use the fuzzer specific dictionary file.
cargo +nightly-2023-04-21 fuzz run -O --debug-assertions \
cargo +nightly fuzz run -O --debug-assertions \
fuzz_executor -- -fork=$(nproc) \
-dict=fuzz/fuzz_targets/fuzz_executor.dict
```