OpenJ9 should not include man pages for non-existent tools

[keithc-ca]

A user was concerned [1] about warnings when installing OpenJ9 on Ubuntu 18.04 via a PPA [2], for example:

** Missing executable /usr/lib/jvm/adoptopenjdk-11-jdk-openj9/bin/jinfo even though man page /usr/lib/jvm/adoptopenjdk-11-jdk-openj9/man/man1/jinfo.1.gz exists.
** This is probably a bug in AdoptOpenJDK and should be reported upstream.

OpenJ9 images should not include man pages for commands that are not provided.

[1] https://stackoverflow.com/questions/56678788/i-got-missing-executeable-files-after-installing-openjdk-openj9-in-ubuntu-18-04
[2] https://launchpad.net/~rpardini/+archive/ubuntu/adoptopenjdk

[pshipton]

@lumpfish @andrew-m-leonard can you pls take a look.

[lumpfish]

@keithc-ca - please can you confirm that for the current openj9 version the executables which are not provided (and therefore the man pages which should be removed from the openjdk-openj9 build) are jinfo and jstatd.
These are the executables in the latest openj9-openjdk11 build:

jdk-11.0.6+10$ ls -1 bin
jar
jarsigner
java
javac
javadoc
javap
jcmd
jconsole
jdb
jdeprscan
jdeps
jdmpview
jextract
jimage
jitserver
jjs
jlink
jmap
jmod
jps
jrunscript
jshell
jstack
jstat
keytool
pack200
rmic
rmid
rmiregistry
serialver
traceformat
unpack200

[pshipton]

Note OpenJ9 has an independent impl of these utilities so the docs may not match.
jcmd
jps
jstack
jstat

[lumpfish]

Note OpenJ9 has an independent impl of these utilities so the docs may not match.
jcmd
jps
jstack
jstat

Does openj9 provide its own man page (.1) files for its implementation?

[keithc-ca]

@keithc-ca - please can you confirm that for the current openj9 version the executables which are not provided (and therefore the man pages which should be removed from the openjdk-openj9 build) are jinfo and jstatd.

The answer varies by jdk version:

• 8 - jhat jinfo jstatd
• 11 - jinfo jstatd
• 14 - jfr jinfo
• 15 - jfr jinfo

[keithc-ca]

Note OpenJ9 has an independent impl of these utilities so the docs may not match.
jcmd
jps
jstack
jstat

Does openj9 provide its own man page (.1) files for its implementation?

Our implementation should match or the utility should have a different name.

[pshipton]

Does openj9 provide its own man page (.1) files for its implementation?

No. Seems a good idea though to add these in the future. In particular for the OpenJ9 specific utilities.

Our implementation should match or the utility should have a different name.

That is incompatible with the OpenJ9 strategy. The utilities were recently added to OpenJ9 in order to be somewhat compatible with the Hotspot versions, so users won't have to change in order to use OpenJ9. However the OpenJ9 versions are subsets, and don't work the same in all cases.

I'll find the man pages and read them to see if I spot any problems, and update here.

[lumpfish]

I'll find the man pages and read them to see if I spot any problems, and update here.

[pshipton]

Looking at jdk11. In summary we should remove the man pages for these utilities until such time as the OpenJ9 commands are completely compatible (probably never), or OpenJ9 creates man pages for the OpenJ9 utilities.

jcmd - refers to -f and PerfCounter.print, neither of which are currently supported by OpenJ9.

jps - contains a -V option not currently supported by OpenJ9.

jstack - refers to executable core, remote-hostname-or-IP, -F, -m options which aren't currently supported by OpenJ9.

jstat - generally not compatible, OpenJ9 only supports -class

[keithc-ca]

I had been working on this; jdk8 and jdk11 were straight-forward and I have opened pull requests:

• Omit inappropriate man pages ibmruntimes/openj9-openjdk-jdk8#382
• Omit inappropriate man pages ibmruntimes/openj9-openjdk-jdk11#271

When I got to jdknext, I discovered that things are different: the man pages are associated with their respective modules and so the filtering needs to be sprinkled through those modules, but I didn't immediately see the necessary make hooks to enable that.

[pshipton]

Seems likely jdk14 won't be fixed for the 0.20 release, moving this forward.

[keithc-ca]

With the above changes to jdk14 and jdknext, I think the only remaining unwanted man page is jfr. which should be addressed upstream by moving that man page to the jdk.jfr module.

[pshipton]

@keithc-ca can this be closed, or do you want to wait for the upstream change to occur?

[keithc-ca]

As we don't expect any more changes will be required specifically for openj9, I think it's reasonable to close this.