Cargokit to Native Assets Migration

Purpose

Verify that an app created with the default Cargokit backend can be migrated to Native Assets by following the documented migration steps, and that its Flutter tests still pass on Linux.

Source

• Context: PR #3285
• Related docs or skills: website/docs/manual/integrate/05-migrate-cargokit-to-native-assets.md, .claude/skills/frb-manual-test/SKILL.md

When To Run

Run after changing the Cargokit-to-Native-Assets migration guide, either integration backend, or the create and integrate commands.

Preconditions

• Repository: fzyzcjy/flutter_rust_bridge
• Required checkout state: submodules initialized; intentional documentation or manual-test changes are allowed.
• Required credentials or account state: network access to Flutter, Dart, Cargo, and pub package sources.
• Required device or simulator state: Linux desktop support through the FRB Docker development environment.

Environment

• OS: Linux in the per-worktree FRB Docker container.
• Flutter: repository Docker image version; capture flutter --version.
• Dart: repository Docker image version; capture dart --version.
• Rust: repository Docker image version; capture rustc --version.
• Device or simulator: Linux desktop.
• Browser or external service: pub.dev and crates.io package sources.

Preparation

From the repository root:

git submodule update --init --recursive
.claude/skills/frb-dev-env/frb_dev_env.py docker create
.claude/skills/frb-dev-env/frb_dev_env.py docker exec -- flutter --version
.claude/skills/frb-dev-env/frb_dev_env.py docker exec -- dart --version
.claude/skills/frb-dev-env/frb_dev_env.py docker exec -- rustc --version

Test Data

• Input files, API examples, account fixtures, or generated assets: a fresh app named frb_migration_test, generated by the current checkout.
• Reset procedure before each run: remove /root/frb_manual_test_cargokit_migration inside the development container.

Steps

1. Confirm that tools/manual_tests/cargokit-to-native-assets-migration.md is aligned with website/docs/manual/integrate/05-migrate-cargokit-to-native-assets.md.

2. Create a default Cargokit app with the current code generator.

   bashCopy

   .claude/skills/frb-dev-env/frb_dev_env.py docker exec -- bash -lc '
   set -euxo pipefail
   rm -rf /root/frb_manual_test_cargokit_migration
   cargo run --manifest-path frb_codegen/Cargo.toml -- create /root/frb_manual_test_cargokit_migration --platforms linux --skip-fvm-install
   test -d /root/frb_manual_test_cargokit_migration/rust_builder/cargokit
   '
   

3. Run Native Assets integration and remove the old Cargokit package and analyzer exclusion.

   bashCopy

   .claude/skills/frb-dev-env/frb_dev_env.py docker exec -- bash -lc '
   set -euxo pipefail
   cd /root/frb_manual_test_cargokit_migration
   cargo run --manifest-path "$OLDPWD/frb_codegen/Cargo.toml" -- integrate --integration-backend native-assets --platforms linux --skip-fvm-install
   flutter pub remove rust_lib_frb_manual_test_cargokit_migration
   rm -rf rust_builder
   perl -0pi -e "s/analyzer:\n  exclude:\n    - rust_builder\/cargokit\/\*\*\n\n//" analysis_options.yaml
   test -f hook/build.dart
   grep -q 'crate-type.*cdylib.*staticlib' rust/Cargo.toml
   grep -q '^channel = "[0-9]' rust/rust-toolchain.toml
   test ! -e rust_builder
   ! grep -q rust_builder pubspec.yaml analysis_options.yaml
   '
   

4. Refresh dependencies, regenerate the bridge, and run the Flutter tests.

   bashCopy

   .claude/skills/frb-dev-env/frb_dev_env.py docker exec -- bash -lc '
   set -euxo pipefail
   cd /root/frb_manual_test_cargokit_migration
   flutter pub get
   cargo run --manifest-path "$OLDPWD/frb_codegen/Cargo.toml" -- generate
   xvfb-run -a flutter test integration_test/simple_test.dart -d linux
   '
   

Expected Result

• The manual test covers every migration-guide action in the same order.
• Cargokit exists before migration and is absent afterward.
• hook/build.dart exists after integration.
• rust/Cargo.toml has cdylib and staticlib crate types, and rust/rust-toolchain.toml pins a concrete toolchain.
• pubspec.yaml and analysis_options.yaml do not reference rust_builder.
• Code generation exits zero.
• The Linux integration test exits zero and prints All tests passed!.

Failure Criteria

The test fails if any of the following happens:

• The manual test and migration guide do not align.
• Project creation or Native Assets integration exits non-zero.
• The expected Cargokit or Native Assets files are absent at the corresponding checkpoint.
• A stale rust_builder reference remains.
• Dependency resolution, code generation, or Flutter tests exit non-zero.

Environment setup or package-source unavailability should be reported as blocked instead of a product failure.

Results To Capture

• Full terminal log for preparation and all steps.
• Flutter, Dart, and Rust versions.
• Exit status and success lines for code generation and the Linux integration test.
• Final checks for hook/build.dart, rust_builder, pubspec.yaml, and analysis_options.yaml.
• Final cleanup and repository status.

Troubleshooting

• If the development container is absent, rerun frb_dev_env.py docker create.
• If dependency resolution fails, capture the failing package source and proxy state before classifying the run.
• If Linux desktop dependencies are missing, record flutter doctor -v and classify the run as blocked.

Cleanup

.claude/skills/frb-dev-env/frb_dev_env.py docker exec -- rm -rf /root/frb_manual_test_cargokit_migration
git status --short

Future Automation

This scenario can move into the integrate-generation CI once that job can create, mutate, and test a disposable project without materially increasing its runtime.