(Quick Reference)

2 Using the Plugin - Reference Documentation

Authors: Luke Daley, Graeme Rocher, Peter Ledbrook, John Engelman

Version: 2.1.1

2 Using the Plugin

The Grails Gradle Plugin is available from Bintray's JCenter and the Maven Central repositories. Apply it to a Gradle project the same way as any other plugin:

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'org.grails:grails-gradle-plugin:2.0.1'
    }
}

apply plugin: 'grails'

version = 1.0

grails { grailsVersion = '2.3.6' groovyVersion = '2.1.9' }

repositories { grails.central() }

The plugin requires that the grails.grailsVersion is specified for the project. Additionally, the version property is required for executing the init task since Grails needs the application version during project initialization.

While the grails.groovyVersion property is not required, specifying it allows the plugin to properly configure the Groovy runtime for the bootstrap and compile classpaths. Additionally, specifying it will configure a Gradle ResolutionStrategy to prevent different versions of groovy or groovy-all from entering the classpath through dependencies.

If you are using the Grails Gradle Plugin to build applications with a version of Grails prior to 2.3.0, configuring the grails.groovyVersion property may have some side effects.

Specifying a grails.groovyVersion that does not match the Groovy version supplied with the specified grails.grailsVersion is not supported. It is possible to make this configuration, but unforeseen behavior may occur.

2.1 Initializing a Grails Project

Once the plugin is applied, a new Grails project can be initialized through Gradle.

$ gradle init //Initializes a Grails application

OR

$ gradle init-plugin //Initializes a Grails plugin

Both tasks initialize the Grails project in the current working directory.

The plugin initializes the application/plugin with the name of the Gradle project and the current Gradle project version

2.2 Configuring Project Dependencies

Using the Grails Gradle Plugin bypasses the normal Grails application build framework in favor of Gradle. The consequence of this is that the BuildConfig.groovy is no longer consulted for repository or dependency information. All repositories and dependencies MUST be configured via Gradle.

Because Grails is no longer resolving the dependency information, the short syntax for plugins cannot be used:

plugins {
  compile ':resources:1.1.1'
}

In Grails, the syntax omits the Maven groupId for Grails plugins because all public Grails plugins are published under the org.grails.plugins groupId. With Gradle, the groupId MUST be specified:

dependencies {
    compile 'org.grails.plugins:resources:1.1.1'
}

The Grails Gradle Plugin configures the following scopes for dependency resolution: bootstrap, provided, compile, runtime, test. These scopes map to the same scopes normally used in BuildConfig.groovy.

2.3 Running a Grails Project

The Grails Gradle Plugin creates a run task on the project that will start the Grails application container in the normal development environment by executing the Grails run-app script.

$ gradle run

Grails does not ship with an application container provided, so the build must specify a Grails plugin dependency. Typically, this will be the Grails tomcat plugin:

dependencies {
    bootstrap 'org.grails.plugins:tomcat:7.0.50'
}

By default, the plugin configures the run task and dynamic grails-run-app task to enabled class reloading via SpringLoaded. Other other tasks created by the plugin or dynamically created via the Grails Script pattern will have reloading disabled. To enable reloading for GrailsTask, define the task and configure the reload property to true.

Running the run task will prevent the Gradle execution from completing (i.e. the task blocks on the running container). To terminate the Grails application, use Ctrl+C to terminate the Gradle run

2.4 Running Tests

The Grails Gradle Plugin configures a test task that executes the projects tests through the Grails framework. Additionally, the plugin configures the normal Gradle check task with a dependency on test.

$ gradle test
:test
| Loading Grails 2.3.5
…
| Tests PASSED - view reports in /Users/jengelman/workspace/personal/gg-test/build/test-results

BUILD SUCCESSFUL

Total time: 14.181 secs

$ gradle check :grails-test-app UP-TO-DATE :test UP-TO-DATE :check UP-TO-DATE

BUILD SUCCESSFUL

Total time: 1.177 secs

The plugin configures test results by default to be output to build/test-results

Running Specific Test Phases

The GrailsTestTask allows for configuring the specific test phases through the phases property. By default the test task is configured with no phases which results in Grails executing ALL test phases. This can be modified as such:

test {
    phases = ['unit:', 'integration:']
}

The above block will configure test to only execute the unit and integration test phases.

The phases property of GrailsTestTask gets passed to Grails's test-app command directly. Therefore, you must provide content that is compatible with the test-app script. Grails test phase/type selection is of the form <phase>:<type>. Valid syntaxes include (not a complete list): unit:, unit:unit, unit:spock, :spock, etc.

phases = ['unit:'] //Execute all tests types in the unit phase
phases = ['integration:spock'] //Execute all Spock tests in the integration phase
phases = [':unit'] //Execute all JUnit test type in all phases

Refer to the section Targeting Test Types and/or Phases in the Grails User Guide for additional information.

Configuring a Test Task Rule

It may be beneficial to configure a Gradle task rule to execute specific test phases from the command line. This can be accomplished as so:

project.tasks.addRule('Pattern: test<Phase>') { String taskName ->
    if (taskName.startsWith('test')) {
        task(taskName, type: GrailsTestTask) {
            String testPhase = (taskName - 'test').toLowerCase()
            phases = [testPhase + ':']
        }
    }
}

