Gradle Java 插件

思维导图

Java 插件是构建 JVM 项目的基础,它为项目增加了很多能力,例如编译,测试,打包,发布等等。
很多插件都是基于 Java 插件实现的,例如 Android 插件。

用法

使用 id 应用插件

1
2
3
plugins {
id 'java'
}

Source sets 源集

Java 插件引入了源集的概念,它在逻辑上表示一组用于编译执行的源文件,这些源文件可能包括源代码文件和资源文件。

一个源集有一个相关联的编译类路径和运行时类路径。

Java 插件就是通过源集的概念来管理源代码目录的。

源集的一个用途是,把源文件进行逻辑上的分组,以描述它们的目的。
例如,你可能会使用一个源集来定义一个集成测试套件,或者你可能会使用单独的源集来定义你的项目的 API 和实现类。

Java 插件提供了两个标准源集

  • main 包含了项目的源代码,被用于编译和生成 JAR 文件
  • test 包含单元测试源代码,它们将被编译并使用 JUnit 或 TestNG 来执行。

源集提供了很多属性,我这里就列出几个重要的属性:

属性 类型 默认值 描述
name - 只读 String 非空 源集的名字
output - 只读 SourceSetOutput 非空 源集的输出文件,包括它编译过的类和资源。
output.classesDirs 只读 FileCollection $buildDir/classes/java/$name

例如:build/classes/java/main
源集编译过的 class 文件目录
output.resourcesDir 只读 File $buildDir/resources/$name例如main源集:build/resources/main 源集产生的资源目录
java - 只读 SourceDirectorySet [${project.projectDir}/src/${sourceSet.name}/java] 源集的 Java 源代码 ,只包含 .java 会排除其他类型。
java.srcDirs Set src/$name/java,

例如 src/main/java
源集的 Java 源文件的源目录。是一个集合,可以设置多个源代码目录,更改源代码目录就是更改这个属性
java.outputDir File $buildDir/classes/java/$name,

e.g. build/classes/java/main
源代码编译的 class 文件输出目录
resources - 只读 SourceDirectorySet [${project.projectDir}/src/${sourceSet.name}/resources] 源集的资源,只包含资源。
resources.srcDirs Set [src/$name/resources] 源集的资源目录,是一个集合,可以指定多个

跟多的源集属性可以查看下面的文档

sourceSets DSL

sourceSets API

定义一个新的源集

源集的位置也很重要,不要在 dependencies 下面,否则对源集的依赖就将不起作用

1
2
3
sourceSets {
other
}

访问源集

sourceSets 是 Java 插件为 Project 增加的一个属性,可以直接使用。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
task outSourceSet {
doLast {
//遍历
sourceSets.all {
println "$name -> "
}
println "-----分割线----"
//单个的
println "${sourceSets.main.name} -> "
println "${sourceSets['main'].name} -> "

//一些属性
println " java.srcDirs -->${sourceSets.main.java.srcDirs}"
println " resource.srcDirs -->${sourceSets.main.resources.srcDirs}"
}
}

为源集添加依赖

1
2
3
4
5
6
7
8
9
dependencies {
// This dependency is used by the application.
implementation 'com.google.guava:guava:27.1-jre'

// Use JUnit test framework
testImplementation 'junit:junit:4.12'
//为 other 源集添加依赖
otherImplementation 'com.google.code.gson:gson:2.8.5'
}

将源集打成一个 JAR 包

创建一个 otherJar 任务,将源集的输出作为任务的文件来源。

执行这个任务即可生成 JAR 包。

1
2
3
4
5
6
7
8
9
10
11
/**
* 为 other 源集打个 jar 包
* 默认输出目录是 build/libs
* 默认名字是 [archiveBaseName]-[archiveAppendix]-[archiveVersion]-[archiveClassifier].[archiveExtension]
*/
task otherJar(type:Jar){
archiveBaseName = sourceSets.other.name
archiveVersion = '0.1.0'
destinationDirectory = file("${project.projectDir}/jar")
from sourceSets.other.output
}

为源集生成 doc

创建一个任务将源集的所有 Java 文件作为源文件。

执行这个任务即可生成 doc 文件。

1
2
3
4
5
task otherDoc(type:Javadoc){
destinationDir = file("${project.projectDir}/doc")
source sourceSets.other.allJava
title sourceSets.other.name
}

项目结构

