flutter_rust_bridge

Crates.ioflutter_rust_bridge
lib.rsflutter_rust_bridge
version2.0.0-dev.37
sourcesrc
created_at2021-10-06 14:12:42.999352
updated_at2024-05-30 10:06:14.103148
descriptionHigh-level memory-safe binding generator for Flutter/Dart <-> Rust
homepage
repositoryhttps://github.com/fzyzcjy/flutter_rust_bridge
max_upload_size
id461194
size420,533
fzyzcjy (fzyzcjy)

documentation

README

flutter_rust_bridge v2: Flutter/Dart <-> Rust binding generator, feature-rich, but seamless and simple.

Rust Package Flutter Package Stars CI Post-Release codecov All Contributors Codacy Badge

Logo

What's new in V2

Click to expand
  • Rapid setup: Only a one-liner command to integrate into your project.
  • Arbitrary types: Use arbitrary Rust and Dart types without manual intervention, even if they are not serializable or non-clone (previously need some manual intervention).
  • Async Rust: Support asynchronous Rust (async fn), in addition to sync Rust / async Dart / sync Dart.
  • Rust call Dart: Allow Rust to call Dart functions (previously only allow Dart to call Rust).
  • Support whole folders as inputs: Previously only support one single file (e.g. api.rs).
  • Use libraries/tools in Flutter/Rust: All existing libraries, Flutter debuggers, ... Nothing to stop you from using them.
  • New codec: A new codec, SSE, which is several times faster under typical workload.

Please visit this page for more information and update guide.

I want to keep it in beta for a while (though CI has all passed), to allow publishing API breaking changes, and hear your thoughts and suggestions about it!

๐Ÿ€ What's this?

  • Just write down some normal Rust code (even with arbitrary types, closure, &mut, async, etc)
  • And call it from Flutter, as if Rust code is normal Flutter code
  • The bridge will generate all needed glues in between

๐Ÿ“š Quickstart

Create a working Flutter + Rust app and see it live, by running:

cargo install 'flutter_rust_bridge_codegen@^2.0.0-dev.0' && \
    flutter_rust_bridge_codegen create my_app && cd my_app && flutter run

(Optional) Edit rust/src/api/simple.rs (e.g. Hello -> Hi), then see the change by:

flutter_rust_bridge_codegen generate && flutter run

For more elaborated quickstart, please visit this page.

๐Ÿš€ Advantages

1. Officially Flutter Favorite

This package is officially Flutter Favorite, and is in the first batch of 7 packages at its rebooting.

2. Simplicity

  • Rapid setup: Only a one-liner command to integrate into your project.
  • Write your code naturally: Use your intuition and write the code you want. The bridge understands many advanced grammars (see below), allowing seamless calling Rust from Dart.
  • Use libraries/tools in Flutter/Rust: All existing libraries, Flutter debuggers, ... Nothing to stop you from using them.
  • Battery included: Even small things like logging and enable backtraces are configured in the starter kit.

3. Powerfulness

  • Arbitrary types: Use arbitrary Rust and Dart types without manual intervention, even if they are not serializable or non-clone.
  • Async & sync x Rust & Dart: Multi modes for various needs - Async Dart to avoid blocking the main thread, sync Dart for places needed (e.g. Widget.build); async Rust for IO bound tasks, thread pools for CPU-heavy computations.
  • Two-way road: Not only can Dart call Rust - Rust can also call Dart.
  • Auto-translatable types: Lots of types can be further translated to Dart native types, e.g. complex enums and structs, zero-copy big arrays, errors (Result), and Streams (iterator).
  • Auto safety: Focus on your code, and forget memory safety, malloc/free, or undefined behavior completely.
  • Customizable & bare-metal mode: Provide sensible defaults, but everything (loader, handler, ...) can be customized. You can even throw all away and only use the bare minimum calling.
  • Cross-platform: Support Android, iOS, Windows, Linux, MacOS, and Web.
  • Other features, e.g. support whole folders as input, pure-Dart compatible, instance and static methods, ...

4. Reliability

  • Solid CI: Valgrind & sanitizers (ASAN/MSAN/LSAN) for memory/UB-related bugs, testing per platform per mode, benchmarking, test coverage, post-release, etc, all guaranteed by CI.
  • Used by many people: See here for an incomplete list.
  • Easy to code-review & convince yourself: This package simply simulates how humans write boilerplate code. If you want to convince yourself (or your team) that it is safe, there is not much code to track.
  • Fast: It is only a thin (though feature-rich) wrapper, benchmarked on CI, and even has multiple codecs for best performance under different workloads.
  • Hackable: If (for whatever reason) you want to hack the source, there are contributor guides, code is modular, and the execution logic is intuitive.
  • Ask questions: Feel free to ask questions in the issue tracker, and I usually reply within hours (if not sleeping).

