From 3172fbc6c23761ed9a0ec9fde7c05dbccb10fe85 Mon Sep 17 00:00:00 2001 From: Mumfrey Date: Mon, 11 Sep 2017 16:57:20 +0100 Subject: [PATCH] 0.7.4 - Dynamic annotation for decorating members with runtime targets Updates minecraft-dev/MinecraftDev#298 --- gradle.properties | 2 +- .../asm/launch/MixinBootstrap.java | 2 +- .../org/spongepowered/asm/mixin/Dynamic.java | 89 +++++++++++++++++++ .../mixin/injection/struct/InjectionInfo.java | 32 +++++-- .../MixinPreProcessorStandard.java | 41 ++++++++- 5 files changed, 155 insertions(+), 11 deletions(-) create mode 100644 src/main/java/org/spongepowered/asm/mixin/Dynamic.java diff --git a/gradle.properties b/gradle.properties index e24d3800..75580b6d 100644 --- a/gradle.properties +++ b/gradle.properties @@ -4,5 +4,5 @@ packaging=jar description=Mixin url=https://www.spongepowered.org organization=SpongePowered -buildVersion=0.7.3 +buildVersion=0.7.4 buildType=SNAPSHOT diff --git a/src/main/java/org/spongepowered/asm/launch/MixinBootstrap.java b/src/main/java/org/spongepowered/asm/launch/MixinBootstrap.java index 6b14d263..8215f3e5 100644 --- a/src/main/java/org/spongepowered/asm/launch/MixinBootstrap.java +++ b/src/main/java/org/spongepowered/asm/launch/MixinBootstrap.java @@ -60,7 +60,7 @@ public abstract class MixinBootstrap { /** * Subsystem version */ - public static final String VERSION = "0.7.3"; + public static final String VERSION = "0.7.4"; /** * Log all the things diff --git a/src/main/java/org/spongepowered/asm/mixin/Dynamic.java b/src/main/java/org/spongepowered/asm/mixin/Dynamic.java new file mode 100644 index 00000000..fc97cb69 --- /dev/null +++ b/src/main/java/org/spongepowered/asm/mixin/Dynamic.java @@ -0,0 +1,89 @@ +/* + * This file is part of Mixin, licensed under the MIT License (MIT). + * + * Copyright (c) SpongePowered + * Copyright (c) contributors + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package org.spongepowered.asm.mixin; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Decorator annotation for mixin elements whose targets are not available in + * the original class and are either fabricated or transformed at runtime. This + * annotation is purely for decoration purposes and has no semantic implications + * of any kind. + * + *

Its use on mixin elements is encouraged because it yields the following + * benefits:

+ * + *
    + *
  1. Aids mixin maintainers by providing context for seemingly-pointless + * injections. An injector or overwrite whose target does not appear to + * exist can be given context by decorating it with this annotation.
  2. + *
  3. Allowing mixin tooling such as IDE plugins to gain awareness that a + * particular target can be allowed to fail validation from static analysis. + * In the case where tooling might flag the target as invalid, this + * annotation can provide context to suppress or enhance generated warnings. + *
  4. + *
  5. Provide additional context when an injection fails. For example if an + * injector decorated with @Dynamic fails to locate a valid + * target, mixin will include the contents of the @Dynamic + * annotation with the error message, providing additional debugging + * information to end users. This might, for example, be used to identify + * when an upstream transformation is disabled or changed.
  6. + *
+ * + *

Because of the possible inclusion in error messages, it is suggested that + * the description provided via @Dynamic provides as much + * information in as terse a manner possible. Good examples of text descriptions + * to include might be: + * + *

+ * + *

In other words, the contents of the @Dynamic should try to + * provide as much useful context for the decorated method without being overly + * verbose. In the case of the last example, where the contents of the + * annotation are the fully-qualified coordinates of an upstream mixin, it may + * be possible for tooling to enable navigation or other enhanced functionality, + * so deciding for a project

