Toolchain and Infrastructure

This repository uses a pinned, hermetic toolchain managed via CIPD (infra/cipd.ensure) for compiling, testing, and formatting code. The toolchain versions (Rust, Clang/LLVM, GCC, and bindgen) are kept in sync with the fuchsia.git toolchain.

Setting Up the Environment

Before compiling, testing, or formatting code in this repository, always set up the shell environment to use the infra versions of the toolchain rather than system-installed or rustup (~/.cargo/bin) tools:

  • Bash / Zsh:
    source infra/env_setup.sh
  • Fish:
    source infra/env_setup.fish

Sourcing these scripts ensures the CIPD packages are present in infra/packages and prepends infra/packages/bin and infra/packages to PATH.

Note for AI Agents: Always ensure infra/env_setup.sh is sourced (or infra/packages/bin is prepended to PATH) before running cargo or other build/test commands so that you use the infra versions of the toolchain.

Building and Testing Rust Crates

The Rust workspace is located in the rust/ directory. When running cargo commands from the repository root, pass --manifest-path rust/Cargo.toml (or run cargo from within the rust/ directory):

cargo build --manifest-path rust/Cargo.toml
cargo test --manifest-path rust/Cargo.toml

Formatting Code (cargo fmt)

Always use cargo fmt instead of invoking rustfmt directly in this repository:

# From the repository root:
cargo fmt --manifest-path rust/Cargo.toml

# Or from within the rust/ directory:
cargo fmt

To check formatting without modifying files (as done in presubmit):

cargo fmt --manifest-path rust/Cargo.toml -- --check

Why cargo fmt instead of rustfmt?

  • Toolchain consistency: cargo fmt (when run with the infra versions of the toolchain) uses the pinned rustfmt binary from infra/packages/bin rather than a host rustup binary.
  • Configuration discovery: cargo fmt automatically locates and applies rust/rustfmt.toml, which configures edition 2024 and nightly formatting options (wrap_comments = true, use_small_heuristics = "Max", etc.) that match downstream repositories. Running rustfmt directly on individual files can miss these settings or fail on unstable options if the wrong binary is invoked.