Debian Codegraph @

.cargo/vendor/libfuzzer-sys/README.md

raw
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-module' \
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 * Update the `COMMIT=...` variable in `./update-libfuzzer.sh` with the new
90 commit hash from [llvm-mirror/llvm-project](github.com/llvm-mirror/llvm-project)
91 that you are vendoring.
92
93 * Re-run the script:
94
95 ```
96 $ ./update-libfuzzer.sh <github.com/llvm-mirror/llvm-project SHA1>
97 ```
98
99 ## License
100
101 All files in the `libfuzzer` directory are licensed NCSA.
102
103 Everything else is dual-licensed Apache 2.0 and MIT.