Upgrade Guide

Flutter/Rust Bridge Regeneration

Regenerate the bindings whenever a Rust function signature, struct, enum or module exposed to Dart changes.

# Match the codegen to the `flutter_rust_bridge` pin in
# third_party/OxidANT/Cargo.toml (`=2.13.0` today). A floating latest writes
# bindings the Rust runtime then refuses at load time.
cargo install --locked --version 2.13.0 flutter_rust_bridge_codegen
bash scripts/linux/generate-frb-bindings.sh

The wrapper requires a clean OxidANT checkout matching the index gitlink and refuses to overwrite changed generated files. It also rejects hidden Git index flags and ignored files in source input directories; ordinary model downloads and build caches are allowed. It then runs OxidANT's scripts/linux/frb-codegen.sh, which holds the one bridge input and flag set and takes only this app's Rust root and Dart output. That script requires the generator at the hub's FLUTTER_RUST_BRIDGE_VERSION, full cross-target locked Cargo metadata, a loader stem equal to the Rust library name, and matching Rust/Dart versions and content hashes. It writes both lib/src/rust/ and OxidANT's src/frb_generated.rs; commit and push OxidANT first, then move this repository's gitlink with the hub's pin-antfrastructure-submodule.py --path third_party/OxidANT and commit the Dart side with it. The first run installs cargo-expand 1.0.127 from its checksummed crate; offline generation also requires the full locked cross-platform Cargo cache.

Two gates keep the pair fresh. OxidANT's fmt-clippy step regenerates its Rust side and fails when it differs from the commit. Here, the frb-bindings job in linux-x64.yml runs verify-frb-bindings.py over the committed lib/src/rust/frb_generated.dart and the pinned third_party/OxidANT/src/frb_generated.rs on every push. It compares the loader stem, generator version and content hash; it does not regenerate, so it cannot see an API change that neither side picked up. OxidANT's step covers that.

Dependency Upgrades

Flutter, Rust and the bridge's codegen come from the build image, not from this repo: their versions are the hub's pins in third_party/ANTfrastructure/linux/scripts/01-core/versions.env (FLUTTER_VERSION, the Rust toolchains, FLUTTER_RUST_BRIDGE_VERSION). Moving one means a new image, then the hub pin here.

Submodules and manifests go through Renovate, report first: scripts/linux/renovate-local.sh on Linux, scripts\windows\Invoke-Renovate.ps1 on Windows (AGENTS.md § 5, Dependency upgrades).

Recommended order:

  1. One ecosystem at a time: Dart/Flutter, then Rust, then platform tooling.
  2. Static checks and tests after each step.
  3. Regenerate the docs and check for broken links and pages.

When upgrading flutter_rust_bridge on the Flutter side, the image's FLUTTER_RUST_BRIDGE_VERSION must move with it: the web lane installs the codegen only when the image has none, so it would build with the old one. Also run this in the Rust project, third_party/OxidANT, its own repository: commit there, then move the gitlink here (AGENTS.md § 3):

cargo upgrade --pinned --package flutter_rust_bridge

Validation Checklist

  • [ ] flutter analyze passes
  • [ ] Relevant tests pass
  • [ ] bash scripts/linux/generate-docs.sh succeeds
  • [ ] Streaming examples still run on at least one target device