Merge pull request #442 from cunarist/various-tweaks

Apply various tweaks and write migration guides

documentation/docs/.pages

@@ -10,5 +10,6 @@ nav:
   - printing-for-debugging.md
   - graceful-shutdown.md
   - configuration.md
+  - upgrading.md
   - frequently-asked-questions.md
   - contribution.md

documentation/docs/frequently-asked-questions.md

@@ -203,7 +203,7 @@ message MyUniqueOutput {
 
 ```dart title="lib/main.dart"
 import 'dart:async';
-import 'package:example_app/messages/exports.dart';
+import 'package:example_app/messages/all.dart';
 
 var currentInteractionId = 0;
 final myUniqueOutputs = Map<int, Completer<MyUniqueOutput>>();
@@ -218,7 +218,7 @@ void main() async {
 
 ```dart title="lib/main.dart"
 import 'dart:async';
-import 'package:example_app/messages/exports.dart';
+import 'package:example_app/messages/all.dart';
 
 onPressed: () async {
   final completer = Completer<MyUniqueOutput>();
@@ -312,7 +312,7 @@ Failed to load dynamic library 'libhub.so': libhub.so: cannot open shared object
 In this case, you can specify a path that points to the compiled Rust library. Simply provide a string path to your dynamic library file.
 
 ```dart title="lib/main.dart"
-import './messages/exports.dart';
+import './messages/all.dart';
 
 async void main() {
   await initializeRust(compiledLibPath: '/path/to/library/libhub.so');

documentation/docs/state-management.md

@@ -16,9 +16,11 @@ Several crates on `crates.io` provide building blocks for implementing the actor
 
 Here’s a basic example using the [`actix`](https://github.com/actix/actix) crate, a popular choice for the actor model:
 
-```rust title="Rust"
+```rust title="native/hub/src/lib.rs"
 use actix::prelude::*;
 
+rinf::write_interface!()
+
 // this is our Message
 // we have to define the response type (rtype)
 #[derive(Message)]

documentation/docs/tutorial.md

@@ -37,7 +37,7 @@ rinf message
 Create a button widget in Dart that accepts the user input.
 
 ```dart title="lib/main.dart"
-import 'package:test_app/messages/exports.dart';
+import 'package:test_app/messages/all.dart';
 
 child: Column(
   mainAxisAlignment: MainAxisAlignment.center,
@@ -146,7 +146,7 @@ async fn main() {
 Finally, receive the signals in Dart with `StreamBuilder` and rebuild the widget accordingly.
 
 ```dart title="lib/main.dart"
-import 'package:test_app/messages/exports.dart';
+import 'package:test_app/messages/all.dart';
 
 children: [
   StreamBuilder(
@@ -184,7 +184,7 @@ rinf message
 ```
 
 ```dart title="lib/main.dart"
-import 'package:test_app/messages/exports.dart';
+import 'package:test_app/messages/all.dart';
 
 children: [
   StreamBuilder(

documentation/docs/upgrading.md

@@ -0,0 +1,42 @@
+# Upgrading Rinf
+
+## 🐾 Minor Upgrades
+
+Whenever upgrading Rinf, please ensure that the Rinf versions in `pubspec.yaml` and `native/hub/Cargo.toml` are identical.
+
+## 7️⃣ Migrating from 6 to 7
+
+The overall usage remains the same, but some changes have been made to the API to improve code readability and flexibility.
+
+Explicitly bind the `main` function in Rust with the async runtime of your choice. Also, don't forget to await the `dart_shutdown` future provided by Rinf in the `main` function.
+
+```rust title="Rust"
+[tokio::main]
+async fn main() {
+    // Do whatever you want here.
+    rinf::dart_shutdown().await;
+}
+```
+
+Remove `RINF:` from Protobuf message annotations. For example, `[RINF:DART-SIGNAL]` should become `[DART-SIGNAL]`.
+
+```proto title="Protobuf"
+// [DART-SIGNAL]
+message SomeMessage {}
+```
+
+Import messages from the root `messages` module, not from the inner module where they are declared.
+
+```dart title="Dart"
+import './messages/all.dart';
+```
+
+```rust title="Rust"
+use crate::messages::*;
+```
+
+When you need to run a Flutter web server, use `rinf server` to get the complete Flutter command with the necessary arguments.
+
+```bash title="CLI"
+rinf server
+```

flutter_package/bin/src/helpers.dart

@@ -146,7 +146,7 @@ please refer to Rinf's [documentation](https://rinf.cunarist.com).
   if (await mainFile.exists()) {
     await Process.run('dart', ['format', './lib/main.dart']);
     var mainText = await mainFile.readAsString();
-    if (!mainText.contains('messages/exports.dart')) {
+    if (!mainText.contains('messages/all.dart')) {
       final lines = mainText.split('\n');
       final lastImportIndex = lines.lastIndexWhere(
         (line) => line.startsWith('import '),
@@ -157,7 +157,7 @@ please refer to Rinf's [documentation](https://rinf.cunarist.com).
       );
       lines.insert(
         lastImportIndex + 2,
-        "import './messages/exports.dart';",
+        "import './messages/all.dart';",
       );
       mainText = lines.join('\n');
     }

flutter_package/bin/src/message.dart

@@ -146,7 +146,7 @@ Future<void> generateMessageCode({
     final resourceNames = entry.value;
     final modRsLines = <String>[];
     for (final resourceName in resourceNames) {
-      modRsLines.add('pub mod $resourceName;');
+      modRsLines.add('mod $resourceName;');
       modRsLines.add('pub use $resourceName::*;');
     }
     for (final otherSubPath in resourcesInFolders.keys) {
@@ -179,12 +179,12 @@ Future<void> generateMessageCode({
           continue;
         }
         final childName = otherSubPathSplitted.last;
-        modRsLines.add('pub mod $childName;');
+        modRsLines.add('mod $childName;');
         modRsLines.add('pub use $childName::*;');
       }
     }
     if (subPath == '/') {
-      modRsLines.add('pub mod generated;');
+      modRsLines.add('mod generated;');
       modRsLines.add('pub use generated::*;');
     }
     final modRsContent = modRsLines.join('\n');
@@ -234,8 +234,8 @@ Future<void> generateMessageCode({
   }
   fillingBar.increment();
 
-  // Generate `exports.dart` for `messages` module in Dart.
-  fillingBar.desc = 'Writing `exports.dart` file';
+  // Generate `all.dart` for `messages` module in Dart.
+  fillingBar.desc = 'Writing `all.dart` file';
   final exportsDartLines = <String>[];
   exportsDartLines.add("export './generated.dart';");
   for (final entry in resourcesInFolders.entries) {
@@ -249,7 +249,7 @@ Future<void> generateMessageCode({
     }
   }
   final exportsDartContent = exportsDartLines.join('\n');
-  await File.fromUri(dartOutputPath.join('exports.dart'))
+  await File.fromUri(dartOutputPath.join('all.dart'))
       .writeAsString(exportsDartContent);
   fillingBar.increment();
 

flutter_package/example/lib/main.dart

@@ -1,7 +1,7 @@
 import 'dart:ui';
 import 'package:flutter/material.dart';
 import 'package:rinf/rinf.dart';
-import './messages/exports.dart';
+import './messages/all.dart';
 
 void main() async {
   await initializeRust(assignRustSignal);