Author: khmarbaise
Date: Mon Jun 16 17:15:11 2014
New Revision: 1602931
URL: http://svn.apache.org/r1602931
Log:
[MJAR-176]
- Changed documentation according to the suggestions in the
issue.
Added:
maven/plugins/trunk/maven-jar-plugin/src/site/apt/examples/attached-jar.apt.vm
maven/plugins/trunk/maven-jar-plugin/src/site/apt/examples/create-test-jar.apt.vm
maven/plugins/trunk/maven-jar-plugin/src/site/apt/examples/include-exclude.apt.vm
Modified:
maven/plugins/trunk/maven-jar-plugin/src/site/apt/index.apt.vm
maven/plugins/trunk/maven-jar-plugin/src/site/apt/usage.apt.vm
maven/plugins/trunk/maven-jar-plugin/src/site/site.xml
Added:
maven/plugins/trunk/maven-jar-plugin/src/site/apt/examples/attached-jar.apt.vm
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-jar-plugin/src/site/apt/examples/attached-jar.apt.vm?rev=1602931&view=auto
==============================================================================
---
maven/plugins/trunk/maven-jar-plugin/src/site/apt/examples/attached-jar.apt.vm
(added)
+++
maven/plugins/trunk/maven-jar-plugin/src/site/apt/examples/attached-jar.apt.vm
Mon Jun 16 17:15:11 2014
@@ -0,0 +1,70 @@
+ ------
+ How to create an additional attached jar artifact from the project
+ ------
+ Karl Heinz Marbaise
+ ------
+ 2014-06-16
+ ------
+
+ ~~ 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
+
+How to create an additional attached jar artifact from the project
+
+ Specify a list of fileset patterns to be included or excluded by adding
+ <<<\<includes\>>>>/<<<\<include\>>>> or <<<\<excludes\>>>>/<<<\<exclude\>>>>
+ and add a <<<classifier>>> in your <<<pom.xml>>>.
+
+ <<Note:>> the jar-plugin must be defined in a new execution, otherwise it
+ will replace the default use of the jar-plugin instead of adding a second
+ artifact. The <<<classifier>>> is also required to create more than one
artifact.
+
++-----------------+
+<project>
+ ...
+ <build>
+ <plugins>
+ ...
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-jar-plugin</artifactId>
+ <version>${project.version}</version>
+ <executions>
+ <execution>
+ <phase>package</phase>
+ <goals>
+ <goal>jar</goal>
+ </goals>
+ <configuration>
+ <classifier>client</classifier>
+ <includes>
+ <include>**/service/*</include>
+ </includes>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ ...
+ </plugins>
+ </build>
+ ...
+</project>
++-----------------+
+
Added:
maven/plugins/trunk/maven-jar-plugin/src/site/apt/examples/create-test-jar.apt.vm
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-jar-plugin/src/site/apt/examples/create-test-jar.apt.vm?rev=1602931&view=auto
==============================================================================
---
maven/plugins/trunk/maven-jar-plugin/src/site/apt/examples/create-test-jar.apt.vm
(added)
+++
maven/plugins/trunk/maven-jar-plugin/src/site/apt/examples/create-test-jar.apt.vm
Mon Jun 16 17:15:11 2014
@@ -0,0 +1,125 @@
+ ------
+ How to create a jar containing test classes
+ ------
+ Karl Heinz Marbaise
+ ------
+ 2014-06-16
+ ------
+
+ ~~ 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
+
+How to create a jar containing test classes
+
+ When you want to create a jar containing test-classes, you would probably
want to reuse those classes.
+ There are two ways to solve this:
+
+ * Create an attached jar with the test-classes from the current project and
loose its transitive <<<test>>>-scoped dependencies.
+
+ * Create a separate project with the test-classes.
+
+ []
+
+* The easy way
+
+ You can produce a jar which will include your test classes and resources.
+
++-----------------+
+<project>
+ ...
+ <build>
+ <plugins>
+ ...
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-jar-plugin</artifactId>
+ <version>${project.version}</version>
+ <executions>
+ <execution>
+ <goals>
+ <goal>test-jar</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ ...
+ </plugins>
+ </build>
+ ...
+</project>
++-----------------+
+
+ To reuse this artifact in an other project, you must declare this dependency
with type test-jar :
+
++-----------------+
+<project>
+ ...
+ <dependencies>
+ <dependency>
+ <groupId>groupId</groupId>
+ <artifactId>artifactId</artifactId>
+ <type>test-jar</type>
+ <version>version</version>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+ ...
+</project>
++-----------------+
+
+ <<Note:>> The downside of this solution is that you don't get the transitive
<<<test>>>-scoped dependencies automatically.
+ Maven only resolves the <<<compile>>>-time dependencies, so you'll have to
add all the other required <<<test>>>-scoped dependencies by hand.
+
+* The preferred way
+
+ In order to let Maven resolve all <<<test>>>-scoped transitive dependencies
you should create a separate project.
+
++-----------------+
+<project>
+ <groupId>groupId</groupId>
+ <artifactId>artifactId-tests</artifactId>
+ <version>version</version>
+ ...
+</project>
++-----------------+
+
+ * Move the sources files from <<<src/test/java>>> you want to share from
the original project to the <<<src/main/java>>> of this project.
+ The same type of movement counts for the resources as well of course.
+
+ * Move the required <<<test>>>-scoped dependencies and from the original
project to this project and remove the scope (i.e. changing it to the
<<<compile>>>-scope).
+ And yes, that means that the junit dependency (or any other testing
framework dependency) gets the default scope too.
+ You'll probably need to add some project specific dependencies as well to
let it all compile again.
+
+ Now you have your reusable test-classes and you can refer to it as you're
used to:
+
++-----------------+
+<project>
+ ...
+ <dependencies>
+ <dependency>
+ <groupId>groupId</groupId>
+ <artifactId>artifactId-tests</artifactId>
+ <version>version</version>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+ ...
+</project>
++-----------------+
Added:
maven/plugins/trunk/maven-jar-plugin/src/site/apt/examples/include-exclude.apt.vm
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-jar-plugin/src/site/apt/examples/include-exclude.apt.vm?rev=1602931&view=auto
==============================================================================
---
maven/plugins/trunk/maven-jar-plugin/src/site/apt/examples/include-exclude.apt.vm
(added)
+++
maven/plugins/trunk/maven-jar-plugin/src/site/apt/examples/include-exclude.apt.vm
Mon Jun 16 17:15:11 2014
@@ -0,0 +1,61 @@
+ ------
+ Howto include/exclude content from a jar archive
+ ------
+ Karl Heinz Marbaise
+ ------
+ 2014-06-16
+ ------
+
+ ~~ 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
+
+How to include/exclude content from jar artifact
+
+ Specify a list of fileset patterns to be included or excluded by adding
+ <<<\<includes\>>>>/<<<\<include\>>>> or <<<\<excludes\>>>>/<<<\<exclude\>>>>
+ in your <<<pom.xml>>>.
+
++-----------------+
+<project>
+ ...
+ <build>
+ <plugins>
+ ...
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-jar-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <includes>
+ <include>**/service/*</include>
+ </includes>
+ </configuration>
+ </plugin>
+ ...
+ </plugins>
+ </build>
+ ...
+</project>
++-----------------+
+
+ Note that the patterns need to be relative to the path specified for the
plugin's
+ <<<classesDirectory>>> parameter.
+
+
Modified: maven/plugins/trunk/maven-jar-plugin/src/site/apt/index.apt.vm
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-jar-plugin/src/site/apt/index.apt.vm?rev=1602931&r1=1602930&r2=1602931&view=diff
==============================================================================
--- maven/plugins/trunk/maven-jar-plugin/src/site/apt/index.apt.vm (original)
+++ maven/plugins/trunk/maven-jar-plugin/src/site/apt/index.apt.vm Mon Jun 16
17:15:11 2014
@@ -32,9 +32,9 @@ ${project.name}
* Goals Overview
- * {{{./jar-mojo.html}jar:jar}} create a jar file for your project sources.
+ * {{{./jar-mojo.html}jar:jar}} create a jar file for your project classes
inclusive resources.
- * {{{./test-jar-mojo.html}jar:test-jar}} create a jar file for your project
test classes.
+ * {{{./test-jar-mojo.html}jar:test-jar}} create a jar file for your project
test classes .
[]
@@ -76,4 +76,10 @@ ${project.name}
* {{{./examples/default-manifest-file.html}Using a Default Manifest File}}
+ * {{{./examples/include-exclude.html}Howto include/exclude Content from a
jar archive}}
+
+ * {{{./examples/attached-jar.html}How to create an additional attached jar
artifact from the project}}
+
+ * {{{./examples/create-test-jar.html}How to create a jar containing test
classes}}
+
[]
Modified: maven/plugins/trunk/maven-jar-plugin/src/site/apt/usage.apt.vm
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-jar-plugin/src/site/apt/usage.apt.vm?rev=1602931&r1=1602930&r2=1602931&view=diff
==============================================================================
--- maven/plugins/trunk/maven-jar-plugin/src/site/apt/usage.apt.vm (original)
+++ maven/plugins/trunk/maven-jar-plugin/src/site/apt/usage.apt.vm Mon Jun 16
17:15:11 2014
@@ -31,7 +31,9 @@
Usage
Some brief examples on how to use this plugin. If you want to use advanced
- configurations you should have a look at the documentation for
+ configurations you should have a look at the
+ {{{./index.html#Examples}Example section}}.
+ documentation for
{{{http://maven.apache.org/shared/maven-archiver/}Maven Archiver}}.
To handle archiving this version of Maven JAR Plugin uses
@@ -39,194 +41,41 @@ Usage
<<Note:>> Originally, this plugin was meant to sign JARs as well. As of
version 2.3, the corresponding goals are no
longer supported and users are advised to use the dedicated
- {{{http://maven.apache.org/plugins/maven-jarsigner-plugin/}Maven Jarsigner
Plugin}} instead. As of version 2.5, the
- corresponding goals were removed.
+ {{{http://maven.apache.org/plugins/maven-jarsigner-plugin/}Maven Jarsigner
Plugin}} instead. As of the
+ current version 2.5, the corresponding goals were removed.
* How to build a JAR file
If the packaging of your project is set to 'jar', this plugin is executed
- whenever it passes the "package" phase. You can execute it
- using the command below:
+ whenever it passes the "package" phase. The following is a simple example
+ of a project which should produce a 'jar' as an artifact.
-+-----------------+
-mvn package
-+-----------------+
-
- In your project's <<<target>>> directory you'll able to see the generated
jar file.
-
-
-* How to include/exclude content from jar artifact
-
- Specify a list of fileset patterns to be included or excluded by adding
- <<<\<includes\>>>>/<<<\<include\>>>> or <<<\<excludes\>>>>/<<<\<exclude\>>>>
- in your <<<pom.xml>>>.
-
-+-----------------+
++----------+
<project>
...
- <build>
- <plugins>
- ...
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-jar-plugin</artifactId>
- <version>${project.version}</version>
- <configuration>
- <includes>
- <include>**/service/*</include>
- </includes>
- </configuration>
- </plugin>
- ...
- </plugins>
- </build>
+ <groupId>com.mycompany.project</groupId>
+ <artifactId>core</artifactId>
+ <version>1.0-SNAPSHOT</version>
...
</project>
-+-----------------+
-
- Note that the patterns need to be relative to the path specified for the
plugin's
- <<<classesDirectory>>> parameter.
-
-
-* How to create an additional attached jar artifact from the project
++----------+
- Specify a list of fileset patterns to be included or excluded by adding
- <<<\<includes\>>>>/<<<\<include\>>>> or <<<\<excludes\>>>>/<<<\<exclude\>>>>
- and add a <<<classifier>>> in your <<<pom.xml>>>.
+ The packing 'jar' type is not needed to mentioned, cause 'jar' is the
default packaging type.
+ Apart from the above you need to create some real classes which should be
located within
+ <<<src/main/java>>>. If you need some resources (for example property files)
as well they
+ should be located in <<<src/main/resources>>>. Now we can create a 'jar'
file by using the
+ command below:
- <<Note:>> the jar-plugin must be defined in a new execution, otherwise it
- will replace the default use of the jar-plugin instead of adding a second
- artifact. The <<<classifier>>> is also required to create more than one
artifact.
-
-+-----------------+
-<project>
- ...
- <build>
- <plugins>
- ...
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-jar-plugin</artifactId>
- <version>${project.version}</version>
- <executions>
- <execution>
- <phase>package</phase>
- <goals>
- <goal>jar</goal>
- </goals>
- <configuration>
- <classifier>client</classifier>
- <includes>
- <include>**/service/*</include>
- </includes>
- </configuration>
- </execution>
- </executions>
- </plugin>
- ...
- </plugins>
- </build>
- ...
-</project>
+-----------------+
-
-* How to create a jar containing test classes
-
- When you want to create a jar containing test-classes, you would probably
want to reuse those classes.
- There are two ways to solve this:
-
- * Create an attached jar with the test-classes from the current project and
loose its transitive <<<test>>>-scoped dependencies.
-
- * Create a separate project with the test-classes.
-
- []
-
-** The easy way
-
- You can produce a jar which will include your test classes and resources.
-
-+-----------------+
-<project>
- ...
- <build>
- <plugins>
- ...
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-jar-plugin</artifactId>
- <version>${project.version}</version>
- <executions>
- <execution>
- <goals>
- <goal>test-jar</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- ...
- </plugins>
- </build>
- ...
-</project>
-+-----------------+
-
- To reuse this artifact in an other project, you must declare this dependency
with type test-jar :
-
-+-----------------+
-<project>
- ...
- <dependencies>
- <dependency>
- <groupId>groupId</groupId>
- <artifactId>artifactId</artifactId>
- <type>test-jar</type>
- <version>version</version>
- <scope>test</scope>
- </dependency>
- </dependencies>
- ...
-</project>
+mvn package
+-----------------+
- <<Note:>> The downside of this solution is that you don't get the transitive
<<<test>>>-scoped dependencies automatically.
- Maven only resolves the <<<compile>>>-time dependencies, so you'll have to
add all the other required <<<test>>>-scoped dependencies by hand.
-
-** The preferred way
+ In your project's <<<target>>> directory you'll able to 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>>> which have been copied into
<<<target/classes>>>.
- In order to let Maven resolve all <<<test>>>-scoped transitive dependencies
you should create a separate project.
-
-+-----------------+
-<project>
- <groupId>groupId</groupId>
- <artifactId>artifactId-tests</artifactId>
- <version>version</version>
- ...
-</project>
-+-----------------+
-
- * Move the sources files from <<<src/test/java>>> you want to share from
the original project to the <<<src/main/java>>> of this project.
- The same type of movement counts for the resources as well of course.
-
- * Move the required <<<test>>>-scoped dependencies and from the original
project to this project and remove the scope (i.e. changing it to the
<<<compile>>>-scope).
- And yes, that means that the junit dependency (or any other testing
framework dependency) gets the default scope too.
- You'll probably need to add some project specific dependencies as well to
let it all compile again.
-
- Now you have your reusable test-classes and you can refer to it as you're
used to:
-
-+-----------------+
-<project>
- ...
- <dependencies>
- <dependency>
- <groupId>groupId</groupId>
- <artifactId>artifactId-tests</artifactId>
- <version>version</version>
- <scope>test</scope>
- </dependency>
- </dependencies>
- ...
-</project>
-+-----------------+
+ Usually there is no need to mentioned the 'maven-jar-plugin' explicit cause
it's bound to
+ the
{{{http://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html}Maven
Build Life Cylce}}.
For full documentation, click {{{./plugin-info.html}here}}.
Modified: maven/plugins/trunk/maven-jar-plugin/src/site/site.xml
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-jar-plugin/src/site/site.xml?rev=1602931&r1=1602930&r2=1602931&view=diff
==============================================================================
--- maven/plugins/trunk/maven-jar-plugin/src/site/site.xml (original)
+++ maven/plugins/trunk/maven-jar-plugin/src/site/site.xml Mon Jun 16 17:15:11
2014
@@ -37,6 +37,9 @@ under the License.
<item name="Manifest Customization"
href="examples/manifest-customization.html"/>
<item name="Using a Default Manifest File"
href="examples/default-manifest-file.html"/>
<item name="Using Your Own Manifest File"
href="http://maven.apache.org/shared/maven-archiver/examples/manifestFile.html"/>
+ <item name="Additional attached JAR" href="examples/attached-jar.html"/>
+ <item name="Create Test JAR" href="examples/create-test-jar.html"/>
+ <item name="Include/Exclude clases"
href="examples/include-exclude.html"/>
</menu>
</body>
</project>
