Forge Community Wiki

Changes

User:ChampionAsh5357/1.17.1/Toolchain (view source)

Revision as of 05:54, 7 August 2021

3,178 bytes removed ,  05:54, 7 August 2021
Maybe an updated toolchain?
Line 8: Line 8:  
== Overall process ==
 
== Overall process ==
 
When setting up the environment for the first time, a gradle refresh triggers three things:
 
When setting up the environment for the first time, a gradle refresh triggers three things:
−
# ForgeGradle downloads the MCPConfig zip for the file you're using, and triggers the SetupMCP task.
+
# ForgeGradle downloads the MCPConfig zip for the file you're using, and triggers the extractSrg/createSrgToMcp task.
 
# After that, it processes the jar - applies access transformers, side stripper and others
 
# After that, it processes the jar - applies access transformers, side stripper and others
 
# Finally, it patches and finalizes the code, ready for modder consumption.
 
# Finally, it patches and finalizes the code, ready for modder consumption.
Line 47: Line 47:     
=== Download and parsing MCPConfig ===
 
=== Download and parsing MCPConfig ===
−
The first thing that ForgeGradle does upon initializing a first-time setup, is starting the [https://github.com/MinecraftForge/ForgeGradle/blob/a0d2d1f488b3285ef7c75367feeebbe1a38aa19b/src/mcp/java/net/minecraftforge/gradle/mcp/tasks/SetupMCP.java#L74 SetupMCP] task.  
+
The first thing that ForgeGradle does upon initializing a first-time setup, is starting the [https://github.com/MinecraftForge/ForgeGradle/blob/a0d2d1f488b3285ef7c75367feeebbe1a38aa19b/src/mcp/java/net/minecraftforge/gradle/mcp/tasks/SetupMCP.java#L74 SetupMCP] task.
   −
This task then seeks to [https://github.com/MinecraftForge/ForgeGradle/blob/a0d2d1f488b3285ef7c75367feeebbe1a38aa19b/src/mcp/java/net/minecraftforge/gradle/mcp/tasks/DownloadMCPConfig.java#L68 download the MCPConfig.zip jar] for the version you're setting up.
+
This task then seeks to [https://github.com/MinecraftForge/ForgeGradle/blob/a0d2d1f488b3285ef7c75367feeebbe1a38aa19b/src/mcp/java/net/minecraftforge/gradle/mcp/tasks/DownloadMCPConfig.java#L68 download the MCPConfig.zip jar] for the version you're setting up
 
Once it is acquired, it  
 
Once it is acquired, it  
 
[https://github.com/MinecraftForge/ForgeGradle/blob/a0d2d1f488b3285ef7c75367feeebbe1a38aa19b/src/mcp/java/net/minecraftforge/gradle/mcp/util/MCPRuntime.java#L75 parses the steps contained within the config.json]. It does this by interpreting the file with the following rules:
 
[https://github.com/MinecraftForge/ForgeGradle/blob/a0d2d1f488b3285ef7c75367feeebbe1a38aa19b/src/mcp/java/net/minecraftforge/gradle/mcp/util/MCPRuntime.java#L75 parses the steps contained within the config.json]. It does this by interpreting the file with the following rules:
Line 78: Line 78:  
= TODO UPDATE BELOW =
 
= TODO UPDATE BELOW =
   −
=== MCInjector ===
+
=== ForgeFlower ===  
−
[https://github.com/ModCoderPack/MCInjector MCInjector] is the tool we use to apply various fixes to the code, while it is still in bytecode form. That meaning, it works on compiled code, not sourcecode. It does this because it's easier to rename LVT entries (from the snowman) to readable names while you can search for every other code path that references that specific entry; ergo renaming all accesses at once. This is impossible in sourcecode, where every name is identical and string matching is impossible.
+
After the code has been cleaned up by MCInjector, to a state where it no longer conflicts with itself, it can be passed to the decompiler.
 +
 
 +
The decompiler used by ForgeGradle is a custom fork of [https://github.com/JetBrains/intellij-community/tree/master/plugins/java-decompiler/engine Jetbrains' FernFlower], called [https://github.com/MinecraftForge/ForgeFlower ForgeFlower].
 +
 
 +
It simply searches the jar for files, cleans up the bytecode, and then converts it into a reasonable best-guess interpretation.
    
It:
 
It:
 
* Removes synthetic parameters from constructors
 
* Removes synthetic parameters from constructors
 
** In bytecode, inner classes have the outer class as their first constructor parameter, but Java source code does not.
 
** In bytecode, inner classes have the outer class as their first constructor parameter, but Java source code does not.
−
* Handles adding annotations for parameters that have synthetic data
  −
** In bytecode, these Nonnull (or whatever) annotations are attached to the parameters, not to the function that contains them.
   
* Adds constructors for inner classes
 
* Adds constructors for inner classes
 
** These are removed by Proguard sometimes, as they are not required in the bytecode if the parent has a default constructor.
 
** These are removed by Proguard sometimes, as they are not required in the bytecode if the parent has a default constructor.
−
* Adds synthetic (invisible) constructors for classes without them
+
* Hides bridge methods
−
 
+
* Decompiles generic signatures
−
 
+
* Encodes non-ASCII characters in string and character literals as Unicode escaped characters
−
It also applies fixes for things like EXC;
+
* Hides synthetic class members
−
* Renaming parameters inside constructors, such that subclasses retain the ID of their parent.
+
* Prevents simple lambdas from being inlined
−
* Fixing access for select functions, where it is required for the proper recompilation.
  −
* Applying proper typing to constructor parameters
  −
* Applying proper external (LWJGL) exception data to functions and classes.
  −
 
  −
Note that it does NOT rename to SRG. LVT (Local Variables) are renamed to lvt_&lt;index&gt;_&lt;version&gt;<ref>Index means: the place where this item was found. If it is the 4th entry in the table, it is index 3.</ref>
  −
 
  −
=== ForgeFlower ===
  −
After the code has been cleaned up by MCInjector, to a state where it no longer conflicts with itself, it can be passed to the decompiler.
  −
 
  −
The decompiler used by ForgeGradle is a custom fork of [https://github.com/JetBrains/intellij-community/tree/master/plugins/java-decompiler/engine Jetbrains' FernFlower], called [https://github.com/MinecraftForge/ForgeFlower ForgeFlower].
  −
 
  −
It simply searches the jar for files, converts the bytecode into a reasonable best-guess interpretation.
      
As you can see by the repository, a lot of work has gone into tuning it for Minecraft's needs, but it is still a far way from perfect. This is why the patches are needed.
 
As you can see by the repository, a lot of work has gone into tuning it for Minecraft's needs, but it is still a far way from perfect. This is why the patches are needed.
   −
If you [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.16.4/patches/ look at the patches] for 1.16.4, they are mostly incredibly simple changes. Adding generics, making types more strict.  
+
If you [https://github.com/MinecraftForge/MCPConfig/tree/master/versions/release/1.17.1/patches look at the patches] for 1.17.1, they are mostly incredibly simple changes. Adding generics, making types more strict.  
    
This is all stuff that should be done by the decompiler, and PRs are always welcome at the ForgeFlower repository for changes and fixes that would reduce the amount of MCPConfig patches required to get the game to compile.
 
This is all stuff that should be done by the decompiler, and PRs are always welcome at the ForgeFlower repository for changes and fixes that would reduce the amount of MCPConfig patches required to get the game to compile.
Line 123: Line 113:  
It is a simple program, but it works.
 
It is a simple program, but it works.
   −
=== SpecialSource ===
+
=== Vignette ===
−
SpecialSource is where SRG starts to come into play. It serves the role of our deobfuscator, performing deobfuscation.
+
Vignette is where SRG starts to come into play. It serves the role of our deobfuscator, performing deobfuscation.
    
This process is done with the help of a '''deobfusation map''', a file generated by the original obfuscator (in this case, ProGuard) that contains a map of the obfuscated names to original, non-obfuscated names. This is commonly used on debofuscating stack traces outputted by an obfuscated program, for debugging purposes.<ref name="retrace"/>
 
This process is done with the help of a '''deobfusation map''', a file generated by the original obfuscator (in this case, ProGuard) that contains a map of the obfuscated names to original, non-obfuscated names. This is commonly used on debofuscating stack traces outputted by an obfuscated program, for debugging purposes.<ref name="retrace"/>
   −
We have three sets of deobfuscation maps available to us; the obf->SRG mappings distributed with the MCPConfig system, the Yarn intermediary system, or the offical mappings.<ref name="mojmappings"/>.
+
We have three sets of deobfuscation maps available to us; the obf->SRG mappings distributed with the MCPConfig system, the Yarn intermediary system, or the official mappings.<ref name="mojmappings"/>.
 +
 
 +
To rectify this problem, Forge has it's own process to create deobfuscation mappings for the game, using the official mappings. This process is split into two separate parts: the '''SRG renaming''', and the '''official mapping'''. During the SetupMCP task, only the SRG renaming is performed.
 +
 
 +
Vignette itself operates on the compiled jar and takes in a .tsrg file, like that [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.17.1/joined.tsrg contained in the MCPConfig zip]. It does this because it's easier to rename LVT entries (from the snowman) to readable names while you can search for every other code path that references that specific entry; ergo renaming all accesses at once. This is impossible in source code, where every name is identical and string matching is impossible.
   −
To rectify this problem, Forge has it's own process to create deobfuscation mappings for the game, using community-sourced human-readable names. This process is split into two separate parts: the '''SRG renaming''', and the '''MCP mapping'''. During the SetupMCP task, only the SRG renaming is performed.
+
It also:
 +
* Handles adding annotations for parameters that have synthetic data
 +
** In bytecode, these Nonnull (or whatever) annotations are attached to the parameters, not to the function that contains them.
 +
* Adds synthetic (invisible) constructors for classes without them
   −
SpecialSource itself operates on the source jar, as can be gathered by the name, and takes in a .tsrg file, like that [https://github.com/MinecraftForge/MCPConfig/blob/master/versions/release/1.16.4/joined.tsrg contained in the MCPConfig zip].
+
LVT (Local Variables) are initially renamed to lvt_&lt;index&gt;_&lt;version&gt;<ref>Index means: the place where this item was found. If it is the 4th entry in the table, it is index 3.</ref>
   −
It first renames classes, straight into MCP names.
+
First, the class names are renamed from their obfuscated target to the specified mapping output.
−
Then, iterating the members of the class, it renames fields, methods, parameters and inner classes.
+
Then, iterating the members of the class, it renames fields, methods, parameters, and inner classes.
    
A recap from earlier:
 
A recap from earlier:
 
* For classes -> <code>c_###_</code> (but it is immediately changed without the c_ being written to disk)
 
* For classes -> <code>c_###_</code> (but it is immediately changed without the c_ being written to disk)
−
* For functions/methods -> <code>func_&lt;ID&gt;_&lt;obf-name&gt;</code>
+
* For functions/methods -> <code>m_&lt;ID&gt;_</code>
−
* For fields -> <code>field_&lt;ID&gt;_&lt;obf-name&gt;</code>
+
* For fields -> <code>f_&lt;ID&gt;_</code>
−
* For function/method parameters -> <code>p_###_#_</code> for normal methods, <code>p_i###_#</code> for constructors; the second number is the index<ref>The index is the position of the argument. 0 on the left, 1 after that, 2 after that. Note that double and long arguments increase their index by two, rather than one.</ref> of the parameter.
+
* For function/method parameters -> <code>p_###_</code><ref>The index is the position of the argument. 0 on the left, 1 after that, 2 after that. Note that double and long arguments increase their index by two, rather than one of the parameter</ref>.
   −
For example, <code>func_71410_x</code> refers to a function with SRG ID 71410 and original obfuscated name of <code>x</code>.<ref>For version 1.16.2, <code>func_71410_x</code> refers to <code>Minecraft.getInstance()</code>, with real obfuscated name of <code>B</code>, but when the getInstance() function was first discovered in code, it was called x.</ref>
+
For example, <code>m_91087_</code> refers to a function with SRG ID 91087.<ref>For version 1.17.1, <code>m_91087_</code> refers to <code>Minecraft#getInstance</code> with an obfuscated name of <code>dvp$C</code>.</ref>
   −
At this point, combined with the MCInjector step from earlier, we have a completely SRGed-up source jar.
+
At this point, we have a completely remapped jar.
    
=== Patches ===
 
=== Patches ===
 
Once we have the source code ready to go, the final step in the setup is to apply patches.
 
Once we have the source code ready to go, the final step in the setup is to apply patches.
−
These are done trivially, using diffs and [https://github.com/CadixDev/gitpatcher gitpatcher].
+
These are done trivially, using diffs and [https://github.com/MinecraftForge/BinaryPatcher BinaryPatcher].
−
 
  −
=== Clean-up ===
  −
Because of the way Proguard (or whatever obfuscator) and ForgeFlower mangle the source code, we need to take some steps to clean it up before we can proceed.
  −
 
  −
Assorted cleanup fixes are performed by the [https://github.com/MinecraftForge/MCPCleanup/ MCPCleanup] utility. These include:
  −
* removing trailing whitespace at the end of lines
  −
* removing extra newlines at the start and end of files
  −
* removing extra newlines between every line of code (every set of concurrent newlines is replaced with a single)
  −
* removing comments (// hello, /* hello */)
  −
** the purpose of this step is unclear - it seems to be a preventative measure to ensure that Java changes do not interfere with the patch alignment in the future. Comments from the decompiler are still sometimes present in the source code.
  −
* removing imports from the package a class is in
  −
* removing comments that include the phrase <code>GL_[^*]+</code>
  −
* replacing [[Toolchain:Magic Constants|magic constants]] with their code substitutions
  −
* replacing <code>Character.valueOf(&lt;character&gt;)</code> with <code>&lt;character&gt;</code>
  −
* replacing OpenGL integer constants with their code representation
  −
* converting unicode character constants back into integer representation
  −
* formatting the code with JAStyle
  −
 
  −
It also adjusts abstract functions in some way - after running the program on a jar, the parameters of a default abstract function get renamed, but it is unclear exactly what part of the source code does this.
      
== The Forge Side ==
 
== The Forge Side ==
Line 176: Line 154:  
The next step is to run the <code>gradlew setup</code> task, which does what it implies: Applying the Forge system to the processed vanilla code.
 
The next step is to run the <code>gradlew setup</code> task, which does what it implies: Applying the Forge system to the processed vanilla code.
   −
First, it applies ATs. After that, patches. Finally, MCP/Crowdsourced mappings are applied.
+
First, it applies ATs. After that, patches. Finally, the official mappings are applied.
    
All in all, compared to the MCPConfig setup, this is a string of extremely basic tasks - mostly just one-line commands.
 
All in all, compared to the MCPConfig setup, this is a string of extremely basic tasks - mostly just one-line commands.
Line 184: Line 162:  
[[Access Transformers]] are a way of changing the visibility and finality of classes and class members. A full explanation of how it works, what the specification is, and what exactly they're used for, can be found at that page.
 
[[Access Transformers]] are a way of changing the visibility and finality of classes and class members. A full explanation of how it works, what the specification is, and what exactly they're used for, can be found at that page.
   −
They are applied by passing the AT Config (nowadays called accesstransformer.cfg) into SpecialSource:
+
They are applied by passing the AT Config (nowadays called accesstransformer.cfg) into AccessTransformers:
−
* <code>SpecialSource.jar --in-jar {input} --out-jar {output} --access-transformer {at.cfg}</code>
+
* <code>AccessTransformers.jar --inJar {input} --outJar {output} --logFile accesstransform.log --atFile {at.cfg}</code>
   −
[https://github.com/MinecraftForge/MinecraftForge/blob/c3e84646db70f518dd0b37a8fcfc42cb814d7ba8/src/main/resources/META-INF/accesstransformer.cfg The current AT cfg can be found here.]
+
[https://github.com/MinecraftForge/MinecraftForge/blob/1.17.x/src/main/resources/META-INF/accesstransformer.cfg The current AT cfg can be found here.]
    
=== Applying Patches ===
 
=== Applying Patches ===
Line 193: Line 171:  
The patches used for Forge itself are different from those used by MCPConfig, which means there are two separate patching stages performed.
 
The patches used for Forge itself are different from those used by MCPConfig, which means there are two separate patching stages performed.
   −
As opposed to the minimal MCPConfig patching, with the goal to make the code recompileable, the Forge patching is done to apply the API and modloader to the code.
+
As opposed to the minimal MCPConfig patching, with the goal to make the code recompilable, the Forge patching is done to apply the API and modloader to the code.
   −
It does this in a very similar way, with the [https://github.com/CadixDev/gitpatcher gitpatcher] utility.
+
It does this in a very similar way, with the [https://github.com/MinecraftForge/BinaryPatcher BinaryPatcher] utility.
       
=== Applying Mappings ===
 
=== Applying Mappings ===
−
This step isn't strictly necessary, and it can be ommitted. However, working with exclusively SRG names is confusing for most people, so we have an extra step to apply human names to the SRG.
+
This step isn't strictly necessary, and it can be omitted. However, working with exclusively SRG names is confusing for most people, so we have an extra step to apply human names to the SRG.
   −
These renames can come from any source; as mentioned earlier, the MCP/Crowdsourced naming, the Yarn naming, or the Mojang Obf-map naming. ForgeGradle does not care, as long as there is a valid SRG->names map.
+
These renames can come from any source; as mentioned earlier, the Yarn naming or the Mojang Obf-map naming. ForgeGradle does not care, as long as there is a valid SRG->names map.
    
How ForgeGradle retrieves these mappings is covered in the [[ForgeGradle/mappings|appropriate article]].
 
How ForgeGradle retrieves these mappings is covered in the [[ForgeGradle/mappings|appropriate article]].
   −
The process of renaming itself is a simple regex substitution, performed by [https://github.com/MinecraftForge/ForgeGradle/blob/e2ed49546abced95650635f81be071441ec60995/src/common/java/net/minecraftforge/gradle/common/util/McpNames.java#L104 ForgeGradle itself]. This is made possible by the assured uniqueness of SRG names.
+
The process of renaming itself is a simple regex substitution, performed by [https://github.com/MinecraftForge/ForgeGradle/blob/a0d2d1f488b3285ef7c75367feeebbe1a38aa19b/src/common/java/net/minecraftforge/gradle/common/util/McpNames.java#L105 ForgeGradle itself]. This is made possible by the assured uniqueness of SRG names.
    
=== Post-processing ===
 
=== Post-processing ===
Line 214: Line 192:     
== Some additional Infos ==
 
== Some additional Infos ==
−
# You will never see c_XXX_ for classes, because the class names are picked beforehand
+
# You will never see c_XXX_ for classes, because the class names are picked beforehand using the official mapping classnames
−
#* this is still crowdsourced, but before a new version is ready for Forge, all classes are given an <code>MCP</code> name
  −
#* this <code>MCP</code> name stays constant throughout the game version it was picked for; it can change between versions, but it usually wont for already-named classes (except for misspells, typos, and misnames)
   
# If you look into the JAR, you won't see any packages for the obfuscated classes, but the deobfuscated classes do have the packages, this is because the same process that names the classes, also decides what package they belong to
 
# If you look into the JAR, you won't see any packages for the obfuscated classes, but the deobfuscated classes do have the packages, this is because the same process that names the classes, also decides what package they belong to
−
# parameters have special names
  −
#* there are two types of parameter names: <code>p_XXX_X_</code> and <code>p_iXXX_X_</code>
  −
#* the one with the i means that it's a parameter for a constructor
  −
#* the first set of numbers are the SRG ID of their parent method, and the second number denotes the index of the parameter
  −
#* the index of the parameter is a bit more involved, but this will not be explained here
  −
# If you look into the source, you'll see that parameters for lambdas don't have mapped names
  −
#* This is because of a complication in how the lambdas are compiled/decompiled; it's a more advanced topic which involves how the compiler compiles lambdas which we will not explain here.
      
== See also ==
 
== See also ==
Retrieved from ‘https://forge.gemwire.uk/wiki/Special:MobileDiff/2905’