Add FFI and JNI support to Swift and Kotlin by tarrinneal · Pull Request #11352 · flutter/packages

tarrinneal · 2026-03-25T18:52:22Z

This PR introduces optional Native Interop to Pigeon, enabling direct communication between Dart and native code without the overhead of traditional MethodChannel serialization. It leverages FFI (Foreign Function Interface) for Swift (iOS/macOS) and JNI (Java Native Interface) for Kotlin (Android).

This represents a significant architectural shift, moving from message-based passing to direct memory sharing and function calls. It also updates the concurrency model for asynchronous methods, moving from completion handlers/callbacks to modern language features: async/await in Swift and Coroutines in Kotlin.

Generators Covered

Swift Generator: Updated to support FFI bindings and async/await for asynchronous methods.
Kotlin Generator: Updated to support JNI bindings and Kotlin Coroutines for asynchronous methods.
Dart Generator: Updated to handle the generated interop bindings on the Dart side.

What's In Scope

Infrastructure: Added core support for useFfi and useJni options.
Automation: Implemented multi-step generation flows that automatically invoke jnigen and ffigen to produce final bindings.
Config Generation: Added jnigen_config_generator.dart and ffigen_config_generator.dart to generate the necessary configuration files for the external tools.
Documentation: Added a detailed native_interop_guide.md explaining prerequisites, setup, and usage.
Tests: Added ni_tests.dart and associated generated files and integration tests to verify the feature.

What's Out of Scope

Other Languages: This PR specifically targets Swift and Kotlin for the Native Interop feature. Support for Objective-C, C++, and GObject is not included in this interop implementation, and may not be in the future.
Performance Optimization for Complex Classes: As noted in the guide, there is a known performance regression when transferring complex classes with many fields compared to MethodChannel Pigeon. This PR delivers the functional infrastructure, but optimizing this specific case is left for follow-up work.
Non-instant released data. Currently all data that is sent over host or flutter api surfaces is converted to the correct shape and type for the language it is moving toward and the data created in the other language is then discarded. This presents some inefficiencies and potential workflows that are not yet available.

work toward flutter/flutter#182230
design doc flutter/flutter#181430

stuartmorgan-g

More WIP review comments; still haven't finished the full pass.

stuartmorgan-g

Another review drop!

I believe I've made it through all the non-test code now, so the end is in sight. (After all, how much test code can there be?)

stuartmorgan-g · 2026-06-23T15:10:48Z

+  }
+}
+
+ffi_bridge.MessagesPigeonTypedData toPigeonTypedData(TypedData value) {


A lot of these helpers aren't file-private; is that intentional? Do we need to make these visible to Pigeon clients?

stuartmorgan-g · 2026-06-23T15:13:06Z

+    }
+  }
+
+  String getToDartCall(


A lot of these non-trivial helpers could use a Dart doc comment explaining very briefly what they do/are for, and what any non-obvious parameter means.

stuartmorgan-g · 2026-06-23T15:17:49Z

+      return '$name${_getNullableSymbol(type.isNullable)}.toFfi()';
+    }
+    if (type.isEnum && !type.isNullable) {
+      return 'ffi_bridge.${type.baseName}.values[$name]';


The magic string ffi_bridge appears a lot, and should be a file-level constant instead.

stuartmorgan-g · 2026-06-23T15:20:50Z

+      return 'NSObject${_getNullableSymbol((forceNullable || type.isNullable) && !forceNonNullable)}';
+    }
+
+    return '${ffiName.replaceAll('ffi_bridge.', prefix)}${_getNullableSymbol((forceNullable || type.isNullable) && !forceNonNullable)}';


If sometimes we want the prefix and sometimes we don't, why not have withPrefix as a parameter to ffiName, instead of unconditionally adding it there and then conditionally removing it?

stuartmorgan-g · 2026-06-23T15:21:27Z

