Fork me on GitHub

exec:exec

Full name:

org.codehaus.mojo:exec-maven-plugin:3.4.1:exec

Description:

A Plugin for executing external programs.

Attributes:

  • Requires a Maven project to be executed.
  • Requires dependency resolution of artifacts in scope: test.
  • The goal is thread-safe and supports parallel builds.
  • Since version: 1.0.

Optional Parameters

Name Type Since Description
<addOutputToClasspath> boolean 1.5.1 Add project output directory to classpath. This might be undesirable when the exec plugin is run before the compile step. Default is true.
Default: true
User Property: addOutputToClasspath
<addResourcesToClasspath> boolean 1.5.1 Add project resource directories to classpath. This is especially useful if the exec plugin is used for a code generator that reads its settings from the classpath.
Default: false
User Property: addResourcesToClasspath
<arguments> List<?> 1.0

A list of arguments passed to the executable, which should be of type <argument> or <classpath>. Can be overridden by using the exec.args environment variable.

<async> boolean - If set to true the child process executes asynchronously and build execution continues in parallel.
Default: false
User Property: exec.async
<asyncDestroyOnShutdown> boolean - If set to true, the asynchronous child process is destroyed upon JVM shutdown. If set to false, asynchronous child process continues execution after JVM shutdown. Applies only to asynchronous processes; ignored for synchronous processes.
Default: true
User Property: exec.asyncDestroyOnShutdown
<classpathScope> String - Defines the scope of the classpath passed to the plugin.
  • runtime (default): Include "compile" and "runtime" scopes
  • compile: Include "compile", "provided", and "system" scopes
  • test: Include all scopes
  • provided: Include "compile", "runtime", "provided", and "system" scopes
  • system: Include "system" scope
Since 1.1.2, the default value is 'runtime' instead of 'compile'.
Default: runtime
User Property: exec.classpathScope
<commandlineArgs> String - Arguments separated by space for the executed program. For example: "-j 20"
User Property: exec.args
<environmentScript> File 1.4.0 Environment script to be merged with environmentVariables This script is platform specifics, on Unix its must be Bourne shell format. Use this feature if you have a need to create environment variable dynamically such as invoking Visual Studio environment script file
<environmentVariables> Map<String,String> 1.1-beta-2

Environment variables to pass to the executed program. For example if you want to set the LANG var: <environmentVariables> <LANG>en_US</LANG> </environmentVariables>

<executable> String 1.0

The executable. Can be a full path or the name of the executable. In the latter case, the executable must be in the PATH for the execution to work. Omit when using executableDependency.

The plugin will search for the executable in the following order:

  1. relative to the root of the project
  2. as toolchain executable
  3. relative to the working directory (Windows only)
  4. relative to the directories specified in the system property PATH (Windows Only)
Otherwise use the executable as is.


User Property: exec.executable
<executableDependency> ExecutableDependency 1.1-beta-1 If provided the ExecutableDependency identifies which of the plugin dependencies contains the executable class. This will have the effect of only including plugin dependencies required by the identified ExecutableDependency.

If includeProjectDependencies is set to true, all of the project dependencies will be included on the executable's classpath. Whether a particular project dependency is a dependency of the identified ExecutableDependency will be irrelevant to its inclusion in the classpath.

<forceJava> boolean 3.1.1 Forces the plugin to recognize the given executable as java executable. This helps with longClasspath and longModulepath parameters.

You shouldn't normally be needing this unless you renamed your java binary or are executing tools other than java which need modulepath or classpath parameters in a separate file.


Default: false
User Property: exec.forceJava
<includePluginDependencies> boolean 3.4.0 Indicates if this plugin's dependencies should be used when executing the main class.

This is useful when project dependencies are not appropriate. Using only the plugin dependencies can be particularly useful when the project is not a java project. For example a mvn project using the csharp plugins only expects to see dotnet libraries as dependencies.


