跳到主要内容

2024-07-01

一言

欲买桂花同载酒，荒泷天下第一斗。 --- 《原神》 · 鱼鱼

今天看了一下gradle-jooq-plugin的源码来学习一下gradle和gradle插件

settings.gradle​

备注

因为不打算使用 Gralde Enterprise ，所以忽略了相关配置

这段代码是一个Gradle配置文件，主要用于配置缓存设置。下面是对每一部分的详细讲解：

plugins {
    id 'org.gradle.toolchains.foojay-resolver-convention' version '0.8.0'
}

这一部分是插件声明

  • org.gradle.toolchains.foojay-resolver-convention：用于工具链解析的插件。
buildCache {
    local {
        enabled = true
    }
}

这一部分是构建缓存的配置：

  • local { enabled = true }：启用了本地缓存。
rootProject.name = 'gradle-jooq-plugin'

最后一行设置了根项目的名称为 gradle-jooq-plugin。

gradle.properties​

gradle.properties 文件是Gradle项目的配置文件，用于定义全局属性和设置。这些设置可以影响整个构建过程的行为。具体来说，这个文件中定义的三个属性的作用如下：

  1. org.gradle.caching=true

    • 作用：启用构建缓存。
    • 详细说明：构建缓存可以显著加快构建速度，通过存储和重用以前构建过的任务的输出结果。如果某些任务的输入和环境没有变化，Gradle可以直接使用缓存中的结果，而不需要重新执行这些任务。

  2. org.gradle.parallel=true

    • 作用：启用并行构建。
    • 详细说明：并行构建允许Gradle同时执行多个独立的任务，这样可以充分利用多核处理器的性能，缩短构建时间。这对于大型项目尤为有用，可以显著提高构建效率。

  3. org.gradle.jvmargs=-Duser.language=en -Duser.country=US -Dfile.encoding=UTF-8

    • 作用：配置JVM参数。
    • 详细说明：这行设置了JVM的启动参数，具体包括：
      • -Duser.language=en：设置语言为英语。
      • -Duser.country=US：设置国家为美国。
      • -Dfile.encoding=UTF-8：设置文件编码为UTF-8。
    • 影响：这些设置确保构建过程使用统一的语言、区域设置和文件编码，避免由于不同的语言、区域设置或文件编码导致的构建问题或结果不一致。

总结来说，这些设置是为了优化构建性能和确保构建环境的一致性。启用构建缓存和并行构建可以加快构建速度，而统一的JVM参数设置则可以确保构建过程中的一致性和稳定性。

提示

org.gradle.caching 和 org.gradle.parallel= 默认都是 false

build.gradle​

这段代码是一个Gradle构建脚本，用于配置一个Java Gradle插件项目。以下是详细讲解：

插件声明​

plugins {
    id 'java-gradle-plugin'
    id 'com.gradle.plugin-publish' version '1.2.1'
    id 'org.nosphere.gradle.github.actions' version '1.4.0'
    id 'groovy'
}
  • java-gradle-plugin: 用于开发Gradle插件的插件。
  • com.gradle.plugin-publish: 用于发布Gradle插件的插件。
  • org.nosphere.gradle.github.actions: 用于在GitHub Actions中使用Gradle的插件。
  • groovy: 添加对Groovy语言的支持。

项目属性​

group = 'nu.studer'
version = '9.0.1-DEV'
  • group: 项目的组织标识。
  • version: 项目的版本号。

配置依赖解析策略​

configurations.all { Configuration c ->
    c.resolutionStrategy.eachDependency { DependencyResolveDetails details ->
        if (details.requested.group == 'jakarta.xml.bind' && details.requested.name == 'jakarta.xml.bind-api') {
            details.useVersion '3.0.1'
        }
    }
}
  • 强制将 jakarta.xml.bind:jakarta.xml.bind-api 依赖的版本设置为 3.0.1。

仓库配置​

repositories {
    mavenCentral()
}
  • 使用 Maven Central 作为依赖的仓库。

依赖声明​

