This article originally appeared in the January 2011 issue of GroovyMag.
Gradle is a build system in which builds are described using a declarative and concise DSL written in the Groovy language. This article describes how you can wrap proven Apache Ant Tasks in a Gradle Plugin to make using them as effortless as possible. We’ll also go over some of the tools Gradle provides for building and testing robust Plugin functionality following some easy patterns.
Creating new custom Plugins for Gradle is a relatively straightforward and easy process. Within a Plugin it’s possible to configure a Gradle Project with new properties, dependencies, Tasks – pretty much anything that you can configure in a build.gradle file can be encapsulated into a Plugin for abstraction, portability and reuse. One of the easier ways to add functionality through a Plugin is to encapsulate an existing Ant Task and enhance it by providing the ease-of-use and configuration that Gradle users have come to expect. Recently, I’ve been writing a lot more JavaScript and was looking for static analysis tools to help guide me away from ‘bad habits’. The popular choice for static analysis of JavaScript code seems to be JSLint, so here’s an example of providing that functionality for a Gradle build by wrapping an existing JSLint task and making it easier to work with.
Anatomy of a Gradle Plugin
Gradle plugins can most easily be built using Gradle itself. There is a conveniently available gradleApi() method you can call to include the required framework classes, demonstrated in the dependencies section of a build.gradle file shown in Listing 1. For this example we’re also using the Groovy Plugin and JUnit for testing, so we will include those dependencies as well.
[groovy language=”true”]
dependencies {
compile gradleApi()
groovy group: ‘org.codehaus.groovy’, name: ‘groovy’, version: ‘1.7.6’
testCompile group: ‘junit’, name: ‘junit’, version: ‘4.8.2
}
[/groovy]
Listing 1: The dependencies portion of a build.gradle file for building our Plugin
Creating a new Gradle Plugin is a simple matter of implementing the Gradle interface and its single required method, the skeleton of which is shown in Listing 2. Within the apply method, the Plugin can configure the Project to add Tasks or properties as needed.
[groovy language=”true”]
class JSLintPlugin implements Plugin<Project>
{
void apply(Project project)
{
//configure the Project here
}
}
[/groovy]
Listing 2: Skeleton of the Plugin implementation
Integrating with Ant
I’ve never been overly fond of Ant, mostly due to the extremely verbose and repetitive nature of the xml declaration. But the fact remains that Ant has been a primary and well-used build tool for years, and the Tasks written for it have been tried and tested by many developers. The Groovy AntBuilder, in combination with the facilities Gradle provides for dependency resolution and classpath management, makes it very easy to incorporate existing Ant functionality into a build and abstract most of the details away from the end user. For this plugin, we add the library containing the Ant Task to a custom configuration so that we can have it automatically downloaded and easily resolve the classpath.
Listing 3 shows how the configuration for the JSLint4Java Task could appear in an Ant build.xml file. Note that you’re on your own here to provide the required library for the classpath.
[xml language=”true”]
<taskdef name="jslint"
classname="com.googlecode.jslint4java.ant.JSLintTask"
classpath="/path/to/jslint4java-1.4.jar"/>
<target name="jslint">
<jslint options="undef,white" haltOnFailure="false">
<formatter type="xml" destfile="${build.dir}/reports"/>
<fileset dir="." includes="**/*.js" excludes="**/server/"/>
</jslint>
</target>
[/xml]
Listing 3: Configuring the Ant target in a build.xml file
Gradle makes it easy to separate the configuration and execution phases of the build, allowing for a Plugin to add an Ant Task to the Gradle Project and expose the (optional) configuration in a build script. In addition, Gradle encourages a pattern of providing a ‘convention’ object alongside of a Plugin to clearly separate the concerns.
Listing 4 demonstrates some code from the Plugin implementation that adds a ‘jslint’ Task to a Gradle Project, setting the specific options based on a convention object. Note how we extract the classpath using the notation project.configurations.jslint.asPath.
[groovy language=”true”]
private static final String TASK_NAME = ‘jslint’
private Project project
private JSLintPluginConvention jsLintpluginConvention
…
// some of the code in the apply method
this.jsLintpluginConvention = new JSLintPluginConvention(project)
project.convention.plugins.jslint = jsLintpluginConvention
project.task(TASK_NAME) << {
project.file(project.reportsDir).mkdirs()
logger.info("Running jslint on project ${project.name}")
ant.taskdef(name: TASK_NAME, classname: jsLintpluginConvention.taskName,
classpath: project.configurations.jslint.asPath)
ant."$TASK_NAME"(jsLintpluginConvention.mapTaskProperties()) {
formatter(type: jsLintpluginConvention.decideFormat(),
destfile: jsLintpluginConvention.createOutputFileName())
jsLintpluginConvention.inputDirs.each { dirName ->
fileset(dir: dirName,
includes: jsLintpluginConvention.includes,
excludes: jsLintpluginConvention.excludes)
}
}
}
[/groovy]
Listing 4: Adding a jslint Task to a Gradle Project
If you’re not already familiar with the Gradle syntax for creating new Tasks inline, the project.task(String taskName) method is called to instantiate a new Task, and the ‘< <' syntax is used to to push the Task activities into the 'doLast' Task lifecycle phase. Allowing for configuration of the Task in a build script is as simple as exposing a method named the same as the Task that takes in a Closure parameter and applies that Closure to set properties on the convention object, as shown in Listing 5. [groovy language="true"] /** * Perform custom configuration of the plugin using the provided closure. * @param closure */ def jslint(Closure closure) { closure.delegate = this closure() } [/groovy] Listing 5: A method to allow for configuration of the jslint Task from a build script
The simple use-case
As per usual when working with Gradle, using this plugin in the most basic case requires only these things:
- Declare a dependency on the Plugin source. This can be either a released jar to be downloaded from a repository by Gradle or you can download a jar manually from pretty much anywhere and add it to the classpath directly.
- Apply the Plugin to a Gradle build.
- Call the jslint Task as part of the build.
The entire configuration and usage looks something like Listing 6, assuming that the gradle-jslint-plugin jar is found in /usr/home/gradlelibs.
[groovy language=”true”]
/* In a build.gradle file */
buildscript {
dependencies {
classpath fileTree(dir: ‘/usr/home/gradlelibs’, include: ‘*.jar’)
}
}
apply plugin: org.kar.jslint.gradle.plugin.JSLintPlugin
/* and on the command line… */
gradle jslint
[/groovy]
Listing 6: Configuring the jslint Plugin in a build script and calling it from the command line
By default, this is enough to scan for all .js files under the directory where the build script is located and create a JSLint text report using the basic settings.
The not-so-simple case
Of course in the real world the defaults aren’t always what we need, so being able to easily configure the Task is essential. Fortunately, Gradle makes extending a custom Plugin to allow for configuration by a simple Closure, so we can exercise the code from Listing 5 in a build script with the Closure definition in Listing 7.
[groovy language=”true”]
jslint {
haltOnFailure = false
excludes = ‘**/metadata/’
options = ‘rhino’
formatterType = ‘html’
}
[/groovy]
Listing 7: Departing from the default jslint Task configuration
Extending Ant Task capabilities
The Ant Task as is can produce either a plain text document or an xml report, but transforming the results into a more consumable html format is easy to do using an Ant xslt Task. Having Gradle wrap the Task definition allows for simply adding a new formatter type to the configuration and abstracting away the details from the end user. A copy of an xsl file available online is easy to incorporate with the plugin and can be used to transform the xml output into a nicely formatted web page. Being able to program around Ant Tasks like this is a great way to enhance their value in your build. An example of simple output from the test cases included in the Plugin is shown in Figure 1.
[singlepic id=76]
Figure 1: Example html formatted output from jslint
Testing using ProjectBuilder
In order to facilitate testing custom Tasks and Plugins, the Gradle framework provides the ProjectBuilder implementation to handle most of the heavy lifting. This gives you a mocked out instance of a Gradle Project that builds into a temporary directory; very handy for testing how Tasks behave under real working conditions. Having tools like this available directly from the framework removes a lot of potential barriers that might otherwise discourage testing of custom components. The source code that accompanies this article uses the ProjectBuilder to achieve 100% code coverage of the project and is available on github at https://github.com/kellyrob99/gradle-jslint-plugin if you’d like to look closer for some ideas on how to test your own Gradle Plugins. An already built version of the jar is also available if you’d like to try without having to build it yourself: https://github.com/kellyrob99/gradle-jslint-plugin/blob/master/releases/gradle-jslint-plugin-0.1-SNAPSHOT.jar.
How could we improve this Plugin?
This implementation represents the ‘brute-force’ method of wrapping an Ant Task, and there are several ways to enhance its function, if we wanted to spend some additional time and effort on the Plugin. It would actually be far more flexible if we extended the Gradle DefaultTask to provide the actual functionality; this would allow for the possibility of executing the Task separately against different sets of JavaScript in the same project with different configurations of JSLint. In the case of an application with both client and server-side JavaScript, for instance, you might want to apply different rules. In that event you’d probably also want to have the capability to aggregate multiple result sets, which would be a relatively easy feature to add.
Having a separate Task implementation defined would also make it easier to clearly define the inputs and outputs of the process using one of the @Input or @Output Gradle annotations, allowing for incremental builds including JSLint execution. The full set of annotations available from the org.gradle.api.tasks package allow for combining File and/or simple property types to make your Tasks smarter regarding whether or not running again would produce a different result than the last execution.
This article was created using the recently released 0.9 version of Gradle and version 1.4.4 of jslint4java.
Learn more
If you’d like to find out some background or more about Gradle and how to create your own custom Plugins and Tasks, you can find some good information on these sites:
- The Gradle documentation at http://gradle.org/documentation.html
- In particular, the Project API is a great starting point for getting to know Gradle: http://gradle.org/latest/docs/javadoc/org/gradle/api/Project.html
- The excellent examples of Mr. Haki at http://mrhaki.blogspot.com/search/label/Gradle%3AGoodness
- Published plugins on github can be found with this search: https://github.com/search?type=Repositories&language=&q=gradle+plugin
