[#maven-plugin]
= Maven Plugin

WildFly Swarm provides a Maven plugin to accomplish most of the work of building xref:uberjar[uberjar] packages.

.General Usage

The WildFly Swarm Maven plugin is used like any other Maven plugin, that is through editing the `pom.xml` file in your application and adding a `<plugin>` section:

[source,xml]
----
<plugin>
  <groupId>org.wildfly.swarm</groupId>
  <artifactId>wildfly-swarm-plugin</artifactId>
  <version>${version.wildfly-swarm}</version>
  <executions>
    ...
    <configuration>
      ...
    <configuration/>
  </executions>
</plugin>
----

== Goals

The WildFly Swarm Maven plugin provides several goals:

package::
Creates the executable package (see xref:creating-an-uberjar[]).

run::
Executes your application in the Maven process. The application is stopped if the Maven build is interrupted, for example when you press Ctrl + C.

[#maven-plugin-multistart-goal]
start and multistart::
Executes your application in a forked process. Generally, it is only useful for running integration tests using a plugin, such as the `maven-failsafe-plugin`.
The `multistart` variant allows starting multiple WildFly Swarm{ndash}built applications using Maven GAVs to support complex testing scenarios.

stop::
Stops any previously started applications.
+
NOTE: The `stop` goal can only stop applications that were started _in the same Maven execution_.

[#maven-plugin-configuration]
== Configuration Options

The plugin accepts the following options:

bundleDependencies::
If true, dependencies will be included in the `-swarm.jar` file.
Otherwise, they will be resolved from `$M2_REPO` or the network at runtime.
+
[cols="1,2a"]
|===
|Property
|`swarm.bundleDependencies`

|Default
|true

|Used by
|`package`
|===

debug::
The port to use for debugging.
If set, the swarm process will suspend on start and open a debugger on this port.
+
[cols="1,2a"]
|===
|Property
|`swarm.debug.port`

|Default
|

|Used by
|`run`, `start`
|===

environment::
A properties-style list of environment variables to use when executing the application.
+
[cols="1,2a"]
|===
|Property
|_none_

|Default
|

|Used by
|`multistart`, `run`, `start`
|===

environmentFile::
A `.properties` file with environment variables to use when executing the application.
+
[cols="1,2a"]
|===
|Property
|`swarm.environmentFile`

|Default
|

|Used by
|`multistart`, `run`, `start`
|===

fractionDetectMode::
+
--
The mode of fraction detection. The available options are:

* `when_missing`: Runs only when no WildFly Swarm dependencies are found.
* `force`: Always run, and merge any detected fractions with the existing dependencies. Existing dependencies take precedence.
* `never`: Disable fraction detection.

[cols="1,2a"]
|===
|Property
|`swarm.detect.mode`

|Default
|`when_missing`

|Used by
|`package`, `run`, `start`
|===
--

fractions::
+
--
A list of extra fractions to include when auto-detection is used. It is useful for fractions that cannot be detected or user-provided fractions.

The format of specifying a fraction can be:
* `group:name:version`
* `name:version`
* `name`

If no group is provided, `org.wildfly.swarm` is assumed.

If no version is provided, the version is taken from the WildFly Swarm BOM for the version of the plugin you are using.

[cols="1,2a"]
|===
|Property
|_none_

|Default
|

|Used by
|`package`, `run`, `start`
|===
--

ifndef::product[]
hollow::
Specifies if the resulting executable JAR should be hollow, and therefore not include the default deployment.
+
[cols="1,2a"]
|===
|Property
|`swarm.hollow`

|Default
|`false`

|Used by
|`package`
|===
endif::[]

jvmArguments::
A list of `<jvmArgument>` elements specifying additional JVM arguments (such as `-Xmx32m`).
+
[cols="1,2a"]
|===
|Property
|`swarm.jvmArguments`

|Default
|

|Used by
|`multistart`, `run`, `start`
|===

modules::
Paths to a directory containing additional module definitions.
+
[cols="1,2a"]
|===
|Property
|_none_

|Default
|./modules

|Used by
|`package`, `run`, `start`
|===

processes::
Application configurations to start (see xref:maven-plugin-multistart-goal[multistart]).
+
[cols="1,2a"]
|===
|Property
|_none_

|Default
|

|Used by
|`multistart`
|===

properties::
See xref:maven-plugin-properties[].
+
[cols="1,2a"]
|===
|Property
|_none_

|Default
|

|Used by
|`package`, `run`, `start`
|===

propertiesFile::
See xref:maven-plugin-properties[].
+
[cols="1,2a"]
|===
|Property
|`swarm.propertiesFile`

|Default
|

|Used by
|`package`, `run`, `start`
|===

stderrFile::
A file path where to store the `stderr` output instead of sending it to the `stderr` output of the launching process.
+
[cols="1,2a"]
|===
|Property
|`swarm.stderr`

|Default
|

|Used by
|`run`, `start`
|===

stdoutFile::
A file path where to store the `stdout` output instead of sending it to the `stdout` output of the launching process.
+
[cols="1,2a"]
|===
|Property
|`swarm.stdout`

|Default
|

|Used by
|`run`, `start`
|===

useUberJar::
If true, the `-swarm.jar` file specified at `${project.build.directory}` is used.
This JAR is not created automatically, so make sure you execute the `package` goal first.
+
[cols="1,2a"]
|===
|Property
|`wildfly-swarm.useUberJar`

|Default
|false

|Used by
|`run`, `start`
|===

[#maven-plugin-properties]
== Configuration Properties

Properties can be used to configure execution and affect the packaging
or running of your application.

If you add a `<properties>` or `<propertiesFile>` section to the `<configuration>` of the plugin, the properties are used when executing your application using the `mvn wildfly-swarm:run` command.
In addition to that, the same properties are added to your `_myapp_-swarm.jar` file to affect subsequent executions of the uberjar.
Any properties loaded from the `<propertiesFile>` override identically-named properties in the `<properties>` section.

Any properties added to the uberjar can be overridden at runtime using the traditional `-Dname=value` mechanism of the `java` binary, or using the YAML-based configuration files.

Only the following properties are added to the uberjar at package time:

* The properties specified outside of the `<properties>` section or the `<propertiesFile>`, whose path starts with one of the following:
** `jboss.`
** `wildfly.`
** `swarm.`
** `maven.`
* The properties that override a property specified in the `<properties>` section or the `<propertiesFile>`.

