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:
gnrt
to run on host machine, e.g. ninja -C out/Default gnrt
.gnrt
with the gen
action: e.g. out/Default/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
.//third_party/rust/foo/v1/crate
directory, which contains the upstream code.out/<conf>/gnrt download foo 1.3.2
.for i in $(find third_party/rust/foo/v1/patches/*); do patch -p1 < $i; done
out/<conf>/gnrt gen
to re-generate all third-party BUILD.gn
files.gnrt
and gnrt_unittests
. Run gnrt
and ensure the BUILD.gn
outputs are the same as before. Run gnrt_unittests
.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