This directory contains tools for importing third-party Rust crates and constructing BUILD.gn files from them.
The //third_party/rust/third_party.toml
crate defines the set of crates depended on from first-party code. Any transitive dependencies will be found from those listed there. The file is a subset of a standard Cargo.toml
file, but only listing the [dependencies]
section.
To use a third-party crate “bar” version 3 from first party code, add the following to //third_party/rust/third_party.toml
in [dependencies]
:
[dependencies] bar = "3"
To enable a feature “spaceships” in the crate, change the entry in //third_party/rust/third_party.toml
to include the feature:
[dependencies] bar = { version = "3", features = [ "spaceships" ] }
BUILD.gn
files for third-party cratesTo generate BUILD.gn
files for all third-party crates, and find missing transitive dependencies to download, use the gnrt
tool:
src/
dir of Chromium.gnrt
to run on host machine: cargo build --release --manifest-path tools/crates/gnrt/Cargo.toml --target-dir out/gnrt
.gnrt
with the gen
action: out/gnrt/release/gnrt gen
.This will generate a BUILD.gn
file for each third-party crate. The BUILD.gn
file changes will be visible in git status
and can be added with git add
.
To download crate “foo”, at version 4.2.3:
gnrt
with the download
action: e.g. out/Default/gnrt download --security-critical=yes foo 4.2.3
This will download the crate and unpack it into //third_party/rust/foo/v4/crate
. The entire v4
directory, which includes the crate
subdirectory as well as a generated README.chromium
file, should be added to the repository with git add third_party/rust/foo/v4
.
Once all the crates are downloaded and gnrt gen
completes, a CL can be uploaded to go through third-party review.
You may patch a crate in tree, but save any changes made into a diff file in a patches/
directory for the crate. The diff file should be generated by git-format-patch
each new patch numbered consecutively so that they can be applied in order. For example, these files might exist if the “foo” crate was patched with a couple of changes:
//third_party/rust/foo/v4/patches/0001-Edit-the-Cargo-toml.diff //third_party/rust/foo/v4/patches/0002-Other-changes.diff
To update a crate “foo” to the latest version you must just re-import it at this time. To update from version “1.2.0” to “1.3.2”:
gnrt
before making any changes to //third_party/rust
: cargo build --release --manifest-path tools/crates/gnrt/Cargo.toml --target-dir out/gnrt
.//third_party/rust/foo/v1/crate
directory, which contains the upstream code.out/gnrt/release/gnrt download foo 1.3.2
.for i in $(find third_party/rust/foo/v1/patches/*); do patch -p1 < $i; done
out/gnrt/release/gnrt gen
to re-generate all third-party BUILD.gn
files.all_rust
to verify things are working.The directory structure for a crate “foo” version 3.4.2 is:
//third_party/ rust/ foo/ v3/ BUILD.gn (generated by gnrt) README.chromium crate/ Cargo.toml src/ ...etc... patches/ 0001-Edit-the-Cargo-toml.diff 0002-Other-changes.diff
BUILD.gn
files for stdlib cratesTo generate BUILD.gn
files for the crates with the gnrt
tool:
src/
dir of Chromium.gnrt
to run on host machine: cargo build --release --manifest-path tools/crates/gnrt/Cargo.toml --target-dir out/gnrt
.gnrt
with the gen
action: out/gnrt/release/gnrt gen --for-std
.This will generate the //build/rust/std/rules/BUILD.gn
file, with the changes visible in git status
and can be added with git add
.
BUILD.gn
files for stdlib crates when rolling RustThe above instructions generate GN rules from the installed Rust toolchain in //third_party/rust-toolchain. If you don‘t have an installed toolchain yet (or it’s the wrong revision), you can generate from another Rust source root, such as in //third_party/rust_src/src
by adding a value to the --for-std
argument:
//third_party/rust_src/src
. This can be done with tools/clang/scripts/upload_revision.py --no-git --skip-clang --rust-git-hash DESIRED_GIT_HASH
.tools/rust/build_rust.py --update-deps
.gnrt
to run on host machine: cargo build --release --manifest-path tools/crates/gnrt/Cargo.toml --target-dir out/gnrt
.gnrt
with the gen
action: out/gnrt/release/gnrt gen --for-std=third_party/rust_src/src
.