Groovy 插件 - Gradle 中文

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 插件 - 其他任务依赖关系
任务名称	依赖于
`classes`	`compileGroovy`
`testClasses`	`compileTestGroovy`
`sourceSetClasses`	`compileSourceSetGroovy`

图 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 中实现，因此 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（基本）插件将尝试从任务的 classpath 推断它。这将按如下方式完成

如果在 classpath 中找到 groovy-all(-indy) Jar，则该 jar 将被添加到 groovyClasspath 中。
如果在 classpath 中找到 groovy(-indy) jar，并且该项目至少声明了一个存储库，则将向 groovyClasspath 添加一个相应的 groovy(-indy) 存储库依赖项。
否则，任务执行将失败，并显示一条消息，指出无法推断 groovyClasspath。

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

约定属性

Groovy 插件不会向项目添加任何约定属性。

源集属性

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

Groovy 插件 — 源集属性

groovy — GroovySourceDirectorySet（只读）: 默认值：非空

此源集的 Groovy 源文件。包含在 Groovy 源目录中找到的所有 .groovy 和 .java 文件，并排除所有其他类型的文件。
groovy.srcDirs — Set<File>: 默认值：[projectDir/src/name/groovy]

包含此源集的 Groovy 源文件的源目录。还可能包含用于联合编译的 Java 源文件。可以使用指定多个文件中描述的任何内容进行设置。
allGroovy — FileTree（只读）: 默认值：非空

此源集的所有 Groovy 源文件。仅包含在 Groovy 源目录中找到的 .groovy 文件。

这些属性由类型为 GroovySourceSet 的约定对象提供。

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

Groovy 插件 - 修改的源集属性

属性名称更改

属性名称	更改
`allJava`	添加在 Groovy 源目录中找到的所有 `.java` 文件。
`allSource`	添加在 Groovy 源目录中找到的所有源文件。

allJava

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

allSource

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

GroovyCompile

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

表 2. Groovy 插件 - GroovyCompile 属性
任务属性	类型	默认值
`classpath`	FileCollection	`sourceSet.compileClasspath`
`source`	FileTree。可以使用指定多个文件中描述的任何内容进行设置。	`sourceSet.groovy`
`destinationDirectory`	`File`.	`sourceSet.groovy.destinationDirectory`
`groovyClasspath`	FileCollection	非空时为 `groovy` 配置；否则为在 `classpath` 上找到的 Groovy 库
`javaLauncher`	`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。

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

但是，与 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 启用增量编译，您需要

启用 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 编译的已知问题。

对资源的更改不会触发重新编译，这可能会导致一些不正确的情况——例如扩展模块。

为 Java 6 或 Java 7 编译和测试

通过将工具链支持添加到 GroovyCompile，可以使用与运行 Gradle 不同的 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 工具引入的相同约定。

此页面是否有用？