src/tools/crates

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. 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

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. Run 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.

Generating BUILD.gn files for stdlib crates when rolling Rust

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

1. Checkout the git revision you want to generate from in //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.
2. Update dependencies for the stdlib with tools/rust/build_rust.py --update-deps.
3. Build gnrt to run on host machine: cargo build --release --manifest-path tools/crates/gnrt/Cargo.toml --target-dir out/gnrt.
4. Run gnrt with the gen action: out/gnrt/release/gnrt gen --for-std=third_party/rust_src/src.