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 库。尽管如此，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，并且项目至少声明了一个仓库，则相应的 groovy(-indy) 仓库依赖项将添加到 groovyClasspath。
否则，任务的执行将失败，并显示一条消息，指出无法推断 groovyClasspath。

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

约定属性

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

Source set 属性

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

Groovy 插件 — source set 属性

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 任务。任务类型与 JavaCompile 任务共享很多，通过扩展 AbstractCompile（请参见相关的 Java 插件部分）。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 文件中

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

启用 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。这意味着对 source-retention 注解的更改不会触发完全重新编译。

已知问题

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

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

为 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 工具引入的约定相同的约定。

此页是否对您有帮助？