5.3.4Custom build scripts with Gant

Although the future of build files in Groovy belongs to Gradle, Gant still occupies one special niche in the Groovy ecosystem. As of this writing, the latest version of the Grails framework (2.3)3 still implements its build scripts in Gant.4 If you need to create a custom build script for a Grails application, Gant is still useful. If you’re not planning to do that, you can comfortably skip this subsection.

GANT USE CASE Grails commands are implemented as Gant scripts, so if you need to customize a Grails command or create a new one, Gant is the tool of choice.

The Gant scripts in Grails are also an excellent choice of sample code. To keep this section simple I’ll review parts of an existing Grails Gant script, called Clean.groovy. The script can be found in the scripts directory under the root of the Grails distribution. As with all Grails Gant scripts, it’s invoked using the script name in lowercase, substituting dashes for camel case; so for the Clean script the command would be grails clean, and for the CreateDomainObject script the command is grails create-domain-object.

Here’s the Clean script in its entirety (minus the copyright statement):

includeTargets << grailsScript("_GrailsClean") setDefaultTarget("cleanAll")

3Grails is discussed in chapter 8 on databases and chapter 10 on web development. The home page for Grails is http://grails.org.

4Gant will continue to be included in Grails through at least version 2.3.

www.it-ebooks.info

The grailsScript command loads a different Gant script, called _GrailsClean. By convention (and Grails is all about conventions), scripts that begin with an underscore are internal scripts that can’t be executed from the command line. The first line thus loads a series of tasks, and the second line makes the cleanAll task the default.

Turning now to the _GrailsClean script, let me highlight a couple of small sections from it:

includeTargets << grailsScript("_GrailsEvents")

target (cleanAll: "Cleans a Grails project") { clean()

cleanTestReports()

grailsConsole.updateStatus "Application cleaned."

}

target (clean: "Implementation of clean") { depends(cleanCompiledSources, cleanWarFile)

}

The resemblance to Ant is not accidental. Gant scripts contain targets, and targets can be invoked as though they were method calls. Here the target defined with the name cleanAll invokes two other tasks (clean and cleanTestReports) and then invokes the updateStatus method on the predefined grailsConsole object.

The clean task uses the depends method (again analogous to the same functionality in Ant) to make sure that the cleanCompiledSources and cleanWarFile tasks are invoked when the clean task is invoked. Here’s a snippet from the cleanCompiledSources task:

target (cleanCompiledSources: "Cleans compiled Java and Groovy sources") { def webInf = "${basedir}/web-app/WEB-INF" ant.delete(dir:"${webInf}/classes") ant.delete(file:webXmlFile.absolutePath, failonerror:false) ant.delete(dir:"${projectWorkDir}/gspcompile", failonerror:false)

The task goes on to delete many more items, delegating to an internal AntBuilder object in each case. The cleanWarFile task shows how you can mix in Groovy logic code inside a script:

target (cleanWarFile: "Cleans the deployable .war file") { if (buildConfig.grails.project.war.file) {

warName = buildConfig.grails.project.war.file

}

else {

def fileName = grailsAppName

def version = metadata.'app.version' if (version) {

fileName += "-$version"

}

warName = "${basedir}/${fileName}.war"

}

www.it-ebooks.info

ant.delete(file:warName, failonerror:false)

}

This is straightforward Groovy code that simply defines some variables and sets their properties based on the current configuration, and then invokes the delete method on the ant object.

That’s enough Gant for this book.5

5.3.5Ant summary

That also concludes the discussion of Ant and Ant-based approaches, both in Java and Groovy. The “Lessons learned” sidebar shows the details.

Lessons learned (Ant)

1If you have an existing Ant build, you can add <groovyc> and <groovy> tasks to it.

2Gant is only used by Grails, and not for very much longer.

3AntBuilder is rare by itself but is built into and useful in Gradle

It’s time now to examine the other major build tool in the Java world: Maven.

Ant limitations

When it was released Ant was a major improvement over previous build processes. Still, it has major issues that complicate life, especially in larger builds. Here’s a brief list of complexities associated with using Ant. This is not intended to be a criticism of Ant, but rather to highlight the issues that lead to the next-generation tools.

Ant builds are based on XML, and XML is not a scripting language. Builds inevitably need to be customized and usually vary depending on whether the project is in development, test, or production mode. Ant allows you to set properties, but properties aren’t variables. It’s especially difficult to do complex branching logic in an XML file.

Ant says nothing about dependency management. It assumes you have all the required libraries available and that you can build a file set to hold them and use that as your classpath. The Ivy project (also from Apache) fills that gap, and the combination of Ant and Ivy is much more common now than Ant alone.

XML was designed to be processed by programs, not people. Reading a short XML file isn’t hard. Reading a long, involved one is, and even the trivial build file presented in this section is over 50 lines long when a few basic tasks are included.

5Additional information on Gant can be found at the Groovy website. There’s also a decent tutorial in the book Grails in Action (Manning, 2009), by Peter Ledbrook and Glen Smith. Finally, the Grails user guide has a section on creating Gant scripts specifically for Grails.

www.it-ebooks.info