There are four GN target templates which should be used for Rust projects:
rustc_library defines a library and optionally a unit test target. The library can be depended on by other targets.rustc_binary defines an executable and optionally a unit test target.rustc_test defines a test-only target.rustc_macro defines a procedural macro target.The examples/rust directory has some examples of Rust packages that use these targets, as do the Rust FIDL examples.
If you want to test out Fuchsia with your own custom-built versions of rustc or cargo, you can set the rustc_prefix argument to fx set, like this:
fx set core.x64 --release --args "rustc_prefix=\"/path/to/bin/dir\""
Fuchsia Rust targets are not built with Cargo. There is only partial support for Cargo.toml files. Having a Cargo.toml file for your target can be useful for using the fargo tool or other tools from the Rust 3p ecosystem.
A Cargo.toml file can be automatically generated for rustc_library and rustc_binary targets based on their .gn file definitions by running:
$ scripts/gn_to_cargo.py out/default/project.json $ fx gen-cargo path/from/fuchsia/root/to/target:label
Note that the label you use must be the GN label for a rustc_... GN template invocation, not a Fuchsia package or other GN rule.
You can generate and browse HTML documentation for your target and its dependencies by running:
fx rustdoc path/from/fuchsia/root/to/target:label --open
You can run unit tests on connected devices using fx, with the fx test {package name} command. See Testing Rust code for information on adding and running tests.
Procedural macro targets are executed on the host at compile time. Therefore, they cannot depend on other crates which are only available on device, e.g. zircon.
Negative tests, e.g. asserting that a macro fails to compile with a specific error, are currently not supported.
By default our build configuration makes all Rust warnings into errors. This requirement can be onerous during development, and on your local machine you may wish to see warnings as warnings and let CQ enforce the hard boundary.
The rust_cap_lints GN arg allows you to control this behavior in your development environment. Setting rust_cap_lints = "warn" in fx args or fx set will allow you to develop locally without being blocked by warnings.
We don't currently have a style guide for Rust, but you should run fx rustfmt or fx format-code before submitting. We mostly use the rustfmt defaults, but have a couple custom settings.
If you're new to Rust, and would like someone to review your changes to validate that your usage of Rust is idiomatic, contact one of the following (or add them as a reviewer to your change.)
(To volunteer for this, please add yourself to the list above and upload the change with one of the above as the reviewer).
Public discussion happens on the rust@fuchsia.com mailing list. For Googler-only channels, see go/fuchsia-rust-googlers.