【Gradle jvm插件系列6】 Groovy插件权威详解

【Gradle jvm插件系列6】 Groovy插件权威详解

内容

• 使用
• 任务
• 项目布局
• 依赖管理
• 自动配置groovyClasspath
• 约定属性
• 源集属性
• GroovyCompile
• 增量Groovy编译
• 编译和测试Java 6或Java 7

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

请注意，如果要从API /实现分离中受益，还可以将java-library插件应用于Groovy项目。

使用

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

plugins {
    id 'groovy'
}

任务

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

• compileGroovy — GroovyCompile

  • 依赖：compileJava
  • 编译生产的Groovy源文件。

• compileTestGroovy — GroovyCompile

  • 依赖：compileTestJava
  • 编译测试的Groovy源文件。

• compileSourceSetGroovy — GroovyCompile

  • 依赖：compileSourceSetJava
  • 编译给定源集的Groovy源文件。

• groovydoc — Groovydoc

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

Groovy插件还向Java插件添加了以下任务的依赖关系。

任务名称	依赖
classes	compileGroovy
testClasses	compileTestGroovy
sourceSetClasses	compileSourceSetGroovy

项目布局

Groovy插件假定Groovy布局中显示的项目布局。所有Groovy源目录都可以包含Groovy和Java代码。Java源目录只能包含Java源代码。这些目录不需要存在或包含任何内容；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生产和测试源文件。

sourceSets {
    main {
        groovy {
            srcDirs = ['src/groovy']
        }
    }

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

依赖管理

由于Gradle的构建语言基于Groovy，并且Gradle的某些部分是用Groovy实现的，Gradle已经随附了一个Groovy库。尽管如此，Groovy项目仍然需要显式声明Groovy依赖项。这个依赖项将在编译和运行时类路径上使用。它还将用于获取Groovy编译器和Groovydoc工具。

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

repositories {
    mavenCentral()
}

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

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

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

要使用随Gradle一起提供的Groovy库，请声明localGroovy()依赖项。请注意，不同的Gradle版本随附不同的Groovy版本；因此，使用localGroovy()比声明常规Groovy依赖项更不安全。

dependencies {
    implementation localGroovy()
}

Groovy库不一定要来自远程存储库。它也可以来自本地lib目录，可能是检入源代码控制：

repositories {
    flatDir { dirs 'lib' }
}

dependencies {
    implementation module('org.codehaus.groovy:groovy:2.4.15') {
        dependency('org.ow2.asm:asm-all:5.0.3')
        dependency('antlr:antlr:2.7.7')
        dependency('commons-cli:commons-cli:1.2')
        module('org.apache.ant:ant:1.9.4') {
            dependencies('org.apache.ant:ant-junit:1.9.4@jar',
                         'org.apache.ant:ant-launcher:1.9.4')
        }
    }
}

自动配置groovyClasspath

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

除非明确配置了任务的groovyClasspath，否则Groovy（基础）插件将尝试从任务的类路径中推断出它。具体做法如下：

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

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

约定属性

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

源集属性

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

属性名	类型	默认值
groovy	GroovySourceDirectorySet（只读）	默认值：非空
groovy.srcDirs	Set	默认值：[projectDir/src/name/groovy]
allGroovy	FileTree（只读）	默认值：非空

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

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

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

GroovyCompile

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

任务属性	类型	默认值
classpath	FileCollection	sourceSet.compileClasspath
source	FileTree	可以使用任何描述多个文件的方法。
destinationDirectory	File	sourceSet.groovy.destinationDirectory
groovyClasspath	FileCollection	如果非空，则为groovy配置；否则，在类路径上找到Groovy库。
javaLauncher	Property	无，但如果在java扩展上定义了工具链，则会进行配置。

编译避免

注意：自Gradle 5.6起，Groovy编译避免是一个孵化功能。已知存在一些不准确性，请谨慎使用。

要启用对Groovy编译避免的孵化支持，将enableFeaturePreview添加到您的设置文件中：

enableFeaturePreview('GROOVY_COMPILATION_AVOIDANCE')

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

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

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

configurations { 
    astTransformation 
} 

dependencies { 
    astTransformation(project(":ast-transformation")) 
} 

tasks.withType(GroovyCompile).configureEach { 
    astTransformationClasspath.from(configurations.astTransformation) 
}

增量Groovy编译

从5.6开始，Gradle引入了一个实验性的增量Groovy编译器。要启用Groovy的增量编译，您需要：

• 启用Groovy编译避免。
• 在构建脚本中显式启用增量Groovy编译：

tasks.withType(GroovyCompile).configureEach {
    options.incremental = true
    options.incrementalAfterFailure = true
}

这样可以带来以下好处：

• 增量构建速度更快。
• 如果只更改了一小组Groovy源文件，则只有受影响的源文件将被重新编译。不需要重新编译不需要重新编译的类保持在输出目录中不变。例如，如果只更改了几个Groovy测试类，就不需要重新编译所有Groovy测试源文件 - 只需重新编译更改的部分即可。

要了解增量编译的工作原理，请参阅增量Java编译的详细概述。请注意，与Java增量编译存在一些差异：

• Groovy编译器不会在生成的注解类字节码中保留@Retention（GROOVY-9185），因此所有注解都是RUNTIME。这意味着对源代码保留的注解的更改不会触发完全重新编译。
• 已知问题：
  • 对资源的更改不会触发重新编译，这可能导致某些不正确性 - 例如扩展模块。

编译和测试Java 6或Java 7

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

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(7)
    }
}

这样可以将构建配置为Java 7 Groovy。

参考链接