Default: false
User Property: exec.includePluginsDependencies
<inheritIo> boolean 3.0.1 Program standard input, output and error streams will be inherited from the maven process. This allow tighter control of the streams and the console.
See also: ProcessBuilder.inheritIO()
User Property: exec.inheritIo
<longClasspath> boolean 1.1.2 If set to true the classpath and the main class will be written to a MANIFEST.MF file and wrapped into a jar. Instead of '-classpath/-cp CLASSPATH mainClass' the exec plugin executes '-jar maven-exec.jar'.
Default: false
User Property: exec.longClasspath
<longModulepath> boolean 1.1.2 If set to true the modulepath and the main class will be written as an @arg file Instead of '--module-path/-p MODULEPATH ' the exec plugin executes '@modulepath'.
Default: true
User Property: exec.longModulepath
<outputFile> File 1.1-beta-2 Program standard and error output will be redirected to the file specified by this optional field. If not specified the standard Maven logging is used.
Note: Be aware that System.out and System.err use buffering, so don't rely on the order!
See also: System.err, System.in
User Property: exec.outputFile
<quietLogs> boolean 3.0.0 When combined with exec.useMavenLogger=true, prints all executed program output at debug level instead of the default info level to the Maven logger.
Default: false
User Property: exec.quietLogs
<skip> boolean 1.0.1 Skip the execution. Starting with version 1.4.0 the former name skip has been changed into exec.skip.
Default: false
User Property: exec.skip
Alias: skip
<sourceRoot> File - This folder is added to the list of those folders containing source to be compiled. Use this if your plugin generates source code.
User Property: sourceRoot
<successCodes> int[] 1.1.1 Exit codes to be resolved as successful execution for non-compliant applications (applications not returning 0 for success).
<testSourceRoot> File - This folder is added to the list of those folders containing source to be compiled for testing. Use this if your plugin generates test source code.
User Property: testSourceRoot
<timeout> int 3.0.0

Timeout in full milliseconds, default is 0.

When set to a value larger than zero, the executable is forcefully terminated if it did not finish within this time, and the build will fail.


Default: 0
User Property: exec.timeout
<toolchain> String -

The toolchain. If omitted, "jdk" is assumed.


Default: jdk
User Property: exec.toolchain
<useMavenLogger> boolean 3.0.0 When enabled, program standard and error output will be redirected to the Maven logger as Info and Error level logs, respectively. If not enabled the traditional behavior of program output being directed to standard System.out and System.err is used.

NOTE: When enabled, to log the program standard out as Maven Debug level instead of Info level use exec.quietLogs=true.

This option can be extremely helpful when combined with multithreaded builds for two reasons:
  • Program output is suffixed with the owning thread name, making it easier to trace execution of a specific projects build thread.
  • Program output will not get jumbled with other maven log messages.
For Example, if using exec:exec to run a script to echo a count from 1 to 100 as:
for i in {1..100}
do
  echo "${project.artifactId} - $i"
done
When this script is run multi-threaded on two modules, module1 and module2, you might get output such as:
[BuilderThread 1] [INFO] --- exec-maven-plugin:1.6.0:exec (test) @ module1 ---
[BuilderThread 2] [INFO] --- exec-maven-plugin:1.6.0:exec (test) @ module2 ---
...
module2 - 98
modu
module1 - 97
module1 -
le2 - 9899
...
With this flag enabled, the output will instead come something similar to:
...
[Exec Stream Pumper] [INFO] [BuilderThread 2] module2 - 98
[Exec Stream Pumper] [INFO] [BuilderThread 1] module1 - 97
[Exec Stream Pumper] [INFO] [BuilderThread 1] module1 - 98
[Exec Stream Pumper] [INFO] [BuilderThread 2] module2 - 99
...
NOTE 1: To show the thread in the Maven log, configure the Maven installations conf/logging/simplelogger.properties option: org.slf4j.simpleLogger.showThreadName=true
NOTE 2: This option is ignored when exec.outputFile is specified.
See also: System.err, System.in
Default: false
User Property: exec.useMavenLogger
<workingDirectory> File 1.0 The current working directory. Optional. If not specified, basedir will be used.
User Property: exec.workingdir

Parameter Details

<addOutputToClasspath>

Add project output directory to classpath. This might be undesirable when the exec plugin is run before the compile step. Default is true.
  • Type: boolean
  • Since: 1.5.1
  • Required: No
  • User Property: addOutputToClasspath
  • Default: true

<addResourcesToClasspath>

Add project resource directories to classpath. This is especially useful if the exec plugin is used for a code generator that reads its settings from the classpath.
  • Type: boolean
  • Since: 1.5.1
  • Required: No
  • User Property: addResourcesToClasspath
  • Default: false

