diff --git a/README.MD b/README.MD index e35254d8..aaf554e8 100644 --- a/README.MD +++ b/README.MD @@ -3,32 +3,51 @@ ![Mixin Logo](docs/javadoc/resources/logo.png?raw=true) -**Mixin** is a trait/mixin framework for Java using [ASM](http://asm.ow2.org/) -and hooking into the runtime class-loading process via Mojang's -[LegacyLauncher](https://github.com/Mojang/LegacyLauncher) system. +**Mixin** is a trait/mixin framework for Java using [ASM](https://asm.ow2.io/) +and hooking into the runtime classloading process via a set of pluggable +built-in or user-provided services. Built-in services currently support Mojang's +[LegacyLauncher](https://github.com/Mojang/LegacyLauncher) system, though this +is deprecated in favour of [ModLauncher](https://github.com/cpw/modlauncher) by +cpw, which has greater extensibility and has support for Java 8 and later. ### Documentation -The main documentation for **Mixin** can be found in the [Wiki](../../wiki). +The main documentation for **Mixin** can be found in the +[Wiki](https://github.com/SpongePowered/Mixin/wiki). Additional documentation for individual features and annotations can be found in the extensive [Javadoc](http://jenkins.liteloader.com/job/Mixin/javadoc/). For -additional help use the channel [`#mixin` on the -Sponge Discord Server](https://discord.gg/tBcwxz2). +additional help use the channel [`#mixin` on the Sponge Discord Server](https://discord.gg/tBcwxz2). -### Building Mixin -**Mixin** uses the [Gradle](http://gradle.org/) build automation system. To -perform a build, use gradle version 4.9 and execute +### Binaries - gradle +Mixin binaries are available via [Jenkins](https://jenkins.liteloader.com/view/Other/job/Mixin/) +and are published to the following maven repositories: -from within the project root directory. *(If you do not have Gradle installed on -your system you can instead run the supplied Gradle wrapper `gradlew`)* +* https://repo.spongepowered.org/repository/maven-public/ - SNAPHOTs and RELEASE + builds +* https://files.minecraftforge.net/maven/ - RELEASE builds only -### Integration with Eclipse IDE +### Tooling -The **Mixin** project can be integrated easily with Eclipse using Buildship. -Simply choose `Import` -> `Gradle Project` and follow the prompts. +For handling obfuscation tasks, Mixin provides an [Annotation Processor](https://github.com/SpongePowered/Mixin/wiki/Using-the-Mixin-Annotation-Processor) +which works at compile time to generate obfuscation mappings for your toolchain +to apply. If using Gradle 5 or later, annotation processors are no longer +automatically loaded from `compile` configurations and must be specified +explicitly via `annotationProcessor` configurations. For this purpose, Mixin +provides "fat jar" artefacts containing all required dependencies via the +`:processor` classifier. For example if your build uses the dependency +`org.spongepowered:mixin:1.2.3` then your annotationProcessor configuration +should specify dependency `org.spongepowered:mixin:1.2.3:processor`. + +If you are using Mixin in a [Minecraft Forge](https://minecraftforge.net/) +project then the [MixinGradle](https://github.com/SpongePowered/MixinGradle) +plugin can be used to simplify the configuration of the Mixin Annotation +Processor. It provides a simple syntax for configuring the Mixin AP for your +project, see the [MixinGradle README](https://github.com/SpongePowered/MixinGradle/blob/master/README.md) +for how to configure MixinGradle. + +### Integration with Eclipse When developing using **Mixin**, you can use the **Mixin Annotation Processor** within Eclipse to provide context-sensitive errors and warnings to help you more @@ -45,11 +64,12 @@ easily troubleshoot your mixins. To do so: 7. Check the `Enable annotation processing` checkbox 8. Click the `New...` button next to the `Processor options` box * Set `Key` to **reobfSrgFile** - * Set `Value` to the fully-qualified path to the `mcp-srg.srg` file (for Sponge - this can be found in `Sponge/build/srgs/mcp-srg.srg`) + * Set `Value` to the fully-qualified path to the `mcp-srg.srg` file (the + location of the mapping file varies by platform, if you are unsure where to + find it please follow the discord link below). 9. Click `OK` to apply the changes -### Integration with IntelliJ IDEA IDE +### Integration with IntelliJ IDEA Enhanced functionality for working with **Mixin** in IntelliJ IDEA is available via the [Minecraft Development for IntelliJ IDEA](https://plugins.jetbrains.com/idea/plugin/8327) @@ -57,6 +77,11 @@ plugin developed by [DemonWav](https://github.com/demonwav). ### Version History +[Specifying the `minVersion` property in your configurations](https://github.com/SpongePowered/Mixin/wiki/PSA-Forward-Compatibility-Features-in-Mixin) +is extrememly important. The following version history can be used to determine +when features were introduced (and sometimes when major bugs are squashed) in +order to help you determine which `minVersion` you should specify. + @@ -67,13 +92,28 @@ plugin developed by [DemonWav](https://github.com/demonwav). - + + + + + + diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/InjectionPoint.java b/src/main/java/org/spongepowered/asm/mixin/injection/InjectionPoint.java index b762c06f..e5fff052 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/InjectionPoint.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/InjectionPoint.java @@ -78,15 +78,63 @@ import com.google.common.collect.ImmutableList.Builder; * using intersection (and) or union (or) relationships to allow multiple * strategies to be easily combined.

* - *

You are free to create your own injection point subclasses, but take note - * that it is allowed for a single InjectionPoint instance to be used for - * multiple injections and thus implementing classes MUST NOT cache the insn - * list, event, or nodes instance passed to the {@link #find find} method, as - * each call to {@link #find find} must be considered a separate functional - * contract and the InjectionPoint's lifespan is not linked to the discovery - * lifespan, therefore it is important that the InjectionPoint implementation is - * fully stateless and that calls to {@link #find find} are idempotent. - *

+ *

Built-in Injection Points

+ * + *

The following built-in Injection Points are available:

+ * + * + * + *

Additionally, the two special injection points are available which are + * only supported for use with {@link ModifyVariable @ModifyVariable}:

+ * + * + * + *

See the javadoc for each type for more details on the scheme used by each + * injection point.

+ * + *

Custom Injection Points

+ * + *

You are free to create your own injection point subclasses. Once defined, + * they can be used by your mixins in one of two ways:

+ * + *
    + *
  1. Specify the fully-qualified name of the injection point class in the + * {@link At#value @At.value}.
  2. + *
  3. Decorate your injection point class with {@link AtCode @AtCode} + * annotation which specifies a namespace and shortcode for the injection + * point, and register the class in your mixin config. You can then specify + * the namespaced code (eg. MYMOD:CUSTOMPOINT) in {@link At#value + * @At.value}.
  4. + *
+ * + *

When writing custom injection points, note that the general contract of + * injection points is that they be entirely - or at least behaviourally - + * stateless. It is allowed for a single InjectionPoint instance to be + * used by the mixin processor for multiple injections and thus implementing + * classes MUST NOT cache the insn list, event, or nodes instance + * passed to the {@link #find find} method, as each call to {@link #find find} + * must be considered a separate contract and the InjectionPoint's lifespan is + * not linked to the discovery lifespan. It is therefore important that the + * InjectionPoint implementation is fully stateless and that calls to + * {@link #find find} are idempotent.

*/ public abstract class InjectionPoint { diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/ModifyVariable.java b/src/main/java/org/spongepowered/asm/mixin/injection/ModifyVariable.java index 5dd71cfe..a525f02a 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/ModifyVariable.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/ModifyVariable.java @@ -30,6 +30,8 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; import org.spongepowered.asm.mixin.MixinEnvironment.Option; +import org.spongepowered.asm.mixin.injection.modify.AfterStoreLocal; +import org.spongepowered.asm.mixin.injection.modify.BeforeLoadLocal; import org.spongepowered.asm.mixin.injection.selectors.ITargetSelector; import org.spongepowered.asm.mixin.injection.throwables.InjectionError; import org.spongepowered.asm.mixin.injection.throwables.InvalidInjectionException; @@ -57,7 +59,9 @@ import org.spongepowered.asm.util.ConstraintParser.Constraint; * *

The injector has two operating modes, explicit and implicit * , and can operate either on the entire LVT or on the {@link #argsOnly - * ethod arguments only}.

+ * method arguments only}.

+ * + *

Explicit mode

* *

In explicit mode, the variable to capture can be specified by * specifying values for the discriminator arguments {@link #ordinal}, @@ -65,12 +69,32 @@ import org.spongepowered.asm.util.ConstraintParser.Constraint; * order to attempt to locate the variable to capture. If no local variable * matches any discriminators, the capture fails.

* + *

Implicit mode

+ * *

If no values for the capture discrimiators are specified, the injector * operates in implicit mode. If exactly one variable of the capture * type exists in the target LVT, then capture will succeed. However, if more * than one variable of the required type is encountered in the LVT then an * {@link InvalidInjectionException} is thrown.

* + *

Context-sensitive injection points

+ * + *

Normally the {@link InjectionPoint injection points} specified by {@link + * #at} are independent of the injector being used. With ModifyVariable + * there are two special injection points which consume the discriminator from + * the annotation:

+ * + * + * + *

See the javadoc for each injection point for details.

+ * + *

Notes

+ * *

Like other injectors, the callback signature can optionally include the * target method arguments by simply appending them to the handler method * signature.

@@ -108,7 +132,8 @@ public @interface ModifyVariable { * An {@link At} annotation which describes the {@link InjectionPoint} in * the target method. * - * @return {@link At} which identifies the target method invocation + * @return {@link At} which identifies the location to inject inside the + * target method. */ public At at();
0.8.10.8.3February 2021 +
    +
  • Added dynamic target selector support and @Desc + target selector
  • +
  • Added pattern target selector
  • +
  • Added more expressive quantifier support to explicit target + selectors
  • +
  • Facelift and overall improvements to javadoc
  • +
+
0.8.1 (0.8.2) September 2020
  • Hotfix for supporting ModLauncher 7.0
  • Fix critical issue with resolving obfuscated members in inherited interfaces
  • +
  • Updated to ASM 7.2