You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by jd...@apache.org on 2008/12/16 23:01:36 UTC
svn commit: r727187 - in /maven/plugins/trunk/maven-assembly-plugin: ./
src/main/java/org/apache/maven/plugin/assembly/mojos/ src/site/apt/
src/site/apt/examples/ src/site/apt/examples/multimodule/ src/site/fml/
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:jdcasey@apache.org">John Casey</a>
* @author <a href="mailto:brett@apache.org">Brett Porter</a>
* @author <a href="mailto:vincent.siveton@gmail.com">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:jdcasey@apache.org">John Casey</a>
* @author <a href="mailto:jerome@coffeebreaks.org">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:jdcasey@apache.org">John Casey</a>
* @author <a href="mailto:gscokart@users.sourceforge.net">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:jdcasey@apache.org">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:jdcasey@apache.org">John Casey</a>
* @author <a href="mailto:gscokart@users.sourceforge.net">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:jdcasey@apache.org">John Casey</a>
* @author <a href="mailto:brett@apache.org">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>