| # 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 {#cargo-toml-gen} |
| |
| 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: |
| |
| ```sh |
| 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: |
| |
| ```sh |
| 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. |
| |
| ```sh |
| fx gen-cargo foo/path/to/target:_some_label_rustc_static |
| ``` |
| |
| Note that this label must point to a [`rustc_...` GN template](README.md#build) |
| (not a Fuchsia package or other GN target). For example: |
| |
| ``` |
| rustc_binary("some_label") { |
| ... |
| } |
| ``` |
| |
| ### Generating .cargo/config files {#cargo-config-gen} |
| |
| 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`][fargo] tool. |
| |
| 1. [Install rustup](https://rustup.rs/) |
| 2. Configure `rustup` to use the Fuchsia Rust toolchain by running: |
| |
| ```sh |
| 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][fargo] for fargo. |
| 4. Create your config: |
| |
| ```sh |
| 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 |
| ``` |
| |
| [fargo]: https://fuchsia.googlesource.com/fargo/ |