//////////////////////////////////////////

  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.

//////////////////////////////////////////
ifndef::tools-groovyc[]
:tools-groovyc: tools-groovyc.adoc
endif::[]

= The <groovyc> Ant Task

[[groovyc-ant-task-using]]
== `<groovyc>`

[[groovyc-ant-task-description]]
=== Description

Compiles Groovy source files and, if joint compilation option is used, Java source files from http://ant.apache.org/[Apache Ant].

[[groovyc-ant-task-taskdef]]
=== 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.

[source,xml]
-----------------------------------------------------------------------
<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>
-----------------------------------------------------------------------

[[groovyc-ant-task-attributes]]
=== <groovyc> Attributes

[cols="<,<,<",options="header,footer"]
|=======================================================================
|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:*

[source,xml]
-----------------------------------------------------------------------
<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"/>
-----------------------------------------------------------------------

[[groovyc-ant-task-nested-elements]]
=== <groovyc> Nested Elements

[cols="<,<,<,<",options="header,footer"]
|==========================================================
|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 |https://ant.apache.org/manual/using.html#arg[command line argument] |No |N/A
|sysproperty |an Ant https://ant.apache.org/manual/Tasks/java.html[`<sysproperty>`] |No |N/A
|syspropertyset |an Ant https://ant.apache.org/manual/Types/propertyset.html[`<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`.

[[groovyc-ant-task-joint-compilation]]
=== Joint Compilation

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

[source,xml]
-----------------------------------------------------------------------
<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 <<{tools-groovyc}#section-jointcompilation,joint compilation>> section.

[[groovyc-ant-task-forked-jvm-args]]
=== 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
https://ant.apache.org/manual/Tasks/java.html[`<java>`] task). This is
useful for compile-time configuration consumed by AST transforms, the
parser/lexer, or annotation processors.

[source,xml]
-----------------------------------------------------------------------
<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.
