src/site/apt/advanced-descriptor-topics.apt.vm

  ---
  Advanced Assembly-Descriptor 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 Assembly-Descriptor Topics

* Quick Note on All <<<includes>>> and <<<excludes>>> Patterns

  <<<excludes>>> take priority over <<<includes>>>.

* Archive file resolution

  If two or more elements (e.g., file, fileSet) select different sources for
  the same file for archiving, only one of the source files will be archived.

  As per version 2.5.2 of the assembly plugin, the first phase to
  add the file to the archive "wins". The filtering is done solely based
  on name inside the archive, so the same source file can be added under
  different output names. The order of the phases is as follows:
  1) FileItem 2) FileSets 3) ModuleSet 4) DepenedencySet and 5) Repository elements.

  Elements of the same type will be processed in the order they appear in the
  descriptors. If you need to "overwrite" a file included by a previous set,
  the only way to do this is to exclude that file from the earlier set.

  Note that this behaviour was slightly different in earlier versions of the
  assembly plugin.


* Advanced Artifact-Matching in <<<includes>>> and <<<excludes>>>

  When using <<<dependencySet>>> or <<<moduleSet>>>, the <<<\<includes/\>>>> and
  <<<\<excludes/\>>>> sections actually apply to artifacts, not filenames.
  This can be a good thing, since you don't have to know the artifact's
  filename in the local repository. However, explicitly specifying the full
  artifact ID (consisting of groupId, artifactId, version, type, and classifier)
  for each artifact to be included or excluded can lead to very a verbose
  descriptor. Starting with version 2.2, the assembly plugin addresses the
  clumsiness of explicit artifact identification through the use of wildcard
  patterns.

  The following easy rules should be applied when specifying artifact-matching
  patterns:

  [[1]] Artifacts are matched by a set of identifier strings. In the following
        strings, <<<type>>> is <<<'jar'>>> by default, and <<<classifier>>> is
        omitted if null.

        * <<<groupId:artifactId:type:classifier>>>
          ( <<<artifact.getDependencyConflictId()>>> )

        * <<<groupId:artifactId>>>
          ( <<<ArtifactUtils.versionlessKey( artifact )>>> )

        * <<<groupId:artifactId:type:classifier:version>>>
          ( <<<artifact.getId()>>> )

        []

  [[2]] Any <<<'*'>>> character in an include/exclude pattern will result in the
        pattern being split, and the sub-patterns being matched within the three
        artifact identifiers mentioned above, using <<<String.indexOf(..)>>>.

  [[3]] When no <<<'*'>>> is present in an include/exclude pattern, the pattern
        will only match if the <<entire>> pattern equals one of the three
        artifact identifiers above, using the <<<String.equals(..)>>> method.

  [[4]] In case you missed it above, artifact-identification fields are
        separated by colons (<<<':'>>>) in the matching strings. So, a wildcard
        pattern that matches any artifact of type <<<'war'>>> might be specified
        as <<<*:war>>>.

  []

** Example: Include all dependencies of type <<<'war'>>>

  In this example, we'll configure a <<<dependencySet>>> so it only includes
  those <<<war>>> dependencies.

---
<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">
  [...]
  <dependencySets>
    <dependencySet>
      <includes>
        <include>*:war</include>
      </includes>
    </dependencySet>
  </dependencySets>
  [...]
</assembly>
---

*** GOTCHA!

  In the above example, any <<<war>>> artifacts that happen to have a classifier
  (not sure why this particular case would happen, but it <is> possible) will be
  <<skipped>>. If you <really> want to be careful about catching all of the
  <<<war>>> artifacts in your project, you might want to use the following
  pattern:

---
*: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 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">
  [...]
  <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 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">
  [...]
  <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 Regular Expressions to Exclude Files

  Sometimes, you may find you need to specify an extremely fine-grained inclusion or
  exclusion pattern for a <<<fileSet>>>. In these cases, you have the option of specifying
  your pattern in the form of a regular expression by using the <<<%regex[...]>>> syntax.

  <Note:> For completeness, the default pattern type - Ant-style patterns - can also be
  specified using the new <<<%ant[...]>>> syntax. This will allow room for future expansion
  of <<<fileSet>>> patterns, including the option to change the default pattern syntax
  someday.

** Example: Including directories named <<<target>>> in the <<<src>>> directory

  In this example, we want to produce a buildable source distribution of a
  Maven project hierarchy. Obviously, each project's <<<target>>> directory is
  a temporary workspace for the build process, so we want to exclude these
  directories. However, if one or more of the projects also includes a subdirectory
  named <<<target>>> in the <<<src>>> directory structure - perhaps as part of
  a Java package name - we want to make sure the files in this directory are
  included in the assembly.

---
<assembly>
  [...]
  <fileSets>
    <fileSet>
      <directory>${project.basedir}</directory>
      <outputDirectory></outputDirectory>
      <excludes>
        <exclude>%regex[(?!.*src/).*target.*]</exclude>
      </excludes>
    </fileSet>
    [...]
  </fileSets>
  [...]
</assembly>
---

  The above <<<fileSet>>> uses a somewhat obscure feature of regular
  expressions called <negative lookahead>, which means our exclude pattern
  will only match paths that contain the word <<<target>>> but <<don't>>
  contain <<<src>>>. Effectively, any <<<target>>> directory within the
  <<<src>>> directory structure will be preserved in the assembly.

* 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 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">
  [...]
  <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 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">
  [...]
  <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 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">
  [...]
  <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}}.

  []