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

igraves · 2020-09-22T17:52:00Z

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:
  --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.
  --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.
  --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.
  --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".
  --exclude-resources <pattern-list>
                            Specify resources to exclude.
                            e.g.: **.jcov,glob:**/META-INF/**
  --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.
  --include-locales <langtag>[,<langtag>]*
                            BCP 47 language tags separated by a comma,
                            allowing
                            locale matching defined in RFC 4647.
                            e.g.: en,ja,*-IN
  --order-resources <pattern-list>
                            Order resources. 
                            e.g.: **/module-info.class,@classlist,
                            /java.base/java/lang/**
  --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.
  --strip-debug             Strip debug information from the output image
  --strip-java-debug-attributes 
                            Strip Java debug attributes from
                            classes in the output image
  --strip-native-commands   Exclude native commands (such as java/java.exe)
                            from the image.
  --system-modules retainModuleTarget
                            Fast loading of module descriptors (always enabled)
  --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-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>.
  --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>.
  --vm <client|server|minimal|all>
                            Select the HotSpot VM in the output image.
                            Default is all

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

Progress

Change must not contain extraneous whitespace
Commit message must refer to an issue
Change must be properly reviewed

Issue

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

Reviewers

Mandy Chung (@mlchung - Reviewer) ⚠️ Review applies to fe79b36
Alan Bateman (@AlanBateman - Reviewer) ⚠️ Review applies to fe79b36

Download

$ git fetch https://git.openjdk.java.net/jdk pull/305/head:pull/305
$ git checkout pull/305

bridgekeeper · 2020-09-22T17:53:28Z

👋 Welcome back igraves! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2020-09-22T17:54:19Z

@igraves The following label will be automatically applied to this pull request: core-libs.

When this pull request is ready to be reviewed, an RFR email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label (add|remove) "label" command.

mlbridge · 2020-09-22T17:57:44Z

Webrevs

mlchung · 2020-09-23T00:37:18Z

The output looks much better. Have you considered to sort them in alphabetical order of the plugin name?

igraves · 2020-09-23T01:39:35Z

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.

AlanBateman · 2020-09-23T15:04:08Z

Can we put a base abstract class in jdk.tools.jlink.internal.plugins that implements getUsage. That would avoid needing to have the same getUsage method in all the plugins.

The text in the value of some of the .usage keys looks like it will wrap significantly, can the values of release-info.usage and strip-native-debug-symbols.usage be re-formatted so that the usage is readable with a default terminal?

igraves · 2020-09-23T15:48:46Z

I'll shrink narrow those descriptions down to 80 characters.

As to the abstract class, I think it'd make sense to have that implement getUsage, getName, and getDescription -- essentially combine all of those very similar things in the same place.

igraves · 2020-09-23T17:41:49Z

Updated to consolidate documentation/resource-related methods into an abstract base class and shortened the mentioned usage bodies to 80 chars or less.

AlanBateman · 2020-09-24T09:28:31Z

AbstractPlugin might be a better name for the abstract class as it will likely define methods beyond access to name, description and usage. It also needs a copyright header.
StripNativeDebugSymbolsPlugin may have been missed in the update, it can extend the abstract class too.
AddResourcePlugin: the name field can be removed, also should be good to rename "n" to "name" so it's a bit clearer.
TaskHelper - the IDE may have messed up the imports when it was edited.

mlchung

I suggest to update the PR description with the new jlink --show-plugins output.

mlchung · 2020-09-24T23:13:33Z

src/jdk.jlink/share/classes/jdk/tools/jlink/internal/TaskHelper.java

-import java.util.List;
-import java.util.Locale;
-import java.util.Map;
+import java.util.*;


I assume this change is unintentional. Probably IDE converted the single-class imports to this.

mlchung · 2020-09-24T23:15:25Z

src/jdk.jlink/share/classes/jdk/tools/jlink/internal/plugins/DocumentedPlugin.java

+
+import jdk.tools.jlink.plugin.Plugin;
+
+public abstract class DocumentedPlugin implements Plugin {


I agree with Alan that AbstractPlugin is better.

This should also provide the default implementation of getArgumentsDescription() such that the plugins don't need to implement.

mlchung · 2020-09-24T23:16:05Z

src/jdk.jlink/share/classes/jdk/tools/jlink/internal/plugins/DocumentedPlugin.java

+
+public abstract class DocumentedPlugin implements Plugin {
+
+    private final String NAME;


Nit: use lowercase for final instance field name.

mlchung · 2020-09-24T23:22:38Z

src/jdk.jlink/share/classes/jdk/tools/jlink/internal/plugins/OrderResourcesPlugin.java

@@ -46,23 +46,19 @@
 *
 * Order Resources plugin
 */
