The <groovyc> Ant Task

1. `<groovyc>`

1.1. Description

Compiles Groovy source files and, if joint compilation option is used, Java source files from Apache Ant.

Assuming the groovy jars are in groovy.libs, you will need to declare this task at some point in the build.xml prior to the groovyc task being invoked. Consider also adding any additional Groovy module jars, libraries and potentially transitive dependencies you might be using.

<taskdef name="groovyc" classname="org.codehaus.groovy.ant.Groovyc">
  <classpath>
    <fileset file="${groovy.libs}/groovy-ant-VERSION.jar"/>
    <fileset file="${groovy.libs}/groovy-VERSION.jar"/>
  </classpath>
</taskdef>

1.3. <groovyc> Attributes

Attribute Description Required

Attribute	Description	Required
srcdir	Location of the Groovy (and possibly Java) source files.	Yes
destdir	Location to store the class files.	Yes
classpath	The classpath to use.	No
classpathref	The classpath to use given as a path references.	No
sourcepath	The sourcepath to use.	No
sourcepathref	The sourcepath to use given as a path reference.	No
encoding	Encoding of source files.	No
verbose	Asks the compiler for verbose output; defaults to no.	No
includeAntRuntime	Whether to include the Ant run-time libraries in the classpath; defaults to yes.	No
includeJavaRuntime	Whether to include the default run-time libraries from the executing VM in the classpath; defaults to no.	No
includeDestClasses	This property controls whether to include the destination classes directory in the classpath given to the compiler. The default value is "true".	No
fork	Whether to execute groovyc using a spawned instance of the JVM; defaults to no.	No
memoryInitialSize	The initial size of the memory for the underlying VM, if using fork mode; ignored otherwise. Defaults to the standard VM memory setting. (Examples: 83886080, 81920k, or 80m)	No
memoryMaximumSize	The maximum size of the memory for the underlying VM, if using fork mode; ignored otherwise. Defaults to the standard VM memory setting. (Examples: 83886080, 81920k, or 80m)	No
failonerror	Indicates whether compilation errors will fail the build; defaults to true.	No
proceed	Inverse alias for failonerror.	No
listfiles	Indicates whether the source files to be compiled will be listed; defaults to no.	No
stacktrace	if true each compile error message will contain a stacktrace	No
indy	Enable compilation with the ``invoke dynamic'' support when using Groovy 2.0 and beyond and running on JDK 7	No
scriptBaseClass	Sets the base class for Groovy scripts	No
stubdir	Set the stub directory into which the Java source stub files should be generated. The directory need not exist and will not be deleted automatically - though its contents will be cleared unless 'keepStubs' is true. Ignored when forked.	No
keepStubs	Set the keepStubs flag. Defaults to false. Set to true for debugging. Ignored when forked.	No
forceLookupUnnamedFiles	The Groovyc Ant task is frequently used in the context of a build system that knows the complete list of source files to be compiled. In such a context, it is wasteful for the Groovy compiler to go searching the classpath when looking for source files and hence by default the Groovyc Ant task calls the compiler in a special mode with such searching turned off. If you wish the compiler to search for source files then you need to set this flag to true. Defaults to false.	No
configscript	Set the configuration file used to customize the compilation configuration.	No
parameters	Generates metadata for reflection on method parameter names on JDK 8 and above. Defaults to false.	No
previewFeatures	Enables the JEP preview features on JDK 12 and above. Defaults to false.	No
targetBytecode	Sets the bytecode compatibility level.	No
javahome	Sets the `java.home` value to use, default is the current JDK’s home.	No
executable	Sets the name of the java executable to use when invoking the compiler in forked mode, ignored otherwise.	No
scriptExtension	Set the extension to use when searching for Groovy source files. Accepts extensions in the form *.groovy, .groovy or groovy.	No
updatedProperty	The property to set on compilation success. This property will not be set if the compilation fails, or if there are no files to compile.	No
errorProperty	The property to set on compilation failure. This property will be set if the compilation fails.	No

srcdir

Location of the Groovy (and possibly Java) source files.

Yes

destdir

Location to store the class files.

Yes

classpath

The classpath to use.

classpathref

The classpath to use given as a path references.

sourcepath

The sourcepath to use.

sourcepathref

The sourcepath to use given as a path reference.

encoding

Encoding of source files.

verbose

Asks the compiler for verbose output; defaults to no.

includeAntRuntime

Whether to include the Ant run-time libraries in the classpath; defaults to yes.

