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.
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.
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.
<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>
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.
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.5</source>
<target>1.5</target>
</configuration>
</plugin>
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.
<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>
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.
<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>
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.
<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.
<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>