R8 and shrinking

The shrinking step is the only part of the build that can turn working code into a crash without changing a line of source. It is also the only part that turns a 40 MB app into a 25 MB one.

TL;DR#

• R8 does shrinking, optimisation, obfuscation and dexing in a single pass over the program.
• It starts from entry points — manifest components, keep rules, resources — and removes everything that cannot be reached by a path the analysis can see.
• Reflection, JNI and serialisation are invisible edges in the call graph. That is what keep rules are for.
• mapping.txt is the rename dictionary. Without it, a release stack trace is unreadable, and it is the file you must upload with a release.
• minifyEnabled true with no rules is a reasonable start for a small app and a guaranteed problem for one that uses reflection.

Mental model#

Imagine a factory that has been running for ten years and has accumulated every tool anyone ever ordered.

R8 is a ruthless new plant manager. She starts from the shipping door — the entry points that actually get used — and traces backwards. Anything she cannot reach is scrap. Then she reorganises what remains: two machines that always run together become one, a machine that always receives the same setting gets that setting baked in. Finally she relabels everything with short names, so the next person to look at the plant cannot tell what it produces.

The keep rule is a note pinned to a machine: do not touch this one, it is reachable some other way. Reflection is exactly that: a path that only exists at runtime.

Where the analogy breaks#

The plant manager can be wrong, but she cannot know she is wrong. R8's analysis is static; it cannot see a Class.forName("com.example.Handler") call whose string was assembled at runtime. The programmer has to declare those edges explicitly, and the language has no way to check that the declaration is complete. That is why keep rules are a known source of bugs rather than a solved problem.

The big picture#

Step through the phases. The important thing to watch is not the removal; it is that the removal is transitive. LegacySync calls UserRepository, but nothing calls LegacySync, so the edge disappears — and the repo is kept only because MainActivity still reaches it another way.

Deep dive#

What R8 actually runs#

R8 is triggered by isMinifyEnabled = true (and isShrinkResources = true for resources). It runs four passes over the same in-memory program:¹

Because all four share one representation, an inlining decision in pass two can make a class unreachable in pass one. That is why R8's shrinking is more aggressive than ProGuard's was: it is not a linear pipeline.

The rule file, line by line#

R8 reads ProGuard-format rules. The syntax is terse and the mistakes are silent, so it is worth reading one properly.¹

# Keep the entry point of a library the manifest never names.
-keep class com.example.sdk.EntryPoint { *; }
 
# Keep the names of anything annotated, but allow shrinking of unused members.
-keepclassmembers,allowobfuscation class * {
    @com.example.KeepName <fields>;
}
 
# Keep enum values: values() is generated and reflectively enumerated.
-keepclassmembers enum * {
    public static **[] values();
    public static ** valueOf(java.lang.String);
}
 
# Keep a class named only in a JSON config.
-keep class com.example.plugins.** { *; }
 
# Do not warn about a dependency that is only used on one platform.
-dontwarn com.example.optional.**

Read the first line as "keep this class and all of its members, and do not rename it". Read the second as "keep member names for annotated fields, but still allow the class to be shrunk if it is unreachable".

Why reflection breaks, precisely#

Consider a plugin loader:

val clazz = Class.forName("com.example.plugins.WeatherPlugin")
val plugin = clazz.getDeclaredConstructor().newInstance() as Plugin

Nothing in the source references WeatherPlugin as a type. R8 sees a string. It cannot know the string names a class, so WeatherPlugin is unreachable and is removed. On a debug build, R8 is off, so it works. On release, ClassNotFoundException.

There are three fixes, in increasing order of preference:

1. A keep rule for the plugin package.
2. A -keepnames rule if only renaming is the problem and shrinking can stay on.
3. Remove the reflection: use an explicit factory map from key to constructor. This is better code and it removes the invisible edge entirely.

The third option is not always available — plugin systems and serialisation libraries are built on reflection by design — but it should be the default answer for code you own.

The mapping file#

Every obfuscated build writes mapping.txt beside the APK:

com.example.app.data.User -> a.b.c:
    java.lang.String name -> a
    int age -> b

That file is the only way to turn this:¹

java.lang.NullPointerException
    at a.b.c.d(SourceFile:3)