Why Flutter + Rust?

Click to expand

Firstly, super briefly introduce each component (you can find much more in a lot of blogs and posts):

  • Flutter: Cross-platform, hot-reload, rapid-development, flexible UI toolkit.
    • "The most popular cross-platform mobile SDK" (by StackOverflow [1][2]).
  • Rust: Highly efficient and performant, reliable, productive.
    • "The most desired programming language" for 8 years (by StackOverflow and GitHub [1][2]).

Typical scenarios to combine them include:

  • UI framework for Rust: When you want a UI framework for your Rust system.
  • Use arbitrary Rust libraries in Flutter: When the desired functionality only has a library in Rust, not Dart (Flutter).
  • Need high-performance code for Flutter: Rust makes it easy and performant to write multi-thread code, algorithms, data-intensive operations, SIMD code, etc.
  • ...

๐Ÿงญ Show me the code

Example 1: Simple

Simple Rust...

fn f(a: String, b: Vec<String>) -> MyStruct { ... }

...called from Dart, without manual intervention.

print(f(a: 'Hello', b: ['Tom']));

Example 2: Show off skills ;)

Let's see how fancy we can support:

// โ†ฑ Arbitrarily fancy Rust types
struct Garden { land: whatever::fancy::Land }

// โ†ฑ Complex but auto-translatable
enum Tree { A { name: (String, i32), children: Option<Vec<Tree>> }, B }

// โ†ฑ Support functions & methods
impl Garden {
    // โ†ฑ Allow async & sync Rust
    async fn plant(
        // โ†ฑ Support T/&T/&mut T
        &mut self,
        tree: Tree,
        // โ†ฑ Rust can also call Dart
        chooser: impl Fn(String) -> bool,
        // โ†ฑ Error translation ; zero copy
    ) -> Result<Vec<u8>, FancyError> {
        ...
    }
}

Still seamlessly call in Dart:

var tree = Tree.a(('x', 42), [Tree.b()]);
// โ†ฑ Async & sync Dart
print(await garden.plant(tree, (a) => true));

๐Ÿ’ก Documentation

Check out the documentation for quickstart, full guides and more.

๐Ÿ“Ž P.S. Achieve ~60 FPS, no matter how janky the Flutter app was due to build/layout

Here is my another open-source library :) https://github.com/fzyzcjy/flutter_smooth.

โœจ Acknowledgments and contributors

Firstly, I want to sincerely thank Dart, Flutter and Rust (alphabetical order). Dart provides a solid foundation for productive UI development, Flutter enables developers to make cross-platform apps with ease, and Rust empowers everyone to build reliable and efficient software. Without the languages and frameworks, this bridge connects absolutely nothing. Besides, I also want to express my thanks for conferring the official Flutter Favorite honor to the package. In addition, I also want to say thanks to the Dart, Flutter and Rust team members as well as community members, who have helped me during the development of flutter_rust_bridge by valuable discussions, insights, and actions.

Secondly, thanks goes to these wonderful contributors (emoji key following all-contributors specification):

fzyzcjy
fzyzcjy

๐Ÿ’ป ๐Ÿ“– ๐Ÿ’ก ๐Ÿค” ๐Ÿšง
Viet Dinh
Viet Dinh

๐Ÿ’ป โš ๏ธ ๐Ÿ“–
rogurotus
rogurotus

๐Ÿ’ป ๐Ÿ“–
Nicolas Gasull
Nicolas Gasull

๐Ÿ’ป
Joshua Wade
Joshua Wade

๐Ÿ’ป
Lattice 0
Lattice 0

๐Ÿ’ป ๐Ÿ“–
Unoqwy
Unoqwy

๐Ÿ’ป
Anton Lazarev
Anton Lazarev

๐Ÿ’ป
sagu
sagu

๐Ÿ’ป ๐Ÿ“–
Sebastian Urban
Sebastian Urban

๐Ÿ’ป
Rom's
Rom's

๐Ÿ’ป ๐Ÿ“–
่€่‘ฃ
่€่‘ฃ

๐Ÿ’ป ๐Ÿ“–
Gregory Conrad
Gregory Conrad

