1 files changed, 102 insertions, 0 deletions
diff --git a/docs/getting-started/new-project-guide/rust_lang.md b/docs/getting-started/new-project-guide/rust_lang.md
new file mode 100644
index 00000000..51229903
--- /dev/null
+++ b/docs/getting-started/new-project-guide/rust_lang.md
@@ -0,0 +1,102 @@
+---
+layout: default
+title: Integrating a Rust project
+parent: Setting up a new project
+grand_parent: Getting started
+nav_order: 2
+permalink: /getting-started/new-project-guide/rust-lang/
+---
+
+# Integrating a Rust project
+{: .no_toc}
+
+- TOC
+{:toc}
+---
+
+The process of integrating a project written in Rust with OSS-Fuzz is very
+similar to the general [Setting up a new project]({{ site.baseurl
+}}/getting-started/new-project-guide/) process. The key specifics of integrating
+a Rust project are outlined below.
+
+## cargo-fuzz support
+
+Rust integration with OSS-Fuzz is expected to use [`cargo
+fuzz`](https://github.com/rust-fuzz/cargo-fuzz) to build fuzzers. The `cargo
+fuzz` tool will build code with required compiler flags as well as link to the
+correct libFuzzer on OSS-Fuzz itself. Note that using `cargo fuzz` also makes it
+quite easy to run the fuzzers locally yourself if you get a failing test case!
+
+## Project files
+
+First you'll want to follow the [setup instructions for `cargo fuzz`
+itself](https://rust-fuzz.github.io/book/). Afterwards your project should have:
+
+* A top-level `fuzz` directory
+* A `fuzz/Cargo.toml` manifest which pulls in necessary dependencies to fuzz
+* Some `fuzz/fuzz_targets/*.rs` files which are the fuzz targets that will be
+  compiled and run on OSS-Fuzz.
+
+Note that you can customize this layout as well, but you'll need to edit some
+the scripts below to integrate into OSS-Fuzz.
+
+### project.yaml
+
+The `language` attribute must be specified.
+
+```yaml
+language: rust
+```
+
+The only supported fuzzing engine and sanitizer are `libfuzzer` and `address`,
+respectively.
+[Example](https://github.com/google/oss-fuzz/blob/12ef3654b3e9adfd20b5a6afdde54819ba71493d/projects/serde_json/project.yaml#L3-L6)
+
+```yaml
+sanitizers:
+  - address
+fuzzing_engines:
+  - libfuzzer
+```
+
+### Dockerfile
+
+The OSS-Fuzz builder image has the latest nightly release of Rust as well as
+`cargo fuzz` pre-installed and in `PATH`. In the `Dockerfile` for your project
+all you'll need to do is fetch the latest copy of your code and install any
+system dependencies necessary to build your project.
+[Example](https://github.com/google/oss-fuzz/blob/12ef3654b3e9adfd20b5a6afdde54819ba71493d/projects/serde_json/Dockerfile#L18-L20)
+
+```dockerfile
+RUN git clone --depth 1 https://github.com/serde-rs/json json
+```
+
+### build.sh
+
+Here it's expected that you'll build the fuzz targets for your project and then
+copy the final binaries into the output directory.
+[Example](https://github.com/google/oss-fuzz/blob/12ef3654b3e9adfd20b5a6afdde54819ba71493d/projects/serde_json/build.sh#L20):
+
+```sh
+cd $SRC/json
+cargo fuzz build -O
+cp fuzz/target/x86_64-unknown-linux-gnu/release/from_slice $OUT/
+```
+
+Note that you likely want to pass the `-O` flag to `cargo fuzz build` which
+builds fuzzers in release mode. You may also want to pass the
+`--debug-assertions` flag to enable more checks while fuzzing. In this example
+the `from_slice` binary is the fuzz target.
+
+With some bash-fu you can also automatically copy over all fuzz targets into
+the output directory so when you add a fuzz target to your project it's
+automatically integrated into OSS-Fuzz:
+
+```sh
+FUZZ_TARGET_OUTPUT_DIR=target/x86_64-unknown-linux-gnu/release
+for f in fuzz/fuzz_targets/*.rs
+do
+    FUZZ_TARGET_NAME=$(basename ${f%.*})
+    cp $FUZZ_TARGET_OUTPUT_DIR/$FUZZ_TARGET_NAME $OUT/
+done
+```