From native code gems to Java treasures

Prerequisites

You need the following components to run the samples provided here:

• JDK 22+ installed on your machine.
• jextract binaries.
• Python installed for running the Python example.

How to use the sample with C code

1. Obtain Java bindings to C by running in a terminal window:

# macOS compatible command
export C_INCLUDE_PATH=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include
jextract --output src -t org.unix -I $C_INCLUDE_PATH $C_INCLUDE_PATH/time.h

# Linux
export C_INCLUDE_PATH=/usr/include/
jextract --output src -t org.unix -I $C_INCLUDE_PATH $C_INCLUDE_PATH/time.h

2. Run TimeTranslator.java with the following command:

# macOS and Linux compatible command
java --enable-native-access=ALL-UNNAMED --enable-preview --source 23 src/TimeTranslator.java

The --enable-native-access=ALL-UNNAMED option enables warning-free use for all code on the class path.

How to use the sample with Python code

1. Obtain Java bindings to Python by running in a terminal window:

# macOS and Linux compatible command
jextract --output src \
    -l :/Library/Frameworks/Python.framework/Versions/3.11/lib/libpython3.11.dylib \
    -I $/Library/Frameworks/Python.framework/Versions/3.11/include/python3.11 \
    -t org.python \
    /Library/Frameworks/Python.framework/Versions/3.11/include/python3.11/Python.h

2. Run PyDukerMaker.java with the following command:

# macOS and Linux compatible command
java --enable-native-access=ALL-UNNAMED --enable-preview --source 23 src/PyDukeMaker.java

How to use the sample for OpenGL

In order to run successfully, the following commands need also the presence of compile_flags.txt.

1. Dump of all the symbols encountered in a header file:

# macOS and Linux compatible command
jextract --output src \
    -l :/opt/homebrew/Cellar/freeglut/3.6.0/lib \
    -I /opt/homebrew/Cellar/freeglut \
    -I /opt/homebrew/Cellar/mesa \
    -I /opt/homebrew/Cellar/mesa-glu \
    -t org.freeglut \
    --dump-includes glut.symbols \
    /opt/homebrew/Cellar/freeglut/3.6.0/include/GL/freeglut.h

2. Obtain Java bindings to OpenGL by running the filtering file:

# macOS and Linux compatible command
jextract --output src \
    -l :/opt/homebrew/Cellar/freeglut/3.6.0/lib \
    -I /opt/homebrew/Cellar/freeglut \
    -I /opt/homebrew/Cellar/mesa \
    -I /opt/homebrew/Cellar/mesa-glu \
    -t org.freeglut @glut.symbols \
    /opt/homebrew/Cellar/freeglut/3.6.0/include/GL/freeglut.h

3. Run Teapot.java with:

java -XstartOnFirstThread --enable-native-access=ALL-UNNAMED src/Teapot.java

The JVM flag -XstartOnFirstThread is used to ensure that the Java application starts on the main thread of the first available GUI event dispatching thread when running on Mac OS X.

When debugging an application is useful to inspect the parameters passed to a native call. Code generated by jextract supports tracing of native calls, meaning parameters passed to native calls can be printed on the standard output.

To enable the tracing support, just pass the -Djextract.trace.downcalls=true flag as a VM argument when launching your application:

# macOS and Linux compatible command
java -XstartOnFirstThread -Djextract.trace.downcalls=true --enable-native-access=ALL-UNNAMED src/Teapot.java

How to run the sample with Rust

This example was created by Jorn Vernee and you can find out all about it by reading his blog post https://jornvernee.github.io/java/panama/rust/panama-ffi/2021/09/03/rust-panama-helloworld.html.

1. Obtain Java bindings to Rust by running in a terminal window:

jextract --output src -t org.rust --include-function hello_world \
  -l :./rust-panama-helloworld/target/debug/librust_panama_helloworld.dylib \
  rust-panama-helloworld/lib.h 

2. Run SimpleRust.java by using the following command:

java --enable-native-access=ALL-UNNAMED --enable-preview --source 23 src/SimpleRust.java