| ------ |
| Usage |
| ------ |
| John Casey |
| ------ |
| 2011-02-07 |
| ------ |
| |
| ~~ 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 |
| |
| Usage |
| |
| To handle filtering this version of Maven Assembly Plugin uses |
| {{{http://maven.apache.org/shared/maven-filtering/index.html}Maven Filtering}} ${mavenFilteringVersion}. |
| |
| To handle archiving this version of Maven Assembly Plugin uses |
| {{{http://maven.apache.org/shared/maven-archiver/index.html}Maven Archiver}} ${mavenArchiverVersion}. |
| |
| This document is intended to provide instructions for using the |
| maven-assembly-plugin. In order for this discussion to be useful, it's |
| critical to cover two topics: configuration of the plugin - both inside the |
| POM and, where possible, from the command line - and the different execution |
| styles. For the sake of clarity, we'll cover configuration before execution. |
| |
| |
| * Deprecation notice |
| |
| All goals except <<<assembly:single>>> have been <<deprecated>>. See the |
| {{{./index.html}introduction page}} for more details. |
| |
| |
| * Configuration |
| |
| Getting started with the Assembly Plugin is pretty simple. If you want to use |
| one of the prefabricated assembly descriptors, you configure which descriptor |
| to use with the \<<<<descriptorRefs\>>>>/\<<<<descriptorRef\>>>> parameter. |
| If you want to use a custom assembly descriptor, you configure the path to your |
| descriptor using the \<<<<descriptors\>>>>/\<<<<descriptor\>>>> parameter. |
| |
| Note that a single invocation of the Assembly Plugin can actually |
| produce assemblies from multiple descriptors, allowing you maximum flexibility |
| to customize the suite of binaries your project produces. When the assembly is |
| created it will use the assemblyId as the artifact's classifier and will attach |
| the created assembly to the project so that it will be uploaded into the repository |
| on the install and deploy goals. |
| |
| For example, imagine that our project produces a JAR. If we want to create an |
| assembly binary that includes our project's dependencies, we can take |
| advantage of one of the Assembly Plugin's prefabricated descriptors. You |
| configure it as follows in your project's <<<pom.xml>>>: |
| |
| +---+ |
| <project> |
| [...] |
| <build> |
| [...] |
| <plugins> |
| <plugin> |
| <!-- NOTE: We don't need a groupId specification because the group is |
| org.apache.maven.plugins ...which is assumed by default. |
| --> |
| <artifactId>maven-assembly-plugin</artifactId> |
| <version>${project.version}</version> |
| <configuration> |
| <descriptorRefs> |
| <descriptorRef>jar-with-dependencies</descriptorRef> |
| </descriptorRefs> |
| </configuration> |
| [...] |
| </project> |
| +---+ |
| |
| Note that the Assembly Plugin allows you to specify multiple |
| <<<descriptorRefs>>> at once, to produce multiple types of assemblies in a |
| single invocation. |
| |
| Alternatively, we've created a custom assembly descriptor called |
| <<<src.xml>>> in the <<<src/assembly>>> directory (see the |
| {{{Resources}Resources}} section for more information). We can tell the |
| Assembly Plugin to use that instead: |
| |
| +---+ |
| <project> |
| [...] |
| <build> |
| [...] |
| <plugins> |
| <plugin> |
| <artifactId>maven-assembly-plugin</artifactId> |
| <version>${project.version}</version> |
| <configuration> |
| <descriptors> |
| <descriptor>src/assembly/src.xml</descriptor> |
| </descriptors> |
| </configuration> |
| [...] |
| </project> |
| +---+ |
| |
| Again, note that we could specify multiple custom assembly descriptors here. |
| Additionally, it's possible to specify a mixture of <<<descriptors>>> and |
| <<<descriptorRefs>>> within the same configuration. |
| |
| <<Note:>> Many other configuration options are available for the various goals |
| in the Assembly Plugin. For more information, see the |
| {{{./examples/index.html}examples section}} or the {{{./plugin-info.html}plugin |
| parameter documentation}}. |
| |
| |
| * Execution: Building an Assembly |
| |
| Once you've configured the various <<<descriptors>>> and <<<descriptorRefs>>> |
| for the assemblies you want the project to produce, it's time to build them. |
| |
| In most cases, you'll want to make sure your assemblies are created as part |
| of your normal build process. This ensures the assembly archives are made |
| available for installation and deployment, and that they are created during |
| the release of your project. This is handled by the <<<assembly:single>>> goal. |
| |
| To bind the <<<single>>> goal to a project's build lifecycle, you can add |
| this configuration (assuming you're using the <<<jar-with-dependencies>>> |
| prefabricated descriptor): |
| |
| +---+ |
| <project> |
| [...] |
| <build> |
| [...] |
| <plugins> |
| <plugin> |
| <artifactId>maven-assembly-plugin</artifactId> |
| <version>${project.version}</version> |
| <configuration> |
| <descriptorRefs> |
| <descriptorRef>jar-with-dependencies</descriptorRef> |
| </descriptorRefs> |
| </configuration> |
| <executions> |
| <execution> |
| <id>make-assembly</id> <!-- this is used for inheritance merges --> |
| <phase>package</phase> <!-- bind to the packaging phase --> |
| <goals> |
| <goal>single</goal> |
| </goals> |
| </execution> |
| </executions> |
| </plugin> |
| [...] |
| </project> |
| +---+ |
| |
| Then, to create a project assembly, simple execute the normal <<<package>>> |
| phase from the default lifecycle: |
| |
| +---+ |
| mvn package |
| +---+ |
| |
| When this build completes, you should see a file in the <<<target>>> directory with |
| a name similar to the following: |
| |
| +---+ |
| target/sample-1.0-SNAPSHOT-jar-with-dependencies.jar |
| +---+ |
| |
| Notice the artifact classifier, between the end of the version and the |
| beginning of the file extension, <<<jar-with-dependencies>>>. This is the |
| <<<id>>> of the assembly descriptor used to create this artifact. |
| |
| ** GOTCHA! |
| |
| In most cases, the <<<single>>> goal should be bound to the <<<package>>> phase |
| of the build. However, if your assembly doesn't require binaries, or if you need |
| to use one assembly as input for another, you may need to change this. While it's |
| possible to assign the <<<single>>> goal to any phase of the build lifecycle, you should |
| be careful to make sure the resources included in your assembly exist before that |
| assembly is created. |
| |
| |
| * Advanced Configuration |
| |
| ** Creating an Executable JAR |
| |
| As you've no doubt noticed, the Assembly Plugin can be a very useful way to |
| create a self-contained binary artifact for your project, among many other |
| things. However, once you've created this self-contained JAR, you will |
| probably want the ability to execute it using the <<<-jar>>> JVM switch. |
| |
| To accommodate this, the Assembly Plugin supports configuration of an |
| <<<\<archive\>>>> element which is handled by <<<maven-archiver>>> |
| (see {{{Resources}Resources}}). Using this |
| configuration, it's easy to configure the <<<Main-Class>>> attribute of the |
| JAR manifest: |
| |
| +---+ |
| <project> |
| [...] |
| <build> |
| [...] |
| <plugins> |
| <plugin> |
| <artifactId>maven-assembly-plugin</artifactId> |
| <version>${project.version}</version> |
| <configuration> |
| [...] |
| <archive> |
| <manifest> |
| <mainClass>org.sample.App</mainClass> |
| </manifest> |
| </archive> |
| </configuration> |
| [...] |
| </plugin> |
| [...] |
| </project> |
| +---+ |
| |
| If we add this configuration to the <<<single>>> goal example above and |
| rebuild, we will see an entry like this in the <<<META-INF/MANIFEST.MF>>> file of |
| the resulting JAR: |
| |
| +---+ |
| [...] |
| Main-Class: org.sample.App |
| +---+ |
| |
| For more information on advanced configuration for the Assembly Plugin, see |
| the {{{Resources}Resources}} section. |
| |
| ** GOTCHA! |
| |
| At this point, only the <<<jar>>> and <<<war>>> assembly formats support the <<<\<archive\>>>> |
| configuration element. |
| |
| |
| * {Resources} |
| |
| [[1]] For more information on writing your own assembly descriptor, read the |
| {{{./assembly.html}Assembly Descriptor}} |
| |
| [[2]] For more information about <<<maven-archiver>>>, look |
| {{{http://maven.apache.org/shared/maven-archiver/index.html}here}}. |
| |
| [[3]] For more information on advanced <<<maven-assembly-plugin>>> |
| configuration, see the {{{./examples/index.html}examples}}. |
| |
| [] |