Author: jdcasey
Date: Fri Dec 1 16:15:07 2006
New Revision: 481454
URL: http://svn.apache.org/viewvc?view=rev&rev=481454
Log:
Fixing a couple of counter-intuitive settings, wiring up <baseDirectory/>, and
proving advanced documentation.
Added:
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/advanced-module-set-topics.apt
(with props)
Modified:
maven/plugins/trunk/maven-assembly-plugin/required-docs.txt
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/archive/DefaultAssemblyArchiver.java
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/archive/archiver/PrefixingProxyArchiver.java
maven/plugins/trunk/maven-assembly-plugin/src/main/mdo/descriptor.mdo
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/advanced-descriptor-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/site.xml
maven/plugins/trunk/maven-assembly-plugin/src/test/java/org/apache/maven/plugin/assembly/archive/phase/ModuleSetAssemblyPhaseTest.java
maven/plugins/trunk/maven-assembly-plugin/src/test/java/org/apache/maven/plugin/assembly/filter/ComponentsXmlArchiverFileFilterTest.java
Modified: maven/plugins/trunk/maven-assembly-plugin/required-docs.txt
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/required-docs.txt?view=diff&rev=481454&r1=481453&r2=481454
==============================================================================
--- maven/plugins/trunk/maven-assembly-plugin/required-docs.txt (original)
+++ maven/plugins/trunk/maven-assembly-plugin/required-docs.txt Fri Dec 1
16:15:07 2006
@@ -5,31 +5,4 @@
+ how are they used?
+ what can they specify?
o include examples of usage
-* Advanced Assembly Descriptor Topics: new page
- o ModuleSet improvements
- + module-set-level includes/excludes
- + includeModuleDirectory
- + excludeSubModuleDirectories
- + outputDirectoryMapping at the module level
- + sources vs. binaries sections
- # binaries: attachmentClassifier to look at certain attached
- artifacts for a module
- # binaries: dependencySets section to specify which module
- deps to include
- # includes/excludes still present for backward compat ONLY
- + fileSets subsection (?)
- o FileSet improvements
- + useDefaultExcludes
- o baseDirectory to provide alternate basedir for the root dir of the
- assembly
- o useStrictFiltering -> Added to SetBase, so all dependency sets and
- module sets, etc. can use to fail the build on unused filters in those
sets.
-* Examples:
- o Update all multi-module examples to reflect improvements in <sources>
- and <binaries> sections.
- o Add examples for include/exclude wildcards
- + including filtering out artifacts with a certain classifier or
- type using wildcards
- o More?
-
Modified:
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/archive/DefaultAssemblyArchiver.java
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/archive/DefaultAssemblyArchiver.java?view=diff&rev=481454&r1=481453&r2=481454
==============================================================================
---
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/archive/DefaultAssemblyArchiver.java
(original)
+++
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/archive/DefaultAssemblyArchiver.java
Fri Dec 1 16:15:07 2006
@@ -7,6 +7,7 @@
import org.apache.maven.plugin.assembly.filter.ComponentsXmlArchiverFileFilter;
import org.apache.maven.plugin.assembly.format.AssemblyFormattingException;
import org.apache.maven.plugin.assembly.utils.AssemblyFileUtils;
+import org.apache.maven.plugin.assembly.utils.AssemblyFormatUtils;
import org.apache.maven.plugins.assembly.model.Assembly;
import org.codehaus.plexus.archiver.ArchiveFileFilter;
import org.codehaus.plexus.archiver.Archiver;
@@ -77,7 +78,17 @@
try
{
- Archiver archiver = createArchiver( format,
assembly.isIncludeBaseDirectory(), configSource.getFinalName(),
configSource.getTarLongFileMode(), componentsXmlFilter );
+ String finalName = configSource.getFinalName();
+ String specifiedBasedir = assembly.getBaseDirectory();
+
+ String basedir = finalName;
+
+ if ( specifiedBasedir != null )
+ {
+ basedir = AssemblyFormatUtils.getOutputDirectory(
specifiedBasedir, configSource.getProject(), finalName );
+ }
+
+ Archiver archiver = createArchiver( format,
assembly.isIncludeBaseDirectory(), basedir, configSource.getTarLongFileMode(),
componentsXmlFilter );
for ( Iterator phaseIterator = assemblyPhases.iterator();
phaseIterator.hasNext(); )
{
@@ -114,11 +125,12 @@
* @param includeBaseDir
* @param tarLongFileMode
* @param finalName
+ * @param string
* @return archiver Archiver generated
* @throws org.codehaus.plexus.archiver.ArchiverException
* @throws org.codehaus.plexus.archiver.manager.NoSuchArchiverException
*/
- protected Archiver createArchiver( String format, boolean includeBaseDir,
String finalName,
+ protected Archiver createArchiver( String format, boolean includeBaseDir,
String finalName,
String tarLongFileMode,
ComponentsXmlArchiverFileFilter componentsXmlFilter )
throws ArchiverException, NoSuchArchiverException
{
Modified:
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/archive/archiver/PrefixingProxyArchiver.java
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/archive/archiver/PrefixingProxyArchiver.java?view=diff&rev=481454&r1=481453&r2=481454
==============================================================================
---
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/archive/archiver/PrefixingProxyArchiver.java
(original)
+++
maven/plugins/trunk/maven-assembly-plugin/src/main/java/org/apache/maven/plugin/assembly/archive/archiver/PrefixingProxyArchiver.java
Fri Dec 1 16:15:07 2006
@@ -151,4 +151,9 @@
delegate.setIncludeEmptyDirs( includeEmptyDirs );
}
+ public void setDotFileDirectory( File dotFileDirectory )
+ {
+ throw new UnsupportedOperationException( "Undocumented feature of
plexus-archiver; this is not yet supported." );
+ }
+
}
Modified: maven/plugins/trunk/maven-assembly-plugin/src/main/mdo/descriptor.mdo
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/main/mdo/descriptor.mdo?view=diff&rev=481454&r1=481453&r2=481454
==============================================================================
--- maven/plugins/trunk/maven-assembly-plugin/src/main/mdo/descriptor.mdo
(original)
+++ maven/plugins/trunk/maven-assembly-plugin/src/main/mdo/descriptor.mdo Fri
Dec 1 16:15:07 2006
@@ -689,11 +689,11 @@
<name>includeDependencies</name>
<version>1.0.0+</version>
<type>boolean</type>
- <defaultValue>false</defaultValue>
+ <defaultValue>true</defaultValue>
<description>
If set to true, the plugin will include the direct and transitive
dependencies of
of the project modules included here. Otherwise, it will only
include the module
- packages only. Default value is false.
+ packages only. Default value is true.
</description>
</field>
<field>
Modified:
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/advanced-descriptor-topics.apt
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/site/apt/advanced-descriptor-topics.apt?view=diff&rev=481454&r1=481453&r2=481454
==============================================================================
---
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/advanced-descriptor-topics.apt
(original)
+++
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/advanced-descriptor-topics.apt
Fri Dec 1 16:15:07 2006
@@ -48,9 +48,6 @@
strings, <<<type>>> is <<<'jar'>>> by default, and <<<classifier>>> is
omitted if null.
- # ArtifactUtils.versionlessKey( artifact )
- # artifact.getDependencyConflictId()
- # artifact.getId()
* <<<groupId:artifactId:type:classifier>>>
( <<<artifact.getDependencyConflictId()>>> )
@@ -108,3 +105,170 @@
*:war:*
---
+** Example: Exclude all source-jar dependencies.
+
+ In this example, we're dealing with the fact that project sources are
+ often distributed using jar files, in addition to normal binaries. We want to
+ filter out any source-jar files (they'll be marked with a <<<sources>>>
+ classifier) from the binary jars.
+
+---
+<assembly>
+ [...]
+ <dependencySets>
+ <dependencySet>
+ <includes>
+ <include>*:jar:*</include>
+ </includes>
+ <excludes>
+ <exclude>*:sources</exclude>
+ </excludes>
+ </dependencySet>
+ </dependencySets>
+ [...]
+</assembly>
+---
+
+* Including Subversion Metadata Directories in a FileSet
+
+ For most use cases, it's important to avoid adding metadata files from your
+ source-control system, such as Subversion's <<<.svn>>> directories. Such
+ metadata can increase the size of the resulting assembly vastly. By default,
+ the assembly plugin will exclude metadata files for most common
source-control
+ systems from the <<<fileSet>>>s specified in the descriptor.
+
+ On the other hand, what if you <wanted> to include Subversion metadata
+ directories? Starting with version 2.2, the assembly plugin offers the
+ <<<useDefaultExcludes>>> option on all <<<fileSet>>> elements, in order to
+ accommodate this use case.
+
+** Example: Bundle project sources for a developer-quickstart pack
+
+ In this example, let's examine what happens if you have a large project in
+ source control. This project contains a large number of sizable files that
+ haven't changed since the day they were added, in the early stages of the
+ project's lifetime. You want to enable potential developers to get started
+ quickly, without checking out hundreds of 10-megabyte files first.
+
+ The compression incorporated with many archiving formats can offer an
+ advantage here. If we create a project assembly, including Subversion
metadata
+ directories, developers should be able to download the assembly artifact and
+ expand it, then simply type <<<svn up>>>.
+
+---
+<assembly>
+ [...]
+ <fileSets>
+ <fileSet>
+ <useDefaultExcludes>false</useDefaultExcludes>
+ <excludes>
+ <exclude>**/target/**</exclude>
+ </excludes>
+ </fileSet>
+ </fileSets>
+ [...]
+</assembly>
+---
+
+ <NOTE: You'll notice that we're excluding all target directories; these are a
+ form of "calculated" and otherwise transient data, and generally shouldn't
be
+ included in archives, unless your goal is to create project binaries or
+ similar.>
+
+* Using Strict-Filtering to Catch Obsolete Patterns or Incorrect Builds
+
+ At times, you want to build in a set of sanity checks when creating your
+ assembly, to ensure that what goes into the assembly artifact is what you
+ intended. One way you can do this is by enabling <<<useStrictFiltering>>> on
+ your <<<dependencySets>>>, <<<moduleSets>>>, and <<<fileSets>>>.
+
+ <<<useStrictFiltering>>> is a flag that tells the assembly plugin to track
+ each include/exclude pattern to make sure it's used during creation of the
+ assembly. This way, if the assembly-descriptor author intended for a
particular
+ file or artifact to be present, he can add an include/exclude pattern to the
+ descriptor to ensure that file/artifact is present, and then set the
+ <<<useStrictFiltering>>> flag. If the pattern isn't used to match at least
one
+ file during assembly creation, the build will fail and the user will receive
a
+ message notifying him of the unused patterns.
+
+** Example: Ensuring the LICENSE.txt file is included in a jar
+
+ In this example, we want to make sure that our project jar contains the
+ project's open source license language, in order to be compliant with our
+ software foundation's policies.
+
+---
+<assembly>
+ [...]
+ <fileSets>
+ <fileSet>
+ <useStrictFiltering>true</useStrictFiltering>
+ <outputDirectory>META-INF</outputDirectory>
+ <includes>
+ <include>LICENSE.txt</include>
+ </includes>
+ </fileSet>
+ [...]
+ </fileSets>
+ [...]
+</assembly>
+---
+
+ If a developer inadvertently removes the LICENSE.txt from the project
+ directory, the assembly plugin should refuse to build this assembly.
+
+* Using an Alternative Assembly Base Directory
+
+ In many cases, assemblies should have all files arranged under one assembly
+ base directory. This way, a user who expands the assembly will have all of
the
+ contents collected in a nice, neat directory structure, rather than spread
+ throughout the current working directory. This is achieved using the
+ <<<includeBaseDirectory>>> flag, and this flag is set to <<<true>>> by
+ default, which will result in the project's <<<artifactId-version>>> being
+ used as the assembly base directory.
+
+ However, in some special cases you may want to use a different directory name
+ for the root of your assembly. Starting in the 2.2 version of the assembly
+ plugin, this use case is addressed using the <<<baseDirectory>>> element of
+ the assembly descriptor. With this element, you can use POM expressions and
+ static strings to specify the name of the assembly root directory.
+
+** Example: Eclipse-style invariable directory name for the Maven assembly
+
+ In this example, let's explore what would happen if we wanted Maven to use
the
+ Eclipse approach for naming the root directory in its distribution
assemblies.
+ This way, instead of expanding the distribution to find a new
+ <<<maven-2.0.4>>> directory, you'd find a <<<maven>>> directory.
Additionally,
+ consider that the distribution assembly is currently built from the
+ <<<maven-core>>> project, which means we shouldn't use the <<<artifactId>>>
as
+ part of the assembly root directory.
+
+---
+<assembly>
+ [...]
+ <baseDirectory>maven</baseDirectory>
+ [...]
+</assembly>
+---
+
+ Now, imagine that the distribution assembly were created in the top-level
+ <<<maven>>> project. Now, we <can> use the <<<artifactId>>>, and probably
+ should, just to minimize the maintenance of these files.
+
+---
+<assembly>
+ [...]
+ <baseDirectory>${artifactId}</baseDirectory>
+ [...]
+</assembly>
+---
+
+* Advanced ModuleSet Topics
+
+ One of the most complex sections of the assembly descriptor is the
+ <<<moduleSets>>> section. In fact, so many improvements have been made to
this
+ section that we feel it warrants its own <"Advanced Topics"> page.
+
+ * Go to {{{advanced-module-set-topics.html}Advanced Module-Set Topics}}.
+
+ []
Added:
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?view=auto&rev=481454
==============================================================================
---
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/advanced-module-set-topics.apt
(added)
+++
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/advanced-module-set-topics.apt
Fri Dec 1 16:15:07 2006
@@ -0,0 +1,478 @@
+ ---
+ Advanced Module-Set Topics
+ ---
+ John Casey
+ ---
+ 1 December 2006
+ ---
+
+~~ Copyright 2006 The Apache Software Foundation.
+~~
+~~ Licensed under the Apache License, Version 2.0 (the "License");
+~~ you may not use this file except in compliance with the License.
+~~ You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing, software
+~~ distributed under the License is distributed on an "AS IS" BASIS,
+~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+~~ See the License for the specific language governing permissions and
+~~ limitations under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/guides/mini/guide-apt-format.html
+
+
+Advanced Module-Set Topics
+
+* Quick Note
+
+ Some of the topics in this document refer to more general topics or
+ improvements in the assembly descriptor as a whole. For more information, see
+ the {{{advanced-descriptor-topics.html}Advanced Assembly-Descriptor Topics}}
+ page.
+
+* Including and Excluding Modules using a ModuleSet
+
+ As you are no doubt aware, Maven 2.0 introduces advanced handling of
+ multimodule builds. These are builds which contain multiple, often
+ interrelated projects. In these builds, project hierarchy is established
+ through use of the <<<modules>>> section of the POM, where parent POMs
specify
+ their children in a <<<modules>>> section. Other relationships, like
+ interdependency, also exist within multimodule builds; however, these are
+ beyond the scope of this document.
+
+ When constructing an assembly from any parent-level project in a multimodule
+ build, it's possible to process this parent-POM's descendent modules, and
+ include them in some form within the resulting assembly artifact. By default,
+ the entire module hierarchy below the current project is available for
+ inclusion or exclusion. Also, include/exclude patterns for modules are
matched
+ using the artifact-matching rules explained in the <<Advanced
+ Assembly-Descriptor Topics>> document.
+
+ The following examples describe how to select certain modules in the project
+ hierarchy using basic artifact includes/excludes. It does <<not>> describe
+ what to do with the selected modules; to learn about the actions available
for
+ selected modules, see {{including module sources}} and {{including module
+ binaries}} below. For other, more advanced module-handling options, read on!
+
+** Example: Select one from a set of child projects
+
+ Given the following project structure, and all appropriate module references
+ in the parent POM:
+
+---
++ parent (groupId: org.test, artifactId: parent)
+ |
+ + child1 (groupId: org.test, artifactId: child1)
+ |
+ + child2 (groupId: org.test, artifactId: child2)
+---
+
+ We can select <<just>> the child1 module using the following <<<moduleSet>>>:
+
+---
+<assembly>
+ [...]
+ <moduleSets>
+ [...]
+ <moduleSet>
+ <includes>
+ <include>org.test:child1</include>
+ </includes>
+ </moduleSet>
+ </moduleSets>
+ [...]
+</assembly>
+---
+
+ <NOTE: It's important to remember that, if the child1 project itself had
+ children, those children would not be included just because the child1
project
+ was included. Each module is matched separately.>
+
+~~ [jdcasey] TODO: Amend this once we've handled the case where you want to
process
+~~ the entire inheritance/dependency trail. We'll need a flag to say "Include
+~~ my ancestry when matching for includes/excludes", and have that apply
+~~ appropriately to the transitive dependency trail in a dependencySet, or a
+~~ module hierarchy in a moduleSet.
+
+* Quick Note on <<<outputFileNameMapping>>> within ModuleSets
+
+ When used from within a <<<moduleSet>>>, all <<<outputFileNameMapping>>>
+ configurations with expressions like <<<$\{artifactId\}>>> <extract
information
+ from the artifact in question.>
+
+** Example: Setting <<<outputFileNameMapping>>> from <<<moduleSet/binaries>>>
+
+ Given a module with the following:
+
+---
+Group Id: org.test
+Artifact Id: project
+Version: 1.0.1
+Type: jar
+---
+
+ The following <<<outputFileNameMapping>>>:
+
+---
+${groupId}-${artifactId}-${version}.${extension}
+---
+
+ Will result in a file called <<<org.test-project-1.0.jar>>> being created
+ within the assembly.
+
+ <NOTE: The expression <<<$\{extension\}>>> is mapped to the file extension
+ supplied by the ArtifactHandler for the type <<<jar>>>. It's important to
+ remember that the file extension <<need not be .jar>>.>
+
+* {Including Module Sources}
+
+ Once you've selected certain modules to be included in the assembly, you have
+ to determine what you want included from each module. This usually depends on
+ the purpose of the assembly. For instance, if you're building a binary
+ assembly, for use in a runtime context, you probably want to include module
+ binaries only (see the {{Including Module Binaries}} section below). However,
+ if your assembly is meant to include project sources, either as a reference
or
+ to allow users to build your project (or for some other reason altogether),
+ then you're probably interested in the <<<sources>>> section of the
+ <<<moduleSet>>>.
+
+ Processing module sources is a fileSet-based activity. That is, sources are
+ included or excluded based on file-matching patterns, or explicit
+ <<<fileSet>>> subsections. <<For backward compatibility only>>, the
+ <<<\<sources/\>>>> section itself supports <<<includes>>> and <<<excludes>>>
+ that can help determine which files from a module's directory should be
+ processed. Starting in version 2.2 of the assembly plugin, the
+ <<<\<sources/\>>>> section supports a <<<\<fileSets/\>>>> subsection, which
is
+ the preferred way of selecting module-source files for processing.
+
+** Example: including the <<<src>>> directory from each selected module
+
+ In this example, we'll explore how to include the <<<src>>> directory
<<only>>
+ for each module selected by the moduleSet. This is useful to provide a source
+ reference for your project to users.
+
+---
+<assembly>
+ [...]
+ <moduleSets>
+ [...]
+ <moduleSet>
+ [...]
+ <sources>
+ <fileSets>
+ <fileSet>
+ <directory>src</directory>
+ </fileSet>
+ </fileSets>
+ </sources>
+ </moduleSet>
+ </moduleSets>
+</assembly>
+---
+
+** Example: Including a buildable project directory for each selected module
+
+ In this example, we'll explore how to include an entire buildable project
+ directory, for each selected module, within your assembly. This is useful to
+ give your users the chance to tinker with your project, then build it on
their
+ own.
+
+---
+<assembly>
+ [...]
+ <moduleSets>
+ [...]
+ <moduleSet>
+ [...]
+ <sources>
+ <fileSets>
+ <fileSet>
+ <excludes>
+ <exclude>target/**</exclude>
+ </excludes>
+ </fileSet>
+ </fileSets>
+ </sources>
+ </moduleSet>
+ </moduleSets>
+</assembly>
+---
+
+ <NOTE: We exclude the target directory, since this is assumed to be temporary
+ storage for files produced during the course of a Maven build. Permanent
+ project files are not meant to reside here...>
+
+** Consolidating All Module Sources into a Single Directory Structure
+
+ Normally, each module processed by the assembly plugin is placed within its
+ own directory structure inside the assembly root directory. For module
+ sources, the default name of this module-specific directory is the module's
+ <<<artifactId>>>.
+
+ However, in some cases you may want to consolidate module sources into the
+ same directory structure, based in the assembly root directory. To do this,
+ simply set the <<<includeModuleDirectory>>> flag to <<<false>>>.
+
+*** Example: Copy all module sources into a single <<<src>>> directory
+
+ When providing a source reference to users, you may want to produce a
single,
+ consolidated source directory containing all of the source files from your
+ multimodule hierarchy.
+
+---
+<assembly>
+ [...]
+ <moduleSets>
+ [...]
+ <moduleSet>
+ [...]
+ <sources>
+ <includeModuleDirectory>false</includeModuleDirectory>
+ <fileSets>
+ <fileSet>
+ <outputDirectory>src</outputDirectory>
+ <includes>
+ <include>src/**</include>
+ </includes>
+ </fileSet>
+ </fileSets>
+ </sources>
+ </moduleSet>
+ </moduleSets>
+</assembly>
+---
+
+** Excluding Modules of Modules from Direct Assembly Processing
+
+ When dealing with project sources in a complex multimodule build consisting
of
+ several layers of module groupings, it's sometimes desirable to process only
+ the top layer of modules, and provide <<<fileSet>>> specifications to handle
+ sub-modules. This can make it much easier to preserve the project-directory
+ structure, since it doesn't force all modules - regardless of their location
+ within the project hierarchy - through a flat module-processing mechanism.
+ Processing only the first level of modules is the default configuration for
+ the <<<sources>>> section of a <<<moduleSet>>>.
+
+ To explicitly process modules of modules - sub-modules, that is - simply use
+ the <<<excludeSubModuleDirectories>>> flag, set to <<<false>>>.
+
+*** Example: Providing a shallow source-directory structure for reference
+
+ Consider the case where you want to preserve the context of all source files
+ within your project hierarchy, according to the project in which they belong.
+ At the same time, you want to avoid confusing users with a complex nesting of
+ projects within projects, and present a simple list of projects to browse.
+
+ If your project hierarchy looks like this:
+
+---
++ application
+ |
+ + src
+ |
+ + project1
+ | |
+ | + src
+ | |
+ | + project1-child1
+ | | |
+ | | + src
+ | |
+ | + project1-child2
+ | | |
+ | | + src
+ |
+ + project2
+ |
+ + src
+ |
+ + project2-child1
+ |
+ + src
+---
+
+ You may want it to look like this in the resulting assembly:
+
+---
++ application
+| |
+| + src
+|
++ project1
+| |
+| + src
+|
++ project1-child1
+| |
+| + src
+|
++ project1-child2
+| |
+| + src
+|
++ project2
+| |
+| + src
+|
++ project2-child1
+ |
+ + src
+---
+
+ To accomplish this restructuring, simply use the
+ <<<excludeSubModuleDirectories>>> flag, as follows:
+
+---
+<assembly>
+ [...]
+ <moduleSets>
+ [...]
+ <moduleSet>
+ [...]
+ <sources>
+ <excludeSubModuleDirectories>false</excludeSubModuleDirectories>
+ <fileSets>
+ <fileSet>
+ <includes>
+ <include>src/**</include>
+ </includes>
+ </fileSet>
+ </fileSets>
+ </sources>
+ </moduleSet>
+ </moduleSets>
+</assembly>
+---
+
+* {Including Module Binaries}
+
+ 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
+ jar artifact to your assembly archive; or, it can involve selectively
+ including the dependencies of that module in addition to the module's own
jar.
+
+ At any rate, processing module binaries is an artifact-based activity.
+ Accordingly, selection of the appropriate artifacts for a given module
follows
+ the artifact inclusion rules explained in the <<Advanced Assembly-Descriptor
+ Topics>> document.
+
+ Once you've selected <which> artifacts should be processed for a particular
+ module, you have several options for <how> to process them. In its simplest
+ form, the <<<binaries>>> section of a <<<moduleSet>>> has many of the same
+ characteristics as a <<<dependencySet>>>. That is, you have the option to
+ specify an <<<outputDirectory>>>, and you can choose whether to unpack the
+ artifact(s) - the default action will unpack them.
+
+** Processing a Module's Attachment Artifacts
+
+ Sometimes it's important to have the option to add artifacts from a module
+ that are not the main project artifact. Such artifacts might include
javadocs,
+ project sources, or even other assembly artifacts.
+
+*** Example: Including other assemblies within the current assembly
+
+ Suppose we have the following project structure:
+
+---
++ application
+ |
+ + app-db
+ |
+ + app-web
+ |
+ + app-site
+---
+
+ Further, suppose that the assembly plugin is currently executing at the
+ <<<application>>> level, but that another assembly archive has been created
+ previously for the <<<app-site>>> project. This other assembly archive is a
+ zip file containing the project website. We want to include a copy of this
+ website in the application distribution assembly, which we are creating now.
+
+ Finally, suppose that the website-attachment has a classifier of <<<site>>>
+ taken from the assemblyId.
+
+ Since the zipfile containing the website produced by <<<app-site>>> is an
+ attached artifact in that module, we'll need to extract that artifact instead
+ of the main project artifact.
+
+---
+<assembly>
+ [...]
+ <moduleSets>
+ <moduleSet>
+ <includes>
+ <include>*:app-site</include>
+ </includes>
+ <binaries>
+ <attachmentClassifier>site</attachmentClassifier>
+ <outputDirectory>doc</outputDirectory>
+ <outputFileNameMapping>website.${extension}</outputFileNameMapping>
+ </binaries>
+ </moduleSet>
+ [...]
+ </moduleSets>
+</assembly>
+---
+
+** Excluding Module Dependencies
+
+ Just like any binary, modules usually have runtime dependencies, without
which
+ they will simply fail to execute. By default, module dependencies are
included
+ when the module itself is included. However, as we saw in the above example,
+ there are times when this may not be appropriate.
+
+ In the above example, the module binary included was an assembly artifact
that
+ contained the website for the application. Other assemblies might embody a
+ completely self-contained version of the module's binaries, with all
+ dependency classes unpacked and inlined within the archive.
+
+ In short, sometimes we want to turn off automatic dependency inclusion. We
can
+ achieve this by setting the <<<includeDependencies>>> flag to <<<false>>>.
+
+*** Example: Including a <<<jar-with-dependencies>>> module assembly
+
+ Suppose we have the following project structure:
+
+---
++ application
+ |
+ + app-db
+ |
+ + app-web
+---
+
+ Further, suppose that the assembly plugin is currently executing at the
+ <<<app-web>>> level, but that another assembly archive has been created
+ previously for the <<<app-db>>> project using the built-in
+ <<<jar-with-dependencies>>> assembly descriptor. This assembly archive
+ contains all of the module dependencies, so it's not necessary to include
this
+ module's dependencies in the current assembly.
+
+---
+<assembly>
+ [...]
+ <moduleSets>
+ <moduleSet>
+ <includes>
+ <include>*:app-db</include>
+ </includes>
+ <binaries>
+ <attachmentClassifier>jar-with-dependencies</attachmentClassifier>
+ <outputDirectory>lib</outputDirectory>
+
<outputFileNameMapping>${artifactId}-${version}-${classifier}.${extension}</outputFileNameMapping>
+ </binaries>
+ </moduleSet>
+ [...]
+ </moduleSets>
+</assembly>
+---
+
+ <NOTE: The <<<binaries>>> section still accommodates direct
<<<\<includes/\>>>>
+ and <<<\<excludes/\>>>> subsections, for specifying which
module-dependencies
+ to include in the assembly. However, these are deprecated, and only provided
+ for backward compatibility.>
Propchange:
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/advanced-module-set-topics.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/advanced-module-set-topics.apt
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"
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?view=diff&rev=481454&r1=481453&r2=481454
==============================================================================
---
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
Fri Dec 1 16:15:07 2006
@@ -54,7 +54,6 @@
</includes>
<binaries>
<outputDirectory>modules/${artifactId}</outputDirectory>
- <includeDependencies>true</includeDependencies>
<unpack>false</unpack>
</binaries>
</moduleSet>
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?view=diff&rev=481454&r1=481453&r2=481454
==============================================================================
--- maven/plugins/trunk/maven-assembly-plugin/src/site/site.xml (original)
+++ maven/plugins/trunk/maven-assembly-plugin/src/site/site.xml Fri Dec 1
16:15:07 2006
@@ -31,6 +31,12 @@
<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"/>
+ </menu>
+
<menu name="Examples">
<item name="Examples Index" href="examples/index.html"/>
<item name="Single Project" collapse="false"
href="examples/single/index.html">
Modified:
maven/plugins/trunk/maven-assembly-plugin/src/test/java/org/apache/maven/plugin/assembly/archive/phase/ModuleSetAssemblyPhaseTest.java
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/test/java/org/apache/maven/plugin/assembly/archive/phase/ModuleSetAssemblyPhaseTest.java?view=diff&rev=481454&r1=481453&r2=481454
==============================================================================
---
maven/plugins/trunk/maven-assembly-plugin/src/test/java/org/apache/maven/plugin/assembly/archive/phase/ModuleSetAssemblyPhaseTest.java
(original)
+++
maven/plugins/trunk/maven-assembly-plugin/src/test/java/org/apache/maven/plugin/assembly/archive/phase/ModuleSetAssemblyPhaseTest.java
Fri Dec 1 16:15:07 2006
@@ -245,7 +245,7 @@
macTask.expectGetFinalName( "final-name" );
macTask.expectIsSnapshot( false );
macTask.expectGetArtifactHandler();
-
+
int mode = Integer.parseInt( "777", 8 );
macTask.expectAddFile( "out/artifact", mode );
@@ -261,13 +261,14 @@
bin.setOutputDirectory( "out" );
bin.setFileMode( "777" );
bin.setUnpack( false );
+ bin.setIncludeDependencies( false );
ms.setBinaries( bin );
assembly.addModuleSet( ms );
Logger logger = new ConsoleLogger( Logger.LEVEL_DEBUG, "test" );
-
+
mm.replayAll();
createPhase( logger, null ).execute( assembly, macTask.archiver,
macTask.configSource );
@@ -328,6 +329,7 @@
ModuleBinaries binaries = new ModuleBinaries();
+ binaries.setIncludeDependencies( false );
binaries.setUnpack( false );
binaries.setFileMode( "777" );
binaries.setOutputDirectory( "out" );
@@ -404,6 +406,7 @@
ModuleBinaries binaries = new ModuleBinaries();
+ binaries.setIncludeDependencies( false );
binaries.setUnpack( false );
binaries.setFileMode( "777" );
binaries.setOutputDirectory( "out" );
Modified:
maven/plugins/trunk/maven-assembly-plugin/src/test/java/org/apache/maven/plugin/assembly/filter/ComponentsXmlArchiverFileFilterTest.java
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/test/java/org/apache/maven/plugin/assembly/filter/ComponentsXmlArchiverFileFilterTest.java?view=diff&rev=481454&r1=481453&r2=481454
==============================================================================
---
maven/plugins/trunk/maven-assembly-plugin/src/test/java/org/apache/maven/plugin/assembly/filter/ComponentsXmlArchiverFileFilterTest.java
(original)
+++
maven/plugins/trunk/maven-assembly-plugin/src/test/java/org/apache/maven/plugin/assembly/filter/ComponentsXmlArchiverFileFilterTest.java
Fri Dec 1 16:15:07 2006
@@ -482,6 +482,10 @@
{
throw new UnsupportedOperationException( "not supported" );
}
+
+ public void setDotFileDirectory( File dotFileDirectory )
+ {
+ }
}
}
