From fceb069ca0c455bb58b070d78b63efafd3238bf3 Mon Sep 17 00:00:00 2001 From: fzyzcjy Date: Fri, 21 Jun 2024 12:57:02 +0800 Subject: [PATCH 1/5] chore: codegen --- website/docs/index.md | 105 +++++++++++++++++++++++++----------------- 1 file changed, 64 insertions(+), 41 deletions(-) diff --git a/website/docs/index.md b/website/docs/index.md index f4e7e7779c..e20e0a5d2e 100644 --- a/website/docs/index.md +++ b/website/docs/index.md @@ -23,27 +23,31 @@ hide_title: true ## 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. +Tap to expand + +* From 1.x to 2.0.0-dev.0: + * **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. +* From 2.0.0-dev.0 to 2.0.0: + * **Parsing third-party packages**: Scan and use existing Rust packages in Dart (experimental). + * **Lifetimes**: Support returning types with lifetime specifiers (experimental). + * **Traits**: Support traits as base classes and trait objects. + * **New codec**: A new codec, `SSE`, which is several times faster under some workloads. + * **Others (>200 PRs)**: Auto and manual accessors, object proxies, user-defined serializers, developer experience, deadlock-free auto locking, Rust initializers, included batteries, renaming and ignoring, improving streams, more types, ... Please visit [this page](https://fzyzcjy.github.io/flutter_rust_bridge/guides/miscellaneous/whats-new) 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) +* Just write down ***normal*** Rust code (even with arbitrary types, closure, `&mut`, async, traits, etc) * And call it from Flutter, as if Rust code is ***normal*** Flutter code -* The bridge will generate all needed glues in between +* The bridge will generate all glues in between ## 📚 Quickstart @@ -54,42 +58,61 @@ cargo install 'flutter_rust_bridge_codegen@^2.0.0-dev.0' && \ flutter_rust_bridge_codegen create my_app && cd my_app && flutter run ``` +
+Expand optional steps + **(Optional)** Edit `rust/src/api/simple.rs` (e.g. `Hello` -> `Hi`), then see the change by: ```shell flutter_rust_bridge_codegen generate && flutter run ``` +
+ For more elaborated quickstart, please visit [this page](https://fzyzcjy.github.io/flutter_rust_bridge/quickstart). ## 🚀 Advantages - + ### 1. Officially `Flutter Favorite` -This package is [officially Flutter Favorite](https://docs.flutter.dev/packages-and-plugins/favorites), and is in the first batch of 7 packages at its [rebooting](https://medium.com/flutter/whats-new-in-flutter-3-16-dba6cb1015d1). +This package is [officially Flutter Favorite](https://medium.com/flutter/progress-of-the-flutter-package-ecosystem-17cded9a0703), and is in the first batch of 7 packages at its rebooting. ([another link](https://medium.com/flutter/whats-new-in-flutter-3-16-dba6cb1015d1)) ### 2. Simplicity +
+(Tap to expand) Rapid setup, Write your code naturally, Use libraries/tools in Flutter/Rust, Battery included + * **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 +
+(Tap to expand) Arbitrary types, Async & sync, Two-way road, Auto-translatable types, Parsing third-party packages, Auto safety, Customizable & bare-metal mode, Cross-platform, ... + * **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 `enum`s and `struct`s, zero-copy big arrays, errors (`Result`), and `Stream`s (iterator). +* **Parsing third-party packages**: Scan and use existing Rust packages in Dart (experimental). * **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 +
+(Tap to expand) Solid CI, Used by many people, Easy to review, Fast, Hackable, Ask questions + * **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](https://fzyzcjy.github.io/flutter_rust_bridge/guides/users) 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. @@ -97,10 +120,12 @@ This package is [officially Flutter Favorite](https://docs.flutter.dev/packages- * **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 +Tap to expand Firstly, super briefly introduce each component (you can find much more in a lot of blogs and posts): @@ -118,57 +143,55 @@ Typical scenarios to combine them include:
-## 🧭 Show me the code +## ✨ Show me the code -### Example 1: Simple +### Example 1 Simple Rust... ```rust -fn f(a: String, b: Vec) -> MyStruct { ... } +fn f(a: String, b: Vec) -> MyStruct { ... } ``` ...called from Dart, without manual intervention. ```dart -print(f(a: 'Hello', b: ['Tom'])); +print(f(a: 'Hello', b: [MyEnum.c('Tom')])); ``` -### Example 2: Show off skills ;) +### Example 2 -Let's see how fancy we can support: +Suppose we implement a word dictionary in Rust: ```rust // ↱ Arbitrarily fancy Rust types -struct Garden { land: whatever::fancy::Land } - -// ↱ Complex but auto-translatable -enum Tree { A { name: (String, i32), children: Option> }, B } +pub struct WordDict { .. } // ↱ 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, FancyError> { - ... - } +impl WordDict { + // ↱ Can call Dart back ↱ Translate errors + pub fn open(chooser: impl Fn(String) -> bool) -> Result { .. } + + // ↱ Support async & sync Dart; property getter + #[frb(sync, getter)] + // ↱ Support T/&T/&mut T + pub fn size(&self) -> u32 { .. } + + // ↱ Allow async & sync ↱ Support stream (iterator) + pub async fn search(&self, keyword: String, sink: StreamSink) { .. } } ``` Still seamlessly call in Dart: ```dart -var tree = Tree.a(('x', 42), [Tree.b()]); -// ↱ Async & sync Dart -print(await garden.plant(tree, (a) => true)); +final dict = await WordDict.open((situation) => true); +print(dict.size); +await for (final value in dict.search('something')) { print(value); } ``` +There are still many features not covered here, such as parsing third party packages, lifetimes, traits, auto accessors, proxies, etc. + ## 💡 Documentation Check out [the documentation](https://fzyzcjy.github.io/flutter_rust_bridge/) for [quickstart](https://fzyzcjy.github.io/flutter_rust_bridge/quickstart), [full guides](https://fzyzcjy.github.io/flutter_rust_bridge/guides) and more. From 8642a1b0651e123140cc44ae11df39ac42572ab2 Mon Sep 17 00:00:00 2001 From: fzyzcjy Date: Fri, 21 Jun 2024 13:01:02 +0800 Subject: [PATCH 2/5] chore: more --- .github/workflows/post_release.yaml | 4 ++-- README.md | 3 +-- website/docs/guides/custom/codegen.md | 3 +-- .../docs/guides/miscellaneous/upgrade/regular.md | 2 +- website/docs/index.md | 3 +-- website/docs/quickstart.md | 14 +++----------- 6 files changed, 9 insertions(+), 20 deletions(-) diff --git a/.github/workflows/post_release.yaml b/.github/workflows/post_release.yaml index 7f431ec990..69caf90cbd 100644 --- a/.github/workflows/post_release.yaml +++ b/.github/workflows/post_release.yaml @@ -30,8 +30,8 @@ jobs: codegen_install_mode: - cargo-install - cargo-binstall - # - scoop # TODO enable after 2.0.0 stable release - # - homebrew # TODO enable after 2.0.0 stable release + - scoop + - homebrew exclude: - { image: windows-2019, codegen_install_mode: homebrew } - { image: macos-11, codegen_install_mode: scoop } diff --git a/README.md b/README.md index c32e7a50ba..c0cbb94c25 100644 --- a/README.md +++ b/README.md @@ -47,8 +47,7 @@ Please visit [this page](https://fzyzcjy.github.io/flutter_rust_bridge/guides/mi Create a working Flutter + Rust app and see it live, by running: ```shell -cargo install 'flutter_rust_bridge_codegen@^2.0.0-dev.0' && \ - flutter_rust_bridge_codegen create my_app && cd my_app && flutter run +cargo install flutter_rust_bridge_codegen && flutter_rust_bridge_codegen create my_app && cd my_app && flutter run ```
diff --git a/website/docs/guides/custom/codegen.md b/website/docs/guides/custom/codegen.md index 8b78b576c6..f0987062a0 100644 --- a/website/docs/guides/custom/codegen.md +++ b/website/docs/guides/custom/codegen.md @@ -35,8 +35,7 @@ which is often sufficient. The parameter names are the same as the one shown in command line help, except that there are no `no_` negations here. You can also refer to the fields of -[this struct](https://docs.rs/flutter_rust_bridge_codegen/2.0.0-dev.0/lib_flutter_rust_bridge_codegen/codegen/struct.Config.html) -(may need to switch to latest version) +[this struct](https://docs.rs/flutter_rust_bridge_codegen/latest/lib_flutter_rust_bridge_codegen/codegen/struct.Config.html) for parameter names. Anyway, if a wrong name is provided, it will be immediately recognized and reported. diff --git a/website/docs/guides/miscellaneous/upgrade/regular.md b/website/docs/guides/miscellaneous/upgrade/regular.md index 892ae61a7c..16750d666c 100644 --- a/website/docs/guides/miscellaneous/upgrade/regular.md +++ b/website/docs/guides/miscellaneous/upgrade/regular.md @@ -8,5 +8,5 @@ Everything (the Dart and Rust flutter_rust_bridge dependency) will be automatica Suppose you installed the codegen by the standard `cargo install`, then just run: ```shell -cargo install 'flutter_rust_bridge_codegen@^2.0.0-dev.0' && flutter_rust_bridge_codegen generate +cargo install flutter_rust_bridge_codegen && flutter_rust_bridge_codegen generate ``` diff --git a/website/docs/index.md b/website/docs/index.md index e20e0a5d2e..2c61ec3ee7 100644 --- a/website/docs/index.md +++ b/website/docs/index.md @@ -54,8 +54,7 @@ Please visit [this page](https://fzyzcjy.github.io/flutter_rust_bridge/guides/mi Create a working Flutter + Rust app and see it live, by running: ```shell -cargo install 'flutter_rust_bridge_codegen@^2.0.0-dev.0' && \ - flutter_rust_bridge_codegen create my_app && cd my_app && flutter run +cargo install flutter_rust_bridge_codegen && flutter_rust_bridge_codegen create my_app && cd my_app && flutter run ```
diff --git a/website/docs/quickstart.md b/website/docs/quickstart.md index c2838cec3c..35590ac6b8 100644 --- a/website/docs/quickstart.md +++ b/website/docs/quickstart.md @@ -8,7 +8,7 @@ import TabItem from '@theme/TabItem'; If you like to setup in one command: ```shell -cargo install 'flutter_rust_bridge_codegen@^2.0.0-dev.0' && flutter_rust_bridge_codegen create my_app && cd my_app && flutter run +cargo install flutter_rust_bridge_codegen && flutter_rust_bridge_codegen create my_app && cd my_app && flutter run ``` ::: @@ -24,7 +24,7 @@ install `flutter_rust_bridge` using any method: ```shell -cargo install 'flutter_rust_bridge_codegen@^2.0.0-dev.0' +cargo install flutter_rust_bridge_codegen ``` @@ -32,17 +32,13 @@ cargo install 'flutter_rust_bridge_codegen@^2.0.0-dev.0' ```shell -cargo binstall 'flutter_rust_bridge_codegen@^2.0.0-dev.0' +cargo binstall flutter_rust_bridge_codegen ``` -:::caution -It installs v1 instead of v2.0.0-dev.x currently, so please wait a bit until the v2.0.0 stable is released :) -::: - Remark: Thanks @Desdaemon for scripts to publish to brew/scoop ```shell @@ -54,10 +50,6 @@ scoop install flutter_rust_bridge_codegen -:::caution -It installs v1 instead of v2.0.0-dev.x currently, so please wait a bit until the v2.0.0 stable is released :) -::: - Remark: Thanks @Desdaemon for scripts to publish to brew/scoop ```shell From 546c5c6bb8ce8424ce36e22e77ce9971247d66a4 Mon Sep 17 00:00:00 2001 From: fzyzcjy Date: Fri, 21 Jun 2024 13:10:19 +0800 Subject: [PATCH 3/5] chore: temp rm --- website/docs/quickstart.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/website/docs/quickstart.md b/website/docs/quickstart.md index 35590ac6b8..c5ef0d5309 100644 --- a/website/docs/quickstart.md +++ b/website/docs/quickstart.md @@ -37,6 +37,8 @@ cargo binstall flutter_rust_bridge_codegen + + ## 2. Create new projects / Add to existing projects From 5bbabe884fbe3108d1c181291c395b98edacf6f2 Mon Sep 17 00:00:00 2001 From: fzyzcjy Date: Fri, 21 Jun 2024 13:13:11 +0800 Subject: [PATCH 4/5] Revert "Auxiliary commit to revert individual files from 8642a1b0651e123140cc44ae11df39ac42572ab2" This reverts commit a32c2b951592eaca231984452a58fdc04d05afb6. --- .github/workflows/post_release.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/post_release.yaml b/.github/workflows/post_release.yaml index 69caf90cbd..7f431ec990 100644 --- a/.github/workflows/post_release.yaml +++ b/.github/workflows/post_release.yaml @@ -30,8 +30,8 @@ jobs: codegen_install_mode: - cargo-install - cargo-binstall - - scoop - - homebrew + # - scoop # TODO enable after 2.0.0 stable release + # - homebrew # TODO enable after 2.0.0 stable release exclude: - { image: windows-2019, codegen_install_mode: homebrew } - { image: macos-11, codegen_install_mode: scoop } From 031d8b9243c10ac351b2c893635f6fca66a65a52 Mon Sep 17 00:00:00 2001 From: fzyzcjy Date: Fri, 21 Jun 2024 13:15:29 +0800 Subject: [PATCH 5/5] chore: more --- .../docs/guides/miscellaneous/whats-new.md | 34 ++++++++++++++----- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/website/docs/guides/miscellaneous/whats-new.md b/website/docs/guides/miscellaneous/whats-new.md index d9f9e6da0b..541fd25189 100644 --- a/website/docs/guides/miscellaneous/whats-new.md +++ b/website/docs/guides/miscellaneous/whats-new.md @@ -1,5 +1,9 @@ # What's new in V2 +## Upgrade guide + +To upgrade, please refer to [the upgrade guide](upgrade/v2). + ## Changelog :::tip @@ -9,16 +13,26 @@ where there are lists of features (advantages) and a quick show-me-the-code. ### Primary changes -* **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. +* From 1.x to 2.0.0-dev.0: + * **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. +* From 2.0.0-dev.0 to 2.0.0: + * **Parsing third-party packages**: Scan and use existing Rust packages in Dart (experimental). + * **Lifetimes**: Support returning types with lifetime specifiers (experimental). + * **Traits**: Support traits as base classes and trait objects. + * **New codec**: A new codec, `SSE`, which is several times faster under some workloads. + * **Others (>200 PRs)**: Auto and manual accessors, object proxies, user-defined serializers, developer experience, deadlock-free auto locking, Rust initializers, included batteries, renaming and ignoring, improving streams, more types, ... ### More changes +#### From 1.x to 2.0.0-dev.0 + +
+ * Overhaul the whole internal codebase * Making it clear / modualized / elegant, enabling quick development of future features * Unsafe code are further mimimalized and encapsulated @@ -42,6 +56,8 @@ where there are lists of features (advantages) and a quick show-me-the-code. * Automatically install `cargo expand` if not installed. * Fix bugs. -## Upgrade guide +
-To upgrade, please refer to [the upgrade guide](upgrade/v2). +#### From 2.0.0-dev.0 to 2.0.0 + +Please refer to the CHANGELOG for >200 PRs.