dependencies {
    api 'org.jooq:jooq-codegen:3.19.1'
    runtimeOnly 'org.glassfish.jaxb:jaxb-core:3.0.2'
    runtimeOnly 'org.glassfish.jaxb:jaxb-runtime:3.0.2'
    testImplementation 'com.h2database:h2:2.2.224'
    testImplementation 'org.spockframework:spock-core:2.3-groovy-3.0'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}
  • api: 编译时和运行时都需要的依赖。
  • runtimeOnly: 仅在运行时需要的依赖。
  • testImplementation: 测试时需要的依赖。
  • testRuntimeOnly: 仅在测试运行时需要的依赖。

Java工具链配置​

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
        vendor = JvmVendorSpec.BELLSOFT
    }
}
  • 设置Java工具链，指定使用BellSoft的JDK 17。

编译任务配置​

tasks.withType(AbstractCompile).configureEach {
    options.compilerArgs <<
        "-Werror" <<
        "-Xlint:all"
}
  • 为所有编译任务配置编译器参数，使所有警告被视为错误，并启用所有Lint警告。

测试任务配置​

tasks.withType(Test).configureEach {
    maxParallelForks = 1 // there is currently only a single test class
    useJUnitPlatform()

    String testJavaRuntimeVersion = findProperty('testJavaRuntimeVersion') ?: '17'
    String testGradleVersion = findProperty('testGradleVersion') ?: GradleVersion.current().version

    javaLauncher.set(javaToolchains.launcherFor { spec ->
        spec.languageVersion.set(JavaLanguageVersion.of(testJavaRuntimeVersion))
        buildScan.value(identityPath.path + "#jvmVersion", testJavaRuntimeVersion)
    } as Provider<? extends JavaLauncher>)

    systemProperty 'testContext.gradleVersion', testGradleVersion
    buildScan.value(identityPath.path + "#gradleVersion", testGradleVersion)

    def incompatibleJavaVsGradleVersions = parseInt(testJavaRuntimeVersion) > 16 && GradleVersion.version(testGradleVersion) < GradleVersion.version('7.3') ||
        parseInt(testJavaRuntimeVersion) > 15 && GradleVersion.version(testGradleVersion) < GradleVersion.version('7.0')
    if (incompatibleJavaVsGradleVersions) {
        enabled = false
    }
}
  • 配置测试任务：
    • maxParallelForks = 1: 限制并行测试任务的数量为1。
    • useJUnitPlatform(): 使用JUnit Platform进行测试。
    • 动态设置测试使用的Java版本和Gradle版本，并根据兼容性检查是否启用测试任务。

具体解释​

  1. tasks.withType(Test).configureEach { ... }：

    • 这一行代码的作用是找到所有类型为 Test 的任务，并对每一个任务应用下面的配置。

  2. maxParallelForks = 1：

    • 设置并行测试任务的数量为1。这意味着测试任务将会串行执行。注释表明当前只有一个测试类，因此只需要一个并行分叉。

  3. useJUnitPlatform()：

    • 使用JUnit平台来运行测试。这对于支持JUnit 5及其新特性是必要的。

  4. String testJavaRuntimeVersion = findProperty('testJavaRuntimeVersion') ?: '21'：

    • 获取属性 testJavaRuntimeVersion 的值，如果没有设置则使用默认值 '21'。

  5. String testGradleVersion = findProperty('testGradleVersion') ?: GradleVersion.current().version：

    • 获取属性 testGradleVersion 的值，如果没有设置则使用当前Gradle版本。

  6. javaLauncher.set(javaToolchains.launcherFor { spec -> ... } as Provider<? extends JavaLauncher>)：

    • 使用指定的Java版本配置Java启动器：
      • spec.languageVersion.set(JavaLanguageVersion.of(testJavaRuntimeVersion))：设置Java语言版本。
      • buildScan.value(identityPath.path + "#jvmVersion", testJavaRuntimeVersion)：将Java版本添加到构建扫描中。

  7. systemProperty 'testContext.gradleVersion', testGradleVersion：

    • 设置系统属性 testContext.gradleVersion，其值为指定的Gradle版本。

  8. buildScan.value(identityPath.path + "#gradleVersion", testGradleVersion)：

    • 将Gradle版本添加到构建扫描中。

  9. 版本兼容性检查：

    • 通过以下条件检查Java版本和Gradle版本的兼容性： 
      def incompatibleJavaVsGradleVersions = parseInt(testJavaRuntimeVersion) > 16 && GradleVersion.version(testGradleVersion) < GradleVersion.version('7.3') ||
                                             parseInt(testJavaRuntimeVersion) > 15 && GradleVersion.version(testGradleVersion) < GradleVersion.version('7.0')
    • 如果Java版本大于16且Gradle版本小于7.3，或者Java版本大于15且Gradle版本小于7.0，则认为不兼容。

  10. 禁用不兼容的测试任务：

    • 如果检测到不兼容的Java和Gradle版本，则禁用测试任务： 
      if (incompatibleJavaVsGradleVersions) {
          enabled = false
      }

