Gradle Java 插件

思维导图

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

用法

使用 id 应用插件

plugins {
    id 'java'
}

Source sets 源集

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

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

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

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

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

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

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

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

sourceSets DSL

sourceSets API

定义一个新的源集

源集的位置也很重要，不要在 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 世界标准的项目目录。

更改默认目录

这里以更改 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插件任务图

依赖管理

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

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

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

main

test

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

增加的属性

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

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

更多的属性可以查看文档 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