Groovy 插件扩展了 Java 插件，以支持 Groovy 项目。它可以处理 Groovy 代码、混合 Groovy 和 Java 代码，甚至纯 Java 代码（尽管我们不一定建议将其用于后者）。该插件支持联合编译，允许您自由地混合和匹配 Groovy 和 Java 代码，并支持双向依赖。例如，一个 Groovy 类可以扩展一个 Java 类，而该 Java 类又可以扩展一个 Groovy 类。这使得可以为工作选择最佳语言，并在需要时用另一种语言重写任何类。

请注意，如果您想受益于 API/实现分离，您也可以将 java-library 插件应用于您的 Groovy 项目。

用法

要使用 Groovy 插件，请在您的构建脚本中包含以下内容

示例 1. 使用 Groovy 插件
build.gradle.kts
plugins {
    groovy
}
build.gradle
plugins {
    id 'groovy'
}

任务

Groovy 插件向项目添加以下任务。有关更改对 Java 编译任务的依赖项的信息，请参见此处。

compileGroovy — GroovyCompile

依赖于：compileJava

编译生产 Groovy 源文件。

compileTestGroovy — GroovyCompile

依赖于：compileTestJava

编译测试 Groovy 源文件。

compileSourceSetGroovy — GroovyCompile

依赖于：compileSourceSetJava

编译给定源集的 Groovy 源文件。

groovydoc — Groovydoc

为生产 Groovy 源文件生成 API 文档。

Groovy 插件向 Java 插件添加的任务添加以下依赖项。

表 1. Groovy 插件 - 附加任务依赖项
任务名称 依赖于

类

compileGroovy

测试类

compileTestGroovy

sourceSet类

compileSourceSetGroovy
groovyPluginTasks
图 1. Groovy 插件 - 任务

项目布局

Groovy 插件假定 Groovy 布局 中所示的项目布局。所有 Groovy 源目录都可以包含 Groovy 和 Java 代码。Java 源目录只能包含 Java 源代码。[1] 这些目录都不需要存在或包含任何内容；Groovy 插件将简单地编译它找到的任何内容。

src/main/java

生产 Java 源文件。

src/main/resources

生产资源，例如 XML 和属性文件。

src/main/groovy

生产 Groovy 源文件。也可以包含用于联合编译的 Java 源文件。

src/test/java

测试 Java 源文件。

src/test/resources

测试资源。

src/test/groovy

测试 Groovy 源文件。也可以包含用于联合编译的 Java 源文件。

src/sourceSet/java

名为 sourceSet 的源集的 Java 源文件。

src/sourceSet/resources

名为 sourceSet 的源集的资源。

src/sourceSet/groovy

给定源集的 Groovy 源文件。也可以包含用于联合编译的 Java 源文件。

更改项目布局

就像 Java 插件一样，Groovy 插件允许您为 Groovy 生产和测试源文件配置自定义位置。

示例 2. 自定义 Groovy 源布局
build.gradle.kts
sourceSets {
    main {
        groovy {
            setSrcDirs(listOf("src/groovy"))
        }
    }

    test {
        groovy {
            setSrcDirs(listOf("test/groovy"))
        }
    }
}
build.gradle
sourceSets {
    main {
        groovy {
            srcDirs = ['src/groovy']
        }
    }

    test {
        groovy {
            srcDirs = ['test/groovy']
        }
    }
}

依赖管理

由于 Gradle 的构建语言基于 Groovy，Gradle 已经自带了一个 Groovy 库。尽管如此，Groovy 项目仍需要明确声明一个 Groovy 依赖。这个依赖将在编译和运行时类路径上使用。它还将用于分别获取 Groovy 编译器和 Groovydoc 工具。

如果 Groovy 用于生产代码，Groovy 依赖项应添加到 implementation 配置中

示例 3. Groovy 依赖项的配置
build.gradle.kts
repositories {
    mavenCentral()
}

