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" ] }
To generate BUILD.gn
files for all third-party crates, and find missing
transitive dependencies to download, use the gnrt
tool:
- Build
gnrt
to run on host machine, e.g.ninja -C out/Default gnrt
. - Change directory to the root src/ dir of Chromium.
- Run
gnrt
with thegen
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:
- Change directory to the root src/ dir of Chromium.
- Run
gnrt
with thedownload
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":
- Build
gnrt
before making any changes to//third_party/rust
. - Remove the
//third_party/rust/foo/v1/crate
directory, which contains the upstream code. - Re-download the crate at the new version with
out/<conf>/gnrt download foo 1.3.2
. - If there are any, re-apply local patches with
for i in $(find third_party/rust/foo/v1/patches/*); do patch -p1 < $i; done
- Run
out/<conf>/gnrt gen
to re-generate all third-partyBUILD.gn
files. - Re-build
gnrt
andgnrt_unittests
. Rungnrt
and ensure theBUILD.gn
outputs are the same as before. Rungnrt_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