Java 插件的默认目录结构如下所示, 无论这些文件夹中有没有内容, Java 插件都会编译里面的内容, 并处理没有的内容。

这个目录结构也是 Java 世界标准的项目目录。

目录 描述
src/main/java Java 源文件目录
src/main/resources 资源文件目录,例如 xml 和 properties 文件
src/test/java Java 测试源文件目录
src/test/resources 测试资源目录
src/sourceSet/java 给定源集的源代码目录
src/sourceSet/resources 给定源集的资源目录

更改默认目录

这里以更改 main 源集的源代码和资源目录为例

1
2
3
4
5
6
7
8
9
10
sourceSets {
main {
java {
srcDirs = ['src/java']
}
resources {
srcDirs = ['src/resources']
}
}
}

增加的任务

Java 插件为 Project 增加了很多实用的任务,如下:

  • compileJava 类型是 JavaCompile

    依赖于:所有参与编译类路径的任务,包括 jar 任务和通过项目依赖性在类路径上的项目中的任务。

    功能:使用 JDK 编译器编译生产 Java 源文件。

  • processResources Copy

    功能:复制生产资源到资源目录

  • classes

    依赖:compileJava , processResources

    这是个整合的任务,只是依赖于其他任务。其他插件可能会附加别的编译任务到这里。

  • compileTestJava JavaCompile

    依赖:classes, 以及有助于测试编译类路径的所有任务

    功能:使用 JDK 编译器编译测试 Java 源代码和资源文件

  • processTestResources Copy

    功能:复制测试资源到测试资源目录

  • testClasses

    依赖:compileTestJava , processTestResources

    这是个整合任务,只是依赖其他任务。其他扩展插件可能会将测试编译任务附加到这里。

  • jar Jar

    依赖:classes

    功能:根据主源集的类和资源,组装生产 JAR 文件。

  • javadoc JavaDoc

    依赖:classes

    功能:生成 API 文档。

  • test Test

    依赖:testClasses 以及生成测试运行时类路径的所有任务

    功能:使用 JUnit 或者 TestNG 运行单元测试

  • uploadArchives Upload

    依赖:jar 以及生辰附加在 archives{} 配置里的构件的任何其他任务。

    功能:上传 archives{} 配置里的构件包含生成的 JAR 文件到配置的仓库。

  • clean Delete

    功能:删除项目构建目录

  • clean[TaskName] Delete

    功能:删除由指定任务生成的文件。例如 cleanJar 将删除由 jar 任务产生的文件。

源集任务

你增加的每一个源集,Java 插件都会为它增加下面列出的任务:

  • compilesourceSetJava JavaCompile

    依赖:所有有助于源集编译类路径的任务。

    功能:使用 JDK 编译器编译给定源集的 Java 源文件

  • processsourceSetResources Copy

    功能:复制给定源集的资源到资源目录

  • sourceSetClasses Task

    依赖:compilesourceSetJava , processsourceSetResources

    功能:准备给定的源集的类和资源以进行打包和执行。一些扩展插件可能会为给定源集附加编译任务到这里

生命周期任务

Java 插件将它的一些任务附加到基础插件(Java插件自动应用)定义的生命周期任务上。

它还添加了一些其他的生命周期任务:

  • assemble

    依赖:jar, 以及创建附加到归档配置的工件的所有其他任务。

    汇总项目中所有归档的聚合任务。 这个任务是基础插件(Base)里定义的。

  • check

    依赖:test

    汇总项目中的验证任务,例如运行测试。一些插件会增加自己的验证任务到这里。这个任务是基础插件(Base) 里定义的。

  • build

    依赖:check, assemble

    聚合执行项目完整构建的任务。这个任务是基础插件(Base) 里定义的。

  • buildNeeded

    依赖:build ,以及在testRuntimeClasspath配置中依赖的所有项目中的buildNeeded任务。

    执行项目本身及其依赖的所有项目的完整构建。

  • buildDependents

    依赖:build, 以及在 testRuntimeClasspath 配置中依赖此项目的所有项目的 buildDependents 任务

    执行项目本身以及依赖于它的所有项目的完整构建。

  • buildConfigName -任务规则

    依赖:生成附加到命名- ConfigName -配置的工件的所有任务

    为指定的配置组装工件。这个规则是在基础插件增加的。

  • uploadConfigName -任务规则,类型:Upload

    依赖:生成附加到命名- ConfigName -配置的工件的所有任务

    在指定的配置里组装和上传构件。这个规则是在基础插件增加的。

