Author: jdcasey
Date: Tue Dec 16 14:01:35 2008
New Revision: 727187
URL: http://svn.apache.org/viewvc?rev=727187&view=rev
Log:
[MASSEMBLY-151][MASSEMBLY-159] Cleaning up documentation, especially as it
relates to differences between mojos and for dealing with moduleSet/binaries.
Removed:
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/AttachAssemblyDescriptorMojo.java
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/AttachComponentDescriptorMojo.java
Modified:
maven/plugins/trunk/maven-assembly-plugin/pom.xml
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/AssemblyMojo.java
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/AttachedAssemblyMojo.java
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/DirectoryInlineMojo.java
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/DirectoryMojo.java
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/DirectorySingleMojo.java
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/SingleAssemblyMojo.java
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/UnpackMojo.java
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/advanced-module-set-topics.apt
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/examples/multimodule/module-binary-inclusion-simple.apt
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/examples/sharing-descriptors.apt
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/features.apt
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/index.apt
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt
maven/plugins/trunk/maven-assembly-plugin/src/site/fml/faq.fml
Modified: maven/plugins/trunk/maven-assembly-plugin/pom.xml
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/pom.xml?rev=727187&r1=727186&r2=727187&view=diff
==============================================================================
--- maven/plugins/trunk/maven-assembly-plugin/pom.xml (original)
+++ maven/plugins/trunk/maven-assembly-plugin/pom.xml Tue Dec 16 14:01:35 2008
@@ -392,4 +392,14 @@
</build>
</profile>
</profiles>
+
+ <reporting>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-plugin-plugin</artifactId>
+ <version>2.4.3</version>
+ </plugin>
+ </plugins>
+ </reporting>
</project>
Modified:
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/AssemblyMojo.java
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/AssemblyMojo.java?rev=727187&r1=727186&r2=727187&view=diff
==============================================================================
---
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/AssemblyMojo.java
(original)
+++
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/AssemblyMojo.java
Tue Dec 16 14:01:35 2008
@@ -22,9 +22,17 @@
import org.apache.maven.project.MavenProject;
/**
- * Assemble an application bundle or distribution from an assembly descriptor.
This goal should be used from the command line, and if building a multimodule
project it should be used from the root POM.
- * Consider using <code>assembly:attached</code> or
<code>assembly:single</code> for binding assembly generation to the lifecycle.
+ * Assemble an application bundle or distribution using an assembly descriptor
from the command line.
+ * This goal will force Maven to build all included POMs up to the
<code>package</code> phase BEFORE
+ * the assembly is processed.
+ * <br/>
+ *
+ * <b>NOTE:</b> This goal should ONLY be run from the command line, and if
building a multimodule project
+ * it should be used from the root POM. Use the <code>assembly:single</code>
goal for binding
+ * your assembly to the lifecycle.
+ * <br/>
*
+ * @author <a href="mailto:[email protected]";>John Casey</a>
* @author <a href="mailto:[email protected]";>Brett Porter</a>
* @author <a href="mailto:[email protected]";>Vincent Siveton</a>
* @version $Id$
Modified:
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/AttachedAssemblyMojo.java
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/AttachedAssemblyMojo.java?rev=727187&r1=727186&r2=727187&view=diff
==============================================================================
---
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/AttachedAssemblyMojo.java
(original)
+++
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/AttachedAssemblyMojo.java
Tue Dec 16 14:01:35 2008
@@ -22,14 +22,22 @@
import org.apache.maven.project.MavenProject;
/**
- * Assemble an application bundle or distribution from an assembly descriptor.
- * This goal is suitable for binding to the lifecycle at the root of a
multimodule project when you are aggregating the output from the builds of
several modules.
+ * Assemble an application bundle or distribution from an assembly descriptor,
+ * WITHOUT first forcing Maven to build all POMs to the <code>package</code>
+ * phase (as is required by the <code>assembly:assembly</code> goal).
+ * <br/>
*
+ * <b>NOTE:</b> This goal should ONLY be run from the command line, and if
building a multimodule project
+ * it should be used from the root POM. Use the <code>assembly:single</code>
goal for binding
+ * your assembly to the lifecycle.
+ *
+ * @author <a href="mailto:[email protected]";>John Casey</a>
* @author <a href="mailto:[email protected]";>Jerome Lacoste</a>
* @version $Id$
*
* @goal attached
* @aggregator
+ * @deprecated Use goal: 'assembly' (from the command line) or 'single' (from
a lifecycle binding) instead.
*/
public class AttachedAssemblyMojo
extends AbstractAssemblyMojo
Modified:
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/DirectoryInlineMojo.java
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/DirectoryInlineMojo.java?rev=727187&r1=727186&r2=727187&view=diff
==============================================================================
---
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/DirectoryInlineMojo.java
(original)
+++
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/DirectoryInlineMojo.java
Tue Dec 16 14:01:35 2008
@@ -22,15 +22,30 @@
import org.apache.maven.project.MavenProject;
/**
- * Assemble an application bundle or distribution from an assembly descriptor
into the
- * target directory structure but do not generate the final archive. This goal
is suitable
- * for using at the root of a multimodule project, and is the unarchived
counterpart to <code>assembly:attached</code>.
+ * Like the <code>assembly:attached</code> goal, assemble an application
bundle
+ * or distribution from an assembly descriptor,
+ * WITHOUT first forcing Maven to build all POMs to the <code>package</code>
+ * phase (as is required by the <code>assembly:assembly</code> goal). This goal
+ * differs from <code>assembly:attached</code> in that it ignores the
<formats/>
+ * section of the assembly descriptor, and forces the assembly to be created as
+ * a directory in the project's build-output directory (usually
<code>./target</code>).
+ * <br/>
+ *
+ * This goal is also functionally equivalent to using the
<code>assembly:attached</code>
+ * goal in conjunction with the <code>dir</code> assembly format.
+ * <br/>
*
+ * <b>NOTE:</b> This goal should ONLY be run from the command line, and if
building a multimodule project
+ * it should be used from the root POM. Use the
<code>assembly:directory-single</code> goal for binding
+ * your assembly to the lifecycle.
+ *
+ * @author <a href="mailto:[email protected]";>John Casey</a>
* @author <a href="mailto:[email protected]";>Gilles Scokart</a>
* @version $Id$
*
* @goal directory-inline
* @aggregator
+ * @deprecated Use goal: 'directory' (from the command line) or
'directory-single' (from a lifecycle binding) instead.
*/
public class DirectoryInlineMojo
extends AbstractDirectoryMojo
Modified:
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/DirectoryMojo.java
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/DirectoryMojo.java?rev=727187&r1=727186&r2=727187&view=diff
==============================================================================
---
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/DirectoryMojo.java
(original)
+++
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/DirectoryMojo.java
Tue Dec 16 14:01:35 2008
@@ -22,12 +22,24 @@
import org.apache.maven.project.MavenProject;
/**
- * Assemble an application bundle or distribution from an assembly descriptor
into the
- * target directory structure but do not generate the final archive. This goal
should be used from
- * the command line, and if building a multimodule project it should be used
from the root POM.
- * It is the unarchived counterpart to <code>assembly:assembly</code>.
- * Consider using <code>assembly:directory-inline</code> or
<code>assembly:directory-single</code> for binding assembly generation to the
lifecycle.
+ * Like the <code>assembly:attached</code> goal, assemble an application
bundle
+ * or distribution using an assembly descriptor from the command line.
+ * This goal will force Maven to build all included POMs up to the
<code>package</code> phase BEFORE
+ * the assembly is processed. This goal
+ * differs from <code>assembly:assembly</code> in that it ignores the
<formats/>
+ * section of the assembly descriptor, and forces the assembly to be created as
+ * a directory in the project's build-output directory (usually
<code>./target</code>).
+ * <br/>
+ *
+ * This goal is also functionally equivalent to using the
<code>assembly:assembly</code>
+ * goal in conjunction with the <code>dir</code> assembly format.
+ * <br/>
*
+ * <b>NOTE:</b> This goal should ONLY be run from the command line, and if
building a multimodule project
+ * it should be used from the root POM. Use the
<code>assembly:directory-single</code> goal for binding
+ * your assembly to the lifecycle.
+ *
+ * @author <a href="mailto:[email protected]";>John Casey</a>
* @version $Id$
* @goal directory
* @execute phase="package"
Modified:
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/DirectorySingleMojo.java
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/DirectorySingleMojo.java?rev=727187&r1=727186&r2=727187&view=diff
==============================================================================
---
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/DirectorySingleMojo.java
(original)
+++
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/DirectorySingleMojo.java
Tue Dec 16 14:01:35 2008
@@ -22,11 +22,18 @@
import org.apache.maven.project.MavenProject;
/**
- * Assemble an application bundle or distribution from an assembly descriptor
into the
- * target directory structure but do not generate the final archive.
- * This goal is suitable for binding to the lifecycle if you are not
aggregating the content of any modules.
- * It is the unarchived counterpart to <code>assembly:single</code>.
+ * Like the <code>assembly:attached</code> goal, assemble an application
bundle
+ * or distribution from an assembly descriptor. This goal is suitable either
for
+ * binding to the lifecycle or calling directly from the command line
(provided
+ * all required files are available before the build starts, or are produced
+ * by another goal specified before this one on the command line).
+ * <br/>
+ *
+ * This goal differs from <code>assembly:single</code> in that it ignores the
<formats/>
+ * section of the assembly descriptor, and forces the assembly to be created as
+ * a directory in the project's build-output directory (usually
<code>./target</code>).
*
+ * @author <a href="mailto:[email protected]";>John Casey</a>
* @author <a href="mailto:[email protected]";>Gilles Scokart</a>
* @version $Id$
*
Modified:
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/SingleAssemblyMojo.java
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/SingleAssemblyMojo.java?rev=727187&r1=727186&r2=727187&view=diff
==============================================================================
---
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/SingleAssemblyMojo.java
(original)
+++
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/SingleAssemblyMojo.java
Tue Dec 16 14:01:35 2008
@@ -23,8 +23,12 @@
/**
* Assemble an application bundle or distribution from an assembly descriptor.
- * This goal is suitable for binding to the lifecycle if you are not
aggregating the content of any modules.
+ * This goal is suitable either for binding to the lifecycle or calling
directly
+ * from the command line (provided all required files are available before the
+ * build starts, or are produced by another goal specified before this one
+ * on the command line).
*
+ * @author <a href="mailto:[email protected]";>John Casey</a>
* @author <a href="mailto:[email protected]";>Brett Porter</a>
* @version $Id$
* @goal single
Modified:
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/UnpackMojo.java
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/UnpackMojo.java?rev=727187&r1=727186&r2=727187&view=diff
==============================================================================
---
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/UnpackMojo.java
(original)
+++
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/mojos/UnpackMojo.java
Tue Dec 16 14:01:35 2008
@@ -40,6 +40,7 @@
* @version $Id$
* @goal unpack
* @requiresDependencyResolution test
+ * @deprecated Use org.apache.maven.plugins:maven-dependency-plugin goal:
unpack or unpack-dependencies instead.
*/
public class UnpackMojo
extends AbstractMojo
Modified:
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/advanced-module-set-topics.apt
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/site/apt/advanced-module-set-topics.apt?rev=727187&r1=727186&r2=727187&view=diff
==============================================================================
---
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/advanced-module-set-topics.apt
(original)
+++
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/advanced-module-set-topics.apt
Tue Dec 16 14:01:35 2008
@@ -349,6 +349,11 @@
* {Including Module Binaries}
+ *WARNING!* Using the <<<binaries>>> section of a <<<moduleSet>>> definition
+ involves some tricky considerations that are a result of the way Maven
+ sorts and executes project builds within a multimodule context. Please
+ read {{{faq.html#module-binaries}this FAQ entry}} if you decide to use them.
+
In cases where your assembly artifact is meant to be used in a runtime
context, you'll most likely want to include the binaries from any modules
processed by the assembly plugin. This can be as simple as adding the
module's
Modified:
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/examples/multimodule/module-binary-inclusion-simple.apt
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/site/apt/examples/multimodule/module-binary-inclusion-simple.apt?rev=727187&r1=727186&r2=727187&view=diff
==============================================================================
---
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/examples/multimodule/module-binary-inclusion-simple.apt
(original)
+++
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/examples/multimodule/module-binary-inclusion-simple.apt
Tue Dec 16 14:01:35 2008
@@ -25,6 +25,13 @@
Including Module Binaries
+* Warning
+
+ *WARNING!* Using the <<<binaries>>> section of a <<<moduleSet>>> definition
+ involves some tricky considerations that are a result of the way Maven
+ sorts and executes project builds within a multimodule context. Please
+ read {{{faq.html#module-binaries}this FAQ entry}} if you decide to use them.
+
* Introduction
It is common practice to create an assembly using the parent POM of a
Modified:
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/examples/sharing-descriptors.apt
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/site/apt/examples/sharing-descriptors.apt?rev=727187&r1=727186&r2=727187&view=diff
==============================================================================
---
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/examples/sharing-descriptors.apt
(original)
+++
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/examples/sharing-descriptors.apt
Tue Dec 16 14:01:35 2008
@@ -71,7 +71,7 @@
<assembly>
<id>my-assembly-descriptor-id</id>
<formats>
- <format>zip</format>
+ <format>jar</format>
</formats>
<fileSets>
<fileSet>
Modified: maven/plugins/trunk/maven-assembly-plugin/src/site/apt/features.apt
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/site/apt/features.apt?rev=727187&r1=727186&r2=727187&view=diff
==============================================================================
--- maven/plugins/trunk/maven-assembly-plugin/src/site/apt/features.apt
(original)
+++ maven/plugins/trunk/maven-assembly-plugin/src/site/apt/features.apt Tue Dec
16 14:01:35 2008
@@ -36,7 +36,7 @@
* All assembly inclusions controlled by include/exclude pattern sets
- * Option to unpack artifact files into the assembly
+ * Option to unpack artifact files into the assembly <[deprecated in 2.2]>
* Project modules can be included as source files or in binary form <[2.1]>
Modified: maven/plugins/trunk/maven-assembly-plugin/src/site/apt/index.apt
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/site/apt/index.apt?rev=727187&r1=727186&r2=727187&view=diff
==============================================================================
--- maven/plugins/trunk/maven-assembly-plugin/src/site/apt/index.apt (original)
+++ maven/plugins/trunk/maven-assembly-plugin/src/site/apt/index.apt Tue Dec 16
14:01:35 2008
@@ -106,42 +106,10 @@
modules, file-sets, and individual files are packaged in the assembly.
-* Goals Overview
+* Goals
- The Assembly Plugin has six goals:
+ For more information about the goals that are available in the Assembly
Plugin, see {{{plugin-info.html}the plugin documentation page}}.
- * {{{assembly-mojo.html}assembly:assembly}} Assembles an application bundle
- or distribution based on an assembly descriptor into an archive of a chosen
- format. Executed from the command-line.
-
- * {{{attached-mojo.html}assembly:attached}} Assembles an application bundle
- or distribution from an assembly descriptor into an archive of a chosen
- format. Executed within the Maven Lifecycle.
-
- * {{{directory-mojo.html}assembly:directory}} Assembles an application bundle
- from an assembly descriptor or distribution into a directory. Executed from
- the command-line.*
-
- * {{{directory-inline-mojo.html}assembly:directory-inline}} Assembles an
- application bundle or distribution into a directory. Executed within the
Maven
- Lifecycle.*
-
- * {{{unpack-mojo.html}assembly:unpack}} Assembles an application bundle or
- distribution from an assembly descriptor into an archive of a chosen format
- but with the dependencies unpacked inside the archive.
-
- * {{{single-mojo.html}assembly:single}} An assembly mojo created as a
- work-around for lifecycle issues until addressed in the Maven 2.1 release.
-
- * {{{directory-single-mojo.html}assembly:directory-single}} An assembly mojo
- created as a work-around for lifecycle issues until addressed in the Maven
2.1
- release. This mojo will generate an assembly into a directory.
-
- []
-
- \* <<NOTE:>> Directory-based assemblies cannot be attached to a project for
- deployment or installation, since they do not represent a single,
- self-contained file which can be transferred across network connections.
* Assembly Descriptor Schemas (XSD)
Modified: maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt?rev=727187&r1=727186&r2=727187&view=diff
==============================================================================
--- maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt (original)
+++ maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt Tue Dec 16
14:01:35 2008
@@ -187,8 +187,8 @@
If you need to ensure that assemblies are produced whenever your project
builds, or when a particular profile is activated (also useful for
configuring
other plugins during this special process), then the following two mojos are
- probably what you're looking for. The <<<attached>>> and
- <<<directory-inline>>> mojos are functional counterparts of the mojos
+ probably what you're looking for. The <<<single>>> and
+ <<<single-directory>>> mojos are functional counterparts of the mojos
discussed above, except that they are meant to bind into the default build
lifecycle.
@@ -199,16 +199,16 @@
once again in a forked lifecycle which is spawned by the <<<assembly>>> mojo
itself.
- By contrast, the <<<attached>>> mojo assumes that the build has already
+ By contrast, the <<<single>>> mojo assumes that the build has already
produced project binaries or whatever else it needs prior to building the
assembly itself. Because they depend on correct binding to the lifecycle in
order to gain access to the files required by your project assembly, the
- <<<attached>>> and <<<directory-inline>>> mojos require the user to have much
+ <<<single>>> and <<<single-directory>>> mojos require the user to have much
more intimate knowledge of the build process.
*** Normal Assemblies
- To bind the <<<attached>>> mojo to a project's build lifecycle, you can add
+ To bind the <<<single>>> mojo to a project's build lifecycle, you can add
this configuration (assuming you're using the <<<jar-with-dependencies>>>
prefabricated descriptor):
@@ -230,7 +230,7 @@
<id>make-assembly</id> <!-- this is used for inheritance merges -->
<phase>package</phase> <!-- append to the packaging phase. -->
<goals>
- <goal>attached</goal> <!-- goals == mojos -->
+ <goal>single</goal> <!-- goals == mojos -->
</goals>
</execution>
</executions>
@@ -259,7 +259,7 @@
*** Assembly Directories
- If instead you want to bind the <<<directory-inline>>> mojo to a project's
+ If instead you want to bind the <<<single-directory>>> mojo to a project's
build lifecycle - so you can construct a directory containing your assembly -
you can add this configuration (assuming you're using the
<<<jar-with-dependencies>>> prefabricated descriptor):
@@ -282,7 +282,7 @@
<id>make-assembly</id> <!-- this is used for inheritance merges -->
<phase>package</phase> <!-- append to the packaging phase. -->
<goals>
- <goal>directory-inline</goal> <!-- goals == mojos -->
+ <goal>single-directory</goal> <!-- goals == mojos -->
</goals>
</execution>
</executions>
@@ -302,7 +302,7 @@
+---+
target
-|-- sample-1.0-SNAPSHOT-jar-with-dependencies
+|-- sample-1.0-SNAPSHOT-jar-with-dependencies.dir
| |-- META-INF
| | |-- MANIFEST.MF
| | `-- maven
@@ -322,18 +322,21 @@
* Advanced Configuration
-** Creating Assemblies from Multiple Projects in a Multimodule Build
-
- In certain cases, you may need to create several assembly archives from
- different points in a multimodule build. For this reason, two new assembly
- mojos have been introduced: <<<assembly:single>>>, and
- <<<assembly:directory-single>>>. These mojos will perform the usual tasks
- associated with creating assembly archives or directories, without running in
- a once-per-build mode. However, it's important to note that the use of the
- <<<\<moduleSets\>>>> section in the assembly descriptor may be limited in
- these cases, since the assembly mojo will not have access to the full list of
- projects in the current build. See the examples entry in the
- {{{#Resources}Resources}} section below for more information.
+~~
+~~ 'single' and 'single-directory' should nearly always replace 'attached' and
'directory-inline'.
+~~
+~~** Creating Assemblies from Multiple Projects in a Multimodule Build
+~~
+~~ In certain cases, you may need to create several assembly archives from
+~~ different points in a multimodule build. For this reason, two new assembly
+~~ mojos have been introduced: <<<assembly:single>>>, and
+~~ <<<assembly:directory-single>>>. These mojos will perform the usual tasks
+~~ associated with creating assembly archives or directories, without running
in
+~~ a once-per-build mode. However, it's important to note that the use of the
+~~ <<<\<moduleSets\>>>> section in the assembly descriptor may be limited in
+~~ these cases, since the assembly mojo will not have access to the full list
of
+~~ projects in the current build. See the examples entry in the
+~~ {{{#Resources}Resources}} section below for more information.
** Creating an Executable Jar
@@ -370,7 +373,7 @@
</project>
+---+
- If we add this configuration to the <<<attached>>> mojo example above and
+ If we add this configuration to the <<<single>>> mojo example above and
rebuild, we will see an entry like this in the META-INF/MANIFEST.MF file of
the resulting jar:
Modified: maven/plugins/trunk/maven-assembly-plugin/src/site/fml/faq.fml
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/site/fml/faq.fml?rev=727187&r1=727186&r2=727187&view=diff
==============================================================================
--- maven/plugins/trunk/maven-assembly-plugin/src/site/fml/faq.fml (original)
+++ maven/plugins/trunk/maven-assembly-plugin/src/site/fml/faq.fml Tue Dec 16
14:01:35 2008
@@ -41,6 +41,50 @@
</answer>
</faq>
</part>
+ <part id="Build Lifecycle">
+ <faq id="binding">
+ <question>What goal should I use to create an assembly as part of my
normal build process?</question>
+ <answer>
+ <p>Use the <a href="single-mojo.html">single</a> or <a
href="directory-single-mojo.html">directory-single</a> goal.</p>
+ <p>Since the <a href="assembly-mojo.html">assembly</a>, <a
href="attached-mojo.html">attached</a>, <a
href="directory-mojo.html">directory</a>, and <a
href="directory-inline-mojo.html">directory-inline</a> goals are all
aggregators, they will execute at most once
+ per execution of Maven. See <a
href="http://docs.codehaus.org/display/MAVEN/Atypical+Plugin+Use+Cases";>Atypical+Plugin+Use+Cases</a>
(wiki) for more
+ information on the problems associated with aggregator mojos.
+ </p>
+ </answer>
+ </faq>
+ <faq id="module-binaries">
+ <question>The Assembly Plugin is saying it cannot find files for the
module binaries included by my assembly descriptor. What gives?</question>
+ <answer>
+ <p>If your assembly includes module binaries, those binaries won't be
available to the assembly plugin except in special cases. This is normally seen
+ when the Assembly Plugin is bound to a phase of the standard build
lifecycle. It happens because of the way Maven sorts and executes the build
process for
+ a multimodule project layout.
+ </p>
+ <p>In a multimodule hierarchy, when a child module declares the parent
POM in its <parent/> section, Maven interprets this to mean that the
parent
+ project's build must be completed before the child build can start.
This ensures that the parent project is in its final form by the time the child
+ needs access to its POM information. In cases where the Assembly
Plugin is included as part of that parent project's build process, it will
execute
+ along with everything else as part of the parent build - <b>before
the child build can start</b>. If the assembly descriptor used in that parent
build
+ references module binaries, it effectively expects the child build
to be completed <b>before the assembly is processed</b>. This leads to a
recursive
+ dependency situation, where the child build depends on the parent
build to complete before it can start, while the parent build depends on the
presence
+ of child-module artifacts to complete successfully. Since these
artifacts are missing, the Assembly Plugin will complain about missing
artifacts, and
+ the build will fail.
+ </p>
+ <p>In many cases, you can avoid this problem by adding a new child
module whose sole purpose is to produce your assembly. In the POM for this new
project,
+ add dependency definitions for any of the module binaries you had
previously referenced. Then, move your assembly descriptor into this new child
module,
+ and change all module-binary references to dependencySet
references. Obviously, any fileSet or file references you may have in this
descriptor may need
+ to be adjusted or have the files they reference moved into the new
child module alongside the descriptor itself.
+ </p>
+ <p>In cases where you absolutely must use module-binaries references,
you should avoid binding your assembly into the main build lifecycle. Modify
your POM
+ so that the Assembly Plugin configuration is defined in the main
the plugin declaration, then remove the executions block from that plugin
declaration
+ (which supplies the phase and goal specifications that create the
lifecycle binding). Finally, to process this assembly, you'll need to execute
something like
+ this:
+ </p>
+ <p><code>mvn package assembly:assembly</code></p>
+ <p>to force Maven to build the entire multimodule structure to the
'package' phase <b>before</b> attempting
+ to process the assembly. This ensures the module artifacts are
present to satisfy your module-binaries definitions.
+ </p>
+ </answer>
+ </faq>
+ </part>
<part id="Artifact and Directory Formatting">
<faq id="dashClassifier">
<question>
