The annotation library described here is in development and considered to be in its prototype phase. As such it is not yet feature complete, but we are actively working on supporting all of the use cases we know of. Once the design exits the prototype phase, it is intended to move to an R8 independent library as part of androidx. All feedback: criticism, comments and suggestions are very welcome!
File new feature requests and bugs in the R8 component.
[[[TOC]]]
When using a Java/Kotlin shrinker such as R8 or Proguard, developers must inform the shrinker about parts of the program that are used either externally from the program itself or internally via reflection and therefore must be kept.
Traditionally these aspects would be kept by writing keep rules in a configuration file and passing that to the shrinker.
The keep annotations described in this document represent an alternative method using Java annotations. The motivation for using these annotations is foremost to place the description of what to keep closer to the program point using reflective behavior. Doing so more directly connects the reflective code with the keep specification and makes it easier to maintain as the code develops. Often the keep annotations are only in effect if the annotated method is used, allowing more precise shrinking. In addition, the annotations are defined independent from keep rules and have a hopefully more clear and direct meaning.
To use the keep annotations your build must include the library of annotations. It is currently built as part of each R8 build and if used with R8, you should use the matching version. You can find all archived builds at:
https://storage.googleapis.com/r8-releases/raw/<version>/keepanno-annotations.jar
Thus you may obtain version 8.2.34 by running:
wget https://storage.googleapis.com/r8-releases/raw/8.2.34/keepanno-annotations.jar
You will then need to set the system property com.android.tools.r8.enableKeepAnnotations to instruct R8 to make use of the annotations when shrinking:
java -Dcom.android.tools.r8.enableKeepAnnotations=1 \ -cp r8.jar com.android.tools.r8.R8 \ # ... the rest of your R8 compilation command here ...
The keep annotation library defines a family of annotations depending on your use case. You should generally prefer @UsesReflection where applicable. Common uses of reflection are to lookup fields and methods on classes. Examples of such use cases are detailed below.
[[[INCLUDE DOC:UsesReflectionOnVirtualMethod]]]
[[[INCLUDE CODE:UsesReflectionOnVirtualMethod]]]
[[[INCLUDE DOC:UsesReflectionFieldPrinter]]]
[[[INCLUDE CODE:UsesReflectionFieldPrinter]]]
[[[INCLUDE DOC:UsesReflectionOnAnnotations]]]
[[[INCLUDE CODE:UsesReflectionOnAnnotations]]]
If the annotations that need to be kept are not runtime visible annotations, then you must specify that by including the RetentionPolicy.CLASS value in the @AnnotationPattern#retention property. An annotation is runtime visible if its definition is explicitly annotated with Retention(RetentionPolicy.RUNTIME).
Sometimes reflecting code cannot be annotated. For example, the reflection can be done in native code or in a library outside your control. In such cases you can annotate the code that is being used by reflection with either @UsedByReflection or @UsedByNative. These two annotations are equivalent. Use the one that best matches why the annotation is needed.
Let's consider some code with reflection outside our control. [[[INCLUDE DOC:UsedByReflectionFieldPrinterOnFields]]]
[[[INCLUDE CODE:UsedByReflectionFieldPrinterOnFields]]]
[[[INCLUDE DOC:UsedByReflectionFieldPrinterOnClass]]]
[[[INCLUDE CODE:UsedByReflectionFieldPrinterOnClass]]]
[[[INCLUDE DOC:UsedByReflectionFieldPrinterConditional]]]
[[[INCLUDE CODE:UsedByReflectionFieldPrinterConditional]]]
If your code is being shrunk before release as a library, then you need to keep the API surface. For that you should use the @KeepForApi annotation.
[[[INCLUDE DOC:ApiClass]]]
[[[INCLUDE CODE:ApiClass]]]
[[[INCLUDE DOC:ApiClassMemberAccess]]]
[[[INCLUDE CODE:ApiClassMemberAccess]]]
[[[INCLUDE DOC:ApiMember]]]
[[[INCLUDE CODE:ApiMember]]]
When an item is kept (e.g., items matched by @KeepTarget or annotated by @UsedByReflection or @KeepForApi) you can additionally specify constraints about what properties of that item must be kept. Typical constraints are to keep the items name or its ability to be reflectively looked up. You may also be interested in keeping the generic signature of an item or annotations associated with it.
By default the constraints are to retain the item's name, its ability to be looked-up as well as its normal usage. Its normal usage is:
[[[INCLUDE DOC:UsesReflectionFieldPrinterWithConstraints]]]
[[[INCLUDE CODE:UsesReflectionFieldPrinterWithConstraints]]]
The generic signature information of an item is not kept by default, and requires adding constraints to the targeted items.
[[[INCLUDE DOC:GenericSignaturePrinter]]]
[[[INCLUDE CODE:GenericSignaturePrinter]]]
There is no automatic migration of keep rules. Keep annotations often invert the direction and rules have no indication of where the reflection is taking place or why. Thus, migrating existing keep rules requires user involvement. Keep rules also have a tendency to be very general, matching a large number of classes and members. Often the rules are much too broad and are keeping more than needed which will have a negative impact on the shrinkers ability to reduce size.
First step in converting a rule is to determine the purpose of the rule. Is it API surface or is it reflection? Note that a very general rule may be covering several use cases and even a mix of both reflection and API usage.
When migrating it is preferable to use @UsesReflection instead of @UsedByReflection. For very general rules it might not be easy or worth it to migrate without completely reevaluating the rule. If one still wants to replace it by annotations, the general @KeepEdge can be used to define a context independent keep annotation.
[[[INCLUDE DOC:KeepMainMethods]]]
[[[INCLUDE CODE:KeepMainMethods]]]
The annotation library is in active development and not all use cases are described here or supported. Reach out to the R8 team by filing a new issue in our tracker. Describe your use case and we will look at how best to support it.
If an annotation is not working as expected it may be helpful to inspect the rules that have been extracted for the annotation. This can be done by inspecting the configuration output of the shrinker. For R8 you can use the command line argument --pg-conf-output <path> to emit the full configuration used by R8.