Skip to content

Building and Shading

Jump to bottom
Jeremy Fail edited this page Apr 4, 2026 · 5 revisions

This page covers Maven and Gradle host projects. The library itself is built with Maven; consumers can use either tool to include it in your project.

Build this library (from this repo)

From the PluginUpdateChecker repository:

mvn clean package

The JAR is target/plugin-update-checker-<version>.jar.

To install into your local Maven repository so Gradle or Maven can resolve com.failprooftech:plugin-update-checker:

mvn clean install

You can also use mvn install:install-file with the built JAR, or publish to Nexus / GitHub Packages.

Add the dependency to your plugin

Adjust version to match this project (pom.xml).

Maven (pom.xml)

<dependency>
    <groupId>com.failprooftech</groupId>
    <artifactId>plugin-update-checker</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle (build.gradle - Groovy DSL)

Point repositories at wherever the artifact lives (e.g. mavenCentral() when published, or mavenLocal() after mvn install on your machine):

repositories {
    mavenCentral()
    // After: mvn install in PluginUpdateChecker
    mavenLocal()
    maven { url = 'https://hub.spigotmc.org/nexus/content/repositories/snapshots/' }
}

dependencies {
    compileOnly 'org.spigotmc:spigot-api:1.20.4-R0.1-SNAPSHOT'
    implementation 'com.failprooftech:plugin-update-checker:1.0.0'
}
  • compileOnly for spigot-api - same idea as Maven provided: the server supplies it; do not bundle it in your fat JAR.
  • implementation for PluginUpdateChecker — this and its transitive runtime dep maven-artifact (for version comparison) should end up inside your shaded plugin JAR. The library JAR from this repo already embeds mJson under com.failprooftech.pluginupdatechecker.shaded.mjson (Maven Shade relocation), so it does not clash with plugins that depend on the stock mjson package.

Gradle (build.gradle.kts - Kotlin DSL)

repositories {
    mavenCentral()
    mavenLocal()
    maven("https://hub.spigotmc.org/nexus/content/repositories/snapshots/")
}

dependencies {
    compileOnly("org.spigotmc:spigot-api:1.20.4-R0.1-SNAPSHOT")
    implementation("com.failprooftech:plugin-update-checker:1.0.0")
}

JAR on disk (no Maven coordinates)

If you only have plugin-update-checker-1.0.0.jar in libs/:

dependencies {
    implementation files('libs/plugin-update-checker-1.0.0.jar')
}

Gradle will not pull transitive dependencies from that file alone. Add maven-artifact explicitly with implementation if needed, or build/install the library with Maven so you can use implementation 'com.failprooftech:plugin-update-checker:…' instead.

Shade and relocate

Produce one plugin JAR that contains this library (and embeddable deps) under relocated package names so two plugins do not clash on the same classpath.

Replace your.plugin.lib.updatechecker (and the other shaded prefixes) with something unique to your plugin, e.g. com.myname.myplugin.lib.updatechecker.

After shading, import the relocated packages in your Java code.

Maven (Shade Plugin)

Example (versions are examples - use current releases):

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.5.1</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
            <configuration>
                <createDependencyReducedPom>false</createDependencyReducedPom>
                <relocations>
                    <relocation>
                        <pattern>com.failprooftech.pluginupdatechecker</pattern>
                        <shadedPattern>your.plugin.lib.updatechecker</shadedPattern>
                    </relocation>
                    <relocation>
                        <pattern>org.apache.maven.artifact</pattern>
                        <shadedPattern>your.plugin.lib.maven.artifact</shadedPattern>
                    </relocation>
                </relocations>
                <filters>
                    <filter>
                        <artifact>*:*</artifact>
                        <excludes>
                            <exclude>META-INF/MANIFEST.MF</exclude>
                        </excludes>
                    </filter>
                </filters>
            </configuration>
        </execution>
    </executions>
</plugin>

Gradle (Shadow plugin)

Gradle does not ship shading; use the Gradle Shadow plugin (actively maintained fork of the classic Shadow plugin). Pick a plugin version compatible with your Gradle version from the Gradle Plugin Portal entry (or search for shadow if the id changes).

1. Apply the plugin at the top of build.gradle:

plugins {
    id 'java'
    id 'com.gradleup.shadow' version '8.3.5'  // replace with a current version from plugins.gradle.org
}

2. Configure shadowJar - merge dependencies into the plugin JAR, strip the classifier so the output is your normal plugin artifact (adjust to match how you name/upload your build), and relocate packages:

shadowJar {
    archiveClassifier.set('')   // empty = main jar name without '-all' suffix; or set to 'reobf' if your toolchain expects it

    relocate 'com.failprooftech.pluginupdatechecker', 'your.plugin.lib.updatechecker'
    relocate 'org.apache.maven.artifact', 'your.plugin.lib.maven.artifact'
}

tasks.build.dependsOn tasks.shadowJar

3. Kotlin DSL (build.gradle.kts) - same idea:

plugins {
    java
    id("com.gradleup.shadow") version "8.3.5"  // replace with a current version from plugins.gradle.org
}

tasks.shadowJar {
    archiveClassifier.set("")
    relocate("com.failprooftech.pluginupdatechecker", "your.plugin.lib.updatechecker")
    relocate("org.apache.maven.artifact", "your.plugin.lib.maven.artifact")
}

tasks.build { dependsOn(tasks.shadowJar) }

Because spigot-api is compileOnly, Shadow does not bundle it into the fat JAR — same rule as Maven: only embed PluginUpdateChecker and maven-artifact, not the server API. PluginUpdateChecker’s own JAR already contains relocated mJson; you do not need a separate relocation for mjson unless you also bundle the upstream artifact yourself.

If your project already uses another fat-JAR or remapping step (e.g. some Paperweight setups), follow that tool’s docs but keep the same relocation patterns as above.

Spigot API stays provided / compileOnly

Do not shade spigot-api into your plugin JAR. On Maven use provided; on Gradle use compileOnly. When shading, relocate com.failprooftech.pluginupdatechecker and org.apache.maven.artifact as shown.

Relocation guard

The library logs a one-time warning if classes remain in com.failprooftech.pluginupdatechecker (relocation was skipped). Successful relocation removes that package from your final artifact.

Clone this wiki locally