Tag: dart

Prepare to embark on a groundbreaking journey through the realms of Flutter as we uncover the remarkable new feature—JNIgen. In this blog, we pull back the curtain to reveal JNIgen’s transformative power, from simplifying intricate tasks to amplifying scalability; this blog serves as a guiding light along the path to a seamlessly integrated Flutter ecosystem.

As Flutter continues to mesmerize developers with its constant evolution, each release unveiling a treasure trove of thrilling new features, the highly anticipated Google I/O 2023 was an extraordinary milestone. Amidst the excitement, a groundbreaking technique was unveiled: JNIgen, offering effortless access to native code like never before.

Let this blog guide you towards a future where your Flutter projects transcend limitations and manifest into awe-inspiring creations.

1. What is JNIgen?

JNIgen, which stands for Java native interface generator,  is an innovative tool that automates the process of generating Dart bindings for Android APIs accessible through Java or Kotlin code. By utilizing these generated bindings, developers can invoke Android APIs with a syntax that closely resembles native code.

With JNIgen, developers can seamlessly bridge the gap between Dart and the rich ecosystem of Android APIs. This empowers them to leverage the full spectrum of Android’s functionality, ranging from system-level operations to platform-specific features. By effortlessly integrating with Android APIs through JNIgen-generated bindings, developers can harness the power of native code and build robust applications with ease.

1.1. Default approach: 

In the current Flutter framework, we rely on Platform channels to establish a seamless communication channel between Dart code and native code. These channels serve as a bridge for exchanging messages and data.

Typically, we have a Flutter app acting as the client, while the native code contains the desired methods to be executed. The Flutter app sends a message containing the method name to the native code, which then executes the requested method and sends the response back to the Flutter app.

However, this approach requires the manual implementation of handlers on both the Dart and native code sides. It entails writing code to handle method calls and manage the exchange of responses. Additionally, developers need to carefully manage method names and channel names on both sides to ensure proper communication.

1.2. Working principle of JNIgen: 

In JNIgen, our native code path is passed to the JNIgen generator, which initiates the generation of an intermediate layer of C code. This C code is followed by the necessary boilerplate in Dart, facilitating access to the C methods. All data binding and C files are automatically generated in the directory specified in the .yaml file, which we will explore shortly.

Consequently, as a Flutter application, our interaction is solely focused on interfacing with the newly generated Dart code, eliminating the need for direct utilization of native code.

1.3. Similar tools: 

During the Google I/O 2023 event, JNIgen was introduced as a tool for native code integration. However, it is important to note that not all external libraries available on www.pub.dev are developed exclusively using channels. Another tool, FFIgen, was introduced earlier at Google I/O 2021 and serves a similar purpose. Both FFIgen and JNIgen function similarly, converting native code into intermediate C code with corresponding Dart dependencies to establish the necessary connections.

While JNIgen primarily facilitates communication between Android native code and Dart code, FFIgen has become the preferred choice for establishing communication between iOS native code and Dart code. Both tools are specifically designed to convert native code into intermediate code, enabling seamless interoperability within their respective platforms.

2. Configuration

Prior to proceeding with the code implementation, it is essential to set up and install the necessary tools.

2.1. System setup: 

2.1.1 Install MVN

Windows

• Download the Maven archive for Windows from the link here [download Binary zip archive]
• After Extracting the zip file, you will get a folder with name “apache-maven-x.x.x”
• Create a new folder with the name “ApacheMaven” in “C:Program Files” and paste the above folder in it. [Your current path will be “C:Program FilesApacheMavenapache-maven-x.x.x”]
• Add the following entry in “Environment Variable” →  “User Variables”
  M2 ⇒ “C:Program FilesApacheMavenapache-maven-x.x.xbin”
  M2_HOME ⇒ “C:Program FilesApacheMavenapache-maven-x.x.x”
• Add a new entry “%M2_HOME%bin” in “path” variable

Mac

• Download Maven archive for mac from the link here [download Binary tar.gz archive]
• Run the following command where you have downloaded the *.tar.gz file

