[jnigen] revamp readme #2670

goderbauer · 2025-10-06T13:52:08Z

This adds a simple "getting started" section to the readme to guide newcomers through setting up jnigen for a Flutter app. It also shuffles some sections around and reflows the text.

github-actions · 2025-10-06T13:54:16Z

PR Health

Breaking changes ✔️

Package	Change	Current Version	New Version	Needed Version	Looking good?

This check can be disabled by tagging the PR with skip-breaking-check.

Changelog Entry ✔️

Package	Changed Files

Changes to files need to be accounted for in their respective changelogs.

This check can be disabled by tagging the PR with skip-changelog-check.

API leaks ✔️

The following packages contain symbols visible in the public API, but not exported by the library. Export these symbols or remove them from your publicly visible API.

Package	Leaked API symbol	Leaking sources

This check can be disabled by tagging the PR with skip-leaking-check.

License Headers ✔️

// Copyright (c) 2025, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

Files
no missing headers

All source files should start with a license header.

Unrelated files missing license headers

Files
pkgs/objective_c/lib/src/ns_input_stream.dart

This check can be disabled by tagging the PR with skip-license-check.

coveralls · 2025-10-06T14:04:03Z

coverage: 81.228% (+0.4%) from 80.804%
when pulling 45719d8 on goderbauer:jnigenreadme
into 0924cb0 on dart-lang:main.

dcharkes

You have auto-line-break on, but it's not at 80 but 120? Is that intentional?

Should we have some standard for markdown files in this repo and enforce it with a ci check?

If it's not intentional, prefer not adding line-breaks to keep the git diff smaller and easier to review.

dcharkes · 2025-10-07T07:58:05Z

pkgs/jnigen/README.md

 ## Migrating to 0.14.2

-When regenerating bindings after an upgrade to JNIgen in the one file per class mode, you will need to delete the old bindings once to fix `A file that was not generated by JNIgen was found in ...` error.
+When regenerating bindings after an upgrade to JNIgen in the one file per class mode, you will need to delete the old


Should this be in the changelog instead?

It's already in there. I'll add some highlight to it and remove it from here.

dcharkes · 2025-10-07T07:59:18Z

pkgs/jnigen/README.md

-Experimental bindings generator for Java bindings through dart:ffi and JNI.

-`jnigen` scans compiled JAR files or Java source code to generate a description of the API, then uses it to generate Dart bindings. The Dart bindings call the C bindings, which in-turn call the Java functions through JNI. Shared functionality and base classes are provided through the support library, `package:jni`.
+Bindings generator to simplify calling Java APIs from Dart code via `dart:ffi` and JNI.


to simply calling -> to call

pkgs/jnigen/README.md

dcharkes · 2025-10-07T08:32:42Z

pkgs/jnigen/README.md

+Bindings are generated for methods, constructors, and fields. Exceptions thrown in Java are rethrown in Dart with stack
+trace from Java.
+
+More advanced features such as callbacks are not supported yet. Support for these features is tracked in the


Isn't this supported by now?

dcharkes · 2025-10-07T08:33:49Z

pkgs/jnigen/README.md

-Currently basic features of the Java language are supported in the bindings. Each Java class is mapped to a Dart class. Bindings are generated for methods, constructors and fields. Exceptions thrown in Java are rethrown in Dart with stack trace from Java.

