Skip to content

Commit

Permalink
updated Maven plugin docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@graemerocher
graemerocher committed May 21, 2014
1 parent 87385cb commit 1f5fd85
Show file tree
Hide file tree
Showing 2 changed files with 86 additions and 122 deletions.
202 changes: 80 additions & 122 deletions src/en/guide/commandLine/antAndMaven.gdoc
View file
@@ -1,73 +1,18 @@
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).

h3. Ant Integration

When you create a Grails application with the [create-app|commandLine] command, Grails doesn't automatically create an Ant @build.xml@ file but you can generate one with the [integrate-with|commandLine] command:

bc.
grails integrate-with --ant

This creates a @build.xml@ file containing the following targets:

* @clean@ - Cleans the Grails application
* @compile@ - Compiles your application's source code
* @test@ - Runs the unit tests
* @run@ - Equivalent to "grails run-app"
* @war@ - Creates a WAR file
* @deploy@ - Empty by default, but can be used to implement automatic deployment

Each of these can be run by Ant, for example:

{code:java}
ant war
{code}

The build file is configured to use "Apache Ivy":http://ant.apache.org/ivy/ for dependency management, which means that it will automatically download all the requisite Grails JAR files and other dependencies on demand. You don't even have to install Grails locally to use it! That makes it particularly useful for continuous integration systems such as [CruiseControl|http://cruisecontrol.sourceforge.net/] or [Jenkins|http://jenkins-ci.org/].

It uses the Grails [Ant task|api:grails.ant.GrailsTask] to hook into the existing Grails build system. The task lets you run any Grails script that's available, not just the ones used by the generated build file. To use the task, you must first declare it:
{code}
<taskdef name="grailsTask"
classname="grails.ant.GrailsTask"
classpathref="grails.classpath"/>
{code}

This raises the question: what should be in "grails.classpath"? The task itself is in the "grails-bootstrap" JAR artifact, so that needs to be on the classpath at least. You should also include the "groovy-all" JAR. With the task defined, you just need to use it! The following table shows you what attributes are available:
{table}
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@.
{table}

The task also supports the following nested elements, all of which are standard Ant path structures:

* @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 in @runtimeClasspath@.

How you populate these paths is up to you. If you use the @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.

h3. Maven Integration

Grails provides integration with "Maven 2":http://maven.apache.org with a Maven plugin.
Grails provides integration with "Maven 3":http://maven.apache.org with a Maven plugin.

h4. 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!*
In order to use the Maven plugin, all you need is Maven 3 installed and set up. This is because *you no longer need to install Grails separately to use it with Maven!*

{note}
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.
{note}

The Maven 3 integration for Grails has been designed and tested for Maven 3.1.0 and above. It will not work with earlier versions.
{note}
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"@
{note}

h4. Creating a Grails Maven Project

Expand Down Expand Up @@ -112,47 +57,6 @@ You can also use some of the Grails commands that have been wrapped as Maven goa

For a complete, up to date list, run @mvn grails:help@

h4. Creating a Grails Maven Project using the Archetype

You can create a Maven Grails project without having Grails installed, simply run the following command:

{code}
mvn archetype:generate -DarchetypeGroupId=org.grails \\\
-DarchetypeArtifactId=grails-maven-archetype \\\
-DarchetypeVersion=2.1.0.RC1 \\\
-DgroupId=example -DartifactId=my-app
{code}

Choose whichever grails version, group ID and artifact ID you want for your application, but everything else must be as written. This will create a new Maven project with a POM and a couple of other files. What you won't see is anything that looks like a Grails application. So, the next step is to create the project structure that you're used to.
But first, to set target JDK to Java 6, do that now. Open my-app/pom.xml and change

{code}
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.5</source>
<target>1.5</target>
</configuration>
</plugin>
{code}
to
{code}
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.6</source>
<target>1.6</target>
</configuration>
</plugin>
{code}

Then you're ready to create the project structure:

{code}
cd my-app
mvn initialize
{code}

h4. Defining Plugin Dependencies

