| # Guide to Keep Annotations |
| |
| ## Disclaimer |
| |
| 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](https://issuetracker.google.com/issues/new?component=326788) in the |
| [R8 component](https://issuetracker.google.com/issues?q=status:open%20componentid:326788). |
| |
| |
| [[[TOC]]] |
| |
| |
| ## [Introduction](introduction) |
| |
| 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. |
| |
| |
| ## [Build configuration](build-configuration) |
| |
| 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 ... |
| ``` |
| |
| |
| ## [Annotating code using reflection](using-reflection) |
| |
| 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. |
| |
| |
| ### [Invoking methods](using-reflection-methods) |
| |
| [[[INCLUDE DOC:UsesReflectionOnVirtualMethod]]] |
| |
| [[[INCLUDE CODE:UsesReflectionOnVirtualMethod]]] |
| |
| |
| ### [Accessing fields](using-reflection-fields) |
| |
| [[[INCLUDE DOC:UsesReflectionFieldPrinter]]] |
| |
| [[[INCLUDE CODE:UsesReflectionFieldPrinter]]] |
| |
| ### [Accessing annotations](using-reflection-annotations) |
| |
| [[[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)`. |
| |
| |
| |
| ## [Annotating code used by reflection (or via JNI)](used-by-reflection) |
| |
| 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]]] |
| |
| |
| ## [Annotating APIs](apis) |
| |
| 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]]] |
| |
| |
| ## [Constraints](constraints) |
| |
| 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. |
| |
| ### [Defaults](constraints-defaults) |
| |
| 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: |
| |
| - to be instantiated, for class items; |
| - to be invoked, for method items; and |
| - to be get and/or set, for field items. |
| |
| [[[INCLUDE DOC:UsesReflectionFieldPrinterWithConstraints]]] |
| |
| [[[INCLUDE CODE:UsesReflectionFieldPrinterWithConstraints]]] |
| |
| |
| ### [Generic signatures](constraints-signatures) |
| |
| 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]]] |
| |
| |
| ## [Migrating rules to annotations](migrating-rules) |
| |
| 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]]] |
| |
| |
| ## [My use case is not covered!](other-uses) |
| |
| 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](https://issuetracker.google.com/issues/new?component=326788). |
| Describe your use case and we will look at how best to support it. |
| |
| |
| ## [Troubleshooting](troubleshooting) |
| |
| 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. |