# ForgeWrapper — Building & Gradle Build System Reference This document provides a comprehensive, line-by-line analysis of the ForgeWrapper build system. Every statement references actual source code from the Gradle build files. Variable names, values, and configuration blocks are taken directly from the project. --- ## Table of Contents 1. [Project Overview](#1-project-overview) 2. [Multi-Project Structure](#2-multi-project-structure) 3. [settings.gradle Analysis](#3-settingsgradle-analysis) 4. [gradle.properties Analysis](#4-gradleproperties-analysis) 5. [Gradle Wrapper Configuration](#5-gradle-wrapper-configuration) 6. [Root build.gradle — Complete Line-by-Line Analysis](#6-root-buildgradle--complete-line-by-line-analysis) - 6.1 [Imports](#61-imports) - 6.2 [Plugins Block](#62-plugins-block) - 6.3 [Java Source/Target Compatibility](#63-java-sourcetarget-compatibility) - 6.4 [Version, Group, and Archives Base Name](#64-version-group-and-archives-base-name) - 6.5 [The multirelase Configuration](#65-the-multirelase-configuration) - 6.6 [Repositories](#66-repositories) - 6.7 [Dependencies](#67-dependencies) - 6.8 [Sources JAR](#68-sources-jar) - 6.9 [JAR Manifest Attributes](#69-jar-manifest-attributes) - 6.10 [Multi-Release JAR Packing](#610-multi-release-jar-packing) - 6.11 [Publishing Configuration](#611-publishing-configuration) - 6.12 [getVersionSuffix()](#612-getversionsuffix) 7. [Jigsaw Subproject build.gradle — Complete Analysis](#7-jigsaw-subproject-buildgradle--complete-analysis) - 7.1 [Plugins](#71-plugins) - 7.2 [Java 9 Toolchain Auto-Detection](#72-java-9-toolchain-auto-detection) - 7.3 [JVM Version Attribute Override](#73-jvm-version-attribute-override) 8. [Multi-Release JAR — Deep Dive](#8-multi-release-jar--deep-dive) 9. [Build Pipeline Diagram](#9-build-pipeline-diagram) 10. [Build Targets and Tasks](#10-build-targets-and-tasks) 11. [Step-by-Step Build Guide](#11-step-by-step-build-guide) 12. [CI/CD Integration](#12-cicd-integration) 13. [Artifact Output Structure](#13-artifact-output-structure) 14. [Publishing to Local Maven Repository](#14-publishing-to-local-maven-repository) 15. [Java Version Requirements](#15-java-version-requirements) 16. [Source File Layout and the Dual-ModuleUtil Pattern](#16-source-file-layout-and-the-dual-moduleutil-pattern) 17. [Troubleshooting](#17-troubleshooting) 18. [Quick Reference Card](#18-quick-reference-card) --- ## 1. Project Overview ForgeWrapper is a Java library that allows third-party Minecraft launchers (originally MultiMC, now adopted more broadly) to launch Minecraft 1.13+ with Forge and NeoForge. The build system produces a **Multi-Release JAR** (MRJAR) that contains: - **Java 8 bytecode** in the standard class path for maximum compatibility. - **Java 9+ bytecode** under `META-INF/versions/9/` for environments running on the Java Platform Module System (JPMS / Project Jigsaw). The Gradle build is a **multi-project build** consisting of: | Project | Directory | Java Target | Purpose | |------------|-------------------|-------------|---------------------------------| | Root | `forgewrapper/` | Java 8 | Main ForgeWrapper library | | `jigsaw` | `forgewrapper/jigsaw/` | Java 9 | JPMS-aware `ModuleUtil` overlay | The root project's JAR task assembles both outputs into a single artifact with `Multi-Release: true` in its manifest. --- ## 2. Multi-Project Structure The ForgeWrapper build is organized as a Gradle multi-project build. The directory tree relevant to the build system is: ``` forgewrapper/ ├── build.gradle ← Root project build script ├── settings.gradle ← Declares root name + subprojects ├── gradle.properties ← Project-wide properties ├── gradlew ← Gradle wrapper (Linux/macOS) ├── gradlew.bat ← Gradle wrapper (Windows) ├── gradle/ │ └── wrapper/ │ └── gradle-wrapper.properties ← Wrapper distribution URL + version ├── src/ │ └── main/ │ └── java/ │ └── io/github/zekerzhayard/forgewrapper/installer/ │ ├── Bootstrap.java │ ├── Installer.java │ ├── Main.java │ ├── detector/ │ │ ├── DetectorLoader.java │ │ ├── IFileDetector.java │ │ └── MultiMCFileDetector.java │ └── util/ │ └── ModuleUtil.java ← Java 8 stub (no-op methods) ├── jigsaw/ │ ├── build.gradle ← Subproject build script │ └── src/ │ └── main/ │ └── java/ │ └── io/github/zekerzhayard/forgewrapper/installer/ │ └── util/ │ └── ModuleUtil.java ← Java 9 full implementation └── build/ ← Generated outputs (after build) ├── libs/ │ ├── ForgeWrapper-.jar │ └── ForgeWrapper--sources.jar └── maven/ ← Local maven publish target ``` The root project compiles all code under `src/` with Java 8. The `jigsaw` subproject compiles its own `ModuleUtil.java` with Java 9. At JAR assembly time, the jigsaw output is injected into `META-INF/versions/9/` inside the root JAR, creating the Multi-Release JAR. --- ## 3. settings.gradle Analysis **File: `forgewrapper/settings.gradle`** (2 lines of active content) ```groovy rootProject.name = 'ForgeWrapper' include 'jigsaw' ``` ### Line-by-line: **`rootProject.name = 'ForgeWrapper'`** Sets the human-readable name of the root Gradle project to `ForgeWrapper`. This name is used as: - The default `archivesBaseName` (overridden in `build.gradle` to `rootProject.name`, which resolves to the same value `ForgeWrapper`). - The `Specification-Title` and `Implementation-Title` in the JAR manifest. - The base filename for produced artifacts: `ForgeWrapper-.jar`. **`include 'jigsaw'`** Includes the subdirectory `jigsaw/` as a Gradle subproject. Gradle will look for `jigsaw/build.gradle` and compile it as a separate project within the same build. This subproject is referenced in the root `build.gradle` via `project(":jigsaw")` in the `multirelase` dependency declaration. The relationship between settings.gradle and the two build.gradle files: ``` settings.gradle │ ├── rootProject.name = 'ForgeWrapper' │ ↓ │ build.gradle (root) │ archivesBaseName = rootProject.name → "ForgeWrapper" │ dependencies { multirelase project(":jigsaw") } │ │ └── include 'jigsaw' │ ↓ ↓ jigsaw/build.gradle ←─────── resolved here ``` --- ## 4. gradle.properties Analysis **File: `forgewrapper/gradle.properties`** (2 active properties) ```properties org.gradle.daemon = false fw_version = projt ``` ### `org.gradle.daemon = false` Disables the Gradle daemon for this project. Normally Gradle keeps a long-lived JVM process (the daemon) running between builds to speed up subsequent invocations. Setting this to `false` means every `./gradlew` invocation starts a fresh JVM. This is typical for: - **CI/CD environments** where daemon state can cause flaky builds. - **Projects with infrequent builds** where the daemon would just consume memory. - **Reproducibility** — no cached daemon state between runs. ### `fw_version = projt` Defines the base version string for ForgeWrapper as the literal value `projt`. This property is referenced in `build.gradle` via string interpolation: ```groovy version = "${fw_version}${-> getVersionSuffix()}" ``` The `${fw_version}` is replaced with `projt` from `gradle.properties`, and then the lazy GString closure `${-> getVersionSuffix()}` appends a suffix. The final version string will be one of: | Environment | Resulting Version | |--------------------------------------|-------------------------------| | Local development | `projt-LOCAL` | | GitHub Actions CI | `projt-2026-04-05` | | IS_PUBLICATION env var set | `projt-2026-04-05` | The `fw_version` property is available to all projects in the multi-project build because `gradle.properties` in the root directory is automatically loaded for all subprojects. --- ## 5. Gradle Wrapper Configuration **File: `forgewrapper/gradle/wrapper/gradle-wrapper.properties`** ```properties distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists distributionUrl=https\://services.gradle.org/distributions/gradle-7.3.3-all.zip zipStoreBase=GRADLE_USER_HOME zipStorePath=wrapper/dists ``` ### Property-by-property: **`distributionBase=GRADLE_USER_HOME`** The base directory where the downloaded Gradle distribution will be stored. `GRADLE_USER_HOME` defaults to `~/.gradle` on Linux/macOS and `%USERPROFILE%\.gradle` on Windows. **`distributionPath=wrapper/dists`** Relative path under `distributionBase` where distributions are unpacked. The full absolute path becomes `~/.gradle/wrapper/dists/`. **`distributionUrl=https\://services.gradle.org/distributions/gradle-7.3.3-all.zip`** The URL from which Gradle **7.3.3** is downloaded. Key observations: - **Version 7.3.3** — Released December 2021. This is a Gradle 7.x release that supports Java toolchains (used in the jigsaw subproject) and is compatible with both Java 8 and Java 17+. - **`-all` variant** — Includes Gradle source code and documentation, not just the binaries (`-bin`). This allows IDEs to show Gradle DSL documentation and enables source-level debugging of Gradle itself. - The `\:` escape is standard `.properties` file syntax for a literal colon. **`zipStoreBase=GRADLE_USER_HOME`** and **`zipStorePath=wrapper/dists`** Where the downloaded ZIP file itself is cached before extraction. Same base directory as the unpacked distribution. ### Gradle Version Compatibility Matrix | Feature Used in Build | Minimum Gradle Version | Actual | |--------------------------------|------------------------|--------| | `java` plugin | 1.0 | 7.3.3 | | `maven-publish` plugin | 1.3 | 7.3.3 | | `javaToolchains.compilerFor` | 6.7 | 7.3.3 | | `layout.buildDirectory.dir()` | 7.1 | 7.3.3 | | `TargetJvmVersion` attribute | 6.0 | 7.3.3 | All features used in the build are supported by Gradle 7.3.3. --- ## 6. Root build.gradle — Complete Line-by-Line Analysis **File: `forgewrapper/build.gradle`** (90 lines) This is the primary build script. We will examine every section. ### 6.1 Imports ```groovy import java.text.SimpleDateFormat ``` Line 1 imports `SimpleDateFormat`, used in the `getVersionSuffix()` method at line 89 to format the current date as `-yyyy-MM-dd` (e.g., `-2026-04-05`). This import is at the top of the script, outside any block, making it available to all closures in the file. ### 6.2 Plugins Block ```groovy plugins { id "java" id "eclipse" id "maven-publish" } ``` Lines 3–7: Three plugins are applied. **`java`** — The core Java compilation plugin. It provides: - `compileJava` task — compiles `src/main/java/**/*.java`. - `jar` task — packages compiled classes into a JAR. - `sourceSets` — the `main` and `test` source sets. - `sourceCompatibility` / `targetCompatibility` — Java version settings. - `configurations` — `implementation`, `compileOnly`, `runtimeOnly`, etc. - The `components.java` software component used by `maven-publish`. **`eclipse`** — Generates Eclipse IDE project files (`.project`, `.classpath`, `.settings/`). Allows developers to run `./gradlew eclipse` to import into Eclipse. This does not affect the build output. **`maven-publish`** — Enables publishing artifacts to Maven repositories. It provides: - The `publishing { }` DSL block. - The `publish` task (and per-repository `publishToMavenLocal`, etc.). - `MavenPublication` type for defining what gets published. ### 6.3 Java Source/Target Compatibility ```groovy sourceCompatibility = targetCompatibility = 1.8 compileJava { sourceCompatibility = targetCompatibility = 1.8 } ``` Lines 9–12: Java 8 compatibility is set **twice** — at the project level and inside the `compileJava` task configuration. This double declaration ensures the setting is applied regardless of evaluation order. - **`sourceCompatibility = 1.8`** — The Java source code must be valid Java 8 syntax. The compiler will reject Java 9+ language features (e.g., `var`, private interface methods). - **`targetCompatibility = 1.8`** — The emitted bytecode targets Java 8 (class file version 52.0). JVMs older than Java 8 will refuse to load these classes. This is critical because ForgeWrapper must run on Minecraft launchers that may still use Java 8. The `ModuleUtil.java` in the root source tree contains no-op stubs precisely because Java 8 has no `java.lang.module` API: ```java // forgewrapper/src/main/java/.../util/ModuleUtil.java public class ModuleUtil { public static void addModules(String modulePath) { // nothing to do with Java 8 } public static void addExports(List exports) { // nothing to do with Java 8 } public static void addOpens(List opens) { // nothing to do with Java 8 } // ... } ``` ### 6.4 Version, Group, and Archives Base Name ```groovy version = "${fw_version}${-> getVersionSuffix()}" group = "io.github.zekerzhayard" archivesBaseName = rootProject.name ``` Lines 14–16: Maven coordinates and artifact naming. **`version`** — A Groovy GString with a lazy evaluation closure. The `fw_version` from `gradle.properties` is resolved immediately to `projt`. The closure `${-> getVersionSuffix()}` is evaluated lazily — only when the GString is converted to a String (at task execution time, not configuration time). This matters because `getVersionSuffix()` calls `System.getenv()` and `new Date()`, which should reflect the actual build time, not the configuration phase time. **`group = "io.github.zekerzhayard"`** — The Maven `groupId`. Follows the reverse-domain convention for the project's GitHub namespace (`github.com/ZekerZhayard`). **`archivesBaseName = rootProject.name`** — Set to `ForgeWrapper` (from `settings.gradle`). This is the filename prefix for all produced JARs: `ForgeWrapper-projt-LOCAL.jar`. ### 6.5 The multirelase Configuration ```groovy configurations { multirelase { implementation.extendsFrom multirelase } } ``` Lines 18–22: This block creates a **custom Gradle configuration** named `multirelase` (note: this is intentionally or accidentally spelled without the second "e" — it is not `multirelease`). The statement `implementation.extendsFrom multirelase` establishes a dependency inheritance chain: everything in the `multirelase` configuration is also visible to the `implementation` configuration. This means: 1. When `multirelase project(":jigsaw")` is declared (line 38), the jigsaw subproject's classes are available on the root project's compile classpath. 2. The `multirelase` configuration is also used separately in the `jar` block (line 60) to extract the jigsaw classes and pack them into `META-INF/versions/9/`. The configuration flow: ``` multirelase config │ ├──→ implementation config (via extendsFrom) │ → compileJava can see jigsaw classes │ └──→ jar task (via configurations.multirelase.files) → copies jigsaw classes into META-INF/versions/9/ ``` This dual use is the heart of the Multi-Release JAR mechanism. The root source code can reference `ModuleUtil` (which it does — in `Bootstrap.java` and `Main.java`), and at compile time Gradle resolves the Java 8 stubs from the root `src/`. At runtime, the JVM selects the appropriate `ModuleUtil` class: the Java 8 stub from the main class path on Java 8 JVMs, or the Java 9 implementation from `META-INF/versions/9/` on Java 9+ JVMs. ### 6.6 Repositories ```groovy repositories { mavenCentral() maven { name = "forge" url = "https://maven.minecraftforge.net/" } } ``` Lines 24–29: Two Maven repositories are declared. **`mavenCentral()`** — Maven Central Repository (`https://repo.maven.apache.org/maven2/`). Used to resolve: - `com.google.code.gson:gson:2.8.7` - `net.sf.jopt-simple:jopt-simple:5.0.4` **Forge Maven** (`https://maven.minecraftforge.net/`) — MinecraftForge's official Maven repository. Named `"forge"` for logging clarity. Used to resolve: - `cpw.mods:modlauncher:8.0.9` - `net.minecraftforge:installer:2.2.7` Note: The repository named `"forge"` is a Gradle naming convention for readability; the name does not affect dependency resolution behavior. ### 6.7 Dependencies ```groovy dependencies { compileOnly "com.google.code.gson:gson:2.8.7" compileOnly "cpw.mods:modlauncher:8.0.9" compileOnly "net.minecraftforge:installer:2.2.7" compileOnly "net.sf.jopt-simple:jopt-simple:5.0.4" multirelase project(":jigsaw") } ``` Lines 31–38: All external dependencies use the `compileOnly` scope. #### Why `compileOnly`? `compileOnly` means the dependency is available at compile time but is **not** included in the runtime classpath or the published POM. ForgeWrapper is loaded into an environment (the Minecraft launcher) that already provides these libraries. Bundling them would cause version conflicts and inflate the JAR. #### Dependency Analysis **`com.google.code.gson:gson:2.8.7`** - **What**: Google's JSON serialization/deserialization library. - **Why compileOnly**: The Minecraft launcher and Forge installer both bundle Gson. Including it again would create version conflicts. - **Classes used**: `com.google.gson.Gson`, `com.google.gson.JsonObject`, etc. Used in `Installer.java` to parse the Forge installer's JSON metadata. **`cpw.mods:modlauncher:8.0.9`** - **What**: The Forge ModLauncher framework by cpw (ChickenPatches Warrior). Manages mod loading, class transformation, and game launch orchestration. - **Why compileOnly**: ModLauncher is part of the Forge runtime. ForgeWrapper interacts with its API to set up the launch environment but doesn't ship it. - **Classes used**: Launch target interfaces and transformation services. - **Version 8.0.9**: Targets Forge for Minecraft 1.16.x–1.17.x era. **`net.minecraftforge:installer:2.2.7`** - **What**: The Forge installer library. Contains code for downloading, extracting, and setting up Forge libraries. - **Why compileOnly**: ForgeWrapper loads the installer JAR at runtime via a `URLClassLoader` (see `Main.java` lines 48–50). It does not bundle it. - **Classes used**: Invoked reflectively — `installer.getMethod("getData", ...)` and `installer.getMethod("install", ...)` in `Main.java`. **`net.sf.jopt-simple:jopt-simple:5.0.4`** - **What**: A command-line option parser for Java. - **Why compileOnly**: Provided by the launcher environment (Forge uses it for argument parsing). ForgeWrapper reads parsed arguments but doesn't need its own copy. - **Classes used**: `OptionParser`, `OptionSet` — for parsing launch arguments like `--fml.mcVersion`, `--fml.forgeVersion`, `--fml.neoForgeVersion`. **`multirelase project(":jigsaw")`** - **What**: A project dependency on the `jigsaw` subproject. - **Scope**: The custom `multirelase` configuration (not `compileOnly` or `implementation` directly). Since `implementation.extendsFrom multirelase`, the jigsaw classes are on the compile classpath. - **Purpose**: The jigsaw project produces a JAR with Java 9 bytecode. This JAR is consumed by the root project's `jar` task and unpacked into `META-INF/versions/9/`. ### 6.8 Sources JAR ```groovy java { withSourcesJar() } ``` Lines 40–42: Registers a `sourcesJar` task that produces `ForgeWrapper--sources.jar` containing all `.java` files from `src/main/java`. This artifact is included in Maven publications alongside the main JAR, enabling downstream users and IDEs to access source code for debugging. ### 6.9 JAR Manifest Attributes ```groovy jar { manifest.attributes([ "Specification-Title": "${project.name}", "Specification-Vendor": "ZekerZhayard", "Specification-Version": "${project.version}".split("-")[0], "Implementation-Title": "${project.name}", "Implementation-Version": "${project.version}", "Implementation-Vendor" :"ZekerZhayard", "Implementation-Timestamp": new Date().format("yyyy-MM-dd'T'HH:mm:ssZ"), "Automatic-Module-Name": "${project.group}.${project.archivesBaseName}".toString().toLowerCase(), "Multi-Release": "true", "GitCommit": String.valueOf(System.getenv("GITHUB_SHA")) ]) ``` Lines 44–56: The `jar` task configures `META-INF/MANIFEST.MF` with these attributes. Each one explained: **`Specification-Title: ForgeWrapper`** Identifies the specification this JAR implements. Set to `project.name` which resolves to `ForgeWrapper`. Part of the JAR Specification versioning convention defined in `java.lang.Package`. **`Specification-Vendor: ZekerZhayard`** The organization or individual that maintains the specification. Hardcoded to the project author's GitHub handle. **`Specification-Version: projt`** The spec version. Note the expression `"${project.version}".split("-")[0]` — this takes the full version string (e.g., `projt-LOCAL` or `projt-2026-04-05`) and splits on `-`, taking only the first element: `projt`. This gives a stable specification version irrespective of the build suffix. **`Implementation-Title: ForgeWrapper`** Same as `Specification-Title`. Identifies this particular implementation. **`Implementation-Version: projt-LOCAL`** (or `projt-2026-04-05`) The full version string including the suffix. Unlike `Specification-Version`, this captures the exact build variant. **`Implementation-Vendor: ZekerZhayard`** The vendor of this implementation. Same as `Specification-Vendor`. **`Implementation-Timestamp: 2026-04-05T14:30:00+0000`** (example) The build timestamp in ISO 8601 format. Generated by `new Date().format(...)`. The format pattern `yyyy-MM-dd'T'HH:mm:ssZ` produces: - `yyyy` — 4-digit year - `MM` — 2-digit month - `dd` — 2-digit day - `'T'` — literal T separator - `HH:mm:ss` — 24-hour time - `Z` — timezone offset (e.g., `+0000`) **`Automatic-Module-Name: io.github.zekerzhayard.forgewrapper`** The JPMS module name for this JAR when it is placed on the module path. The expression `"${project.group}.${project.archivesBaseName}".toString().toLowerCase()` concatenates `io.github.zekerzhayard` + `.` + `ForgeWrapper`, converts to lowercase: `io.github.zekerzhayard.forgewrapper`. This allows other JPMS modules to `requires io.github.zekerzhayard.forgewrapper;`. **`Multi-Release: true`** The critical attribute. Tells the JVM (Java 9+) that this JAR contains version-specific class files under `META-INF/versions//`. Without this attribute, the JVM ignores the `META-INF/versions/` directory entirely. Defined in JEP 238 (Multi-Release JAR Files). **`GitCommit: `** (or `null`) Captures the Git commit SHA from the `GITHUB_SHA` environment variable. `String.valueOf(System.getenv("GITHUB_SHA"))` returns: - The 40-character SHA hex string when built in GitHub Actions. - The string `"null"` when built locally (since `getenv()` returns Java `null`, and `String.valueOf(null)` returns the string `"null"`). This attribute enables tracing a built artifact back to its exact source commit. ### 6.10 Multi-Release JAR Packing ```groovy into "META-INF/versions/9", { from configurations.multirelase.files.collect { zipTree(it) } exclude "META-INF/**" } } ``` Lines 58–63: This block within the `jar { }` closure is the mechanism that creates the Multi-Release JAR. Detailed breakdown: **`into "META-INF/versions/9"`** — All files produced by this `from` block are placed inside the `META-INF/versions/9/` directory within the JAR. This is the Java 9 version overlay directory per JEP 238. **`configurations.multirelase.files`** — Resolves the `multirelase` configuration, which contains `project(":jigsaw")`. This evaluates to the jigsaw subproject's JAR file (e.g., `jigsaw/build/libs/jigsaw.jar`). **`.collect { zipTree(it) }`** — For each file in the resolved configuration (there's exactly one: the jigsaw JAR), `zipTree()` treats it as a ZIP archive and returns a file tree of its contents. This effectively "explodes" the jigsaw JAR. **`exclude "META-INF/**"`** — Excludes the jigsaw JAR's own `META-INF/` directory (which contains its own `MANIFEST.MF`). Only actual class files are copied. This prevents nested/conflicting manifests. The net result: the jigsaw subproject's compiled class files (specifically `io/github/zekerzhayard/forgewrapper/installer/util/ModuleUtil.class`) are placed at: ``` META-INF/versions/9/io/github/zekerzhayard/forgewrapper/installer/util/ModuleUtil.class ``` When the JVM is Java 9+, it will load this class **instead of** the Java 8 stub at: ``` io/github/zekerzhayard/forgewrapper/installer/util/ModuleUtil.class ``` ### 6.11 Publishing Configuration ```groovy publishing { publications { maven(MavenPublication) { groupId "${project.group}" artifactId "${project.archivesBaseName}" version "${project.version}" from components.java } } repositories { maven { url = layout.buildDirectory.dir("maven") } } } tasks.publish.dependsOn build ``` Lines 65–82: Maven publishing setup. **Publication: `maven(MavenPublication)`** Defines a Maven publication with coordinates: - `groupId` = `io.github.zekerzhayard` - `artifactId` = `ForgeWrapper` - `version` = `projt-LOCAL` (or dated variant) **`from components.java`** — Publishes the Java component, which includes: - The main JAR (`ForgeWrapper-.jar`) - The sources JAR (`ForgeWrapper--sources.jar`) - A generated POM file with dependency metadata **Repository target:** ```groovy url = layout.buildDirectory.dir("maven") ``` Publishes to a local directory inside the build output: `forgewrapper/build/maven/`. This is **not** Maven Central or any remote repository. The published artifacts end up at: ``` build/maven/io/github/zekerzhayard/ForgeWrapper// ├── ForgeWrapper-.jar ├── ForgeWrapper--sources.jar ├── ForgeWrapper-.pom ├── ForgeWrapper-.module └── (checksums: .md5, .sha1, .sha256, .sha512) ``` **`tasks.publish.dependsOn build`** — Ensures the project is fully built before publishing. Without this, Gradle could attempt to publish before the JAR is assembled. ### 6.12 getVersionSuffix() ```groovy static String getVersionSuffix() { if (System.getenv("IS_PUBLICATION") != null || System.getenv("GITHUB_ACTIONS") == "true") return new SimpleDateFormat("-yyyy-MM-dd").format(new Date()) return "-LOCAL" } ``` Lines 84–89: A static method that determines the version suffix. **Logic:** 1. If the environment variable `IS_PUBLICATION` is set (to any value, including empty string — `!= null` is the check), append a date suffix. 2. **OR** if the environment variable `GITHUB_ACTIONS` equals the string `"true"` (which GitHub Actions always sets), append a date suffix. 3. Otherwise, append `-LOCAL`. **Important Groovy/Java note:** The `==` comparison with `System.getenv()` uses Java `String.equals()` semantics in Groovy when comparing strings. However, there is a subtle behavior: `System.getenv("GITHUB_ACTIONS")` returns `null` when not in GitHub Actions, and `null == "true"` evaluates to `false` in Groovy (no NPE), which is the desired behavior. **Date format:** `SimpleDateFormat("-yyyy-MM-dd")` produces strings like `-2026-04-05`. The leading `-` is part of the pattern, so the result includes the hyphen separator. **Version assembly flow:** ``` gradle.properties getVersionSuffix() Final version ───────────────── ────────────────── ───────────── fw_version = projt + "-LOCAL" → "projt-LOCAL" fw_version = projt + "-2026-04-05" → "projt-2026-04-05" ``` --- ## 7. Jigsaw Subproject build.gradle — Complete Analysis **File: `forgewrapper/jigsaw/build.gradle`** (27 lines) This subproject compiles the Java 9+ version of `ModuleUtil.java`. ### 7.1 Plugins ```groovy plugins { id "java" id "eclipse" } ``` Lines 1–4: Only `java` and `eclipse`. No `maven-publish` — the jigsaw subproject is never published independently. Its output is consumed exclusively by the root project's `jar` task via the `multirelase` configuration. ### 7.2 Java 9 Toolchain Auto-Detection ```groovy compileJava { if (JavaVersion.current() < JavaVersion.VERSION_1_9) { javaCompiler = javaToolchains.compilerFor { languageVersion = JavaLanguageVersion.of(9) } } sourceCompatibility = 9 targetCompatibility = 9 } ``` Lines 6–14: The compilation block with intelligent Java version detection. **The `if` check:** `JavaVersion.current()` returns the JVM version running Gradle itself. If Gradle is running on Java 8 (which is `< VERSION_1_9`), then the `javaCompiler` is overridden using Gradle's **Java Toolchain** feature. **`javaToolchains.compilerFor { languageVersion = JavaLanguageVersion.of(9) }`** This tells Gradle: "Find a Java 9 compiler on this system and use it for this compilation task." Gradle will search: 1. JDK installations registered in the toolchain registry. 2. Standard JDK installation directories (`/usr/lib/jvm/`, etc.). 3. JDKs managed by tools like SDKMAN!, jabba, or Gradle's auto-provisioning. If no Java 9+ JDK is found, the build fails with an error. **If Gradle is already running on Java 9+**, the `if` block is skipped entirely. The current JVM's compiler is used, with `sourceCompatibility = 9` and `targetCompatibility = 9` ensuring Java 9 bytecode is produced. **`sourceCompatibility = 9`** — Accept Java 9 language features (modules, private interface methods, etc.). The jigsaw `ModuleUtil.java` uses: - `java.lang.module.Configuration` - `java.lang.module.ModuleFinder` - `java.lang.module.ModuleReference` - `java.lang.module.ResolvedModule` - `ModuleLayer.boot()` - `List.of()` - `ClassLoader.getPlatformClassLoader()` These APIs do not exist in Java 8, which is why this code cannot be in the root project. **`targetCompatibility = 9`** — Emit class file version 53.0 (Java 9). The JVM only loads classes from `META-INF/versions/9/` if they are version 53.0 or higher. ### 7.3 JVM Version Attribute Override ```groovy configurations { apiElements { attributes { attribute TargetJvmVersion.TARGET_JVM_VERSION_ATTRIBUTE, 8 } } runtimeElements { attributes { attribute TargetJvmVersion.TARGET_JVM_VERSION_ATTRIBUTE, 8 } } } ``` Lines 16–27: This is a subtle but critical configuration. **Problem:** The jigsaw subproject compiles with `targetCompatibility = 9`, so Gradle automatically sets the `TargetJvmVersion` attribute on its `apiElements` and `runtimeElements` configurations to `9`. When the root project (which targets Java 8) depends on `project(":jigsaw")`, Gradle's dependency resolution would detect a JVM version mismatch and fail: ``` > Could not resolve project :jigsaw. > Incompatible because this component declares a component compatible with Java 9 and the consumer needed a component compatible with Java 8 ``` **Solution:** Override the `TARGET_JVM_VERSION_ATTRIBUTE` to `8` on both outgoing configurations (`apiElements` and `runtimeElements`). This tells Gradle: "Even though this project compiles with Java 9, treat its output as Java 8-compatible for dependency resolution purposes." This is safe because: 1. The jigsaw JAR is **never loaded directly** on Java 8. It is packed into `META-INF/versions/9/` and only loaded by Java 9+ JVMs. 2. The attribute override only affects Gradle's dependency resolution metadata, not the actual bytecode version. **`apiElements`** — The configuration used when another project declares a `compileOnly` or `api` dependency on this project. **`runtimeElements`** — The configuration used when another project declares an `implementation` or `runtimeOnly` dependency on this project. Both must be overridden because the root project's `multirelase` configuration (which extends `implementation`) resolves through `runtimeElements`. --- ## 8. Multi-Release JAR — Deep Dive The Multi-Release JAR (MRJAR) is the defining feature of ForgeWrapper's build system. Here is the complete picture. ### What is a Multi-Release JAR? Defined by [JEP 238](https://openjdk.org/jeps/238) and standardized in Java 9, a Multi-Release JAR allows a single JAR file to contain multiple versions of the same class, each compiled for a different Java version. The JVM automatically selects the appropriate version at runtime based on the JVM version. ### JAR Internal Structure ``` ForgeWrapper-projt-LOCAL.jar │ ├── META-INF/ │ ├── MANIFEST.MF │ │ ├── Multi-Release: true ← Activates MRJAR behavior │ │ ├── Specification-Title: ForgeWrapper │ │ ├── Specification-Vendor: ZekerZhayard │ │ ├── Specification-Version: projt │ │ ├── Implementation-Title: ForgeWrapper │ │ ├── Implementation-Version: projt-LOCAL │ │ ├── Implementation-Vendor: ZekerZhayard │ │ ├── Implementation-Timestamp: 2026-04-05T... │ │ ├── Automatic-Module-Name: io.github.zekerzhayard.forgewrapper │ │ └── GitCommit: null │ │ │ └── versions/ │ └── 9/ │ └── io/github/zekerzhayard/forgewrapper/installer/util/ │ └── ModuleUtil.class ← Java 9 bytecode (version 53.0) │ ├── io/github/zekerzhayard/forgewrapper/installer/ │ ├── Bootstrap.class ← Java 8 bytecode (version 52.0) │ ├── Installer.class │ ├── Main.class │ ├── detector/ │ │ ├── DetectorLoader.class │ │ ├── IFileDetector.class │ │ └── MultiMCFileDetector.class │ └── util/ │ └── ModuleUtil.class ← Java 8 bytecode (no-op stubs) ``` ### Runtime Class Selection ``` JVM Version Class Loaded for ModuleUtil ─────────── ────────────────────────────────────────────────── Java 8 io/github/.../util/ModuleUtil.class (root, no-ops) Java 9 META-INF/versions/9/io/github/.../util/ModuleUtil.class Java 10 META-INF/versions/9/io/github/.../util/ModuleUtil.class Java 11 META-INF/versions/9/io/github/.../util/ModuleUtil.class ... (same — highest ≤ JVM version wins) Java 21 META-INF/versions/9/io/github/.../util/ModuleUtil.class ``` The JVM always selects the highest versioned class that is ≤ the running JVM version. Since ForgeWrapper only has a version 9 overlay, all Java 9+ JVMs use the same Java 9 `ModuleUtil`. ### The Dual ModuleUtil Classes **Root ModuleUtil** (`src/main/java/.../util/ModuleUtil.java`) — 42 lines: ```java public class ModuleUtil { public static void addModules(String modulePath) { // nothing to do with Java 8 } public static void addExports(List exports) { // nothing to do with Java 8 } public static void addOpens(List opens) { // nothing to do with Java 8 } public static void setupClassPath(Path libraryDir, List paths) throws Throwable { // Uses URLClassLoader.addURL() via reflection } public static Class setupBootstrapLauncher(Class mainClass) { // nothing to do with Java 8 return mainClass; } public static ClassLoader getPlatformClassLoader() { // PlatformClassLoader does not exist in Java 8 return null; } } ``` **Jigsaw ModuleUtil** (`jigsaw/src/main/java/.../util/ModuleUtil.java`) — 150+ lines: The Java 9 version provides actual JPMS integration: - `addModules()` — Dynamically adds module paths to the boot module layer at runtime using `sun.misc.Unsafe` to access `MethodHandles.Lookup.IMPL_LOOKUP` and reflectively manipulate the module graph. - `addExports()` / `addOpens()` — Adds `--add-exports` / `--add-opens` at runtime via `Module.implAddExports()` and `Module.implAddOpens()`. - `setupClassPath()` — Uses the module system's `ModuleLayer` to properly add libraries. - `setupBootstrapLauncher()` — Sets up the BootstrapLauncher class introduced in newer Forge versions. - `getPlatformClassLoader()` — Returns `ClassLoader.getPlatformClassLoader()` (Java 9+ API, does not exist in Java 8). --- ## 9. Build Pipeline Diagram ### Complete Build Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ ./gradlew build │ └──────────────────────────────┬──────────────────────────────────┘ │ ┌────────────────┴────────────────┐ ▼ ▼ ┌──────────────────────┐ ┌──────────────────────┐ │ :compileJava │ │ :jigsaw:compileJava │ │ (Java 8, v52.0) │ │ (Java 9, v53.0) │ │ │ │ │ │ Source: │ │ Source: │ │ src/main/java/ │ │ jigsaw/src/main/ │ │ └─ ...ModuleUtil │ │ └─ ...ModuleUtil │ │ (no-op stubs) │ │ (full JPMS impl)│ └──────────┬───────────┘ └──────────┬───────────┘ │ │ ▼ ▼ ┌──────────────────────┐ ┌──────────────────────┐ │ :processResources │ │ :jigsaw:jar │ └──────────┬───────────┘ │ → jigsaw.jar │ │ └──────────┬───────────┘ │ │ │ ┌───────────────────────────┘ │ │ configurations.multirelase │ │ resolves to jigsaw.jar ▼ ▼ ┌──────────────────────────────────────────────┐ │ :jar │ │ │ │ 1. Pack root classes → / │ │ 2. zipTree(jigsaw.jar) │ │ exclude META-INF/** │ │ → META-INF/versions/9/ │ │ 3. Generate MANIFEST.MF with attributes │ │ including Multi-Release: true │ │ │ │ Output: build/libs/ForgeWrapper-.jar │ └──────────────────────┬───────────────────────┘ │ ┌────────────┼────────────┐ ▼ ▼ ▼ ┌──────────────┐ ┌──────────┐ ┌──────────────┐ │ :sourcesJar │ │ :check │ │ :assemble │ │ (sources) │ │ (tests) │ │ (lifecycle) │ └──────┬───────┘ └────┬─────┘ └──────┬───────┘ │ │ │ └──────────────┼──────────────┘ ▼ ┌──────────────────┐ │ :build │ └──────────────────┘ ``` ### Publishing Flow ``` ┌──────────────┐ │ :build │ └──────┬───────┘ │ tasks.publish.dependsOn build ▼ ┌──────────────────────────────────────────────────────┐ │ :publish │ │ │ │ Publication: maven(MavenPublication) │ │ groupId: io.github.zekerzhayard │ │ artifactId: ForgeWrapper │ │ version: projt-LOCAL (or projt-YYYY-MM-DD) │ │ │ │ from components.java: │ │ ├── ForgeWrapper-.jar │ │ └── ForgeWrapper--sources.jar │ │ │ │ Target: build/maven/ │ │ └── io/github/zekerzhayard/ForgeWrapper// │ │ ├── ForgeWrapper-.jar │ │ ├── ForgeWrapper--sources.jar │ │ ├── ForgeWrapper-.pom │ │ └── ForgeWrapper-.module │ └──────────────────────────────────────────────────────┘ ``` ### Version Resolution Flow ``` gradle.properties build.gradle ┌──────────────────┐ ┌──────────────────────────────────┐ │ fw_version=projt │─────▶│ version="${fw_version}${->...}" │ └──────────────────┘ │ │ │ │ ▼ │ │ getVersionSuffix() │ │ │ │ │ ├─ IS_PUBLICATION!=null? │ │ │ └─ YES → "-YYYY-MM-DD" │ │ │ │ │ ├─ GITHUB_ACTIONS=="true"? │ │ │ └─ YES → "-YYYY-MM-DD" │ │ │ │ │ └─ else → "-LOCAL" │ │ │ │ Result: "projt-LOCAL" │ │ or: "projt-2026-04-05" │ └──────────────────────────────────┘ ``` --- ## 10. Build Targets and Tasks ### Key Tasks | Task | Type | Description | |-----------------------------|-------------------|------------------------------------------------| | `:compileJava` | JavaCompile | Compiles root `src/main/java` with Java 8 | | `:processResources` | Copy | Copies `src/main/resources` to build dir | | `:classes` | Lifecycle | Depends on compileJava + processResources | | `:jar` | Jar | Assembles the Multi-Release JAR | | `:sourcesJar` | Jar | Assembles sources JAR | | `:assemble` | Lifecycle | Depends on jar + sourcesJar | | `:check` | Lifecycle | Runs tests (none configured) | | `:build` | Lifecycle | Depends on assemble + check | | `:publish` | Lifecycle | Publishes to build/maven/ (depends on build) | | `:jigsaw:compileJava` | JavaCompile | Compiles jigsaw `src/main/java` with Java 9 | | `:jigsaw:jar` | Jar | Packages jigsaw classes into jigsaw.jar | | `:eclipse` | Lifecycle | Generates Eclipse project files | | `:jigsaw:eclipse` | Lifecycle | Generates Eclipse files for jigsaw subproject | | `:clean` | Delete | Removes `build/` directory | | `:jigsaw:clean` | Delete | Removes `jigsaw/build/` directory | ### Task Dependency Chain Running `./gradlew build` triggers this chain: ``` :build ├── :assemble │ ├── :jar │ │ ├── :classes │ │ │ ├── :compileJava │ │ │ └── :processResources │ │ └── [multirelase config resolution] │ │ └── :jigsaw:jar │ │ └── :jigsaw:classes │ │ ├── :jigsaw:compileJava │ │ └── :jigsaw:processResources │ └── :sourcesJar └── :check └── :test (no tests configured → no-op) ``` ### What Each Task Produces | Task | Output | |-------------------------|-----------------------------------------------------| | `:compileJava` | `build/classes/java/main/**/*.class` | | `:jigsaw:compileJava` | `jigsaw/build/classes/java/main/**/*.class` | | `:jigsaw:jar` | `jigsaw/build/libs/jigsaw.jar` | | `:jar` | `build/libs/ForgeWrapper-.jar` | | `:sourcesJar` | `build/libs/ForgeWrapper--sources.jar` | | `:publish` | `build/maven/io/github/zekerzhayard/ForgeWrapper/` | --- ## 11. Step-by-Step Build Guide ### Prerequisites 1. **Java 8 or higher** — To run Gradle itself. Gradle 7.3.3 supports Java 8 through Java 17. 2. **Java 9 or higher JDK** — Required to compile the jigsaw subproject. If Gradle runs on Java 8, the toolchain must find a Java 9+ JDK. If Gradle runs on Java 9+, no additional JDK is needed. 3. **Internet access** — To download the Gradle wrapper distribution and Maven dependencies (first build only; cached after that). ### Clone and Build ```bash # Navigate to the forgewrapper directory cd forgewrapper/ # Make the wrapper executable (Linux/macOS) chmod +x gradlew # Build the project ./gradlew build ``` On Windows: ```cmd cd forgewrapper\ gradlew.bat build ``` ### Build Output After a successful build: ``` build/libs/ ├── ForgeWrapper-projt-LOCAL.jar ← Main MRJAR artifact └── ForgeWrapper-projt-LOCAL-sources.jar ← Source code archive ``` ### Build + Publish ```bash ./gradlew publish ``` This runs `build` first (due to `tasks.publish.dependsOn build`), then publishes: ``` build/maven/ └── io/ └── github/ └── zekerzhayard/ └── ForgeWrapper/ └── projt-LOCAL/ ├── ForgeWrapper-projt-LOCAL.jar ├── ForgeWrapper-projt-LOCAL-sources.jar ├── ForgeWrapper-projt-LOCAL.pom └── ForgeWrapper-projt-LOCAL.module ``` ### Clean Build ```bash ./gradlew clean build ``` Removes all generated files in `build/` and `jigsaw/build/` before rebuilding. ### Individual Tasks ```bash # Compile only the root project ./gradlew compileJava # Compile only the jigsaw subproject ./gradlew :jigsaw:compileJava # Build only the JAR (no tests, no publish) ./gradlew jar # Generate Eclipse project files ./gradlew eclipse # List all available tasks ./gradlew tasks --all # Show the dependency tree ./gradlew dependencies ``` ### Simulating CI Build Locally ```bash # Set environment variables to simulate GitHub Actions GITHUB_ACTIONS=true GITHUB_SHA=abc123def456 ./gradlew build # Or force a publication-style version IS_PUBLICATION=1 ./gradlew build ``` With either of these, the version suffix changes from `-LOCAL` to the current date (e.g., `-2026-04-05`), and `GitCommit` in the manifest is set to the provided SHA. ### Verbose/Debug Build ```bash # Show task execution details ./gradlew build --info # Full debug logging ./gradlew build --debug # Show dependency resolution details ./gradlew build --scan ``` --- ## 12. CI/CD Integration The build system detects CI environments via environment variables. ### GitHub Actions Detection Two environment variables are checked in `getVersionSuffix()` (line 86 of `build.gradle`): **`GITHUB_ACTIONS`** — Automatically set to `"true"` by GitHub Actions runners. When detected, the version suffix switches from `-LOCAL` to a date stamp. **`GITHUB_SHA`** — The full SHA of the commit that triggered the workflow. This is embedded in the JAR manifest as the `GitCommit` attribute (line 55 of `build.gradle`): ```groovy "GitCommit": String.valueOf(System.getenv("GITHUB_SHA")) ``` ### IS_PUBLICATION **`IS_PUBLICATION`** — A custom environment variable. When set (to any non-null value), it forces date-stamped versioning regardless of whether the build runs in GitHub Actions. This allows publication builds from other CI systems or local environments: ```bash IS_PUBLICATION=yes ./gradlew publish ``` ### CI Build vs Local Build Comparison ``` ┌───────────────────────┬─────────────────────┬──────────────────────┐ │ Aspect │ Local Build │ CI Build │ ├───────────────────────┼─────────────────────┼──────────────────────┤ │ Version suffix │ -LOCAL │ -2026-04-05 │ │ GitCommit manifest │ null │ abc123def456... │ │ Gradle daemon │ disabled (property) │ disabled (property) │ │ Full version example │ projt-LOCAL │ projt-2026-04-05 │ │ Spec-Version │ projt │ projt │ │ Impl-Version │ projt-LOCAL │ projt-2026-04-05 │ └───────────────────────┴─────────────────────┴──────────────────────┘ ``` ### Environment Variable Summary | Variable | Set By | Used In | Effect | |------------------|------------------|---------------------------|--------------------------------| | `GITHUB_ACTIONS` | GitHub Actions | `getVersionSuffix()` | Enables date-stamped version | | `GITHUB_SHA` | GitHub Actions | `jar.manifest.attributes` | Records commit SHA in manifest | | `IS_PUBLICATION` | Manual / CI | `getVersionSuffix()` | Forces date-stamped version | --- ## 13. Artifact Output Structure ### Primary Artifact: ForgeWrapper JAR **File:** `build/libs/ForgeWrapper-.jar` Inspecting the JAR contents (example): ```bash jar tf build/libs/ForgeWrapper-projt-LOCAL.jar ``` Expected output: ``` META-INF/ META-INF/MANIFEST.MF io/ io/github/ io/github/zekerzhayard/ io/github/zekerzhayard/forgewrapper/ io/github/zekerzhayard/forgewrapper/installer/ io/github/zekerzhayard/forgewrapper/installer/Bootstrap.class io/github/zekerzhayard/forgewrapper/installer/Installer.class io/github/zekerzhayard/forgewrapper/installer/Main.class io/github/zekerzhayard/forgewrapper/installer/detector/ io/github/zekerzhayard/forgewrapper/installer/detector/DetectorLoader.class io/github/zekerzhayard/forgewrapper/installer/detector/IFileDetector.class io/github/zekerzhayard/forgewrapper/installer/detector/MultiMCFileDetector.class io/github/zekerzhayard/forgewrapper/installer/util/ io/github/zekerzhayard/forgewrapper/installer/util/ModuleUtil.class META-INF/versions/ META-INF/versions/9/ META-INF/versions/9/io/ META-INF/versions/9/io/github/ META-INF/versions/9/io/github/zekerzhayard/ META-INF/versions/9/io/github/zekerzhayard/forgewrapper/ META-INF/versions/9/io/github/zekerzhayard/forgewrapper/installer/ META-INF/versions/9/io/github/zekerzhayard/forgewrapper/installer/util/ META-INF/versions/9/io/github/zekerzhayard/forgewrapper/installer/util/ModuleUtil.class ``` ### Sources Artifact **File:** `build/libs/ForgeWrapper--sources.jar` Contains `.java` source files from the root project's `src/main/java/` tree. ### Published Maven Artifacts **Directory:** `build/maven/io/github/zekerzhayard/ForgeWrapper//` | File | Description | |------------------------------------------|------------------------------------| | `ForgeWrapper-.jar` | The MRJAR binary | | `ForgeWrapper--sources.jar` | Source code archive | | `ForgeWrapper-.pom` | Maven POM with dependency metadata | | `ForgeWrapper-.module` | Gradle Module Metadata (GMM) | | `*.md5`, `*.sha1`, `*.sha256`, `*.sha512`| Integrity checksums | ### Manifest File Content The `META-INF/MANIFEST.MF` in the produced JAR: ``` Manifest-Version: 1.0 Specification-Title: ForgeWrapper Specification-Vendor: ZekerZhayard Specification-Version: projt Implementation-Title: ForgeWrapper Implementation-Version: projt-LOCAL Implementation-Vendor: ZekerZhayard Implementation-Timestamp: 2026-04-05T12:00:00+0000 Automatic-Module-Name: io.github.zekerzhayard.forgewrapper Multi-Release: true GitCommit: null ``` --- ## 14. Publishing to Local Maven Repository ### How It Works The `publishing` block in `build.gradle` (lines 65–80) configures a Maven publication with a **local filesystem repository**: ```groovy repositories { maven { url = layout.buildDirectory.dir("maven") } } ``` `layout.buildDirectory.dir("maven")` resolves to `build/maven/`. This is a Gradle 7+ API (`layout.buildDirectory` replaces the deprecated `$buildDir`). ### Running the Publish ```bash ./gradlew publish ``` The `publish` task depends on `build` (line 81: `tasks.publish.dependsOn build`), so running `publish` implicitly runs the full build first. ### Generated POM The POM is auto-generated from `components.java`. Since all external dependencies are `compileOnly`, they are **not** included in the POM. The POM contains only the GAV (Group, Artifact, Version) coordinates: ```xml 4.0.0 io.github.zekerzhayard ForgeWrapper projt-LOCAL ``` No `` section is generated because `compileOnly` dependencies are not published. ### Using the Local Maven Repo Other projects can consume the published artifact by adding the local directory as a Maven repository: ```groovy repositories { maven { url = file("/path/to/forgewrapper/build/maven") } } dependencies { implementation "io.github.zekerzhayard:ForgeWrapper:projt-LOCAL" } ``` --- ## 15. Java Version Requirements ### Summary Table | Component | Minimum Java | Configured As | |---------------------|--------------|---------------------------------------------| | Gradle execution | Java 8 | Gradle 7.3.3 supports Java 8–17 | | Root compilation | Java 8 | `sourceCompatibility = targetCompatibility = 1.8` | | Jigsaw compilation | Java 9 | `sourceCompatibility = targetCompatibility = 9` | | Runtime (Java 8) | Java 8 | Uses root ModuleUtil (no-op stubs) | | Runtime (Java 9+) | Java 9 | Uses jigsaw ModuleUtil (full JPMS) | ### Toolchain Behavior The jigsaw subproject uses Gradle's Java Toolchain feature with conditional logic (lines 7–9 of `jigsaw/build.gradle`): ``` ┌────────────────────────────────┐ │ Gradle running on Java 8? │ │ │ │ YES → javaToolchains finds │ │ Java 9 JDK on system │ │ and uses it to compile │ │ │ │ NO → Current JVM (≥9) │ │ compiles with │ │ sourceCompatibility=9 │ └────────────────────────────────┘ ``` ### Finding Java Toolchains When Gradle needs a Java 9 toolchain, it searches these locations: 1. **Environment** — `JAVA_HOME`, `JDK_HOME`, and `PATH` entries. 2. **Standard paths** — `/usr/lib/jvm/` (Linux), `/Library/Java/JavaVirtualMachines/` (macOS), Windows Registry. 3. **Tool managers** — SDKMAN!, jabba, IntelliJ installations. 4. **Gradle auto-provisioning** — If enabled, Gradle can download a JDK automatically from AdoptOpenJDK/Adoptium. ### Bytecode Versions | Class Origin | Target | Class File Version | `-target` flag | |---------------------|--------|--------------------|----------------| | Root project | 1.8 | 52.0 | `1.8` | | Jigsaw subproject | 9 | 53.0 | `9` | You can verify bytecode versions with `javap`: ```bash # Check root ModuleUtil (should be 52.0 = Java 8) javap -v build/classes/java/main/io/github/zekerzhayard/forgewrapper/installer/util/ModuleUtil.class \ | grep "major version" # Check jigsaw ModuleUtil (should be 53.0 = Java 9) javap -v jigsaw/build/classes/java/main/io/github/zekerzhayard/forgewrapper/installer/util/ModuleUtil.class \ | grep "major version" ``` --- ## 16. Source File Layout and the Dual-ModuleUtil Pattern ### Why Two ModuleUtil Classes? ForgeWrapper must run on both Java 8 and Java 9+ JVMs. The Java 9+ `ModuleUtil` uses APIs that don't exist in Java 8: | API Used in Jigsaw ModuleUtil | Introduced In | |-----------------------------------------|---------------| | `java.lang.module.Configuration` | Java 9 | | `java.lang.module.ModuleFinder` | Java 9 | | `java.lang.module.ModuleReference` | Java 9 | | `java.lang.module.ResolvedModule` | Java 9 | | `ModuleLayer.boot()` | Java 9 | | `ClassLoader.getPlatformClassLoader()` | Java 9 | | `List.of()` | Java 9 | | `Module.implAddExports()` | Java 9 (internal) | | `Module.implAddOpens()` | Java 9 (internal) | If these APIs were in the main source tree compiled with Java 8, the build would fail with compilation errors. The Multi-Release JAR approach solves this by keeping the Java 9 code in a separate compilation unit. ### Method Signature Compatibility Both `ModuleUtil` classes must have **identical method signatures** so that callers in the root project (e.g., `Bootstrap.java`, `Main.java`) can reference `ModuleUtil` without caring which version is loaded at runtime. **Root ModuleUtil (Java 8 stubs):** ```java public static void addModules(String modulePath) // line 10: empty body public static void addExports(List exports) // line 14: empty body public static void addOpens(List opens) // line 18: empty body public static void setupClassPath(Path, List) // line 22: URLClassLoader reflection public static Class setupBootstrapLauncher(Class)// line 31: returns mainClass public static ClassLoader getPlatformClassLoader() // line 36: returns null ``` **Jigsaw ModuleUtil (Java 9 implementation):** ```java public static void addModules(String modulePath) // Full JPMS module loading public static void addExports(List exports) // Module.implAddExports public static void addOpens(List opens) // Module.implAddOpens public static void setupClassPath(Path, List) // Module-aware loading public static Class setupBootstrapLauncher(Class)// BootstrapLauncher setup public static ClassLoader getPlatformClassLoader() // ClassLoader.getPlatformClassLoader() ``` ### Call Sites `Bootstrap.java` calls these ModuleUtil methods (lines 70–76): ```java if (modulePath != null) { ModuleUtil.addModules(modulePath); } ModuleUtil.addExports(addExports); ModuleUtil.addOpens(addOpens); ``` `Main.java` calls (lines 49, 62, 63): ```java // line 49 (in URLClassLoader creation): ModuleUtil.getPlatformClassLoader() // lines 62-63: ModuleUtil.setupClassPath(detector.getLibraryDir(), ...); Class mainClass = ModuleUtil.setupBootstrapLauncher(Class.forName(...)); ``` At runtime, the JVM transparently loads the correct `ModuleUtil` class based on the Java version, with no conditional logic needed in the calling code. --- ## 17. Troubleshooting ### Build Fails: "No compatible toolchains found" **Symptom:** ``` > No locally installed toolchains match and toolchain download repositories have not been configured. ``` **Cause:** Gradle is running on Java 8 and cannot find a Java 9+ JDK for the jigsaw subproject. **Fix:** Install a Java 9+ JDK. On Linux: ```bash # Ubuntu/Debian sudo apt install openjdk-11-jdk # Fedora sudo dnf install java-11-openjdk-devel ``` Or set `JAVA_HOME` to an existing Java 9+ installation: ```bash export JAVA_HOME=/path/to/jdk-11 ./gradlew build ``` ### Build Fails: "Could not resolve project :jigsaw" **Symptom:** ``` > Could not resolve project :jigsaw. > Incompatible because this component declares a component compatible with Java 9 and the consumer needed a component compatible with Java 8 ``` **Cause:** The `TargetJvmVersion` attribute override in `jigsaw/build.gradle` is missing or incorrect. **Fix:** Ensure lines 16–27 of `jigsaw/build.gradle` are present: ```groovy configurations { apiElements { attributes { attribute TargetJvmVersion.TARGET_JVM_VERSION_ATTRIBUTE, 8 } } runtimeElements { attributes { attribute TargetJvmVersion.TARGET_JVM_VERSION_ATTRIBUTE, 8 } } } ``` ### Dependencies Not Found **Symptom:** ``` > Could not find cpw.mods:modlauncher:8.0.9. ``` **Cause:** The Forge Maven repository is unreachable or not declared. **Fix:** Check network connectivity to `https://maven.minecraftforge.net/`. Verify the `repositories` block in `build.gradle` includes the `forge` maven repository (lines 24–29). ### Wrong Version in JAR Name **Symptom:** JAR is named `ForgeWrapper-projt-LOCAL.jar` but you expected a dated version. **Cause:** `GITHUB_ACTIONS` and `IS_PUBLICATION` are not set. **Fix:** ```bash IS_PUBLICATION=1 ./gradlew build ``` ### MultiRelease Attribute Missing **Symptom:** The JAR does not exhibit Multi-Release behavior on Java 9+. `ModuleUtil` methods are no-ops even on Java 11. **Diagnosis:** Inspect the manifest: ```bash unzip -p build/libs/ForgeWrapper-*.jar META-INF/MANIFEST.MF | grep Multi-Release ``` If `Multi-Release: true` is missing, check the `jar` block in `build.gradle` (line 54). Also verify the jigsaw classes exist in the JAR: ```bash jar tf build/libs/ForgeWrapper-*.jar | grep "META-INF/versions/9" ``` Expected output should show the `ModuleUtil.class` under `META-INF/versions/9/`. ### Gradle Daemon Issues **Symptom:** Stale build state, phantom errors that disappear after restarting. **Note:** The daemon is disabled (`org.gradle.daemon = false` in `gradle.properties`), so this should not normally occur. If a daemon is somehow running from a previous configuration: ```bash ./gradlew --stop ./gradlew clean build ``` ### Java Version Mismatch in IDE **Symptom:** Eclipse or IntelliJ shows errors on jigsaw source files. **Cause:** The IDE is using Java 8 to compile the jigsaw source set. **Fix for Eclipse:** ```bash ./gradlew eclipse ``` Then re-import the project. The Eclipse plugin generates `.classpath` with correct JRE containers. **Fix for IntelliJ:** Import as Gradle project. IntelliJ reads the `compileJava` block and sets the jigsaw module to use Java 9. ### Verifying the MRJAR Full verification workflow: ```bash # 1. Build ./gradlew clean build # 2. Check JAR contents jar tf build/libs/ForgeWrapper-projt-LOCAL.jar # 3. Verify manifest unzip -p build/libs/ForgeWrapper-projt-LOCAL.jar META-INF/MANIFEST.MF # 4. Check bytecode versions cd build/libs mkdir -p _verify && cd _verify jar xf ../ForgeWrapper-projt-LOCAL.jar # Root ModuleUtil → should be 52 (Java 8) javap -v io/github/zekerzhayard/forgewrapper/installer/util/ModuleUtil.class \ | grep "major version" # Jigsaw ModuleUtil → should be 53 (Java 9) javap -v META-INF/versions/9/io/github/zekerzhayard/forgewrapper/installer/util/ModuleUtil.class \ | grep "major version" # 5. Cleanup cd .. && rm -rf _verify ``` --- ## 18. Quick Reference Card ``` ┌──────────────────────────────────────────────────────────────────┐ │ ForgeWrapper Build Cheat Sheet │ ├──────────────────────────────────────────────────────────────────┤ │ │ │ Build: ./gradlew build │ │ Clean+Build: ./gradlew clean build │ │ Publish: ./gradlew publish │ │ JAR only: ./gradlew jar │ │ Eclipse: ./gradlew eclipse │ │ Tasks list: ./gradlew tasks --all │ │ Dependencies: ./gradlew dependencies │ │ │ │ CI version: GITHUB_ACTIONS=true ./gradlew build │ │ Pub version: IS_PUBLICATION=1 ./gradlew build │ │ │ │ Gradle: 7.3.3 (wrapper) │ │ Root Java: 1.8 (source + target) │ │ Jigsaw Java: 9 (source + target, toolchain auto-detect) │ │ Group: io.github.zekerzhayard │ │ Artifact: ForgeWrapper │ │ Base Version: projt (from gradle.properties: fw_version) │ │ │ │ Output JAR: build/libs/ForgeWrapper-.jar │ │ Sources JAR: build/libs/ForgeWrapper--sources.jar │ │ Maven output: build/maven/ │ │ │ │ Repos: Maven Central │ │ https://maven.minecraftforge.net/ │ │ │ │ Dependencies (all compileOnly): │ │ gson 2.8.7, modlauncher 8.0.9, │ │ installer 2.2.7, jopt-simple 5.0.4 │ │ │ │ MRJAR overlay: META-INF/versions/9/ (from :jigsaw) │ │ Manifest key: Multi-Release: true │ │ │ └──────────────────────────────────────────────────────────────────┘ ``` --- *This document was generated from direct analysis of the ForgeWrapper build configuration files: `build.gradle`, `jigsaw/build.gradle`, `settings.gradle`, `gradle.properties`, and `gradle/wrapper/gradle-wrapper.properties`.*