# The <groovyc> Ant Task

version 6.0.0-beta-1

## 1. `<groovyc>`

### 1.1. Description

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

### 1.2. Required taskdef

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
--- | --- | ---
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
inheritAll | If enabled and `fork` is true, all properties from the parent Ant project are passed to the forked compiler JVM as system properties. For selective passing, use a nested `<sysproperty>` or `<syspropertyset>` instead. Defaults to false. | 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

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
jvmarg | command line argument | No | N/A
sysproperty | an Ant `<sysproperty>` | No | N/A
syspropertyset | an Ant `<propertyset>` | No | 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`, `fork`, `memoryInitialSize`, and `memoryMaximumSize` for the nested `javac` task are taken from the enclosing `groovyc` task. If these attributes or any else that are not explicitly supported are specified then a warning is logged, and they are ignored completely. `classpath` and `classpathref` specified on the nested `javac` task is merged with the values taken from the enclosing `groovyc` task and also used for the Groovy compilation. Nested inside the nested `javac` task the only element supported is `compilerarg`, and this only with the `value` attribute, which is treated like the `line` attribute of the top-level `javac` task, i.e. it is split by spaces into separate arguments. Only arguments starting with `-W`, `-X`, or `-proc:` are properly translated as needed. Anything else is supplied as-is to groovyc and has to be manually prefixed with `-F` or `-J`.

### 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.

### 1.6. Passing JVM arguments and system properties to a forked compiler

When `fork="true"`, you can attach arbitrary JVM arguments and system properties to the spawned compiler JVM via nested `<jvmarg>`, `<sysproperty>`, and `<syspropertyset>` elements (mirroring Ant’s `<java>` task). This is useful for compile-time configuration consumed by AST transforms, the parser/lexer, or annotation processors.

    <groovyc srcdir="src" destdir="build/classes" fork="true">
      <jvmarg value="--add-opens=java.base/java.lang=ALL-UNNAMED"/>
      <sysproperty key="my.compile.flag" value="true"/>
      <syspropertyset>
        <propertyref prefix="myapp."/>
      </syspropertyset>
    </groovyc>

To pass every parent project property at once, set `inheritAll="true"`. Explicit `<sysproperty>` and `<syspropertyset>` entries take precedence on name collision.