From 47e43febdd8ba83c333c9c98ca6a8c0bda421305 Mon Sep 17 00:00:00 2001 From: Robert Ly Date: Thu, 21 Oct 2010 17:12:00 -0700 Subject: Doc change: Proguard tool Change-Id: I98602bf61a971f00cbd41284b457bcb2c15ea441 --- docs/html/guide/developing/tools/proguard.jd | 187 +++++++++++++++++++++++++++ docs/html/guide/guide_toc.cs | 3 +- 2 files changed, 189 insertions(+), 1 deletion(-) create mode 100644 docs/html/guide/developing/tools/proguard.jd diff --git a/docs/html/guide/developing/tools/proguard.jd b/docs/html/guide/developing/tools/proguard.jd new file mode 100644 index 000000000000..6abbd36f136e --- /dev/null +++ b/docs/html/guide/developing/tools/proguard.jd @@ -0,0 +1,187 @@ +page.title=ProGuard +@jd:body + +
+ +
+ +

The ProGuard tool shrinks, optimizes, and obfuscates your code by removing unused code and + renaming classes, fields, and methods with semantically obscure names. The result is a smaller + sized .apk file that is more difficult to reverse engineer. Because ProGuard makes your + application harder to reverse engineer, it is important that you use it + when your application utilizes features that are sensitive to security like when you are + Licensing Your Applications.

+ +

ProGuard is integrated into the Android build system, so you do not have to invoke it + manually. ProGuard runs only when you build your application in release mode, so you do not + have to deal with obfuscated code when you build your application in debug mode. + Having ProGuard run is completely optional, but highly recommended.

+ +

This document describes how to enable and configure ProGuard as well as use the + retrace tool to decode obfuscated stack traces.

+ +

Enabling ProGuard

+ +

When you create an Android project, a proguard.cfg file is automatically + generated in the root directory of the project. This file defines how ProGuard optimizes and + obfuscates your code, so it is very important that you understand how to customize it for your + needs. The default configuration file only covers general cases, so you most likely have to edit + it for your own needs. See the following section about Configuring ProGuard for information on + customizing the ProGuard configuration file.

+ +

To enable ProGuard so that it runs as part of an Ant or Eclipse build, set the + proguard.config property in the <project_root>/default.properties + file. The path can be an absolute path or a path relative to the project's root.

+

If you left the proguard.cfg file in its default location (the project's root directory), +you can specify its location like this:

+
+proguard.config=proguard.cfg
+
+

+You can also move the the file to anywhere you want, and specify the absolute path to it: +

+
+proguard.config=/path/to/proguard.cfg
+
+ + +

When you build your application in release mode, either by running ant release or + by using the Export Wizard in Eclipse, the build system automatically checks to see if + the proguard.config property is set. If it is, ProGuard automatically processes + the application's bytecode before packaging everything into an .apk file. Building in debug mode + does not invoke ProGuard, because it makes debugging more cumbersome.

+ +

ProGuard outputs the following files after it runs:

+ +
+
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:

+ + + + +

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:

+ + + +

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 <MyClass>
+
+ +

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 + <project_root>/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 + <sdk_root>/tools/proguard/ directory. The syntax for executing the + retrace tool is:

+ 
retrace.bat|retrace.sh [-verbose] mapping.txt [<stacktrace_file>]
+

For example:

+ + 
retrace.bat -verbose mapping.txt obfuscated_trace.txt
+ +

If you do not specify a value for <stacktrace_file>, 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.

\ No newline at end of file diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 9c0fcffc4bd2..545807eb1894 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -375,7 +375,7 @@
  • layoutopt
  • mksdcard
  • Monkey
    • -
  • +
  • monkeyrunner @@ -403,6 +403,7 @@
    • +
  • Proguard
  • sqlite3
  • Traceview
  • zipalign
    • -- cgit v1.2.3-59-g8ed1b