<arguments>

A list of arguments passed to the executable, which should be of type <argument> or <classpath>. Can be overridden by using the exec.args environment variable.

  • Type: java.util.List<?>
  • Since: 1.0
  • Required: No

<async>

If set to true the child process executes asynchronously and build execution continues in parallel.
  • Type: boolean
  • Required: No
  • User Property: exec.async
  • Default: false

<asyncDestroyOnShutdown>

If set to true, the asynchronous child process is destroyed upon JVM shutdown. If set to false, asynchronous child process continues execution after JVM shutdown. Applies only to asynchronous processes; ignored for synchronous processes.
  • Type: boolean
  • Required: No
  • User Property: exec.asyncDestroyOnShutdown
  • Default: true

<classpathScope>

Defines the scope of the classpath passed to the plugin.
  • runtime (default): Include "compile" and "runtime" scopes
  • compile: Include "compile", "provided", and "system" scopes
  • test: Include all scopes
  • provided: Include "compile", "runtime", "provided", and "system" scopes
  • system: Include "system" scope
Since 1.1.2, the default value is 'runtime' instead of 'compile'.
  • Type: java.lang.String
  • Required: No
  • User Property: exec.classpathScope
  • Default: runtime

<commandlineArgs>

Arguments separated by space for the executed program. For example: "-j 20"
  • Type: java.lang.String
  • Required: No
  • User Property: exec.args

<environmentScript>

Environment script to be merged with environmentVariables This script is platform specifics, on Unix its must be Bourne shell format. Use this feature if you have a need to create environment variable dynamically such as invoking Visual Studio environment script file
  • Type: java.io.File
  • Since: 1.4.0
  • Required: No

<environmentVariables>

Environment variables to pass to the executed program. For example if you want to set the LANG var: <environmentVariables> <LANG>en_US</LANG> </environmentVariables>

  • Type: java.util.Map<java.lang.String, java.lang.String>
  • Since: 1.1-beta-2
  • Required: No

<executable>

The executable. Can be a full path or the name of the executable. In the latter case, the executable must be in the PATH for the execution to work. Omit when using executableDependency.

The plugin will search for the executable in the following order:

  1. relative to the root of the project
  2. as toolchain executable
  3. relative to the working directory (Windows only)
  4. relative to the directories specified in the system property PATH (Windows Only)
Otherwise use the executable as is.

  • Type: java.lang.String
  • Since: 1.0
  • Required: No
  • User Property: exec.executable

<executableDependency>

If provided the ExecutableDependency identifies which of the plugin dependencies contains the executable class. This will have the effect of only including plugin dependencies required by the identified ExecutableDependency.

If includeProjectDependencies is set to true, all of the project dependencies will be included on the executable's classpath. Whether a particular project dependency is a dependency of the identified ExecutableDependency will be irrelevant to its inclusion in the classpath.

  • Type: org.codehaus.mojo.exec.ExecutableDependency
  • Since: 1.1-beta-1
  • Required: No

<forceJava>

Forces the plugin to recognize the given executable as java executable. This helps with longClasspath and longModulepath parameters.

You shouldn't normally be needing this unless you renamed your java binary or are executing tools other than java which need modulepath or classpath parameters in a separate file.

  • Type: boolean
  • Since: 3.1.1
  • Required: No
  • User Property: exec.forceJava
  • Default: false

<includePluginDependencies>

Indicates if this plugin's dependencies should be used when executing the main class.

This is useful when project dependencies are not appropriate. Using only the plugin dependencies can be particularly useful when the project is not a java project. For example a mvn project using the csharp plugins only expects to see dotnet libraries as dependencies.

  • Type: boolean
  • Since: 3.4.0
  • Required: No
  • User Property: exec.includePluginsDependencies
  • Default: false

<inheritIo>

Program standard input, output and error streams will be inherited from the maven process. This allow tighter control of the streams and the console.
See also: ProcessBuilder.inheritIO()
  • Type: boolean
  • Since: 3.0.1
  • Required: No
  • User Property: exec.inheritIo

<longClasspath>

If set to true the classpath and the main class will be written to a MANIFEST.MF file and wrapped into a jar. Instead of '-classpath/-cp CLASSPATH mainClass' the exec plugin executes '-jar maven-exec.jar'.
  • Type: boolean
  • Since: 1.1.2
  • Required: No
  • User Property: exec.longClasspath
  • Default: false

