Rust in Chromium

[TOC]

Why?

Parsing untrustworthy data is a major source of security bugs, and it's therefore against Chromium rules to do it in the browser process unless you can use a memory-safe language.

Rust provides a cross-platform memory-safe language so that all platforms can handle untrustworthy data directly from a privileged process, without the performance overheads and complexity of a utility process.

Guidelines

Rust in Chromium is not production-ready. It is guarded behind a GN flag which is off by default.

Rust is only used in //third_party/rust, for crates developed outside of the Chromium tree.

Status

The Rust toolchain is still experimental and breaks frequently, but it is behind an off-by-default GN argument, so this does not affect our bots or developers.

We have a working Rust toolchain for Linux x64 and Android targets. We are working on support for other platforms.

For questions or help, reach out to rust-dev@chromium.org or #rust on the Chromium Slack.

Building with Rust support

1. Add "checkout_rust": True to your .gclient file in the "custom vars" section. (This is the default on Linux, so you can skip this).
2. Add enable_rust = true in your gn arguments, via gn args <outdir>.

If you use VSCode, we have additional advice below.

Using a third-party Rust library

Importing a crate from crates.io

See //tools/crates/README.md for instructions on how to import a third-party library and generate GN build rules for it.

Third-party review

Since the Rust toolchain is still experimental, there is no Rust in production and we're not ready to consider approving Rust libraries that aren't part of the experiment and stabilization of the Rust toolchain.

All third-party crates need to go through third-party review. See //docs/adding_to_third_party.md for instructions on how to have a library reviewed.

Writing a wrapper for binding generation

Most Rust libraries will need a more C++-friendly API written on top of them in order to generate C++ bindings to them. Such wrapper libraries should be written in //third_party/rust/<cratename>/<epoch>/wrapper.

See //third_party/rust/serde_json_lenient/v0_1/wrapper/ for an example.

Rust libraries should use our rust_static_library GN template, in place of built-in GN rust_library, in order to integrate properly into the build and get the correct compiler options applied to them.

We provide the CXX tool for generating C++ bindings for the Rust library (or wrapper library). Add any Rust files with a CXX bridge macro to the cxx_bindings variable in the rust_static_library GN rule to have CXX generate C++ a header for that file.

Building on non-Linux platforms

We only have a working Rust toolchain for Linux and Android at this time. To use Rust on other platforms, you will need to provide your own nightly Rust toolchain. You can then tell gn about it using these gn arguments:

enable_rust=true
rust_sysroot_absolute="/Users/you/.rustup/toolchains/<toolchain name>"
rustc_version="<your rustc version>" # add output of rustc -V
# added_rust_stdlib_libs=[]
# removed_rust_stdlib_libs=[]

The last two arguments are any Rust standard library .rlibs which have been added or removed between the version that's distributed for Linux/Android, and the version you're using. They should rarely be necessary; if you get errors about missing standard libraries then adjust removed_rust_stdlib_libs; if you get errors about undefined symbols then have a look in your equivalent of the .rustup/toolchains/<toolchain name>/lib/rustlib/<target>/lib directory and add any new libraries which are not listed in //build/rust/std/BUILD.gn to the added_rust_stlib_libs list.

Using VSCode

1. Ensure you're using the rust-analyzer extension for VSCode, rather than earlier forms of Rust support.
2. Run gn with this extra flag: gn gen out/Release --export-rust-project.
3. ln -s out/Release/rust-project.json rust-project.json
4. When you run VSCode, or any other IDE that uses rust-analyzer it should detect the rust-project.json and use this to give you rich browsing, autocompletion, type annotations etc. for all the Rust within the Chromium codebase.