+    if (type.baseName == 'List') {
+      return '<$ffiCollectionTypes>';
+    } else if (type.baseName == 'Map') {
+      return '<$ffiCollectionTypes>';


As above, List and Map are the same and can be collapsed.

stuartmorgan-g · 2026-06-23T20:30:36Z

+      environment: env,
+    );
+    if (jnigenResult.exitCode != 0) {
+      print('''


I highly recommend printing this second, not first, so it's the most obvious thing someone sees when the command fails.

stuartmorgan-g · 2026-06-23T20:37:26Z

+
+  String? pubspecPath;
+  if (appDirectory != null && appDirectory.isNotEmpty) {
+    pubspecPath = findPubspecPath(path.join(appDirectory, 'placeholder.dart'));


Let's just adjust findPubspecPath to take a Directory instead of appending placeholders in some cases, and then the places where we start with a Dart path we can call it with File(dartPath).parent

stuartmorgan-g · 2026-06-23T20:38:30Z

+  pubspecPath ??= findPubspecPath(path.join(Directory.current.path, 'placeholder.dart'));
+
+  if (pubspecPath == null) {
+    return errors;


We want to return no errors if we couldn't find a pubspec? If so, please add a comment here saying why.

stuartmorgan-g · 2026-06-23T20:39:02Z

+        }
+      }
+    }
+  } catch (_) {}


Why are we silently dropping all exceptions without returning any errors?

stuartmorgan-g · 2026-06-23T20:41:23Z

+            Error(
+              message:
+                  'Missing required dependency "$dep" in pubspec.yaml for $apiName native interop support.\n'
+                  'Please add "$dep" to your dependencies or dev_dependencies in your pubspec.yaml file.',


We should be distinguishing between dev and non-dev dependencies in both the validation and the error message. E.g., if someone adds objective_c as a dev dependency, it shouldn't pass validation. Similarly, if they are completely missing objective_c, as a dependency, they shouldn't have to guess where to add it.

…o Kamyshin

stuartmorgan-g · 2026-06-30T17:43:40Z

+    suppressVersion: true,
+    dartOut: 'lib/src/native_interop_example.g.dart',
+    kotlinOut:
+        'android/app/src/main/kotlin/dev/flutter/pigeon_example_app/NativeInteropExample.g.kt',


Nit: Shouldn't the namespace not have _ (per the recent issue)?

stuartmorgan-g · 2026-06-30T17:44:02Z

@@ -84,6 +103,7 @@ Future<int> generateTestPigeons({required String baseDir, bool includeOverflow =
    'nullable_returns',
    'primitive',
    'proxy_api_tests',
+    'ni_tests',


Nit: keep the alphabetical order

stuartmorgan-g · 2026-06-30T18:58:48Z

@@ -41,3 +41,89 @@ kotlin {
 flutter {
    source = "../.."
 }
+// Gradle stub for listing dependencies in JNIgen. If found in


Is this something that jnigen auto-adds to the file, or something we need to document somewhere?

stuartmorgan-g

I think I've finished the first pass over everything now (although it's hard to be 100% sure since GitHub really struggles with scrolling in the review view for this PR). Next I'll try it out on a plugin again, and take a closer look at the generated code in a more digestible size.

(The comprehensive test generated files have reached the point where they are nearly unreviewable, and the examples are intentionally quite minimal, so I want to drill down with a real-world-sized example.)

stuartmorgan-g · 2026-07-01T14:01:40Z

+    dartOptions: DartOptions(),
+    kotlinOptions: KotlinOptions(
+      useJni: true,
+      // Optional: Paths to search for compiled local classes (primarily needed for standalone Apps)


Nit: apps should not be capitalized

stuartmorgan-g · 2026-07-01T14:07:18Z

+    guard let flutterApi = NIFlutterIntegrationCoreApi.getInstance() else {
+      throw NiTestsError(
+        code: "not_registered", message: "NIFlutterIntegrationCoreApi not registered", details: nil)
+    }


You should be able to make this file less verbose by making a file-level helper:

func getNativeInteropFlutterApi -> NIFlutterIntegrationCoreApi { guard let flutterApi = NIFlutterIntegrationCoreApi.getInstance() else { throw NiTestsError( code: "not_registered", message: "NIFlutterIntegrationCoreApi not registered", details: nil) } return flutterApi }

The all the handlers can just do let flutterApi = getNativeInteropFlutterApi()

stuartmorgan-g · 2026-07-01T14:09:55Z


 /** This plugin handles the native side of the integration tests in example/integration_test/. */
 class TestPlugin : FlutterPlugin, HostIntegrationCoreApi {
  private var flutterApi: FlutterIntegrationCoreApi? = null
  private var flutterSmallApiOne: FlutterSmallApi? = null
  private var flutterSmallApiTwo: FlutterSmallApi? = null
  private var proxyApiRegistrar: ProxyApiRegistrar? = null
+  private var niMessageApi: NIHostIntegrationCoreApiRegistrar? = null
+  // private var niSmallApiOne: NIHostSmallApiRegistrar? = null
+  // private var niSmallApiTwo: NIHostSmallApiRegistrar? = null


stuartmorgan-g · 2026-07-01T14:10:51Z

+//     override suspend fun voidVoid() {
+//       return
+//     }
+// }


stuartmorgan-g · 2026-07-01T14:16:26Z

+      wrappedError.code = "\(error)"
+      wrappedError.message = "\(type(of: error))"
+      wrappedError.details = "Stacktrace: \(Thread.callStackSymbols)"
+    }


We should definitely do a short-ish term follow-up PR to improve the code gen for these; it looks like the do/catch/catch could be extracted to a helper to significantly reduce the amount of code generated.

stuartmorgan-g · 2026-07-01T14:20:14Z

+
+private class PigeonApiImplementation : NativeInteropExampleApi() {
+  override fun doSomething() {
+    // Do nothing or print


Since this is example code, I would expect this to have some explanation of what would go here in a real app. I'm not sure what the current comment is meant to convey.

stuartmorgan-g · 2026-07-01T14:42:07Z

+  final NativeInteropExampleApiForNativeInterop? _nativeInteropApi;
+
+  Future<void> doSomething() async {
+    if ((Platform.isAndroid || Platform.isIOS || Platform.isMacOS) && _nativeInteropApi != null) {


Why do we need the platform checks at the call point? Can't we just expect that _nativeInteropApi won't be set if it's not a platform that supports native interop?

stuartmorgan-g · 2026-07-01T14:48:42Z

+    });
+  });
+
+  //   group('Host API with suffix', () {


Please audit the full PR diff for commented-out code, and ensure we aren't landing any.

stuartmorgan-g · 2026-07-01T19:44:59Z

+## 1. Overview
+
+Pigeon Native Interop allows Dart code to make direct function calls into native platform code, and vice versa, without the overhead of MethodChannel-based message passing. Instead of serializing data into binary buffers, Native Interop establishes direct memory-bound bridges using native pointers and JVM references.
+For a detailed comparison between MethodChannel-based communication and Native Interop—including advantages, limitations, and recommended use cases—see the [Pigeon README](file:///Users/tarrinneal/work/packages/packages/pigeon/README.md#communication-options-methodchannels-vs-native-interop).


I just hit this locally: this and the migration guide have some absolute file path links that aren't going to be very useful to 99.9999% of clients 😉

stuartmorgan-g · 2026-07-01T19:47:19Z

+
+### Android (JNI / JNIgen)
+- **Java 17**: Required by the Android build tools and JNIgen.
+- **Maven (`mvn`)**: Required to resolve dependencies during generation.


This is no longer needed I believe.

stuartmorgan-g · 2026-07-01T19:47:58Z

+### iOS/macOS (FFI / FFIgen)
+- **LLVM (version 9+)**: Required to parse header files. 
+  - On macOS, this is included with Xcode Command Line Tools.
+- **Dart Dependencies**: The `package:ffi` and `package:ffigen` packages must be added to your pubspec.


This should be a step in the section below, rather than a prereq.

stuartmorgan-g · 2026-07-01T19:49:56Z

+
+---
+
+## 2. Migrating Native Code signatures


The first step in the migration guide should be summarizing the changes people need to make to start (adding the Dart deps, what options to add to their pigeon config to enable it, re-running generation), rather than making people jump back to the other doc at this point.

stuartmorgan-g · 2026-07-06T16:49:31Z

+)
+```
+
+#### Kotlin Options for JNI


It's confusing to not have a similar section for Swift.

stuartmorgan-g · 2026-07-06T16:56:29Z

+
+Pigeon automatically orchestrates running `jnigen` and `ffigen` as part of the generation process.
+
+- **Android (JNI)**: When `kotlinOptions.useJni` is enabled and `kotlinOut` is specified:


These lines and/or the lists below them need to be reworded; currently they sound like instructions to the reader. The intro sentence above correctly says that they aren't, but it doesn't read that way here so someone could either be confused by the apparent contraction, or just not read the first sentence carefully enough and try to do all of these steps.

stuartmorgan-g · 2026-07-06T17:09:09Z

    Indent indent, {
    required String dartPackageName,
  }) {
+    _classNamePrefix = generatorOptions.fileSpecificClassNameComponent ?? '';


I'm not sure where in the overall plumbing the problem is, but when I took one of our simple plugins and added the FFI flag to its config, I ended up with things like messagesNumberWrapper as class names that failed Swift format; something should be fixing the casing before it's used here. Obj-C and Kotlin may well have the same issue.

Do we not have any tests that don't explicitly set the file class name component?

stuartmorgan-g · 2026-07-06T17:24:18Z

+  1. Generate the JNI-compatible Kotlin bridge and the `jnigen_config.dart` configuration.
+  2. Run `jnigen` (via the config script) to parse the generated Kotlin bridge and produce Dart JNI bindings.
+  3. Generate the final pigeon Dart output that wraps and imports those JNI bindings.
+- **iOS/macOS (FFI)**: When `swiftOptions.useFfi` is enabled and `swiftOptions.appDirectory` is specified:


We need to figure out some guess fallback or some warning output for when appDirectory isn't set. Right now it silently doesn't actually do what the user would want.

This is especially confusing because Step 1 above does not set it.

stuartmorgan-g · 2026-07-06T17:27:12Z

+  - *Note*: If you are building a Flutter Plugin, this option is generally not needed because JNIgen automatically resolves classes defined inside plugin packages via standard Gradle dependency classpaths.
+  - *CLI Equivalent*: `--kotlin_jni_classpaths <path>` (can be specified multiple times).
+
+### Step 2: Automated Interop Generation


For iOS, Step 2 fails with:

Error: pigeons/messages.dart: Missing required dependency "ffi" in pubspec.yaml for Swift FFI native interop support. Please add "ffi" to your dependencies or dev_dependencies in your pubspec.yaml file.

because Step 1 didn't say to do that. It's good that we have an error message for it, but the guided steps shouldn't trigger that error case.

It was also not at all clear from the error message when I ran this in a plugin that what it was telling me to do was add it to example/'s pubspec, so I added it to the plugin pubspec and then confusingly got the same error message.

And it appears that clients need to add ffigen, swiftgen, and swift2objc to example/pubspec.yaml as well, which isn't in the instructions, nor is there a check with error (just a bunch of "Couldn't resolve the package" errors).

And then when I fixed that I got an error because swiftc seems to be fed a path that assumes that the swiftOut relative path is relative to appDirectory, which is never going to be true for a plugin. So I'm not sure how configuring this is supposed to work exactly.

I think I'll hold off on continuing the "attempt to try it on a plugin" tests until you've had a chance to do a simple run-through yourself on a plugin (I was trying quick_actions) to iron out the major bumps locally.

tarrinneal added 30 commits October 29, 2025 19:00

kotlin jni impementation

b9b0b5e

analyzer

e599d1e

test fixes w jetski

726975d

Merge branch 'main' of https://github.com/flutter/packages into Kamyshin

f636cdb

remove future code

72a305e

Merge branch 'main' of https://github.com/flutter/packages into Kamyshin

4e59659

Merge branch 'main' of https://github.com/flutter/packages into Kamyshin

e22c55a

Merge remote-tracking branch 'origin/Frillback' into Kamyshin

3f0be1d

minor cleanup

0d09615

Merge branch 'main' of https://github.com/flutter/packages into Kamyshin

e0f23a9

omit types

025376c

Merge branch 'main' of https://github.com/flutter/packages into Kamyshin

aa01700

format

6a0df05

flutter api

022ed51

fix swift optional bug

43f2e5a

add nullable tests and more sync tests

5fd46e8

flutter api async methods

a0c56ab

error handling and tests

2c252ae

basic thread tests

5072a47

fix swftFunction

b0cd2ec

add back tests for named/optional params

38bd37e

Merge branch 'main' of https://github.com/flutter/packages into Kamyshin

850cb2e

fix const gen adapter classes

9bb4bc5

performance improvements to typedData and isEquals

0c7ef63

stuff that I'm going to move to a different branch

110ab70

Improve efficiency in some methods

82065a8

analyze this

9861c00

format

11daedd

less repeating, and less listing

e197fc0

allow individual class types to not have colliding hashes

cbf4096

tarrinneal added 9 commits May 6, 2026 15:05

use flags

fe2a3ce

ez

36f37d1

cleaner

6bc9813

check for deps

8c778d8

unimp

625df07

add example

85e3f30

Merge branch 'main' of https://github.com/flutter/packages into Kamyshin

0bcef49

Merge branch 'main' of https://github.com/flutter/packages into Kamyshin

75217be

weird formatting issues with objc headers

aa2cb69

stuartmorgan-g reviewed Jun 22, 2026

View reviewed changes

stuartmorgan-g reviewed Jun 23, 2026

View reviewed changes

tarrinneal added 4 commits June 23, 2026 17:46

fix dependancy issues

4de0740

Merge branch 'Kamyshin' of https://github.com/tarrinneal/packages int…

0fe78ed

…o Kamyshin

don't generate jni code when not using jni

4880a8b

update example app to not be dumb (in one way)

7108341

stuartmorgan-g reviewed Jul 1, 2026

View reviewed changes

stuartmorgan-g requested changes Jul 1, 2026

View reviewed changes

stuartmorgan-g reviewed Jul 1, 2026

View reviewed changes

stuartmorgan-g reviewed Jul 6, 2026

View reviewed changes

tarrinneal added 6 commits July 10, 2026 13:57

some comments

0ef8cb0

Merge branch 'main' of https://github.com/flutter/packages into Kamyshin

f4bb882

gradle matching

45b76ae

Merge branch 'main' of https://github.com/flutter/packages into Kamyshin

549d97e

kotlin versions and ios sdk validation

6ddffdb

nullability and isPrimitive

724515c


		Pigeon automatically orchestrates running `jnigen` and `ffigen` as part of the generation process.

		- Android (JNI): When `kotlinOptions.useJni` is enabled and `kotlinOut` is specified:

Uh oh!

Conversation

tarrinneal commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stuartmorgan-g left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stuartmorgan-g left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

stuartmorgan-g left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

tarrinneal commented Mar 25, 2026 •

edited

Loading