+ */ +@Target({ ElementType.METHOD, ElementType.FIELD }) +@Retention(RetentionPolicy.CLASS) +public @interface Dynamic { + + /** + * Description of this @Dynamic member. See the notes above. + * + * @return description of the member + */ + public String value(); + +} diff --git a/src/main/java/org/spongepowered/asm/mixin/injection/struct/InjectionInfo.java b/src/main/java/org/spongepowered/asm/mixin/injection/struct/InjectionInfo.java index 0fa2a37b..80643437 100644 --- a/src/main/java/org/spongepowered/asm/mixin/injection/struct/InjectionInfo.java +++ b/src/main/java/org/spongepowered/asm/mixin/injection/struct/InjectionInfo.java @@ -38,6 +38,7 @@ import java.util.Set; import org.spongepowered.asm.lib.Opcodes; import org.spongepowered.asm.lib.tree.AnnotationNode; import org.spongepowered.asm.lib.tree.MethodNode; +import org.spongepowered.asm.mixin.Dynamic; import org.spongepowered.asm.mixin.Final; import org.spongepowered.asm.mixin.MixinEnvironment.Option; import org.spongepowered.asm.mixin.extensibility.IMixinInfo; @@ -64,6 +65,8 @@ import org.spongepowered.asm.mixin.transformer.throwables.InvalidMixinException; import org.spongepowered.asm.util.Annotations; import org.spongepowered.asm.util.Bytecode; +import com.google.common.base.Strings; + /** * Contructs information about an injection from an {@link Inject} annotation * and allows the injection to be processed. @@ -271,19 +274,23 @@ public abstract class InjectionInfo extends SpecialMethodInfo implements ISliceC this.classNode.methods.add(method); } + String description = this.getDescription(); String refMapStatus = this.mixin.getReferenceMapper().getStatus(); + String dynamicInfo = this.getDynamicInfo(); if ((this.mixin.getEnvironment().getOption(Option.DEBUG_INJECTORS) && this.injectedCallbackCount < this.expectedCallbackCount)) { throw new InvalidInjectionException(this, - String.format("Injection validation failed: %s %s%s in %s expected %d invocation(s) but %d succeeded. %s", this.getDescription(), - this.method.name, this.method.desc, this.mixin, this.expectedCallbackCount, this.injectedCallbackCount, refMapStatus)); + String.format("Injection validation failed: %s %s%s in %s expected %d invocation(s) but %d succeeded. %s%s", description, + this.method.name, this.method.desc, this.mixin, this.expectedCallbackCount, this.injectedCallbackCount, refMapStatus, + dynamicInfo)); } else if (this.injectedCallbackCount < this.requiredCallbackCount) { throw new InjectionError( - String.format("Critical injection failure: %s %s%s in %s failed injection check, (%d/%d) succeeded. %s", this.getDescription(), - this.method.name, this.method.desc, this.mixin, this.injectedCallbackCount, this.requiredCallbackCount, refMapStatus)); + String.format("Critical injection failure: %s %s%s in %s failed injection check, (%d/%d) succeeded. %s%s", description, + this.method.name, this.method.desc, this.mixin, this.injectedCallbackCount, this.requiredCallbackCount, refMapStatus, + dynamicInfo)); } else if (this.injectedCallbackCount > this.maxCallbackCount) { throw new InjectionError( - String.format("Critical injection failure: %s %s%s in %s failed injection check, %d succeeded of %d allowed", - this.getDescription(), this.method.name, this.method.desc, this.mixin, this.injectedCallbackCount, this.maxCallbackCount)); + String.format("Critical injection failure: %s %s%s in %s failed injection check, %d succeeded of %d allowed.%s", + description, this.method.name, this.method.desc, this.mixin, this.injectedCallbackCount, this.maxCallbackCount, dynamicInfo)); } } @@ -408,7 +415,7 @@ public abstract class InjectionInfo extends SpecialMethodInfo implements ISliceC if (this.targets.size() == 0) { throw new InvalidInjectionException(this, type + " annotation on " + this.method.name + " could not find any targets matching " - + InjectionInfo.namesOf(searchFor) + ". " + this.mixin.getReferenceMapper().getStatus()); + + InjectionInfo.namesOf(searchFor) + ". " + this.mixin.getReferenceMapper().getStatus() + this.getDynamicInfo()); } } @@ -432,6 +439,17 @@ public abstract class InjectionInfo extends SpecialMethodInfo implements ISliceC } } + /** + * Get info from a decorating {@link Dynamic} annotation. If the annotation + * is present, a descriptive string suitable for inclusion in an error + * message is returned. If the annotation is not present then an empty + * string is returned. + */ + protected String getDynamicInfo() { + String dynamic = Annotations.getValue(Annotations.getInvisible(this.method, Dynamic.class)); + return Strings.isNullOrEmpty(dynamic) ? "" : String.format(" Method is @Dynamic(%s)", dynamic); + } + /** * Parse an injector from the specified method (if an injector annotation is * present). If no injector annotation is present then null is diff --git a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinPreProcessorStandard.java b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinPreProcessorStandard.java index bc97c423..170e8d76 100644 --- a/src/main/java/org/spongepowered/asm/mixin/transformer/MixinPreProcessorStandard.java +++ b/src/main/java/org/spongepowered/asm/mixin/transformer/MixinPreProcessorStandard.java @@ -36,6 +36,7 @@ import org.spongepowered.asm.lib.tree.FieldInsnNode; import org.spongepowered.asm.lib.tree.FieldNode; import org.spongepowered.asm.lib.tree.MethodInsnNode; import org.spongepowered.asm.lib.tree.MethodNode; +import org.spongepowered.asm.mixin.Dynamic; import org.spongepowered.asm.mixin.MixinEnvironment; import org.spongepowered.asm.mixin.MixinEnvironment.CompatibilityLevel; import org.spongepowered.asm.mixin.MixinEnvironment.Option; @@ -60,6 +61,8 @@ import org.spongepowered.asm.util.perf.Profiler; import org.spongepowered.asm.util.perf.Profiler.Section; import org.spongepowered.asm.util.throwables.SyntheticBridgeException; +import com.google.common.base.Strings; + /** *

Mixin bytecode pre-processor. This class is responsible for bytecode pre- * processing tasks required to be performed on mixin bytecode before the mixin @@ -380,7 +383,8 @@ class MixinPreProcessorStandard { target = context.findRemappedMethod(mixinMethod); if (target == null) { throw new InvalidMixinException(this.mixin, type + " method " + mixinMethod.name + " in " + this.mixin - + " was not located in the target class." + context.getReferenceMapper().getStatus()); + + " was not located in the target class. " + context.getReferenceMapper().getStatus() + + MixinPreProcessorStandard.getDynamicInfo(mixinMethod)); } mixinMethod.name = method.renameTo(target.name); } @@ -553,7 +557,9 @@ class MixinPreProcessorStandard { target = context.findRemappedField(mixinField); if (target == null) { // If this field is a shadow field but is NOT found in the target class, that's bad, mmkay - throw new InvalidMixinException(this.mixin, "Shadow field " + mixinField.name + " was not located in the target class"); + throw new InvalidMixinException(this.mixin, "Shadow field " + mixinField.name + " was not located in the target class" + + context.getReferenceMapper().getStatus() + + MixinPreProcessorStandard.getDynamicInfo(mixinField)); } mixinField.name = field.renameTo(target.name); } @@ -693,5 +699,36 @@ class MixinPreProcessorStandard { fieldNode.name = field.getName(); } } + + /** + * Get info from a decorating {@link Dynamic} annotation. If the annotation + * is present, a descriptive string suitable for inclusion in an error + * message is returned. If the annotation is not present then an empty + * string is returned. + * + * @param method method to inspect + * @return dynamic text in parentheses or empty string + */ + protected static String getDynamicInfo(MethodNode method) { + return MixinPreProcessorStandard.getDynamicInfo("Method", Annotations.getInvisible(method, Dynamic.class)); + } + + /** + * Get info from a decorating {@link Dynamic} annotation. If the annotation + * is present, a descriptive string suitable for inclusion in an error + * message is returned. If the annotation is not present then an empty + * string is returned. + * + * @param method method to inspect + * @return dynamic text in parentheses or empty string + */ + protected static String getDynamicInfo(FieldNode method) { + return MixinPreProcessorStandard.getDynamicInfo("Field", Annotations.getInvisible(method, Dynamic.class)); + } + + private static String getDynamicInfo(String targetType, AnnotationNode annotation) { + String dynamic = Annotations.getValue(annotation); + return Strings.isNullOrEmpty(dynamic) ? "" : String.format(" %s is @Dynamic(%s)", targetType, dynamic); + } }