-public final class OrderResourcesPlugin implements Plugin {
+public final class OrderResourcesPlugin extends DocumentedPlugin {
    public static final String NAME = "order-resources";


This is not related to your change. It can be private static final field. In my past observation, this static final NAME field is defined in every plugin which isn't really a need for it (at least in the current implementation). It might be good to consider the clean up to remove this static final field and instead call getName() to get the name. Just a thought.

mlchung

Looks good to me. It may be useful to have a regression test to verify the plugin order of the output if possible.

openjdk · 2020-09-28T23:06:35Z

@igraves This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for more details.

After integration, the commit message for the final commit will be:

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

Reviewed-by: mchung, alanb

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 109 new commits pushed to the master branch:

2fe0a5d: 8253476: TestUseContainerSupport.java fails on some Linux kernels w/o swap limit capabilities
fb20690: 8253637: Update EC removal
b1ce6bd: 8253548: jvmFlagAccess.cpp: clang 9.0.0 format specifier error
ff6843c: 8253714: [cgroups v2] Soft memory limit incorrectly using memory.high
d5be829: 8253770: Test tools/javac/parser/JavacParserTest.java fails on Windows after JDK-8253584
6e5d4f3: 8253607: [mlvm] meth/func/jdi/breakpointOtherStratum: un-problemlist and add randomness keyword
3ed960e: 8253640: Make MEMFLAGS an enum class
86491a5: 8253584: Redunant errors for partial member selects
ebf443a: 8253590: java/foreign tests are still failing on x86_32 after foreign-memaccess integration
431338b: 8212107: VMThread issues and cleanup
... and 99 more: https://git.openjdk.java.net/jdk/compare/2e30ff61b0394793655d6c6a593a5de8eb9c07b9...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

As you do not have Committer status in this project an existing Committer must agree to sponsor your change. Possible candidates are the reviewers of this PR (@mlchung, @AlanBateman) but any other Committer may sponsor as well.

➡️ To flag this PR as ready for integration with the above commit message, type /integrate in a new comment. (Afterwards, your sponsor types /sponsor in a new comment to perform the integration).

AlanBateman · 2020-09-29T09:57:27Z

The new AbstractPlugin and each of the implementations extending it look good. The new usages messages look good too. A few minor formatting nits in a few places but otherwise I think good to go.
/approve

openjdk · 2020-09-29T09:58:13Z

@AlanBateman Unknown command approve - for a list of valid commands use /help.

igraves · 2020-09-29T20:47:56Z

Updated JLinkTest to assert alphabetical order. With that I will /integrate .

igraves · 2020-09-29T20:52:27Z

/integrate

openjdk · 2020-09-29T20:54:15Z

@igraves
Your change (at version 5372b15) is now ready to be sponsored by a Committer.

mlchung · 2020-09-29T21:15:13Z

/sponsor

openjdk · 2020-09-29T21:16:47Z

@mlchung @igraves Since your change was applied there have been 109 commits pushed to the master branch:

2fe0a5d: 8253476: TestUseContainerSupport.java fails on some Linux kernels w/o swap limit capabilities
fb20690: 8253637: Update EC removal
b1ce6bd: 8253548: jvmFlagAccess.cpp: clang 9.0.0 format specifier error
ff6843c: 8253714: [cgroups v2] Soft memory limit incorrectly using memory.high
d5be829: 8253770: Test tools/javac/parser/JavacParserTest.java fails on Windows after JDK-8253584
6e5d4f3: 8253607: [mlvm] meth/func/jdi/breakpointOtherStratum: un-problemlist and add randomness keyword
3ed960e: 8253640: Make MEMFLAGS an enum class
86491a5: 8253584: Redunant errors for partial member selects
ebf443a: 8253590: java/foreign tests are still failing on x86_32 after foreign-memaccess integration
431338b: 8212107: VMThread issues and cleanup
... and 99 more: https://git.openjdk.java.net/jdk/compare/2e30ff61b0394793655d6c6a593a5de8eb9c07b9...master

Your commit was automatically rebased without conflicts.

Pushed as commit 8df3e72.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

Tidying up plugins

4add876

openjdk bot added the rfr Pull request is ready for review label Sep 22, 2020

openjdk bot added the core-libs core-libs-dev@openjdk.org label Sep 22, 2020

Fixing up ordering

a94a16b

Consolidate documentation methods to abstract base class DocumentPlugin

4deaa4b

mlchung reviewed Sep 24, 2020

View reviewed changes

igraves added 2 commits September 28, 2020 08:38

Consolidating to AbstractPlugin

bd274ac

Additional usage narrowing

fe79b36

mlchung approved these changes Sep 28, 2020

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Sep 28, 2020

AlanBateman approved these changes Sep 29, 2020

View reviewed changes

Updating JLinkTest to assert alphabetical order on --list-plugins

5372b15

openjdk bot added the sponsor Pull request is ready to be sponsored label Sep 29, 2020

openjdk bot closed this Sep 29, 2020

openjdk bot added integrated Pull request has been integrated and removed sponsor Pull request is ready to be sponsored ready Pull request is ready to be integrated rfr Pull request is ready for review labels Sep 29, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

igraves commented Sep 22, 2020 •

edited by openjdk bot

Loading

bridgekeeper bot commented Sep 22, 2020

openjdk bot commented Sep 22, 2020

mlbridge bot commented Sep 22, 2020 •

edited

Loading

mlchung commented Sep 23, 2020 •

edited

Loading

igraves commented Sep 23, 2020

AlanBateman commented Sep 23, 2020

igraves commented Sep 23, 2020

igraves commented Sep 23, 2020

AlanBateman commented Sep 24, 2020

mlchung left a comment

mlchung Sep 24, 2020

mlchung Sep 24, 2020

mlchung Sep 24, 2020

mlchung Sep 24, 2020

mlchung left a comment

openjdk bot commented Sep 28, 2020 •

edited

Loading

AlanBateman commented Sep 29, 2020

openjdk bot commented Sep 29, 2020

igraves commented Sep 29, 2020

igraves commented Sep 29, 2020

openjdk bot commented Sep 29, 2020

mlchung commented Sep 29, 2020

openjdk bot commented Sep 29, 2020


		import jdk.tools.jlink.plugin.Plugin;

		public abstract class DocumentedPlugin implements Plugin {


		public abstract class DocumentedPlugin implements Plugin {

		private final String NAME;

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

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

Conversation

igraves commented Sep 22, 2020 • edited by openjdk bot Loading

Progress

Issue

Reviewers

Download

bridgekeeper bot commented Sep 22, 2020

openjdk bot commented Sep 22, 2020

mlbridge bot commented Sep 22, 2020 • edited Loading

Webrevs

mlchung commented Sep 23, 2020 • edited Loading

igraves commented Sep 23, 2020

AlanBateman commented Sep 23, 2020

igraves commented Sep 23, 2020

igraves commented Sep 23, 2020

AlanBateman commented Sep 24, 2020

mlchung left a comment

Choose a reason for hiding this comment

mlchung Sep 24, 2020

Choose a reason for hiding this comment

mlchung Sep 24, 2020

Choose a reason for hiding this comment

mlchung Sep 24, 2020

Choose a reason for hiding this comment

mlchung Sep 24, 2020

Choose a reason for hiding this comment

mlchung left a comment

Choose a reason for hiding this comment

openjdk bot commented Sep 28, 2020 • edited Loading

AlanBateman commented Sep 29, 2020

openjdk bot commented Sep 29, 2020

igraves commented Sep 29, 2020

igraves commented Sep 29, 2020

openjdk bot commented Sep 29, 2020

mlchung commented Sep 29, 2020

openjdk bot commented Sep 29, 2020

igraves commented Sep 22, 2020 •

edited by openjdk bot

Loading

mlbridge bot commented Sep 22, 2020 •

edited

Loading

mlchung commented Sep 23, 2020 •

edited

Loading

openjdk bot commented Sep 28, 2020 •

edited

Loading