This directory contains tools for importing third-party Rust crates and constructing BUILD.gn files from them.

Depending on third-party crates

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" ] }

Generating BUILD.gn files for third-party crates

To generate BUILD.gn files for all third-party crates, and find missing transitive dependencies to download, use the gnrt tool:

1. Build gnrt to run on host machine, e.g. ninja -C out/Default gnrt.
2. Change directory to the root src/ dir of Chromium.
3. Run 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.

Downloading missing third-party crates

To download crate “foo”, at version 4.2.3:

1. Change directory to the root src/ dir of Chromium.
2. Run 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.

Patching third-party crates.

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

Updating existing third-party crates

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”:

1. Build gnrt before making any changes to //third_party/rust.
2. Remove the //third_party/rust/foo/v1/crate directory, which contains the upstream code.
3. Re-download the crate at the new version with out/<conf>/gnrt download foo 1.3.2.
4. If there are any, re-apply local patches with for i in $(find third_party/rust/foo/v1/patches/*); do patch -p1 < $i; done
5. Run out/<conf>/gnrt gen to re-generate all third-party BUILD.gn files.
6. Re-build gnrt and gnrt_unittests. Run gnrt and ensure the BUILD.gn outputs are the same as before. Run gnrt_unittests.

Directory structure for third-party crates

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