1 page.title=ProGuard 2 parent.title=Tools 3 parent.link=index.html 4 @jd:body 5 6 <div id="qv-wrapper"> 7 <div id="qv"> 8 <h2>In this document</h2> 9 10 <ol> 11 <li><a href="#enabling">Enabling ProGuard</a></li> 12 13 <li><a href="#configuring">Configuring ProGuard</a></li> 14 15 <li> 16 <a href="#decoding">Decoding Obfuscated Stack Traces</a> 17 18 <ol> 19 <li><a href="#considerations">Debugging considerations for published 20 applications</a></li> 21 </ol> 22 </li> 23 </ol> 24 25 <h2>See also</h2> 26 27 <ol> 28 <li><a href="http://proguard.sourceforge.net/manual/introduction.html">ProGuard 29 Manual »</a></li> 30 31 <li><a href="http://proguard.sourceforge.net/manual/retrace/introduction.html">ProGuard 32 ReTrace Manual »</a></li> 33 </ol> 34 </div> 35 </div> 36 37 <p>The ProGuard tool shrinks, optimizes, and obfuscates your code by removing unused code and 38 renaming classes, fields, and methods with semantically obscure names. The result is a smaller 39 sized <code>.apk</code> file that is more difficult to reverse engineer. Because ProGuard makes your 40 application harder to reverse engineer, it is important that you use it 41 when your application utilizes features that are sensitive to security like when you are 42 <a href="{@docRoot}google/play/licensing/index.html">Licensing Your Applications</a>.</p> 43 44 <p>ProGuard is integrated into the Android build system, so you do not have to invoke it 45 manually. ProGuard runs only when you build your application in release mode, so you do not 46 have to deal with obfuscated code when you build your application in debug mode. 47 Having ProGuard run is completely optional, but highly recommended.</p> 48 49 <p>This document describes how to enable and configure ProGuard as well as use the 50 <code>retrace</code> tool to decode obfuscated stack traces.</p> 51 52 <h2 id="enabling">Enabling ProGuard</h2> 53 54 <p>When you create an Android project, a <code>proguard.cfg</code> file is automatically 55 generated in the root directory of the project. This file defines how ProGuard optimizes and 56 obfuscates your code, so it is very important that you understand how to customize it for your 57 needs. The default configuration file only covers general cases, so you most likely have to edit 58 it for your own needs. See the following section about <a href="#configuring">Configuring ProGuard</a> for information on 59 customizing the ProGuard configuration file.</p> 60 61 <p>To enable ProGuard so that it runs as part of an Ant or Eclipse build, set the 62 <code>proguard.config</code> property in the <code><project_root>/project.properties</code> 63 file. The path can be an absolute path or a path relative to the project's root.</p> 64 <p>If you left the <code>proguard.cfg</code> file in its default location (the project's root directory), 65 you can specify its location like this:</p> 66 <pre class="no-pretty-print"> 67 proguard.config=proguard.cfg 68 </pre> 69 <p> 70 You can also move the the file to anywhere you want, and specify the absolute path to it: 71 </p> 72 <pre class="no-pretty-print"> 73 proguard.config=/path/to/proguard.cfg 74 </pre> 75 76 77 <p>When you build your application in release mode, either by running <code>ant release</code> or 78 by using the <em>Export Wizard</em> in Eclipse, the build system automatically checks to see if 79 the <code>proguard.config</code> property is set. If it is, ProGuard automatically processes 80 the application's bytecode before packaging everything into an <code>.apk</code> file. Building in debug mode 81 does not invoke ProGuard, because it makes debugging more cumbersome.</p> 82 83 <p>ProGuard outputs the following files after it runs:</p> 84 85 <dl> 86 <dt><code>dump.txt</code></dt> 87 <dd>Describes the internal structure of all the class files in the <code>.apk</code> file</dd> 88 89 <dt><code>mapping.txt</code></dt> 90 <dd>Lists the mapping between the original and obfuscated class, method, and field names. 91 This file is important when you receive a bug report from a release build, because it 92 translates the obfuscated stack trace back to the original class, method, and member names. 93 See <a href="#decoding">Decoding Obfuscated Stack Traces</a> for more information.</dd> 94 95 <dt><code>seeds.txt</code></dt> 96 <dd>Lists the classes and members that are not obfuscated</dd> 97 98 <dt><code>usage.txt</code></dt> 99 <dd>Lists the code that was stripped from the <code>.apk</code></dd> 100 </ul> 101 102 <p>These files are located in the following directories:</p> 103 104 <ul> 105 <li><code><project_root>/bin/proguard</code> if you are using Ant.</li> 106 107 <li><code><project_root>/proguard</code> if you are using Eclipse.</li> 108 </ul> 109 110 111 <p class="caution"><strong>Caution:</strong> Every time you run a build in release mode, these files are 112 overwritten with the latest files generated by ProGuard. Save a copy of them each time you release your 113 application in order to de-obfuscate bug reports from your release builds. 114 For more information on why saving these files is important, see 115 <a href="#considerations">Debugging considerations for published applications</a>. 116 </p> 117 118 <h2 id="configuring">Configuring ProGuard</h2> 119 120 <p>For some situations, the default configurations in the <code>proguard.cfg</code> file will 121 suffice. However, many situations are hard for ProGuard to analyze correctly and it might remove code 122 that it thinks is not used, but your application actually needs. Some examples include:</p> 123 124 <ul> 125 <li>a class that is referenced only in the <code>AndroidManifest.xml</code> file</li> 126 127 <li>a method called from JNI</li> 128 129 <li>dynamically referenced fields and methods</li> 130 </ul> 131 132 <p>The default <code>proguard.cfg</code> file tries to cover general cases, but you might 133 encounter exceptions such as <code>ClassNotFoundException</code>, which happens when ProGuard 134 strips away an entire class that your application calls.</p> 135 136 <p>You can fix errors when ProGuard strips away your code by adding a <code>-keep</code> line in 137 the <code>proguard.cfg</code> file. For example:</p> 138 <pre> 139 -keep public class <MyClass> 140 </pre> 141 142 <p>There are many options and considerations when using the <code>-keep</code> option, so it is 143 highly recommended that you read the <a href="http://proguard.sourceforge.net/manual/introduction.html">ProGuard 144 Manual</a> for more information about customizing your configuration file. The <a href= 145 "http://proguard.sourceforge.net/manual/usage.html#keepoverview">Overview of Keep options</a> and 146 <a href="http://proguard.sourceforge.net/index.html#/manual/examples.html">Examples section</a> 147 are particularly helpful. The <a href= 148 "http://proguard.sourceforge.net/manual/troubleshooting.html">Troubleshooting</a> section of the 149 ProGuard Manual outlines other common problems you might encounter when your code gets stripped 150 away.</p> 151 152 <h2 id="decoding">Decoding Obfuscated Stack Traces</h2> 153 154 <p>When your obfuscated code outputs a stack trace, the method names are obfuscated, which makes 155 debugging hard, if not impossible. Fortunately, whenever ProGuard runs, it outputs a 156 <code><project_root>/bin/proguard/mapping.txt</code> file, which shows you the original 157 class, method, and field names mapped to their obfuscated names.</p> 158 159 <p>The <code>retrace.bat</code> script on Windows or the <code>retrace.sh</code> script on Linux 160 or Mac OS X can convert an obfuscated stack trace to a readable one. It is located in the 161 <code><sdk_root>/tools/proguard/</code> directory. The syntax for executing the 162 <code>retrace</code> tool is:</p> 163 <pre>retrace.bat|retrace.sh [-verbose] mapping.txt [<stacktrace_file>]</pre> 164 <p>For example:</p> 165 166 <pre>retrace.bat -verbose mapping.txt obfuscated_trace.txt</pre> 167 168 <p>If you do not specify a value for <em><stacktrace_file></em>, the <code>retrace</code> tool reads 169 from standard input.</p> 170 171 <h3 id="considerations">Debugging considerations for published applications</h3> 172 173 <p>Save the <code>mapping.txt</code> file for every release that you publish to your users. 174 By retaining a copy of the <code>mapping.txt</code> file for each release build, 175 you ensure that you can debug a problem if a user encounters a bug and submits an obfuscated stack trace. 176 A project's <code>mapping.txt</code> file is overwritten every time you do a release build, so you must be 177 careful about saving the versions that you need.</p> 178 179 <p>For example, say you publish an application and continue developing new features of 180 the application for a new version. You then do a release build using ProGuard soon after. The 181 build overwrites the previous <code>mapping.txt</code> file. A user submits a bug report 182 containing a stack trace from the application that is currently published. You no longer have a way 183 of debugging the user's stack trace, because the <code>mapping.txt</code> file associated with the version 184 on the user's device is gone. There are other situations where your <code>mapping.txt</code> file can be overwritten, so 185 ensure that you save a copy for every release that you anticipate you have to debug.</p> 186 187 <p>How you save the <code>mapping.txt</code> file is your decision. For example, you can rename them to 188 include a version or build number, or you can version control them along with your source 189 code.</p>
