Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

Excerpt

GMaven has kick-ass support for compiling Groovy projects with Maven!

Table of Contents
maxLevel2
minLevel1

Project Structure

Groovy projects are structured based on the Maven standard, notably adding the groovy sub-directory to the main and test source collections:

No Format
<project-root>/
  |
  +- pom.xml
  |
  +- src/
  |  |
  |  +- main/
  |  |  |
  |  |  +- groovy/ (source location for Groovy and optional Java sources)
  |  |  |
  |  +- test/
  |  |  |
  |  |  +- groovy/ (source location for Groovy and optional Java test sources)
  |  |  |
  ...

gmaven-archetype-basic Archetype

To help get Groovy projects started faster, you can use the gmaven-archetype-basic. This will create a new project with the basic POM configuration and some example classes to get you started quickly:

No Format
mvn archetype:generate -DarchetypeGroupId=org.codehaus.gmaven.archetypes -DarchetypeArtifactId=gmaven-archetype-basic -DarchetypeVersion=<VERSION>
Tip
titleTIP

Remember to specify archetypeVersion, otherwise mvn will prompt you for the archetype. To use a specific version of an archetype specify -DarchetypeVersion=<VERSION>.


Tip
titleTIP

If the command above does not work, it is likely that you have an outdated version of the archetype plugin in your local repository. Add "-U" to the mvn call in order to force updates.

The Maven Archetype Plugin will ask a few questions about your new project:

No Format
[INFO] [archetype:generate]
...
Define value for groupId: : org.mycompany.myproject
Define value for artifactId: : example-project
Define value for version: : 1.0-SNAPSHOT
Define value for package: : org.mycompany.myproject.example
Confirm properties configuration:
name: Example Project
groupId: org.mycompany.myproject
artifactId: example-project
version: 1.0-SNAPSHOT
package: org.mycompany.myproject.example
 Y: : y
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
...
Note
titleNOTE

Please ignore any ReferenceException warnings about ${...}, they are harmless.

The above example would have created the following project structure:

No Format
example-project
example-project/pom.xml
example-project/src
example-project/src/main
example-project/src/main/groovy
example-project/src/main/groovy/org
example-project/src/main/groovy/org/mycompany
example-project/src/main/groovy/org/mycompany/myproject
example-project/src/main/groovy/org/mycompany/myproject/example
example-project/src/main/groovy/org/mycompany/myproject/example/Example.groovy
example-project/src/main/groovy/org/mycompany/myproject/example/Helper.java
example-project/src/test
example-project/src/test/groovy
example-project/src/test/groovy/org
example-project/src/test/groovy/org/mycompany
example-project/src/test/groovy/org/mycompany/myproject
example-project/src/test/groovy/org/mycompany/myproject/example
example-project/src/test/groovy/org/mycompany/myproject/example/ExampleTest.groovy
example-project/src/test/groovy/org/mycompany/myproject/example/HelperTest.groovy

Compiling Sources

GMaven provides support to compile Groovy sources, which includes joint Java/Groovy compilation via stub-generation.

To enable compilation features configure the gmaven-plugin execute the stub-generation and compilation goals in your projects POM and define a dependency on the Groovy runtime your project requires (using the default version in this example:

Code Block
<dependencies>
    <dependency>
        <groupId>org.codehaus.gmaven.runtime</groupId>
        <artifactId>gmaven-runtime-default</artifactId>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.codehaus.gmaven</groupId>
            <artifactId>gmaven-plugin</artifactId>
            <executions>
                <execution>
                    <goals>
                        <goal>generateStubs</goal>
                        <goal>compile</goal>
                        <goal>generateTestStubs</goal>
                        <goal>testCompile</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Source Selection

By default, all *.groovy files under src/main/groovy will be compiled into target/classes and all *.groovy files under src/test/groovy will be compiled into target/test-classes.

To use a more specific list of sources, specify one or more source filesets. When sources is specified the default location is not automatically included:

Code Block
<plugin>
    <groupId>org.codehaus.gmaven</groupId>
    <artifactId>gmaven-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>compile</goal>
            </goals>
            <configuration>
                <sources>
                    <fileset>
                        <directory>${pom.basedir}/src/main/script</directory>
                        <includes>
                            <include>**/*.groovy</include>
                        </includes>
                    </fileset>
                </sources>
            </configuration>
        </execution>
    </executions>
</plugin>

Compilation Flags

Many of the options available in the Groovy compiler configuration can also be set:

Code Block
<plugin>
    <groupId>org.codehaus.gmaven</groupId>
    <artifactId>gmaven-plugin</artifactId>
    <configuration>
        <debug>false</debug>
        <verbose>true</verbose>
        <stacktrace>true</stacktrace>
        <defaultScriptExtension>.groovy</defaultScriptExtension>
    </configuration>
</plugin>

For the full reference of available flags please see the plugin documentation for the groovy:compile goal.

Stub-Generation

Stub-generation creates minimal Java sources for each Groovy class preserving the class structure and Javadocs, but omitting implementation detail. This allows the standard Maven Compiler Plugin to be used to compile Java sources which have a dependency upon Groovy sources with out any additional POM configuration or magical hacks.

Stub class files are used for resolving classes at compile-time, at runtime the compiled Groovy classes will be used instead.

Stub source files are used for generating API documentation via the standard Maven Javadoc Plugin, other plugins which operate on source files (ex. Maven JXR Plugin) will also utilize these generated source files for reports.

Running Tests

Test execution works just like any normal Maven project using the Maven Surefire Plugin. Using the testCompile goal, the GMaven plugin will compile Groovy sources into Java class files, which the Surefire plugin will execute just like any other Java class.

Be sure to configure your project's to depend on the required Groovy runtime and the desired unit-testing library (using junit3 in this example):

Code Block
<dependencies>
    <dependency>
        <groupId>org.codehaus.gmaven.runtime</groupId>
        <artifactId>gmaven-runtime-default</artifactId>
        <scope>test</scope>
    </dependency>

    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

Non-Groovy projects can still make use of Groovy for testing... which can make for less verbose test classes (smile)

groovy-jar Packaging

Note
titleTODO

TODO

Resources

Goal Documentation