Skip to content

Commit bbc5975

Browse files
authored
[pigeon] Fix native interop (JNI) calls in minified Android release builds (#13151)
Flutter minifies Android release builds with R8, which removes or renames classes that it doesn't see being used. JNI looks up classes and members by name at runtime, from Dart code that R8 can't see. As a result, native interop calls that work in debug builds fail in release builds with `ClassNotFoundException` or `NoSuchMethodError`. This PR: - **Kotlin generator:** When `useJni` is set, adds `@Keep` to every generated class that JNI reaches by name: - data classes, including sealed classes; - enums and their companion objects; - the FlutterApi interface and its Registrar; - the error class. The HostApi interface and Registrar already had `@Keep`. The test plugin and example app are regenerated. - **Docs:** Documents keep rules for six Kotlin standard library classes. `package:jni` and the generated Dart code look these up by name to call and implement `suspend` (`@async`) methods. Library classes can't be annotated, so these rules are needed until `package:jni` ships them (dart-lang/native#3732). - Updated `native_interop_guide.md`, `native_interop_migration_guide.md` and the migration skill. - Each spot has a TODO linking that issue. - **CI:** Adds an `android_kotlin_native_interop_release_tests` suite to the `Linux_android custom_package_tests` shard. It runs the native interop integration tests in a minified release build. - `flutter test` and `flutter drive` don't support release builds on Android, so the suite uses `flutter run --release` and reads the test summary from its output. - The test plugin adds the six Kotlin rules in `consumer-rules.pro`, with a TODO to delete them once dart-lang/native#3732 is fixed. - It deliberately has no rule for its own package, so a missing `@Keep` on any generated class still fails the suite. Results for the native interop suite (339 tests) in a minified release build on an arm64 emulator: | | Passed | Failed | Didn't run | |---|---|---|---| | Before (old generated code, with the Kotlin rules) | 106 | 70 | 163 | | This PR, without the Kotlin rules | 210 | 129 | 0 | | This PR | 339 | 0 | 0 | - **Before:** 163 tests didn't run. R8 had removed the FlutterApi interface, so registering the FlutterApi threw `ClassNotFoundException` during test setup. - **Without the Kotlin rules:** every failure is a call through a `suspend` function. Each one fails with `NoSuchMethodError`, because R8 renames `kotlin.coroutines.Continuation`. Fixes flutter/flutter#193880 Temporary fix for dart-lang/native#3732 ## Pre-Review Checklist **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. [^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.
1 parent 19ba9aa commit bbc5975

16 files changed

Lines changed: 357 additions & 5 deletions

File tree

‎packages/pigeon/CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
1+
## 29.0.7
2+
3+
* [kotlin] Fixes native interop calls failing with `ClassNotFoundException` in minified
4+
Android release builds, by adding `@Keep` to every generated class that JNI reaches by name.
5+
* Updates native interop guides and migration skill with the keep rules that Android
6+
release builds need for the Kotlin classes that `package:jni` looks up by name.
7+
18
## 29.0.6
29

310
* Updates native interop guides and migration skill with SwiftPM `<plugin_name>_objc_gen` target guidance.

‎packages/pigeon/example/native_interop_app/android/app/src/main/kotlin/dev/flutter/pigeonnativeinteropapp/NativeInteropExample.g.kt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ private object NativeInteropExamplePigeonUtils {
3535
* @property message The error message.
3636
* @property details The error details. Must be a datatype supported by the api codec.
3737
*/
38+
@Keep
3839
class FlutterError(
3940
val code: String,
4041
override val message: String? = null,

‎packages/pigeon/lib/src/generator_tools.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ import 'generator.dart';
1616
/// The current version of pigeon.
1717
///
1818
/// This must match the version in pubspec.yaml.
19-
const String pigeonVersion = '29.0.6';
19+
const String pigeonVersion = '29.0.7';
2020

2121
/// Default plugin package name.
2222
const String defaultPluginPackageName = 'dev.flutter.pigeon';

‎packages/pigeon/lib/src/kotlin/kotlin_generator.dart‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -311,6 +311,18 @@ class KotlinGenerator extends StructuredGenerator<InternalKotlinOptions> {
311311
}
312312
}
313313

314+
/// Writes `@Keep` if generating for JNI.
315+
///
316+
/// The generated Dart code reaches these types and their members by name
317+
/// through JNI. Flutter enables R8 for Android release builds by default,
318+
/// and without `@Keep` R8 can remove, rename, or merge them, which breaks
319+
/// those lookups at runtime.
320+
void _writeKeepAnnotationForJni(InternalKotlinOptions generatorOptions, Indent indent) {
321+
if (generatorOptions.useJni) {
322+
indent.writeln('@Keep');
323+
}
324+
}
325+
314326
@override
315327
void writeConstants(
316328
InternalKotlinOptions generatorOptions,
@@ -346,6 +358,7 @@ class KotlinGenerator extends StructuredGenerator<InternalKotlinOptions> {
346358
}) {
347359
indent.newln();
348360
addDocumentationComments(indent, anEnum.documentationComments, _docCommentSpec);
361+
_writeKeepAnnotationForJni(generatorOptions, indent);
349362
indent.write('enum class ${anEnum.name}(val raw: Int) ');
350363
indent.addScoped('{', '}', () {
351364
enumerate(anEnum.members, (int index, EnumMember member) {
@@ -360,6 +373,7 @@ class KotlinGenerator extends StructuredGenerator<InternalKotlinOptions> {
360373
});
361374

362375
indent.newln();
376+
_writeKeepAnnotationForJni(generatorOptions, indent);
363377
indent.write('companion object ');
364378
indent.addScoped('{', '}', () {
365379
indent.write('fun ofRaw(raw: Int): ${anEnum.name}? ');
@@ -393,6 +407,7 @@ class KotlinGenerator extends StructuredGenerator<InternalKotlinOptions> {
393407
_docCommentSpec,
394408
generatorComments: generatedMessages,
395409
);
410+
_writeKeepAnnotationForJni(generatorOptions, indent);
396411
_writeDataClassSignature(indent, classDefinition);
397412
if (classDefinition.isSealed) {
398413
return;
@@ -796,6 +811,7 @@ if (wrapped == null) {
796811
val registered${api.name}: MutableMap<String, ${api.name}> = mutableMapOf()
797812
798813
/// Class that stores instances
814+
@Keep
799815
class ${api.name}Registrar() {
800816
801817
/// Registers an instance with the given name.
@@ -813,6 +829,7 @@ class ${api.name}Registrar() {
813829
}
814830
}
815831
''');
832+
indent.writeln('@Keep');
816833
indent.writeScoped('interface ${api.name} {', '}', () {
817834
for (final Method method in api.methods) {
818835
_writeMethodDeclaration(
@@ -1515,6 +1532,7 @@ class ${api.name}Registrar() {
15151532
' * @property details The error details. Must be a datatype supported by the api codec.',
15161533
);
15171534
indent.writeln(' */');
1535+
_writeKeepAnnotationForJni(generatorOptions, indent);
15181536
indent.write('class ${_getErrorClassName(generatorOptions)} ');
15191537
indent.addScoped('(', ')', () {
15201538
indent.writeln('val code: String,');

‎packages/pigeon/native_interop_guide.md‎

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ Using Native Interop in pigeon follows the standard pigeon workflow, with a few
3636
3. **Configure Options**: Configure `kotlinOptions.useJni` or `swiftOptions.useFfi` in your `PigeonOptions` (see [Step 2: Configure Pigeon Options](#step-2-configure-pigeon-options) below).
3737
4. **Prerequisites**: Ensure your local environment meets the toolchain prerequisites for `jnigen` and `ffigen` (see [Section 3: Prerequisites](#3-prerequisites) below).
3838
5. **Run Code Generation**: Run the `pigeon` tool to generate the native bridge code and interop bindings (see [Step 3: Run Code Generation](#step-3-run-code-generation) below).
39-
6. **Configure Build Systems**: For Swift FFI, configure CocoaPods or Swift Package Manager (SwiftPM) to compile the intermediate Objective-C bridge files (see [Step 4: iOS/macOS Build System Configuration (FFI)](#step-4-iosmacos-build-system-configuration-ffi) below).
39+
6. **Configure Build Systems**: For Swift FFI, configure CocoaPods or Swift Package Manager (SwiftPM) to compile the intermediate Objective-C bridge files (see [Step 4: iOS/macOS Build System Configuration (FFI)](#step-4-iosmacos-build-system-configuration-ffi) below). For Kotlin JNI, add keep rules so that Android release builds work (see [Step 5: Android Release Build Configuration (JNI)](#step-5-android-release-build-configuration-jni) below). <!-- TODO(tarrinneal): Remove this JNI sentence once package:jni ships these keep rules: https://github.com/dart-lang/native/issues/3732 -->
4040
7. **Implement and Call**: Implement the generated protocol/class interface in your native codebase and call the generated Dart methods from your Flutter application.
4141

4242
---
@@ -201,6 +201,36 @@ When implementing Native Interop host APIs directly in an application target rat
201201
```
202202
Calling `register(api:)` in native code also prevents the Xcode linker (`-dead_strip`) from stripping the setup class from the compiled binary.
203203

204+
### Step 5: Android Release Build Configuration (JNI)
205+
206+
<!-- TODO(tarrinneal): Remove this section once package:jni ships these keep rules: https://github.com/dart-lang/native/issues/3732 -->
207+
208+
Flutter enables R8 for Android release builds by default. R8 removes, renames, and merges classes and members that it doesn't see being used. JNI looks up classes and members by name at runtime, so everything that JNI reaches must keep its original name.
209+
210+
Pigeon adds `@Keep` to every generated Kotlin class that the generated Dart code reaches through JNI, so the generated code needs no extra rules. However, `package:jni` and the generated Dart code also look up several Kotlin standard library classes by name to call Kotlin `suspend` functions (`@async` methods) and to implement them from Dart. Library classes can't be annotated, so until `package:jni` includes rules for these classes, you must add them yourself:
211+
212+
```text
213+
# Kotlin classes that package:jni and the generated Dart code look up by name.
214+
-keep class kotlin.Unit { *; }
215+
-keep class kotlin.Result { *; }
216+
-keep class kotlin.Result$Failure { *; }
217+
-keep class kotlin.coroutines.Continuation { *; }
218+
-keep class kotlin.coroutines.intrinsics.CoroutineSingletons { *; }
219+
-keep class kotlin.coroutines.intrinsics.IntrinsicsKt { *; }
220+
```
221+
222+
* **Plugins**: Add the rules to a file in the plugin's `android/` directory, such as `consumer-rules.pro`, and list it in `consumerProguardFiles` in the plugin's `android/build.gradle` or `android/build.gradle.kts`. R8 then applies the rules to every application that uses the plugin:
223+
```gradle
224+
android {
225+
defaultConfig {
226+
consumerProguardFiles("consumer-rules.pro")
227+
}
228+
}
229+
```
230+
* **Applications**: Add the rules to `android/app/proguard-rules.pro`. Flutter applies this file to release builds when it exists.
231+
232+
Debug and profile builds are not minified, so test a release build (for example, with `flutter run --release`) to verify the configuration.
233+
204234
---
205235

206236
## 5. Troubleshooting Automated Generation
@@ -263,6 +293,15 @@ If an iOS or macOS SwiftPM build fails because `<plugin_name>_objc_gen.o` cannot
263293
- **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.)
264294
- **Solution**: Remove the `<plugin_name>_objc_gen` target and its dependency entry from `Package.swift`.
265295

296+
### 5.7 `ClassNotFoundException` or `NoSuchMethodError` in Android Release Builds (JNI)
297+
298+
If native interop calls work in debug builds but fail in release builds with `java.lang.ClassNotFoundException` or `java.lang.NoSuchMethodError`:
299+
- **Cause**: R8 removed or renamed a class or member that JNI looks up by name.
300+
- **Solution**:
301+
- If the error names a class generated by Pigeon, regenerate your Pigeon output with Pigeon 29.0.7 or later, which adds `@Keep` to every generated class that JNI reaches.
302+
- If the error names a class in the `kotlin` package (for example, `kotlin/coroutines/Continuation` in the signature of a `suspend` method), add the keep rules from [Step 5](#step-5-android-release-build-configuration-jni). <!-- TODO(tarrinneal): Remove this bullet once package:jni ships these keep rules: https://github.com/dart-lang/native/issues/3732 -->
303+
- To see what R8 removed or renamed, check `build/app/outputs/mapping/release/mapping.txt` in the application directory.
304+
266305
---
267306

268307
## 6. Migration from Platform Channels

‎packages/pigeon/native_interop_migration_guide.md‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -186,7 +186,29 @@ Ensure your build system is configured appropriately:
186186

187187
---
188188

189-
## 6. Environment Prerequisites & Tooling Versions
189+
## 6. Android Release Build Configuration (JNI)
190+
191+
<!-- TODO(tarrinneal): Remove this section, and renumber the next one, once package:jni ships these keep rules: https://github.com/dart-lang/native/issues/3732 -->
192+
193+
Flutter enables R8 for Android release builds by default, and R8 removes or renames classes that JNI looks up by name. Pigeon adds `@Keep` to the generated Kotlin classes that JNI reaches, but `package:jni` and the generated Dart code also look up Kotlin standard library classes by name to call and implement `suspend` functions. Until `package:jni` includes rules for these classes, add them to a `consumer-rules.pro` file in your plugin's `android/` directory:
194+
195+
```text
196+
# Kotlin classes that package:jni and the generated Dart code look up by name.
197+
-keep class kotlin.Unit { *; }
198+
-keep class kotlin.Result { *; }
199+
-keep class kotlin.Result$Failure { *; }
200+
-keep class kotlin.coroutines.Continuation { *; }
201+
-keep class kotlin.coroutines.intrinsics.CoroutineSingletons { *; }
202+
-keep class kotlin.coroutines.intrinsics.IntrinsicsKt { *; }
203+
```
204+
205+
Then add `consumerProguardFiles("consumer-rules.pro")` to `android.defaultConfig` in the plugin's `android/build.gradle` or `android/build.gradle.kts`, so that every app using the plugin applies the rules. For a standalone application, add the rules to `android/app/proguard-rules.pro` instead.
206+
207+
Debug builds are not minified, so test a release build (for example, by running the example app with `flutter run --release`) after migrating. See [Step 5 of the Native Interop Guide](./native_interop_guide.md#step-5-android-release-build-configuration-jni) for details.
208+
209+
---
210+
211+
## 7. Environment Prerequisites & Tooling Versions
190212

191213
To use Native Interop and its external code generators:
192214
- **`jnigen` 1.0.0 or later**: Earlier versions of JNIgen cannot parse metadata from newer Kotlin compilers and fail with `IllegalArgumentException: Provided Metadata instance has version ... while maximum supported version is ...`. `jnigen` 1.0.0 supports Kotlin metadata up to 2.4, and uses the JDK bundled with Flutter by default.

‎packages/pigeon/platform_tests/test_plugin/android/build.gradle.kts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,9 @@ android {
4343

4444
defaultConfig {
4545
minSdk = 24
46+
// TODO(tarrinneal): Remove, along with consumer-rules.pro, once package:jni
47+
// ships the Kotlin keep rules: https://github.com/dart-lang/native/issues/3732
48+
consumerProguardFiles("consumer-rules.pro")
4649
}
4750

4851
testOptions {
Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Kotlin classes that package:jni and the generated Dart code look up by name
2+
# through JNI. Classes generated by Pigeon are annotated with @Keep, but library
3+
# classes can't be annotated, so they need explicit rules until package:jni
4+
# provides them. See "Android Release Build Configuration (JNI)" in
5+
# native_interop_guide.md.
6+
#
7+
# TODO(tarrinneal): Delete this file and its consumerProguardFiles entry in
8+
# build.gradle.kts once package:jni ships these rules:
9+
# https://github.com/dart-lang/native/issues/3732
10+
-keep class kotlin.Unit { *; }
11+
-keep class kotlin.Result { *; }
12+
-keep class kotlin.Result$Failure { *; }
13+
-keep class kotlin.coroutines.Continuation { *; }
14+
-keep class kotlin.coroutines.intrinsics.CoroutineSingletons { *; }
15+
-keep class kotlin.coroutines.intrinsics.IntrinsicsKt { *; }

‎packages/pigeon/platform_tests/test_plugin/android/src/main/kotlin/com/example/test_plugin/NativeInteropTests.gen.kt‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,7 @@ private object NativeInteropTestsPigeonUtils {
185185
* @property message The error message.
186186
* @property details The error details. Must be a datatype supported by the api codec.
187187
*/
188+
@Keep
188189
class NativeInteropTestsError(
189190
val code: String,
190191
override val message: String? = null,
@@ -193,23 +194,27 @@ class NativeInteropTestsError(
193194

194195
private const val defaultInstanceName = "PigeonDefaultClassName32uh4ui3lh445uh4h3l2l455g4y34u"
195196

197+
@Keep
196198
enum class NativeInteropAnEnum(val raw: Int) {
197199
ONE(0),
198200
TWO(1),
199201
THREE(2),
200202
FORTY_TWO(3),
201203
FOUR_HUNDRED_TWENTY_TWO(4);
202204

205+
@Keep
203206
companion object {
204207
fun ofRaw(raw: Int): NativeInteropAnEnum? {
205208
return values().firstOrNull { it.raw == raw }
206209
}
207210
}
208211
}
209212

213+
@Keep
210214
enum class NativeInteropAnotherEnum(val raw: Int) {
211215
JUST_IN_CASE(0);
212216

217+
@Keep
213218
companion object {
214219
fun ofRaw(raw: Int): NativeInteropAnotherEnum? {
215220
return values().firstOrNull { it.raw == raw }
@@ -218,6 +223,7 @@ enum class NativeInteropAnotherEnum(val raw: Int) {
218223
}
219224

220225
/** Generated class from Pigeon that represents data sent in messages. */
226+
@Keep
221227
data class NativeInteropUnusedClass(val aField: Any? = null) {
222228
companion object {
223229
fun fromList(pigeonVar_list: List<Any?>): NativeInteropUnusedClass {
@@ -259,6 +265,7 @@ data class NativeInteropUnusedClass(val aField: Any? = null) {
259265
*
260266
* Generated class from Pigeon that represents data sent in messages.
261267
*/
268+
@Keep
262269
data class NativeInteropAllTypes(
263270
val aBool: Boolean,
264271
val anInt: Long,
@@ -465,6 +472,7 @@ data class NativeInteropAllTypes(
465472
*
466473
* Generated class from Pigeon that represents data sent in messages.
467474
*/
475+
@Keep
468476
data class NativeInteropAllNullableTypes(
469477
val aNullableBool: Boolean? = null,
470478
val aNullableInt: Long? = null,
@@ -696,6 +704,7 @@ data class NativeInteropAllNullableTypes(
696704
*
697705
* Generated class from Pigeon that represents data sent in messages.
698706
*/
707+
@Keep
699708
data class NativeInteropAllNullableTypesWithoutRecursion(
700709
val aNullableBool: Boolean? = null,
701710
val aNullableInt: Long? = null,
@@ -917,6 +926,7 @@ data class NativeInteropAllNullableTypesWithoutRecursion(
917926
*
918927
* Generated class from Pigeon that represents data sent in messages.
919928
*/
929+
@Keep
920930
data class NativeInteropAllClassesWrapper(
921931
val allNullableTypes: NativeInteropAllNullableTypes,
922932
val allNullableTypesWithoutRecursion: NativeInteropAllNullableTypesWithoutRecursion? = null,
@@ -4368,6 +4378,7 @@ val registeredNativeInteropFlutterIntegrationCoreApi:
43684378
mutableMapOf()
43694379

43704380
/// Class that stores instances
4381+
@Keep
43714382
class NativeInteropFlutterIntegrationCoreApiRegistrar() {
43724383

43734384
/// Registers an instance with the given name.
@@ -4388,6 +4399,7 @@ class NativeInteropFlutterIntegrationCoreApiRegistrar() {
43884399
}
43894400
}
43904401

4402+
@Keep
43914403
interface NativeInteropFlutterIntegrationCoreApi {
43924404
/** A no-op function taking no arguments and returning no value, to sanity test basic calling. */
43934405
fun noop()
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
// Copyright 2013 The Flutter Authors
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file.
4+
5+
import 'package:integration_test/integration_test.dart';
6+
import 'package:shared_test_plugin_code/native_interop_integration_tests.dart';
7+
8+
/// Runs only the native interop tests.
9+
///
10+
/// Native interop reaches generated classes by name, which R8 can break in
11+
/// minified builds, so this is run as a release build with `flutter run`,
12+
/// which unlike `flutter test` and `flutter drive` supports release mode.
13+
void main() {
14+
IntegrationTestWidgetsFlutterBinding.ensureInitialized();
15+
runPigeonNativeInteropIntegrationTests(TargetGenerator.kotlin);
16+
}

0 commit comments

Comments
 (0)