Forge Community Wiki - User contributions [en-gb]

Jar-in-Jar

2022-10-15T14:53:45Z

AterAnimAvis: Update link to sources

Jar-in-Jar is a way to handle the dependencies of your mod.
Sometimes these are libraries pulled from a central maven repository, sometimes these are libraries specially designed for Minecraft and sometimes these are completely other mods.
Whatever the reason for using a library during the development of your mods, you will need to ensure that the end user has them available when he runs your mod in his environment.

Although there are several options available to achieve this, including for example the Shading plugin, this does not work all the time and can even cause problems along the way when for example two mods need the same dependency.
Introducing the all-new, all-shiny: Jar-In-Jar.
====Central function====
Jar-In-Jar is first and foremost a way to load dependencies for mods, from the jars of the mods.
To achieve this it looks for a file called: ''META-INF/jarjar/metadata.json''. If you are interested in the format of this file, see the following section of the JarJar library which we expose: [https://github.com/MinecraftForge/JarJar/tree/main/metadata/src/main/java/net/minecraftforge/jarjar/metadata JarJar Library - Metadata Source]

In short, this metadata file lists a set of dependencies to include, what their maven coordinate is, the accepted version range that your mod supports, the version of the dependency that is included in your mods jar as well as a path to the jar in your mods jar file.

During the startup of the game, FML will first collect all mods and then collect all their dependencies to load. Jar-In-Jar hooks into this second phase and reads all the dependency files (recursively) and then determines what versions of the dependencies to load.
====Dependency negotiation====
Because different mods might need different versions of the same dependency (and have those included) Jar-In-Jar is first and foremost a negotiation system (hence you having to supply a version range your mod supports). From all dependencies that need to be loaded their supported version range is narrowed down to the agreeable range that all mods support. Then there are in principle three outcomes that can occur:
# No agreeable version range is found: Loading can not continue and the user will see an error message that mods require different dependency versions which are not compatible.
# An agreeable version range is found, but no jar was included in any of the dependencies which have a version that fits in the agreed range: Loading can not continue and the user will see an error message that the mods have agreed upon a supported range, but no file was found with the required version.
# An agreeable version range is found, and a matching jar could be located: That dependency will be loaded.

====Dependency loading====
Once negotiation ends, the selected jars are loaded into the game.
The class loading layer is determined in two ways:
# The default way: If a mod, plugin, or language loader is detected then it is loaded in the appropriate layer and processed as such.
# The override way: If a library is supposed to be loaded which is not aware of Minecraft (for example JGraphT) then it will be loaded as a game library only. Meaning that your mod has access to it, but not plugins or language loaders. Those as such can only use libraries that are Minecraft aware or Shaded instead of Jar-In-Jarred into their respective jar.

=== Using ForgeGradle to generate a Jar-In-Jar ===
Jar-In-Jar is a completely optional system.
To enable it, you need to call `jarJar.enable()` anywhere in your buildscript.
By default, this will include all the dependencies in the `jarjar` configuration into the task output of the `jarJar` task.
''Note: The task jarJar is not accessible via the `jarJar` statement, since this references the project extension to manage Jar-In-Jar. If you need to modify the task use: `tasks.jarJar.configure { ... } `''

==== Using the runtime dependencies ====
To include the runtime dependencies as well, you can invoke `jarJar.fromRuntimeConfiguration()` which will include the dependencies which are found at the runtime. If you use this, it is highly suggested to include a dependency filter, since else every single dependency, including Minecraft, forge, and their dependencies are included as well.

==== Using dependency filters ====
While you can filter the dependencies by including them in the `jarJar` configuration or not, this is not always as flexible as you need it to be. To achieve fine grain filtering the dependency configuration endpoint has been added to the `jarJar` extension as well as to the `jarJar` task.
Using this endpoint you can configure dependency patterns (including using regular expressions) which you can include and exclude from the configuration:

===== Exclude gson example =====
dependencies {
exclude(dependency('com.google.gson.*'))
}
This example excludes any dependency which has `com.google.gson.` as a prefix of the group name of that artifact.

===== Include filters with runtime configuration usage =====
It is generally recommended to set at least one `include` filter when using the `fromRuntimeConfiguration` option.

==== Dependency version pinning ====
Since Jar-In-Jar is first and foremost a negotiation system it is required that you provide a way to supply it with a supported range, by default this is done via the version property of your dependency:
dependencies {
jarJar(group: 'com.google.code.gson', name: 'gson', version: '[2.0,3.0)')
}
However, this might not produce the required result or even the required artifact you wish to include (by default the highest supported version is included based on Gradle dependency resolution rules).
Using dependency version pinning you can specify which version of the dependency Jar-In-Jar should include when the jar is made. To achieve this configure the dependency and invoke: `jarJar.pin(<dependency instance>, "version_string")` as follows:
dependencies {
implementation(group: 'com.google.code.gson', name: 'gson', version: '[2.0,3.0)') {
jarJar.pin(it, "2.8.0")
}
}
The example above will include version 2.8.0 of the GSON library into the Jar-In-Jar jar built by the `jarJar` task.

==== Dependency range pinning ====
Next to dependency version pinning Jar-In-Jar also supports pinning the version range which your mod supports, outside of the compile dependency range that you specify in the dependency statement:
dependencies {
implementation(group: 'com.google.code.gson', name: 'gson', version: '2.8.0') {
jarJar.ranged(it, "[2.0,3.0)")
}
}
As you can see this function is very useful when you combine it with runtime configuration-based dependency selection since it allows you to use a single statement to add the dependency to your project, as well as include it with a properly supported version range within your Jar-In-Jar jar.

==== Publishing a Jar-in-Jar jar to maven ====
Although in practice this is not really useful to do, for archival reasons FG supports publishing Jar-In-Jar artifacts to a maven of choice. The setup is similar to how the Shadow plugin handles this:
publications {
mavenJava(MavenPublication) {
from components.java
jarJar.component(it)

//Other statements related to configuring the POM go here
}
}

Using this technique will add all Jar-In-Jar you build in the project to the publication at once and publish them with the other artifacts.
If you want to only publish a specific Jar-In-Jar artifact to this publication use the following statement, which accepts a task instance to achieve this:
publications {
mavenJava(MavenPublication) {
from components.java
jarJar.component(it, tasks.jarJarOther)

//Other statements related to configuring the POM go here
}
}

Dependencies

2021-05-09T19:46:08Z

AterAnimAvis: Basic CurseMaven description

A '''dependency''' is the reliance of a piece of software on another piece of software. In the context of Minecraft Forge, it is a mod or library which another mod relies or ''depends'' on.

Dependencies are declared in three ways:
* The <code>dependencies</code> block in a Gradle buildscript defines compile-time and runtime dependencies, which are used by the build system and compiler when building or running the mod in the development environment.
* The act of using classes, fields, and methods from a library creates a dependency on the library in the compiled binaries. The library may be an explicitly declared dependency, or a dependency of an explicitly declared dependency (such as the Guava libraries that Minecraft depends on).
* [[Proper_Mod_Structuring#Dependency_Configurations|Dependency configurations]] are declared in the <tt>mods.toml</tt> metafile, which is then checked by Forge on runtime on whether they are satisfied.

== Hard and Soft Dependencies ==
There are two types of mod dependencies: hard dependencies, and soft dependencies.

A '''hard dependency''' is a dependency where the dependent mod requires that the dependency is present. This may be in the form of a code dependency, wherein the JVM will crash due to the missing class, field, or method from the dependency, or it may be in the form of a dependency configuration which mandates that the dependency is present.

Hard dependencies should be declared using a dependency configuration to allow the Forge Mod Loader to detect the missing dependency and gracefully handle it by showing an error screen to the user, rather than the JVM crashing with a non-user-friendly exception message.

A '''soft dependency''' is a dependency where the dependent mod does not require the dependency is present, but extra features or compatibility is added in the case of the dependency being present. This often takes the form of cross-mod compatibility features, where a mod soft-depends on another mod or the mod's API.

Soft dependencies usually take the form of isolated code dependencies, where the code that depends on the soft-dependency is isolated from the rest of the mod until the soft-dependency is detected as being present.

== Declaring Dependencies ==
A mod declares a dependency on a mod or library through Gradle, through the <code>dependencies</code> block.<ref>[https://docs.gradle.org/6.8.1/userguide/declaring_dependencies.html Gradle User Guide for 6.8.1: ''Declaring dependencies'']</ref>

For example, to declare a dependency on the <code>net:minecraftforge:eventbus:4.0.0</code> library from the <code>main</code> source set:
<syntaxhighlight lang="gradle">
dependencies {
// 'implementation' is for the main source set
implementation "net.minecraftforge:eventbus:4.0.0"
}
</syntaxhighlight>

{{Tip|ForgeGradle automatically adds the [https://files.minecraftforge.net/maven/ Forge Maven] and [https://maven.apache.org/repository/ Maven Central] repositories to projects. If a dependency is not present in these (such as dependencies on other mods), the repository containing the dependency must be declared in the <code>repositories</code> block of the Gradle buildscript.<ref>[https://docs.gradle.org/6.8.1/userguide/declaring_repositories.html Gradle User Guide for 6.8.1: ''Declaring repositories'']</ref>}}

=== Deobfuscating Dependencies ===
Mods (and libraries which use Minecraft code) are usually released as an SRG-obfuscated JAR, which prevents their direct use in development environments due to mismatch between SRG names from the mod/library and the MCP/mapped names in the development environment.

These mods/libraries must be deobfuscated to the development environment's mappings first. This is done using the <code>fg.deobf</code> function, which creates a dependency which is dynamically remapped to the local environment's mappings.

For example, to declare a dependency on the <code>mezz.jei:jei-1.16.5:7.6.1.75</code> library (which is obfuscated):
<syntaxhighlight lang="gradle">
dependencies {
implementation fg.deobf("mezz.jei:jei-1.16.5:7.6.1.75")
}
</syntaxhighlight>

=== Flat Directory Repositories ===
There are occasions where it is needed to temporarily add a dependency on a JAR file that is not present in a Maven repository, such as to add a mod which adds some developer tools during runtime. Gradle allows declaring '''flat directory repositories''', which use a local directory as a simplified repository.<ref>[https://docs.gradle.org/current/userguide/declaring_repositories.html#sub:flat_dir_resolver Gradle User Guide for 6.8.1: ''Flat directory repository'']</ref>

A flat directory repository is declared using a <code>flatDir</code> block within the <code>repositories</code> block, and specifying directories using <code>dirs</code>:
<syntaxhighlight lang="gradle">
repositories {
flatDir {
dirs 'lib'
}
}
</syntaxhighlight>

When a dependency artifact is searched for in a flat directory repository, it will look for the following files in order (<code>''ext''</code> defaults to <code>jar</code>)<ref>[https://github.com/gradle/gradle/blob/v6.8.1/subprojects/core-api/src/main/java/org/gradle/api/artifacts/repositories/FlatDirectoryArtifactRepository.java gradle/gradle; tag v6.8.1; org.gradle.api.artifacts.repositories.FlatDirectoryArtifactRepository]</ref>:
* <code>''<artifact>''-''<version>''.''<ext>''</code>
* <code>''<artifact>''-''<version>''-''<classifier>''.''<ext>''</code>
* <code>''<artifact>''.''<ext>''</code>
* <code>''<artifact>''-''<classifier>''.''<ext>''</code>

For example, for the dependency <code>junit:junit:4.8.1</code>, it will first search for <code>junit-4.8.1.jar</code> then <code>junit.jar</code>. The group ID in the dependency descriptor must be present (due to the presence of non-flat directory repositories as added by ForgeGradle), but it will always be ignored.

{{Tip/Warning
|Flat directory repositories should ''only'' be used temporarily in a local environment, and not used to include a required dependency for your project. For a actual dependency used by your mod, use a remote Maven repository holding the artifact.
}}

=== CurseMaven ===
A commonly used alternative is [https://www.cursemaven.com/ CurseMaven](credits to Wyn Price) which allows you to depend on any file uploaded to [https://www.curseforge.com/minecraft/mc-mods/ CurseForge].

First add the CurseMaven Repository within the <code>repositories</code> block:
<syntaxhighlight lang="gradle">
repositories {
maven {
url 'https://www.cursemaven.com'
// FG4: It's recommended to uncomment the following block
// content {
// includeGroup "curse.maven"
// }
}
}
</syntaxhighlight>

Then declare a dependency using the following format:
* <code>''curse.maven'':''<description>-<project-id>'':''<file-id>''</code>

As an example, the dependency <code>curse.maven:jei-238222:3295418 </code>, would resolve to [https://www.curseforge.com/minecraft/mc-mods/jei/files/3295418 this file] on CurseForge.

For more information on usage, visit [https://www.cursemaven.com/ CurseMaven]