DOCSEARCHbyAlgolia
Submit Docs

flutter_rust_bridge

repository·master·Indexed 26 days ago

https://github.com/fzyzcjy/flutter_rust_bridge

A feature-rich binding generator that enables seamless communication between Flutter (Dart) and Rust. It allows developers to leverage Rust's performance and safety within Flutter applications, supporting arbitrary types, async Rust, two-way communication, and high-performance SSE codecs. The toolset includes flutter_rust_bridge_codegen for generating Dart bridge code and supports integration via Cargokit and native assets.

Tokens
123.7K
Snippets
337
Records
719
Agent score
89%

What's inside flutter_rust_bridge

  1. High-level design for library integration

    master

    A complete library integration setup involves several components:

    1. Dart-only library: The core logic.
    2. Flutter library: A wrapper around the Dart-only library.
    3. CI/CD (GitHub Actions):
      • Automated unit and integration testing across all supported Flutter platforms.
      • Automated release creation (GitHub releases and pub.dev).
    4. Custom build system: To cross-compile to all supported Flutter platforms.

    Note on Platform Requirements:

    • To compile for macOS/iOS locally, you need a Mac.
    • You can use CI/CD to handle compilation and releases if you do not have a Mac.
    • The build system can cross-compile to other Flutter platforms regardless of your local development device.

  2. Understand the Flutter Rust Bridge project directory structure

    master

    When working with a project generated by flutter_rust_bridge, the directory structure follows a specific pattern to separate Dart, Rust, and auto-generated glue code:

    Dart Side (/lib)

    • main.dart: The entrypoint for your Flutter application.
    • src/rust: Contains the auto-generated glue code that mirrors your Rust crate structure. This is what you interact with from the Dart side.

    Rust Side (/rust)

    • src/api/: The primary location for writing your Flutter-facing Rust code. You can place your API definitions anywhere within this folder.
    • frb_generated.*.rs: Auto-generated glue code used by the Rust side to facilitate communication.

    Build/Glue Folders (Ignore these)

    Depending on your build tool, you may see folders used for backend glue to build Rust with Flutter. You should generally ignore these:

    • /rust_builder: Used when using Cargokit.
    • /hook: Used when using Native Assets.

  3. Understand the recommended repository structure

    master

    When organizing a project with flutter_rust_bridge, the following structure is recommended for a library named library_name:

    • packages/
      • library_name/: The Dart-only (library) package.
        • native/: The Rust library used by Dart.
        • test/: Unit tests for the Dart library.
        • example/: An example project demonstrating usage of library_name in Dart.
      • flutter_library_name/: The Flutter (library) package wrapping library_name.
        • android/, ios/, linux/, macos/, windows/: Platform-specific wrappers for bundling binaries.
        • test/: Unit tests for the Flutter library.
        • example/: An example project showing how to use flutter_library_name in a Flutter app.
          • integration_test/: Tests ensuring the Flutter library, example, and platform configurations work together.
    • scripts/: Build scripts for Flutter binaries and releases.
    • platform-build/: Output folder for created Flutter binaries.
    • analysis_options.yaml: Dart analysis configuration.
    • Cargo.toml: Rust project configuration (placed at root so IDEs find the Rust project in packages/library_name/native).
    • melos.yaml: Monorepo configuration.

  4. Supported platforms for flutter_rust_bridge

    master

    The flutter_rust_bridge supports cross-platform development across six major platforms:

    • Native Platforms: Android, iOS, Windows, MacOS, and Linux.
    • Web Platform: Web (note that the Web platform has specific technical characteristics that differ from the five native platforms).

    While the native platforms share a similar API surface, the Web platform may require specific considerations, though the library provides uniformed APIs to bridge this gap.

  5. Understand the safety and CI practices of flutter_rust_bridge

    master

    The project maintains high safety standards through extensive Continuous Integration (CI) testing. The CI pipeline includes:

    • Memory Safety Checks: Uses Valgrind and sanitizers (ASAN, MSAN, LSAN) to detect memory issues.
    • Multi-platform Testing: Runs tests on Android, iOS, Windows, MacOS, Linux, and Web.
    • Code Quality: Runs flutter_rust_bridge_codegen, linters, code formatters, and performance benchmarks.
    • Post-release Verification: Checks released binaries via post-release tests.

    Users can rely on the library's stability, as it is designed to minimize undefined behavior and memory issues through these automated checks.

  6. Common use cases for Flutter and Rust

    master

    You can use flutter_rust_bridge to achieve the following scenarios:

    • Use arbitrary Rust libraries in Dart: Access Rust-only libraries from your Dart code.
    • High-performance code in Rust: Offload multi-threaded code, complex algorithms, or data-intensive operations to Rust.
    • Logic in Rust, UI in Dart: Use Flutter as the UI framework for a system where the core logic resides in Rust.

  7. Project structure for a flutter_rust_bridge package with native assets

    master

    When using flutter_rust_bridge with native assets in a Flutter package, the project is organized into the following directories:

    • rust: The Rust crate containing the core logic.
    • hook: Contains the native assets build hook.
    • lib: Contains the Dart API and the generated bridge code.
    • example: A Flutter application used to test and demonstrate the package.

  8. Understand the role of flutter_rust_bridge

    master
    The flutter_rust_bridge library is a code generator designed to facilitate calling Rust functions from Flutter/Dart. It automates the generation of the boilerplate code required for FFI (Foreign Function Interface) communication. It does not replace the need for basic familiarity with Flutter/Dart, Rust, or FFI concepts.

  9. Key features of flutter_rust_bridge v2

    master

    The v2 release introduces several major improvements over v1:

    • Rapid Setup: One-liner command for project integration.
    • Arbitrary Types: Use Rust and Dart types without manual serialization or cloning intervention.
    • Async Rust: Support for async fn in Rust, alongside sync/async Dart support.
    • Two-way Communication: Rust can now call Dart functions (previously only Dart could call Rust).
    • Folder-based Inputs: Support for providing entire folders as inputs instead of single files.
    • Advanced Rust Support: Experimental support for parsing third-party packages, lifetimes, and traits.
    • High Performance: A new SSE codec that is significantly faster for certain workloads.

  10. Understand Arbitrary vs Translatable types in flutter_rust_bridge

    master

    When defining types for use between Rust and Dart, flutter_rust_bridge categorizes them into two main types:

    1. Arbitrary Types: These are types that are not directly encodable or cloneable (e.g., types requiring handles to native resources). On the opposite side, they appear as "opaque" handles (similar to fancy pointers). You can pass them as function arguments, return them, or call methods on them.

    2. Translatable Types: These are types (such as structs and enums) that are automatically converted into native Dart types. For example, a Rust struct A { name: String, children: Vec<A> } is translated into a Dart class A { String name; List<A> children; }, where all values are properly converted to their Dart equivalents.

  11. Safety and Reliability of flutter_rust_bridge

    master

    The reliability of flutter_rust_bridge is maintained through several automated verification layers:

    • Memory Safety: The CI automatically runs Valgrind on Dart-to-Rust calls to detect memory problems. Note that Valgrind may report many errors related to the Dart runtime itself (see Dart lang issue #47346); focus on "definitely lost" memory and errors specifically related to the library.
    • Integration Testing: Flutter integration tests are executed in CI to ensure the library functions correctly within real Flutter applications.
    • Code Quality: The CI runs fmt, clippy, dart analyze, and dart format to catch common issues and maintain code standards.
    • Codegen Verification: The run_codegen workflow is part of the CI to ensure the code generator consistently produces valid, compilable results.
    • Production Proven: The library is used in production within the yplusplus (or why++) Flutter application.

  12. Project structure for flutter_package_native_assets

    master

    This package follows a specific structure to manage Rust code, native asset hooks, and Dart bindings:

    • rust: The Rust crate containing the core logic.
    • hook: Contains the native assets build hook used by Flutter.
    • lib: Contains the Dart API and the generated bridge code.
    • example: A Flutter application used to demonstrate and test the package.