tar -xvf apache-maven-3.8.7.bin.tar.gz

tar -xvf apache-maven-3.8.7.bin.tar.gz

• Add the following entry in .zshrc or .bash_profile to set Maven path “export PATH=”$PATH:/Users/username/Downloads/apache-maven-x.x.x/bin”

Or

• You can use brew to install llvm 

brew install llvm

brew install llvm

• Brew will give you instruction like this for further setup

==> llvm
To use the bundled libc++ please add the following LDFLAGS:
LDFLAGS="-L/opt/homebrew/opt/llvm/lib/c++ -Wl,-rpath,/opt/homebrew/opt/llvm/lib/c++"
llvm is keg-only, which means it was not symlinked into /opt/homebrew,
because macOS already provides this software and installing another version in
parallel can cause all kinds of trouble.
If you need to have llvm first in your PATH, run:
echo 'export PATH="/opt/homebrew/opt/llvm/bin:$PATH"' >> ~/.zshrc
For compilers to find llvm you may need to set:
export LDFLAGS="-L/opt/homebrew/opt/llvm/lib"
export CPPFLAGS="-I/opt/homebrew/opt/llvm/include"

==> llvm
To use the bundled libc++ please add the following LDFLAGS:
LDFLAGS="-L/opt/homebrew/opt/llvm/lib/c++ -Wl,-rpath,/opt/homebrew/opt/llvm/lib/c++"

llvm is keg-only, which means it was not symlinked into /opt/homebrew,
because macOS already provides this software and installing another version in
parallel can cause all kinds of trouble.

If you need to have llvm first in your PATH, run:
echo 'export PATH="/opt/homebrew/opt/llvm/bin:$PATH"' >> ~/.zshrc

For compilers to find llvm you may need to set:
export LDFLAGS="-L/opt/homebrew/opt/llvm/lib"
export CPPFLAGS="-I/opt/homebrew/opt/llvm/include"

2.1.1 Install Clang-Format

Windows

• Download the latest version of LLVM for windows from the link here

Mac

• Run the following brew command: 

brew install clang-format

brew install clang-format

2.2. Flutter setup: 

2.2.1 Get Dependencies

Run the following commands with Flutter:

flutter pub add jni

flutter pub add jni

flutter pub add jnigen

flutter pub add jnigen

2.2.2 Setup configuration file

Figure 01 provides a visual representation of the .yaml file, which holds crucial configurations utilized by JNIgen. These configurations serve the purpose of identifying paths for native classes, as well as specifying the locations where JNIgen generates the resulting C and Dart files. Furthermore, the .yaml file allows for specifying Maven configurations, enabling the selection of specific third-party libraries that need to be downloaded to facilitate code generation.

By leveraging the power of the .yaml file, developers gain control over the path identification process and ensure that the generated code is placed in the desired locations. Additionally, the ability to define Maven configurations grants flexibility in managing dependencies, allowing the seamless integration of required third-party libraries into the generated code. This comprehensive approach enables precise control and customization over the code generation process, enhancing the overall efficiency and effectiveness of the development workflow.

Let’s explore the properties that we have utilized within the .yaml file (Please refer “3.2.2. code implementation” section’s example for better understanding):

• android_sdk_config: 

When the value of a specific property is set to “true,” it triggers the execution of a Gradle stub during the invocation of JNIgen. Additionally, it includes the Android compile classpath in the classpath of JNIgen. However, to ensure that all dependencies are cached appropriately, it is necessary to have previously performed a release build.

• output 

As the name implies, the “output” section defines the configuration related to the generation of intermediate code. This section plays a crucial role in determining how the intermediate code will be generated and organized.

•  c >> library_name &&  c >> path:
  Here we are setting details for c_based binding code.

•  dart >> path &&  dart >> structure:

Here we are defining configuration for dart_based binding code.

•  source_path:

These are specific directories that are scanned during the process of locating the relevant source files.

•  classes:

By providing a comprehensive list of classes or packages, developers can effectively control the scope of the code generation process. This ensures that the binding code is generated only for the desired components, minimizing unnecessary code generation

