Fuchsia uses third-party Rust crates. They are placed in
This set of crates is based on the dependencies listed in
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:
- Calculate dependencies.
- Get Open Source Review Board (OSRB) approval.
- Upload the change for code review.
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.
Steps to add a third-party crate
- Change directory to Fuchsia repo base directory
- Add an entry in
third_party/rust_crates/Cargo.tomlfor the crate you want to add.
Run the following command to calculate the dependencies and download the crates:
This command downloads all crates listed in
rust_crates/Cargo.tomlas well as their dependencies, places them in the
vendordirectory, and updates
Do a build test. For example:
fx set core.x64 && fx build
Run the following command to update crate-map:
fx update-rustc-crate-map --output third_party/rust_crates/crate_map.json
This command updates
crate_map.jsonwith information about the Rust crates available for each target (Fuchsia and host). Note that this step uses information from the build step - make sure that the build for the
third_partyfolder has succeeded first before running this command. This would be part of the
fx buildyou are expected to run in the previous step.
Identify all the crates to be brought (see the diff in
//third_party/rust_crates/vendor/). Do not submit the CL for code review. Get OSRB approval first. If there are any files in the source repository that are not included when vendored, make a note of that for the OSRB reviewer. For example, font files that are only used for testing but are excluded when the crate is vendored. If you are not a Google employee, you will need to ask a Google employee to do this part for you.
After the OSRB approval, upload the change for review to Gerrit.
code-review+2and merge the change into third_party/rust_crates.
Steps to update a third-party crate
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
fx update-rustc-third-partyas above.
- Identify all new library dependencies brought in
(see the diff in
//third_party/rust_crates/vendor/). Again, do not submit the CL 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.
Adding a new mirror
- Request the addition of a mirror on fuchsia.googlesource.com.
- Add the mirror to the Jiri manifest for the Rust runtime.
- Add a patch section for the crate to the workspace.
- Run the update script.
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.
Grandfathered non-UNIC crates
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.
Rationale for standardization
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.
- Independently developed crates do not share a common release schedule, versioning scheme, or adherence to any particular version of the Unicode standard.
UNIC crates are generated from a consistent set of Unicode data files.
- Each of the independent crates uses an arbitrary version and subset of the data. For example, different crates might have different assumptions about whether a particular code point is assigned, what its properties are, etc.
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.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2019-12-11.