dependencies {
    implementation("org.codehaus.groovy:groovy-all:2.4.15")
}
build.gradle
repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.codehaus.groovy:groovy-all:2.4.15'
}

如果 Groovy 仅用于测试代码，则 Groovy 依赖项应添加到 testImplementation 配置中

示例 4. Groovy 测试依赖项的配置
build.gradle.kts
dependencies {
    testImplementation("org.codehaus.groovy:groovy-all:2.4.15")
}
build.gradle
dependencies {
    testImplementation 'org.codehaus.groovy:groovy-all:2.4.15'
}

要使用 Gradle 自带的 Groovy 库，请声明 localGroovy() 依赖项。请注意，不同的 Gradle 版本附带不同的 Groovy 版本；因此，使用 localGroovy() 不如声明常规 Groovy 依赖项安全。

示例 5. 捆绑 Groovy 依赖项的配置
build.gradle.kts
dependencies {
    implementation(localGroovy())
}
build.gradle
dependencies {
    implementation localGroovy()
}

groovyClasspath 的自动配置

GroovyCompile 和 Groovydoc 任务通过两种方式使用 Groovy 代码：在它们的 classpath 上，以及在它们的 groovyClasspath 上。前者用于定位源代码引用的类，通常会包含 Groovy 库以及其他库。后者用于分别加载和执行 Groovy 编译器和 Groovydoc 工具，并且应该只包含 Groovy 库及其依赖项。

除非明确配置了任务的 groovyClasspath，否则 Groovy (base) 插件将尝试从任务的 classpath 推断它。操作如下：

  • 如果在 classpath 上找到 groovy-all(-indy) Jar，则该 jar 将添加到 groovyClasspath 中。

  • 如果在 classpath 上找到 groovy(-indy) jar，并且项目至少声明了一个仓库，则相应的 groovy(-indy) 仓库依赖项将被添加到 groovyClasspath 中。

  • 否则，任务的执行将失败，并显示一条消息，指出无法推断 groovyClasspath。

请注意，每个 jar 的“-indy”变体指的是支持 invokedynamic 的版本。

约定属性

Groovy 插件没有向项目添加任何约定属性。

源集属性

Groovy 插件为项目中的每个源集添加了以下扩展。您可以在构建脚本中使用这些属性，就像它们是源集对象的属性一样。

Groovy 插件 — 源集属性

groovy — GroovySourceDirectorySet（只读）

默认值：不为空

此源集的 Groovy 源文件。包含 Groovy 源目录中找到的所有 .groovy 和 .java 文件，并排除所有其他类型的文件。

groovy.srcDirs — Set<File>

默认值：[项目目录/src/名称/groovy]

包含此源集 Groovy 源文件的源目录。也可以包含用于联合编译的 Java 源文件。可以使用 指定多个文件 中描述的任何内容进行设置。

Groovy 插件还修改了一些源集属性

Groovy 插件 - 修改后的源集属性

属性名称 更改

所有Java

添加 Groovy 源目录中找到的所有 .java 文件。

allSource

添加 Groovy 源目录中找到的所有源文件。

GroovyCompile

Groovy 插件为项目中的每个源集添加了一个 GroovyCompile 任务。该任务类型通过扩展 AbstractCompile 与 JavaCompile 任务共享很多内容（参见 相关 Java 插件部分）。GroovyCompile 任务支持官方 Groovy 编译器的T大多数配置选项。该任务还可以利用 Java 工具链支持。

表 2. Groovy 插件 - GroovyCompile 属性
任务属性 类型 默认值

类路径

文件集合

源集.compileClasspath

源

FileTree。可以使用 指定多个文件 中描述的任何内容进行设置。

源集.groovy

目标目录

文件.

源集.groovy.目标目录

groovy类路径

文件集合

如果非空，则为 groovy 配置；否则为 classpath 中找到的 Groovy 库

