1# Fuzzing `bindgen` with `csmith` 2 3[`csmith`][csmith] generates random C and C++ programs that can be used as test 4cases for compilers. When testing `bindgen` with `csmith`, we interpret the 5generated programs as header files, and emit Rust bindings to them. If `bindgen` 6panics, the emitted bindings won't compile with `rustc`, or the generated layout 7tests in the bindings fail, then we report an issue containing the test case! 8 9<!-- START doctoc generated TOC please keep comment here to allow auto update --> 10<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> 11 12 13- [Prerequisites](#prerequisites) 14- [Running the Fuzzer](#running-the-fuzzer) 15- [Reporting Issues](#reporting-issues) 16 17<!-- END doctoc generated TOC please keep comment here to allow auto update --> 18 19## Prerequisites 20 21Requires `python3`, `csmith`, and `creduce` to be in `$PATH`. 22 23Many OS package managers have `csmith` and `creduce` packages: 24 25``` 26$ sudo apt install csmith creduce 27$ brew install csmith creduce 28$ # Etc... 29``` 30 31## Running the Fuzzer 32 33Run `csmith` and test `bindgen` on the generated test cases with this command: 34 35``` 36$ ./driver.py 37``` 38 39The driver will keep running until it encounters an error in `bindgen`. 40 41Each invocation of `./driver.py` will use its own temporary directories, so 42running it in multiple terminals in parallel is supported. 43 44`csmith` is run with `--no-checksum --nomain --max-block-size 1 45--max-block-depth 1` which disables the `main` function, and makes function 46bodies as simple as possible as `bindgen` does not care about them, but they 47cannot be completely disabled in `csmith`. Run `csmith --help` to see what 48exactly those options do. 49 50## Reporting Issues 51 52Once the fuzz driver finds a test case that causes some kind of error in 53`bindgen` or its emitted bindings, it is helpful to 54[run C-Reduce on the test case][creducing] to remove the parts that are 55irrelevant to reproducing the error. This is ***very*** helpful for the folks 56who further investigate the issue and come up with a fix! 57 58Additionally, mention that you discovered the issue via `csmith` and we will add 59the `A-csmith` label. You can find all the issues discovered with `csmith`, and 60related to fuzzing with `csmith`, by looking up 61[all issues tagged with the `A-csmith` label][csmith-issues]. 62 63[csmith]: https://github.com/csmith-project/csmith 64[creducing]: ../CONTRIBUTING.md#using-creduce-to-minimize-test-cases 65[csmith-issues]: https://github.com/rust-lang/rust-bindgen/issues?q=label%3AA-csmith 66