Skip to main content

2024-07-01

One-liner

To buy sweet osmanthus and carry wine together, Arataki is the best fighter in the world. --- "Genshin Impact" · Yoimiya

Today, I looked at the gradle-jooq-plugin source code to learn about Gradle and Gradle plugins.

settings.gradle​

This code snippet is a Gradle configuration file primarily used to configure caching settings. Below is a detailed explanation of each part:

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

This section declares the plugin:

  • org.gradle.toolchains.foojay-resolver-convention: A plugin for toolchain resolution.
buildCache {
    local {
        enabled = true
    }
}

This section configures the build cache:

  • local { enabled = true }: Enables the local cache.
rootProject.name = 'gradle-jooq-plugin'

The last line sets the root project name to gradle-jooq-plugin.

gradle.properties​

The gradle.properties file is a configuration file for a Gradle project, used to define global properties and settings. These settings can affect the behavior of the entire build process. Specifically, the three properties defined in this file serve the following purposes:

  1. org.gradle.caching=true

    • Purpose: Enables build caching.
    • Explanation: Build caching can significantly speed up the build process by storing and reusing the outputs of previously executed tasks. If certain tasks' inputs and environment haven't changed, Gradle can reuse the cached results instead of rerunning those tasks.

  2. org.gradle.parallel=true

    • Purpose: Enables parallel builds.
    • Explanation: Parallel builds allow Gradle to execute multiple independent tasks simultaneously, taking full advantage of multi-core processors to reduce build time. This is particularly useful for large projects, significantly improving build efficiency.

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

    • Purpose: Configures JVM arguments.
    • Explanation: This line sets JVM startup parameters, specifically:
      • -Duser.language=en: Sets the language to English.
      • -Duser.country=US: Sets the country to the United States.
      • -Dfile.encoding=UTF-8: Sets the file encoding to UTF-8.
    • Impact: These settings ensure the build process uses consistent language, locale, and file encoding, preventing build issues or inconsistent results due to different language, locale, or file encoding settings.

In summary, these settings aim to optimize build performance and ensure build environment consistency. Enabling build caching and parallel builds can speed up the build process, while uniform JVM parameter settings ensure consistency and stability during the build process.

tip

org.gradle.caching and org.gradle.parallel are both false by default.

build.gradle​

This code snippet is a Gradle build script used to configure a Java Gradle plugin project. Here’s a detailed explanation:

Plugin Declarations​

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: Plugin for developing Gradle plugins.
  • com.gradle.plugin-publish: Plugin for publishing Gradle plugins.
  • org.nosphere.gradle.github.actions: Plugin for using Gradle in GitHub Actions.
  • groovy: Adds support for the Groovy language.

Project Properties​

group = 'nu.studer'
version = '9.0.1-DEV'
  • group: Organization identifier for the project.
  • version: Version number of the project.

Dependency Resolution Strategy​

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'
        }
    }
}
  • Forces the version of the jakarta.xml.bind:jakarta.xml.bind-api dependency to 3.0.1.

Repository Configuration​

repositories {
    mavenCentral()
}
  • Uses Maven Central as the dependency repository.

Dependency Declarations​

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: Dependencies required at both compile and runtime.
  • runtimeOnly: Dependencies required only at runtime.
  • testImplementation: Dependencies required for testing.
  • testRuntimeOnly: Dependencies required only at test runtime.

Java Toolchain Configuration​

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
        vendor = JvmVendorSpec.BELLSOFT
    }
}
  • Configures the Java toolchain to use BellSoft JDK 17.

Compilation Task Configuration​

tasks.withType(AbstractCompile).configureEach {
    options.compilerArgs <<
        "-Werror" <<
        "-Xlint:all"
}
  • Configures compiler arguments for all compile tasks to treat all warnings as errors and enable all lint warnings.

Test Task Configuration​

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
    }
}
  • Configures test tasks:
    • maxParallelForks = 1: Limits the number of parallel test tasks to 1.
    • useJUnitPlatform(): Uses JUnit Platform for testing.
    • Dynamically sets the Java and Gradle versions for testing and disables the test task if versions are incompatible.

