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 configuration 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 the test tass as part of its validation. It is primarily used to perform quick validation before compatibility-testing is invoked.

  • 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 by the main settings.gradle

  • gradle-api/jar-extractor does the actual work of extracting Gradle API JARs and is used by 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 is a a separate project containing subprojects for various JDKs. It performs validation against as many of the supported Gradle versions as possible. It has its own buildSrc.

Compatibility testing

Everything lives inside compatibility-testing. On CI builds this is driven from the script run-compatibility-test-on-ci.sh which lives in the root directory.

Local testing

For local testing one can either switch directory to compatibility-testing or run the run-compatibility-test-on-ci.sh script in the root directory.

Using the compatibility-testing folder
$ ./gradlew publishLocalTestingPublicationToLocalTestingRepoRepository (1)
$ cd compatibility-testing (2)
$ ./gradlew gradleTest -PgrolifantTest.versions=8.2,9.7.1 (3) (4)
$ ./gradlew :jdk17:gradleTest -PgrolifantTest.versions=9.0.1,9.7.1 -PgrolifantTest.tests=**MySpec** (5) (6)
1 Ensure all artifacts are in the local testing repository
2 Change directory
3 Run the gradleTest command.
4 To restrict testing to specific Gradle versions use -PgrolifantTest.versions
5 To restrict testing to one specific JDK, only run the tests for that subproject and optionally restrict which versions to test.
6 To restrict it to only specific tests within the tests being run inside gradleTest use -ProlifantTest.tests.
Using run-compatibility-test-on-ci.sh
GRADLE_VERS=8.0.2,8.14.3 ./run-compatibility-test-on-ci.sh (1)
1 Usage of GRADLE_VERS is required when using the script locally. Provide the list of versions to test.

You can also run one specific version of one JDK in the IntelliJ IDE. Just go to compatibility-testing/jdk*/.generated-src/gradleTestPlugin/gradleTest/src/groovy and select the test you want to run or debug.

Override Gradle versions for testing

Although compatibility testing uses gradleTest under the hood, the gradleTest.versions property should not be used. Use the grolifantTest.versions property instead. The reason is that there are additional filters involved to control which Gradle versions are used by which subproject.

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.8.6
  inputs:
    versions: "7.3.3,7.4.2,7.5.1,7.6.6"
    overrideGradleTestProperty: grolifantTest
    testProjectDir: compatibility-testing
- component: $CI_SERVER_FQDN/ysb33rOrg/org/gitlab-pipeline-recipes/gradleTest@0.8.6
  inputs:
    versions: "8.0.2,8.1.1,8.2.1,8.3"
    overrideGradleTestProperty: grolifantTest
    testProjectDir: compatibility-testing
- component: $CI_SERVER_FQDN/ysb33rOrg/org/gitlab-pipeline-recipes/gradleTest@0.8.6
  inputs:
    versions: "8.4,8.5,8.6,8.7"
    overrideGradleTestProperty: grolifantTest
    testProjectDir: compatibility-testing
- component: $CI_SERVER_FQDN/ysb33rOrg/org/gitlab-pipeline-recipes/gradleTest@0.8.6
  inputs:
    versions: "8.8,8.9,8.11.1"
    overrideGradleTestProperty: grolifantTest
    testProjectDir: compatibility-testing
- component: $CI_SERVER_FQDN/ysb33rOrg/org/gitlab-pipeline-recipes/gradleTest@0.8.6
  inputs:
    versions: "8.12.1,8.13,8.14.5"
    overrideGradleTestProperty: grolifantTest
    testProjectDir: compatibility-testing
- component: $CI_SERVER_FQDN/ysb33rOrg/org/gitlab-pipeline-recipes/gradleTest@0.8.6
  inputs:
    versions: "9.0.0,9.1.0,9.2.1"
    overrideGradleTestProperty: grolifantTest
    testProjectDir: compatibility-testing
- component: $CI_SERVER_FQDN/ysb33rOrg/org/gitlab-pipeline-recipes/gradleTest@0.8.6
  inputs:
    versions: "9.3.1,9.4.1,9.5.1"
    overrideGradleTestProperty: grolifantTest
    testProjectDir: compatibility-testing
- component: $CI_SERVER_FQDN/ysb33rOrg/org/gitlab-pipeline-recipes/gradleTest@0.8.6
  inputs:
    versions: "9.6.1,9.7.1"
    overrideGradleTestProperty: grolifantTest
    testProjectDir: compatibility-testing

CI builds are driven from the script run-compatibility-test-on-ci.sh which lives in the root directory.

Finding test results

Because of the complexity of the compatibility tests, the gradleTest results are found in two places:

  • If you need to know which specific versions of Gradle failed, then look in compatibility-testing/<JDK-VERSION>/build/reports/tests/gradleTest/index.html.

  • If you need to know why specific API tests failed for that specific version of Gradle, then look in compatibility-testing/<JDK-VER>/build/gradleTest/<GRADLE-VERSION>/pluginCompatibility/build/reports/tests/test/index.html.