Groovy support in Schmant

Revision History
Revision 1.0.1	2010.02.16

Table of Contents

Running
Environment
Imports
Troubleshooting
Miscellaneous notes
Further reading
See also

Running

To enable Groovy, either install the Groovy-all Jar (groovy-all-version.jar) in the running JDK or put it on the classpath when running the build script. A Groovy distribution can be downloaded form the Groovy site.

Environment

Before running a Groovy script, Schmant prepares the scripting environment by running the prepare.groovy script. It enables the org.schmant.task.base task package and defines the following functions:

debug(/* Object */ s)

Write a debug message to the current Report.

info(/* Object */ s)

Write an information message to the current Report.

warn(/* Object */ s)

Write a warning message to the current Report.

error(/* Object */ s)

Write an error message to the current Report.

fail(/* Object */ s)

Write an error message to the current Report and abort the build script execution.

enableTaskPackage(/* String */ name)

Enable the task package name. This method is seldom used directly from Groovy scripts. See the section called “Imports”.

include(/* Object */ f)

Execute the supplied script using the current script executor and return the result. The f argument is interpreted by InterpretAsReadableFileStrategy.

Since include uses interpreted arguments, it can use files from a variety of locations. For large projects, for instance, it may be useful to distribute common utility functions in a Zip file.

Example 1. Including script files in a Zip archive

import java.io.File
import org.entityfs.util.Directories
import org.entityfs.zip.ZipFileSystemBuilder

// Get a Directory for the root directory of the Zip file
def includeRoot = new ZipFileSystemBuilder().
  // Assuming that the script's working directory is an Eclipse workspace
  // directory, get the script archive from the Resources project
  setZipFile(new File("Resources/scripts/common-scripts.zip")).
  create().rootDirectory

// Include a couple of script files from the Zip file.
include(Directories.getFile(includeRoot, "common.groovy"));
include(Directories.getFile(includeRoot, "compile.groovy"));

The methods of SchmantUtil may be useful when creating paths relative to the currently executing script file.

The build script is launched from the wrapper.groovy script. It enables the task packages specified in the script header (see below).

Imports

Unlike for instance JavaScript, Jython and BeanShell, import statements in Groovy may only occur at the top of a script file. This means that Schmant cannot import common classes automatically. Instead classes and/or packages have to be imported manually by the build scripts.

Another consequence is that all classes used by the script must be on the classpath when the script file is loaded. This means that all task packages that is used by a script must be enabled before the script is loaded, if the script should be able to import classes from the task packages. Hence the script cannot use the enableTaskPackage function for task packages containing classes that it wants to import. Instead, the script can list the task packages that it wants to use in a comment block (// comments) at the top of the script. Task packages listed there are enabled by wrapper.groovy or by the include function.

Example 2. Enabling a task package using a script comment

// This task package will be enabled
// enableTaskPackage org.at4j

// This will not since there is a blank row before this comment block
// enableTaskPackage org.junit.junit4

// Now this import will work
import org.schmant.task.at4j.tar.TarTF

info "Hello " + TarTF.class + " world!"

Troubleshooting

If your build fails with an exception, the failing row is in the exception's stack trace. Look for rows beginning with at ScriptX.run(ScriptX.groovy:nnn), where X is often 3 and nnn is the row in the script file where the exception was thrown. If the exception was thrown from within a closure, search for a row looking like ScriptX$_run_closureY.doCall(ScriptX.groovy:nnn).

Miscellaneous notes

Filters can be combined using logical operators.: Groovy supports combining ConvenientFilter implementations using the & (and), | (or), ^ (xor) and ~ (negate) operators.
Variables and functions defined with def are local.: Variables and functions defined with def or, for variables, with a specific type such as String
, are local to the script file where they are defined. If a function or a variable should be visible from other script files, define it without using def or a type.