Getting Started with Rust in Chromium

Welcome! If you're interested in learning more about how to use Rust as a Chromium developer, you're in the right place.

Rust support in Chromium is still growing, so your best resource is the Rust-in-Chrome team (internal link). We're the folks responsible for building and maintaining Chromium's Rust infrastructure, and we're always happy to help out people who want to use Rust in their work -- it is quite literally our job to make your lives easier.

[TOC]

Contacting us

If you have questions or an idea about how to use Rust in your work, we'd be more than happy to provide advice and support.

External Resources

The best ways to reach us are at [email protected], or in the #rust channel on the Chromium Slack.

Team Resources (internal)

For Google employees, there are several internal resources you can use as well. If you want to contact the team as a whole, feel free to send a message to [email protected] or join the Chrome + Rust chatroom. However, we also have spaces dedicated to getting started with Rust:

• A chatroom (go/rust-in-chrome-questions).
• Regular office hours (go/rust-in-chrome-office-hours). There are no signups, so feel free to drop in to the call at any time!

FAQ

• Q: Do I need approval to use Rust in Chromium?
  • A: Nope! Rust is considered just another tool; you may choose to use it at your own discretion, and only need acceptance from code owners as usual.
• Q: How do I get my Rust code reviewed?
  • A: Code should be reviewed by the local owners. Since Rust is still growing, the Rust-in-Chrome team is happy to provide reviews and advice on the linguistic portion of the CL, but owner reviews are still needed to ensure the code is doing the right things in the first place.
• Q: Are there any restrictions on unsafe Rust?
  • A: The short answer is no. We encourage you to avoid it whenever possible, but you can opt in to unsafe rust at your own discretion by adding allow_unsafe = true to your build target. See //docs/rust/unsafe.md for more information.
• Q: How should I set myself up for Rust development?
  • A: We recommend using VSCode with the rust-analyzer extension. See //docs/rust/dev_experience_tips_and_tricks.md for more information, and see below for information about getting your files hooked into the build system.
• Q: How do I interoperate with C++ code?
  • A: If you want to call C++ functions directly from Rust, or vice-versa, our standard tool is cxx. An alternative if you're implementing a service in Rust is to use Mojo as a communication method, which avoids the need for direct interop. See //docs/rust/ffi.md for more information.
• Q: How should I test my code?
  • A: Chromium uses gtest for Rust code, using the //testing/rust_gtest_interop library to integrate into existing testing binaries (example). Unlike most Rust project, we do not support #[cfg(test)]-style testing.
• Q: Can I use unstable compiler features?
  • A: Generally, no. Since the features could change or be removed without warning, you need approval from the Rust in Chrome team to use unstable features in your code. See //docs/rust/unstable_rust_feature_usage.md for more information.

Build system setup

First-party Rust libraries

If you want to create your own Rust library inside of Chromium, use the rust_static_library GN template (not the built-in rust_library) to integrate properly into the Chromium build and get the correct compiler options (example). Internally, this will generate a Rust crate with a mangled name based on the name of the GN target (to ensure crate names are globally unique).

To use that crate from Chromium code, import it using the chromium::import! macro, which is automatically available in all Chromium code (example). The standard library and crates from //third_party/rust do not use mangled names, so chromium::import! is not necessary for them.

Your IDE (or coding agent) may suggest use mangled_crate_name::foo;, but please use chromium::import! instead to avoid depending on the mangling scheme.

Third-party Rust libraries

crates.io

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.

Other libraries

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.

Additional Resources

The other documents in this folder (//docs/rust) contain a variety of information about using Rust in Chromium, including both advice and our policies. However, they are more useful as a reference once you're familiar with the language.

If you want to learn more about Rust on your own, Google maintains a free Rust course. The course outline and "slides" are available to everyone, and they alone can be very helpful. If you're a Google employee, you can also see if there are any instructor-led courses scheduled (go/comprehensive-rust).