3.0 - Full rewrite, Gradle 9, Java-centric API (#23)

Author: Jonathing

.github/workflows/publish.yml

@@ -9,7 +9,7 @@ permissions:
 
 jobs:
   build:
-    uses: MinecraftForge/SharedActions/.github/workflows/gradle.yml@main
+    uses: MinecraftForge/SharedActions/.github/workflows/gradle.yml@v0
     with:
       java: 17
       gradle_tasks: "publish publishPlugins"

build.gradle

@@ -1,50 +1,66 @@
 import com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar
+import org.gradle.api.attributes.plugin.GradlePluginApiVersion
 
 plugins {
-    id 'dev.gradleplugins.groovy-gradle-plugin'
+    id 'java-gradle-plugin'
+    id 'groovy'
     id 'idea'
     id 'eclipse'
     id 'maven-publish'
     alias libs.plugins.licenser
     alias libs.plugins.gradleutils
+    alias libs.plugins.javadoc.links
     alias libs.plugins.plugin.publish
     alias libs.plugins.shadow
 }
 
 final projectDisplayName = 'Forge Gradle Utilities'
+final projectArtifactId = base.archivesName = 'gradleutils'
 description = 'Small collection of utilities for standardizing MinecraftForge gradle scripts'
 group = 'net.minecraftforge'
 version = gitversion.tagOffset
 
 println "Version: $version"
 
-// Git Version requires Java 17
-java.toolchain.languageVersion = JavaLanguageVersion.of 17
+java {
+    toolchain.languageVersion = JavaLanguageVersion.of(17)
+    withSourcesJar()
+    withJavadocJar()
+}
 
 configurations {
     named(JavaPlugin.RUNTIME_CLASSPATH_CONFIGURATION_NAME) {
         // Fixes a conflict between Git Version's shadowed SLF4J from JGit and Gradle's own loggers
         exclude group: 'org.slf4j', module: 'slf4j-api'
     }
-}
 
-repositories {
-    maven { url = 'https://maven.minecraftforge.net' }
-    mavenCentral()
+    // Applies the "Gradle Plugin API Version" attribute to configuration
+    // This was added in Gradle 7, gives consumers useful errors if they are on an old version
+    def applyGradleVersionAttribute = { Configuration configuration ->
+        configuration.attributes {
+            attribute(GradlePluginApiVersion.GRADLE_PLUGIN_API_VERSION_ATTRIBUTE, objects.named(GradlePluginApiVersion, libs.versions.gradle.get()))
+        }
+    }
+
+    // TODO [GradleUtils] Re-enable this after first publish of GradleUtils 3.0.0
+//    named('apiElements', applyGradleVersionAttribute)
+//    named('runtimeElements', applyGradleVersionAttribute)
+//    named('shadowRuntimeElements', applyGradleVersionAttribute)
 }
 
 dependencies {
-    // Static Analysis
+    // Gradle API
+    compileOnly libs.gradle
     compileOnly libs.nulls
 
+    // JavaDoc Links Plugin
+    compileOnly libs.gradle.javadoc.links
+
     // GitHub Actions Workflows
     implementation libs.yaml
 
-    // Git Version
-    implementation libs.gitver
-
-    // Backwards compatibility
-    implementation libs.jgit
+    // Tools
+    implementation libs.bundles.utils
 }
 
 // Removes local Gradle API from compileOnly. This is a workaround for bugged plugins.
@@ -58,7 +74,7 @@ afterEvaluate { project ->
 }
 
 license {
-    header = rootProject.file 'LICENSE-header.txt'
+    header = rootProject.file('LICENSE-header.txt')
     newLine = false
     exclude '**/*.properties'
 }
@@ -68,7 +84,7 @@ tasks.named('jar', Jar) {
 }
 
 tasks.named('shadowJar', ShadowJar) {
-    enableRelocation = true
+    enableAutoRelocation = true
     archiveClassifier = null
     relocationPrefix = 'net.minecraftforge.gradleutils.shadow'
 }
@@ -77,64 +93,58 @@ tasks.withType(GroovyCompile).configureEach {
     groovyOptions.optimizationOptions.indy = true
 }
 
+tasks.withType(Javadoc).configureEach {
+    javadocTool = javaToolchains.javadocToolFor { languageVersion = JavaLanguageVersion.of(24) }
+
+    options { StandardJavadocDocletOptions options ->
+        options.windowTitle = projectDisplayName + project.version
+        options.tags 'apiNote:a:API Note:', 'implNote:a:Implementation Note:', 'implSpec:a:Implementation Requirements:'
+    }
+}
+
 changelog {
     fromBase()
     publishAll = false
 }
 
 gradlePlugin {
-    website.set gitversion.url
-    vcsUrl.set gitversion.url + '.git'
-
-    compatibility {
-        minimumGradleVersion = libs.versions.gradle.get()
-    }
-
-    groovy {
-        withSourcesJar()
-        withGroovydocJar()
+    website = gitversion.url
+    vcsUrl = gitversion.url + '.git'
+
+    plugins.register('gradleutils') {
+        id = 'net.minecraftforge.gradleutils'
+        implementationClass = 'net.minecraftforge.gradleutils.GradleUtilsPlugin'
+        displayName = projectDisplayName
+        description = project.description
+        tags.set(['minecraftforge'])
     }
+}
 
-    plugins {
-        register('gradleutils') {
-            id = 'net.minecraftforge.gradleutils'
-            implementationClass = 'net.minecraftforge.gradleutils.GradleUtilsPlugin'
-            displayName = projectDisplayName
-            description = project.description
-            tags = ['minecraftforge']
-        }
-        register('changelog') {
-            id = 'net.minecraftforge.changelog'
-            implementationClass = 'net.minecraftforge.gradleutils.changelog.ChangelogPlugin'
-            displayName = 'Git Changelog'
-            description = 'Creates a changelog text file based on git history using Git Version'
-            tags = ['git', 'changelog']
-        }
-    }
+// Allows the thin jar to be published, but won't be considered as the java-runtime variant in the module
+// This forces Gradle to use the fat jar when applying the plugin
+(components.java as AdhocComponentWithVariants).withVariantsFromConfiguration(configurations.runtimeElements) {
+    skip()
 }
 
 publishing {
     publications.register('pluginMaven', MavenPublication) {
-        artifactId = project.name
-
+        artifactId = projectArtifactId
         changelog.publish it
 
         pom { pom ->
             name = projectDisplayName
             description = project.description
 
-            gradleutils.pom.setGitHubDetails pom
+            gradleutils.pom.setGitHubDetails(pom)
 
             licenses {
                 license gradleutils.pom.licenses.LGPLv2_1
             }
 
-            // TODO [GradleUtils][GU3.0] Re-evaluate active developers in GU 3.0
             developers {
-                developer gradleutils.pom.developers.LexManos
-                developer gradleutils.pom.developers.SizableShrimp
-                developer gradleutils.pom.developers.Paint_Ninja
                 developer gradleutils.pom.developers.Jonathing
+                developer gradleutils.pom.developers.Paint_Ninja
+                developer gradleutils.pom.developers.LexManos
             }
         }
     }

gradle.properties

@@ -2,10 +2,8 @@ org.gradle.caching=true
 org.gradle.parallel=true
 org.gradle.configureondemand=true
 
-# TODO [GradleUtils][Gradle9] Re-enable config cache in Gradle 9
-# Configuration Cache causes issues with plugin publishing.
-# Do continue to make our Gradle plugins (GU, FG7, etc.) support it though.
-#org.gradle.configuration-cache=true
-#org.gradle.configuration-cache.parallel=true
+org.gradle.configuration-cache=true
+org.gradle.configuration-cache.parallel=true
+org.gradle.configuration-cache.problems=warn
 
 systemProp.org.gradle.unsafe.suppress-gradle-api=true

gradle/gradle-daemon-jvm.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.14-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.0.0-bin.zip
 networkTimeout=10000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME

gradle/wrapper/gradle-wrapper.properties

@@ -1,37 +1,44 @@
-import org.gradle.api.initialization.resolve.RepositoriesMode
-
 plugins {
-    id 'dev.gradleplugins.gradle-plugin-development' version '1.9.0'
     id 'org.gradle.toolchains.foojay-resolver-convention' version '0.10.0'
 }
 
 rootProject.name = 'gradleutils'
 
 dependencyResolutionManagement {
-    // Repositories are located in build.gradle for this project
-    // dev.gradleplugins.groovy-gradle-plugin is bugged and force adds repositories on the project
-    // so, we can't declare the repositories in here
-    repositoriesMode = RepositoriesMode.PREFER_PROJECT
+    repositories {
+        maven { url = 'https://maven.minecraftforge.net/' }
+        maven { url = 'https://maven.moddinglegacy.com' } // Gradle API
+        maven { url = 'https://repo.eclipse.org/content/groups/releases/' }
+        mavenCentral()
+        //mavenLocal()
+    }
 
     versionCatalogs.register('libs') {
-        plugin 'licenser', 'net.minecraftforge.licenser' version '1.2.0'
-        plugin 'gradleutils', 'net.minecraftforge.gradleutils' version '2.5.1'
-        plugin 'plugin-publish', 'com.gradle.plugin-publish' version '1.3.1'
-        plugin 'shadow', 'com.gradleup.shadow' version '9.0.0-beta13'
+        version 'gradle-javadoc-links', '8.14'
+
+        plugin 'licenser',       'net.minecraftforge.licenser'    version '1.2.0'                   // https://plugins.gradle.org/plugin/net.minecraftforge.licenser
+        plugin 'gradleutils',    'net.minecraftforge.gradleutils' version '2.6.0'                   // https://plugins.gradle.org/plugin/net.minecraftforge.gradleutils
+        plugin 'javadoc-links',  'io.freefair.javadoc-links'      versionRef 'gradle-javadoc-links' // https://plugins.gradle.org/plugin/io.freefair.javadoc-links
+        plugin 'plugin-publish', 'com.gradle.plugin-publish'      version '1.3.1'                   // https://plugins.gradle.org/plugin/com.gradle.plugin-publish
+        plugin 'shadow',         'com.gradleup.shadow'            version '9.0.0-rc3'               // https://plugins.gradle.org/plugin/com.gradleup.shadow
 
         // Gradle API
-        version 'gradle', '7.3'
+        // TODO [ForgeGradle][FG7][Gradle Api] REMOVE once Gradle publish their own API artifacts
+        // Original:  https://github.com/remal-gradle-api/packages/packages/760197?version=9.0.0
+        // Mirror:    https://repos.moddinglegacy.com/#/modding-legacy/name/remal/gradle-api/gradle-api/9.0.0
+        version 'gradle', '9.0.0'
+        library 'gradle', 'name.remal.gradle-api', 'gradle-api'  versionRef 'gradle'
+        library 'nulls',  'org.jetbrains',         'annotations' version    '26.0.2'
 
-        // Static Analysis
-        library 'nulls', 'org.jetbrains', 'annotations' version '26.0.2'
+        // JavaDoc Links Plugin
+        library 'gradle-javadoc-links', 'io.freefair.javadoc-links', 'io.freefair.javadoc-links.gradle.plugin' versionRef 'gradle-javadoc-links'
 
         // GitHub Actions Workflows
         library 'yaml', 'org.yaml', 'snakeyaml' version '2.4'
 
-        // Git Version
-        library 'gitver', 'net.minecraftforge', 'gitversion' version '0.5.2'
-
-        // Backwards compatibility
-        library 'jgit', 'org.eclipse.jgit', 'org.eclipse.jgit' version '7.2.0.202503040940-r'
+        // Tools
+        library 'utils-hash',     'net.minecraftforge', 'hash-utils'      version '0.1.9' // https://files.minecraftforge.net/net/minecraftforge/hash-utils/index.html
+        library 'utils-download', 'net.minecraftforge', 'download-utils'  version '0.3.1' // https://files.minecraftforge.net/net/minecraftforge/download-utils/index.html
+        bundle 'utils', ['utils-hash', 'utils-download']
     }
 }

settings.gradle

@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) Forge Development LLC and contributors
+ * SPDX-License-Identifier: LGPL-2.1-only
+ */
+package net.minecraftforge.gradleutils;
+
+import org.gradle.api.DefaultTask;
+import org.gradle.api.provider.Property;
+import org.gradle.api.provider.ProviderFactory;
+import org.gradle.api.reflect.HasPublicType;
+import org.gradle.api.reflect.TypeOf;
+import org.gradle.api.tasks.Input;
+import org.gradle.api.tasks.TaskAction;
+
+import javax.inject.Inject;
+
+// TODO [GradleUtils][TeamCity] Delete this when off of TeamCity
+@Deprecated(forRemoval = true)
+abstract class ConfigureTeamCity extends DefaultTask implements HasPublicType {
+    static final String NAME = "configureTeamCity";
+
+    @Override
+    public TypeOf<?> getPublicType() {
+        // We don't want this task to be configurable, so tell Gradle it's just a default task
+        return TypeOf.typeOf(DefaultTask.class);
+    }
+
+    @Inject
+    public ConfigureTeamCity(ProviderFactory providers) {
+        this.setGroup("Build Setup");
+        this.setDescription("Prints the marker lines into the log which configure the pipeline. [deprecated]");
+        this.onlyIf("Only runs on TeamCity, so the TEAMCITY_VERSION environment variable must be set.", task -> providers.environmentVariable("TEAMCITY_VERSION").isPresent());
+
+        this.getBuildNumber().convention(providers.provider(() -> this.getProject().getVersion()).map(Object::toString));
+    }
+
+    /** The build number to print, usually the project version. */
+    protected abstract @Input Property<String> getBuildNumber();
+
+    @TaskAction
+    public void exec() {
+        this.getLogger().warn("WARNING: Usage of TeamCity is deprecated within Minecraft Forge Minecraft Forge has been gradually moving off of TeamCity and into GitHub Actions. When the migration is fully complete, this task along with its automatic setup will be removed.");
+
+        final var buildNumber = this.getBuildNumber().get();
+        this.getLogger().lifecycle("Setting project variables and parameters.");
+        System.out.printf("##teamcity[buildNumber '%s']%n", buildNumber);
+        System.out.printf("##teamcity[setParameter name='env.PUBLISHED_JAVA_ARTIFACT_VERSION' value='%s']%n", buildNumber);
+    }
+}