Setup Guide

This setup guide covers the standard use-case of generating and integrating native bindings into a Java project with a main source set.

Prerequisites

You should have these things in place before you start:

• JVM 17 or above
• A Gradle project using Gradle v8.8 or above

Including the Plugin

This will configure the project to download and use Jextract 22 which is determined from the Java toolchain.

Tip

See the latest version on Gradle plugin portal.

Kotlin

build.gradle.kts

plugins {
    `java-library`
    id("de.infolektuell.jextract") version "x.y.z"
}

repositories {
    mavenCentral()
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(22)
    }
}

Groovy

build.gradle

plugins {
    id 'java-library'
    id 'de.infolektuell.jextract' version 'x.y.z'
}

repositories {
    mavenCentral()
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of 22
    }
}

Adding a Library

Libraries often consist of a name.h file and binaries like libname.dylib or name.dll. Put them in your source folder like this:

• Directorylib

  • Directorysrc

    • Directorymain

      • Directoryjava

        • Directorycom

          • Directoryexample

            • Directorygreeting

              • greeting.java
      • Directorynative

        • Directorymacos

          • libgreeting.dylib the macOS binary
        • Directorywindows

          • greeting.dll the windows binary
      • Directorypublic

        • greeting.h the header file
  • build.gradle.kts
• settings.gradle.kts

Configuring the plugin

Configure the plugin via DSL extension, so it can find the library files.

Kotlin

build.gradle.kts

jextract.libraries {
    val greeting by registering {
        header = layout.projectDirectory.file("src/main/public/greeting.h")
        headerClassName = "Greeting"
        targetPackage = "com.example.greeting"
        useSystemLoadLibrary = true
        libraries.add("greeting")
    }
    sourceSets.named("main") {
        jextract.libraries.addLater(greeting)
    }
}

Groovy

build.gradle

jextract.libraries {
    def greeting = register('greeting') {
        header = layout.projectDirectory.file("src/main/public/greeting.h")
        headerClassName = "Greeting"
        targetPackage = "com.example.greeting"
        useSystemLoadLibrary = true
        libraries.add("greeting")
    }
    sourceSets.named("main") {
        jextract.libraries.addLater(greeting)
    }
}

Build and use

Now the project is ready for its first build.

Windows

Building the project

gradlew.bat build

Linux

Building the project

./gradlew build

This will result in the following output file structure:

• Directory.gradle

  • Directoryjextract Cache for Jextract downloads and installations

    • downloads
    • installation
• Directorylib

  • Directorybuild

    • …
    • Directorygenerated

      • Directorysources

        • Directoryjextract

          • Directorygreeting the library bindings

            • Directorycom

              • Directoryexample

                • Directorygreeting

                  • Greeting.java the bindings to import and use in Java code
    • …
  • build.gradle.kts
• settings.gradle.kts

Missing last step

This tutorial still doesn’t explain how to deploy the native binary files.