5.7 Ant and Maven - Reference Documentation
Authors: Graeme Rocher, Peter Ledbrook, Marc Palmer, Jeff Brown, Luke Daley, Burt Beckwith, Lari Hotari
Version: 2.3.8
5.7 Ant and Maven
If all the other projects in your team or company are built using a standard build tool such as Ant or Maven, you become the black sheep of the family when you use the Grails command line to build your application. Fortunately, you can easily integrate the Grails build system into the main build tools in use today (well, the ones in use in Java projects at least).Ant Integration
When you create a Grails application with the create-app command, Grails doesn't automatically create an Antbuild.xml
file but you can generate one with the integrate-with command:
grails integrate-with --ant
This creates a build.xml
file containing the following targets:
clean
- Cleans the Grails applicationcompile
- Compiles your application's source codetest
- Runs the unit testsrun
- Equivalent to "grails run-app"war
- Creates a WAR filedeploy
- Empty by default, but can be used to implement automatic deployment
ant war
<taskdef name="grailsTask" classname="grails.ant.GrailsTask" classpathref="grails.classpath"/>
Attribute | Description | Required |
---|---|---|
home | The location of the Grails installation directory to use for the build. | Yes, unless classpath is specified. |
classpathref | Classpath to load Grails from. Must include the "grails-bootstrap" artifact and should include "grails-scripts". | Yes, unless home is set or you use a classpath element. |
script | The name of the Grails script to run, e.g. "TestApp". | Yes. |
args | The arguments to pass to the script, e.g. "-unit -xml". | No. Defaults to "". |
environment | The Grails environment to run the script in. | No. Defaults to the script default. |
includeRuntimeClasspath | Advanced setting: adds the application's runtime classpath to the build classpath if true. | No. Defaults to true . |
classpath
- The build classpath (used to load Gant and the Grails scripts).compileClasspath
- Classpath used to compile the application's classes.runtimeClasspath
- Classpath used to run the application and package the WAR. Typically includes everything in @compileClasspath.testClasspath
- Classpath used to compile and run the tests. Typically includes everything inruntimeClasspath
.
home
attribute and put your own dependencies in the lib
directory, then you don't even need to use any of them. For an example of their use, take a look at the generated Ant build file for new apps.Maven Integration
Grails provides integration with Maven 2 with a Maven plugin.Preparation
In order to use the Maven plugin, all you need is Maven 2 installed and set up. This is because you no longer need to install Grails separately to use it with Maven!The Maven 2 integration for Grails has been designed and tested for Maven 2.0.9 and above. It will not work with earlier versions.
The default mvn setup DOES NOT supply sufficient memory to run the Grails environment. We recommend that you add the following environment variable setting to prevent poor performance:export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=256"
Creating a Grails Maven Project
Using thecreate-pom
command you can generate a valid Maven pom.xml
file for any existing Grails project. The below presents an example:$ grails create-app myapp $ cd myapp $ grails create-pom com.mycompany
create-pom
command expects a group id as an argument. The name and the version are taken from the application.properties
of the application. The Maven plugin will keep the version in the pom.xml
in sync with the version in application.properties
.The following standard Maven commands are then possible:
compile
- Compiles a Grails projectpackage
- Builds a WAR file from the Grails project.install
- Builds a WAR file (or plugin zip/jar if a plugin) and installs it into your local Maven cachetest
- Runs the tests of a Grails projectclean
- Cleans the Grails project
grails:create-controller
- Calls the create-controller commandgrails:create-domain-class
- Calls the create-domain-class commandgrails:create-integration-test
- Calls the create-integration-test commandgrails:create-pom
- Creates a new Maven POM for an existing Grails projectgrails:create-script
- Calls the create-script commandgrails:create-service
- Calls the create-service commandgrails:create-taglib
- Calls the create-tag-lib commandgrails:create-unit-test
- Calls the create-unit-test commandgrails:exec
- Executes an arbitrary Grails command line scriptgrails:generate-all
- Calls the generate-all commandgrails:generate-controller
- Calls the generate-controller commandgrails:generate-views
- Calls the generate-views commandgrails:install-templates
- Calls the install-templates commandgrails:list-plugins
- Calls the list-plugins commandgrails:package
- Calls the package commandgrails:run-app
- Calls the run-app command
mvn grails:help
Creating a Grails Maven Project using the Archetype
You can create a Maven Grails project without having Grails installed, simply run the following command:mvn archetype:generate -DarchetypeGroupId=org.grails \ -DarchetypeArtifactId=grails-maven-archetype \ -DarchetypeVersion=2.1.0.RC1 \ -DgroupId=example -DartifactId=my-app
<plugin> <artifactId>maven-compiler-plugin</artifactId> <configuration> <source>1.5</source> <target>1.5</target> </configuration> </plugin>
<plugin> <artifactId>maven-compiler-plugin</artifactId> <configuration> <source>1.6</source> <target>1.6</target> </configuration> </plugin>
cd my-app mvn initialize
Defining Plugin Dependencies
All Grails plugins are published to a standard Maven repository located at . When using the Maven plugin for Grails you must ensure that this repository is declared in your list of remote repositories:<repository> <id>grails-plugins</id> <name>grails-plugins</name> <url>http://repo.grails.org/grails/plugins</url> </repository>
pom.xml
file:<dependency> <groupId>org.grails.plugins</groupId> <artifactId>database-migration</artifactId> <version>1.1</version> <scope>runtime</scope> <type>zip</type> </dependency>
type
element must be set to zip
.Forked Grails Execution
By default the Maven plugin will run Grails commands in-process, meaning that the Grails process occupies the same JVM as the Maven process. This can put strain on the Maven process for particularly large applications.In this case it is recommended to use forked execution. Forked execution can be configured in theconfiguration
element of the plugin:<plugin> <groupId>org.grails</groupId> <artifactId>grails-maven-plugin</artifactId> <version>${grails.version}</version> <configuration> <!-- Whether for Fork a JVM to run Grails commands --> <fork>true</fork> </configuration> <extensions>true</extensions> </plugin>
forkDebug
element:<!-- Whether for Fork a JVM to run Grails commands --> <fork>true</fork> <forkDebug>true</forkDebug>
forkMaxMemory
- The maximum amount of heap (default 1024)forkMinMemory
- The minimum amount of heap (default 512)forkPermGen
- The amount of permgen (default 256)
Multi Module Maven Builds
The Maven plugin can be used to power multi-module Grails builds. The easiest way to set this is up is with thecreate-multi-project-build
command:$ grails create-app myapp $ grails create-plugin plugin1 $ grails create-plugin plugin2 $ grails create-multi-project-build org.mycompany:parent:1.0
mvn install
will build all projects together. To enable the 'grails' command to read the POMs you can modify BuildConfig.groovy
to use the POM and resolve dependencies from your Maven local cache:grails.project.dependency.resolution = {
…
pom true
repositories {
…
mavenLocal()
}
}
pom.xml
file you can do an initial mvn install
from the parent project to build all plugins and install them into your local maven cache and then cd
into your project and use the regular grails run-app
command to run your application. All previously built plugins will be resolved from the local Maven cache.Adding Grails commands to phases
The standard POM created for you by Grails already attaches the appropriate core Grails commands to their corresponding build phases, so "compile" goes in the "compile" phase and "war" goes in the "package" phase. That doesn't help though when you want to attach a plugin's command to a particular phase. The classic example is functional tests. How do you make sure that your functional tests (using which ever plugin you have decided on) are run during the "integration-test" phase?Fear not: all things are possible. In this case, you can associate the command to a phase using an extra "execution" block:<plugin> <groupId>org.grails</groupId> <artifactId>grails-maven-plugin</artifactId> <version>2.1.0.RC2</version> <extensions>true</extensions> <executions> <execution> <goals> … </goals> </execution> <!-- Add the "functional-tests" command to the "integration-test" phase --> <execution> <id>functional-tests</id> <phase>integration-test</phase> <goals> <goal>exec</goal> </goals> <configuration> <command>functional-tests</command> </configuration> </execution> </executions> </plugin>
grails:exec
goal, which can be used to run any Grails command. Simply pass the name of the command as the command
system property, and optionally specify the arguments with the args
property:mvn grails:exec -Dcommand=create-webtest -Dargs=Book
Debugging a Grails Maven Project
Maven can be launched in debug mode using the "mvnDebug" command. To launch your Grails application in debug, simply run:mvnDebug grails:run-app
MAVEN_OPTS="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005"
mvn grails:run-app