src/site/fml/faq.fml

<?xml version="1.0" encoding="UTF-8"?>

<!--
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.
-->


<faqs xmlns="http://maven.apache.org/FML/1.0.1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  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="deploy">
      <question>If the Assembly Plugin is run during the package phase, do my assemblies get deployed during the deploy phase?</question>
      <answer>
        <p>Yes. The assemblies created by the Assembly Plugin is attached to your project so it gets deployed too.</p>
      </answer>
    </faq>
    <faq id="classifier">
      <question>Can I use an artifact created by the assembly plugin as a dependency?</question>
      <answer>
        <p>Yes. You can refer to it using the id of the assembly as the dependency classifier.</p>
      </answer>
    </faq>
    <faq id="javadoc">
      <question>How do I use the Assembly Plugin to package my project's javadoc files?</question>
      <answer>
        <p>The Javadoc Plugin can generate the javadoc files of your projects. Also, the Javadoc Plugin can package them!</p>
        <p>Please see the <a href="http://maven.apache.org/plugins/maven-javadoc-plugin/">Javadoc Plugin Documentation</a>.</p>
      </answer>
    </faq>
    <faq id="inherit">
      <question>Starting with version 2.2 configuration/executions defined in a parent POM are no longer inherited, why?</question>
      <answer>
        <p>As part of the deprecation of all goals except for the <code>single</code> goal, the goals of the Assembly Plugin and their configuration/executions are no longer inherited by default.</p>
        <p>If you need the configuration/executions to be inherited you need to explicitly say so by adding a line to the plugin declaration in the parent POM:</p>
        <pre>
          &lt;plugin&gt;
            &lt;artifactId&gt;maven-assembly-plugin&lt;/artifactId&gt;
            &lt;inherited&gt;true&lt;/inherited&gt;
            ...
        </pre>
      </answer>
    </faq>
    <faq id="shared-descriptor-bug">
      <question>
        In previous versions (before 2.2 final), I followed the example in the documentation for <a href="/examples/sharing-descriptors.html">sharing assembly descriptors</a>, 
        which recommended using the <code>&lt;descriptors/&gt;</code> configuration section to refer to the shared assembly descriptor. As of version 2.2, 
        <em>this no longer works</em>. Why not?
      </question>
      <answer>
        <p>The use of <code>&lt;descriptors/&gt;</code> was always incorrect, and counter to the design of this configuration parameter. Unfortunately, 
           some code was introduced in version 2.2-beta-2 that allowed this parameter to reference descriptors on the classpath, instead of being forced to 
           use <code>&lt;descriptorRefs/&gt;</code> as is the intention of the design. In version 2.2, this bug was fixed.
        </p>
        <p>It is important to note that the correct form, <code>&lt;descriptorRefs/&gt;</code> has always worked, and continues to work. The documentation 
           has now been fixed to reflect the correct configuration.
        </p>
      </answer>
    </faq>
    <faq id="module-binaries">
      <question>The Assembly Plugin is saying it cannot find files for the module binaries included by my assembly descriptor. What gives?</question>
      <answer>
        <p><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 &lt;parent/&gt; section, Maven interprets this to mean that the parent
           project's build must be completed before the child build can start. This ensures that the parent project is in its final form by the time the child
           needs access to its POM information. In cases where the Assembly Plugin is included as part of that parent project's build process, it will execute
           along with everything else as part of the parent build - <b>before the child build can start</b>. If the assembly descriptor used in that parent build
           references module binaries, it effectively expects the child build to be completed <b>before the assembly is processed</b>. This leads to a recursive
           dependency situation, where the child build depends on the parent build to complete before it can start, while the parent build depends on the presence
           of child-module artifacts to complete successfully. Since these artifacts are missing, the Assembly Plugin will complain about missing artifacts, and
           the build will fail.
        </p>
        <p>In many cases, you can avoid this problem by adding a new child module whose sole purpose is to produce your assembly. In the POM for this new project,
           add dependency definitions for any of the module binaries you had previously referenced. 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 create an assembly-child POM mentioned above, then insert
           <code>&lt;useAllReactorProjects&gt;true&lt;useAllReactorProjects&gt;</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 and higher.</p>
      </answer>
    </faq>
    <faq id="required-classifiers">
      <question>
        In previous versions (before 2.2 final), leaving off the assembly id and leaving the classifier unconfigured resulted in the 
        assembly being used as the project's main artifact. With the 2.2 release, this configuration results in a validation error. 
        My project depended on the previous behavior! Why has this changed, and how can I make this work in my project?
      </question>
      <answer>
        <p>The assembly id is used for reporting and calculating descriptor/component merges. They're also required to avoid collisions with the 
           main output of the project's build process. It's critical that this id be in place, to overriding the project's main artifact inadvertently, 
           and to help error-reporting make sense to the user. <em>Leaving off the assembly id has always been an error</em>, but unfortunately previous 
           releases contained a bug in the model that allowed empty or missing assembly id's. This bug has been fixed in version 2.2.
        </p>
        <p>However, in certain cases it makes sense to use the assembly output as the main project artifact. So, what's the correct approach in these 
           situations? This use case is meant to require deliberate configuration, so your intention to depart from the normal behavior will be clear.
           To configure the use of the assembly output as the main project artifact, follow these steps:
        </p>
        <p>
          <ol>
            <li>Make sure your assembly only uses <b>one format</b>. More than one format could mean the assembly artifact used for the project's 
                main artifact is non-deterministic.
            </li>
            <li>Add the configuration: <code>&lt;appendAssemblyId&gt;false&lt;/appendAssemblyId&gt;</code> to your assembly-plugin execution. 
                This will prevent the assembly artifact from simply being attached to the project.
            </li>
          </ol>
        </p>
      </answer>
    </faq>
    <faq id="dashClassifier">
      <question>
        I have a dependencySet that includes some artifacts with classifiers, and others without classifiers.
        How can I setup the file mappings to handle both cases appropriately?
      </question>
      <answer>
        <p>
          The best way to handle a mixed bag of dependencies with and without classifiers is to use the
          <b>${dashClassifier?}</b> expression, added in version 2.2-beta-2 of the assembly plugin especially
          for this purpose. This expression will determine whether each artifact has a classifier, and if it
          does, it will substitute the artifact's classifier - prepended by a dash - in place of the expression.
        </p>
        <p>
          For example, suppose you want to include two artifacts, commons-logging-1.0.4.jar, and
          yourserver-1.0-client.jar (where 'client' is the classifier of the second artifact). To do this,
          simply add the following to your dependencySet:
        </p>
        <pre>