<longModulepath>

If set to true the modulepath and the main class will be written as an @arg file Instead of '--module-path/-p MODULEPATH ' the exec plugin executes '@modulepath'.
  • Type: boolean
  • Since: 1.1.2
  • Required: No
  • User Property: exec.longModulepath
  • Default: true

<outputFile>

Program standard and error output will be redirected to the file specified by this optional field. If not specified the standard Maven logging is used.
Note: Be aware that System.out and System.err use buffering, so don't rely on the order!
See also: System.err, System.in
  • Type: java.io.File
  • Since: 1.1-beta-2
  • Required: No
  • User Property: exec.outputFile

<quietLogs>

When combined with exec.useMavenLogger=true, prints all executed program output at debug level instead of the default info level to the Maven logger.
  • Type: boolean
  • Since: 3.0.0
  • Required: No
  • User Property: exec.quietLogs
  • Default: false

<skip>

Skip the execution. Starting with version 1.4.0 the former name skip has been changed into exec.skip.
  • Type: boolean
  • Since: 1.0.1
  • Required: No
  • User Property: exec.skip
  • Default: false
  • Alias: skip

<sourceRoot>

This folder is added to the list of those folders containing source to be compiled. Use this if your plugin generates source code.
  • Type: java.io.File
  • Required: No
  • User Property: sourceRoot

<successCodes>

Exit codes to be resolved as successful execution for non-compliant applications (applications not returning 0 for success).
  • Type: int[]
  • Since: 1.1.1
  • Required: No

<testSourceRoot>

This folder is added to the list of those folders containing source to be compiled for testing. Use this if your plugin generates test source code.
  • Type: java.io.File
  • Required: No
  • User Property: testSourceRoot

<timeout>

Timeout in full milliseconds, default is 0.

When set to a value larger than zero, the executable is forcefully terminated if it did not finish within this time, and the build will fail.

  • Type: int
  • Since: 3.0.0
  • Required: No
  • User Property: exec.timeout
  • Default: 0

<toolchain>

The toolchain. If omitted, "jdk" is assumed.

  • Type: java.lang.String
  • Required: No
  • User Property: exec.toolchain
  • Default: jdk

<useMavenLogger>

When enabled, program standard and error output will be redirected to the Maven logger as Info and Error level logs, respectively. If not enabled the traditional behavior of program output being directed to standard System.out and System.err is used.

NOTE: When enabled, to log the program standard out as Maven Debug level instead of Info level use exec.quietLogs=true.

This option can be extremely helpful when combined with multithreaded builds for two reasons:
  • Program output is suffixed with the owning thread name, making it easier to trace execution of a specific projects build thread.
  • Program output will not get jumbled with other maven log messages.
For Example, if using exec:exec to run a script to echo a count from 1 to 100 as:
for i in {1..100}
do
  echo "${project.artifactId} - $i"
done
When this script is run multi-threaded on two modules, module1 and module2, you might get output such as:
[BuilderThread 1] [INFO] --- exec-maven-plugin:1.6.0:exec (test) @ module1 ---
[BuilderThread 2] [INFO] --- exec-maven-plugin:1.6.0:exec (test) @ module2 ---
...
module2 - 98
modu
module1 - 97
module1 -
le2 - 9899
...
With this flag enabled, the output will instead come something similar to:
...
[Exec Stream Pumper] [INFO] [BuilderThread 2] module2 - 98
[Exec Stream Pumper] [INFO] [BuilderThread 1] module1 - 97
[Exec Stream Pumper] [INFO] [BuilderThread 1] module1 - 98
[Exec Stream Pumper] [INFO] [BuilderThread 2] module2 - 99
...
NOTE 1: To show the thread in the Maven log, configure the Maven installations conf/logging/simplelogger.properties option: org.slf4j.simpleLogger.showThreadName=true
NOTE 2: This option is ignored when exec.outputFile is specified.
See also: System.err, System.in
  • Type: boolean
  • Since: 3.0.0
  • Required: No
  • User Property: exec.useMavenLogger
  • Default: false

<workingDirectory>

The current working directory. Optional. If not specified, basedir will be used.
  • Type: java.io.File
  • Since: 1.0
  • Required: No
  • User Property: exec.workingdir