# Rust

## Build

There are four GN target templates that should be used for Rust projects:

- [`rustc_library`](https://cs.opensource.google/fuchsia/fuchsia/+/main:/build/rust/rustc_library.gni "Rust library") defines a library and optionally a unit test target. The library can be depended on by other targets.
- [`rustc_binary`](https://cs.opensource.google/fuchsia/fuchsia/+/main:/build/rust/rustc_binary.gni "Rust binary") defines an executable and optionally a unit test target.
- [`rustc_test`](https://cs.opensource.google/fuchsia/fuchsia/+/main:/build/rust/rustc_test.gni "Rust test") defines a test-only target.
- [`rustc_macro`](https://cs.opensource.google/fuchsia/fuchsia/+/main:/build/rust/rustc_macro.gni "Rust proc macro") defines a [procedural macro](https://doc.rust-lang.org/reference/procedural-macros.html) target.

The [examples/rust](https://cs.opensource.google/fuchsia/fuchsia/+/main:/examples/rust/) directory has some examples of Rust
packages that use these targets, as do the [Rust FIDL examples](https://fuchsia.dev/docs/development/languages/fidl/tutorials/rust).

> [!NOTE]
> **Note:** The example [Rust BUILD.gn file](https://cs.opensource.google/fuchsia/fuchsia/+/main:/examples/rust/BUILD.gn) contains the line `group("rust")`. In this instance, `rust` refers to the directory the `.gn` file is in, not the language.

See also: [Build Fuchsia with a custom Rust toolchain](https://fuchsia.dev/fuchsia-src/build/rust_toolchain.md)

## Cargo.toml

Fuchsia Rust targets are not built with cargo. That said, you can
[generate Cargo.toml files](https://fuchsia.dev/fuchsia-src/development/languages/rust/cargo) for use with external tooling. This
functionality is not guaranteed to work.

### Autogenerated documentation

Once you have a Cargo.toml for your target you can generate and browse HTML
documentation for your target and its dependencies by running:

    fx rustdoc-link path/from/fuchsia/root/to/target:label

## Tests

You can run unit tests on connected devices using `fx`, with the `fx test
{package name}` command. See [Testing Rust code](https://fuchsia.dev/fuchsia-src/development/languages/rust/testing) for information
on adding and running tests.

## Procedural macros

Procedural macro targets are executed on the host at compile time. Therefore,
they cannot depend on other crates that 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.

## Warnings and errors

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 `deny_warnings` GN arg allows you to control this behavior in your development environment.
Setting `deny_warnings = false` in `fx args` or adding `--args=deny_warnings=false` to
your `fx set` will allow you to develop locally without being blocked by warnings. You can
add the argument to [`local/args.gn`](https://fuchsia.dev/docs/development/build/fx#defining-persistent-local-build-arguments) in your checkout so that it will be applied
to all builds without needing to type it in your terminal each time.

## Style

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](https://cs.opensource.google/fuchsia/fuchsia/+/main:/rustfmt.toml).

## Rust Idiomatic Usage Review

If you're new to Rust or would like someone to review your changes to
validate that your usage of Rust is idiomatic, add "Fuchsia Rust Reviewers"
as a reviewer to your CL in Gerrit and a reviewer will be assigned.

Email tq-rust-reviewers@google.com with any issues.

## Communication channels

Public discussion happens on the [rust-users@fuchsia.dev](https://groups.google.com/a/fuchsia.dev/g/rust-users) mailing list.

## Existing Fuchsia Rust libraries

- [List of crates](https://fuchsia.dev/docs/reference/rust/crates)
- [Autogenerated documentation for crates](https://fuchsia.dev/go/rustdoc/)

## Going further

- [Editor setup](https://fuchsia.dev/fuchsia-src/development/languages/rust/editors)
- [Measuring binary bloat](https://fuchsia.dev/fuchsia-src/development/languages/rust/bloat)
- [Managing external dependencies](https://fuchsia.dev/fuchsia-src/development/languages/rust/external_crates)
- [Unsafe code](https://fuchsia.dev/fuchsia-src/development/languages/rust/unsafe)
- [Unstable features](https://fuchsia.dev/fuchsia-src/development/languages/rust/unstable)
- [Rust FIDL server/client tutorial](https://fuchsia.dev/docs/development/languages/fidl/tutorials/rust)
- [Logging](https://fuchsia.dev/fuchsia-src/development/languages/rust/logging)

[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/development/languages/rust/README.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/development/languages/rust/README.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/development/languages/rust/README.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/development/languages/rust/README.md "Edit the source code of this page")