Detailed Explanation​

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

    • This line finds all tasks of type Test and applies the configuration below to each.

  2. maxParallelForks = 1:

    • Limits the number of parallel test tasks to 1. The comment indicates that there is currently only one test class.

  3. useJUnitPlatform():

    • Uses JUnit Platform for running tests, which is necessary to support JUnit 5 and its new features.

  4. String testJavaRuntimeVersion = findProperty('testJavaRuntimeVersion') ?: '17':

    • Gets the testJavaRuntimeVersion property value, defaulting to '17' if not set.

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

    • Gets the testGradleVersion property value, defaulting to the current Gradle version if not set.

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

    • Configures the Java launcher with the specified Java version:
      • spec.languageVersion.set(JavaLanguageVersion.of(testJavaRuntimeVersion)): Sets the Java language version.
      • buildScan.value(identityPath.path + "#jvmVersion", testJavaRuntimeVersion): Adds the Java version to the build scan.

  7. systemProperty 'testContext.gradleVersion', testGradleVersion:

    • Sets the system property testContext.gradleVersion to the specified Gradle version.

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

    • Adds the Gradle version to the build scan.

  9. Version Compatibility Check:

    • Checks the compatibility of Java and Gradle versions: 
      def incompatibleJavaVsGradleVersions = parseInt(testJavaRuntimeVersion) > 16 && GradleVersion.version(testGradleVersion) < GradleVersion.version('7.3') ||
                                             parseInt(testJavaRuntimeVersion) > 15 && GradleVersion.version(testGradleVersion) < GradleVersion.version('7.0')
    • If Java version is greater than 16 and Gradle version is less than 7.3, or Java version is greater than 15 and Gradle version is less than 7.0, they are considered incompatible

.

  1. Disabling Incompatible Test Tasks:
    • If the Java and Gradle versions are incompatible, the test task is disabled: 
      if (incompatibleJavaVsGradleVersions) {
          enabled = false
      }

Syntax Explanation​

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 is a property of the test task used to specify the Java launcher. The set method sets the launcher to the value in parentheses.

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

    • javaToolchains is a Gradle object for managing Java toolchains.
    • The launcherFor method takes a closure (similar to an anonymous function in Groovy) to configure the launcher specification spec and returns a Provider of JavaLauncher.

  3. Closure spec -> ...:

    • Inside the closure, the spec (launcher specification) is configured: 
      spec.languageVersion.set(JavaLanguageVersion.of(testJavaRuntimeVersion))
    • spec.languageVersion.set(JavaLanguageVersion.of(testJavaRuntimeVersion)): Sets the language version to the value of testJavaRuntimeVersion. This converts it to a JavaLanguageVersion object.

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

    • Adds the Java version information to the build scan. buildScan is an object for recording build information, and the value method adds a key-value pair.
    • identityPath.path + "#jvmVersion" generates a unique key, associating it with testJavaRuntimeVersion.

  5. as Provider<? extends JavaLauncher>:

    • This is a type cast. The launcherFor method returns a Provider, which is a container for deferred evaluation. as Provider<? extends JavaLauncher> explicitly casts it to a Provider type.

Javadoc Task Configuration​

tasks.withType(Javadoc).configureEach {
    options.addStringOption('Xdoclint:none', '-quiet')
}
  • Configures Javadoc tasks to disable all documentation checks and run quietly.

Gradle Plugin Publishing Configuration​

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'
        }
    }
}
  • Configures plugin publishing information:
    • website: The plugin's official website.
    • vcsUrl: The plugin's version control system URL.
    • plugins: Defines specific plugin information, including ID, name, description, tags, and implementation class.

Plugin Validation Task Configuration​

tasks.withType(ValidatePlugins.class).configureEach {
    failOnWarning = true
    enableStricterValidation = true
}
  • Configures the plugin validation task to enforce strict validation rules, ensuring any warnings will fail the build.

This code snippet meticulously configures various aspects of a Gradle plugin project, including dependency management, task configurations, and plugin publishing, ensuring consistency and reliability in the build and testing processes.