docs/rust.md
[TOC]
Handling untrustworthy data in non-trivial ways is a major source of security bugs, and it's therefore against Chromium's security policies to do it in the Browser or Gpu process unless you are working in 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 overhead and complexity of a utility process.
The Rust toolchain is enabled for and supports all platforms and development environments that are supported by the Chromium project. The first milestone to include full production-ready support was M119.
Rust can be used anywhere in the Chromium repository (not just //third_party)
subject to current interop capabilities. There is no special
process for introducing Rust. Similar to any code change, OWNERS approval is
required. Googlers can see go/chrome-rust for more details.
For questions or help, reach out to
[email protected],
or #rust channel
on the Chromium Slack,
or (Google-internal, sorry)
Chrome Rust chatroom.
If you use VSCode, we have additional advice below.
First-party Rust libraries should use the
rust_static_library
GN template (not the built-in rust_library) to integrate properly into the
mixed-language Chromium build and get the correct compiler options applied to
them.
Rust libraries that depend on other first-party Rust libraries
should import APIs using chromium::import! from
the Chromium prelude library
rather than
use some_crate_name::foo.
This avoids concerns about non-globally-unique crate names.
This guidance doesn't apply when depending on Rust standard library
nor when depending on crates from //third_party/rust.
See
//docs/rust-ffi.md
for how to interop with Rust code from C/C++.
Mapping of Chromium APIs to Rust:
gtest integration is provided by
//testing/rust_gtest_interop
library.//base and can be
used in place of LOG(...) from C++ side.
dbg! macro which writes
everything about a variable to stderr.See
//third_party/rust/README-importing-new-crates.md
for instructions on how to import a crate from https://crates.io into Chromium.
The crates will get updated semi-automatically through the process described in
../tools/crates/create_update_cl.md.
These libraries use the
cargo_crate
GN template.
Third-party Rust libraries that are not distributed through crates.io should live outside of //third_party/rust.
Such libraries will typically depend on //third_party/rust crates
and use //build/rust/*.gni templates, but there is no other Chromium
tooling to import such libraries or keep them updated.
For examples, see //third_party/crabbyavif or
//third_party/cloud_authenticator.
Unstable features are unsupported by default in Chromium. Any use of an
unstable language or library feature should be agreed upon by the Rust toolchain
team before enabling it. See
tools/rust/unstable_rust_feature_usage.md
for more details.
This section has been moved to
//docs/rust/dev_experience_tips_and_tricks.md.
If you are building a throwaway or experimental tool, you might like to use pure
cargo tooling rather than gn and ninja. Even then, you may choose
to restrict yourself to the toolchain and crates that are already approved for
use in Chromium, by
tools/crates/run_cargo.py (which will use
Chromium's //third_party/rust-toolchain/bin/cargo).cargo/config.toml to ask to use the crates vendored
into Chromium's //third_party/rust/chromium_crates_io.An example of how this can work can be found in https://crrev.com/c/6320795/5.