Java 插件是构建 JVM 项目的基础,它为项目增加了很多能力,例如编译,测试,打包,发布等等。
很多插件都是基于 Java 插件实现的,例如 Android 插件。
用法
使用 id 应用插件
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] | 源集的资源目录,是一个集合,可以指定多个 |
跟多的源集属性可以查看下面的文档
定义一个新的源集
源集的位置也很重要,不要在 dependencies
下面,否则对源集的依赖就将不起作用
sourceSets {
other
}
访问源集
sourceSets 是 Java 插件为 Project 增加的一个属性,可以直接使用。
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}"
}
}
为源集添加依赖
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 包。
/**
* 为 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 文件。
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 源集的源代码和资源目录为例
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 插件增加了很多依赖配置到项目中,JavaCompile 和 test 任务就可以使用这些配置将依赖文件添加到类路径并使用他们。
编译时依赖,被 implementation 取代 | |
implementation 继承自compile | 仅实现依赖性。 |
compileOnly | 仅仅编译时依赖 运行时不能用 |
compileClasspath 继承自 compile,compileOnly,implemenation | 当编译源代码时使用的编译类路径,被 compileJava 任务使用 |
annotationProcessor | 编译时使用的注解处理器 |
继承自 compile | 运行时依赖,由 runtimeOnly 取代 |
runtimeOnly | 仅运行时依赖,编译时不能用 |
runtimeClasspath 继承自 runtimeOnly,runtime,implementation | 运行时类路径包含 implementation 和仅运行时的元素 |
继承自 compile | 测试编译的依赖项,被 testImplementation 取代 |
testImplementation 继承自 testCompile,implemenation | 仅实现测试依赖 |
testCompileOnly | 编译时测试依赖,仅仅只在编译时 |
testCompileClasspath 继承自 testCompile ,testCompileOnly ,testImplementation | 测试编译类路径,当编译测试代码的时由 compileTestJava 任务使用 |
继承自 runtime,testCompile | 测试运行时依赖,由 testRuntimeOnly 取代 |
testRuntimeOnly 继承自 runtimeOnly | 测试的运行时依赖 |
testRuntimeClasspath 继承自 testRuntimeOnly,testRuntime,testImplementation | 运行测试的运行时类路径,由 test 任务使用 |
archives | 项目产生的构件(例如 jar),由 uploadArchives 使用 |
下面两张图是 main 和 test 源集的配置依赖关系
- 灰色字体:已废弃的
- 黑色字体绿色背景:可以根据配置声明依赖项。
- 灰蓝背景: 该配置用于被任务使用,而不是用于声明依赖项。
- 浅蓝色背景:任务
除了以上的配置,Java 插件为了每个源集还添加了以下配置,这些配置只针对给定源集
已废弃 | 给定源集的编译时依赖,由 sourceSet Implementation 取代 |
sourceSet Implementation extend sourceSetCompile | 实现给定源集的依赖性。由 sourceSetCompileClasspath, sourceSetRuntimeClasspath 使用。 |
sourceSetCompileOnly | 给定源集的编译时依赖,只能在编译时使用。 |
sourceSetCompileClasspath extend compilesourceSetJava | 当编译源代码时的编译类路径,被 sourceSetCompile,sourceSetCompileOnly,sourceSetImplementation 使用。 |
sourceSetAnnotationProcessor | 给定源集在编译时使用的注解处理器 |
已废弃 | 给定源集的运行时依赖,由 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