Skip to content

Latest commit

 

History

History
69 lines (47 loc) · 3.95 KB

README.md

File metadata and controls

69 lines (47 loc) · 3.95 KB
Raw

Jextract

jextract is a tool which mechanically generates Java bindings from native library headers. This tools leverages the clang C API in order to parse the headers associated with a given native library, and the generated Java bindings build upon the Foreign Function & Memory API. The jextract tool was originally developed in the context of Project Panama (and then made available in the Project Panama Early Access binaries).

💡 For instruction on how to use the jextract tool, please refer to the guide here.

Getting jextract

Pre-built binaries for jextract are periodically released here. These binaries are built from the master branch of this repo, and target the foreign memory access and function API in the latest mainline JDK (for which binaries can be found here).

Alternatively, to build jextract from the latest sources (which include all the latest updates and fixes) please refer to the building section below.

Building

jextract depends on the C libclang API. To build the jextract sources, the easiest option is to download LLVM binaries for your platform, which can be found here (version 13.0.0 is recommended). Both the jextract tool and the bindings it generates depend heavily on the Foreign Function & Memory API, so a suitable jdk 22 distribution is also required.

Building older jextract versions

The master branch always tracks the latest version of the JDK. If you wish to build an older version of jextract, which targets an earlier version of the JDK you can do so by checking out the appropriate branch. For example, to build a jextract tool which works against JDK 21:

git checkout jdk21

Over time, new branches will be added, each targeting a specific JDK version.

jextract can be built using gradle, as follows (on Windows, gradlew.bat should be used instead).

We currently use gradle version 7.3.3 which is fetched automatically by the gradle wrapper. This version of gradle requires Java 17 on the PATH/JAVA_HOME to run. Note that the JDK we use to build (the toolchain JDK) is passed in separately as a property.

$ sh ./gradlew -Pjdk22_home=<jdk22_home_dir> -Pllvm_home=<libclang_dir> clean verify
Using a local installation of LLVM

While the recommended way is to use a release from the LLVM project, extract it then make llvm_home point to this directory, it may be possible to use a local installation instead.

E.g. on macOs the llvm_home can also be set as one of these locations :

  • /Library/Developer/CommandLineTools/usr/ if using Command Line Tools
  • /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/ if using XCode
  • $(brew --prefix llvm) if using the LLVM install from Homebrew

After building, there should be a new jextract folder under build. To run the jextract tool, simply run the jextract command in the bin folder:

$ build/jextract/bin/jextract
Expected a header file

Testing

The repository also contains a comprehensive set of tests, written using the jtreg test framework, which can be run as follows (again, on Windows, gradlew.bat should be used instead):

$ sh ./gradlew -Pjdk22_home=<jdk22_home_dir> -Pllvm_home=<libclang_dir> -Pjtreg_home=<jtreg_home> jtreg

Note: running jtreg task requires cmake to be available on the PATH.