By utilizing these properties within the .yaml file, developers can effectively control various aspects of the code generation process, including path identification, code organization, and dependency management. To get more in-depth information, please check out the official documentation here.

2.3. Generate bindings files:

Once this setup is complete, the final step for JNIgen is to obtain the jar file that will be scanned to generate the required bindings. To initiate the process of generating the Android APK, you can execute the following command:

flutter build apk

flutter build apk

Run the following command in your terminal to generate code:

dart run jnigen --config jnigen.yaml

dart run jnigen --config jnigen.yaml

2.3. Android setup: 

Add the address of CMakeLists.txt file in your android >> app >> build.gradle file’s buildTypes section:

buildTypes {
        externalNativeBuild {
            cmake {
                path <address of CMakeLists.txt>
            }
        }
    }

buildTypes {
        externalNativeBuild {
            cmake {
                path <address of CMakeLists.txt>
            }
        }
    }

With this configuration, we are specifying the path for the CMake file that will been generated by JNIgen.This path declaration is crucial for identifying the location of the generated CMake file within the project structure.

With the completion of the aforementioned steps, you are now ready to run your application and leverage all the native functions that have been integrated.

3. Sample Project

To gain hands-on experience and better understand the JNIgen, let’s create a small project together. Follow the steps below to get started. 

Let’s start with:

3.1. Packages & directories:

3.1.1 Create a project using the following command:

flutter create jnigen_integration_project

flutter create jnigen_integration_project

3.1.2 Add these under dependencies of pubspec.yaml (and run command flutter pub get):

jni: ^0.5.0
jnigen: ^0.5.0

jni: ^0.5.0
jnigen: ^0.5.0

3.1.3. Got to android >> app >> src >> main directory.

3.1.4. Create directories inside the main as show below:

‍

3.2. Code Implementation:

3.2.1 We will start with Android code. Create 2 files HardwareUtils.java & HardwareUtilsKotlin.kt inside the utils directory.

 HardwareUtilsKotlin.kt

package com.hardware.utils
import android.os.Build
class HardwareUtilsKotlin {
   fun getHardwareDetails(): Map<String, String>? {
       val hardwareDetails: MutableMap<String, String> = HashMap()
       hardwareDetails["Language"] = "Kotlin"
       hardwareDetails["Manufacture"] = Build.MANUFACTURER
       hardwareDetails["Model No."] = Build.MODEL
       hardwareDetails["Type"] = Build.TYPE
       hardwareDetails["User"] = Build.USER
       hardwareDetails["SDK"] = Build.VERSION.SDK
       hardwareDetails["Board"] = Build.BOARD
       hardwareDetails["Version Code"] = Build.VERSION.RELEASE
       return hardwareDetails
   }
}

package com.hardware.utils

import android.os.Build

class HardwareUtilsKotlin {

   fun getHardwareDetails(): Map<String, String>? {
       val hardwareDetails: MutableMap<String, String> = HashMap()
       hardwareDetails["Language"] = "Kotlin"
       hardwareDetails["Manufacture"] = Build.MANUFACTURER
       hardwareDetails["Model No."] = Build.MODEL
       hardwareDetails["Type"] = Build.TYPE
       hardwareDetails["User"] = Build.USER
       hardwareDetails["SDK"] = Build.VERSION.SDK
       hardwareDetails["Board"] = Build.BOARD
       hardwareDetails["Version Code"] = Build.VERSION.RELEASE
       return hardwareDetails
   }
}

 HardwareUtils.java 

package com.hardware.utils;
import android.os.Build;
import java.util.HashMap;
import java.util.Map;
public class HardwareUtils {
   public Map<String, String> getHardwareDetails() {
       Map<String, String> hardwareDetails = new HashMap<String, String>();
       hardwareDetails.put("Language", "JAVA");
       hardwareDetails.put("Manufacture", Build.MANUFACTURER);
       hardwareDetails.put("Model No.", Build.MODEL);
       hardwareDetails.put("Type", Build.TYPE);
       hardwareDetails.put("User", Build.USER);
       hardwareDetails.put("SDK", Build.VERSION.SDK);
       hardwareDetails.put("Board", Build.BOARD);
       hardwareDetails.put("Version Code", Build.VERSION.RELEASE);
       return hardwareDetails;
   }
   public Map<String, String> getHardwareDetailsKotlin() {
       return new HardwareUtilsKotlin().getHardwareDetails();
   }
}

