7903121: initial jextract tool code, tests and samples

Reviewed-by: mcimadamore, jvernee

Author: sundararajana

.gitignore

@@ -0,0 +1,2 @@
+.gradle
+**/build/

Makefile

@@ -0,0 +1,52 @@
+default: all
+
+.NOTPARALLEL:
+
+include make/Common.gmk
+
+JEXTRACT_NATIVE_TEST_DIR ?= $(JEXTRACT_IMAGE_NATIVE_TEST_DIR)
+JEXTRACT_TEST_JDK ?= $(JEXTRACT_IMAGE_TEST_JDK_DIR)
+JEXTRACT_DIR ?= $(JEXTRACT_IMAGE_DIR)
+
+TEST ?= test
+
+all: bundles
+
+TARGETS += all
+
+
+image images test-image bundles:
+	$(MAKE) -f make/Build.gmk $@
+
+TARGETS += image images test-image bundles
+
+
+verify: test test-integration
+
+TARGETS += verify
+
+
+test-prebuilt:
+	@( \
+	    $(MAKE) --no-print-directory -r -R -I make/common/ -f make/RunTestsPrebuilt.gmk \
+	        test-prebuilt $(MAKE_ARGS) \
+	        JEXTRACT_TEST_JDK="$(JEXTRACT_TEST_JDK)" \
+	        JEXTRACT_NATIVE_TEST_DIR="$(JEXTRACT_NATIVE_TEST_DIR)" \
+	        JEXTRACT_DIR="$(JEXTRACT_DIR)" \
+	        TEST="$(TEST)" \
+	)
+
+TARGETS += test-prebuilt
+
+
+test: image test-image test-prebuilt
+
+TARGETS += test
+
+clean:
+	rm -rf $(BUILD_DIR)
+
+TARGETS += clean
+
+
+.PHONY: default $(TARGETS)

README.md

