docs/development/languages/rust/README.md

# Rust

## Build

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

- [`rustc_library`][target-library-rustc] defines a library and optionally a
  unit test target. The library can be depended on by other targets.
- [`rustc_binary`][target-binary-rustc] defines an executable and optionally a
  unit test target.
- [`rustc_test`][target-test-rustc] defines a test-only target.
- [`rustc_macro`][target-macro-rustc] defines a
  [procedural macro][rust-proc-macros] target.

The [examples/rust][rust-examples] directory has some examples of Rust
packages that use these targets, as do the [Rust FIDL examples][fidl-tutorial].

### Building with a custom toolchain

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\""
```

## Cargo.toml

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`][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:

```sh
$ fx set --cargo-toml-gen <other flags and product config ...>
$ 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.

## Autogenerated docs

You can generate and browse HTML documentation for your target and its
dependencies by running:

```sh
fx rustdoc path/from/fuchsia/root/to/target:label --open
```

## Tests

You can run unit tests on connected devices using `fx`, with the `fx test
{package name}` command.  See [Testing Rust code](testing.md) 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 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.

## Warnings & 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 `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.

## 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][rustfmt-toml].

## Rust Idiomatic Usage Review

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.)

- adamperry@google.com
- belgum@google.com
- bwb@google.com
- dnordstrom@google.com
- jamuraa@google.com
- nickpollard@google.com
- tmandry@google.com

(To volunteer for this, please add yourself to the list above and upload the
change with one of the above as the reviewer).

## Communication channels

Public discussion happens on the [rust@fuchsia.com] mailing list. For
Googler-only channels, see [go/fuchsia-rust-googlers].

## Existing Fuchsia Rust libraries

- [List of crates](crates.md)
- [Autogenerated documentation for crates](https://fuchsia-docs.firebaseapp.com)

## Going further

- [Editor setup](editors.md)
- [Measuring binary bloat](bloat.md)
- [Managing third-party dependencies](third_party.md)
- [Unsafe code](unsafe.md)
- [Unstable features](unstable.md)
- [Rust FIDL server/client tutorial][fidl-tutorial]
- [Logging](logging.md)
- [Add logging to hello world](add-logging.md)


[target-library-rustc]: /build/rust/rustc_library.gni "Rust library"
[target-binary-rustc]: /build/rust/rustc_binary.gni "Rust binary"
[target-test-rustc]: /build/rust/rustc_test.gni "Rust test"
[target-macro-rustc]: /build/rust/rustc_macro.gni "Rust proc macro"
[rust-examples]: /examples/rust/
[fargo]: https://fuchsia.googlesource.com/fargo
[rustfmt-install]: https://github.com/rust-lang-nursery/rustfmt#quick-start
[rustfmt-toml]: /rustfmt.toml
[fidl-tutorial]: /docs/development/languages/fidl/tutorials/tutorial-rust.md
[rust@fuchsia.com]: https://groups.google.com/a/fuchsia.com/forum/#!forum/rust-fuchsia
[go/fuchsia-rust-googlers]: https://goto.google.com/fuchsia-rust-googlers
[rust-proc-macros]: https://doc.rust-lang.org/reference/procedural-macros.html