https://github.com/digitalsmile/native-memory-processor
Java FFM API code generation library
https://github.com/digitalsmile/native-memory-processor
c clang code-generation cpp java java-22 java-ffm libclang native-code
Last synced: about 2 months ago
JSON representation
Java FFM API code generation library
- Host: GitHub
- URL: https://github.com/digitalsmile/native-memory-processor
- Owner: DigitalSmile
- License: apache-2.0
- Created: 2024-05-02T09:29:35.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-03-30T06:03:28.000Z (9 months ago)
- Last Synced: 2025-04-08T04:42:46.916Z (9 months ago)
- Topics: c, clang, code-generation, cpp, java, java-22, java-ffm, libclang, native-code
- Language: Java
- Homepage:
- Size: 46.3 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Java Native Memory Processing
#### Create an interop code with ease.
## Introduction
With the release of JDK 22 the new Foreign Function & Memory API (FFM API) has been introduced from preview phase.
This API is intended to substitute Java Native Interface (JNI) and become a standard of interacting with native code from Java.
While FFM API itself is very powerful and can provide access to onheap/offheap memory segments and call a native function, it is lacking of extended features of converting C/C++ structures to Java classes.
Of course, we have `jextract` tool, but the code it generates is kind of messy and hard to understand.
This project goal is to combine the power of FFM API and Java, like annotation processing, to make you happy while working with native functions and structures.
## Features
- two separate libraries - `annotation` and `annotation-processor` working with code generation during compile time
- C/C++ types support in top level: struct, union, enum (including anonymous and opaque)
- context based generation: combine several native libraries within one code base
- can load third party native libraries or use already loaded by classloader
- flexible native-to-java function declarations
- pass to native functions primitives and objects, by value or just a pointer
- java exceptions with the power of errno/strerr
- safe and clean code generation
- useful helpers to work with structures, like `.createEmpty()`
- ready to write your project unit tests with generated native structures
## Requirements
- `JDK22+` with FFM API enabled ( use `--enable-native-access=ALL-UNNAMED` run parameter or add `Enable-Native-Access: ALL-UNNAMED` to jar manifest file)
- `glibc 2.31+` (ubuntu 20.04+ or MacOS Sonoma+) on host machine where annotation processor is running (requirement for `libclang`).
Windows hosts are not yet supported.
## Quick start
1) Add dependencies to your `build.gradle`:
```groovy
dependencies {
// Annotations to use for code generation
implementation 'io.github.digitalsmile.native:annotation:${version}'
// Process annotations and generate code at compile time
annotationProcessor 'io.github.digitalsmile.native:annotation-processor:${version}'
}
```
2) Define interface class and run your build:
```java
@NativeMemory(header = "gpio.h")
@Structs
@Enums
public interface GPIO {
@NativeManualFunction(name = "ioctl", useErrno = true)
int nativeCall(int fd, long command, int data) throws NativeMemoryException;
}
```
This code snippet will generate all structures and enums within the header file `gpio.h` (located in `resources` folder), as well as `GPIONative` class with call implementation of `ioctl` native function.
Observe concepts in [doucmentation](CONCEPTS.md) or find more examples in [getting started](USAGE.md). You can also look at [tests](annotation-processor-test/src/test/java/io/github/digitalsmile/gpio) or in my other project https://github.com/digitalsmile/gpio
3) Enjoy! :)
## Plans
- more support of native C/C++ types and patterns
- validation of structures parameters and custom validation support