danakj | 6e25f74 | 2022-12-01 21:47:42 | [diff] [blame] | 1 | # Rust in Chromium |
| 2 | |
| 3 | [TOC] |
| 4 | |
| 5 | # Why? |
| 6 | |
danakj | bb4d0c77 | 2023-10-13 13:22:28 | [diff] [blame] | 7 | Handling untrustworthy data in non-trivial ways is a major source of security |
| 8 | bugs, and it's therefore against Chromium's security policies |
| 9 | [to do it in the Browser or Gpu process](../docs/security/rule-of-2.md) unless |
| 10 | you are working in a memory-safe language. |
danakj | 6e25f74 | 2022-12-01 21:47:42 | [diff] [blame] | 11 | |
| 12 | Rust provides a cross-platform memory-safe language so that all platforms can |
| 13 | handle untrustworthy data directly from a privileged process, without the |
| 14 | performance overheads and complexity of a utility process. |
| 15 | |
danakj | 6e25f74 | 2022-12-01 21:47:42 | [diff] [blame] | 16 | # Status |
| 17 | |
danakj | bb4d0c77 | 2023-10-13 13:22:28 | [diff] [blame] | 18 | The Rust toolchain is enabled for and supports all platforms and development |
| 19 | environments that are supported by the Chromium project. The first milestone |
| 20 | to include full production-ready support was M119. |
danakj | 6e25f74 | 2022-12-01 21:47:42 | [diff] [blame] | 21 | |
David Adrian | d891869 | 2024-12-12 22:02:50 | [diff] [blame] | 22 | Rust can be used anywhere in the Chromium repository (not just `//third_party`) |
| 23 | subject to [current interop capabilities][interop-rust-doc], however it is |
| 24 | currently subject to a internal approval and FYI process. Googlers can view |
| 25 | go/chrome-rust for details. New usages of Rust are documented at |
| 26 | [`[email protected]`](https://groups.google.com/a/chromium.org/g/rust-fyi). |
danakj | 6e25f74 | 2022-12-01 21:47:42 | [diff] [blame] | 27 | |
| 28 | For questions or help, reach out to `[email protected]` or `#rust` on the |
| 29 | [Chromium Slack](https://www.chromium.org/developers/slack/). |
| 30 | |
danakj | 6e25f74 | 2022-12-01 21:47:42 | [diff] [blame] | 31 | If you use VSCode, we have [additional advice below](#using-vscode). |
| 32 | |
danakj | bb4d0c77 | 2023-10-13 13:22:28 | [diff] [blame] | 33 | # Adding a third-party Rust library |
danakj | 6e25f74 | 2022-12-01 21:47:42 | [diff] [blame] | 34 | |
danakj | bb4d0c77 | 2023-10-13 13:22:28 | [diff] [blame] | 35 | Third-party libraries are pulled from [crates.io](https://crates.io), but |
| 36 | Chromium does not use Cargo as a build system. |
danakj | 6e25f74 | 2022-12-01 21:47:42 | [diff] [blame] | 37 | |
| 38 | ## Third-party review |
| 39 | |
danakj | 6e25f74 | 2022-12-01 21:47:42 | [diff] [blame] | 40 | All third-party crates need to go through third-party review. See |
| 41 | [//docs/adding_to_third_party.md](adding_to_third_party.md) for instructions on |
| 42 | how to have a library reviewed. |
| 43 | |
danakj | bb4d0c77 | 2023-10-13 13:22:28 | [diff] [blame] | 44 | ## Importing a crate from crates.io |
| 45 | |
danakj | 0ec93d1 | 2023-11-17 16:12:23 | [diff] [blame] | 46 | The `//third_party/rust/chromium_crates_io/Cargo.toml` file defines the set of crates |
danakj | bb4d0c77 | 2023-10-13 13:22:28 | [diff] [blame] | 47 | depended on from first-party code. Any transitive dependencies will be found |
danakj | 0ec93d1 | 2023-11-17 16:12:23 | [diff] [blame] | 48 | from those listed there. The file is a [standard `Cargo.toml` file]( |
| 49 | https://doc.rust-lang.org/cargo/reference/manifest.html), though the crate |
| 50 | itself is never built, it is only used to collect dependencies through the |
| 51 | `[dependencies]` section. |
danakj | bb4d0c77 | 2023-10-13 13:22:28 | [diff] [blame] | 52 | |
danakj | 0ec93d1 | 2023-11-17 16:12:23 | [diff] [blame] | 53 | To use a third-party crate "bar" version 3 from first party code: |
danakj | 98bec16 | 2023-11-21 14:55:02 | [diff] [blame] | 54 | 1. Change directory to the root `src/` dir of Chromium. |
| 55 | 1. Add the crate to `//third_party/rust/chromium_crates_io/Cargo.toml`: |
| 56 | * `vpython3 ./tools/crates/run_gnrt.py add foo` to add the latest version of `foo`. |
| 57 | * `vpython3 ./tools/crates/run_gnrt.py add [email protected]` to add a specific version of `foo`. |
| 58 | * Or, directly through (nightly) cargo: |
| 59 | `cargo run --release --manifest-path tools/crates/gnrt/Cargo.toml --target-dir out/gnrt add foo` |
| 60 | * Or, edit the Cargo.toml by hand, finding the version you want from [crates.io](https://crates.io). |
| 61 | 1. Download the crate's files: |
| 62 | * `./tools/crates/run_gnrt.py vendor` to download the new crate. |
| 63 | * Or, directly through (nightly) cargo: |
danakj | 0ec93d1 | 2023-11-17 16:12:23 | [diff] [blame] | 64 | `cargo run --release --manifest-path tools/crates/gnrt/Cargo.toml --target-dir out/gnrt vendor` |
danakj | f509caa | 2023-11-23 15:29:43 | [diff] [blame] | 65 | * This will also apply any patches in `//third_party/rust/chromium_crates_io/patches` |
| 66 | for the crates. If a patch can not apply, the crate's download will be cancelled and |
Lukasz Anforowicz | b2b4b123 | 2025-04-25 16:22:33 | [diff] [blame] | 67 | an error will be printed. See |
| 68 | `//third_party/rust/chromium_crates_io/patches/README.md` for more details. |
danakj | 98bec16 | 2023-11-21 14:55:02 | [diff] [blame] | 69 | 1. (optional) If the crate is only to be used by tests and tooling, then |
| 70 | specify the `"test"` group in `//third_party/rust/chromium_crates_io/gnrt_config.toml`: |
| 71 | ``` |
| 72 | [crate.foo] |
| 73 | group = "test" |
| 74 | ``` |
| 75 | 1. Generate the `BUILD.gn` file for the new crate: |
| 76 | * `vpython3 ./tools/crates/run_gnrt.py gen` |
| 77 | * Or, directly through (nightly) cargo: |
| 78 | `cargo run --release --manifest-path tools/crates/gnrt/Cargo.toml --target-dir out/gnrt gen` |
Lukasz Anforowicz | 057876d | 2024-06-05 19:07:58 | [diff] [blame] | 79 | 1. Add the new files to git: |
| 80 | * `git add -f third_party/rust/chromium_crates_io/vendor`. |
| 81 | (The `-f` is important, as files may be skipped otherwise from a |
| 82 | `.gitignore` inside the crate.) |
| 83 | * `git add third_party/rust` |
Lukasz Anforowicz | f6888b7b | 2025-03-25 17:41:13 | [diff] [blame] | 84 | 1. Upload the CL and get a review from `//third_party/rust/OWNERS`. |
danakj | 0ec93d1 | 2023-11-17 16:12:23 | [diff] [blame] | 85 | |
| 86 | ### Cargo features |
danakj | bb4d0c77 | 2023-10-13 13:22:28 | [diff] [blame] | 87 | |
| 88 | To enable a feature "spaceships" in the crate, change the entry in |
danakj | 0ec93d1 | 2023-11-17 16:12:23 | [diff] [blame] | 89 | `//third_party/rust/chromium_crates_io/Cargo.toml` to include the feature: |
danakj | bb4d0c77 | 2023-10-13 13:22:28 | [diff] [blame] | 90 | ```toml |
| 91 | [dependencies] |
| 92 | bar = { version = "3", features = [ "spaceships" ] } |
| 93 | ``` |
| 94 | |
danakj | 98bec16 | 2023-11-21 14:55:02 | [diff] [blame] | 95 | ## Security |
danakj | bb4d0c77 | 2023-10-13 13:22:28 | [diff] [blame] | 96 | |
danakj | 98bec16 | 2023-11-21 14:55:02 | [diff] [blame] | 97 | If a shipping library needs security review (has any `unsafe`), and the review |
| 98 | finds it's not satisfying the [rule of 2](../docs/security/rule-of-2.md), then |
| 99 | move it to the `"sandbox"` group in `//third_party/rust/chromium_crates_io/gnrt_config.toml` |
| 100 | to make it clear it can't be used in a privileged process: |
| 101 | ``` |
| 102 | [crate.foo] |
| 103 | group = "sandbox" |
| 104 | ``` |
| 105 | |
| 106 | If a transitive dependency moves from `"safe"` to `"sandbox"` and causes |
| 107 | a dependency chain across the groups, it will break the `gnrt vendor` step. |
| 108 | You will need to fix the new crate so that it's deemed safe in unsafe review, |
| 109 | or move the other dependent crates out of `"safe"` as well by setting their |
| 110 | group in `gnrt_config.toml`. |
| 111 | |
| 112 | # Updating existing third-party crates |
| 113 | |
Lukasz Anforowicz | 85528a6 | 2024-03-20 19:12:53 | [diff] [blame] | 114 | Third-party crates will get updated semi-automatically through the process |
| 115 | described in |
| 116 | [`../tools/crates/create_update_cl.md`](../tools/crates/create_update_cl.md). |
| 117 | If you nevertheless need to manually update a crate to its latest minor |
| 118 | version, then follow the steps below: |
| 119 | |
danakj | 98bec16 | 2023-11-21 14:55:02 | [diff] [blame] | 120 | 1. Change directory to the root `src/` dir of Chromium. |
Dominik Röttsches | a07a553 | 2024-01-24 19:16:23 | [diff] [blame] | 121 | 1. Update the versions in `//third_party/rust/chromium_crates_io/Cargo.toml`. |
Lukasz Anforowicz | 85528a6 | 2024-03-20 19:12:53 | [diff] [blame] | 122 | * `vpython3 ./tools/crates/run_gnrt.py update <crate name>` |
danakj | 98bec16 | 2023-11-21 14:55:02 | [diff] [blame] | 123 | * Or, directly through (nightly) cargo: |
Lukasz Anforowicz | 85528a6 | 2024-03-20 19:12:53 | [diff] [blame] | 124 | `cargo run --release --manifest-path tools/crates/gnrt/Cargo.toml --target-dir out/gnrt update <crate name>` |
danakj | 98bec16 | 2023-11-21 14:55:02 | [diff] [blame] | 125 | 1. Download any updated crate's files: |
| 126 | * `./tools/crates/run_gnrt.py vendor` |
Dominik Röttsches | a07a553 | 2024-01-24 19:16:23 | [diff] [blame] | 127 | * If you want to restrict the update to certain crates, add the crate names |
| 128 | as arguments to `vendor`, like: `./tools/crates/run_gnrt.py vendor |
| 129 | <crate-name>` |
danakj | 98bec16 | 2023-11-21 14:55:02 | [diff] [blame] | 130 | * Or, directly through (nightly) cargo: |
| 131 | `cargo run --release --manifest-path tools/crates/gnrt/Cargo.toml --target-dir out/gnrt vendor` |
Lukasz Anforowicz | 8452bd8d | 2023-11-28 23:31:55 | [diff] [blame] | 132 | 1. Add the downloaded files to git: |
danakj | 98bec16 | 2023-11-21 14:55:02 | [diff] [blame] | 133 | * `git add -f third_party/rust/chromium_crates_io/vendor` |
| 134 | * The `-f` is important, as files may be skipped otherwise from a |
| 135 | `.gitignore` inside the crate. |
danakj | 98bec16 | 2023-11-21 14:55:02 | [diff] [blame] | 136 | 1. Generate the `BUILD.gn` files |
| 137 | * `vpython3 ./tools/crates/run_gnrt.py gen` |
| 138 | * Or, directly through (nightly) cargo: |
| 139 | `cargo run --release --manifest-path tools/crates/gnrt/Cargo.toml --target-dir out/gnrt gen` |
Lukasz Anforowicz | 8452bd8d | 2023-11-28 23:31:55 | [diff] [blame] | 140 | 1. Add the generated files to git: |
| 141 | * `git add -f third_party/rust` |
danakj | bb4d0c77 | 2023-10-13 13:22:28 | [diff] [blame] | 142 | |
| 143 | ### Directory structure for third-party crates |
| 144 | |
| 145 | The directory structure for a crate "foo" version 3.4.2 is: |
| 146 | ``` |
| 147 | //third_party/ |
| 148 | rust/ |
danakj | 98bec16 | 2023-11-21 14:55:02 | [diff] [blame] | 149 | foo/ (for the "foo" crate) |
Lukasz Anforowicz | 8452bd8d | 2023-11-28 23:31:55 | [diff] [blame] | 150 | v3/ (version 3.4.2 maps to the v3 epoch) |
danakj | bb4d0c77 | 2023-10-13 13:22:28 | [diff] [blame] | 151 | BUILD.gn (generated by gnrt gen) |
danakj | 98bec16 | 2023-11-21 14:55:02 | [diff] [blame] | 152 | README.chromium (generated by gnrt vendor) |
Lukasz Anforowicz | 8452bd8d | 2023-11-28 23:31:55 | [diff] [blame] | 153 | chromium_crates_io/ |
| 154 | vendor/ |
| 155 | foo-3.4.2 (crate sources downloaded from crates.io) |
danakj | 98bec16 | 2023-11-21 14:55:02 | [diff] [blame] | 156 | patches/ |
Lukasz Anforowicz | 8452bd8d | 2023-11-28 23:31:55 | [diff] [blame] | 157 | foo/ (patches for the "foo" crate) |
Lukasz Anforowicz | b2b4b123 | 2025-04-25 16:22:33 | [diff] [blame] | 158 | 0001-Some-changes.diff |
danakj | bb4d0c77 | 2023-10-13 13:22:28 | [diff] [blame] | 159 | 0002-Other-changes.diff |
Lukasz Anforowicz | 8452bd8d | 2023-11-28 23:31:55 | [diff] [blame] | 160 | Cargo.toml |
| 161 | Cargo.lock |
| 162 | gnrt_config.toml |
danakj | bb4d0c77 | 2023-10-13 13:22:28 | [diff] [blame] | 163 | ``` |
| 164 | |
danakj | 6e25f74 | 2022-12-01 21:47:42 | [diff] [blame] | 165 | ## Writing a wrapper for binding generation |
| 166 | |
| 167 | Most Rust libraries will need a more C++-friendly API written on top of them in |
danakj | bb4d0c77 | 2023-10-13 13:22:28 | [diff] [blame] | 168 | order to generate C++ bindings to them. The wrapper library can be placed |
| 169 | in `//third_party/rust/<cratename>/<epoch>/wrapper` or at another single place |
| 170 | that all C++ goes through to access the library. The [CXX](https://cxx.rs) is |
| 171 | used to generate bindings between C++ and Rust. |
danakj | 6e25f74 | 2022-12-01 21:47:42 | [diff] [blame] | 172 | |
| 173 | See |
danakj | bb4d0c77 | 2023-10-13 13:22:28 | [diff] [blame] | 174 | [`//third_party/rust/serde_json_lenient/v0_1/wrapper/`]( |
| 175 | https://source.chromium.org/chromium/chromium/src/+/main:third_party/rust/serde_json_lenient/v0_1/wrapper/) |
| 176 | and |
| 177 | [`//components/qr_code_generator`]( |
| 178 | https://source.chromium.org/chromium/chromium/src/+/main:components/qr_code_generator/;l=1;drc=b185db5d502d4995627e09d62c6934590031a5f2) |
| 179 | for examples. |
danakj | 6e25f74 | 2022-12-01 21:47:42 | [diff] [blame] | 180 | |
danakj | bb4d0c77 | 2023-10-13 13:22:28 | [diff] [blame] | 181 | Rust libraries should use the |
| 182 | [`rust_static_library`]( |
| 183 | https://source.chromium.org/chromium/chromium/src/+/main:build/rust/rust_static_library.gni) |
| 184 | GN template (not the built-in `rust_library`) to integrate properly into the |
| 185 | mixed-language Chromium build and get the correct compiler options applied to |
| 186 | them. |
danakj | 6e25f74 | 2022-12-01 21:47:42 | [diff] [blame] | 187 | |
Lukasz Anforowicz | dcdb524a | 2025-03-24 19:26:41 | [diff] [blame] | 188 | See `rust-ffi.md` for information on C++/Rust FFI. |
danakj | 6e25f74 | 2022-12-01 21:47:42 | [diff] [blame] | 189 | |
Tatsuyuki Ishi | b3425ab0 | 2025-04-10 19:02:20 | [diff] [blame] | 190 | # Unstable features |
| 191 | |
| 192 | Unstable features are **unsupported** by default in Chromium. Any use of an |
| 193 | unstable language or library feature should be agreed upon by the Rust toolchain |
| 194 | team before enabling it. |
| 195 | |
| 196 | Since Chromium imports the Rust toolchain at its HEAD and builds it in a |
| 197 | nightly-like configuration, it is technically possible to depend on unstable |
| 198 | features. However, unstable features often change in a backwards incompatible |
| 199 | way without a warning. If such incompatible changes are introduced, importing a |
| 200 | new version of toolchain now requires the owner to fix forward, instead of being |
| 201 | an automated process. This makes toolchain upgrades prohibitively difficult. |
| 202 | |
| 203 | When an exception is required, consider: |
| 204 | |
| 205 | - Whether the unstable feature brings significant value that is unattainable |
| 206 | in stable alternatives |
| 207 | - The risk of breaking changes to the feature |
| 208 | - Ways to fallback in case a backward-incompatible toolchain change is |
| 209 | introduced |
| 210 | |
| 211 | A list of exceptions is maintained in |
| 212 | [`../tools/rust/unstable_rust_feature_usage.md`](../tools/rust/unstable_rust_feature_usage.md). |
| 213 | |
danakj | 3d037ff | 2024-11-07 19:31:41 | [diff] [blame] | 214 | # Logging |
Adrian Taylor | 91eaa36 | 2024-02-09 14:17:03 | [diff] [blame] | 215 | |
danakj | 3d037ff | 2024-11-07 19:31:41 | [diff] [blame] | 216 | Use the [log](https://docs.rs/log) crate's macros in place of base `LOG` |
| 217 | macros from C++. They do the same things. The `debug!` macro maps to |
| 218 | `DLOG(INFO)`, the `info!` macro maps to `LOG(INFO)`, and `warn!` and `error!` |
| 219 | map to `LOG(WARNING)` and `LOG(ERROR)` respectively. The additional `trace!` |
| 220 | macro maps to `DLOG(INFO)` (but there is [WIP to map it to `DVLOG(INFO)`]( |
| 221 | https://chromium-review.googlesource.com/c/chromium/src/+/5996820)). |
| 222 | |
| 223 | Note that the standard library also includes a helpful |
| 224 | [`dbg!`](https://doc.rust-lang.org/std/macro.dbg.html) macro which writes |
| 225 | everything about a variable to `stderr`. |
| 226 | |
| 227 | Logging may not yet work in component builds: |
| 228 | [crbug.com/374023535](https://crbug.com/374023535). |
| 229 | |
| 230 | # Tracing |
| 231 | |
| 232 | TODO: [crbug.com/377915495](https://crbug.com/377915495). |
| 233 | |
| 234 | # Strings |
| 235 | |
| 236 | Prefer to use [`BString`](https://docs.rs/bstr/latest/bstr/struct.BString.html) |
| 237 | and [`BStr`](https://docs.rs/bstr/latest/bstr/struct.BStr.html) to work with |
| 238 | strings in first-party code instead of `std::String` and `str`. These types do |
| 239 | not require the strings to be valid UTF-8, and avoid error handling or panic |
| 240 | crashes when working with strings from C++ and/or from the web. Because the |
| 241 | web is not UTF-8 encoded, many strings in Chromium are also not. |
| 242 | |
| 243 | In cross-language bindings, `&[u8]` can be used to represent a string until |
| 244 | native support for `BStr` is available in our interop tooling. A `u8` slice |
| 245 | can be converted to `BStr` or treated as a string with |
| 246 | [`ByteSlice`](https://docs.rs/bstr/latest/bstr/trait.ByteSlice.html). |
Adrian Taylor | 91eaa36 | 2024-02-09 14:17:03 | [diff] [blame] | 247 | |
danakj | 6e25f74 | 2022-12-01 21:47:42 | [diff] [blame] | 248 | # Using VSCode |
| 249 | |
| 250 | 1. Ensure you're using the `rust-analyzer` extension for VSCode, rather than |
| 251 | earlier forms of Rust support. |
danakj | bb4d0c77 | 2023-10-13 13:22:28 | [diff] [blame] | 252 | 2. Run `gn` with the `--export-rust-project` flag, such as: |
| 253 | `gn gen out/Release --export-rust-project`. |
danakj | 6e25f74 | 2022-12-01 21:47:42 | [diff] [blame] | 254 | 3. `ln -s out/Release/rust-project.json rust-project.json` |
| 255 | 4. When you run VSCode, or any other IDE that uses |
| 256 | [rust-analyzer](https://rust-analyzer.github.io/) it should detect the |
| 257 | `rust-project.json` and use this to give you rich browsing, autocompletion, |
| 258 | type annotations etc. for all the Rust within the Chromium codebase. |
danakj | f3d7f37 | 2023-12-07 18:17:12 | [diff] [blame] | 259 | 5. Point rust-analyzer to the rust toolchain in Chromium. Otherwise you will |
| 260 | need to install Rustc in your system, and Chromium uses the nightly |
| 261 | compiler, so you would need that to match. Add the following to |
| 262 | `.vscode/settings.json` in the Chromium checkout: |
| 263 | ``` |
| 264 | { |
| 265 | // The rest of the settings... |
| 266 | |
| 267 | "rust-analyzer.cargo.extraEnv": { |
| 268 | "PATH": "../../third_party/rust-toolchain/bin:$PATH", |
| 269 | } |
| 270 | } |
| 271 | ``` |
| 272 | This assumes you are working with an output directory like `out/Debug` which |
| 273 | has two levels; adjust the number of `..` in the path according to your own |
| 274 | setup. |
Adrian Taylor | c5fbb57 | 2023-11-21 14:25:42 | [diff] [blame] | 275 | |
| 276 | # Using cargo |
| 277 | |
| 278 | If you are building a throwaway or experimental tool, you might like to use pure |
| 279 | `cargo` tooling rather than `gn` and `ninja`. Even then, you may choose |
| 280 | to restrict yourself to the toolchain and crates that are already approved for |
| 281 | use in Chromium. |
| 282 | |
| 283 | Here's how. |
| 284 | |
| 285 | ``` |
| 286 | export PATH_TO_CHROMIUM_SRC=~/chromium/src |
| 287 | mkdir my-rust-tool |
| 288 | cd my-rust-tool |
| 289 | mkdir .cargo |
| 290 | cat <<END > .cargo/config.toml |
| 291 | [source.crates-io] |
| 292 | replace-with = "vendored-sources" |
| 293 | |
| 294 | [source.vendored-sources] |
| 295 | directory = "$PATH_TO_CHROMIUM_SRC/third_party/rust/chromium_crates_io/vendor" |
| 296 | END |
| 297 | $PATH_TO_CHROMIUM_SRC/third_party/rust-toolchain/bin/cargo init --offline |
| 298 | $PATH_TO_CHROMIUM_SRC/third_party/rust-toolchain/bin/cargo run --offline |
| 299 | ``` |
| 300 | |
| 301 | Most `cargo` tooling works well with this setup; one exception is `cargo add`, |
| 302 | but you can still add dependencies manually to your `Cargo.toml`: |
| 303 | |
| 304 | ``` |
| 305 | [dependencies] |
| 306 | log = "0.4" |
| 307 | ``` |
David Adrian | d891869 | 2024-12-12 22:02:50 | [diff] [blame] | 308 | |
| 309 | [interop-rust-doc]: https://docs.google.com/document/d/1kvgaVMB_isELyDQ4nbMJYWrqrmL3UZI4tDxnyxy9RTE/edit?tab=t.0#heading=h.fpqr6hf3c3j0 |