Using cargo on Fuchsia

Many tools in the Rust ecosystem assume you are using cargo. For tools like this, which don't have a counterpart in our build, there is a utility for generating Cargo.toml files. You can run cargo itself (cargo check for instance) using it.

This functionality is maintained by volunteers. GN and Cargo have some design mismatches that may result in the generated Cargo.toml files not working at all or needing manual tweaks. Because of this, cargo in the Fuchsia tree is not officially supported; things may break from time to time.

Generating Cargo.toml files

In order to generate the cargo files based on the build graph of GN, add --cargo-toml-gen to the fx set command or the //build/rust:cargo_toml_gen target to $OUT_DIR/args.gn's universe_package_labels. This adds a few seconds to gn gen. Make sure to run a full fx build after updating the setting:

fx set PRODUCT.BOARD --cargo-toml-gen <other fx args>
fx build

Note: If a Cargo.toml is required to complete an fx build, such as in the case cbindgen needs to be run to generate new C bindings for a Rust crate, you may need to use the //build/rust:cargo_toml_gen build target instead. This target will only build the Cargo.toml files.

Most editors require the Cargo.toml file to be in a location that is adjacent to the src/ directory. Symlinks to these files can be generated using the following commands, where //foo/path/to/target:some_label is the GN target that you want to work on:

fx gen-cargo foo/path/to/target:some_label

Note: The above will not work for rustc_staticlib targets, e.g. Rust crates used to generate C bindings generally use the rustc_staticlib target template. For rustc_staticlib targets, you should use the following command instead.

fx gen-cargo foo/path/to/target:_some_label_rustc_static

Note that this label must point to a rustc_... GN template (not a Fuchsia package or other GN target). For example:

rustc_binary("some_label") {
   ...
}

Generating .cargo/config files

Some plugins require a .cargo/config file to allow cargo to operate correctly for Fuchsia (e.g. to run cargo check). To easily generate this file, use the fargo tool.

  1. Install rustup

  2. Configure rustup to use the Fuchsia Rust toolchain by running:

    rustup toolchain link fuchsia $($FUCHSIA_DIR/scripts/youcompleteme/paths.py VSCODE_RUST_TOOLCHAIN)
rustup default fuchsia

  3. Clone and install the fargo tool within your $FUCHSIA_DIR by following the getting started instructions for fargo.

  4. Create your config:

    cd $FUCHSIA_DIR && fargo write-config
# Note the caveats about changing architecture in the fargo readme
# https://fuchsia.googlesource.com/fargo/#creating-a-cargo_config