src/site/apt/usage.apt.vm

 ------
 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.