0.7.4 - Dynamic annotation for decorating members with runtime targets

Updates minecraft-dev/MinecraftDev#298
This commit is contained in:
Mumfrey committed 2017-09-11 16:57:20 +01:00
1 parent 3961a7cbf8
commit 3172fbc6c2
5 files changed
+155 -11

No files matched your search

@@ -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
@@ -0,0 +1,89 @@
/*
* This file is part of Mixin, licensed under the MIT License (MIT).
*
* Copyright (c) SpongePowered <https://www.spongepowered.org>
* 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.
*
* <p>Its use on mixin elements is encouraged because it yields the following
* benefits:</p>
*
* <ol>
* <li>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.</li>
* <li>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.
* </li>
* <li>Provide additional context when an injection fails. For example if an
* injector decorated with <tt>&#064;Dynamic</tt> fails to locate a valid
* target, mixin will include the contents of the <tt>&#064;Dynamic</tt>
* 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.</li>
* </ol>
*
* <p>Because of the possible inclusion in error messages, it is suggested that
* the description provided via <tt>&#064;Dynamic</tt> provides as much
* information in as terse a manner possible. Good examples of text descriptions
* to include might be:
*
* <ul>
* <li><tt>"Method Foo.bar is added at runtime by mod X"</tt></li>
* <li><tt>"All calls to Foo.bar are replaced at runtime by mod Y with a calls
* to Baz.flop"</tt></li>
* <li><tt>"Added by SomeOtherUpstreamMixin"</tt></li>
* <li><tt>"com.foo.bar.SomeOtherUpstreamMixin"</tt></li>
* </ul>
*
* <p>In other words, the contents of the <tt>&#064;Dynamic</tt> 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 </p>
*/
@Target({ ElementType.METHOD, ElementType.FIELD })
@Retention(RetentionPolicy.CLASS)
public @interface Dynamic {
/**
* Description of this <tt>&#064;Dynamic</tt> member. See the notes above.
*
* @return description of the member
*/
public String value();
}
@@ -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.<String>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 <tt>null</tt> is
@@ -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;
/**
* <p>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.<String>getValue(annotation);
return Strings.isNullOrEmpty(dynamic) ? "" : String.format(" %s is @Dynamic(%s)", targetType, dynamic);
}
}