Configure and troubleshoot R8 Keep Rules

Posted by Ajesh R Pai – Developer Relations Engineer & Ben Weiss – Senior Developer Relations Engineer

In modern Android development, shipping a small, fast, and secure application is a fundamental user expectation. The Android build system’s primary tool for achieving this is the R8 optimizer, the compiler that handles dead code and resource removal for shrinking, code renaming or minification, and app optimization.

Enabling R8 is a critical step in preparing an app for release, but it requires developers to provide guidance in the form of “Keep Rules.”

After reading this article, check out the Performance Spotlight Week video on enabling, debugging and troubleshooting the R8 optimizer on YouTube.

The need to write Keep Rules stems from a core conflict: R8 is a static analysis tool, but Android apps often rely on dynamic execution patterns like reflection or calls in and out of native code using the JNI (Java Native Interface).

R8 builds a graph of used code by analyzing direct calls. When code is accessed in a dynamic way, R8’s static analysis cannot predict that and it will identify that code as unused and remove it, leading to runtime crashes.

A keep rule is an explicit instruction to the R8 compiler, stating: “This specific class, method, or field is an entry point that will be accessed dynamically at runtime. You must keep it, even if you cannot find a direct reference to it.”

See the official guide for more details on Keep Rules.

Custom Keep Rules for an application are written in text file. By convention, this file is named proguard-rules.pro and is located in the root of the app or library module. This file is then specified in your module’s build.gradle.kts file’s release build type.

Use the correct default file

The getDefaultProguardFile method imports a default set of rules provided by the Android SDK. When using the wrong file your app might not be optimized. Make sure to use proguard-android-optimize.txt. This file provides the default Keep Rules for standard Android components and enables R8’s code optimizations. The outdated proguard-android.txt only provides the Keep Rules but does not enable R8’s optimizations.

Since this is a serious performance problem, we are starting to warn developers about using the wrong file, starting in Android Studio Narwhal 3 Feature Drop. And starting with the Android Gradle Plugin Version 9.0 we’re no longer supporting the outdated proguard-android.txt file. So make sure you upgrade to the optimized version.

A keep rule consists of three main parts:

1. An option like -keep or -keepclassmembers

2. Optional modifiers like allowshrinking

3. A class specification that defines the code to match

For the complete syntax and examples, refer to the guidance to add Keep Rules.

It’s important to know about best practices, but also about anti-patterns. These anti-patterns often arise from misunderstandings or troubleshooting shortcuts and can be catastrophic for a production build’s performance.

Global options

These flags are global toggles that should never be used in a release build. They are only for temporary debugging to isolate a problem.

Using -dontotptimize effectively disables R8’s performance optimizations leading to a slower app.

When using -dontobfuscate you disable all renaming and using -dontshrink turns off dead code removal. Both of these global rules increase app size.

Avoid using these global flags in a production environment wherever possible for a more performant app user experience.

Overly broad keep rules

The easiest way to nullify R8’s benefits is to write overly-broad Keep Rules. Keep rules like the one below instruct the R8 optimizer to not shrink, not obfuscate, and not optimize any class in this package or any of its sub-packages. This completely removes R8’s benefits for that entire package. Try to write narrow and specific Keep Rules instead.

The inversion operator (!)

The inversion operator (!) seems like a powerful way to exclude a package from a rule. But it’s not that simple. Take this example:

You might think that this rule means “do not keep classes in com.example.package.” But it actually means “keep every class, method and property in the entire application that is not in com.example.package.” If that came as a surprise to you, best check for any negations in your R8 configuration.

Redundant rules for Android components

Another common mistake is to manually add Keep Rules for your app’s Activities, Services, or BroadcastReceivers. This is unnecessary. The default proguard-android-optimize.txt file already includes the relevant rules for these standard Android components to work out of the box.

Also many libraries bring their own Keep Rules. So you should not have to write your own rules for these. In case there is a problem with Keep Rules from a library you’re using, it is best to reach out to the library author to see what the problem is.

Now that you know what not to do, let’s talk about best practices.

Good Keep Rules should be as narrow and specific as possible. They should preserve only what is necessary, allowing R8 to optimize everything else.

Use common ancestors

Instead of writing separate Keep Rules for multiple different data models, write one rule that targets a common base class or interface. The below rule tells R8 to keep any members of classes that implement this interface and is highly scalable.

Use Annotations to target multiple classes

Create a custom annotation (e.g., @Serialize) and use it to “tag” classes that need their fields preserved. This is another clean, declarative, and highly scalable pattern. You can create Keep Rules for already existing annotations from frameworks you’re using as well.

The Keep Option is the most critical part of the rule. Choosing the wrong one can needlessly disable optimization.