๐Ÿ“– ๐Ÿ’ป
huang12zheng
huang12zheng

๐Ÿ’ป ๐Ÿ“–
Daniel
Daniel

๐Ÿ’ป
Manuel Philipp
Manuel Philipp

๐Ÿ’ป ๐Ÿ“–
SoLongAnd...
SoLongAnd...

๐Ÿ’ป ๐Ÿ“–
hsfzxjy
hsfzxjy

๐Ÿ’ป
Cupnfish
Cupnfish

๐Ÿ’ป
alanlzhang
alanlzhang

๐Ÿ’ป ๐Ÿ“–
Erikas Taroza
Erikas Taroza

๐Ÿ’ป
่˜่˜
่˜่˜

๐Ÿ’ป
SimplyKyle!
SimplyKyle!

๐Ÿ’ป
Zaitam
Zaitam

๐Ÿ’ป
Brent Lewis
Brent Lewis

๐Ÿ’ป ๐Ÿ“–
nitn3lav
nitn3lav

๐Ÿ’ป ๐Ÿ“–
Kevin Li
Kevin Li

๐Ÿ’ป ๐Ÿ“–
Alex Procelewski
Alex Procelewski

๐Ÿ“– ๐Ÿ’ป
Daniel Porteous (dport)
Daniel Porteous (dport)

๐Ÿ“–
Andreas Monitzer
Andreas Monitzer

๐Ÿ’ป
Kim Dong-Hyun
Kim Dong-Hyun

๐Ÿ’ป ๐Ÿ“–
NightFeather
NightFeather

๐Ÿ’ป
ไนๆœˆ
ไนๆœˆ

๐Ÿ’ป
Krysl
Krysl

๐Ÿ’ป
Wouter Ensink
Wouter Ensink

๐Ÿ“–
Marcel
Marcel

๐Ÿ’ป
Aidan
Aidan

๐Ÿ“–
Debanjan Basu
Debanjan Basu

๐Ÿ“–
Patrick Auernig
Patrick Auernig

๐Ÿ’ป
Sai Chaitanya
Sai Chaitanya

๐Ÿ’ป
Xidorn Quan
Xidorn Quan

๐Ÿ’ป
jsonmona
jsonmona

๐Ÿ’ป
mtz
mtz

๐Ÿ’ป
codercengiz
codercengiz

๐Ÿ’ป
Michael Bryan
Michael Bryan

๐Ÿ’ป
Patrick Mukherjee
Patrick Mukherjee

๐Ÿ’ป
Aran Donohue
Aran Donohue

๐Ÿ’ป
Philip Kannegaard Hayes
Philip Kannegaard Hayes

๐Ÿ’ป
SilverMira
SilverMira

๐Ÿ’ป
Sander in 't Hout
Sander in 't Hout

๐Ÿ’ป
Haled Odat
Haled Odat

๐Ÿ’ป
็Ž‹ๅฎ‡้€ธ
็Ž‹ๅฎ‡้€ธ

๐Ÿ’ป
bus710
bus710

๐Ÿ“–
._.
._.

๐Ÿ“–
Marc Gutenberger
Marc Gutenberger

๐Ÿ’ป
Andrii Stadnik
Andrii Stadnik

๐Ÿ’ป
syndim
syndim

๐Ÿ’ป
Rhian Moraes
Rhian Moraes

๐Ÿ“–
Ares Andrew
Ares Andrew

๐Ÿ“–
polypixeldev
polypixeldev

๐Ÿ“–
CicadaCinema
CicadaCinema

๐Ÿ’ป ๐Ÿ“–
CosmicHorror
CosmicHorror

๐Ÿ’ป
Akash Gurava
Akash Gurava

๐Ÿ’ป
Fabian Lรถschner
Fabian Lรถschner

๐Ÿ’ป
Vincent Herlemont
Vincent Herlemont

๐Ÿ’ป
wxitcode
wxitcode

๐Ÿ“–
canxin
canxin

๐Ÿ’ป
pixelshot91
pixelshot91

๐Ÿ“–
TrackerSB
TrackerSB

๐Ÿ’ป
Dampfwalze
Dampfwalze

๐Ÿ“–
Samuel Cavalcanti
Samuel Cavalcanti

๐Ÿ“–
Roman Zaynetdinov
Roman Zaynetdinov

๐Ÿ“–
raphaelrobert
raphaelrobert

