| <?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> |
| <plugin> |
| <artifactId>maven-assembly-plugin</artifactId> |
| <inherited>true</inherited> |
| ... |
| </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><descriptors/></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><descriptors/></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><descriptorRefs/></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><descriptorRefs/></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 <parent/> 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><useAllReactorProjects>true<useAllReactorProjects></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><appendAssemblyId>false</appendAssemblyId></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> |
| <outputFileNameMapping>${artifact.artifactId}-${artifact.version}${dashClassifier?}.${artifact.extension}</outputFileNameMapping> |
| </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> |