Building and running the bindings generator

Java-GI publishes pre-built bindings for a number of libraries, including GLib, Gtk4, LibAdwaita, GtkSourceview, WebkitGtk and GStreamer. The bindings should work on Linux, Windows and MacOS. To generate and build the bindings for these libraries, follow these steps:

  • Clone the Java-GI project (jwharm/java-gi) and the GIR input files (gircore/gir-files) from GitHub
  • Run the Gradle build, either using an IDE, or navigate into the java-gi folder and run ./gradlew build (on Windows: gradlew build).
git clone
git clone
cd java-gi
./gradlew build

The gir-files repository contains regularly updated gir files that Java-GI generates bindings from. If you clone this repository in another location, update the girFilesLocation path in accordingly.

Generating bindings for other libraries

First of all, install the GObject-introspection (gir) files of the library you want to generate bindings for. To do this, you need to download the release package (usually a .tar.gz file) of the library from their website and generate the introspection files using the included build script. Usually there is a build option to generate the gir file.

Alternatively, in most Linux distributions, the gir files are usually installed with a development package, postfixed with "-dev" or "-devel". For example, the Gtk gir files on Fedora are installed by the "gtk4-devel" package. All installed gir files can normally be found in /usr/share/gir-1.0. However, this is not the preferred method to obtain a gir file. Distributions often patch libraries, impacting the gir file too. It's better to generate the gir file from the upstream release package. Be sure to download the release package for an actual release, and not a random snapshot.

Once the gir file is available, copy it into the gir-files folder under the correct platform subfolder (linux, windows or macos).

Now you can add a Java-GI module for the library. Create a folder under /modules, add it to settings.gradle, and create a build.gradle file:

plugins {
    id 'java-gi.library-conventions'

dependencies {
    // Add dependencies on other modules here.
    // The dependencies can be found in the GIR file (search for <include> tags).
    api project(':gio')

tasks.named('generateSources') {
    girFile = 'My-Gir-File-0.0.gir'

The generateSources task accepts an optional urlPrefix argument to set an URL that is prefixed to image links.

When neccessary, you can patch the introspection data. To do this, create a patch class implementing PatchSet in the folder buildSrc/main/java/io/github/jwharm/javagi/patches and add a patch = new ...Patch() argument to the generateSources task. (See the Gtk buildfile for an example).

If you encounter any problems or errors, check the generated Java source code in the java-gi/modules/{modulename}/build/generated/sources/java-gi directory for issues.