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 2010/09/28 00:49:52 UTC
svn commit: r1001945 - in /maven/plugins/trunk/maven-assembly-plugin: ./
src/site/ src/site/apt/ src/site/apt/examples/multimodule/ src/site/fml/
Author: jdcasey
Date: Mon Sep 27 22:49:52 2010
New Revision: 1001945
URL: http://svn.apache.org/viewvc?rev=1001945&view=rev
Log:
[MASSEMBLY-455][MASSEMBLY-431] Improve documentation of built-in descriptors, and add documentation of new useAllReactorProjects flag for the moduleSet section.
Modified:
maven/plugins/trunk/maven-assembly-plugin/pom.xml
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/descriptor-refs.apt.vm
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/examples/multimodule/module-binary-inclusion-simple.apt.vm
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/index.apt
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt.vm
maven/plugins/trunk/maven-assembly-plugin/src/site/fml/faq.fml
maven/plugins/trunk/maven-assembly-plugin/src/site/site.xml
Modified: maven/plugins/trunk/maven-assembly-plugin/pom.xml
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/pom.xml?rev=1001945&r1=1001944&r2=1001945&view=diff
==============================================================================
--- maven/plugins/trunk/maven-assembly-plugin/pom.xml (original)
+++ maven/plugins/trunk/maven-assembly-plugin/pom.xml Mon Sep 27 22:49:52 2010
@@ -292,6 +292,10 @@ under the License.
<version>2.4.1</version>
</plugin>
<plugin>
+ <artifactId>maven-site-plugin</artifactId>
+ <version>2.1.1</version>
+ </plugin>
+ <plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>2.3.1</version>
Modified: maven/plugins/trunk/maven-assembly-plugin/src/site/apt/descriptor-refs.apt.vm
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/site/apt/descriptor-refs.apt.vm?rev=1001945&r1=1001944&r2=1001945&view=diff
==============================================================================
--- maven/plugins/trunk/maven-assembly-plugin/src/site/apt/descriptor-refs.apt.vm (original)
+++ maven/plugins/trunk/maven-assembly-plugin/src/site/apt/descriptor-refs.apt.vm Mon Sep 27 22:49:52 2010
@@ -33,23 +33,10 @@ Pre-defined Descriptor Files
As of version 2.2, there are now four predefined descriptor formats available
for reuse, packaged within the Assembly Plugin, instead of the original three.
Their descriptorIds are:
+
+%{toc|fromDepth=2|toDepth=2}
- * {{{#bin}bin}} - can be used for general assembly of binary packages.
-
- * {{{#jar-with-dependencies}jar-with-dependencies}} - can be used for general
- assembly of a binary package with all the dependency libraries included
- unpacked inside the archive.
-
- * {{{#src}src}} - can be used for general assembly of a source archive which can
- be used to build your project.
-
- * {{{#project}project}} - <<new in version 2.2>>, this is used to create an
- assembly of the entire source project, including the Maven POM and other files
- outside of your source directory structure, but excluding all SCM files and
- the target directory. <<GOTCHA:>> If you use an output directory other than
- /target, this descriptorRef may include the output from your build process.
-
-* {bin}
+* bin
Use <<<bin>>> as the <<<descriptorRef>>> of your assembly-plugin configuration
in order to create a binary distribution archive of your project.
@@ -62,9 +49,9 @@ Pre-defined Descriptor Files
Below is the <<<bin>>> descriptor format:
-%{snippet|id=bin|url=${project.scm.url}/src/main/resources/assemblies/bin.xml}
+%{snippet|id=bin|file=src/main/resources/assemblies/bin.xml}
-* {jar-with-dependencies}
+* jar-with-dependencies
Use <<<jar-with-dependencies>>> as the <<<descriptorRef>>> of your
assembly-plugin configuration in order to create a jar archive which contains
@@ -74,9 +61,9 @@ Pre-defined Descriptor Files
Below is the <<<jar-with-dependencies>>> descriptor format:
-%{snippet|id=jar-with-dependencies|url=${project.scm.url}/src/main/resources/assemblies/jar-with-dependencies.xml}
+%{snippet|id=jar-with-dependencies|file=src/main/resources/assemblies/jar-with-dependencies.xml}
-* {src}
+* src
Use <<<src>>> as the <<<descriptorRef>>> in your assembly-plugin configuration
to create source archives for your project. The archive will contain the
@@ -86,9 +73,11 @@ Pre-defined Descriptor Files
Below is the <<<src>>> descriptor format:
-%{snippet|id=src|url=${project.scm.url}/src/main/resources/assemblies/src.xml}
+%{snippet|id=src|file=src/main/resources/assemblies/src.xml}
+
+* project
-* {project}
+ (Since 2.2)
Using the <<<project>>> <<<\<descriptorRef\>>>> in your assembly plugin
configuration will produce an assembly containing your entire project, minus
@@ -100,4 +89,4 @@ Pre-defined Descriptor Files
The following is the assembly descriptor for the <<<project>>> descriptorRef:
-%{snippet|id=project|url=${project.scm.url}/src/main/resources/assemblies/project.xml}
+%{snippet|id=project|file=src/main/resources/assemblies/project.xml}
Modified: maven/plugins/trunk/maven-assembly-plugin/src/site/apt/examples/multimodule/module-binary-inclusion-simple.apt.vm
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/site/apt/examples/multimodule/module-binary-inclusion-simple.apt.vm?rev=1001945&r1=1001944&r2=1001945&view=diff
==============================================================================
--- maven/plugins/trunk/maven-assembly-plugin/src/site/apt/examples/multimodule/module-binary-inclusion-simple.apt.vm (original)
+++ maven/plugins/trunk/maven-assembly-plugin/src/site/apt/examples/multimodule/module-binary-inclusion-simple.apt.vm Mon Sep 27 22:49:52 2010
@@ -35,6 +35,13 @@ Including Module Binaries
sorts and executes project builds within a multimodule context. Please
read {{{../../faq.html#module-binaries}this FAQ entry}} if you decide to use them.
+ <<NOTE:>> The new (since 2.2) <<<useAllReactorProjects>>> flag in the <<<moduleSet>>> section
+ allows you to consume module binaries from child modules in a multimodule build. This
+ is an important to resolve the conflict between Maven's build ordering and the old
+ approach to module binaries, where the assembly was build from the parent POM.
+ Please read the FAQ entry above for more information, and read the documentation
+ below (carefully!) to see the new approach in action.
+
* Introduction
It is common practice to create an assembly using the parent POM of a
@@ -61,6 +68,11 @@ Including Module Binaries
<includeBaseDirectory>false</includeBaseDirectory>
<moduleSets>
<moduleSet>
+
+ <!-- Enable access to all projects in the current multimodule build! -->
+ <useAllReactorProjects>true</useAllReactorProjects>
+
+ <!-- Now, select which projects to include in this module-set. -->
<includes>
<include>org.test:child1</include>
</includes>
@@ -83,11 +95,17 @@ Including Module Binaries
its dependency artifacts. These artifacts should be contained within the
directory structure <<<modules/child1>>> for this module, since the
outputDirectory expression will be interpolated on a module-by-module basis.
+
+ <<Finally>>, notice the <<new>> <<<useAllReactorProjects>>> flag. This enables
+ access to all projects in the current reactor (multimodule build), even from
+ a child module. Using this flag, it's now possible to use a child module - sorted
+ to the end of the multimodule build process using appropriate dependency
+ declarations - to generate an assembly containing module binaries.
* The POM
Now, let's review the POM configuration necessary to enable the building of
- this assembly via the <assembly:directory> mojo:
+ this assembly via the <<<assembly:single>>> mojo. First, let's look at the parent POM:
+---+
<?xml version="1.0" encoding="UTF-8"?>
@@ -107,33 +125,95 @@ Including Module Binaries
<module>child1</module>
<module>child2</module>
<module>child3</module>
+ <module>distribution</module>
</modules>
<build>
- <plugins>
- <plugin>
- <artifactId>maven-assembly-plugin</artifactId>
- <version>${project.version}</version>
- <configuration>
- <descriptors>
- <descriptor>src/assemble/bin.xml</descriptor>
- </descriptors>
- </configuration>
- </plugin>
- </plugins>
+ <pluginManagement>
+ <plugins>
+ <plugin>
+ <artifactId>maven-assembly-plugin</artifactId>
+ <version>${project.version}</version>
+ <configuration>
+ <descriptors>
+ <descriptor>src/assemble/bin.xml</descriptor>
+ </descriptors>
+ </configuration>
+ </plugin>
+ </plugins>
+ </pluginManagement>
</build>
</project>
+---+
- This POM simply directs the Assembly Plugin to use the <<<bin.xml>>>
- assembly descriptor when executing.
+ <<NOTE:>> The last module - <<<distribution>>> - is the child in which the assembly will be created.
+
+ That POM looks like this:
+
++---+
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>org.test</groupId>
+ <artifactId>parent</artifactId>
+ <version>1.0</version>
+ </parent>
+
+ <artifactId>distribution</artifactId>
+
+ <packaging>pom</packaging>
+
+ <name>Distribution</name>
+
+ <!-- NOTE: These dependency declarations are only required to sort this project to the
+ end of the line in the multimodule build.
+
+ Since we only include the child1 module in our assembly, we only need to ensure this
+ distribution project builds AFTER that one...
+ -->
+ <dependencies>
+ <dependency>
+ <groupId>org.test</groupId>
+ <artifactId>child1</artifactId>
+ <version>1.0</version>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <plugin>
+ <artifactId>maven-assembly-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>distro-assembly</id>
+ <phase>package</phase>
+ <goals>
+ <goal>single</goal>
+ </goals>
+ <configuration>
+ <descriptors>
+ <descriptor>src/assemble/bin.xml</descriptor>
+ </descriptors>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </build>
+</project>
++---+
+
+ This POM directs the Assembly Plugin to execute the <<<single>>> goal when the build reaches the
+ <<<package>>> phase, and tells it to use the <<<bin.xml>>> assembly descriptor when executing.
* Execute!
To build the assembly, we issue the following command:
+---+
-mvn clean package assembly:directory
+mvn clean package
+---+
This will ensure that the output directory (normally, <<<target>>>), is
@@ -147,10 +227,13 @@ mvn clean package assembly:directory
* Examining the Output
When the Maven execution completes, the following directory structure should
- be left:
+ be left. Remember, our assembly format was <<<dir>>>, which is why the output
+ is a directory and not an archive of some sort.
+
+ Here are the directory contents:
+---+
-target/parent-1.0-bin
+target/distribution/distribution-1.0-bin
`-- modules
`-- child1
|-- child1-1.0.jar
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=1001945&r1=1001944&r2=1001945&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 Mon Sep 27 22:49:52 2010
@@ -29,10 +29,6 @@
Maven Assembly Plugin
-~~ * Status
-~~
-~~ <<Current Assembly Plugin Version is: 2.1>>
-~~
* Introduction
Do you want to create a binary distribution from a Maven project that includes
@@ -97,7 +93,7 @@ What is an Assembly?
The Maven Assembly Plugin
- The Assembly Plugin for Maven 2.0 is primarily intended to allow users to
+ The Assembly Plugin for Maven is primarily intended to allow users to
aggregate the project output along with its dependencies, modules, site
documentation, and other files into a single distributable archive.
@@ -109,14 +105,33 @@ The Maven Assembly Plugin
modules, file-sets, and individual files are packaged in the assembly.
+* DEPRECATION NOTICE
+
+ Usage of the <<<assembly:assembly>>>, <<<assembly:attached>>>,
+ <<<assembly:directory>>>, and <<<assembly:directory-inline>>> are <<DEPRECATED>>,
+ since they wreak havoc with normal build processes and promote non-standard
+ build practices.
+
+ Additionally, the <<<assembly:single-directory>>> mojo is
+ redundant, and has been deprecated in favor of the <<<dir>>> assembly format.
+
+ Finally, the <<<assembly:unpack>>> mojo has been deprecated in favor of the far
+ more comprehensive {{{http://maven.apache.org/plugins/maven-dependency-plugin/}Maven
+ Dependency Plugin}}.
+
* Goals
+ The main goal in the assembly plugin is the {{{./single-mojo.html}single}} mojo. It is used to create all assemblies.
+ <<All other mojos are currently deprecated.>>>
+
For more information about the goals that are available in the Assembly Plugin, see {{{./plugin-info.html}the plugin documentation page}}.
* Assembly Descriptor Schemas (XSD)
- * {{{http://maven.apache.org/xsd/assembly-1.1.1.xsd}http://maven.apache.org/xsd/assembly-1.1.1.xsd}} (for version 2.2-beta-4 and higher)
+ * {{{http://maven.apache.org/xsd/assembly-1.1.1.xsd}http://maven.apache.org/xsd/assembly-1.1.2.xsd}} (for version 2.2-beta-6 and higher)
+
+ * {{{http://maven.apache.org/xsd/assembly-1.1.1.xsd}http://maven.apache.org/xsd/assembly-1.1.1.xsd}} (for version 2.2-beta-5 and lower)
* {{{http://maven.apache.org/xsd/assembly-1.1.0.xsd}http://maven.apache.org/xsd/assembly-1.1.0.xsd}} (for version 2.2-beta-3 and lower)
Modified: maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt.vm
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt.vm?rev=1001945&r1=1001944&r2=1001945&view=diff
==============================================================================
--- maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt.vm (original)
+++ maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt.vm Mon Sep 27 22:49:52 2010
@@ -28,6 +28,20 @@
Configuration and Usage
+* DEPRECATION NOTICE
+
+ Usage of the <<<assembly:assembly>>>, <<<assembly:attached>>>,
+ <<<assembly:directory>>>, and <<<assembly:directory-inline>>> are <<DEPRECATED>>,
+ since they wreak havoc with normal build processes and promote non-standard
+ build practices.
+
+ Additionally, the <<<assembly:single-directory>>> mojo is
+ redundant, and has been deprecated in favor of the <<<dir>>> assembly format.
+
+ Finally, the <<<assembly:unpack>>> mojo has been deprecated in favor of the far
+ more comprehensive {{{http://maven.apache.org/plugins/maven-dependency-plugin/}Maven
+ Dependency Plugin}}.
+
* Introduction
This document is intended to provide instructions for using the
@@ -108,111 +122,18 @@ Configuration and Usage
<<NOTE:>> Many other configuration options are available for the various mojos
in the Assembly Plugin. For more information, see the
- {{{examples/index.html}examples section}} or the {{{plugin-info.html}plugin
+ {{{./examples/index.html}examples section}} or the {{{./plugin-info.html}plugin
parameter documentation}}.
* Executing: Building an Assembly
Once you've configured the various <<<descriptors>>> and <<<descriptorRefs>>>
- for the assemblies you want the project to produce, it's time to determine how
- you want to build them.
-
- Currently, there are two basic approaches to building assemblies: as a
- dedicated build action, or bound to a phase of the normal build lifecycle.
- Beyond this, it's also possible to have the Assembly Plugin simply create an
- assembly directory for any given <<<descriptor>>> or <<<descriptorRef>>>,
- instead of creating archives.
-
-** Building an Assembly as a Standalone Process
-
- First, let's examine how we can build an assembly directly, as a process
- separate from the normal build lifecycle. In this case, assemblies won't be
- produced when the normal build is executed, only in special circumstances.
-
- <<NOTE:>> Invoking the <<<assembly>>> and <<<directory>>> mojos will cause
- Maven to build the project using the normal lifecycle, up to the <<<package>>>
- phase. Because many assemblies will contain compiled classes and other
- binaries, it's reasonable to assume that the package phase will be required to
- ensure those binaries exist and have been tested. The main advantage of
- producing an assembly in this way is to avoid producing it as part of your
- normal build process. In some cases, you may only want to create an assembly
- periodically; these mojos provide two ways to accomplish that goal.
-
-*** Normal Assemblies
-
- You can build an assembly directly by executing:
-
-+---+
-mvn assembly:assembly
-+---+
-
- When this build completes, you should see a file in the target directory with
- a name similar to the following:
-
-+---+
-target/sample-1.0-SNAPSHOT-jar-with-dependencies.jar
-+---+
-
- Notice the artifact classifier, between the end of the version and the
- beginning of the file extension, <<<jar-with-dependencies>>>. This is the
- <<<id>>> of the assembly descriptor used to create this artifact.
-
-*** Assembly Directories
-
- You can construct an assembly directory directly from the command line by
- executing:
-
-+---+
-mvn assembly:directory
-+---+
-
- When completed, you should see a directory structure similar to this:
+ for the assemblies you want the project to produce, it's time to build them.
-+---+
-target
-|-- sample-1.0-SNAPSHOT-jar-with-dependencies
-| |-- META-INF
-| | |-- MANIFEST.MF
-| | `-- maven
-| | `-- org.sample
-| | `-- sample
-| | |-- pom.properties
-| | `-- pom.xml
-| |-- junit
-[...]
-| | `-- TestRunner.class
-| |-- junit3.8.1
-| |-- org
-| | `-- sample
-| | `-- App.class
-| `-- stylesheet.css
-+---+
-
-** Building an Assembly as Part of the Build Lifecycle
-
- 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 <<<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.
-
- The <<<assembly>>> mojo forces a <<<package>>> phase build to execute, in
- order to guarantee the availability of project binaries. Unfortunately, this
- currently means that binding the <<<assembly>>> mojo to the default lifecycle
- will cause Maven to execute the build twice - once for the main process, and
- once again in a forked lifecycle which is spawned by the <<<assembly>>> mojo
- itself.
-
- 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
- <<<single>>> and <<<single-directory>>> mojos require the user to have much
- more intimate knowledge of the build process.
-
-*** Normal Assemblies
+ In most cases, you'll want to make sure your assemblies are created as part
+ of your normal build process. This ensures the assembly archives are made
+ available for installation and deployment, and that they are created during
+ the release of your project. This is handled by the <<<assembly:single>>> mojo.
To bind the <<<single>>> mojo to a project's build lifecycle, you can add
this configuration (assuming you're using the <<<jar-with-dependencies>>>
@@ -263,89 +184,18 @@ target/sample-1.0-SNAPSHOT-jar-with-depe
Notice the artifact classifier, between the end of the version and the
beginning of the file extension, <<<jar-with-dependencies>>>. This is the
<<<id>>> of the assembly descriptor used to create this artifact.
-
-*** Assembly Directories
-
- 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):
-
-+---+
-<project>
- [...]
- <build>
- [...]
- <plugins>
- <plugin>
- <artifactId>maven-assembly-plugin</artifactId>
- <version>${project.version}</version>
- <configuration>
- <descriptorRefs>
- <descriptorRef>jar-with-dependencies</descriptorRef>
- </descriptorRefs>
- </configuration>
- <executions>
- <execution>
- <id>make-assembly</id> <!-- this is used for inheritance merges -->
- <phase>package</phase> <!-- append to the packaging phase. -->
- <goals>
- <goal>single-directory</goal> <!-- goals == mojos -->
- </goals>
- </execution>
- </executions>
- </plugin>
- [...]
-</project>
-+---+
-
- Then, to create a project assembly, simple execute the normal <<<package>>>
- phase from the default lifecycle:
-+---+
-mvn package
-+---+
+** GOTCHA!
- When completed, you should see a directory structure similar to this:
-
-+---+
-target
-|-- sample-1.0-SNAPSHOT-jar-with-dependencies.dir
-| |-- META-INF
-| | |-- MANIFEST.MF
-| | `-- maven
-| | `-- org.sample
-| | `-- sample
-| | |-- pom.properties
-| | `-- pom.xml
-| |-- junit
-[...]
-| | `-- TestRunner.class
-| |-- junit3.8.1
-| |-- org
-| | `-- sample
-| | `-- App.class
-| `-- stylesheet.css
-+---+
+ In most cases, the <<<single>>> mojo should be bound to the <<<package>>> phase
+ of the build. However, if your assembly doesn't require binaries, or if you need
+ to use one assembly as input for another, you may need to change this. While it's
+ possible to assign the <<<single>>> mojo to any phase of the build lifecycle, you should
+ be careful to make sure the resources included in your assembly exist before that
+ assembly is created.
* Advanced Configuration
-~~
-~~ '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
As you've no doubt noticed, the Assembly Plugin can be a very useful way to
@@ -396,22 +246,19 @@ Main-Class: org.sample.App
** GOTCHA!
- At this point, only the <<<jar>>> assembly format supports the <<<\<archive\>>>>
- configuration element. By definition, directory-based assembly mojos -
- <<<assembly:directory>>>, <<<assembly:directory-inline>>>, and
- <<<assembly:directory-single>>> - do not produce a jar-format archive, and
- therefore do not support the <<<\<archive\>>>> element.
+ At this point, only the <<<jar>>> and <<<war>>> assembly formats support the <<<\<archive\>>>>
+ configuration element.
* {Resources}
[[1]] For more information on writing your own assembly descriptor, read the
- {{{assembly.html}Assembly Descriptor}}
+ {{{./assembly.html}Assembly Descriptor}}
[[2]] For more information about the <<<maven-jar-plugin>>>, look
{{{http://maven.apache.org/plugins/maven-jar-plugin/}here}}.
[[3]] For more information on advanced <<<maven-assembly-plugin>>>
- configuration, see the {{{examples/index.html}examples}}.
+ configuration, see the {{{./examples/index.html}examples}}.
[]
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=1001945&r1=1001944&r2=1001945&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 Mon Sep 27 22:49:52 2010
@@ -25,6 +25,12 @@ under the License.
xsi:schemaLocation="http://maven.apache.org/FML/1.0.1 http://maven.apache.org/xsd/fml-1.0.1.xsd"
id="FAQ" title="Frequently Asked Questions">
<part id="General">
+ <faq id="getting-started">
+ <question>There seem to be a large number of mojos available in the assembly plugin. Which goal should I use to build my assembly?</question>
+ <answer>
+ <p>You should use the <code>single</code> mojo. All mojos except for <code>single</code> have been deprecated.</p>
+ </answer>
+ </faq>
<faq id="deploy">
<question>If the Assembly Plugin is run during the package phase, do my assemblies get deployed during the deploy phase?</question>
<answer>
@@ -49,7 +55,10 @@ under the License.
<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>Use the <a href="single-mojo.html">single</a> goal.</p>
+ <p><b>NOTE:</b> All other mojos have been deprecated, either because they can cause strange and unpredictable behavior in a variety of situations, or
+ because they are redundant given the availability of the <code>dir</code> assembly format and the <code>maven-dependency-plugin</code>.
+ </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.
@@ -59,9 +68,9 @@ under the License.
<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><b>If your assembly includes module binaries, those binaries won't be available to the assembly plugin except in special cases.</b> This is normally seen
+ when the Assembly Plugin is bound to a phase of the standard build lifecycle in the <b>parent POM</b> of a multimodule build.
+ It is a result 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
@@ -73,19 +82,20 @@ under the License.
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
+ add dependency definitions for any of the module binaries you had previously referenced. This will ensure the new assembly child is built last.
+ Then, move your assembly descriptor into this new child module. At this point, you have the option of either changing all moduleSet/binaries references
+ to dependencySet references, <b>or you can keep the moduleSets and instead set the useAllReactorProjects flag to <i>true</i> for each moduleSet.</b>
+ </p>
+ <p>
+ 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>In cases where you absolutely must use module-binaries references, you should create an assembly-child POM mentioned above, then insert
+ <code><useAllReactorProjects>true<useAllReactorProjects></code> to each of your <code>moduleSet</code> sections. Then, bind the assembly
+ in your assembly-child POM (normally to the <code>package</code> phase) using the <code>single</code> goal. When you execute the build from the top-level POM,
+ Maven should generated your assembly in the new child project.
</p>
+ <p><b>NOTE:</b> The useAllReactorProjects flag is only available in version 2.2-beta-6 and higher.</p>
</answer>
</faq>
</part>
Modified: maven/plugins/trunk/maven-assembly-plugin/src/site/site.xml
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/site/site.xml?rev=1001945&r1=1001944&r2=1001945&view=diff
==============================================================================
--- maven/plugins/trunk/maven-assembly-plugin/src/site/site.xml (original)
+++ maven/plugins/trunk/maven-assembly-plugin/src/site/site.xml Mon Sep 27 22:49:52 2010
@@ -25,37 +25,37 @@ under the License.
name="Maven Assembly plugin">
<body>
<menu name="Reference">
- <item name="Features" href="features.html"/>
- <item name="Descriptor Format" href="assembly.html"/>
- <item name="Component Format" href="component.html"/>
- <item name="Predefined Descriptors" href="descriptor-refs.html"/>
+ <item name="Features" href="./features.html"/>
+ <item name="Descriptor Format" href="./assembly.html"/>
+ <item name="Component Format" href="./component.html"/>
+ <item name="Predefined Descriptors" href="./descriptor-refs.html"/>
</menu>
<menu name="Overview">
- <item name="Introduction" href="index.html"/>
- <item name="Goals" href="plugin-info.html"/>
- <item name="Usage" href="usage.html"/>
- <item name="FAQ" href="faq.html"/>
+ <item name="Introduction" href="./index.html"/>
+ <item name="Goals" href="./plugin-info.html"/>
+ <item name="Usage" href="./usage.html"/>
+ <item name="FAQ" href="./faq.html"/>
</menu>
<menu name="Advanced Topics">
- <item name="Assembly Descriptors" href="advanced-descriptor-topics.html"/>
- <item name="ModuleSets" href="advanced-module-set-topics.html"/>
+ <item name="Assembly Descriptors" href="./advanced-descriptor-topics.html"/>
+ <item name="ModuleSets" href="./advanced-module-set-topics.html"/>
</menu>
<menu name="Examples">
- <item name="Examples Index" href="examples/index.html"/>
- <item name="Single Project" collapse="false" href="examples/single/index.html">
- <item name="Filtering Some Distribution Files" href="examples/single/filtering-some-distribution-files.html"/>
- <item name="Including/Excluding Artifacts" href="examples/single/including-and-excluding-artifacts.html"/>
- <item name="Using Component Descriptors" href="examples/single/using-components.html"/>
- <item name="Using Repositories" href="examples/single/using-repositories.html"/>
+ <item name="Examples Index" href="./examples/index.html"/>
+ <item name="Single Project" collapse="false" href="./examples/single/index.html">
+ <item name="Filtering Some Distribution Files" href="./examples/single/filtering-some-distribution-files.html"/>
+ <item name="Including/Excluding Artifacts" href="./examples/single/including-and-excluding-artifacts.html"/>
+ <item name="Using Component Descriptors" href="./examples/single/using-components.html"/>
+ <item name="Using Repositories" href="./examples/single/using-repositories.html"/>
</item>
- <item name="Multimodule Projects" collapse="false" href="examples/multimodule/index.html">
- <item name="Include Module Artifacts" href="examples/multimodule/module-binary-inclusion-simple.html"/>
- <item name="Include Module Sources" href="examples/multimodule/module-source-inclusion-simple.html"/>
+ <item name="Multimodule Projects" collapse="false" href="./examples/multimodule/index.html">
+ <item name="Include Module Artifacts" href="./examples/multimodule/module-binary-inclusion-simple.html"/>
+ <item name="Include Module Sources" href="./examples/multimodule/module-source-inclusion-simple.html"/>
</item>
- <item name="Sharing Assembly Descriptors" href="examples/sharing-descriptors.html"/>
+ <item name="Sharing Assembly Descriptors" href="./examples/sharing-descriptors.html"/>
</menu>
</body>
</project>