You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit ea212a2
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: packages/pigeon/native_interop_guide.md
+12-5Lines changed: 12 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -77,8 +77,6 @@ flutter pub add jni
77
77
flutter pub add dev:jnigen dev:logging dev:path
78
78
```
79
79
80
-
*Note: Ensure the resolved `objective_c` version in `pubspec.yaml` matches the version expected by your `ffigen` version (e.g., `ffigen: ^22.0.0` generates bindings that require `objective_c: ^9.6.0`).*
81
-
82
80
### Step 2: Configure Pigeon Options
83
81
84
82
Enable Native Interop for your target platforms by setting the configuration options in your Pigeon file:
This allows CocoaPods to automatically compile the generated Objective-C bridging files into the framework.
158
156
159
157
#### Swift Package Manager (SwiftPM) Configuration
160
-
Because Swift and Objective-C files cannot reside within the same SwiftPM target, you must define two separate targets in your `Package.swift` file:
158
+
**Only if a `.m` file is generated** in `<swift_output_dir>_objc_gen`, you must configure a separate Objective-C target in your `Package.swift` file. Because Swift and Objective-C files cannot reside within the same SwiftPM target, define two separate targets:
161
159
1. An Objective-C target for the generated bridge files (e.g., `my_plugin_objc_gen`).
162
160
2. The main Swift target that depends on the Objective-C target.
163
161
164
-
Example configuration:
162
+
> **Important:** If your Pigeon schema only uses synchronous `@HostApi()` methods (and does not generate a `.m` file in `<swift_output_dir>_objc_gen`), **do not** add the `<plugin_name>_objc_gen` target to `Package.swift`. SwiftPM requires every `.target` to contain at least one compilable source file (`.m`, `.c`, or `.swift`). Declaring a `<plugin_name>_objc_gen` target when the directory only contains a `.h` header (or temporary `.o` file) will cause Xcode builds to fail with:
163
+
> `Build input file cannot be found: '.../<plugin_name>_objc_gen.o'`
164
+
165
+
Example configuration (when `<plugin_name>_objc_gen` contains a generated `.m` file):
@@ -204,7 +205,7 @@ When implementing Native Interop host APIs directly in an application target rat
204
205
205
206
## 5. Troubleshooting Automated Generation
206
207
207
-
If `dart run pigeon`encounters errors while running `jnigen` or `ffigen`, review the following troubleshooting steps:
208
+
If `dart run pigeon`or your platform build encounters errors, review the following troubleshooting steps:
208
209
209
210
### 5.1 Unupdated Native Implementation or Uncompiled Code (JNI)
210
211
@@ -256,6 +257,12 @@ F DartJNI : JNI is not initialized. Are you trying to invoke a Java API from Dar
256
257
-**Cause**: Your plugin's `registerWith()` method (invoked by Flutter's `_PluginRegistrant.register()` before `main()`) constructed your Dart plugin class, and its constructor eagerly called `<MyApi>.createWithNativeInteropApi()` before `JniPlugin` initialized `DartJNI`.
257
258
-**Solution**: Initialize `<MyApi>.createWithNativeInteropApi()` lazily using `late final` rather than eagerly in the constructor initializer list (see [Section 4 of the Migration Guide](./native_interop_migration_guide.md#4-dart-client-adaptation)).
If an iOS or macOS SwiftPM build fails because `<plugin_name>_objc_gen.o` cannot be found:
263
+
-**Cause**: `Package.swift` defines a `<plugin_name>_objc_gen` target, but `ffigen` did not generate a `.m` implementation file in `Sources/<plugin_name>_objc_gen/` (because the Pigeon schema has no async callbacks, closures, or `@FlutterApi` methods requiring Objective-C trampolines). Without a `.m` source file, SwiftPM does not produce an object file for the target. (Note: any `.o` file produced inside `Sources/<plugin_name>_objc_gen/` during `ffigen` execution is a temporary `swiftc` artifact and must not be committed or used.)
264
+
-**Solution**: Remove the `<plugin_name>_objc_gen` target and its dependency entry from `Package.swift`.
Copy file name to clipboardExpand all lines: packages/pigeon/native_interop_migration_guide.md
+9-4Lines changed: 9 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -43,8 +43,6 @@ flutter pub add jni
43
43
flutter pub add dev:jnigen dev:logging dev:path
44
44
```
45
45
46
-
*Note: Ensure the resolved `objective_c` version in `pubspec.yaml` matches the version expected by your `ffigen` version (e.g., `ffigen: ^22.0.0` generates bindings that require `objective_c: ^9.6.0`).*
47
-
48
46
### 2.2 Update Pigeon Configuration Options
49
47
50
48
In your Pigeon Dart definition file, update `@ConfigurePigeon` to enable `useJni: true` for Kotlin and/or `useFfi: true` for Swift:
@@ -171,10 +169,17 @@ From the Dart side, instantiate your generated Host API using `<MyApi>.createWit
171
169
172
170
## 5. iOS/macOS Build System Configuration (FFI)
173
171
174
-
For Swift FFI, the toolchain generates an Objective-C bridging target under `<swift_output_dir>_objc_gen`. Ensure your build system includes these Objective-C files:
172
+
For Swift FFI, the toolchain generates an Objective-C bridging directory under `<swift_output_dir>_objc_gen`:
173
+
-**`.h` (Headers)**: Always generated to declare module interfaces and types for `ffigen`.
174
+
-**`.m` (Bridging Implementation)**: Only generated when the schema contains async callbacks, closures, `@FlutterApi`, or Objective-C blocks requiring trampoline implementations.
175
+
-**`.o` (Temporary Object Files)**: Intermediate binary files generated during `ffigen`/`swiftgen` AST parsing. These are **not** needed after code generation and must **not** be committed to version control.
176
+
177
+
Ensure your build system is configured appropriately:
175
178
176
179
-**CocoaPods**: Ensure `s.source_files = 'Sources/**/*.{swift,m,h}'` in your `.podspec`.
177
-
-**SwiftPM**: Add a separate Objective-C target for `my_plugin_objc_gen` in `Package.swift` and depend on it from your main Swift target.
180
+
-**SwiftPM (`Package.swift`)**:
181
+
-**Only if a `.m` file is generated** in `<swift_output_dir>_objc_gen`: Add a separate Objective-C target for `<plugin_name>_objc_gen` in `Package.swift` and depend on it from your main Swift target.
182
+
-**If no `.m` file is generated** (e.g., your schema only has synchronous `@HostApi()` methods and `<swift_output_dir>_objc_gen` only contains a `.h` header): **Do not** add the `<plugin_name>_objc_gen` target to `Package.swift`. SwiftPM requires at least one compilable source file (`.m`, `.c`, or `.swift`) per target; an empty/header-only target causes Xcode builds to fail with `Build input file cannot be found: '.../<plugin_name>_objc_gen.o'`.
178
183
-**Application & Example App Targets**:
179
184
-**Swift Module Name**: Set `ffiModuleName` in `SwiftOptions` to match your application's Swift module name (defaults to `'Runner'`). If iOS and macOS share the same generated Dart FFI file, both platforms must compile under that same module name. Since Flutter's default macOS template sets the module name to the app name rather than `Runner`, you can unify them by setting `PRODUCT_MODULE_NAME = Runner` in `macos/Runner/Configs/AppInfo.xcconfig` (or by matching whatever module name you configure). If iOS and macOS use separate Pigeon generation outputs or you only target one platform, unifying module names across platforms is not required.
180
185
-**Native Registration**: Register the native API implementation in native code (e.g., `MainFlutterWindow.swift` in `awakeFromNib()` on macOS, or `AppDelegate.swift` on iOS via `MyApiSetup.register(api: api)`). This also ensures the setup class is referenced so the Xcode linker does not strip it (`-dead_strip`).
Copy file name to clipboardExpand all lines: packages/pigeon/platform_tests/shared_test_plugin_code/lib/src/generated/native_interop_tests.gen.jni.dart
+2-2Lines changed: 2 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,4 @@
1
-
// AUTO GENERATED BY JNIGEN 1.0.0. DO NOT EDIT!
1
+
// AUTO GENERATED BY JNIGEN 1.0.1. DO NOT EDIT!
2
2
3
3
// Copyright 2013 The Flutter Authors
4
4
// Use of this source code is governed by a BSD-style license that can be
@@ -41,7 +41,7 @@ import 'dart:core' show Object, String;
0 commit comments