 ------
 Usage
 ------
 Jerome Lacoste
 ------
 2008-10-10
 ------

 ~~ Copyright 2006 The Codehaus
 ~~
 ~~ Licensed under the Apache License, Version 2.0 (the "License");
 ~~ you may not use this file except in compliance with the License.
 ~~ You may obtain a copy of the License at
 ~~
 ~~      http://www.apache.org/licenses/LICENSE-2.0
 ~~
 ~~ Unless required by applicable law or agreed to in writing, software
 ~~ distributed under the License is distributed on an "AS IS" BASIS,
 ~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 ~~ See the License for the specific language governing permissions and
 ~~ limitations under the License.

 ~~ NOTE: For help with the syntax of this file, see:
 ~~ http://maven.apache.org/doxia/references/apt-format.html

Usage

* Exec goal

 You can formally specify all the relevant execution information in the plugin configuration.
 Depending on your use case, you can also specify some or all information using system properties.

** Command line

 Using system properties you would just execute it like in the following example.

-----
mvn exec:exec -Dexec.executable="maven" [-Dexec.workingdir="/tmp"] -Dexec.args="-X myproject:dist"
-----

** POM Configuration

 Add a configuration similar to the following to your POM:

-------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            ...
            <goals>
              <goal>exec</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <executable>maven</executable>
          <!-- optional -->
          <workingDirectory>/tmp</workingDirectory>
          <arguments>
            <argument>-X</argument>
            <argument>myproject:dist</argument>
            ...
          </arguments>
          <environmentVariables>
            <LANG>en_US</LANG>
          </environmentVariables>
        </configuration>
      </plugin>
    </plugins>
  </build>
   ...
</project>
-------------------

* Java goal

  This goal helps you run a Java program within the same VM as Maven.

** Differences compared to plain command line

  The goal goes to great length to try to mimic the way the VM works, but there are some subtle differences.
  Today all differences come from the way the goal deals with <<thread management>>.

*--------------------------------------+------------------------------------------+
|                command line          |           Java Mojo                      |
*--------------------------------------+------------------------------------------+
| The VM exits as soon as the only     |  By default daemon threads are joined    |
| remaining threads are daemon threads | and interrupted once all known non       |
|                                      | daemon threads have quit. The join    |
|                                      | timeout is customisable                  |
|                                      | The user might wish to further   |
|                                      | cleanup by stopping the unresponsive     |
|                                      | threads.                                 |
|                                      | The user can disable the full extra      |
|                                      | thread management (interrupt/join/[stop])|
*--------------------------------------+------------------------------------------+

  Read the documentation for the {{{./java-mojo.html}java goal}} for more information on how to configure this behavior.

  If you find out that these differences are unacceptable for your case, you may need to use the {{{./exec-mojo.html} exec goal}} to wrap your Java executable.

** Command line

  If you want to execute Java programs in the same VM, you can either use the command line version

-----
mvn exec:java -Dexec.mainClass="com.example.Main" [-Dexec.args="argument1"] ...
-----

** POM Configuration

  or you can configure the plugin in your POM:

-------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            ...
            <goals>
              <goal>java</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <mainClass>com.example.Main</mainClass>
          <arguments>
            <argument>argument1</argument>
            ...
          </arguments>
          <systemProperties>
            <systemProperty>
              <key>myproperty</key>
              <value>myvalue</value>
            </systemProperty>
            ...
          </systemProperties>
        </configuration>
      </plugin>
    </plugins>
  </build>
   ...
</project>
-------------------

  <<Note:>> The <<<java>>> goal doesn't spawn a new process. Any VM specific option that you want to pass to the executed class must be passed to the Maven VM using
  the <<<MAVEN_OPTS>>> environment variable.
  E.g.

-------------------
MAVEN_OPTS=-Xmx1024m
-------------------

  Otherwise consider using the <<<exec>>> goal.
