AGENTS.md

Flutter FFI package bridging to Unyo Core JVM runtime via JNI.

Project Type

Flutter package (not an app) with FFI JNI bindings
Uses package:jni and package:jnigen for Java interop
Main export: lib/aniyomi_bridge.dart

Flutter Version

Managed via FVM (Flutter Version Management):

Flutter 3.38.1 (see .fvmrc)
Use fvm flutter commands or ensure Flutter 3.38.1 is active

Key Commands

# Install dependencies
fvm flutter pub get

# Run tests
fvm flutter test

# Generate JNI bindings (jnigen)
fvm flutter pub run jnigen --config jnigen/aniyomibridge.yaml
fvm flutter pub run jnigen --config jnigen/headers.yaml
# ... (see jnigen/*.yaml for all configs)

# Run example app
fvm flutter run -C example

# Analyze
fvm flutter analyze

# Format
fvm dart format .

Architecture

lib/
├── aniyomi_bridge.dart      # Main API class (AniyomiBridge)
├── jni_isolate.dart          # JNI isolate worker (JVM runs in separate isolate)
├── jni_isolate_message.dart  # Message types for isolate communication
├── models/                   # Dart models (e.g., extension.dart)
└── jmodels/                  # JNI-generated Dart bindings (AUTO-GENERATED)
    ├── janiyomibridge.dart   # Generated from AniyomiBridge Java class
    ├── jsanime.dart          # Generated from SAnime
    ├── jsepisode.dart        # Generated from SEpisode
    ├── jvideo.dart           # Generated from Video
    └── ... (other j*.dart files)

jnigen/
├── aniyomibridge.yaml        # Config for generating janiyomibridge.dart
├── headers.yaml              # Config for jheaders.dart (okhttp3.Headers)
├── sanime.yaml, video.yaml, etc.  # Per-class generation configs

assets/
└── unyo-core.jar             # Java library (source of JNI bindings)

jre/
├── linux/customjre/          # Custom JRE for Linux builds
└── macos/customjre/          # Custom JRE for macOS builds

Code Generation (JNIGen)

The lib/jmodels/j*.dart files are auto-generated from Java classes via JNIGen:

Source JAR: assets/unyo-core.jar
Configs: jnigen/*.yaml (one per Java class)
Generated classes mirror eu.kanade.tachiyomi.* and dev.k3vinb5.unyo.core.*

Never manually edit jmodels/j*.dart files—regenerate via:

for config in jnigen/*.yaml; do
  fvm flutter pub run jnigen --config "$config"
done

JRE Requirements

This package requires a custom JRE bundled with the host application:

# Debug builds
./installJREDebug.sh linux   # or macos

# Release builds
./installJRERelease.sh linux # or macos

The scripts copy jre/<platform>/customjre/ into the Flutter build output.

Testing

Test directory: test/ (currently empty)
Example app: example/ (test the package here)

Key Dependencies

jni: ^0.14.2 / jnigen: ^0.14.2 — JNI bindings
logger: ^2.6.2 — Logging
path_provider: ^2.1.5, path, crypto — Storage utilities

Isolate Model

JNI operations run in a separate isolate (jni_isolate.dart) to avoid blocking the main thread. All Java calls are dispatched via JniIsolateMessage and results returned through ReceivePort.

Important Notes

Do not commit pubspec.lock — it's gitignored per Dart library conventions
analysis_options.yaml uses package:flutter_lints/flutter.yaml
The package exports extension loading from remote URLs (see example/lib/main.dart)

3.4 KiB Raw Permalink Blame History