package com.hardware.utils;


import android.os.Build;


import java.util.HashMap;
import java.util.Map;


public class HardwareUtils {


   public Map<String, String> getHardwareDetails() {
       Map<String, String> hardwareDetails = new HashMap<String, String>();
       hardwareDetails.put("Language", "JAVA");
       hardwareDetails.put("Manufacture", Build.MANUFACTURER);
       hardwareDetails.put("Model No.", Build.MODEL);
       hardwareDetails.put("Type", Build.TYPE);
       hardwareDetails.put("User", Build.USER);
       hardwareDetails.put("SDK", Build.VERSION.SDK);
       hardwareDetails.put("Board", Build.BOARD);
       hardwareDetails.put("Version Code", Build.VERSION.RELEASE);
       return hardwareDetails;
   }


   public Map<String, String> getHardwareDetailsKotlin() {
       return new HardwareUtilsKotlin().getHardwareDetails();
   }


}

3.2.2 To provide the necessary configurations to JNIGen for code generation, we will create a .yaml file named JNIgen.yaml in the root of the project.

   jnigen.yaml 

android_sdk_config:
 add_gradle_deps: true
output:
 c:
   library_name: hardware_utils
   path: src/
 dart:
   path: lib/hardware_utils.dart
   structure: single_file
source_path:
 - 'android/app/src/main/java'
classes:
 - 'com.hardware.utils'

android_sdk_config:
 add_gradle_deps: true


output:
 c:
   library_name: hardware_utils
   path: src/
 dart:
   path: lib/hardware_utils.dart
   structure: single_file


source_path:
 - 'android/app/src/main/java'


classes:
 - 'com.hardware.utils'

3.2.3 Let’s generate C & Dart code.

Execute the following command to create APK:

flutter build apk

flutter build apk

After the successful execution of the above command, execute the following command:

dart run jnigen --config jnigen.yaml

dart run jnigen --config jnigen.yaml

3.2.4 Add the address of CMakeLists.txt in your android >> app >> build.gradle file’s buildTypes section as shown below :

buildTypes {
        externalNativeBuild {
            cmake {
                path "../../src/CMakeLists.txt"
            }
        }
  }

buildTypes {
        externalNativeBuild {
            cmake {
                path "../../src/CMakeLists.txt"
            }
        }
  }

3.2.5. Final step is to call the methods from Dart code, which was generated by JNIgen.

To do this, replace the MyHomePage class code with the below code from main.dart file.

class MyHomePage extends StatefulWidget {
 const MyHomePage({super.key, required this.title});
 final String title;
 @override
 State<MyHomePage> createState() => _MyHomePageState();
}
class _MyHomePageState extends State<MyHomePage> {
 String _hardwareDetails = '';
 String _hardwareDetailsKotlin = '';
 JObject activity = JObject.fromRef(Jni.getCurrentActivity());
 @override
 void initState() {
   JMap<JString, JString> deviceHardwareDetails =
       HardwareUtils().getHardwareDetails();
   _hardwareDetails = 'This device details from Java class:n';
   deviceHardwareDetails.forEach((key, value) {
     _hardwareDetails =
         '$_hardwareDetailsn${key.toDartString()} is ${value.toDartString()}';
   });
   JMap<JString, JString> deviceHardwareDetailsKotlin =
       HardwareUtils().getHardwareDetailsKotlin();
   _hardwareDetailsKotlin = 'This device details from Kotlin class:n';
   deviceHardwareDetailsKotlin.forEach((key, value) {
     _hardwareDetailsKotlin =
         '$_hardwareDetailsKotlinn${key.toDartString()} is ${value.toDartString()}';
   });
   setState(() {
     _hardwareDetails;
     _hardwareDetailsKotlin;
   });
   super.initState();
 }
 @override
 Widget build(BuildContext context) {
   return Scaffold(
     appBar: AppBar(
       title: Text(widget.title),
     ),
     body: Center(
       child: Column(
         mainAxisAlignment: MainAxisAlignment.center,
         children: <Widget>[
           Text(
             _hardwareDetails,
             textAlign: TextAlign.center,
           ),
           SizedBox(height: 20,),
           Text(
             _hardwareDetailsKotlin,
             textAlign: TextAlign.center,
           ),
         ],
       ),
     ),
   );
 }
}

