RFR: 8218685: jlink --list-plugins needs to be readable and tidy

[Ian Graves]

On Wed, 23 Sep 2020 00:37:18 GMT, Mandy Chung <mchung at openjdk.org> wrote:

>> These changes update the jlink plugin command line documentation to tidy them up into a more canonical form.
>> 
>> The output generated by jlink from this change appears as follows:
>> 
>>> build/macosx-x64/images/jdk/bin/jlink --list-plugins
>> 
>> List of available plugins:
>>   --strip-debug             Strip debug information from the output image
>>   --strip-java-debug-attributes
>>                             Strip Java debug attributes from classes in the output image
>>   --exclude-resources <pattern-list>
>>                             Specify resources to exclude.
>>                             e.g.: **.jcov,glob:**/META-INF/**
>>   --exclude-files <pattern-list>
>>                             Specify files to exclude.
>>                             e.g.: **.java,glob:/java.base/lib/client/**
>>   --exclude-jmod-section <section-name>
>>                             Specify a JMOD section to exclude.
>>                             Where <section-name> is "man" or "headers".
>>   --dedup-legal-notices [error-if-not-same-content]
>>                             De-duplicate all legal notices.
>>                             If error-if-not-same-content is specified then
>>                             it will be an error if two files of the same
>>                             filename are different.
>>   --system-modules retainModuleTarget
>>                             Fast loading of module descriptors (always enabled)
>>   --strip-native-commands   Exclude native commands (such as java/java.exe) from the image
>>   --order-resources <pattern-list>
>>                             Order resources.
>>                             e.g.: **/module-info.class, at classlist,/java.base/java/lang/**
>>   --compress <0|1|2>[:filter=<pattern-list>]
>>                             Compress all resources in the output image.
>>                             Level 0: No compression
>>                             Level 1: Constant string sharing
>>                             Level 2: ZIP.
>>                             An optional <pattern-list> filter can be
>>                             specified to list the pattern of files to be included.
>>   --vm <client|server|minimal|all>
>>                             Select the HotSpot VM in the output image.  Default is all
>>   --include-locales <langtag>[,<langtag>]*
>>                             BCP 47 language tags separated by a comma, allowing
>>                             locale matching defined in RFC 4647. e.g.: en,ja,*-IN
>>   --generate-jli-classes @filename
>>                             Specify a file listing the java.lang.invoke classes
>>                             to pre-generate. By default, this plugin may use a
>>                             builtin list of classes to pre-generate. If this plugin
>>                             runs on a different runtime version than the image being
>>                             created then code generation will be disabled by
>>                             default to guarantee correctness
>>                             add ignore-version=true to override this.
>>   --release-info <file>|add:<key1>=<value1>:<key2>=<value2>:...|del:<key list>
>>                             <file> option is to load release properties from the supplied file.
>>                             add: is to add properties to the release file.
>>                             Any number of <key>=<value> pairs can be passed.
>>                             del: is to delete the list of keys in release file.
>>   --add-options <options>   Prepend the specified <options> string, which may
>>                             include whitespace, before any other options when
>>                             invoking the virtual machine in the resulting image.
>>   --vendor-bug-url <vendor-bug-url>
>>                             Override the vendor bug URL baked into the build.
>>                             The value of the system property
>>                             "java.vendor.url.bug" will be <vendor-url-bug>.
>>   --vendor-vm-bug-url <vendor-vm-bug-url>
>>                             Override the vendor VM bug URL baked into the build.
>>                             The URL displayed in VM error logs will be <vendor-vm-bug-url>.
>>   --vendor-version <vendor-version>
>>                             Override the vendor version string baked into the build,
>>                             if any. The value of the system property
>>                             "java.vendor.version" will be <vendor-version>.
>> 
>> For options requiring a <pattern-list>, the value will be a comma separated
>> list of elements each using one the following forms:
>>   <glob-pattern>
>>   glob:<glob-pattern>
>>   regex:<regex-pattern>
>>   @<filename> where filename is the name of a file containing patterns to be
>>               used, one pattern per line
>
> The output looks much better.  Have you considered to sort them in alphabetical order of the plugin name?

Yes! I had intended to but it looks like I got hung up making sure non-documented plugins came last. Will push a change
for this.

-------------

PR: https://git.openjdk.java.net/jdk/pull/305