<commit_before>[#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

The plugin accepts the following options:

[cols="d,a,3*a", options="header"]
|===
|Name|Property|Description|Default|Used by

|`bundleDependencies`
|`swarm.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.
|true
|`package`

|`debug`
|_none_
|The port to use for debugging. If set, the swarm process will suspend on start and open a debugger on this port.
|
|`run`, `start`

|`environment`
|_none_
|A properties-style list of environment variables to use when executing the application.
|
|`multistart`, `run`, `start`

|`environmentFile`
|`swarm.environmentFile`
|A `.properties` file with environment variables to use when executing the application.
|
|`multistart`, `run`, `start`

|`fractionDetectMode`
|`swarm.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.
|`when_missing`
|`package`, `run`, `start`

|`fractions`
|_none_
|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.
|
|`package`, `run`, `start`

ifndef::product[]
|`hollow`
|`swarm.hollow`
|Specifies if the resulting executable JAR should be hollow, and therefore not include the default deployment.
|`false`
|`package`
endif::[]

|`jvmArguments`
|`swarm.jvmArguments`
|A list of `<jvmArgument>` elements specifying additional JVM arguments (such as `-Xmx32m`).
|
|`multistart`, `run`, `start`

|`modules`
|_none_
|Paths to a directory containing additional module definitions.
|./modules
|`package`, `run`, `start`

|`processes`
|_none_
|Application configurations to start (see xref:maven-plugin-multistart-goal[multistart]).
|
|`multistart`

|`properties`
|_none_
|See xref:maven-plugin-properties[].
|
|`package`, `run`, `start`

|`propertiesFile`
|`swarm.propertiesFile`
|See xref:maven-plugin-properties[].
|
|`package`, `run`, `start`

|`stderrFile`
|`swarm.stderr`
|A file path where to store the `stderr` output instead of sending it to the `stderr` output of the launching process.
|
|`run`, `start`

|`stdoutFile`
|`swarm.stdout`
|A file path where to store the `stdout` output instead of sending it to the `stdout` output of the launching process.
|
|`run`, `start`

|`useUberJar`
|`swarm.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.
|false
|`run`, `start`
|===

[#maven-plugin-properties]
=== 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>`.
<commit_msg>Reformatted Maven plugin options table (#748)<commit_after>[#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
|_none_

|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.fractionDetectMode`

|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
|`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>`.

{'fraction_non_alphanumeric': 0.12090909090909091, 'fraction_numerical': 0.003305785123966942, 'mean_word_length': 5.108531044926805, 'pattern_counts': {'":': 0, '<': 49, '<?xml version=': 0, '>': 49, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 4}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5264295', 'n_tokens_mistral': 3855, 'n_tokens_neox': 3686, 'n_words': 1454}