Handling untrustworthy data in non-trivial ways is a major source of security bugs, and it‘s therefore against Chromium’s security policiesto 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 tocurrent interop capabilities, however it is currently subject to a internal approval and FYI process. Googlers can view go/chrome-rust for details. New usages of Rust are documented atrust-fyi@chromium.org.
For questions or help, reach out torust-dev@chromium.org, or#rust channel on theChromium Slack, or (Google-internal, sorry)Chrome Rust chatroom.
If you use VSCode, we haveadditional advice below.
Third-party libraries are pulled fromcrates.io, but Chromium does not use Cargo as a build system.
All third-party libraries (not just Rust) need to go through third-party review. See//docs/adding_to_third_party.md for instructions.
Third-party crates (fromcrates.io) that Chromium depends on are described by two files:
//third_party/rust/chromium_crates_io/Cargo.toml. This file defines the set of cratesdirectly depended on from first-party code (from Chromium first-party code, but also from Pdfium, V8, etc.). Their transitive dependencies don't need to be listed, because they will be automatically identified and covered by tools likegnrt. The file is astandardCargo.toml file, even though the crate itself is never built - it is only used to enable/disable crate features, specify crate versions, etc.//third_party/rust/chromium_crates_io/gnrt_config.toml. This file defines Chromium-specific,cargo-agnostic metadata like: - Configuring certain aspects of Chromium build (e.g.allow_unsafe,allow_unstable_features,extra_src_roots,group = "test", etc.) - Specifying licensing information when it can't be automatically inferred (e.g. pointing outlicense_files with non-standard filenames).To import a third-party crate follow the steps below:
src/ dir of Chromium.//third_party/rust/chromium_crates_io/Cargo.toml:vpython3 ./tools/crates/run_gnrt.py add foo to add the latest version offoo.vpython3 ./tools/crates/run_gnrt.py add foo@1.2.3 to add a specific version offoo.//third_party/rust/chromium_crates_io/Cargo.toml by hand, finding the version you want fromcrates.io../tools/crates/run_gnrt.py vendor to download the new crate.//third_party/rust/chromium_crates_io/patches. See//third_party/rust/chromium_crates_io/patches/README.md for more details."test" group in//third_party/rust/chromium_crates_io/gnrt_config.toml:[crate.foo]group = "test"
BUILD.gn file for the new crate:vpython3 ./tools/crates/run_gnrt.py gen//third_party/rust/crate_name/OWNERSgit add -f third_party/rust/chromium_crates_io/vendor. (The-f is important, as files may be skipped otherwise from a.gitignore inside the crate.)git add third_party/rust//third_party/rust/OWNERS (checkthird_party/rust/OWNERS-review-checklist.md to see what to expect).Note that at this point the new crate is still not seen bygn norninja, and is not covered by CQ. To make the new crate part of the build, you need to add adeps edge between an existing build target and the newly added//third_party/rust/some_crate/v123:lib target. This will allowautoninja -C out/Default third_party/rust/some_crate/v123:lib to work. Additionally, this will help CQ to prevent regressions when updatingrustc or enabling new Rust warnings.
If a shipping library needs security review (has anyunsafe), and the review finds it‘s not satisfying therule of 2, then move it to the"sandbox" group in//third_party/rust/chromium_crates_io/gnrt_config.toml to make it clear it can’t be used in a privileged process:
[crate.foo]group = "sandbox"
If a transitive dependency moves from"safe" to"sandbox" and causes a dependency chain across the groups, it will break thegnrt vendor step. You will need to fix the new crate so that it's deemed safe in unsafe review, or move the other dependent crates out of"safe" as well by setting their group ingnrt_config.toml.
gnrt enumerates all.rs files as crate sources, but may need help with discovering additional files consumed with something likeinclude_str!. So, if you see:
ERROR: file not in GN sources:../../third_party/rust/chromium_crates_io/vendor/some_crate/README.md
Then you can:
Add the missing files tothird_party/rust/chromium_crates_io/gnrt_config.toml - for example:
[crate.some_crate]extra_input_roots = ['../README.md']
Re-generateBUILD.gn files by running:tools/crates/run_gnrt.py gen
Third-party crates will get updated semi-automatically through the process described in../tools/crates/create_update_cl.md. If you nevertheless need to manually update a crate to its latest minor or major version, then follow the steps below. To facilitate easier review, we recommend uploading separate patchsets for 1) manual changes, and 2) tool-driven, automated changes.
src/ dir of Chromium.//third_party/rust/chromium_crates_io/Cargo.toml.vpython3 ./tools/crates/run_gnrt.py update <crate name>.cargo update and accepts the samecommand line parameters. In particular, you may need to specify--breaking when working on major version updates../tools/crates/run_gnrt.py vendorgit add -f third_party/rust/chromium_crates_io/vendor-f is important, as files may be skipped otherwise from a.gitignore inside the crate.BUILD.gn filesvpython3 ./tools/crates/run_gnrt.py gencargo run --release --manifest-path tools/crates/gnrt/Cargo.toml --target-dir out/gnrt gengit add third_party/rustThe directory structure for a crate “foo” version 3.4.2 is:
//third_party/ rust/ foo/ (for the "foo" crate) v3/ (version 3.4.2 maps to the v3 epoch) BUILD.gn (generated by gnrt gen) README.chromium (generated by gnrt vendor) chromium_crates_io/ vendor/ foo-v3 (crate sources downloaded from crates.io) patches/ foo/ (patches for the "foo" crate) 0001-Some-changes.diff 0002-Other-changes.diff Cargo.toml Cargo.lock gnrt_config.toml
Most Rust libraries will need a more C++-friendly API written on top of them in order to generate C++ bindings to them. The wrapper library can be placed in//third_party/rust/<cratename>/<epoch>/wrapper or at another single place that all C++ goes through to access the library. TheCXX is used to generate bindings between C++ and Rust.
See//third_party/rust/serde_json_lenient/v0_1/wrapper/ and//components/qr_code_generator for examples.
Rust libraries should use therust_static_library GN template (not the built-inrust_library) to integrate properly into the mixed-language Chromium build and get the correct compiler options applied to them.
Seerust-ffi.md for information on C++/Rust FFI.
Unstable features areunsupported 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. Seetools/rust/unstable_rust_feature_usage.md for more details.
Use thelog crate's macros in place of baseLOG macros from C++. They do the same things. Thedebug! macro maps toDLOG(INFO), theinfo! macro maps toLOG(INFO), andwarn! anderror! map toLOG(WARNING) andLOG(ERROR) respectively. The additionaltrace! macro maps toDLOG(INFO) (but there isWIP to map it toDVLOG(INFO)).
Note that the standard library also includes a helpfuldbg! macro which writes everything about a variable tostderr.
Logging may not yet work in component builds:crbug.com/374023535.
TODO:crbug.com/377915495.
rust-analyzer extension for VSCode, rather than earlier forms of Rust support.gn with the--export-rust-project flag, such as:gn gen out/Release --export-rust-project.ln -s out/Release/rust-project.json rust-project.jsonrust-project.json and use this to give you rich browsing, autocompletion, type annotations etc. for all the Rust within the Chromium codebase..vscode/settings.json in the Chromium checkout:{ // The rest of the settings... "rust-analyzer.cargo.extraEnv": { "PATH": "../../third_party/rust-toolchain/bin:$PATH", }}This assumes you are working with an output directory likeout/Debug which has two levels; adjust the number of.. in the path according to your own setup.If you are building a throwaway or experimental tool, you might like to use purecargo tooling rather thangn andninja. 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 inhttps://crrev.com/c/6320795/5.