Gradle Java plug-in

JVM Java plug-in is the basis for building projects, it adds a lot of capacity for the project, such as compiling, testing, packaging, publishing, and so on.

Many plug-ins are Java-based plug-in implementation, such as Android plugin.

usage

Use application plug-id

plugins {
    id 'java'
}

Source sets the set of source

Introduced the concept of Java source plug set which represents the source files used to compile a set of logically executing, the source file may include the source and resource files.

It has a set of compiler-based source runtime class path and a path associated.

Java plug-in is through the concept of source set to manage the source code directory.

Use set is a source, the source file on a logical grouping to describe their purpose.
For example, you might use a source to define a set of integrated test suite, or you may use a single set of source API to define and implement a class of your project.

Java plug-in provides a set of two standard sources

• comprising the main source code for the project, and is used to generate a JAR file compiled
• test means comprising test source code, which will be compiled and executed using JUnit or TestNG.

Source collection provides many properties, I am here to list a few important attributes:

Attributes	Types of	Defaults	description
name - Read-only	String	non empty	Set the name of the source
output - read-only	SourceSetOutput	non empty	Set output file source, including its compiled classes and resources.
output.classesDirs read-only	FileCollection	$buildDir/classes/java/$name 例如：build/classes/java/main	Source collection compiled class files directory
output.resourcesDir read-only	File	$ BuildDir / resources / $ name e.g. main source set: build / resources / main	Set source generated resource directory
java - read-only	SourceDirectorySet	[${project.projectDir}/src/${sourceSet.name}/java]	Java source code source set, containing only .java would exclude the other types.
java.srcDirs	Set	src / $ name / java, e.g. src / main / java	Source Java source directory source file set. Is a collection, you can set up multiple source code directory, change the source code directory is to change this property
java.outputDir	File	$buildDir/classes/java/$name, e.g. build/classes/java/main	Source code compiled class file output directory
resources - read-only	SourceDirectorySet	[${project.projectDir}/src/${sourceSet.name}/resources]	Source set of resources, contains only resource.
resources.srcDirs	Set	[src/$name/resources]	Resource Directory source set is a collection, you can specify multiple

With multi-source set of properties You can view the following document

sourceSets DSL

sourceSets API

Define a new set of source

Set the location of the source is also important, not the dependenciesnext, or the dependency on the set will not work

sourceSets {
    other
}

Access to the source set

sourceSets is a Java plug-in for Project added a property can be used directly.

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}"
    }
}

Adding the source current dependent

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'
}

A current source labeled JAR package

OtherJar create a task, the source output set as a task source file.

Perform this task to generate JAR package.

/**
 * 为 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
}

Generating a set of source doc

Create a task for all Java source file as a set of source files.

Perform this task to generate doc file.

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

Project structure

The default directory structure of the Java plug-in is as follows, regardless folder has no content, will compile the Java plug-in inside the content, and the content is not processed.

This directory structure is also Java world standard project directory.

table of Contents	description
src/main/java	Java source files directory
src/main/resources	Resource directories, such as xml and properties files
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 任务就可以使用这些配置将依赖文件添加到类路径并使用他们。

依赖配置	描述
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 源集的配置依赖关系

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

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

依赖配置	描述
sourceSetCompile 已废弃	给定源集的编译时依赖，由 sourceSet Implementation 取代
sourceSet Implementation 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

学习资料：

• https://wiki.jikexueyuan.com/project/gradle/java-package.html
• http://benweizhu.github.io/blog/2015/01/31/deep-into-gradle-in-action-2/
• https://docs.gradle.org/current/userguide/java_plugin.html
• https://docs.gradle.org/current/userguide/building_java_projects.html