[jnigen] Improve the UX of Jni.spawn for Dart standalone (#1916)

* Clarify setup for jnigen on Windows - Add section for generating java types
* Do not require setting `dylibDir` explicitly when running `Jni.spawn`
* Improve docs and error messages

Co-authored-by: Hossein Yousefi <[email protected]>

Author: dickermoshe

pkgs/jni/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.14.0-wip
+
+- Added `DynamicLibraryLoadError` which is thrown when the dynamic library fails
+  to load. `HelperNotFoundError` will only be thrown when the helper library
+  cannot be found.
+- Update the README.md to include info about generating bindings for built-in
+  java types.
+- Do not require a `dylibDir` when running `Jni.spawn` from Dart standalone,
+  instead use the default value of `build/jni_libs`.
+
 ## 0.13.0
 
 - **Breaking Change**: Separated primitive arrays from object arrays.

pkgs/jni/bin/setup.dart

@@ -12,7 +12,7 @@ const jniNativeBuildDirective =
     '# jni_native_build (Build with jni:setup. Do not delete this line.)';
 
 // When changing this constant here, also change corresponding path in
-// test/test_util.
+// test/test_util, and the default value for `Jni._dylibDir`.
 const _defaultRelativeBuildPath = 'build/jni_libs';
 
 const _buildPath = 'build-path';

pkgs/jni/lib/src/errors.dart

@@ -2,6 +2,8 @@
 // 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.
 
+import 'dart:io';
+
 import 'third_party/generated_bindings.dart';
 
 // TODO(#567): Add the fact that [JException] is now a [JObject] to the
@@ -100,9 +102,30 @@ final class HelperNotFoundError extends Error {
 
   @override
   String toString() => '''
-Lookup for helper library $path failed.
-Please ensure that `dartjni` shared library is built.
-Provided jni:setup script can be used to build the shared library.
-If the library is already built, ensure that the JVM libraries can be 
-loaded from Dart.''';
+Unable to locate the helper library.
+
+Ensure that the helper library is available at the path: $path
+Run `dart jni:setup` to generate the shared library if it does not exist.
+
+Note: If the --build-path option is passed to jni:setup, Jni.spawn must be
+called with same dylibDir. Also when creating new Dart isolates, Jni.setDylibDir
+must be called.
+''';
+}
+
+final class DynamicLibraryLoadError extends Error {
+  final String libraryPath;
+
+  DynamicLibraryLoadError(this.libraryPath);
+
+  @override
+  String toString() {
+    return '''
+Failed to load dynamic library at path: $libraryPath
+The library was found at the specified path, but it could not be loaded. 
+This might be due to missing dependencies or incorrect file permissions. 
+Please ensure ${Platform.isWindows ? r'that `\bin\server\jvm.dll` is in the PATH, and ' : ''}that the file has the correct permissions.
+
+''';
+  }
 }

pkgs/jni/lib/src/jni.dart

@@ -36,11 +36,15 @@ String _getLibraryFileName(String base) {
 DynamicLibrary _loadDartJniLibrary({String? dir, String baseName = 'dartjni'}) {
   final fileName = _getLibraryFileName(baseName);
   final libPath = (dir != null) ? join(dir, fileName) : fileName;
+  final file = File(libPath);
+  if (!file.existsSync()) {
+    throw HelperNotFoundError(libPath);
+  }
   try {
     final dylib = DynamicLibrary.open(libPath);
     return dylib;
   } catch (_) {
-    throw HelperNotFoundError(libPath);
+    throw DynamicLibraryLoadError(libPath);
   }
 }
 
@@ -50,7 +54,7 @@ abstract final class Jni {
   static final JniBindings _bindings = JniBindings(_dylib);
 
   /// Store dylibDir if any was used.
-  static String? _dylibDir;
+  static String _dylibDir = join('build', 'jni_libs');
 
   /// Sets the directory where dynamic libraries are looked for.
   /// On dart standalone, call this in new isolate before doing
@@ -108,7 +112,7 @@ abstract final class Jni {
     int jniVersion = JniVersions.JNI_VERSION_1_6,
   }) =>
       using((arena) {
-        _dylibDir = dylibDir;
+        _dylibDir = dylibDir ?? _dylibDir;
         final jvmArgs = _createVMArgs(
           options: jvmOptions,
           classPath: classPath,

pkgs/jni/pubspec.yaml

@@ -4,7 +4,7 @@
 
 name: jni
 description: A library to access JNI from Dart and Flutter that acts as a support library for package:jnigen.
-version: 0.13.0
+version: 0.14.0-wip
 repository: https://github.com/dart-lang/native/tree/main/pkgs/jni
 issue_tracker: https://github.com/dart-lang/native/issues?q=is%3Aissue+is%3Aopen+label%3Apackage%3Ajni
 
@@ -16,8 +16,8 @@ topics:
   - jni
 
 environment:
-  sdk: '>=3.3.0 <4.0.0'
-  flutter: '>=2.11.0'
+  sdk: ">=3.3.0 <4.0.0"
+  flutter: ">=2.11.0"
 
 dependencies:
   args: ^2.5.0

pkgs/jni/test/isolate_test.dart

@@ -24,7 +24,6 @@ void run({required TestRunnerCallback testRunner}) {
     final foo = 'foo'.toJString();
     final port = ReceivePort();
     await Isolate.spawn((sendPort) {
-      Jni.setDylibDir(dylibDir: 'build/jni_libs');
       sendPort.send(foo.toDartString());
       Isolate.current.kill();
     }, port.sendPort);
@@ -37,7 +36,6 @@ void run({required TestRunnerCallback testRunner}) {
     // isolates.
     'foo'.toJString();
     await Isolate.spawn((_) {
-      Jni.setDylibDir(dylibDir: 'build/jni_libs');
       'bar'.toJString();
       Isolate.current.kill();
     }, null);

pkgs/jni/test/jobject_test.dart

@@ -225,12 +225,6 @@ void run({required TestRunnerCallback testRunner}) {
   testRunner('Isolate', () async {
     final receivePort = ReceivePort();
     await Isolate.spawn((sendPort) {
-      // On standalone target, make sure to call [setDylibDir] before accessing
-      // any JNI function in a new isolate.
-      //
-      // otherwise subsequent JNI calls will throw a "library not found"
-      // exception.
-      Jni.setDylibDir(dylibDir: 'build/jni_libs');
       final randomClass = JClass.forName('java/util/Random');
       final random =
           randomClass.constructorId('()V').call(randomClass, JObject.type, []);

pkgs/jnigen/README.md

@@ -135,7 +135,9 @@ More advanced features such as callbacks are not supported yet. Support for thes
 
 On Flutter targets, native libraries are built automatically and bundled. On standalone platforms, no such infrastructure exists yet. As a stopgap solution, running `dart run jni:setup` in a target directory builds all JNI native dependencies of the package into `build/jni_libs`. 
 
-The build directory has to be passed to `Jni.spawn` call. It's assumed that all dependencies are built into the same target directory, so that once JNI is initialized, generated bindings can load their respective C libraries automatically.
+To start a JVM, call `Jni.spawn`. It's assumed that all dependencies are built into the same target directory, so that once JNI is initialized, generated bindings can load their respective C libraries automatically.
+
+If a custom build path has been set for the dynamic libraries built by `dart run jni:setup --build-path path/to/dylib`, the same path must be passed to `Jni.spawn`. Also anytime a new Dart isolate is spawned, the directory must be set again using `Jni.setDylibDir`.
 
 ## Requirements
 ### SDK
@@ -154,9 +156,11 @@ __On windows, append the path of `jvm.dll` in your JDK installation to PATH.__
 For example, on Powershell:
 
 ```powershell
-$env:Path += ";${env:JAVA_HOME}\bin\server".
+$env:Path += ";${env:JAVA_HOME}\bin\server"
 ```
 
+Note: The above will only add `jvm.dll` to `PATH` for the current Powershell session, use the Control Panel to add it to path permanently.
+
 If JAVA_HOME not set, find the `java.exe` executable and set the environment variable in Control Panel. If java is installed through a package manager, there may be a more automatic way to do this. (Eg: `scoop reset`).
 
 ### C tooling
@@ -179,6 +183,22 @@ If the classes are in JAR file, make sure to provide path to JAR file itself, an
 #### `jnigen` is unable to parse sources.
 If the errors are similar to `symbol not found`, ensure all dependencies of the source are available. If such dependency is compiled, it can be included in `class_path`.
 
+#### Generate bindings for built-in types
+To generate bindings for built-in Java types (like those in `java.*` packages), you need to provide the OpenJDK source code to the generator. Here's how:
+
+1. Locate the `src.zip` file in your Java installation directory
+2. Extract the `java.base` folder from this zip file
+3. Add the path to the extracted `java.base` folder in your `source_path` list in the YAML configuration
+
+For example, to generate bindings for `java.lang.Math`, your configuration might look like:
+
+```yaml
+source_path:
+  - '/path/to/extracted/java.base'
+classes:
+  - 'java.lang.Math'
+```
+
 #### How are classes mapped into bindings?
 Each Java class generates a subclass of `JObject` class, which wraps a `jobject` reference in JNI. Nested classes use `_` as separator, `Example.NestedClass` will be mapped to `Example_NestedClass`.
 
@@ -248,7 +268,7 @@ Currently we don't have an automatic mechanism for using these. You can unpack t
 However there are 2 caveats to this caveat.
 
 * SDK stubs after version 28 are incomplete. OpenJDK Doclet API we use to generate API summaries will error on incomplete sources.
-* The API can't process the `java.**` namespaces in the Android SDK stubs, because it expects a module layout. So if you want to generate bindings for, say, `java.lang.Math`, you cannot use the Android SDK stubs. OpenJDK sources can be used instead.
+* The API can't process the `java.**` namespaces in the Android SDK stubs, because it expects a module layout. So if you want to generate bindings for, say, `java.lang.Math`, you cannot use the Android SDK stubs. OpenJDK sources can be used instead. See [Generate bindings for built-in types](#generate-bindings-for-built-in-types) above for instructions on how to use OpenJDK sources.
 
 The JAR files (`$SDK_ROOT/platforms/android-$VERSION/android.jar`) can be used instead. But compiled JARs do not include JavaDoc and method parameter names. This JAR is automatically included by Gradle when `android_sdk_config` >> `add_gradle_deps` is specified.