1 # The `libfuzzer-sys` Crate
2 
3 Barebones wrapper around LLVM's libFuzzer runtime library.
4 
5 The CPP parts are extracted from compiler-rt git repository with `git filter-branch`.
6 
7 libFuzzer 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 
19 This crate can also be used manually as following:
20 
21 First create a new cargo project:
22 
23 ```
24 $ cargo new --bin fuzzed
25 $ cd fuzzed
26 ```
27 
28 Then add a dependency on the `fuzzer-sys` crate and your own crate:
29 
30 ```toml
31 [dependencies]
32 libfuzzer-sys = "0.4.0"
33 your_crate = { path = "../path/to/your/crate" }
34 ```
35 
36 Change the `fuzzed/src/main.rs` to fuzz your code:
37 
38 ```rust
39 #![no_main]
40 
41 use libfuzzer_sys::fuzz_target;
42 
43 fuzz_target!(|data: &[u8]| {
44     // code to fuzz goes here
45 });
46 ```
47 
48 Build 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 
58 And finally, run the fuzzer:
59 
60 ```sh
61 $ ./target/debug/fuzzed
62 ```
63 
64 ### Linking to a local libfuzzer
65 
66 When using `libfuzzer-sys`, you can provide your own `libfuzzer` runtime in two ways.
67 
68 If 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`.
70 For 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 
77 Alternatively, you may also disable the default `link_libfuzzer` feature:
78 
79 In `Cargo.toml`:
80 ```toml
81 [dependencies]
82 libfuzzer-sys = { path = "../../libfuzzer", default-features = false }
83 ```
84 
85 Then 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 
95 All files in `libfuzzer` directory are licensed NCSA.
96 
97 Everything else is dual-licensed Apache 2.0 and MIT.
98