Java启动器

Property<JavaLauncher>，参见工具链文档。

无，但如果在 java 扩展上定义了工具链，则会进行配置。

编译避免

警告：Groovy 编译避免是 Gradle 5.6 以来的一个孵化功能。已知存在不准确性，请自行承担风险启用。

要启用 Groovy 编译避免的孵化支持，请在您的设置文件中添加 enableFeaturePreview

settings.gradle
enableFeaturePreview('GROOVY_COMPILATION_AVOIDANCE')
settings.gradle.kts
enableFeaturePreview("GROOVY_COMPILATION_AVOIDANCE")

如果一个依赖项目以 ABI 兼容的方式（只有其私有 API 发生更改）发生更改，则 Groovy 编译任务将是最新状态。这意味着如果项目 A 依赖于项目 B，并且 B 中的某个类以 ABI 兼容的方式更改（通常只更改方法的实现），则 Gradle 不会重新编译 A。

有关不影响 ABI 且被忽略的更改类型的详细列表，请参阅 Java 编译避免。

但是，与 Java 的注解处理类似，有多种方法可以自定义 Groovy 编译过程，其中实现细节很重要。一些著名的例子是Groovy AST 转换。在这些情况下，这些依赖项必须在名为 astTransformationClasspath 的类路径中单独声明。

示例 6. 声明 AST 转换
build.gradle.kts
val astTransformation by configurations.creating
dependencies {
    astTransformation(project(":ast-transformation"))
}
tasks.withType<GroovyCompile>().configureEach {
    astTransformationClasspath.from(astTransformation)
}
build.gradle
configurations { astTransformation }
dependencies {
    astTransformation(project(":ast-transformation"))
}
tasks.withType(GroovyCompile).configureEach {
    astTransformationClasspath.from(configurations.astTransformation)
}

增量式 Groovy 编译

自 5.6 版本以来，Gradle 引入了实验性的增量 Groovy 编译器。要为 Groovy 启用增量编译，您需要：

示例 7. 启用增量 Groovy 编译
buildSrc/src/main/kotlin/myproject.groovy-conventions.gradle.kts
tasks.withType<GroovyCompile>().configureEach {
    options.isIncremental = true
    options.incrementalAfterFailure = true
}
buildSrc/src/main/groovy/myproject.groovy-conventions.gradle
tasks.withType(GroovyCompile).configureEach {
    options.incremental = true
    options.incrementalAfterFailure = true
}

这将为您带来以下好处

  • 增量构建速度快得多。

  • 如果只更改少量 Groovy 源文件，则只会重新编译受影响的源文件。不需要重新编译的类在输出目录中保持不变。例如，如果您只更改了几个 Groovy 测试类，则不需要重新编译所有 Groovy 测试源文件 — 只需重新编译已更改的文件即可。

要了解增量编译的工作原理，请参阅 增量 Java 编译 以获取详细概述。请注意，与 Java 增量编译有以下几个不同之处：

Groovy 编译器不会在生成的注解类字节码中保留 @Retention（GROOVY-9185），因此所有注解都是 RUNTIME。这意味着对源保留注解的更改不会触发完全重新编译。

已知问题

另请参阅 增量 Java 编译的已知问题。

  • 对资源的更改不会触发重新编译，这可能会导致一些不正确性——例如 Extension Modules。

为 Java 6 或 Java 7 编译和测试

通过向 GroovyCompile 添加工具链支持，可以使用与运行 Gradle 的 Java 版本不同的 Java 版本编译 Groovy 代码。如果您也有 Java 源文件，这将配置 JavaCompile 以使用正确的 Java 编译器，如 Java 插件 文档中所述。

示例：为 Groovy 配置 Java 7 构建

build.gradle.kts
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(7)
    }
}
build.gradle
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(7)
    }
}
1. Gradle 使用 Russel Winder 的 Gant 工具引入的相同约定。