Project maintenance

Structure

  • buildSrc sets up most of the build curiosities of this project.

  • Each subproject directory named grolifantXX where XX is a number, refers to a library that is compatible with a specific Gradle major release. These libraries are not directly referenced by consuming projects.;

  • grolifant-rawhide is a subproject with no Gradle API dependencies and is purely focused on execution within an external JVM process or a Gradle worker. It can be included in an implementation configureation of a consuming project.

  • grolifant-core is the core API and the only one that should be used in an api or implementation configuration of a consuming project.

  • grolifant-herd is a library that consuming projects need to place on the runtimeOnly configuration.

  • test-in-plugin-context is a local testing library which tries to build a local plugin that consumes Grolifant. It does not publish any artifacts, but it does run both test and gradleTest tasks as part of it’s validation.

  • docs is where all the documentation goes. It is not a subproject — documentation is built from the root project.

  • gradle/libs.versions.toml is the version catalog of this project. It is also consumed by buildSrc.

  • gradle.properties holds certain metadata as dictated by the YSF project plugin suite. It does not hold any project dependency versions. It is also consumed by buildSrc.

  • gradle-api/buildSettings provides a plugin to create gradle-api-XXX projects on the fly and is used but the main seettings.gradle

  • gradle-api/jar-extractor does the actual work of extracting Gradle API JARs and is used byt buildSrc.

  • gradle-api/api-jars is a template build directory used by gradle-api/buildSettings as the project directory. Its own build directories are sent to build/gradle-api-XXX on the root project

Compatibility testing

The three main entities are:

  • The test-in-plugin-context and test-in-plugin-context-jdk17 subprojects.

  • The CompatibilityTestPlugin defined in buildSrc.

  • The gradle/gradleTest/common.gradle file.

When test-in-plugin-context:test is executed it will use the fallbackGradleForTesting version defined in the version catalog to set a system property called OVERRIDE_GRADLE_VERSION.

test-in-plugin-context/build.gradle
testing {
    suites {
        test {
            targets {
                all {
                    testTask.configure {
                        systemProperties OVERRIDE_GRADLE_VERSION: grolifantOps.resolveProperty('overrideTestGradleVersion',ysfProject.versionOf('fallbackGradleForTesting')).get()
                        systemProperties OVERRIDE_GROOVY_VERSION: ysfProject.versionOf('gradle7to8Groovy')
                    }
                }
            }
        }
    }
}

When test-in-plugin-context:gradleTest is executed it either use the Gradle versions defined on the command-line via -DgradleTest.versions or it will read a list from gradle.properties. It will set a number of system properties that the test task can then process later on. This is defined in the CompatibilityTestPlugin.

buildSrc/src/main/groovy/org/ysb33r/internal/CompatibilityTestPlugin.groovy
minHeapSize = '512m'
maxHeapSize = '2048m'
forkEvery = 4

systemProperties WITHOUT_DEBUG: 1,
    COMPAT_TEST_RESOURCES_DIR: resourcesDir.absolutePath

The PLUGIN_COMPATIBILITY_TEST flag controls how gradle/gradleTest/common.gradle handles dependencies between test and `gradleTest executions.

Override Gradle version

When running test-in-plugin-context:test it is possible to override Gradle version using for Testkit. Pass test -PoverrideTestGradleVersion=<VERSION> replacing <VERSION> with the specific version you desire. This can be useful to quickly test compatibility with a specific version, rather than wait for gradleTest to do its thing.

CI

When it executes on CI, it will create parallel jobs to handle batches of Gradle versions as per the below recipes.

.gitlab-ci.yml
- component: $CI_SERVER_FQDN/ysb33rOrg/org/gitlab-pipeline-recipes/gradleTest@0.7.0
  inputs:
    versions: "7.3.3,7.4.2,7.5.1,7.6.4"
- component: $CI_SERVER_FQDN/ysb33rOrg/org/gitlab-pipeline-recipes/gradleTest@0.7.0
  inputs:
    versions: "8.0.2,8.1.1,8.2.1,8.3"
- component: $CI_SERVER_FQDN/ysb33rOrg/org/gitlab-pipeline-recipes/gradleTest@0.7.0
  inputs:
    versions: "8.4,8.5,8.6,8.7"
- component: $CI_SERVER_FQDN/ysb33rOrg/org/gitlab-pipeline-recipes/gradleTest@0.7.0
  inputs:
    versions: "8.8,8.9,8.11.1"
- component: $CI_SERVER_FQDN/ysb33rOrg/org/gitlab-pipeline-recipes/gradleTest@0.7.0
  inputs:
    versions: "8.12.1,8.13,8.14.3"
- component: $CI_SERVER_FQDN/ysb33rOrg/org/gitlab-pipeline-recipes/gradleTest@0.7.0
  inputs:
    versions: "9.0.0,9.1.0-rc-1"