Panama: name conflict with IBM jextract and OpenJDK jextract

[tajila]

As part of project Panama, Oracle will be releasing an application called jextract

jextract is a simple - but convenient - tool which generates a Java API from one or more native C headers. The tool can be obtained by building the foreign-jextract branch of Panama foreign repository.

Interacting with the jextract tool usually involves two steps:

    Use the jextract tool to generate a java interface for some C header files
    Write a Java program which invokes the wrapper API points generated by jextract

The jextract tool provides some basic options in order to control how the extraction process works; these are listed below:

    -C <String> - specify arguments to be passed to the underlying Clang parser
    -I <String> - specify include files path
    -l <String> - specify a library (name or full absolute path) which should be linked when the generated API is loaded
    -d <String> - specify where to place generated files
    -t <String> specify the target package for the generated classes
    --filter <String> - simple string-based filtering mechanism; only symbols from headers whose absolute path contains the specified string will be included in the generated API
    --source - generate java sources instead of classfiles

The remainder of this documents shows some basic usage examples of the jextract tool.

IBM JDKs have an application called jextract:

Use the jextract utility to process system dumps.

For an analysis of core dumps from Linux and AIX® platforms, copies of executable files and libraries are required along with the system dump. You must run the jextract utility provided in the SDK to collect these files. You must run jextract using the same SDK level, on the same system that produced the system dump. The jextract utility compresses the dump, executable files, and libraries into a single .zip file for use in subsequent problem diagnosis.

When a core file is generated, run the jextract utility against the core file with the following syntax:

jextract <core file name> [<zip_file>]
Copy code

to generate a compressed file in the current directory, containing the dump and the required executable file and libraries. The jextract utility is in the directory sdk/jre/bin. If you run jextract on a JVM level that is different from the one on which the dump was produced you see the following messages:

J9RAS.buildID is incorrect (found e8801ed67d21c6be, expecting eb4173107d21c673). 
This version of jextract is incompatible with this dump. 
Failure detected during jextract, see previous message(s).

[tajila]

Openjdk jextract may be released in the JDK17 timeframe

[keithc-ca]

What do people think about adding j9extract (to all versions) now, so we have time to get people accustomed to using it before the new jextract show up?

For 11+, it's as simple as adding to the launcher makefile for openj9.dtfj:

$(eval $(call SetupBuildLauncher, j9extract, \
    MAIN_CLASS := com.ibm.jvm.j9.dump.extract.Main, \
    CFLAGS := -DEXPAND_CLASSPATH_WILDCARDS, \
))

[pshipton]

That is a good idea, although not sure about the name. We can raise a question about the name in the committers slack channel and see if anyone has input. I don't think we can resolve this until after the current vacation/holiday period.

[manqingl]

The jextract tool is an extremely popular tool in Service world. Almost all system core files needs to be jextracted (zOS system core files are the only exception). So I prefer to keep the name consistent if possible.

Would it be possible to automatically grab the native libraries when generating the system core files? If that is the case, then the dependency on jextract would be alleviated. That would help service scenarios.

I will forward this link to service community for them to comment.

[DanHeidinga]

+1 to renaming our tool, if only due to popularity the new panama tool will have.

I'd avoid very similar names - jextract & j9extract are easily confused. Better to pick something that won't be easily typo'd or misunderstood by both existing service users and new panama users. Maybe a longer more explicit name like servicecollector would be better?

[paulcheeseman]

Some GDB implementations have a function called packcore which packages up a core file with all the files required to analyse it - i.e. exactly what jextract does.

So maybe something like jpackcore or j9packcore would be appropriate?

[keithc-ca]

If everyone is happy with using jpackcore, I'll create some pull requests.

[manqingl]

@keithc-ca : are you trying to rename the utility in IBM Java too? I do not have problem on renaming it in Java 11 or above, but we have used it in IBM Java for so long. Maybe just an alias in IBM Java?

[keithc-ca]

The plan is that jpackcore will be equivalent to (i.e. an alias for) jextract in all versions of Java where openjdk does not provide a different tool named jextract. Then you will be able to use jpackcore in any (recent) build independent of whether jextract means the same thing.

[manqingl]

Sounds like a good plan @keithc-ca