๐Ÿ“–
Mouayad Alhamwi
Mouayad Alhamwi

๐Ÿ“–
elliotsayes
elliotsayes

๐Ÿ“–
muji
muji

๐Ÿ“–
thomas725
thomas725

๐Ÿ“–
orange soeur
orange soeur

๐Ÿ“–
Alex Gorichev
Alex Gorichev

๐Ÿ“–
Sven-Hendrik Haase
Sven-Hendrik Haase

๐Ÿ“–
Chris Ohk
Chris Ohk

๐Ÿ“–
Vitalii Hurianov
Vitalii Hurianov

๐Ÿ“–
Sam Nystrom
Sam Nystrom

๐Ÿ“–
mattiasgronlund
mattiasgronlund

๐Ÿ’ป
Antonio D'souza
Antonio D'souza

๐Ÿ“–
max
max

๐Ÿ“–
Jonathan
Jonathan

๐Ÿ“–
Akash Jaiswal
Akash Jaiswal

๐Ÿ“–
Febrian Setianto
Febrian Setianto

๐Ÿ“–
Satvik Pendem
Satvik Pendem

๐Ÿ’ป
Damien Wise
Damien Wise

๐Ÿ“–
rustui
rustui

๐Ÿ“–
J
J

๐Ÿ“–
Ikko Ashimine
Ikko Ashimine

๐Ÿ“–
thesimplekid
thesimplekid

๐Ÿ“–

