Skip to content

Usage

Jump to bottom
Keegan Witt edited this page Sep 29, 2023 · 50 revisions

The two most popular use cases for GMavenPlus are executing Groovy scripts and compiling Groovy sources. However, there are other usages available. Such as generating GroovyDoc, and launching a Groovy shell or console bound to a Maven project, which you can read about on our examples page.

Executing a Groovy script

You may choose to bind your execution to any phase you wish. In this example, it is not bound to any phase and must be called explicitly like this

mvn gplus:execute

Configuring GMavenPlus

<project>
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.gmavenplus</groupId>
        <artifactId>gmavenplus-plugin</artifactId>
        <version>3.0.2</version>
        <executions>
          <execution>
            <goals>
              <goal>execute</goal>
            </goals>
          </execution>
        </executions>
      <configuration>
        <scripts>
          <script><![CDATA[
            // your script here
          ]]></script>
        </scripts>
      </configuration>
      <dependencies>
        <dependency>
          <groupId>org.apache.groovy</groupId>
          <artifactId>groovy</artifactId>
          <version>4.0.15</version>
          <scope>runtime</scope>
        </dependency>
      </dependencies>
    </plugin>
  </plugins>
  </build>
</project>

More advanced usages can be found on our examples page.

Compiling Groovy sources

The compilation goals (including those for joint compilation) for GMavenPlus are bound to their respective phases in the build lifecycle. So to compile your sources, you need only tell maven how much of the lifecycle to execute. The following will compile your sources:

mvn compile

To compile your test sources, you'll do:

mvn test-compile

The above command will execute both compiler:compile and compiler:testCompile since the compile phase happens a few phases before the test-compile phase.

Configuring GMavenPlus

<project>
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.gmavenplus</groupId>
        <artifactId>gmavenplus-plugin</artifactId>
        <version>3.0.2</version>
        <executions>
          <execution>
            <goals>
              <goal>addSources</goal>
              <goal>addTestSources</goal>
              <goal>generateStubs</goal>
              <goal>compile</goal>
              <goal>generateTestStubs</goal>
              <goal>compileTests</goal>
              <goal>removeStubs</goal>
              <goal>removeTestStubs</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.8.1</version>
      </plugin>
      <plugin>
        <!-- if including source jars, use the no-fork goals
             otherwise both the Groovy sources and Java stub sources
             will get included in your jar -->
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-source-plugin</artifactId>
        <!-- source plugin \> = 2.1 is required to use the no-fork goals -->
        <version>3.2.1</version>
        <executions>
          <execution>
            <id>attach-sources</id>
            <goals>
              <goal>jar-no-fork</goal>
              <goal>test-jar-no-fork</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  <dependencies>
    <dependency>
      <groupId>org.apache.groovy</groupId>
      <artifactId>groovy</artifactId>
      <version>4.0.15</version>
    </dependency>
  </dependencies>
</project>

More advanced usages can be found on our examples page.

Why do I need so many goals?

Because we need to mix Groovy and Java lifecycles together. The only other way to do this is a with a custom lifecycle. This seemed inappropriate since you have to introduce a new type (which both GMaven and GMavenPlus did at one time as groovy-jar). But what if you are mixing Groovy, Java, and another language (maybe Scala)? We'd have to define types for all the combinations. It also seemed inappropriate that consumers of your artifact should be aware of the fact it was written in another language.

Here's how those goals map to the sequence of actions GMavenPlus takes

  1. Add the Groovy source sources to Maven's main sources (because addSources was requested). This is useful for when you want to make a source jar. If you have no main Groovy code, you can omit this.
  2. Add the Groovy test sources to Maven's test sources (addTestSources was requested). This is useful for when you want to make a test source jar. If you have no test Groovy code, you can omit this.
  3. Generate Java stubs for main Groovy code (because generateStubs was requested). These are then added to Maven's main sources for the Compiler plugin to use so Java can compile against them. If you have no main Groovy code or are not mixing Groovy with Java or creating Groovydoc, you can omit this.

  4. At this point in the execution, the Compiler plugin will compile the main Java code (including the generated main Java stubs if applicable).

  5. Compile the main Groovy code (because compile was requested). If you have no main Groovy code, you can omit this.
  6. Remove the main stubs from Maven's main sources (because removeStubs was requested). This can be done because stubs are only needed until Java is compiled. If you don't run this step, the stubs will be included in the main source jar (if created). If you didn't request generateStubs, you can omit this.
  7. Generate Java stubs for test Groovy code (because generateTestStubs was requested). These are then added to Maven's test sources for the Compiler plugin to use so Java can compile against them. If you have no test Groovy code or are not mixing Groovy with Java or creating Groovydoc, you can omit this.

  8. At this point in the execution, the Compiler plugin will compile the test Java code (including the generated test Java stubs if applicable).

  9. Compile the test Groovy code (because compileTests was requested). If you have no test Groovy code, you can omit this.
  10. Remove the test stubs from Maven's test sources (because removeTestStubs was requested). This can be done because stubs are only needed until Java is compiled. If you don't run this step, the stubs will be included in the test source jar (if created). If you didn't request generateTestStubs, you can omit this.
Clone this wiki locally