@@ -1,9 +1,7 @@
-## Proposal: jextract
+## jextract
 
 `jextract` is a tool that mechanically generates Java bindings from a native library headers. We would like to include this tool, originally developed in the context of [Project Panama](https://openjdk.java.net/projects/panama/) (and available in the Project Panama [Early Access binaries](https://jdk.java.net/panama/)) in the set of tools that are part of the code-tools project.
 
-### Rationale
-
 The Java SE 18 API defines an [incubating API](https://openjdk.java.net/jeps/419) to:
 
 * manipulate foreign memory, that is memory which resides *outside* the Java heap; and
@@ -155,3 +153,40 @@ It is easy to see how this mechanism allows developers to look into the set of s
 
 For more examples on how to use the `jextract` tool with real-world libraries, please refer to this [document](https://github.com/openjdk/panama-foreign/blob/d8c0fe5918cb1c6c744eb26797ea4fa04142c237/doc/panama_jextract.md).
 
+
+### Building jextract tool
+
+jextract depends on clang+LLVM binaries. Please download and install clang+LLVM binaries for your platform.
+You can find the prebuilt binaries from [https://releases.llvm.org/download.html](https://releases.llvm.org/download.html). The path of the clang+LLVM installation is provided using the `libclang_home` variable.
+
+Gradle tool needs jdk 17 or below to run. JAVA_HOME should be set to
+jdk 17 or below. Or PATH should contain java from jdk 17 or below. jdk18 build is
+needed to build jextract which is passed from command with -Pjdk18_home option.
+
+You can download jdk18 early access build from [https://jdk.java.net/18/](https://jdk.java.net/18/)
+
+For Windows, please use gradlew.bat.
+
+```sh
+
+$ sh ./gradlew -Pjdk18_home=<jdk18_home_dir> -Plibclang_home=<libclang_dir> clean verify
+
+```
+
+### Testing jextract tool
+
+jextract tests are written for jtreg test framework. Please download and install jtreg binaries.
+The path of the jtreg installation is provided using the `jtreg_home` variable.
+
+For Windows, please use gradlew.bat.
+
+```sh
+
+$ sh ./gradlew -Pjdk18_home=<jdk18_home_dir> -Plibclang_home=<libclang_dir> -Pjtreg_home=<jtreg_dir> clean jtreg
+
+```
+
+### jextract samples
+
+jextract samples can be found "samples" top-level directory. Building/running particular sample may require
+specific third-party software installation.

build.gradle

@@ -0,0 +1,209 @@
+import org.apache.tools.ant.taskdefs.condition.Os
+
+plugins {
+    id "java"
+    // moditect for module-info.class injection and jlink
+    id "org.moditect.gradleplugin" version "1.0.0-rc3"
+    // jpackage plugin for packging jextract native app
+    id "org.panteleyev.jpackageplugin" version "1.3.1"
+}
+
+version = '1.0'
+
+def libclang_home = project.property("libclang_home")
+def clang_version = new File("${libclang_home}/lib/clang/").list()[0]
+
+def jextract_path
+if (Os.isFamily(Os.FAMILY_WINDOWS)) {
+    jextract_path = "$buildDir/jextract/jextract.exe"
+} else if (Os.isFamily(Os.FAMILY_MAC)) {
+    jextract_path = "$buildDir/jextract.app/Contents/MacOS/jextract"
+} else {
+    jextract_path = "$buildDir/jextract/bin/jextract"
+}
+
+def clang_include_dir = "${libclang_home}/lib/clang/${clang_version}/include"
+def os_lib_dir = Os.isFamily(Os.FAMILY_WINDOWS)? "bin" : "lib"
+def libclang_dir = "${libclang_home}/${os_lib_dir}"
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    implementation "net.sf.jopt-simple:jopt-simple:5.0.4"
+}
+
+compileJava {
+    options.compilerArgs.addAll(['--release', '18'])
+    options.compilerArgs << "--add-modules=jdk.incubator.foreign"
+    options.compilerArgs << "-Xlint:all"
+    options.fork = true
+    options.forkOptions.executable = "${jdk18_home}/bin/javac"
+}
+
+jar {
+    archiveBaseName = 'jextract'
+    archiveVersion = project.version
+}
+
+moditect {
+    // moditect uses java.home to find JDK tools
+    System.setProperty("java.home", "$jdk18_home")
+
+    // inject module-info.class for org.openjdk.jextract module
+    addMainModuleInfo {
+        dependsOn build
+
+        jvmVersion = '18'
+        version = project.version
+        module {
+            moduleInfoSource = '''
+                module org.openjdk.jextract {
+                    requires transitive java.compiler;
+                    requires transitive jdk.incubator.foreign;
+                    requires jopt.simple;
+                    requires java.prefs;
+                    exports org.openjdk.jextract;
+
+                    provides java.util.spi.ToolProvider with
+                       org.openjdk.jextract.JextractTool.JextractToolProvider;
+                }
+                '''
+        }
+    }
+
+    // inject module-info.class for jopt.simple module
+    addDependenciesModuleInfo {
+        jvmVersion = '18'
+        outputDirectory = file("$buildDir/modules")
+        modules {
+            module {
+                artifact 'net.sf.jopt-simple:jopt-simple:5.0.4'
+                moduleInfoSource = '''
+                    module jopt.simple {
+                        exports joptsimple;
+                        exports joptsimple.util;
+                    }
+                '''
+            }
+        }
+    }
+
+    // jlink a JDK image with org.openjdk.jextract & dependent modules only
+    createRuntimeImage {
+        onlyIf { !new File("$buildDir/jextract-jdk-image").exists() }
+        outputDirectory = file("$buildDir/jextract-jdk-image")
+        modulePath = [file("$buildDir/modules")]
+        modules = ['org.openjdk.jextract', 'jdk.compiler']
+    }
+}
+
+task copyLibClang(type: Copy) {
+    dependsOn createRuntimeImage
+
+    into("$buildDir")
+
+    from("${libclang_dir}") {
+        include("*clang.*")
+        include("libLLVM.*")
+        into("jextract-jdk-image/${os_lib_dir}")
+    }
+
+    from("$clang_include_dir") {
+        include("*.h")
+        into("jextract-jdk-image/conf/jextract")
+    }
+}
+
+// jpackage jextract jdk image as a platform dependent native app
+jpackage {
+    dependsOn copyLibClang
+    onlyIf { !new File(jextract_path).exists() }
+
+    appName = "jextract"
+    runtimeImage = "$buildDir/jextract-jdk-image/"
+    module = "org.openjdk.jextract/org.openjdk.jextract.JextractTool"
+    type = "APP_IMAGE"
+    appVersion = "1.0"
+    destination =  "$buildDir"
+    javaOptions = [
+        "--add-modules=jdk.incubator.foreign",
+        "--enable-native-access=org.openjdk.jextract"
+    ]
+    winConsole = true
+}
+
+// very simple integration test for generated jpackage'd jextract
+task verify(type: Exec) {
+    dependsOn jpackage
+
+    executable = "${jextract_path}"
+    args = [ "test.h", "-d", "$buildDir/integration_test" ]
+}
+
+// jlink a JDK image with org.openjdk.jextract for testing
+task createRuntimeImageForTest(type: org.moditect.gradleplugin.image.CreateRuntimeImageTask) {
+    dependsOn verify
+
+    onlyIf { !new File("$buildDir/jextract-jdk-test-image").exists() }
+    outputDirectory = file("$buildDir/jextract-jdk-test-image")
+    modulePath = [file("$buildDir/modules"),file("$jdk18_home/jmods")]
+    modules = ['ALL-MODULE-PATH']
+}
+
+task prepareTestJDK(type: Copy) {
+    dependsOn createRuntimeImageForTest
+
+    into("$buildDir")
+
+    from("${libclang_dir}") {
+        include("*clang.*")
+        include("libLLVM.*")
+        into("jextract-jdk-test-image/${os_lib_dir}")
+    }
+
+    from("$clang_include_dir") {
+        include("*.h")
+        into("jextract-jdk-test-image/conf/jextract")
+    }
+}
+
+task cmakeConfigure(type: Exec) {
+    executable = "cmake"
+    args = [
+        "-B", "$buildDir/testlib-build",
+        "-S", "$projectDir/test/test-support",
+        "-DTEST_SOURCE_ROOT:FILEPATH=$projectDir/test",
+        "-DCMAKE_BUILD_TYPE:STRING=Release",
+        "-DCMAKE_INSTALL_PREFIX:FILEPATH=$buildDir/testlib-install"
+    ]
+}
+
+task cmakeBuild(type: Exec) {
+    dependsOn cmakeConfigure
+
+    executable = "cmake"
+    args = [
+        "--build", "$buildDir/testlib-build",
+        "--config", "Release",
+        "--target", "install"
+    ]
+}
+
+// run jtreg tests. Note: needs jtreg_cmd variable set to point to the jtreg
+task jtreg(type: JavaExec) {
+    dependsOn prepareTestJDK,cmakeBuild
+
+    workingDir = "$buildDir"
+
+    classpath = files(findProperty("jtreg_home") + "/lib/jtreg.jar")
+
+    args = [
+            "-jdk", "$buildDir/jextract-jdk-test-image",
+            "-nativepath:$buildDir/testlib-install/${os_lib_dir}",
+            "-javaoption:--enable-native-access=org.openjdk.jextract,ALL-UNNAMED",
+            "-avm", "-conc:auto", "-verbose:summary",
+            "../test"
+    ]
+}

gradle/wrapper/gradle-wrapper.jar

@@ -0,0 +1,5 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.3.3-bin.zip
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists