1--- 2layout: default 3title: Integrating a Rust project 4parent: Setting up a new project 5grand_parent: Getting started 6nav_order: 2 7permalink: /getting-started/new-project-guide/rust-lang/ 8--- 9 10# Integrating a Rust project 11{: .no_toc} 12 13- TOC 14{:toc} 15--- 16 17The process of integrating a project written in Rust with OSS-Fuzz is very 18similar to the general [Setting up a new project]({{ site.baseurl 19}}/getting-started/new-project-guide/) process. The key specifics of integrating 20a Rust project are outlined below. 21 22## cargo-fuzz support 23 24Rust integration with OSS-Fuzz is expected to use [`cargo 25fuzz`](https://github.com/rust-fuzz/cargo-fuzz) to build fuzzers. The `cargo 26fuzz` tool will build code with required compiler flags as well as link to the 27correct libFuzzer on OSS-Fuzz itself. Note that using `cargo fuzz` also makes it 28quite easy to run the fuzzers locally yourself if you get a failing test case! 29 30## Project files 31 32First you'll want to follow the [setup instructions for `cargo fuzz` 33itself](https://rust-fuzz.github.io/book/). Afterwards your project should have: 34 35* A top-level `fuzz` directory. 36* A `fuzz/Cargo.toml` manifest which pulls in necessary dependencies to fuzz. 37* Some `fuzz/fuzz_targets/*.rs` files which are the fuzz targets that will be 38 compiled and run on OSS-Fuzz. 39 40Note that you can customize this layout as well, but you'll need to edit some 41the scripts below to integrate into OSS-Fuzz. 42 43### project.yaml 44 45The `language` attribute must be specified. 46 47```yaml 48language: rust 49``` 50 51The only supported fuzzing engine and sanitizer are `libfuzzer` and `address`, 52respectively. 53[Example](https://github.com/google/oss-fuzz/blob/12ef3654b3e9adfd20b5a6afdde54819ba71493d/projects/serde_json/project.yaml#L3-L6) 54 55```yaml 56sanitizers: 57 - address 58fuzzing_engines: 59 - libfuzzer 60``` 61 62### Dockerfile 63 64The OSS-Fuzz builder image has the latest nightly release of Rust as well as 65`cargo fuzz` pre-installed and in `PATH`. In the `Dockerfile` for your project 66all you'll need to do is fetch the latest copy of your code and install any 67system dependencies necessary to build your project. 68[Example](https://github.com/google/oss-fuzz/blob/12ef3654b3e9adfd20b5a6afdde54819ba71493d/projects/serde_json/Dockerfile#L18-L20) 69 70```dockerfile 71RUN git clone --depth 1 https://github.com/serde-rs/json json 72``` 73 74### build.sh 75 76Here it's expected that you'll build the fuzz targets for your project and then 77copy the final binaries into the output directory. 78[Example](https://github.com/google/oss-fuzz/blob/12ef3654b3e9adfd20b5a6afdde54819ba71493d/projects/serde_json/build.sh#L20): 79 80```sh 81cd $SRC/json 82cargo fuzz build -O 83cp fuzz/target/x86_64-unknown-linux-gnu/release/from_slice $OUT/ 84``` 85 86Note that you likely want to pass the `-O` flag to `cargo fuzz build` which 87builds fuzzers in release mode. You may also want to pass the 88`--debug-assertions` flag to enable more checks while fuzzing. In this example 89the `from_slice` binary is the fuzz target. 90 91With some bash-fu you can also automatically copy over all fuzz targets into 92the output directory so when you add a fuzz target to your project it's 93automatically integrated into OSS-Fuzz: 94 95```sh 96FUZZ_TARGET_OUTPUT_DIR=target/x86_64-unknown-linux-gnu/release 97for f in fuzz/fuzz_targets/*.rs 98do 99 FUZZ_TARGET_NAME=$(basename ${f%.*}) 100 cp $FUZZ_TARGET_OUTPUT_DIR/$FUZZ_TARGET_NAME $OUT/ 101done 102``` 103