From c4ed5aca81a019ad504de0ecac93f81c89bbfeba Mon Sep 17 00:00:00 2001 From: Martin Desruisseaux Date: Tue, 8 Sep 2026 17:32:36 +0900 Subject: [PATCH 1/2] Split paragraphs that are long lines into multiple lines. This commit does not change any sentence, it only add line separators. The intend is to make easier to see the diffs in next commits. --- src/site/markdown/examples/attached-jar.md.vm | 9 +++-- .../markdown/examples/create-test-jar.md.vm | 27 +++++++++---- .../markdown/examples/include-exclude.md.vm | 5 ++- .../examples/manifest-customization.md.vm | 11 +++-- src/site/markdown/index.md | 22 +++++++--- src/site/markdown/usage.md.vm | 40 ++++++++++++++----- 6 files changed, 82 insertions(+), 32 deletions(-) diff --git a/src/site/markdown/examples/attached-jar.md.vm b/src/site/markdown/examples/attached-jar.md.vm index 8558777..0897992 100644 --- a/src/site/markdown/examples/attached-jar.md.vm +++ b/src/site/markdown/examples/attached-jar.md.vm @@ -1,6 +1,6 @@ --- title: How to create an additional attached jar artifact from the project -author: +author: - Karl Heinz Marbaise date: 2014-06-16 --- @@ -26,9 +26,12 @@ under the License. # How to Create an Additional Attached JAR Artifact -Add ``/`` or ``/`` in your `pom.xml`. Add a `classifier` as well. +Add ``/`` or ``/`` in your `pom.xml`. +Add a `classifier` as well. -**Note:** Define the JAR Plugin in a new execution. Otherwise, it replaces the default use of the JAR Plugin. It does not add a second artifact. The `classifier` is also required to create more than one artifact. +**Note:** Define the JAR Plugin in a new execution. +Otherwise, it replaces the default use of the JAR Plugin. It does not add a second artifact. +The `classifier` is also required to create more than one artifact. ```unknown diff --git a/src/site/markdown/examples/create-test-jar.md.vm b/src/site/markdown/examples/create-test-jar.md.vm index 8936e8e..f123e9a 100644 --- a/src/site/markdown/examples/create-test-jar.md.vm +++ b/src/site/markdown/examples/create-test-jar.md.vm @@ -1,6 +1,6 @@ --- title: How to create a jar with test classes -author: +author: - Karl Heinz Marbaise date: 2014-06-16 --- @@ -26,9 +26,11 @@ under the License. # How to Create a JAR With Test Classes -When you create a JAR with test classes, you probably want to reuse those classes. There are two ways to do this: +When you create a JAR with test classes, you probably want to reuse those classes. +There are two ways to do this: -- Create an attached JAR with the test classes from the current project. This JAR does not include the transitive `test`-scoped dependencies. +- Create an attached JAR with the test classes from the current project. + This JAR does not include the transitive `test`-scoped dependencies. - Create a separate project with the test classes. The easy way @@ -80,11 +82,18 @@ To reuse this artifact in another project, declare the dependency with `type` se ``` -This configuration generates two JAR files. The first contains the classes from `src/main/java`. The second contains the classes from `src/test/java`. The JAR names follow the schema `artifactId-version.jar` and `artifactId-version-classifier.jar`. +This configuration generates two JAR files. +The first contains the classes from `src/main/java`. +The second contains the classes from `src/test/java`. +The JAR names follow the schema `artifactId-version.jar` and `artifactId-version-classifier.jar`. -The values of `artifactId` and `version` come from your `pom.xml` file. The default `classifier` is `tests`. You can change it in the [jar goal configuration](../test-jar-mojo.html). +The values of `artifactId` and `version` come from your `pom.xml` file. +The default `classifier` is `tests`. +You can change it in the [jar goal configuration](../test-jar-mojo.html). -**Note:** This solution does not include the transitive `test`-scoped dependencies automatically. Maven resolves only the `compile`-time dependencies. Add all other required `test`-scoped dependencies by hand. +**Note:** This solution does not include the transitive `test`-scoped dependencies automatically. +Maven resolves only the `compile`-time dependencies. +Add all other required `test`-scoped dependencies by hand. The preferred way ----------------- @@ -100,8 +109,10 @@ To let Maven resolve all `test`-scoped transitive dependencies, create a separat ``` -- Move the source files you want to share from `src/test/java` in the original project to `src/main/java` in this project. Move the resources in the same way. -- Move the required `test`-scoped dependencies from the original project to this project. Remove their `test` scope. The test framework dependency, for example junit, gets the default scope too. Add any project specific dependencies that the code needs. +- Move the source files you want to share from `src/test/java` in the original project to `src/main/java` in this project. + Move the resources in the same way. +- Move the required `test`-scoped dependencies from the original project to this project. Remove their `test` scope. + The test framework dependency, for example junit, gets the default scope too. Add any project specific dependencies that the code needs. Add this dependency to use the reusable test classes in another project: diff --git a/src/site/markdown/examples/include-exclude.md.vm b/src/site/markdown/examples/include-exclude.md.vm index 789eca5..be8eb99 100644 --- a/src/site/markdown/examples/include-exclude.md.vm +++ b/src/site/markdown/examples/include-exclude.md.vm @@ -1,6 +1,6 @@ --- title: Howto include/exclude content from a jar archive -author: +author: - Karl Heinz Marbaise date: 2014-06-16 --- @@ -26,7 +26,8 @@ under the License. # How to Include or Exclude Content from a JAR Artifact -Add ``/`` or ``/`` in your `pom.xml`. These elements specify the fileset patterns to include or exclude. +Add ``/`` or ``/`` in your `pom.xml`. +These elements specify the fileset patterns to include or exclude. ```unknown diff --git a/src/site/markdown/examples/manifest-customization.md.vm b/src/site/markdown/examples/manifest-customization.md.vm index 4daeccd..274be8f 100644 --- a/src/site/markdown/examples/manifest-customization.md.vm +++ b/src/site/markdown/examples/manifest-customization.md.vm @@ -1,6 +1,6 @@ --- title: Manifest customization -author: +author: - Dennis Lundberg date: 2006-07-12 --- @@ -31,12 +31,17 @@ The Default Manifest The documentation for [Maven Archiver](/shared/maven-archiver/examples/manifest.html) describes the default contents of the manifest. -Since version 2.1, the Maven JAR Plugin uses Maven Archiver ${mavenArchiverVersion}. It no longer creates the Specification and Implementation details in the manifest by default. To add them, specify them explicitly in your plugin configuration. The documentation for [Maven Archiver](/shared/maven-archiver/examples/manifest.html) describes this as well. +Since version 2.1, the Maven JAR Plugin uses Maven Archiver ${mavenArchiverVersion}. +It no longer creates the Specification and Implementation details in the manifest by default. +To add them, specify them explicitly in your plugin configuration. +The documentation for [Maven Archiver](/shared/maven-archiver/examples/manifest.html) describes this as well. Manifest Customization ---------------------- -You can alter the default manifest with the `archive` configuration element. The example below shows some of the available configuration options. For more information, see the [Maven Archiver reference](/shared/maven-archiver/index.html). +You can alter the default manifest with the `archive` configuration element. +The example below shows some of the available configuration options. +For more information, see the [Maven Archiver reference](/shared/maven-archiver/index.html). ```unknown diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md index 3aa65e1..0c6df4a 100644 --- a/src/site/markdown/index.md +++ b/src/site/markdown/index.md @@ -1,6 +1,6 @@ --- title: Introduction -author: +author: - Dennis Lundberg date: 2013-07-22 --- @@ -35,15 +35,27 @@ This plugin builds JAR files. To sign JAR files, use the [Maven Jarsigner Plugin ## Usage -General instructions for the JAR Plugin are on the [usage page](./usage.html). The examples below describe more specific use cases. +General instructions for the JAR Plugin are on the [usage page](./usage.html). +The examples below describe more specific use cases. -If you have questions about the plugin, see the [FAQ](./faq.html) or contact the [user mailing list](./mailing-lists.html). The mailing list stores all posts in an archive. An older thread can contain the answer to your question. You can search the [mail archive](./mailing-lists.html) for the answer. +If you have questions about the plugin, see the [FAQ](./faq.html) or contact the [user mailing list](./mailing-lists.html). +The mailing list stores all posts in an archive. +An older thread can contain the answer to your question. +You can search the [mail archive](./mailing-lists.html) for the answer. -If the plugin is missing a feature or has a defect, file a feature request or bug report in the [issue tracker](https://github.com/apache/maven-jar-plugin/issues). When you create a new issue, describe your concern in detail. The developers must reproduce the problem to fix a bug. Attach entire debug logs, POMs, or small demo projects to the issue. Patches are welcome. Contributors can check out the project from the [source repository](./scm.html) and find supplementary information in the [guide to helping with Maven](https://maven.apache.org/guides/development/guide-helping.html). +If the plugin is missing a feature or has a defect, +file a feature request or bug report in the [issue tracker](https://github.com/apache/maven-jar-plugin/issues). +When you create a new issue, describe your concern in detail. +The developers must reproduce the problem to fix a bug. +Attach entire debug logs, POMs, or small demo projects to the issue. Patches are welcome. +Contributors can check out the project from the [source repository](./scm.html) and find supplementary information +in the [guide to helping with Maven](https://maven.apache.org/guides/development/guide-helping.html). ## Archiver Configuration -The plugin uses Maven Archiver to handle JAR content and manifest configuration. See the [Maven Archiver Documentation](/shared/maven-archiver/) to learn how to set it up. You can also see the [Guide to Working with Manifests](/guides/mini/guide-manifest.html). +The plugin uses Maven Archiver to handle JAR content and manifest configuration. +See the [Maven Archiver Documentation](/shared/maven-archiver/) to learn how to set it up. +You can also see the [Guide to Working with Manifests](/guides/mini/guide-manifest.html). ## Examples diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm index 597de38..215c954 100644 --- a/src/site/markdown/usage.md.vm +++ b/src/site/markdown/usage.md.vm @@ -1,6 +1,6 @@ --- title: Usage -author: +author: - Jerome Lacoste - Dennis Lundberg - Olivier Lamy @@ -29,9 +29,12 @@ under the License. # Usage -The examples below show how to use this plugin. For advanced configurations, see the [Example section](./index.html#Examples). See the documentation for [Maven Archiver](/shared/maven-archiver/). +The examples below show how to use this plugin. +For advanced configurations, see the [Example section](./index.html#Examples). +See the documentation for [Maven Archiver](/shared/maven-archiver/). -This version of the Maven JAR Plugin uses [Maven Archiver](/shared/maven-archiver/index.html) ${mavenArchiverVersion} to handle archive creation. +This version of the Maven JAR Plugin uses [Maven Archiver](/shared/maven-archiver/index.html) ${mavenArchiverVersion} +to handle archive creation. **Note:** If you need to sign your JAR files, use the [Maven Jarsigner Plugin](/plugins/maven-jarsigner-plugin/) instead. @@ -43,7 +46,7 @@ To create a JAR file with Maven, create a `pom.xml` file with at least the follo ```xml 4.0.0 - + com.mycompany.project core 1.0-SNAPSHOT @@ -63,21 +66,36 @@ mvn package The `package` phase bundles all the files into the artifact. In this case, the artifact is a JAR file. -The generated JAR file is in the `target` directory. Its name is `core-1.0-SNAPSHOT.jar`. The JAR file contains the compiled Java class files and the files from `src/main/resources`. +The generated JAR file is in the `target` directory. Its name is `core-1.0-SNAPSHOT.jar`. +The JAR file contains the compiled Java class files and the files from `src/main/resources`. -Usually you do not need to declare the `maven-jar-plugin` in your `pom.xml`. The plugin is bound to the [Maven Build Life Cycle](/guides/introduction/introduction-to-the-lifecycle.html). +Usually you do not need to declare the `maven-jar-plugin` in your `pom.xml`. +The plugin is bound to the [Maven Build Life Cycle](/guides/introduction/introduction-to-the-lifecycle.html). For full documentation, see [plugin-info](./plugin-info.html). Modular JAR files ----------------- -The [Java Platform Module System (JPMS)](https://openjdk.java.net/projects/jigsaw/spec/) introduced Modular JAR files in the [JAR file specifications](https://cr.openjdk.java.net/~mr/jigsaw/spec/jar.html). A Modular JAR file contains a `module-info.class` file in the root directory. For multi-release JAR files, the file is in the versioned area. If the project contains `module-info.class`, the final JAR is a modular JAR. This happens without any configuration and regardless of the plugin version. +The [Java Platform Module System (JPMS)](https://openjdk.java.net/projects/jigsaw/spec/) introduced +Modular JAR files in the [JAR file specifications](https://cr.openjdk.java.net/~mr/jigsaw/spec/jar.html). +A Modular JAR file contains a `module-info.class` file in the root directory. +For multi-release JAR files, the file is in the versioned area. +If the project contains `module-info.class`, the final JAR is a modular JAR. +This happens without any configuration and regardless of the plugin version. -Since version 3.1.2, this plugin updates the modular descriptor when the JAR contains `module-info.class`. The plugin adds additional attributes, such as the list of included packages. It verifies the modular descriptor. It also verifies that all services provided by the module are in the JAR file. The most notable added attribute is the module main class. +Since version 3.1.2, this plugin updates the modular descriptor when the JAR contains `module-info.class`. +The plugin adds additional attributes, such as the list of included packages. +It verifies the modular descriptor. +It also verifies that all services provided by the module are in the JAR file. +The most notable added attribute is the module main class. -If the JAR manifest contains the `Main-Class` attribute, this plugin sets the module main class to the same value. For an example, see [Make The Jar Executable](../../shared/maven-archiver/examples/classpath.html). +If the JAR manifest contains the `Main-Class` attribute, this plugin sets the module main class to the same value. +For an example, see [Make The Jar Executable](../../shared/maven-archiver/examples/classpath.html). -The plugin uses the JDK `jar` tool internally to add the additional attributes and to verify the modular descriptor. This requires JDK version 9 or newer. +The plugin uses the JDK `jar` tool internally to add the additional attributes and to verify the modular descriptor. +This requires JDK version 9 or newer. -If you use JDK version 8 or earlier, the JAR is still a modular JAR. The JAR contains `module-info.class`. The plugin adds no additional attributes and performs no validation. +If you use JDK version 8 or earlier, the JAR is still a modular JAR. +The JAR contains `module-info.class`. +The plugin adds no additional attributes and performs no validation. From 3d3bfa3ba1a051bd73fd79354a3dc7ffee5a15a1 Mon Sep 17 00:00:00 2001 From: Martin Desruisseaux Date: Tue, 8 Sep 2026 17:59:23 +0900 Subject: [PATCH 2/2] Adapt the documentation since the plugin now uses jar tools instead of Maven Archiver, except for the manifest content. Also add a note about include/exclude filters accepting various syntax. --- .../markdown/examples/include-exclude.md.vm | 3 +++ .../examples/manifest-customization.md.vm | 3 +-- src/site/markdown/index.md | 3 ++- src/site/markdown/usage.md.vm | 23 ++++++------------- 4 files changed, 13 insertions(+), 19 deletions(-) diff --git a/src/site/markdown/examples/include-exclude.md.vm b/src/site/markdown/examples/include-exclude.md.vm index be8eb99..24b4ce6 100644 --- a/src/site/markdown/examples/include-exclude.md.vm +++ b/src/site/markdown/examples/include-exclude.md.vm @@ -53,3 +53,6 @@ These elements specify the fileset patterns to include or exclude. ``` The patterns must be relative to the path for the plugin's `classesDirectory` parameter. +By default, the syntax is the same as Maven 3, where `**` can match any number of directories including zero. +An alternative syntax can be specified by prefixing the pattern with `glob:`, `regex:` or any other syntax added +through the service provider mechanism. See `FileSystem.getPathMatcher(String)` in Java NIO for more information. diff --git a/src/site/markdown/examples/manifest-customization.md.vm b/src/site/markdown/examples/manifest-customization.md.vm index 274be8f..810909f 100644 --- a/src/site/markdown/examples/manifest-customization.md.vm +++ b/src/site/markdown/examples/manifest-customization.md.vm @@ -31,8 +31,7 @@ The Default Manifest The documentation for [Maven Archiver](/shared/maven-archiver/examples/manifest.html) describes the default contents of the manifest. -Since version 2.1, the Maven JAR Plugin uses Maven Archiver ${mavenArchiverVersion}. -It no longer creates the Specification and Implementation details in the manifest by default. +Since version 2.1, the Maven JAR Plugin no longer creates the Specification and Implementation details in the manifest by default. To add them, specify them explicitly in your plugin configuration. The documentation for [Maven Archiver](/shared/maven-archiver/examples/manifest.html) describes this as well. diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md index 0c6df4a..561df1c 100644 --- a/src/site/markdown/index.md +++ b/src/site/markdown/index.md @@ -53,7 +53,8 @@ in the [guide to helping with Maven](https://maven.apache.org/guides/development ## Archiver Configuration -The plugin uses Maven Archiver to handle JAR content and manifest configuration. +The plugin uses the JDK `jar` tool internally to create and verify the JAR file. +The plugin uses Maven Archiver to handle manifest configuration. See the [Maven Archiver Documentation](/shared/maven-archiver/) to learn how to set it up. You can also see the [Guide to Working with Manifests](/guides/mini/guide-manifest.html). diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm index 215c954..d8ec157 100644 --- a/src/site/markdown/usage.md.vm +++ b/src/site/markdown/usage.md.vm @@ -33,10 +33,11 @@ The examples below show how to use this plugin. For advanced configurations, see the [Example section](./index.html#Examples). See the documentation for [Maven Archiver](/shared/maven-archiver/). +The plugin uses the JDK `jar` tool internally to create and verify the JAR file. This version of the Maven JAR Plugin uses [Maven Archiver](/shared/maven-archiver/index.html) ${mavenArchiverVersion} -to handle archive creation. +to handle manifest configuration. -**Note:** If you need to sign your JAR files, use the [Maven Jarsigner Plugin](/plugins/maven-jarsigner-plugin/) instead. +**Note:** If you need to sign your JAR files, use the [Maven Jarsigner Plugin](/plugins/maven-jarsigner-plugin/). How to build a JAR file ----------------------- @@ -77,25 +78,15 @@ For full documentation, see [plugin-info](./plugin-info.html). Modular JAR files ----------------- -The [Java Platform Module System (JPMS)](https://openjdk.java.net/projects/jigsaw/spec/) introduced +The [Java Module System](https://openjdk.java.net/projects/jigsaw/spec/) introduced Modular JAR files in the [JAR file specifications](https://cr.openjdk.java.net/~mr/jigsaw/spec/jar.html). A Modular JAR file contains a `module-info.class` file in the root directory. -For multi-release JAR files, the file is in the versioned area. +For multi-release JAR files, the file can be in the versioned area. If the project contains `module-info.class`, the final JAR is a modular JAR. This happens without any configuration and regardless of the plugin version. -Since version 3.1.2, this plugin updates the modular descriptor when the JAR contains `module-info.class`. -The plugin adds additional attributes, such as the list of included packages. -It verifies the modular descriptor. -It also verifies that all services provided by the module are in the JAR file. -The most notable added attribute is the module main class. +Since version 4.0.0-beta-2, this plugin can verify the JAR file with a `validate` option. +The checks depend on the JDK tool and can include a verification of `module-info.class`. If the JAR manifest contains the `Main-Class` attribute, this plugin sets the module main class to the same value. For an example, see [Make The Jar Executable](../../shared/maven-archiver/examples/classpath.html). - -The plugin uses the JDK `jar` tool internally to add the additional attributes and to verify the modular descriptor. -This requires JDK version 9 or newer. - -If you use JDK version 8 or earlier, the JAR is still a modular JAR. -The JAR contains `module-info.class`. -The plugin adds no additional attributes and performs no validation.