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. Change directory to the root src/ dir of Chromium.
2. Run vpython3 ./tools/crates/run_gnrt.py gen to build and run gnrt with the gen action.

Or, to directly build gnrt:

1. Change directory to the root src/ dir of Chromium.
2. Build gnrt to run on host machine: cargo build --release --manifest-path tools/crates/gnrt/Cargo.toml --target-dir out/gnrt.
3. Run 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.

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: cargo build --release --manifest-path tools/crates/gnrt/Cargo.toml --target-dir out/gnrt.
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/gnrt/release/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/gnrt/release/gnrt gen to re-generate all third-party BUILD.gn files.
6. Build all_rust to verify things are working.

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

Generating BUILD.gn files for stdlib crates

Simple way:

Run tools/rust/gnrt_stdlib.py.

Longer way

This requires Rust to be installed and available in your system, typically through https://rustup.rs.

To generate BUILD.gn files for the crates with the gnrt tool:

1. Change directory to the root src/ dir of Chromium.
2. Build gnrt to run on host machine: cargo build --release --manifest-path tools/crates/gnrt/Cargo.toml --target-dir out/gnrt.
3. Ensure you have a checkout of the Rust source tree in third_party/rust-src which can be done with tools/rust/build_rust.py --sync-for-gnrt.
4. Run gnrt with the gen action: out/gnrt/release/gnrt gen --for-std third_party/rust-src.

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.