| ------ |
| Usage |
| ------ |
| Jerome Lacoste |
| Dennis Lundberg |
| Olivier Lamy |
| Karl Heinz Marbaise |
| ------ |
| 2016-06-03 |
| ------ |
| |
| ~~ Licensed to the Apache Software Foundation (ASF) under one |
| ~~ or more contributor license agreements. See the NOTICE file |
| ~~ distributed with this work for additional information |
| ~~ regarding copyright ownership. The ASF licenses this file |
| ~~ to you under the Apache License, Version 2.0 (the |
| ~~ "License"); you may not use this file except in compliance |
| ~~ with the License. You may obtain a copy of the License at |
| ~~ |
| ~~ http://www.apache.org/licenses/LICENSE-2.0 |
| ~~ |
| ~~ Unless required by applicable law or agreed to in writing, |
| ~~ software distributed under the License is distributed on an |
| ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| ~~ KIND, either express or implied. See the License for the |
| ~~ specific language governing permissions and limitations |
| ~~ under the License. |
| |
| ~~ NOTE: For help with the syntax of this file, see: |
| ~~ http://maven.apache.org/doxia/references/apt-format.html |
| |
| Usage |
| |
| Some brief examples on how to use this plugin. If you want to use advanced |
| configurations you should have a look at the |
| {{{./index.html#Examples}Example section}}. |
| documentation for |
| {{{/shared/maven-archiver/}Maven Archiver}}. |
| |
| To handle archiving this version of Maven JAR Plugin uses |
| {{{/shared/maven-archiver/index.html}Maven Archiver}} ${mavenArchiverVersion}. |
| |
| <<Note:>> If you need to sign your JAR files you should use the |
| {{{/plugins/maven-jarsigner-plugin/}Maven Jarsigner Plugin}} instead. |
| |
| * How to build a JAR file |
| |
| When you want to create a JAR-file with Maven, you first have to create a <<<pom.xml>>>-file with at least the following content: |
| |
| +----------+ |
| <project> |
| <modelVersion>4.0.0</modelVersion> |
| |
| <groupId>com.mycompany.project</groupId> |
| <artifactId>core</artifactId> |
| <version>1.0-SNAPSHOT</version> |
| <!-- <packaging>jar</packaging> --> |
| </project> |
| +----------+ |
| |
| Since 'jar' is the default packaging type it is not required to set it in this case. |
| Apart from the above you will normally want some real java source files which should be located within |
| <<<src/main/java>>>. If you need extra resources on your classpath (for example property files) |
| they should be located in <<<src/main/resources>>>. |
| Now we can create a JAR-file by using the command below: |
| |
| +-----------------+ |
| mvn package |
| +-----------------+ |
| |
| The 'package' phase is always responsible for bundling all the files in the artifact, in this case a JAR-file. |
| |
| In your project's <<<target>>> directory you'll see the generated jar file which is named like: |
| 'core-1.0-SNAPSHOT.jar'. The resulting 'jar' file contains the compiled java class files as well as |
| the files from <<<src/main/resources>>>. |
| |
| Usually there is no need to mentioned the 'maven-jar-plugin' explicit cause it's bound to |
| the {{{/guides/introduction/introduction-to-the-lifecycle.html}Maven Build Life Cycle}}. |
| |
| For full documentation, click {{{./plugin-info.html}here}}. |
| |
| * Modular JAR files |
| |
| The {{{https://openjdk.java.net/projects/jigsaw/spec/}Java Platform Module System (JPMS)}} introduced |
| {{{https://cr.openjdk.java.net/~mr/jigsaw/spec/jar.html}changes in the JAR file specifications}} |
| as well - Modular JAR files. Modular JAR files are JAR files with <<<module-info.class>>> file in the root directory |
| (or in the versioned area for multi-release JAR files). If the project contains <<<module-info.class>>> |
| the resulting JAR will be a Modular JAR without a need for any configuration regardless of the plugin version used. |
| |
| Starting with version 3.1.2, if the JAR file contains <<<module-info.class>>>, this plugin will update |
| the modular descriptor (<<<module-info.class>>>) with additional attributes such as the list of packages included |
| and will validate the resulting modular descriptor (for example if all services provided by the module are actually |
| included in the JAR file). The most notable additional attribute added is the module main class. |
| If the JAR manifest contains <<<Main-Class>>> attribute this plugin will set the module main class to the same value |
| (for example how to set it read {{{../../shared/maven-archiver/examples/classpath.html}Make The Jar Executable}}). |
| Internally the plugin uses the JDK <<<jar>>> tool so in order to add the additional attributes and to |
| verify the modular descriptor Maven should be run with JDK version 9 or newer. If version 8 or earlier is used |
| the resulting JAR still will be Modular JAR (as it contains <<<module-info.class>>>) but no additional attributes |
| will be added and no validation will be performed. |