diff options
author | Nick Fitzgerald <fitzgen@gmail.com> | 2017-10-05 10:49:11 -0700 |
---|---|---|
committer | Nick Fitzgerald <fitzgen@gmail.com> | 2017-10-05 10:51:56 -0700 |
commit | 29fff6a5a23c7b8e483df00b83352ac8849bf212 (patch) | |
tree | a945094a13ca709dabf466bb77ca6b58f668c315 | |
parent | d97cba5caec6fa2d784f03ab3eae8ea97c1abeb2 (diff) |
Extend the `csmith` README
-rw-r--r-- | csmith-fuzzing/README.md | 64 |
1 files changed, 61 insertions, 3 deletions
diff --git a/csmith-fuzzing/README.md b/csmith-fuzzing/README.md index e4c74243..258ab5e7 100644 --- a/csmith-fuzzing/README.md +++ b/csmith-fuzzing/README.md @@ -1,7 +1,65 @@ -Fuzz bindgen with `csmith` https://github.com/csmith-project/csmith . +# Fuzzing `bindgen` with `csmith` -Run with `python3 driver.py`. It will run until until it encounters an error in `bindgen`. +[`csmith`][csmith] generates random C and C++ programs that can be used as test +cases for compilers. When testing `bindgen` with `csmith`, we interpret the +generated programs as header files, and emit Rust bindings to them. If `bindgen` +panics, the emitted bindings won't compile with `rustc`, or the generated layout +tests in the bindings fail, then we report an issue containing the test case! + +<!-- START doctoc generated TOC please keep comment here to allow auto update --> +<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> + + +- [Prerequisites](#prerequisites) +- [Running the Fuzzer](#running-the-fuzzer) +- [Reporting Issues](#reporting-issues) + +<!-- END doctoc generated TOC please keep comment here to allow auto update --> + +## Prerequisites Requires `python3`, `csmith` and `bindgen` to be in `$PATH`. -csmith is run with `--no-checksum --nomain --max-block-size 1 --max-block-depth 1` which disables the `main` function and makes function bodies as simple as possible as bindgen does not care about them but they cannot be completely disabled in csmith. Run `csmith --help` to see what exactly those options do. +Many OS package managers have a `csmith` package: + +``` +$ sudo apt install csmith +$ brew install csmith +$ # Etc... +``` + +## Running the Fuzzer + +Run `csmith` and test `bindgen` on the generated test cases with this command: + +``` +$ ./driver.py +``` + +The driver will keep running until it encounters an error in `bindgen`. + +Each invocation of `./driver.py` will use its own temporary directories, so +running it in multiple terminals in parallel is supported. + +`csmith` is run with `--no-checksum --nomain --max-block-size 1 +--max-block-depth 1` which disables the `main` function, and makes function +bodies as simple as possible as `bindgen` does not care about them, but they +cannot be completely disabled in `csmith`. Run `csmith --help` to see what +exactly those options do. + +## Reporting Issues + +Once the fuzz driver finds a test case that causes some kind of error in +`bindgen` or its emitted bindings, it is helpful to +[run C-Reduce on the test case][creducing] to remove the parts that are +irrelevant to reproducing the error. This is ***very*** helpful for the folks +who further investigate the issue and come up with a fix! + +Additionally, mention that you discovered the issue via `csmith` and we will add +the `A-csmith` label. You can find all the issues discovered with `csmith`, and +related to fuzzing with `csmith`, by looking up +[all issues tagged with the `A-csmith` label][csmith-issues]. + +[csmith]: https://github.com/csmith-project/csmith +[creducing]: ../CONTRIBUTING.md#using-creduce-to-minimize-test-cases +[csmith-issues]: https://github.com/rust-lang-nursery/rust-bindgen/issues?q=label%3AA-csmith |