src/site/apt/advanced-module-set-topics.apt.vm - maven-assembly-plugin - Git at Google

   ---
   Advanced Module-Set Topics
   ---
   John Casey
   ---
   2006-12-01
   ---

 ~~ Licensed to the Apache Software Foundation (ASF) under one
 ~~ or more contributor license agreements.  See the NOTICE file
 ~~ distributed with this work for additional information
 ~~ regarding copyright ownership.  The ASF licenses this file
 ~~ to you under the Apache License, Version 2.0 (the
 ~~ "License"); you may not use this file except in compliance
 ~~ with the License.  You may obtain a copy of the License at
 ~~
 ~~   http://www.apache.org/licenses/LICENSE-2.0
 ~~
 ~~ Unless required by applicable law or agreed to in writing,
 ~~ software distributed under the License is distributed on an
 ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 ~~ KIND, either express or implied.  See the License for the
 ~~ specific language governing permissions and limitations
 ~~ under the License.

 ~~ NOTE: For help with the syntax of this file, see:
 ~~ http://maven.apache.org/doxia/references/apt-format.html

 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 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}including module sources}}
   and {{{Including_Module_Binaries}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 xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
   [...]
   <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>>>:

 ---
 ${module.groupId}-${module.artifactId}-${module.version}.${module.extension}
 ---

   Will result in a file called <<<org.test-project-1.0.jar>>> being created
   within the assembly.

   <NOTE: The expression> <<<$\{module.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 xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
   [...]
   <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 xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
   [...]
   <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 xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
   [...]
   <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 xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
   [...]
   <moduleSets>
     [...]
     <moduleSet>
       [...]
       <sources>
         <excludeSubModuleDirectories>false</excludeSubModuleDirectories>
         <fileSets>
           <fileSet>
             <includes>
               <include>src/**</include>
             </includes>
           </fileSet>
         </fileSets>
       </sources>
     </moduleSet>
   </moduleSets>
 </assembly>
 ---

 * {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
   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 xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
   [...]
   <moduleSets>
     <moduleSet>
       <includes>
         <include>*:app-site</include>
       </includes>
       <binaries>
         <attachmentClassifier>site</attachmentClassifier>
         <outputDirectory>doc</outputDirectory>
         <outputFileNameMapping>website.${module.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 xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
   [...]
   <moduleSets>
     <moduleSet>
       <includes>
         <include>*:app-db</include>
       </includes>
       <binaries>
         <attachmentClassifier>jar-with-dependencies</attachmentClassifier>
         <outputDirectory>lib</outputDirectory>
         <outputFileNameMapping>${module.artifactId}-${module.version}-${module.classifier}.${module.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.>
	---
	Advanced Module-Set Topics
	---
	John Casey
	---
	2006-12-01
	---

	~~ Licensed to the Apache Software Foundation (ASF) under one
	~~ or more contributor license agreements. See the NOTICE file
	~~ distributed with this work for additional information
	~~ regarding copyright ownership. The ASF licenses this file
	~~ to you under the Apache License, Version 2.0 (the
	~~ "License"); you may not use this file except in compliance
	~~ with the License. You may obtain a copy of the License at
	~~
	~~ http://www.apache.org/licenses/LICENSE-2.0
	~~
	~~ Unless required by applicable law or agreed to in writing,
	~~ software distributed under the License is distributed on an
	~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	~~ KIND, either express or implied. See the License for the
	~~ specific language governing permissions and limitations
	~~ under the License.

	~~ NOTE: For help with the syntax of this file, see:
	~~ http://maven.apache.org/doxia/references/apt-format.html

	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 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}including module sources}}
	and {{{Including_Module_Binaries}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 xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
	[...]
	<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>>>:

	---
	${module.groupId}-${module.artifactId}-${module.version}.${module.extension}
	---

	Will result in a file called <<<org.test-project-1.0.jar>>> being created
	within the assembly.

	<NOTE: The expression> <<<$\{module.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 xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
	[...]
	<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 xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
	[...]
	<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 xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
	[...]
	<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 xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
	[...]
	<moduleSets>
	[...]
	<moduleSet>
	[...]
	<sources>
	<excludeSubModuleDirectories>false</excludeSubModuleDirectories>
	<fileSets>
	<fileSet>
	<includes>
	<include>src/**</include>
	</includes>
	</fileSet>
	</fileSets>
	</sources>
	</moduleSet>
	</moduleSets>
	</assembly>
	---

	* {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
	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 xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
	[...]
	<moduleSets>
	<moduleSet>
	<includes>
	<include>*:app-site</include>
	</includes>
	<binaries>
	<attachmentClassifier>site</attachmentClassifier>
	<outputDirectory>doc</outputDirectory>
	<outputFileNameMapping>website.${module.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 xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
	[...]
	<moduleSets>
	<moduleSet>
	<includes>
	<include>*:app-db</include>
	</includes>
	<binaries>
	<attachmentClassifier>jar-with-dependencies</attachmentClassifier>
	<outputDirectory>lib</outputDirectory>
	<outputFileNameMapping>${module.artifactId}-${module.version}-${module.classifier}.${module.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.>