Maven Configuration
Chapter 7
EXPLORE MORE
EXPLORE MORE
7.1. Configuring Maven Plugins
To customize the behavior of a Maven Plugin, you will need to configure the plugin in a project’s POM. The following sections outline the various methods available for customizing a Maven plugin’s configuration.
7.1.1. Plugin Configuration Parameters
Maven plugins are configured using properties that are defined by goals within a plugin. If you look at a goal like the compile
goal in the Maven Compiler Plugin you will see a list of configuration parameters like source
, target
, compilerArgument
, fork
, optimize
, and many others. If you look at the testCompile
goal you will see a different list of configuration parameters for the testCompile
goal. If you are looking for details on the available plugin goal configuration parameters, you can use the Maven Help Plugin to describe a particular plugin or a particular plugin goal.
To describe a particular plugin, use the help:describe
goal from the command line as follows:
$ mvn help:describe -Dcmd=compiler:compile [INFO] [help:describe {execution: default-cli}] [INFO] 'compiler:compile' is a plugin goal (aka mojo). Mojo: 'compiler:compile' compiler:compile Description: Compiles application sources Deprecated. No reason given
For more information about the available configuration parameters, run the same command with the -Ddetail
argument:
$ mvn help:describe -Dcmd=compiler:compile -Ddetail [INFO] [help:describe {execution: default-cli}] [INFO] 'compiler:compile' is a plugin goal (aka mojo). Mojo: 'compiler:compile' compiler:compile Description: Compiles application sources Deprecated. No reason given Implementation: org.apache.maven.plugin.CompilerMojo Language: java Bound to phase: compile Available parameters: compilerArgument Sets the unformatted argument string to be passed to the compiler if fork is set to true. This is because the list of valid arguments passed to a Java compiler varies based on the compiler version. Deprecated. No reason given compilerArguments Sets the arguments to be passed to the compiler (prepending a dash) if fork is set to true. This is because the list of valid arguments passed to a Java compiler varies based on the compiler version. Deprecated. No reason given compilerId (Default: javac) The compiler id of the compiler to use. See this guide for more information. Deprecated. No reason given compilerVersion Version of the compiler to use, ex. '1.3', '1.5', if fork is set to true. Deprecated. No reason given debug (Default: true) Set to true to include debugging information in the compiled class files. Deprecated. No reason given encoding The -encoding argument for the Java compiler. Deprecated. No reason given excludes A list of exclusion filters for the compiler. Deprecated. No reason given executable Sets the executable of the compiler to use when fork is true. Deprecated. No reason given failOnError (Default: true) Indicates whether the build will continue even if there are compilation errors; defaults to true. Deprecated. No reason given fork (Default: false) Allows running the compiler in a separate process. If 'false' it uses the built in compiler, while if 'true' it will use an executable. Deprecated. No reason given includes A list of inclusion filters for the compiler. Deprecated. No reason given maxmem Sets the maximum size, in megabytes, of the memory allocation pool, ex. '128', '128m' if fork is set to true. Deprecated. No reason given meminitial Initial size, in megabytes, of the memory allocation pool, ex. '64', '64m' if fork is set to true. Deprecated. No reason given optimize (Default: false) Set to true to optimize the compiled code using the compiler's optimization methods. Deprecated. No reason given outputFileName Sets the name of the output file when compiling a set of sources to a single file. Deprecated. No reason given showDeprecation (Default: false) Sets whether to show source locations where deprecated APIs are used. Deprecated. No reason given showWarnings (Default: false) Set to true to show compilation warnings. Deprecated. No reason given source The -source argument for the Java compiler. Deprecated. No reason given staleMillis (Default: 0) Sets the granularity in milliseconds of the last modification date for testing whether a source needs recompilation. Deprecated. No reason given target The -target argument for the Java compiler. Deprecated. No reason given verbose (Default: false) Set to true to show messages about what the compiler is doing. Deprecated. No reason given
If you need to get a list of plugin goals which are contained in a plugin, you can run the help:describe goal and pass in the plugin parameter. The plugin parameter accepts a plugin prefix or a groupId
and an artifactId
for a plugin as shown in the following examples:
$ mvn help:describe -Dplugin=compiler [INFO] [help:describe {execution: default-cli}] [INFO] org.apache.maven.plugins:maven-compiler-plugin:2.0.2 Name: Maven Compiler Plugin Description: Maven Plugins Group Id: org.apache.maven.plugins Artifact Id: maven-compiler-plugin Version: 2.0.2 Goal Prefix: compiler This plugin has 2 goals: compiler:compile Description: Compiles application sources Deprecated. No reason given compiler:testCompile Description: Compiles application test sources Deprecated. No reason given
You can use the groupId
and the artifactId
of the plugin and get the same list of plugin goals.
$ mvn help:describe -Dplugin=org.apache.maven.plugins:maven-compiler-plugin
Passing the -Ddetail
argument to the help:describe
goal with the plugin parameter will cause Maven to print out all of the goals and all of the goal parameters for the entire plugin.
7.1.2. Adding Plugin Dependencies
If you need to configure a plugin to use specific versions of dependencies, you can define these dependencies under a dependencies element under plugin. When the plugin executes, it will execute with a classpath that contains these dependencies. Adding Dependencies to a Plugin is an example of a plugin configuration that overrides default dependency versions and adds new dependencies to facilitate goal execution.
Adding Dependencies to a Plugin.
<plugin> <groupId>com.agilejava.docbkx</groupId> <artifactId>docbkx-maven-plugin</artifactId> <version>2.0.9</version> <dependencies> <dependency> <groupId>docbook</groupId> <artifactId>docbook-xml</artifactId> <version>4.5</version> </dependency> <dependency> <groupId>org.apache.fop</groupId> <artifactId>fop-pdf-images</artifactId> <version>1.3</version> </dependency> <dependency> <groupId>org.apache.fop</groupId> <artifactId>fop-pdf-images-res</artifactId> <version>1.3</version> <classifier>res</classifier> </dependency> <dependency> <groupId>pdfbox</groupId> <artifactId>pdfbox</artifactId> <version>0.7.4-dev</version> <classifier>dev</classifier> </dependency> </dependencies> </plugin>
7.1.3. Setting Global Plugin Parameters
To set a value for a plugin configuration parameter in a particular project, use the XML shown in Configuring a Maven Plugin. Unless this configuration is overridden by a more specific plugin parameter configuration, Maven will use the values defined directly under the plugin
element for all goals which are executed in this plugin.
Configuring a Maven Plugin.
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <configuration> <source>1.5</source> <target>1.5</target> </configuration> </plugin>
7.1.4. Setting Execution Specific Parameters
You can configure plugin parameters for specific executions of a plugin goal. Setting Configuration Parameters in an Execution shows an example of configuration parameters being passed to the execution of the run goal of the AntRun plugin during the validate phase. This specific execution will inherit the configuration parameters from the plugin’s configuration element and merge them with the values defined for this particular execution.
Setting Configuration Parameters in an Execution.
<plugin> <artifactId>maven-antrun-plugin</artifactId> <executions> <execution> <phase>validate</phase> <goals> <goal>run</goal> </goals> <configuration> <tasks> <echo>${PATH}=${env.PATH}</echo> <echo>User's Home Directory: ${user.home}</echo> <echo>Project's Base Director: ${basedir}</echo> </tasks> </configuration> </execution> </executions> </plugin>
7.1.5. Setting Default Command Line Execution Parameters
Starting with Maven 2.2.0, you can now supply configuration parameters for goals which are executed from the command-line. To do this, use the special execution id value of "default-cli". Configuring Plugin Parameters for Command Line Execution shows an example that binds the single goal to the package phase of the lifecycle which produces a binary distribution. This example also configures the default-cli
execution for the assembly plugin to use the jar-with-dependencies
assembly descriptor. The bin.xml descriptor will be used during the lifecycle, and jar-with-dependencies
will be used when you execute mvn assembly:assembly
from the command line.
Configuring Plugin Parameters for Command Line Execution.
<plugin> <artifactId>maven-assembly-plugin</artifactId> <configuration> <appendAssemblyId>false</appendAssemblyId> </configuration> <executions> <execution> <id>assemble-binary</id> <phase>package</phase> <goals> <goal>single</goal> </goals> <configuration> <descriptors> <descriptor>src/main/assembly/bin.xml</descriptor> </descriptors> </configuration> </execution> <execution> <id>default-cli</id> <configuration> <descriptorRefs> <descriptorRef>jar-with-dependencies</descriptorRef> </descriptorRefs> </configuration> </execution> </executions> </plugin>
7.1.6. Setting Parameters for Goals Bound to Default Lifecycle
Starting with Maven 2.2.0, if you need to customize the behavior of a goal which is already bound to the default lifecycle, you can use the execution id "default-<goal>". You can customize the behavior of the Jar plugin’s jar goal which is bound to the package phase in the default lifecycle, and you can customize the configuration parameters of a separate goal execution if you follow the example shown in Setting a Parameter for a Default Goal Execution.
Setting a Parameter for a Default Goal Execution.
<plugin> <artifactId>maven-jar-plugin</artifactId> <executions> <execution> <id>default-jar</id> <configuration> <excludes> <exclude>**/somepackage/*</exclude> </excludes> </configuration> </execution> <execution> <id>special-jar</id> <phase>package</phase> <goals> <goal>jar</goal> </goals> <configuration> <includes> <include>**/sompackage/*</include> </includes> <classifier>somepackage</classifier> </configuration> </execution> </executions> </plugin>
In this example, the default jar goal is customized to exclude contents in a specific package. Another jar goal is bound to the package phase to create a JAR file which contains only the contents of a particular package in a classified JAR file.
Configuring the default goal execution parameters can also come in handy if you need to configure two goals bound to the default lifecycle with separate settings for the same configuration parameter. Setting Two Default Goal Plugin Configuration Parameters shows an example that configures the default resources:resources goal to exclude empty directories while configuring the default resources:testResources goal to include empty directories.
Setting Two Default Goal Plugin Configuration Parameters.
<plugin> <artifactId>maven-resources-plugin</artifactId> <executions> <execution> <id>default-resources</id> <configuration> <includeEmptyDirs>false</includeEmptyDirs> </configuration> </execution> <execution> <id>default-testResources</id> <configuration> <includeEmptyDirs>true</includeEmptyDirs> </configuration> </execution> </executions> </plugin>