All Grails plugins are published to a standard Maven repository located at [http://repo.grails.org/grails/plugins/]. When using the Maven plugin for Grails you must ensure that this repository is declared in your list of remote repositories:
Expand All @@ -179,32 +83,51 @@ With this done you can declare plugin dependencies within your @pom.xml@ file:

Note that the @type@ element must be set to @zip@.

h4. Forked Grails Execution
h4. Specifying the Grails Version to Use

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.
The 2.4.0 version of the Maven plugin works with different versions of Grails. By default it tries to auto-detect the version of Grails to use from the @grails-dependencies@ dependency definition found in the @pom.xml@:

In this case it is recommended to use forked execution. Forked execution can be configured in the @configuration@ element of the plugin:
{code:xml}
<dependency>
<groupId>org.grails</groupId>
<artifactId>grails-dependencies</artifactId>
<version>2.4.0</version>
</dependency>
{code}

If you change the version of @grails-dependencies@ then a different version of Grails will be used. However, you can also explicitly define the Grails version to be used in the plugin @configuration@:

{code}
<plugin>
<groupId>org.grails</groupId>
<artifactId>grails-maven-plugin</artifactId>
<version>${grails.version}</version>
<version>2.4.0</version>
<configuration>
<!-- Whether for Fork a JVM to run Grails commands -->
<fork>true</fork>
<grailsVersion>2.4.0</grailsVersion>
</configuration>
<extensions>true</extensions>
</plugin>
{code}

With this configuration in place a separate JVM will be forked when running Grails commands. If you wish to debug the JVM that is forked you can add the @forkDebug@ element:
h4. Debugging Grails Execution

The Maven plugin will run Grails commands in a separate process, meaning that the Grails process occupies a separate JVM as the Maven process.

To debug the Grails process you need to configure the @forkDebug@ option in the plugin's @configuration@ tag:

{code:xml}
<!-- Whether for Fork a JVM to run Grails commands -->
<fork>true</fork>
<forkDebug>true</forkDebug>
{code}
<plugin>
<groupId>org.grails</groupId>
<artifactId>grails-maven-plugin</artifactId>
<version>2.4.0</version>
<configuration>
<forkDebug>true</forkDebug>
</configuration>
<extensions>true</extensions>
</plugin>
{code}

With this configuration in place the JVM executed in Maven will load in debug mode.

If you need to customize the memory of the forked process the following elements are available:

Expand Down Expand Up @@ -249,7 +172,7 @@ Fear not: all things are possible. In this case, you can associate the command t
<plugin>
<groupId>org.grails</groupId>
<artifactId>grails-maven-plugin</artifactId>
<version>2.1.0.RC2</version>
<version>2.4.0</version>
<extensions>true</extensions>
<executions>
<execution>
Expand Down Expand Up @@ -278,23 +201,58 @@ This also demonstrates the @grails:exec@ goal, which can be used to run any Grai
mvn grails:exec -Dcommand=create-webtest -Dargs=Book
{code}

h4. Debugging a Grails Maven Project
h4. Raising issues

Maven can be launched in debug mode using the "mvnDebug" command. To launch your Grails application in debug, simply run:
If you come across any problems with the Maven integration, please raise a [JIRA issue|http://jira.grails.org/browse/MAVEN].

{code}
mvnDebug grails:run-app
{code}

The process will be suspended on startup and listening for a debugger on port 8000.
h3. Ant Integration

When you create a Grails application with the [create-app|commandLine] command, Grails doesn't automatically create an Ant @build.xml@ file but you can generate one with the [integrate-with|commandLine] command:

bc.
grails integrate-with --ant

This creates a @build.xml@ file containing the following targets:

* @clean@ - Cleans the Grails application
* @compile@ - Compiles your application's source code
* @test@ - Runs the unit tests
* @run@ - Equivalent to "grails run-app"
* @war@ - Creates a WAR file
* @deploy@ - Empty by default, but can be used to implement automatic deployment

Each of these can be run by Ant, for example:

{code:java}
ant war
{code}

If you need more control of the debugger, this can be specified using the MAVEN_OPTS environment variable, and launch Maven with the default "mvn" command:
The build file is configured to use "Apache Ivy":http://ant.apache.org/ivy/ for dependency management, which means that it will automatically download all the requisite Grails JAR files and other dependencies on demand. You don't even have to install Grails locally to use it! That makes it particularly useful for continuous integration systems such as [CruiseControl|http://cruisecontrol.sourceforge.net/] or [Jenkins|http://jenkins-ci.org/].

It uses the Grails [Ant task|api:grails.ant.GrailsTask] to hook into the existing Grails build system. The task lets you run any Grails script that's available, not just the ones used by the generated build file. To use the task, you must first declare it:
{code}
MAVEN_OPTS="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005"
mvn grails:run-app
<taskdef name="grailsTask"
classname="grails.ant.GrailsTask"
classpathref="grails.classpath"/>
{code}

h4. Raising issues
This raises the question: what should be in "grails.classpath"? The task itself is in the "grails-bootstrap" JAR artifact, so that needs to be on the classpath at least. You should also include the "groovy-all" JAR. With the task defined, you just need to use it! The following table shows you what attributes are available:
{table}
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@.
{table}

If you come across any problems with the Maven integration, please raise a [JIRA issue|http://jira.grails.org/browse/MAVEN].
The task also supports the following nested elements, all of which are standard Ant path structures:

* @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 in @runtimeClasspath@.

How you populate these paths is up to you. If you use the @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.
6 changes: 6 additions & 0 deletions src/en/guide/introduction/whatsNew24.gdoc
View file
Expand Up @@ -203,6 +203,12 @@ Account.withTransaction([propagationBehavior: TransactionDefinition.PROPAGATION_

See the [withTransaction|domainClasses] docs for more information.

h4. New Maven Plugin

The Maven plugin has been rewritten to use [Aether for dependency resolution|http://wiki.eclipse.org/Aether/Using_Aether_in_Maven_Plugins] and can now be used with both Grails 2.3.x and Grails 2.4.x without releasing a new version of the plugin.

This means that the Maven plugin version number is no longer tied to the version number of Grails and new releases of the Maven plugin will not come out with each new Grails release. Instead, users can continue to use the 2.4.0 version of the plugin for any version of Grails going forward.

h4. Improved Unit Testing Support For allowedMethods

The allowedMethods property is now respected in unit tests.
Expand Down

0 comments on commit 1f5fd85

Please sign in to comment.