<?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>
  </part>
  <part id="Build Lifecycle">
    <faq id="binding">
      <question>What goal should I use to create an assembly as part of my normal build process?</question>
      <answer>
        <p>Use the <a href="single-mojo.html">single</a> or <a href="directory-single-mojo.html">directory-single</a> goal.</p>
        <p>Since the <a href="assembly-mojo.html">assembly</a>, <a href="attached-mojo.html">attached</a>, <a href="directory-mojo.html">directory</a>, and <a href="directory-inline-mojo.html">directory-inline</a> goals are all aggregators, they will execute at most once
           per execution of Maven. See <a href="http://docs.codehaus.org/display/MAVEN/Atypical+Plugin+Use+Cases">Atypical+Plugin+Use+Cases</a> (wiki) for more
           information on the problems associated with aggregator mojos.
        </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>If your assembly includes module binaries, those binaries won't be available to the assembly plugin except in special cases. This is normally seen
           when the Assembly Plugin is bound to a phase of the standard build lifecycle. It happens because of the way Maven sorts and executes the build process for
           a multimodule project layout.
        </p>
        <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. Then, move your assembly descriptor into this new child module,
           and change all module-binary references to dependencySet references. Obviously, any fileSet or file references you may have in this descriptor may need
           to be adjusted or have the files they reference moved into the new child module alongside the descriptor itself.
        </p>
        <p>In cases where you absolutely must use module-binaries references, you should avoid binding your assembly into the main build lifecycle. Modify your POM
           so that the Assembly Plugin configuration is defined in the main the plugin declaration, then remove the executions block from that plugin declaration
           (which supplies the phase and goal specifications that create the lifecycle binding). Finally, to process this assembly, you'll need to execute something like
           this:
        </p>
        <p><code>mvn package assembly:assembly</code></p>
        <p>to force Maven to build the entire multimodule structure to the 'package' phase <b>before</b> attempting
           to process the assembly. This ensures the module artifacts are present to satisfy your module-binaries definitions.
        </p>
      </answer>
    </faq>
  </part>
  <part id="Artifact and Directory Formatting">
    <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>
  </part>
</faqs>