class MyHomePage extends StatefulWidget {
 const MyHomePage({super.key, required this.title});

 final String title;

 @override
 State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
 String _hardwareDetails = '';
 String _hardwareDetailsKotlin = '';
 JObject activity = JObject.fromRef(Jni.getCurrentActivity());

 @override
 void initState() {
   JMap<JString, JString> deviceHardwareDetails =
       HardwareUtils().getHardwareDetails();
   _hardwareDetails = 'This device details from Java class:n';
   deviceHardwareDetails.forEach((key, value) {
     _hardwareDetails =
         '$_hardwareDetailsn${key.toDartString()} is ${value.toDartString()}';
   });

   JMap<JString, JString> deviceHardwareDetailsKotlin =
       HardwareUtils().getHardwareDetailsKotlin();
   _hardwareDetailsKotlin = 'This device details from Kotlin class:n';
   deviceHardwareDetailsKotlin.forEach((key, value) {
     _hardwareDetailsKotlin =
         '$_hardwareDetailsKotlinn${key.toDartString()} is ${value.toDartString()}';
   });

   setState(() {
     _hardwareDetails;
     _hardwareDetailsKotlin;
   });
   super.initState();
 }

 @override
 Widget build(BuildContext context) {
   return Scaffold(
     appBar: AppBar(
       title: Text(widget.title),
     ),
     body: Center(
       child: Column(
         mainAxisAlignment: MainAxisAlignment.center,
         children: <Widget>[
           Text(
             _hardwareDetails,
             textAlign: TextAlign.center,
           ),
           SizedBox(height: 20,),
           Text(
             _hardwareDetailsKotlin,
             textAlign: TextAlign.center,
           ),
         ],
       ),
     ),
   );
 }
}

After all of this, when we launch our app, we will see information about our Android device.

4. Result

For your convenience, the complete code for the project can be found here. Feel free to refer to this code repository for a comprehensive overview of the implementation details and to access the entirety of the source code.

5. Conclusion

In conclusion, we explored the limitations of the traditional approach to native API access in Flutter for mid to large-scale projects. Through our insightful exploration of JNIgen’s working principles, we uncovered its remarkable potential for simplifying the native integration process.

By gaining a deep understanding of JNIgen’s inner workings, we successfully developed a sample project and provided detailed guidance on the essential setup requirements. Armed with this knowledge, developers can embrace JNIgen’s capabilities to streamline their native integration process effectively.

We can say that JNIgen is a valuable tool for Flutter developers seeking to combine the power of Flutter’s cross-platform capabilities with the flexibility and performance benefits offered by native code. It empowers developers to build high-quality apps that seamlessly integrate platform-specific features and existing native code libraries, ultimately enhancing the overall user experience. 

Hopefully, this blog post has inspired you to explore the immense potential of JNIgen in your Flutter applications. By harnessing the JNIgen, we can open doors to new possibilities.

Thank you for taking the time to read through this blog!

6. Reference

1. https://docs.flutter.dev/
2. https://pub.dev/packages/jnigen
3. https://pub.dev/packages/jni
4. https://github.com/dart-lang/jnigen
5. https://github.com/dart-lang/jnigen#readme
6. https://github.com/dart-lang/jnigen/wiki/Architecture-&-Design-Notes
7. https://medium.com/simform-engineering/jnigen-an-easy-way-to-access-platform-apis-cb1fd3101e33
8. https://medium.com/@marcoedomingos/the-ultimate-showdown-methodchannel-vs-d83135f2392d