Understanding ProGuard Mapping Conflicts and Incremental Obfuscation

ProGuard, released in 2002 by Eric Lafortune, is a widely used open‑source Java/Android code optimizer and obfuscator. It consists of four modules: Shrinker, Optimizer, Obfuscator and Retrace.

The article focuses on a problem that appears when using the -applymapping option for incremental obfuscation. After applying a previous mapping file, ProGuard may emit warnings such as Warning: ... is not being kept as ..., but remapped to ..., and the resulting obfuscated method names can become inconsistent with the host module, causing compatibility issues.

Typical symptoms include warnings like:

Printing mapping to [.../mapping.txt]...
Warning: com.bumptech.glide.load.resource.gif.GifFrameLoader: method 'void stop()' is not being kept as 'b', but remapped to 'c'
...

and a diff showing that the method stop() is mapped to b in the initial obfuscation but to c_ after applying the mapping.

The root cause lies in how ProGuard handles mapping reuse (MappingKeeper), name collection (MemberNameCollector) and conflict resolution. When a method already has a visitorInfo (the new name) from a previous mapping, the collector may overwrite it with a later entry (e.g., clear overwriting stop), leading to duplicate new names. During the conflict‑handling phase, ProGuard detects the duplicate, clears the visitorInfo of the later method and generates a new name with an underscore suffix, producing the observed c_ mapping.

Inline information further complicates the picture. ProGuard’s optimizer can inline small methods, copying their bytecode into callers. Inline entries appear in the mapping file with line‑range annotations, e.g.:

81:88: void clear() -> c
2077:2078: void stop() :77:78 -> c

When a crash occurs in an inlined method, Retrace uses these annotations to reconstruct the original stack trace.

The article outlines the full ProGuard workflow: initialization (reading rules and seeds), shrink (removing unused code), optimize (including inlining), a second shrink, and finally obfuscate (name assignment, conflict handling, mapping generation). It also explains how the mapping file is structured (class, field, method mappings, and inline entries) and why certain warnings appear.

To reproduce the issue, the authors provide a sample project (ProGuardSample) that triggers the warning when compiled with ./gradlew assembleDebug and then re‑compiled with -applymapping.

Additional common ProGuard pitfalls are listed, such as reflection‑related keep rules, incorrect rule syntax, and performance tuning of -optimizationpasses.

In summary, the article explains the internal mechanisms of ProGuard that lead to mapping conflicts during incremental obfuscation and offers practical guidance for diagnosing and fixing them.