1# The `libfuzzer-sys` Crate
2
3Barebones wrapper around LLVM's libFuzzer runtime library.
4
5The CPP parts are extracted from compiler-rt git repository with `git filter-branch`.
6
7libFuzzer relies on LLVM sanitizer support. The Rust compiler has built-in support for LLVM sanitizer support, for now, it's limited to Linux. As a result, `libfuzzer-sys` only works on Linux.
8
9## Usage
10
11### Use `cargo fuzz`!
12
13[The recommended way to use this crate with `cargo fuzz`!][cargo-fuzz].
14
15[cargo-fuzz]: https://github.com/rust-fuzz/cargo-fuzz
16
17### Manual Usage
18
19This crate can also be used manually as following:
20
21First create a new cargo project:
22
23```
24$ cargo new --bin fuzzed
25$ cd fuzzed
26```
27
28Then add a dependency on the `fuzzer-sys` crate and your own crate:
29
30```toml
31[dependencies]
32libfuzzer-sys = "0.4.0"
33your_crate = { path = "../path/to/your/crate" }
34```
35
36Change the `fuzzed/src/main.rs` to fuzz your code:
37
38```rust
39#![no_main]
40
41use libfuzzer_sys::fuzz_target;
42
43fuzz_target!(|data: &[u8]| {
44    // code to fuzz goes here
45});
46```
47
48Build by running the following command:
49
50```sh
51$ cargo rustc -- \
52    -C passes='sancov' \
53    -C llvm-args='-sanitizer-coverage-level=3' \
54    -C llvm-args='-sanitizer-coverage-inline-8bit-counters' \
55    -Z sanitizer=address
56```
57
58And finally, run the fuzzer:
59
60```sh
61$ ./target/debug/fuzzed
62```
63
64### Linking to a local libfuzzer
65
66When using `libfuzzer-sys`, you can provide your own `libfuzzer` runtime in two ways.
67
68If you are developing a fuzzer, you can set the `CUSTOM_LIBFUZZER_PATH` environment variable to the path of your local
69`libfuzzer` runtime, which will then be linked instead of building libfuzzer as part of the build stage of `libfuzzer-sys`.
70For an example, to link to a prebuilt LLVM 16 `libfuzzer`, you could use:
71
72```bash
73$ export CUSTOM_LIBFUZZER_PATH=/usr/lib64/clang/16/lib/libclang_rt.fuzzer-x86_64.a
74$ cargo fuzz run ...
75```
76
77Alternatively, you may also disable the default `link_libfuzzer` feature:
78
79In `Cargo.toml`:
80```toml
81[dependencies]
82libfuzzer-sys = { path = "../../libfuzzer", default-features = false }
83```
84
85Then link to your own runtime in your `build.rs`.
86
87## Updating libfuzzer from upstream
88
89```
90./update-libfuzzer.sh <github.com/llvm-mirror/llvm-project SHA1>
91```
92
93## License
94
95All files in `libfuzzer` directory are licensed NCSA.
96
97Everything else is dual-licensed Apache 2.0 and MIT.
98