• Home
Name
Date
Size
#Lines
LOC

..--

README.mdD12-May-20242.4 KiB6646

csmith.hD12-May-2024418 168

driver.pyD12-May-20247.7 KiB285228

predicate.pyD12-May-20249.2 KiB274220

README.md

1 # Fuzzing `bindgen` with `csmith`
2 
3 [`csmith`][csmith] generates random C and C++ programs that can be used as test
4 cases for compilers. When testing `bindgen` with `csmith`, we interpret the
5 generated programs as header files, and emit Rust bindings to them. If `bindgen`
6 panics, the emitted bindings won't compile with `rustc`, or the generated layout
7 tests 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 
21 Requires `python3`, `csmith`, and `creduce` to be in `$PATH`.
22 
23 Many 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 
33 Run `csmith` and test `bindgen` on the generated test cases with this command:
34 
35 ```
36 $ ./driver.py
37 ```
38 
39 The driver will keep running until it encounters an error in `bindgen`.
40 
41 Each invocation of `./driver.py` will use its own temporary directories, so
42 running 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
46 bodies as simple as possible as `bindgen` does not care about them, but they
47 cannot be completely disabled in `csmith`. Run `csmith --help` to see what
48 exactly those options do.
49 
50 ## Reporting Issues
51 
52 Once 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
55 irrelevant to reproducing the error. This is ***very*** helpful for the folks
56 who further investigate the issue and come up with a fix!
57 
58 Additionally, mention that you discovered the issue via `csmith` and we will add
59 the `A-csmith` label. You can find all the issues discovered with `csmith`, and
60 related 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