dump.txt
Describes the internal structure of all the class files in the .apk file
mapping.txt
Lists the mapping between the original and obfuscated class, method, and field names.
This file is important when you receive a bug report from a release build, because it
translates the obfuscated stack trace back to the original class, method, and member names.
See Decoding Obfuscated Stack Traces for more information.
seeds.txt
Lists the classes and members that are not obfuscated
usage.txt
Lists the code that was stripped from the .apk
These files are located in the following directories:
/bin/proguard if you are using Ant.
/proguard if you are using Eclipse.
Caution: Every time you run a build in release mode, these files are
overwritten with the latest files generated by ProGuard. Save a copy of them each time you release your
application in order to de-obfuscate bug reports from your release builds.
For more information on why saving these files is important, see
Debugging considerations for published applications.
Configuring ProGuard
For some situations, the default configurations in the proguard.cfg file will
suffice. However, many situations are hard for ProGuard to analyze correctly and it might remove code
that it thinks is not used, but your application actually needs. Some examples include:
a class that is referenced only in the AndroidManifest.xml file
a method called from JNI
dynamically referenced fields and methods
The default proguard.cfg file tries to cover general cases, but you might
encounter exceptions such as ClassNotFoundException, which happens when ProGuard
strips away an entire class that your application calls.
You can fix errors when ProGuard strips away your code by adding a -keep line in
the proguard.cfg file. For example:
-keep public class
There are many options and considerations when using the -keep option, so it is
highly recommended that you read the ProGuard
Manual for more information about customizing your configuration file. The Overview of Keep options and
Examples section
are particularly helpful. The Troubleshooting section of the
ProGuard Manual outlines other common problems you might encounter when your code gets stripped
away.
Decoding Obfuscated Stack Traces
When your obfuscated code outputs a stack trace, the method names are obfuscated, which makes
debugging hard, if not impossible. Fortunately, whenever ProGuard runs, it outputs a
/bin/proguard/mapping.txt file, which shows you the original
class, method, and field names mapped to their obfuscated names.
The retrace.bat script on Windows or the retrace.sh script on Linux
or Mac OS X can convert an obfuscated stack trace to a readable one. It is located in the
/tools/proguard/ directory. The syntax for executing the
retrace tool is:
retrace.bat|retrace.sh [-verbose] mapping.txt []
For example:
retrace.bat -verbose mapping.txt obfuscated_trace.txt
If you do not specify a value for , the retrace tool reads
from standard input.
Debugging considerations for published applications
Save the mapping.txt file for every release that you publish to your users.
By retaining a copy of the mapping.txt file for each release build,
you ensure that you can debug a problem if a user encounters a bug and submits an obfuscated stack trace.
A project's mapping.txt file is overwritten every time you do a release build, so you must be
careful about saving the versions that you need.
For example, say you publish an application and continue developing new features of
the application for a new version. You then do a release build using ProGuard soon after. The
build overwrites the previous mapping.txt file. A user submits a bug report
containing a stack trace from the application that is currently published. You no longer have a way
of debugging the user's stack trace, because the mapping.txt file associated with the version
on the user's device is gone. There are other situations where your mapping.txt file can be overwritten, so
ensure that you save a copy for every release that you anticipate you have to debug.
How you save the mapping.txt file is your decision. For example, you can rename them to
include a version or build number, or you can version control them along with your source
code.