fuchsia_custom_rust.md

Build Fuchsia with a custom Rust toolchain

This guide explains how to build Fuchsia with a custom Rust compiler. This is useful if you need to build Fuchsia with a patched compiler, or a compiler built with custom options.

Use another version of Rust

If all you need to do is use a different version than the one currently being used, most of this doc is not necessary. Fuchsia builders build Rust after every change to Rust's main branch.

1. Find the commit hash you want to use.

2. Run the following commands from your Fuchsia directory:

   # Replace COMMIT with the full Rust commit hash.
   # This command updates the manifests in the integration repo, which you can
   # then commit or revert as necessary.
   fx roll-compiler --package rust git_revision:{{ '<var>' }}COMMIT{{ '</var>' }}
   
   # Fetch the package versions you specified and install them in `prebuilt/`.
   jiri fetch-packages -local-manifest
   

3. Run the following command to build Fuchsia:

   fx build
   

   The Fuchsia build now uses the updated compiler.

   Note: A clean build is not necessary; the build automatically detects the new compiler version.

Prerequisites

Prior to building Fuchsia with a custom Rust toolchain, you need to do the following:

Note: These instructions are for Debian-based systems, but you should use the correct package manager for your machine.

1. Build a custom Rust toolchain for Fuchsia.

2. Complete the following guide to download the Fuchsia source: Get Fuchsia source code. To confirm that jiri is in your PATH run jiri -help.

   Note: The below commands assume DEV_ROOT is set to the parent directory of your Fuchsia checkout.

Build Fuchsia with your custom Rust toolchain

1. Change into your Fuchsia directory.

2. Run the following command to use the newly built toolchain:

   DEV_ROOT={{ '<var>' }}DEV_ROOT{{ '</var>' }}
   
   fx set core.x64 \
     --args=rustc_prefix="\"$DEV_ROOT/rust/install/fuchsia-rust\"" \
     --args=rustc_version_string='"1"'
   # plus other settings such as:
   #   --with //bundles:kitchen_sink
   #   --variant=coverage-rust  # to enable coverage profiling of fuchsia binaries
   #   --variant=host_coverage-rust  # to enable coverage profiling of host binaries
   

   Note: rustc_version_string can be any string, and it’s used to force a recompile after a custom toolchain changes. If you rebuild the toolchain, change the value so Rust targets get rebuilt.

3. Run the following command to rebuild Fuchsia:

   fx build