includeJavaRuntime

Whether to include the default run-time libraries from the executing VM in the classpath; defaults to no.

includeDestClasses

This property controls whether to include the destination classes directory in the classpath given to the compiler. The default value is "true".

fork

Whether to execute groovyc using a spawned instance of the JVM; defaults to no.

memoryInitialSize

The initial size of the memory for the underlying VM, if using fork mode; ignored otherwise. Defaults to the standard VM memory setting. (Examples: 83886080, 81920k, or 80m)

memoryMaximumSize

The maximum size of the memory for the underlying VM, if using fork mode; ignored otherwise. Defaults to the standard VM memory setting. (Examples: 83886080, 81920k, or 80m)

failonerror

Indicates whether compilation errors will fail the build; defaults to true.

proceed

Inverse alias for failonerror.

listfiles

Indicates whether the source files to be compiled will be listed; defaults to no.

stacktrace

if true each compile error message will contain a stacktrace

indy

Enable compilation with the ``invoke dynamic'' support when using Groovy 2.0 and beyond and running on JDK 7

scriptBaseClass

Sets the base class for Groovy scripts

stubdir

Set the stub directory into which the Java source stub files should be generated. The directory need not exist and will not be deleted automatically - though its contents will be cleared unless 'keepStubs' is true. Ignored when forked.

keepStubs

Set the keepStubs flag. Defaults to false. Set to true for debugging. Ignored when forked.

forceLookupUnnamedFiles

The Groovyc Ant task is frequently used in the context of a build system that knows the complete list of source files to be compiled. In such a context, it is wasteful for the Groovy compiler to go searching the classpath when looking for source files and hence by default the Groovyc Ant task calls the compiler in a special mode with such searching turned off. If you wish the compiler to search for source files then you need to set this flag to true. Defaults to false.

configscript

Set the configuration file used to customize the compilation configuration.

parameters

Generates metadata for reflection on method parameter names on JDK 8 and above. Defaults to false.

previewFeatures

Enables the JEP preview features on JDK 12 and above. Defaults to false.

targetBytecode

Sets the bytecode compatibility level.

javahome

Sets the java.home value to use, default is the current JDK’s home.

executable

Sets the name of the java executable to use when invoking the compiler in forked mode, ignored otherwise.

scriptExtension

Set the extension to use when searching for Groovy source files. Accepts extensions in the form *.groovy, .groovy or groovy.

updatedProperty

The property to set on compilation success. This property will not be set if the compilation fails, or if there are no files to compile.

errorProperty

The property to set on compilation failure. This property will be set if the compilation fails.

Example:

<path id="classpath.main">
  <fileset dir="${groovy.libs}" includes="*.jar" excludes="groovy-ant-*.jar"/>
  ...
</path>
<groovyc srcdir="${dir.sources}" destdir="${dir.classes}" classpathref="classpath.main"
         fork="true" includeantruntime="false" configscript="config.groovy" targetBytecode="1.8"/>

1.4. <groovyc> Nested Elements

element	kind	Required	Replaces Attribute
src	a path structure	Yes (unless srcdir is used)	srcdir
classpath	a path structure	No	classpath or classpathref
javac	javac task	No	N/A

element

kind

Required

Replaces Attribute

src

a path structure

Yes (unless srcdir is used)

srcdir

classpath

a path structure

classpath or classpathref

javac

javac task

N/A

Notes:

For path structures see for example https://ant.apache.org/manual/using.html#path
For usages of the javac task see https://ant.apache.org/manual/Tasks/javac.html
The nested javac task behaves more or less as documented for the top-level javac task. srcdir, destdir, classpath, encoding and parameters for the nested javac task are taken from the enclosing groovyc task. If these attributes are specified then they are added, they do not replace. In fact, you should not attempt to overwrite the destination. Other attributes and nested elements are unaffected, for example fork, memoryMaximumSize, etc. may be used freely.

1.5. Joint Compilation

Joint compilation is enabled by using an embedded javac element, as shown in the following example:

<groovyc srcdir="${testSourceDirectory}" destdir="${testClassesDirectory}" targetBytecode="1.8">
  <classpath>
    <pathelement path="${mainClassesDirectory}"/>
    <pathelement path="${testClassesDirectory}"/>
    <path refid="testPath"/>
  </classpath>
  <javac debug="true" source="1.8" target="1.8" />
</groovyc>

More details about joint compilation can be found in the joint compilation section.