下面的图展示了这些任务的关系

Java插件任务图

依赖管理

Java 插件增加了很多依赖配置到项目中,JavaCompile 和 test 任务就可以使用这些配置将依赖文件添加到类路径并使用他们。

依赖配置 描述
compile 编译时依赖,被 implementation 取代
implementation 继承自compile 仅实现依赖性。
compileOnly 仅仅编译时依赖 运行时不能用
compileClasspath 继承自 compile,compileOnly,implemenation 当编译源代码时使用的编译类路径,被 compileJava 任务使用
annotationProcessor 编译时使用的注解处理器
runtime 继承自 compile 运行时依赖,由 runtimeOnly 取代
runtimeOnly 仅运行时依赖,编译时不能用
runtimeClasspath 继承自 runtimeOnly,runtime,implementation 运行时类路径包含 implementation 和仅运行时的元素
testCompile 继承自 compile 测试编译的依赖项,被 testImplementation 取代
testImplementation 继承自 testCompile,implemenation 仅实现测试依赖
testCompileOnly 编译时测试依赖,仅仅只在编译时
testCompileClasspath 继承自 testCompile ,testCompileOnly ,testImplementation 测试编译类路径,当编译测试代码的时由 compileTestJava 任务使用
testRuntime 继承自 runtime,testCompile 测试运行时依赖,由 testRuntimeOnly 取代
testRuntimeOnly 继承自 runtimeOnly 测试的运行时依赖
testRuntimeClasspath 继承自 testRuntimeOnly,testRuntime,testImplementation 运行测试的运行时类路径,由 test 任务使用
archives 项目产生的构件(例如 jar),由 uploadArchives 使用

下面两张图是 main 和 test 源集的配置依赖关系

  • 灰色字体:已废弃的
  • 黑色字体绿色背景:可以根据配置声明依赖项。
  • 灰蓝背景: 该配置用于被任务使用,而不是用于声明依赖项。
  • 浅蓝色背景:任务

main

test

除了以上的配置,Java 插件为了每个源集还添加了以下配置,这些配置只针对给定源集

依赖配置 描述
sourceSetCompile 已废弃 给定源集的编译时依赖,由 sourceSetImplementation 取代
sourceSetImplementation extend sourceSetCompile 实现给定源集的依赖性。由 sourceSetCompileClasspath, sourceSetRuntimeClasspath 使用。
sourceSetCompileOnly 给定源集的编译时依赖,只能在编译时使用。
sourceSetCompileClasspath extend compilesourceSetJava 当编译源代码时的编译类路径,被 sourceSetCompile,sourceSetCompileOnly,sourceSetImplementation 使用。
sourceSetAnnotationProcessor 给定源集在编译时使用的注解处理器
sourceSetRuntime 已废弃 给定源集的运行时依赖,由 sourceSetRuntimeOnly 取代
sourceSetRuntimeOnly 给定源集的运行时依赖,仅仅是运行时的
sourceSetRuntimeClasspath extends sourceSetRuntimeOnly ,sourceSetRuntime,sourceSetImplementation 给定源集的运行时类路径,包含 implement 和 runtime 的元素。

增加的属性

Java 插件为项目增加了很多新的属性,可以在脚本中直接使用这些属性。

下面是一些我认为比较重要的属性:

属性 类型 默认值 描述
sourceSets 只读 SourceSetContainer 非空 包含项目的源集
sourceCompatibility JavaVersion 当前 JVM 的版本 编译 Java 源代码时使用的 Java 版本,可以是一个 数值或者字符串,例如 ‘1.8’ 或者 1.8
targetCompatibility JavaVersion sourceCompatibility 生成 class 文件的版本,可以是一个 数值或者字符串,例如 ‘1.8’ 或者 1.8
archivesBaseName String 归档的文件使用的名字,例如 JAR 和 ZIP 文件
manifest Manifest 一个空的清单 包含所有 JAR 文件的清单。
libsDirName String libs 项目生成的库的存放目录,项目的相对路径。

更多的属性可以查看文档 Convention properties

学习资料:


佛系编码 wechat
微信扫一扫,关注我的公众号
坚持原创技术分享,您的支持将鼓励我继续创作!