More specifically, thanks for all these contributions:

  • Desdaemon: Support not only simple enums but also enums with fields which gets translated to native enum or sealed freezed class in Dart. Support the Option type as nullable types in Dart. Support Vec of Strings type. Support tuple type. Support comments in code. Add marker attributes for future usage. Add Linux and Windows support for with-flutter example, and make CI works for that. Avoid parameter collision. Overhaul the documentation and add several chapters to demonstrate configuring a Flutter+Rust project in all five platforms. Refactor command module. Precompiled binary CI workflow. Fix bugs. Add support for the Web platform, parallel to the existing mobile/desktop platforms, via WASM and JavaScript as intermediate values. GitHub retry actions. Implement draft of opaque types. Refactor Boxed and Option. Impl list of dates and optionals. Parameter defaults. Refactor CLI. Refactor codegen errors. Refactor for performance.
  • rogurotus: Add Rust opaque types, enabling arbitrary Rust structs to be used as opaque Dart objects by generating wrappers and raw Arc pointers. Also add Dart opaque types, allowing to use any Dart objects in Rust code. Extend SyncReturn for more types. Fix generation bug. Fix SyncReturn. Migrate to dart-sys. Update CI. Fix linters. Fix SyncReturn bug.
  • ngasull: Make sync mode support whatever types that classical async mode supports. Bump sdk.
  • SecondFlight: Allow structs and enums to be imported from other files within the crate by creating source graph. Auto-create relevant dir. Fix store_dart_post_cobject error with ffigen 6.0.
  • lattice0: Implement hierarchy of exceptions. Support methods, such that Rust struct impls can be converted to Dart class methods. StreamSink at any argument.
  • Unoqwy: Add struct mirrors, such that types in the external crates can be imported and used without redefining and copying.
  • antonok-edm: Avoid converting syn types to strings before parsing to improve code and be more robust.
  • sagudev: Make code generator a lib. Add error types. Depend on cbindgen. Fix LLVM paths. Update deps. Fix CI errors.
  • surban: Support unit return type. Skip unresolvable modules. Ignore prefer_const_constructors. Non-final Dart fields.
  • Roms1383: Fix build_runner calling bug. Remove global ffigen dependency. Improve version check. Fix enum name-variant conflicts. Support Chrono date time and UUID types. Migrate to Rust 1.64 workspace. Update and refactor CI. Update header comments. Code cleanup.
  • dbsxdbsx: Allow generating multiple Rust and Dart files. Fix lint. Update doc. Add logging.
  • GregoryConrad: Add doc to setup frb inside a Dart/Flutter library.
  • huang12zheng: Support type aliases and nested ones. Tweak code generation. Fix rust_build_and_test on Mac. Improve CI logic and cache. Remove bridge field in model.
  • trobanga: Add support for [T;N] structs. Add usize support. Add a cmd argument. Separate dart tests. Fix fallible list case. Fix test compile. Fix Result + RustAutoOpaque.
  • MnlPhlp: Support macros and will auto expand. Allow mirror types in streams.
  • SoLongAndThanksForAllThePizza: Refactor and enhance SyncReturn to support more types. Refactor post-release CI.
  • hsfzxjy: Fix SyncReturn use-after-free bug.
  • Cupnfish: Support arrays as function parameters. Allow multi mirror.
  • alanlzhang: Add generation for Dart metadata. Enhance and fix module parser. Fix enum in struct. Fix linter. Improve hints.
  • erikas-taroza: Support list of primitive enums. Make enum camelCase. Warn wrong path. Fix cargo expand.
  • SiongSng: Finish implementing exception hierarchy. Fix SyncReturn bug.
  • JustSimplyKyle: Also finish implementing exception hierarchy. Allow ignore function.
  • Zaitam: Fix when method return struct. Partial migration to Dart 3.
  • coder0xff: Discuss binding unmodified Rust. Refactor SupportedInnerType. Extra codegen tester.
  • nitn3lav: Nested structs without Box.
  • AlienKevin: Add flutter example for macOS. Add doc for Android NDK bug. Improve migration doc.
  • alexthe2: Add Option Datetime. Add empty structs. Improve doc. Add r#. Fix mirror enum bug.
  • banool: Fix pubspec parsing. Fix symbol-stripping doc.
  • anlumo: Fix freezed + methods. Non-clone RustOpaque.
  • temeddix: Fix broken CI. Custom num workers. Fix MacOS doc steps. Update doc. Make zero-copy defaultable.
  • NightFeather0615: Fix Vec bool.
  • OfficialBoyfriend: Fix error display.
  • Krysl: Add preamble.
  • w-ensink: Improve doc. Fix CI. Refactor. Add tests.
  • smw-wagnerma: Improve Windows encoding handling.
  • powpingdone: Document JNI init and libc++_static linking.
  • debanjanbasu: Document alternative NDK init.
  • valeth: Rename callFfi's port.
  • sccheruku: Prevent double-generating utility.
  • upsuper: Refactor delegate-attr.
  • jsonmona: Add import.
  • MateusHBR: Add pub get.
  • codercengiz: Fix mirroring bug.
  • Michael-F-Bryan: Detect broken bindings.
  • patmuk: Set MSRV. Fail fast. Improve message. Improve docs.
  • aran: Fix map + mirror. Fix pubspec. Upgrde ffigen. Bump version. Fix typo.
  • phlip9: Fix no-serde compilation.
  • SilverMira: Fix StreamSink.
  • h3x4d3c1m4l: Fix when outside folder.
  • HalidOdat: Improve config method. Hint build.rs.
  • Berrysoft: Fix missing symbols.
  • bus710: Add a case in troubleshooting.
  • Demezy: Mention troubleshooting.
  • gutenfries: Bump proc-macros.
  • anstadnik: Check keywords.
  • syndim: Add a bracket to box.
  • rhian-cs: Add Cargo workspace doc.
  • TENX-S: Improve doc. Reproduce a bug.
  • polypixeldev: Improve doc.
  • CicadaCinema: Bump version. Improve doc.
  • CosmicHorrorDev: Change deps.
  • akashgurava: Partial fix.
  • w1th0utnam3: Improve message.
  • vincent-herlemont: Loosen version.
  • wxitcode: Add org option. Fix a typo.
  • canxin121: Fix permission.
  • pixelshot91: Update cargokit. Fix doc link.
  • TrackerSB: Bump allo-isolate.
  • Dampfwalze: Improve doc.
  • samuel-cavalcanti: Improve doc.
  • zaynetro: Improve doc.
  • raphaelrobert: Remove oudated doc.
  • DMouayad: Improve doc.
  • elliotsayes: Improve doc.
  • tmpfs: Improve doc.
  • thomas725: Improve doc.
  • juzi5201314: Improve doc.
  • Voklen: Improve doc.
  • svenstaro: Improve doc.
  • utilForever: Fix typos.
  • not-holar: Fix typos.
  • Stonks3141: Fix doc credit.
  • mattiasgronlund: Bump version.
  • adsouza: Fix doc grammar.
  • vimaxwell: Fix doc link.
  • lker-dev: Fix doc link.
  • jaiakash: Fix doc link.
  • feber: Fix doc link.
  • satvikpendem: Little co-work #989.
  • damywise: Fix a typo.
  • rustui: Fix a typo.
  • escwxyz: Fix a typo.
  • eltociear: Fix a typo.
  • thesimplekid: Fix a typo.
Commit count: 18783

cargo fmt