$ gradle testUnit //Execute the unit test phase

When adding a a TaskRule for Grails tasks, avoid using a prefix that begins with
grails-
. This is the prefix that the plugin uses for executing arbitrary Grails scripts. Gradle doesn't provide a method to order TaskRules, so using this prefix will likely result in a duplicate task exception.

Running Specific Tests

In matching with the Gradle standard, use the -Dtest.single property to defined single tests to run. The GrailsTestTask observes this system property and will pass the value as is to the Grails test task.

$ gradle test -Dtest.single=FooController

The --test syntax introduced in Gradle 1.10 is not supported for selecting tests to execute. This is because the plugin is delegating to the underlying GrailsLauncher to execute tests and not using Gradle's Test class as a base. All the normal test selection methods for the Grails test-app command are supported since the value of test.single is passed directly as a command line argument to the Grails script.

$ gradle test -Dtest.single="Foo Bar"

Setting the Test Results Output Directly

If multiple GrailsTestTasks are configured in a project and are part of the normal build process, it may be benefical to configure each task to output its test results to a different directory. By default, Grails cleans the test output directory before running tests so that the test report matches the tests executed. Use the testResultsDir property on GrailsTestTask to configure the test output directory.

task unit(type: GrailsTestTask) {
    testResultsDir = file('build/reports/test-unit')
    phases = ['unit:']
}

task integration(type: GrailsTestTask) { testResultsDir = file('build/reports/test-int') phases = ['integration:'] }

test.enabled = false // Disable the default test task that executes all phases check.dependsOn [unit, integration] // Configure test phase tasks to execute on the 'check' task

2.5 Executing Grails Scripts

The plugin configures a Gradle Task Rule to allow execution of any available Grails scripts as Gradle tasks. Simply prefix the Grails script name with grails- and execute from Gradle.

$ gradle grails-refresh-dependencies

Similar to the behavior of Grails itself, the provided script will be passed as the execution for Grails. If the requested script is provided via a Grails plugin that is not yet installed, then the execution will fail because plugin resolution in Grails occurs after validating the script. This can be avoided by executing a gradle assemble so that Grails compilation & plugin resolution occurs after adding a new Grails plugin to the build dependencies.

2.6 Packaging a Grails Project

The Grails Gradle Plugin configures the normal Gradle assemble task to execute the appropriate Grails command for creating the project's output. For applications, the assemble task depends on war which executes the Grails war script and produces a War output. For plugins, the assemble task depends on packagePlugin which executes the Grails package-plugin script and produces the plugin Zip output.

Additionally, the plugin configures the normal Gradle build task to depend on test and assemble

2.7 Configuring Plugin Properties

The plugin provides a number of properties that can be configure for each build. These properties are configure through the grails extension in the Gradle build:

grails {
    grailsVersion = '2.3.6'
    groovyVersion = '2.1.9'
    springLoadedVersion = '1.1.3'
}

GrailsVersion

The grailsVersion property specifies the version of Grails to build the application against. This will transitively include a number of Grails libraries onto the classpath for compilation.

GroovyVersion

The groovyVersion property specifies the version of Groovy to use to build the application. This is a convenience method. By setting this property, the plugin will add the specified version of the groovy-all library to both the boot and compile configurations. Additionally, it will configure a ResolutionStrategy rule to convert all requests for groovy-all to use this version for the dependency and all requests for the standard groovy library will be converted to request the groovy-all library instead.

If you are using the Grails Gradle Plugin to build applications with a version of Grails prior to 2.3.0, configuring the grails.groovyVersion property may have some side effects.

Specifying a grails.groovyVersion that does not match the Groovy version supplied with the specified grails.grailsVersion is not supported. It is possible to make this configuration, but unforeseen behavior may occur.

SpringLoadedVersion

The springLoadedVersion property specifies the version of the SpringLoaded library to place on the classpath when executing the run or grails-run-app tasks. This library enables class reloading. Internally, the plugin configures a Java Agent using this library which performs the reload in the JVM. The plugin configures a default version of the library, and this property can be used to specify a different version than the default.

By default, the plugin only configures the springLoaded library and reloading on the run and grails-run-app tasks.

2.8 Upgrading a Grails Application

Grails ships with an upgrade that is used to upgrade an application or plugin from one version of Grails to another. Use of this command is NOT supported via the Grails-Gradle plugin. This script requires an actual Grails installation on the machine.

Instead, the plugin will automatically modify the application.properties to reflect both the version of Grails and the application's version (as specific by grails.grailsVersion and project.version respectively). This synchronization will occur as the during any GrailsTask.

This behavior is identical to the behavior of Maven enabled Grails packages as stated in MAVEN-137

The Grails version synchronization will allow you to change the Grails version via the build.gradle file, however, it will NOT apply any upgrades that maybe be obtained through a normal grails upgrade process. It is the responsibility of the user to manually apply any differences that may occur.

A good resource for this is the What's new in Grails x.y

Alternatively, you can initialize a new project with the new Grails version and compare the 2 directories with your favorite diff tool.