into this:

java.lang.NullPointerException
    at com.example.app.data.User.equals(User.kt:12)

Play Console accepts an upload of mapping.txt per release. Without it, every crash report from that version is noise. It is also why the mapping file must be archived with the build, not regenerated later: a new build produces a different mapping.

Resource shrinking#

isShrinkResources = true is a separate mechanism from code shrinking, and it depends on it. R8 records which resources the code actually references; the resource shrinker removes the rest. A resource referenced only from a removed code path disappears with it.

The common failure: a resource referenced only by name, through getIdentifier() or a string in a database, gets removed. The fix is to keep it explicitly:

<!-- res/raw/keep.xml -->
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:keep="@layout/plugin_*,@drawable/plugin_*" />

Full mode and the future#

R8 has a stricter configuration, usually called full mode, which changes assumptions about default constructors and reflection. It shrinks harder and breaks more. It is enabled by default in newer toolchain versions for some projects, and the migration path is the same as always: run it, find the crash, add the narrowest keep rule that fixes it.

Debugging a release-only crash#

There is a procedure, and following it saves hours.

1. Reproduce with R8 on and obfuscation off. Set -dontobfuscate and rebuild. If the crash disappears, the problem is a name being looked up reflectively; if it persists, it is shrinking.
2. Read the mapping. With obfuscation on, retrace the stack trace before doing anything else. The class name in the trace is meaningless until you do.
3. Narrow the keep rule. Keep the specific class or member that is looked up, not the package. Then verify in seeds.txt that the rule kept what you expected and nothing more.
4. Recheck resource shrinking separately. If the crash is a missing resource, the code keep rules are irrelevant; tools:keep in a keep.xml is the tool.

The order matters because the two failure modes look identical from the outside. A ClassNotFoundException can come from either, and only step one distinguishes them.

The keep-rule review heuristics#

Three questions make a rule review fast.

Does it name a package instead of a class? A package-wide rule usually means someone did not find the specific entry point. It works, and it costs the shrinking you enabled R8 for.

Does it keep * for a class that needs only a name? -keepnames keeps the name and allows shrinking, which is usually what reflection needs. -keep keeps everything.

Is there a matching -dontwarn for a class that is genuinely absent? -dontwarn silences a warning about a class that does not exist. If the class exists and is being removed, -dontwarn is the wrong tool and will hide the real failure until runtime.

How it evolved#

The compatibility decision — keep reading the old rule format — is why a project's proguard-rules.pro has never needed renaming, and also why stale rules accumulate for years.

Under the hood#

• ‹›proguard-rules.pro↗your rules; the project template creates it empty
• ‹›mapping.txt↗the rename map; archive it with every release
• ‹›usage.txt↗what R8 removed, when it is configured to report it
• ‹›seeds.txt↗the classes and members kept by your rules

seeds.txt is the underrated one. It answers "what did my keep rules actually protect?" — and a seed list far larger than expected is the first sign that a rule is too broad.

Curiosity corner#

• R8 was built to be faster than ProGuard on large programs, not to be a better obfuscator. The shrinking and the dexing share one pass, which is where the speed comes from.
• Obfuscation is reversible with enough effort, mapping file or not. It raises cost; it is not encryption.
• The -dontwarn flag silences a warning, not an error. It is for classes that are genuinely optional at runtime, and using it to silence a missing dependency is how you get a NoClassDefFoundError in production.

Try it#

$ 
./gradlew :app:assembleRelease
head -20 app/build/outputs/mapping/release/mapping.txt

com.example.app.MainActivity -> a.a:
    void onCreate(android.os.Bundle) -> a
    com.example.app.data.User user -> b

$ 
cat app/build/outputs/mapping/release/usage.txt | head -40

com.example.app.legacy.LegacySync
com.example.app.debug.DebugOverlay

$ 
retrace mapping.txt obfuscated-stacktrace.txt

java.lang.NullPointerException
    at com.example.app.data.User.equals(User.kt:12)

Build it#

Enable isMinifyEnabled and isShrinkResources on a real project, build release, and install it. Then add a class that is loaded only by name and watch it disappear. That is the lesson no documentation can give you as directly as ClassNotFoundException at 2 a.m.

Check yourself#

Sources#