diff --git a/README.md b/README.md index b35904f2..4f7d48df 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Java-GI -**Java-GI** is a tool for generating GObject-Introspection bindings for Java. The generated bindings use the new [Foreign Function & Memory API](https://openjdk.org/projects/panama/) (JEP 454) to directly access native resources from inside the JVM, with wrapper classes based on GObject-Introspection to offer an elegant API. Java-GI version 0.11 generates bindings to develop Java applications for libraries, based of the versions in GNOME Platform 47: +**Java-GI** is a tool for generating GObject-Introspection bindings for Java. The generated bindings use the [Foreign Function & Memory API](https://openjdk.org/projects/panama/) (JEP 454) to access native resources from Java, with wrapper classes based on GObject-Introspection to offer an elegant API. Java-GI version 0.11.* generates bindings to develop Java applications for libraries, based of the versions in GNOME Platform 47: | Library | Java-GI 0.11.x | Java-GI 0.10.x | Java-GI 0.8.x and 0.9.x | Java-GI 0.7.x | |---------------|----------------|----------------|-------------------------|---------------| @@ -12,7 +12,7 @@ | GtkSourceview | 5.14 | 5.12 | 5.10 | 5.9 | | WebkitGtk | 2.46 | 2.44 | 2.42 | 2.41 | -Please note that Java-GI is still under active development. The bindings should not be used in a production environment yet, and the API is subject to unannounced changes. However, feel free to try out the latest release; feedback is welcome. +Please note that Java-GI is still under active development, and the API is subject to unannounced changes. Feedback is welcome! [For more information, visit the Java-GI website.](https://jwharm.github.io/java-gi/) @@ -67,7 +67,7 @@ repositories { } dependencies { - implementation 'io.github.jwharm.javagi:gtk:0.11.0' + implementation 'io.github.jwharm.javagi:gtk:0.11.1' } ``` @@ -275,15 +275,15 @@ try { ### Portability -The Java-GI bindings are cross-platform: You can use the same jar on all supported operating systems (Linux, Windows and MacOS) provided that the native libraries are installed. Platform-specific types and methods (like `Gtk.PrintUnixDialog`) check the operating system at runtime and throw an `UnsupportedPlatformException` when necessary. +The published bindings are cross-platform: You can use the same jar on all supported operating systems (64-bit Linux, Windows and MacOS) provided that the native libraries are installed. Platform-specific types and methods (like `Gtk.PrintUnixDialog`) check the operating system at runtime and throw an `UnsupportedPlatformException` when necessary. -## Building and Contributing +## Generate bindings -To build Java-GI for yourself, make changes, or use Java-GI to generate bindings for other (GObject-Introspection based) libraries, follow the instructions [here](https://jwharm.github.io/java-gi/generate/). +Java-GI offers a command-line utility to generate bindings for any library that supports GObject-Introspection. It is documented [here](https://jwharm.github.io/java-gi/generate/). ## Known issues -The bindings are still under active development and have not been thoroughly tested yet. The most notable issues and missing features are currently: +Java-GI is still under active development. The most notable issues and missing features are currently: - Java does not distinguish between signed and unsigned data types. Be extra careful when native code returns, for example, a `guint`. - Java-GI makes heavy use of [Cleaners](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/ref/Cleaner.html) to free memory or decrease an object's refcount. Cleaners are triggered during garbage collection of a Java instance. However, Java doesn't guarantee when, and if, the GC will run, and what it will clean, leading to memory leaks. diff --git a/docs/generate.md b/docs/generate.md index 2abe5f2c..89606f30 100644 --- a/docs/generate.md +++ b/docs/generate.md @@ -1,4 +1,4 @@ -# Building and running the bindings generator +# Building the included bindings 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: @@ -25,33 +25,10 @@ The repository contains a Git submodule under `ext/gir-files` that originates fr ## 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. +First of all, find the GObject-introspection (gir) file of the library you want to generate bindings for. To do this, you can 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 `ext/gir-files` repository under the correct platform subfolder (linux, windows or macos). +Once the gir file is available, use the `java-gi` command-line utility to generate the Java bindings. -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: - -```groovy -plugins { - id 'java-gi.library-conventions' -} - -dependencies { - // Add dependencies on other modules here. - // The dependencies can be found in the GIR file (search for tags). - api project(':gio') - api project(':gtk') -} - -generateSources.configure { - namespace = 'Insert-Namespace-Here' -} -``` - -Configure the Java package name, description and an URL prefix for image links in the `ModuleInfo` class in the package `io.github.jwharm.javagi.configuration` in the `BuildSrc/src/main/java` directory. - -When necessary, you can patch the introspection data. To do this, create a patch class implementing `Patch` in the folder `buildSrc/main/java/io/github/jwharm/javagi/patches` and add it to the list in the `Patches` class. - -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. Remember that other libraries are not guaranteed to work flawlessly as soon as they are added. If you have patched the introspection data and are still getting errors, Java GI may have a bug. In that case, please [log an issue in the GitHub repo](https://github.com/jwharm/java-gi/issues). +If you encounter any problems or errors, in most cases it will be easy to work around by updating the generated Java source code. If you think the problem is caused by a bug in Java-GI, please [log an issue in the GitHub repo](https://github.com/jwharm/java-gi/issues). diff --git a/docs/getting-started/getting_started_01.md b/docs/getting-started/getting_started_01.md index 4fe00cfb..cdfd380f 100644 --- a/docs/getting-started/getting_started_01.md +++ b/docs/getting-started/getting_started_01.md @@ -28,7 +28,7 @@ repositories { } dependencies { - implementation 'io.github.jwharm.javagi:gtk:0.11.0' + implementation 'io.github.jwharm.javagi:gtk:0.11.1' } java { diff --git a/docs/usage.md b/docs/usage.md index 6f9dd804..c0b5f4c5 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -20,7 +20,7 @@ Next, add the dependencies. For example, to add Gtk as a dependency: io.github.jwharm.javagi gtk - 0.11.0 + 0.11.1 ``` @@ -32,7 +32,7 @@ Next, add the dependencies. For example, to add Gtk as a dependency: } dependencies { - implementation 'io.github.jwharm.javagi:gtk:0.11.0' + implementation 'io.github.jwharm.javagi:gtk:0.11.1' } ``` @@ -44,20 +44,20 @@ Next, add the dependencies. For example, to add Gtk as a dependency: } dependencies { - implementation("io.github.jwharm.javagi:gtk:0.11.0") + implementation("io.github.jwharm.javagi:gtk:0.11.1") } ``` === "Scala SBT" ```scala - libraryDependencies += "io.github.jwharm.javagi" % "gtk" % "0.11.0" + libraryDependencies += "io.github.jwharm.javagi" % "gtk" % "0.11.1" ``` === "Leiningen" ```clojure - [io.github.jwharm.javagi/gtk "0.11.0"] + [io.github.jwharm.javagi/gtk "0.11.1"] ``` === "bld" @@ -67,7 +67,7 @@ Next, add the dependencies. For example, to add Gtk as a dependency: scope(main) .include(dependency("io.github.jwharm.javagi", "gtk", - version(0,11,0))); + version(0,11,1))); ``` This will add the Gtk bindings to the application's compile and runtime classpath. Other libraries, like `webkit`, `gst`, `adw` and `gtksourceview` can be included likewise. The complete list of available libraries is available [here](https://search.maven.org/search?q=io.github.jwharm.javagi).