-More advanced features such as callbacks are not supported yet. Support for these features is tracked in the [issue tracker](https://github.com/dart-lang/native/issues?q=is%3Aopen+is%3Aissue+label%3Apackage%3Ajni%2Cpackage%3Ajnigen).
+Currently basic features of the Java language are supported in the bindings. Each Java class is mapped to a Dart class.


Maybe we should rephrase this. We're no longer interested in mapping features 1-to-1 due to impedance mismatches. JNIgen is a layer-1 tool.

Side note: We should add the 3-layer markdown file on the repo here somewhere so that we can refer to it.

Do you have a suggested phrasing?

Maybe just: Bindings are generated for classes, methods, constructors, and fields. (leaving out how they are mapped or generated.)

dcharkes · 2025-10-07T08:36:02Z

pkgs/jnigen/README.md


-Dart standalone target is supported, but due to some problems with pubspec format, the `dart` command must be from Flutter SDK and not Dart SDK. See [dart-lang/pub#3563](https://github.com/dart-lang/pub/issues/3563).
+Dart standalone target is supported, but due to some problems with pubspec format, the `dart` command must be from the
+Flutter SDK and not Dart SDK. See [dart-lang/pub#3563](https://github.com/dart-lang/pub/issues/3563).


I think we might be able to make it Dart standalone when we have native assets in stable, and when we split out the android context into package:jni_flutter. cc @HosseinYousefi will know for sure.

For now let's leave the readme like this.

dcharkes · 2025-10-07T08:45:17Z

LGTM to overall flow! 🙏

HosseinYousefi · 2025-10-07T08:22:48Z

pkgs/jnigen/README.md

+   to the pubspec of your app by running:

-Check out the [examples](example/) to see some sample configurations.
+   ```shell


Now it's possible to do flutter pub add jni dev:jnigen.

HosseinYousefi · 2025-10-07T08:25:07Z

pkgs/jnigen/README.md

+Bindings are generated for methods, constructors, and fields. Exceptions thrown in Java are rethrown in Dart with stack
+trace from Java.
+
+More advanced features such as callbacks are not supported yet. Support for these features is tracked in the


Actually they are supported, I forgot to update this section!

HosseinYousefi · 2025-10-07T09:33:13Z

pkgs/jnigen/README.md


-Dart standalone target is supported, but due to some problems with pubspec format, the `dart` command must be from Flutter SDK and not Dart SDK. See [dart-lang/pub#3563](https://github.com/dart-lang/pub/issues/3563).
+Dart standalone target is supported, but due to some problems with pubspec format, the `dart` command must be from the
+Flutter SDK and not Dart SDK. See [dart-lang/pub#3563](https://github.com/dart-lang/pub/issues/3563).


For now let's leave the readme like this.

goderbauer · 2025-10-07T09:59:49Z

You have auto-line-break on, but it's not at 80 but 120? Is that intentional?

The reflow was intentional since most other markdowns in this repo also seem to implicitly follow a limit and it does make the file easier to read in environments that don't render the markdown. Not intentional was the 120 limit, should have been 80. That's fixed now.

goderbauer · 2025-10-07T12:59:08Z

cc @stuartmorgan-g Are you interested in taking a look at the revamped readme to incorporate your feedback?

stuartmorgan-g

This new intro is great! This definitely addresses the core of #1640 from my perspective. I think the notes in that issue about the Requirements section are probably still valid, but it also makes sense to address those separately, so we can split them into a new issue.

I flagged a couple of nits that I happened to notice while re-reading the whole doc, but they are for pre-existing sections so feel free to ignore them here.

stuartmorgan-g · 2025-10-08T13:52:30Z

pkgs/jnigen/README.md

+| Android  | n/a             | Supported |
+| Linux    | Supported       | Supported |
+| Windows  | Supported       | Supported |
+| MacOS    | Supported       | Not Yet   |


Nit while the file is being overhauled: the name of the OS is macOS, not MacOS. (It's confusing because it used to be Mac OS X.)

stuartmorgan-g · 2025-10-08T13:53:08Z

pkgs/jnigen/README.md

-## Note on Dart (standalone) target
-`package:jni` is an FFI plugin containing native code, and any bindings generated from jnigen contains native code too.
+`package:jni` is an FFI plugin containing native code, and any bindings
+generated from jnigen contains native code too.


Nit: contain

stuartmorgan-g · 2025-10-08T13:57:05Z

pkgs/jnigen/README.md

+application targeting Android. It assumes that Flutter has been set up to build
+apps for Android 
+([instructions](https://docs.flutter.dev/platform-integration/android/setup))
+and that the Flutter app was created via `flutter create in_app_java`.


It might be worth adding a forward-link to the Requirements section here? Maybe something like "If you encounter issues running the commands below, check [the detailed setup requirements](...)".

[jnigen] revamp readme

b574d11

github-actions bot added the package:jnigen label Oct 6, 2025

typos

bea6099

type

c2a2db1

goderbauer requested review from dcharkes and HosseinYousefi October 6, 2025 14:05

goderbauer mentioned this pull request Oct 6, 2025

[jnigen] migrate in_app_java example to Dart API #2671

Merged

wordsmithing

ff130b0

dcharkes approved these changes Oct 7, 2025

View reviewed changes

goderbauer mentioned this pull request Oct 7, 2025

[ffigen,jnigen] Align the Dart API between ffigen and jnigen #2673

Open

HosseinYousefi approved these changes Oct 7, 2025

View reviewed changes

goderbauer added 3 commits October 7, 2025 12:05

review and reflow

c930f5f

tweaks

2b12c17

++

464e851

goderbauer added 2 commits October 8, 2025 09:58

empty to trigger CI

e7ed8d4

clarify that the example runs on Android

7cf1ea3

stuartmorgan-g approved these changes Oct 8, 2025

View reviewed changes

review

45719d8

goderbauer added the autosubmit label Oct 8, 2025

auto-submit bot merged commit 2760e5d into dart-lang:main Oct 8, 2025
36 checks passed

goderbauer deleted the jnigenreadme branch October 9, 2025 07:38

[jnigen] revamp readme #2670

[jnigen] revamp readme #2670

Conversation

goderbauer commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Oct 6, 2025

PR Health

Uh oh!

coveralls commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dcharkes 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!

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

Uh oh!

dcharkes commented Oct 7, 2025

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!

goderbauer commented Oct 7, 2025

Uh oh!

goderbauer commented Oct 7, 2025

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!

Uh oh!

Uh oh!

goderbauer commented Oct 6, 2025 •

edited

Loading

coveralls commented Oct 6, 2025 •

edited

Loading