Fuchsia uses third-party Rust crates. They are placed in //third-party/rust_crates/vendor
. This set of crates is based on the dependencies listed in //third_party/rust_crates/Cargo.toml
. If you don't find a crate that you want to use, you may bring that into Fuchsia.
To add a third-party crate, the steps are:
Pay attention to transitive dependencies: A third-party crate may depend on other third-party crates. List all the new crates that end up with being brought in, in the OSRB review. For OSRB, follow the instructions under the “Process for 3rd Party Hosted Code” section in this document.
Note: You MUST get OSRB approval first before uploading a change for review.
Change directory to Fuchsia repo base directory (For example, cd ~/fuchsia
).
Add an entry in third_party/rust_crates/Cargo.toml
for the crate you want to add.
Run the following command to calculate the dependencies and download the crates:
fx update-rustc-third-party
This command downloads all crates listed in rust_crates/Cargo.toml
as well as their dependencies, places them in the vendor
directory, and updates Cargo.toml
and Cargo.lock
.
You may need to provide additional configuration in a [gn.package.<crate>]
section inside the Cargo.toml file. For crates that use a build.rs
script this configuration replaces the script, which is (intentionally) unsupported by our build system. This configuration is used by cargo-gnaw, which generates the GN rules from the Cargo.toml file. See cargo-gnaw's README for more details.
Note: on Linux, pkg-config
needs to be installed.
Do a build test. For example:
fx set core.x64 && fx build
Do NOT upload the change to Gerrit for code review. Get OSRB approval first.
//third_party/rust_crates/vendor/
).Note: As part of OSRB review, you may be asked to import only a subset of the files in a third-party crate. See Importing a subset of files in a crate for how to do this.
Only after getting the OSRB approval, upload the change for review to Gerrit. Include the OSRB bug number in the change (e.g. Bug: “1234”).
Get code-review+2
and merge the change into third_party/rust_crates.
Updating is very similar to adding a crate.
To update a third-party crate, do the following:
Start by bumping the version number of the crate in third_party/rust_crates/Cargo.toml
and rerunning fx update-rustc-third-party
as above.
You may need to update or provide additional configuration in [gn.package.<crate>]
sections inside the Cargo.toml file. For crates that use a build.rs
script this configuration replaces the script, which is (intentionally) unsupported by our build system. This configuration is used by cargo-gnaw, which generates the GN rules from the Cargo.toml file. See cargo-gnaw's README for more details.
Identify all new library dependencies brought in (see the diff in //third_party/rust_crates/vendor/
). Again, do not submit the change for code review until you've received OSRB approval for any new dependencies added.
After OSRB approval, upload the change for review to Gerrit and merge as above.
In some cases, you may want to import only a subset of files in a crate. For example, there may be an optional license in the third-party repo that‘s incompatible with Fuchsia’s license requirements. Here's an example OSRB review in which this happened.
To do this, you‘ll need to add the crate’s files to /third_party/rust_crates/tiny_mirrors
.
fx update-rustc-third-party
, move the downloaded copy of your crate from /third_party/rust_crates/vendor/<my_crate>
to /third_party/rust_crates/tiny_mirrors
.[patch.crates-io]
section of /third_party/rust_crates/Cargo.toml
to point to your new crate:[patch.crates-io] ... my_crate = { path = "tiny_mirrors/my_crate" } ...
fx update-rustc-third-party
and fx build
.If the project requires importing a new third-party crate to handle functionality related to Unicode and internationalization, prefer crates from the UNIC project when available.
The following non-UNIC crates are already vendored and are grandfathered, but we will aim to migrate to UNIC equivalents when possible.
We should encourage upstream dependencies to migrate to UNIC as well.
UNIC crates have distinct advantages over other crates:
UNIC crates are developed in a single repo, with shared common code and a single version scheme.
UNIC crates are generated from a consistent set of Unicode data files.
The UNIC project is aiming for comprehensive feature coverage, to be like ICU for Rust. If the project succeeds, our dependencies on unrelated Unicode crates should be reduced over time.
We maintain OWNERS files for all of our third-party Rust crates to indicate who is responsible for their reviews and updates. These files are generated from a combination of build graph metadata and and an explicit override file.
The tool discovers which build targets depend on a given crate, which means it needs the metadata from the completion of a maximal “kitchen sink” build:
//bundles/buildbot:core
and //bundles:kitchen_sink
in your buildfx build
fx update-rust-3p-owners
Some crates have more users than can be relied upon to maintain the crate in good stead (see Bystander effect). Others implement behavior specific to a domain like security and we would prefer for a specific team to be responsible for reviews of the code.
In these cases, add an entry to //third_party/rust_crates/owners.toml
with the path(s) to other OWNERS files to reference, then re-run the tool. This will replace the reverse-dependency metadata ownership with the overridden paths.
A member of the Rust on Fuchsia team is currently responsible for running the tool on a regular cadence. See https://fxbug.dev/73348 to track the process of automating updates to OWNERS files.
After running fx update-rustc-third-party
, if you encounter an error like this:
Generating GN file from /$HOME/fuchsia/third_party/rust_crates/Cargo.toml Error: GNaw config exists for crates that were not found in the Cargo build graph: library crate, package handlebars version 2.0.0-beta.2 library crate, package core-foundation-sys version 0.7.0 library crate, package pulldown-cmark version 0.6.0 library crate, package nix version 0.18.0
You can fix this issue commenting out your fuchsia target in .cargo/config
:
[build] ... target = "x86_64-fuchsia"
After commenting, it becomes:
[build] ... # target = "x86_64-fuchsia"
This issue is being tracked upstream.