&lt;outputFileNameMapping&gt;${artifact.artifactId}-${artifact.version}${dashClassifier?}.${artifact.extension}&lt;/outputFileNameMapping&gt;
        </pre>
      </answer>
    </faq>
    <faq id="outputFileNameMapping">
      <question>
        Which properties can be used in the outputFileNameMapping parameter.
      </question>
      <answer>
        <p>
          You can use :
        </p>
        <ul>
          <li>all system or maven properties available in your build with the syntax <code>${myProperty}</code>.</li>
          <li>all environment variables with <code>${env.XXX}</code> where <code>XXX</code> is the environment variable.</li>
          <li>the special <code>${dashClassifier?}</code> property (see above).</li>
          <li>all artifacts attributes (<a href="http://maven.apache.org/ref/3.0.4/maven-artifact/apidocs/org/apache/maven/artifact/Artifact.html"> from the Artifact class</a>) like :
          <ul>
              <li><code>${artifact.groupId}</code> : The artifact groupId.</li>
              <li><code>${artifact.artifactId}</code> :  The artifact artifactId.</li>
              <li><code>${artifact.version}</code> :  The artifact classifier.</li>
              <li><code>${artifact.baseVersion}</code> :  The artifact base version (For a SNAPSHOT it will be always -SNAPSHOT and not its timestamp even if you didn't built it yourself).</li>
              <li><code>${artifact.classifier}</code> :  The artifact classifier.</li>
              <li><code>${artifact.scope}</code> :  The artifact scope.</li>
              <li>...</li>
            </ul>
            You can use <code>${module.XXXXX}</code> when using it for your project modules artifacts.
          </li>
        </ul>
      </answer>
    </faq>
    <faq id="tarFileModes">
      <question>
        Tar complains about groupid value being too big
      </question>
      <answer>
        <p>
          GNU tar has restrictions on max value of UID/GUID in tar files.
          Consider using the more well defined POSIX tar format, which should support
          larger values. Use tarLongFileMode=posix in the assembly:single goal.
        </p>
      </answer>
    </faq>

  </part>
</faqs>