语法解释​

javaLauncher.set(javaToolchains.launcherFor { spec ->
    spec.languageVersion.set(JavaLanguageVersion.of(testJavaRuntimeVersion))
    buildScan.value(identityPath.path + "#jvmVersion", testJavaRuntimeVersion)
} as Provider<? extends JavaLauncher>)

  1. javaLauncher.set(...)：

    • javaLauncher 是测试任务的一个属性，用于指定测试任务使用的Java启动器。set 方法将启动器设置为括号中的值。

  2. javaToolchains.launcherFor { spec -> ... }：

    • javaToolchains 是Gradle的一个对象，用于管理Java工具链。
    • launcherFor 方法接受一个闭包（在Groovy中，闭包类似于匿名函数），用于配置启动器规范 spec，并返回一个 JavaLauncher 的 Provider（一个可以延迟求值的容器）。

  3. 闭包 spec -> ...：

    • 闭包内部是对 spec（启动器规范）的配置： 
      spec.languageVersion.set(JavaLanguageVersion.of(testJavaRuntimeVersion))
    • spec.languageVersion.set(JavaLanguageVersion.of(testJavaRuntimeVersion))：设置启动器使用的Java语言版本。testJavaRuntimeVersion 是一个变量，表示所需的Java版本。这里将其转换为 JavaLanguageVersion 对象。

  4. buildScan.value(identityPath.path + "#jvmVersion", testJavaRuntimeVersion)：

    • 这一行将Java版本信息添加到构建扫描中。buildScan 是一个用于记录构建信息的对象，value 方法用于添加键值对。
    • identityPath.path + "#jvmVersion" 生成一个唯一的键，将其与 testJavaRuntimeVersion 关联。

  5. as Provider<? extends JavaLauncher>：

    • 这部分是类型转换。launcherFor 方法返回的是一个 Provider，它是一个可以延迟求值的对象。as Provider<? extends JavaLauncher> 将其明确转换为 Provider 类型。

Javadoc任务配置​

tasks.withType(Javadoc).configureEach {
    options.addStringOption('Xdoclint:none', '-quiet')
}
  • 为Javadoc任务配置参数，禁用所有文档检查并使其静默运行。

Gradle插件发布配置​

gradlePlugin {
    website = 'https://github.com/etiennestuder/gradle-jooq-plugin'
    vcsUrl = 'https://github.com/etiennestuder/gradle-jooq-plugin'
    plugins {
        pluginDevPlugin {
            id = 'nu.studer.jooq'
            displayName = 'gradle-jooq-plugin'
            description = 'Gradle plugin that integrates jOOQ.'
            tags.set(['jooq'])
            implementationClass = 'nu.studer.gradle.jooq.JooqPlugin'
        }
    }
}
  • 配置插件发布信息：
    • website: 插件的官网地址。
    • vcsUrl: 插件的版本控制系统地址。
    • plugins: 定义插件的具体信息，包括ID、名称、描述、标签和实现类。

插件验证任务配置​

tasks.withType(ValidatePlugins.class).configureEach {
    failOnWarning = true
    enableStricterValidation = true
}
  • 为插件验证任务配置严格的验证规则，确保任何警告都会导致构建失败。

这段代码详细配置了Gradle插件项目的各个方面，包括依赖管理、任务配置和插件发布，确保项目构建和测试过程中的一致性和可靠性。