Merge pull request #330 from cunarist/better-template

Provide better template with `tokio` and fewer samples

.github/workflows/build_example_app.yaml

@@ -0,0 +1,118 @@
+# Verify that the example app works properly.
+name: build-example-app
+
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - "**.md"
+      - "**.html"
+  pull_request:
+    paths-ignore:
+      - "**.md"
+      - "**.html"
+  workflow_dispatch:
+
+concurrency:
+  # Cancels the workflow
+  # when another event in the same context happens.
+  # If it's a PR, context is the pull request number.
+  # Otherwise, it uses the Git reference(branch or tag name).
+  group: >
+    ${{ github.workflow }}
+    ${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: ${{ matrix.runner }} / ${{ matrix.target }}
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false # Important
+      matrix:
+        runner: [ubuntu-latest, windows-latest, macos-latest]
+        target: [android, web] # On all platforms
+        include:
+          # Specify targets for each platform
+          - runner: ubuntu-latest
+            target: linux
+          - runner: windows-latest
+            target: windows
+          - runner: macos-latest
+            target: macos
+          - runner: macos-latest
+            target: ios
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Setup Flutter SDK
+        uses: subosito/flutter-action@v2
+        with:
+          channel: "stable"
+
+      - name: Setup Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Setup Ninja and GTK3 toolchain (Only Linux target)
+        if: matrix.target == 'linux'
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y ninja-build libgtk-3-dev
+
+      - name: Setup Java toolchain (Only Android target)
+        if: matrix.target == 'android'
+        uses: actions/setup-java@v4
+        with:
+          distribution: "zulu"
+          java-version: "11"
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install the CLI tool
+        working-directory: rust_crate/
+        run: cargo install --path ./
+
+      - name: Prepare a Flutter app for testing
+        run: python automate prepare-example-app
+
+      - name: Build the example app
+        if: matrix.target == 'linux'
+        working-directory: flutter_ffi_plugin/example/
+        run: flutter build linux --verbose
+
+      - name: Build the example app
+        if: matrix.target == 'android'
+        working-directory: flutter_ffi_plugin/example/
+        run: |
+          flutter build apk --verbose
+          flutter build appbundle --verbose
+
+      - name: Build the example app
+        if: matrix.target == 'windows'
+        working-directory: flutter_ffi_plugin/example/
+        run: flutter build windows --verbose
+
+      - name: Build the example app
+        if: matrix.target == 'macos'
+        working-directory: flutter_ffi_plugin/example/
+        run: flutter build macos --verbose
+
+      - name: Build the example app
+        if: matrix.target == 'ios'
+        working-directory: flutter_ffi_plugin/example/
+        run: flutter build ios --verbose --no-codesign
+
+      - name: Build the example app
+        if: matrix.target == 'web'
+        working-directory: flutter_ffi_plugin/example/
+        run: |
+          rinf wasm --release
+          flutter build web --verbose

.github/workflows/build_test.yaml → .github/workflows/build_test_app.yaml

@@ -1,6 +1,6 @@
 # Verify that the app build works as intended
 # when utilizing the code inside the repository.
-name: build-test
+name: build-test-app
 
 on:
   push:
@@ -81,8 +81,8 @@ jobs:
         working-directory: rust_crate/
         run: cargo install --path ./
 
-      - name: Create a Flutter app for testing
-        run: python automate create-test-app
+      - name: Prepare a Flutter app for testing
+        run: python automate prepare-test-app
 
       - name: Build the example app
         if: matrix.target == 'linux'

.github/workflows/user_installation.yaml → .github/workflows/build_user_app.yaml

@@ -1,7 +1,7 @@
 # Verify that the documentation steps function as intended
 # when users utilize released versions
 # instead of the code from the repository.
-name: user-installation
+name: build-user-app
 
 on:
   workflow_dispatch:
@@ -64,8 +64,8 @@ jobs:
         working-directory: rust_crate/
         run: cargo install rinf
 
-      - name: Create a Flutter app for testing
-        run: python automate create-user-app
+      - name: Prepare a Flutter app for testing
+        run: python automate prepare-user-app
 
       - name: Build the example app
         if: matrix.target == 'linux'

automate/__main__.py

@@ -3,6 +3,14 @@
 import time
 
 
+def replace_text_in_file(filepath: str, change_from: str, change_to: str):
+    with open(filepath, mode="r", encoding="utf8") as file:
+        content: str = file.read()
+    content = content.replace(change_from, change_to)
+    with open(filepath, mode="w", encoding="utf8") as file:
+        file.write(content)
+
+
 if len(sys.argv) == 1:
     print("Automation option is not provided.")
     print("Use `python automate --help` to see all available operations.")
@@ -15,7 +23,7 @@
     command += " main"
     os.system(command)
 
-elif sys.argv[1] == "create-test-app":
+elif sys.argv[1] == "prepare-test-app":
     filepath = ".gitignore"
     with open(filepath, mode="r", encoding="utf8") as file:
         content: str = file.read()
@@ -39,19 +47,37 @@
 
     os.remove("Cargo.toml")
 
+    # Enable the web target, since it's not enabled by default.
+    replace_text_in_file(
+        "native/hub/src/lib.rs",
+        "use tokio;",
+        "// use tokio;",
+    )
+    replace_text_in_file(
+        "native/hub/src/lib.rs",
+        "// use tokio_with_wasm",
+        "use tokio_with_wasm",
+    )
+    replace_text_in_file(
+        "native/hub/Cargo.toml",
+        "# wasm-bindgen",
+        "wasm-bindgen",
+    )
+    replace_text_in_file(
+        "native/hub/Cargo.toml",
+        "# tokio_with_wasm",
+        "tokio_with_wasm",
+    )
+
     os.chdir("../")
 
-    filepath = "Cargo.toml"
-    with open(filepath, mode="r", encoding="utf8") as file:
-        content: str = file.read()
-    content = content.replace(
+    replace_text_in_file(
+        "Cargo.toml",
         "flutter_ffi_plugin/example/native/*",
         "test_app/native/*",
     )
-    with open(filepath, mode="w", encoding="utf8") as file:
-        file.write(content)
 
-elif sys.argv[1] == "create-user-app":
+elif sys.argv[1] == "prepare-user-app":
     filepath = ".gitignore"
     with open(filepath, mode="r", encoding="utf8") as file:
         content: str = file.read()
@@ -73,17 +99,47 @@
         # associated with the 'protoc_prebuilt' crate.
         time.sleep(60)
 
+    os.remove("Cargo.toml")
+
+    # Enable the web target, since it's not enabled by default.
+    replace_text_in_file(
+        "native/hub/src/lib.rs",
+        "use tokio;",
+        "// use tokio;",
+    )
+    replace_text_in_file(
+        "native/hub/src/lib.rs",
+        "// use tokio_with_wasm",
+        "use tokio_with_wasm",
+    )
+    replace_text_in_file(
+        "native/hub/Cargo.toml",
+        "# wasm-bindgen",
+        "wasm-bindgen",
+    )
+    replace_text_in_file(
+        "native/hub/Cargo.toml",
+        "# tokio_with_wasm",
+        "tokio_with_wasm",
+    )
+
     os.chdir("../")
 
-    filepath = "Cargo.toml"
-    with open(filepath, mode="r", encoding="utf8") as file:
-        content: str = file.read()
-    content = content.replace(
+    replace_text_in_file(
+        "Cargo.toml",
         "flutter_ffi_plugin/example/native/*",
         "user_app/native/*",
     )
-    with open(filepath, mode="w", encoding="utf8") as file:
-        file.write(content)
+
+elif sys.argv[1] == "prepare-example-app":
+    os.chdir("./flutter_ffi_plugin/example")
+
+    command = "rinf message"
+    while os.system(command) != 0:
+        # Retry the command in case of failure,
+        # possibly due to GitHub API rate limiting
+        # associated with the 'protoc_prebuilt' crate.
+        time.sleep(60)
 
 else:
     print("No such option for automation is available.")

documentation/docs/applying-template.md

@@ -37,17 +37,12 @@ After running the command, you'll have new files and folders as your starter Rus
     │   └── ...
     ├── linux/
 +   ├── messages/
-+   │   ├── sample_folder/
-+   │   ├── counter_number.proto
-+   │   ├── fractal_art.proto
++   │   ├── basic.proto
 +   │   └── README.md
 +   ├── native/
 +   │   ├── hub/
 +   │   │   ├── src/
 +   │   │   └── Cargo.toml
-+   │   ├── sample_crate/
-+   │   │   ├── src/
-+   │   │   └── Cargo.toml
 +   │   └── README.md
     ├── web/
     ├── windows/
@@ -58,7 +53,7 @@ After running the command, you'll have new files and folders as your starter Rus
     └── ...
 ```
 
-Various comments are written in the actual code to help you understand the whole structure. Also, you might want to remove `sample_crate` in production.
+Various comments are written in the actual code to help you understand the whole structure.
 
 If you already have a Rust crate that you want to use here, just put it inside `./native` and set it as a dependency of the `hub` crate.
 

documentation/docs/running-and-building.md

@@ -40,9 +40,7 @@ rinf wasm --release
 flutter build web
 ```
 
-### Deploying On a Web Server
-
-When deploying your web app, ensure that your web server is configured to include cross-origin-related HTTP headers in its responses. These headers enable web browsers using your website to gain access to `SharedArrayBuffer` web API, which is something similar to shared memory on the web.
+When deploying your web app on a web server, ensure that your web server is configured to include cross-origin-related HTTP headers in its responses. These headers enable web browsers using your website to gain access to `SharedArrayBuffer` web API, which is something similar to shared memory on the web.
 
 - [`Cross-Origin-Opener-Policy`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy): `same-origin`
 - [`Cross-Origin-Embedder-Policy`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy): `require-corp`.

flutter_ffi_plugin/bin/src/helpers.dart

@@ -38,10 +38,10 @@ Future<void> applyRustTemplate({
   }
 
   // Copy basic folders needed for Rust to work
-  final templateSource = packagePath.join("example/native/");
+  final templateSource = packagePath.join("template/native/");
   final templateDestination = flutterProjectPath.join("native/");
   await copyDirectory(templateSource, templateDestination);
-  final messagesSource = packagePath.join("example/messages/");
+  final messagesSource = packagePath.join("template/messages/");
   final messagesDestination = flutterProjectPath.join("messages/");
   await copyDirectory(messagesSource, messagesDestination);
 
@@ -59,17 +59,6 @@ resolver = "2"
   final cargoFile = File.fromUri(flutterProjectPath.join('Cargo.toml'));
   await cargoFile.writeAsString(cargoText);
 
-  // Disable demonstrations in sample functions
-  final sampleFunctionsFile = File.fromUri(
-    flutterProjectPath.join('native/hub/src/sample_functions.rs'),
-  );
-  var sampleFunctionsContent = await sampleFunctionsFile.readAsString();
-  sampleFunctionsContent = sampleFunctionsContent.replaceAll(
-    'SHOULD_DEMONSTRATE: bool = true',
-    'SHOULD_DEMONSTRATE: bool = false',
-  );
-  await sampleFunctionsFile.writeAsString(sampleFunctionsContent);
-
   // Add some lines to `.gitignore`
   final rustSectionTitle = '# Rust related';
   final messageSectionTitle = '# Generated messages';

flutter_ffi_plugin/example/native/README.md

@@ -3,5 +3,4 @@
 This folder contains Rust crates. Entry point of the Rust logic is the `hub` library crate. These crates are integrated and compiled into the Flutter app by the [Rinf](https://rinf.cunarist.com) framework.
 
 - Do NOT change the name of the `hub` crate. Compilation presets expect the entry library crate to be located at `./native/hub`.
-- Do NOT modify the `bridge` module inside `./native/hub/src` unless you know what you're doing.
 - You CAN name crates other than `hub` as you want.

flutter_ffi_plugin/example/native/hub/Cargo.toml

@@ -14,6 +14,6 @@ crate-type = ["lib", "cdylib", "staticlib"]
 [dependencies]
 rinf = "6.9.2"
 prost = "0.12.3"
-wasm-bindgen = "0.2.91"
-tokio_with_wasm = "0.4.3"
+wasm-bindgen = "0.2.92"                     # Uncomment this line to target the web
+tokio_with_wasm = "0.4.4"                   # Uncomment this line to target the web
 sample_crate = { path = "../sample_crate" }

flutter_ffi_plugin/example/native/hub/src/lib.rs

@@ -1,23 +1,20 @@
 //! This `hub` crate is the
 //! entry point of the Rust logic.
 
-// This `tokio` will be used by Rinf.
-// You can replace it with the original `tokio`
-// if you're not targeting the web.
-use tokio_with_wasm::tokio;
-
 mod messages;
 mod sample_functions;
 
+// use tokio;
+use tokio_with_wasm::tokio; // Uncomment this line to target the web
+
 rinf::write_interface!();
 
+// Use `tokio::spawn` to run concurrent tasks.
 // Always use non-blocking async functions
 // such as `tokio::fs::File::open`.
 // If you really need to use blocking code,
 // use `tokio::task::spawn_blocking`.
 async fn main() {
-    // Repeat `tokio::spawn` anywhere in your code
-    // if more concurrent tasks are needed.
     tokio::spawn(sample_functions::tell_numbers());
     tokio::spawn(sample_functions::stream_fractal());
     tokio::spawn(sample_functions::run_debug_tests());