// Copyright (C) 2024 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.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.

[[groovy_plugin]]
= The Groovy Plugin

The Groovy plugin extends the <<java_plugin.adoc#java_plugin,Java plugin>> to add support for https://groovy-lang.org/[Groovy] projects.
It can deal with Groovy code, mixed Groovy and Java code, and even pure Java code (although we don't necessarily recommend to use it for the latter).
The plugin supports _joint compilation_, which allows you to freely mix and match Groovy and Java code, with dependencies in both directions.
For example, a Groovy class can extend a Java class that in turn extends a Groovy class.
This makes it possible to use the best language for the job, and to rewrite any class in the other language if needed.

Note that if you want to benefit from the <<java_library_plugin.adoc#sec:java_library_separation,API / implementation separation>>, you can also apply the `java-library` plugin to your Groovy project.


[[sec:groovy_usage]]
== Usage

To use the Groovy plugin, include the following in your build script:

.Using the Groovy plugin
====
include::sample[dir="snippets/groovy/quickstart/kotlin",files="build.gradle.kts[tags=use-plugin]"]
include::sample[dir="snippets/groovy/quickstart/groovy",files="build.gradle[tags=use-plugin]"]
====

[[sec:groovy_tasks]]
== Tasks

The Groovy plugin adds the following tasks to the project.
Information about altering the dependencies to Java compile tasks are found <<building_java_projects.adoc#sec:building_jvm_lang,here>>.

`compileGroovy` — link:{groovyDslPath}/org.gradle.api.tasks.compile.GroovyCompile.html[GroovyCompile]::
_Depends on_: `compileJava`
+
Compiles production Groovy source files.

`compileTestGroovy` — link:{groovyDslPath}/org.gradle.api.tasks.compile.GroovyCompile.html[GroovyCompile]::
_Depends on_: `compileTestJava`
+
Compiles test Groovy source files.

`compile__SourceSet__Groovy` — link:{groovyDslPath}/org.gradle.api.tasks.compile.GroovyCompile.html[GroovyCompile]::
_Depends on_: `compile__SourceSet__Java`
+
Compiles the given source set's Groovy source files.

`groovydoc` — link:{groovyDslPath}/org.gradle.api.tasks.javadoc.Groovydoc.html[Groovydoc]::
+
Generates API documentation for the production Groovy source files.

The Groovy plugin adds the following dependencies to tasks added by the Java plugin.

.Groovy plugin - additional task dependencies
[%header%autowidth,compact]
|===
| Task name | Depends on
| `classes` | `compileGroovy`
| `testClasses` | `compileTestGroovy`
| `__sourceSet__Classes` | `compile__SourceSet__Groovy`
|===

.Groovy plugin - tasks
image::groovyPluginTasks.png[]


[[sec:groovy_project_layout]]
== Project layout

The Groovy plugin assumes the project layout shown in <<#groovylayout,Groovy Layout>>. All the Groovy source directories can contain Groovy _and_ Java code. The Java source directories may only contain Java source code.footnote:[Gradle uses the same conventions as introduced by Russel Winder's link:https://github.com/Gant/Gant[Gant tool].] None of these directories need to exist or have anything in them; the Groovy plugin will simply compile whatever it finds.

[[groovylayout]]
include::javaProjectMainLayout.adoc[]

`src/main/groovy`::
Production Groovy source. May also contain Java source files for joint compilation.

include::javaProjectTestLayout.adoc[]

`src/test/groovy`::
Test Groovy source. May also contain Java source files for joint compilation.

include::javaProjectGenericLayout.adoc[]

`src/__sourceSet__/groovy`::
Groovy source files for the given source set. May also contain Java source files for joint compilation.


[[sec:changing_groovy_project_layout]]
=== Changing the project layout

Just like the Java plugin, the Groovy plugin allows you to configure custom locations for Groovy production and test source files.

.Custom Groovy source layout
====
include::sample[dir="snippets/groovy/customizedLayout/kotlin",files="build.gradle.kts[tags=custom-source-locations]"]
include::sample[dir="snippets/groovy/customizedLayout/groovy",files="build.gradle[tags=custom-source-locations]"]
====

[[sec:groovy_dependency_management]]
== Dependency management

Because Gradle's build language is based on Groovy, Gradle already ships with a Groovy library. Nevertheless, Groovy projects need to explicitly declare a Groovy dependency. This dependency will then be used on compile and runtime class paths. It will also be used to get hold of the Groovy compiler and Groovydoc tool, respectively.

If Groovy is used for production code, the Groovy dependency should be added to the `implementation` configuration:

.Configuration of Groovy dependency
====
include::sample[dir="snippets/groovy/quickstart/kotlin",files="build.gradle.kts[tags=groovy-dependency]"]
include::sample[dir="snippets/groovy/quickstart/groovy",files="build.gradle[tags=groovy-dependency]"]
====

If Groovy is only used for test code, the Groovy dependency should be added to the `testImplementation` configuration:

.Configuration of Groovy test dependency
====
include::sample[dir="snippets/groovy/groovyDependency/kotlin",files="build.gradle.kts[tags=groovy-test-dependency]"]
include::sample[dir="snippets/groovy/groovyDependency/groovy",files="build.gradle[tags=groovy-test-dependency]"]
====

To use the Groovy library that ships with Gradle, declare a `localGroovy()` dependency. Note that different Gradle versions ship with different Groovy versions; as such, using `localGroovy()` is less safe then declaring a regular Groovy dependency.

.Configuration of bundled Groovy dependency
====
include::sample[dir="snippets/groovy/groovyDependency/kotlin",files="build.gradle.kts[tags=bundled-groovy-dependency]"]
include::sample[dir="snippets/groovy/groovyDependency/groovy",files="build.gradle[tags=bundled-groovy-dependency]"]
====

[[sec:automatic_configuration_of_groovyclasspath]]
== Automatic configuration of groovyClasspath

The `GroovyCompile` and `Groovydoc` tasks consume Groovy code in two ways: on their `classpath`, and on their `groovyClasspath`. The former is used to locate classes referenced by the source code, and will typically contain the Groovy library along with other libraries. The latter is used to load and execute the Groovy compiler and Groovydoc tool, respectively, and should only contain the Groovy library and its dependencies.

Unless a task's `groovyClasspath` is configured explicitly, the Groovy (base) plugin will try to infer it from the task's `classpath`. This is done as follows:

* If a `groovy-all(-indy)` Jar is found on `classpath`, that jar will be added to `groovyClasspath`.
* If a `groovy(-indy)` jar is found on `classpath`, and the project has at least one repository declared, a corresponding `groovy(-indy)` repository dependency will be added to `groovyClasspath`.
* Otherwise, execution of the task will fail with a message saying that `groovyClasspath` could not be inferred.

Note that the "`-indy`" variation of each jar refers to the version with `invokedynamic` support.

[[sec:groovy_convention_properties]]
== Convention properties

The Groovy plugin does not add any convention properties to the project.

[[sec:groovy_source_set_properties]]
== Source set properties

The Groovy plugin adds the following extensions to each source set in the project. You can use these properties in your build script as though they were properties of the source set object.

=== Groovy Plugin — source set properties

`groovy` — link:{groovyDslPath}/org.gradle.api.tasks.GroovySourceDirectorySet.html[GroovySourceDirectorySet] (read-only)::
_Default value_: Not null
+
The Groovy source files of this source set. Contains all `.groovy` and `.java` files found in the Groovy source directories, and excludes all other types of files.

`groovy.srcDirs` — `Set&lt;File&gt;`::
_Default value_: `[__projectDir__/src/__name__/groovy]`
+
The source directories containing the Groovy source files of this source set. May also contain Java source files for joint compilation. Can set using anything described in <<working_with_files.adoc#sec:specifying_multiple_files,Specifying Multiple Files>>.

`allGroovy` — link:{javadocPath}/org/gradle/api/file/FileTree.html[FileTree] (read-only)::
_Default value_: Not null
+
All Groovy source files of this source set. Contains only the `.groovy` files found in the Groovy source directories.

These properties are provided by a convention object of type link:{groovyDslPath}/org.gradle.api.tasks.SourceSet.html[GroovySourceSet].

The Groovy plugin also modifies some source set properties:

=== Groovy Plugin - modified source set properties

[%header%autowidth,compact]
|===
| Property name | Change
| `allJava` | Adds all `.java` files found in the Groovy source directories.
| `allSource` | Adds all source files found in the Groovy source directories.
|===


[[sec:groovyCompile]]
== GroovyCompile

The Groovy plugin adds a link:{groovyDslPath}/org.gradle.api.tasks.compile.GroovyCompile.html[GroovyCompile] task for each source set in the project.
The task type shares much with the `JavaCompile` task by extending `AbstractCompile` (see <<building_java_projects.adoc#sec:compile, the relevant Java Plugin section>>).
The `GroovyCompile` task supports most configuration options of the official Groovy compiler.
The task can also leverage the <<toolchains.adoc#toolchains,Java toolchain support>>.

.Groovy plugin - GroovyCompile properties
[%header%autowidth,compact]
|===
| Task Property | Type | Default Value

|  `classpath`
| link:{javadocPath}/org/gradle/api/file/FileCollection.html[FileCollection]
| `__sourceSet__.compileClasspath`

|  `source`
| link:{javadocPath}/org/gradle/api/file/FileTree.html[FileTree].
Can set using anything described in <<working_with_files.adoc#sec:specifying_multiple_files,Specifying Multiple Files>>.
| `__sourceSet__.groovy`

|  `destinationDirectory`
| `File`.
| `__sourceSet__.groovy.destinationDirectory`

|  `groovyClasspath`
| link:{javadocPath}/org/gradle/api/file/FileCollection.html[FileCollection]
| `groovy` configuration if non-empty; Groovy library found on `classpath` otherwise

|  `javaLauncher`
| `Property<JavaLauncher>`, see the <<toolchains.adoc#toolchains,toolchain documentation>>.
| None but will be configured if a toolchain is defined on the `java` extension.
|===

[[sec:groovy_compilation_avoidance]]
=== Compilation avoidance

_Caveat: Groovy compilation avoidance is an incubating feature since Gradle 5.6. There are known inaccuracies so please enable it at your own risk._

To enable the incubating support for Groovy compilation avoidance, add a link:{javadocPath}/org/gradle/api/initialization/Settings.html#enableFeaturePreview-java.lang.String-[`enableFeaturePreview`] to your settings file:

====
[.multi-language-sample]
=====
.settings.gradle
[source, groovy]
----
enableFeaturePreview('GROOVY_COMPILATION_AVOIDANCE')
----
=====
[.multi-language-sample]
=====
.settings.gradle.kts
[source,kotlin]
----
enableFeaturePreview("GROOVY_COMPILATION_AVOIDANCE")
----
=====
====

If a dependent project has changed in an https://en.wikipedia.org/wiki/Application_binary_interface[ABI]-compatible way (only its private API has changed), then Groovy compilation tasks will be up-to-date.
This means that if project `A` depends on project `B` and a class in `B` is changed in an ABI-compatible way (typically, changing only the body of a method), then Gradle won't recompile `A`.

See <<java_plugin.adoc#sec:java_compile_avoidance,Java compile avoidance>> for a detailed list of the types of changes that do not affect the ABI and are ignored.

However, similar to Java's annotation processing, there are various ways to https://melix.github.io/blog/2011/05/12/customizing_groovy_compilation_process.html[customize the Groovy compilation process], for which implementation details matter.
Some well-known examples are https://groovy-lang.org/metaprogramming.html#_code_generation_transformations[Groovy AST transformations].
In these cases, these dependencies must be declared separately in a classpath called `astTransformationClasspath`:

.Declaring AST transformations
====
include::sample[dir="snippets/groovy/compilationAvoidance/kotlin/ast-transformation-consumer", files="build.gradle.kts[tags=groovy-compilation-avoidance]"]
include::sample[dir="snippets/groovy/compilationAvoidance/groovy/ast-transformation-consumer", files="build.gradle[tags=groovy-compilation-avoidance]"]
====

[[sec:incremental_groovy_compilation]]
== Incremental Groovy compilation

Since 5.6, Gradle introduces an experimental incremental Groovy compiler. To enable incremental compilation for Groovy, you need:

* Enable <<groovy_plugin.adoc#sec:groovy_compilation_avoidance,Groovy compilation avoidance>>.
* Explicitly enable incremental Groovy compilation in the build script:

.Enable incremental Groovy compilation
====
include::sample[dir="snippets/groovy/incrementalCompilation/kotlin",files="buildSrc/src/main/kotlin/myproject.groovy-conventions.gradle.kts[tags=enable-groovy-incremental]"]
include::sample[dir="snippets/groovy/incrementalCompilation/groovy",files="buildSrc/src/main/groovy/myproject.groovy-conventions.gradle[tags=enable-groovy-incremental]"]
====

This gives you the following benefits:

* Incremental builds are much faster.
* If only a small set of Groovy source files are changed, only the affected source files will be recompiled.
  Classes that don't need to be recompiled remain unchanged in the output directory.
  For example, if you only change a few Groovy test classes, you don't need to recompile all Groovy test source files — only the changed ones need to be recompiled.

To understand how incremental compilation works, see <<java_plugin.adoc#sec:incremental_compile,Incremental Java compilation>> for a detailed overview.
Note that there're several differences from Java incremental compilation:

The Groovy compiler doesn't keep `@Retention` in generated annotation class bytecode (https://issues.apache.org/jira/browse/GROOVY-9185[GROOVY-9185]), thus all annotations are `RUNTIME`.
This means that changes to source-retention annotations won't trigger a full recompilation.

[[sec:incremental_groovy_compilation_known_issues]]
=== Known issues

Also see <<java_plugin.adoc#sec:incremental_compilation_known_issues,Known issues for incremental Java compilation>>.

* Changes to resources won't trigger a recompilation, this might result in some incorrectness — for example https://mrhaki.blogspot.com/2013/01/groovy-goodness-adding-extra-methods.html[Extension Modules].

[[sec:groovy_cross_compilation]]
== Compiling and testing for Java 6 or Java 7

With <<toolchains.adoc#toolchains,toolchain support>> added to `GroovyCompile`, it is possible to compile Groovy code using a different Java version than the one running Gradle.
If you also have Java source files, this will also configure `JavaCompile` to use the right Java compiler is used, as can be seen in the <<building_java_projects.adoc#sec:java_cross_compilation,Java plugin>> documentation.

=== Example: Configure Java 7 build for Groovy

====
include::sample[dir="snippets/groovy/crossCompilation/kotlin",files="build.gradle.kts[tags=groovy-cross-compilation]"]
include::sample[dir="snippets/groovy/crossCompilation/groovy",files="build.gradle[tags=groovy-cross-compilation]"]
====

