1page.title=ProGuard 2parent.title=Tools 3parent.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-gradle">Enabling ProGuard (Gradle Builds)</a></li> 12 13 <li><a href="#enabling">Enabling ProGuard (Ant Builds)</a></li> 14 15 <li><a href="#configuring">Configuring ProGuard</a></li> 16 17 <li> 18 <a href="#decoding">Decoding Obfuscated Stack Traces</a> 19 20 <ol> 21 <li><a href="#considerations">Debugging considerations for published 22 applications</a></li> 23 </ol> 24 </li> 25 </ol> 26 27 <h2>See also</h2> 28 29 <ol> 30 <li> 31 <a href="http://stuff.mit.edu/afs/sipb/project/android/sdk/android-sdk-linux/tools/proguard/docs/index.html#manual/introduction.html">ProGuard 32 Manual »</a> 33 </li> 34 <li> 35 <a href="http://stuff.mit.edu/afs/sipb/project/android/sdk/android-sdk-linux/tools/proguard/docs/index.html#manual/retrace/introduction.html">ProGuard 36 ReTrace Manual »</a> 37 </li> 38 </ol> 39 </div> 40 </div> 41 42 43 44 <p>The <a href="http://proguard.sourceforge.net">ProGuard</a> tool shrinks, optimizes, and 45 obfuscates your code by removing unused code and 46 renaming classes, fields, and methods with semantically obscure names. The result is a smaller 47 sized <code>.apk</code> file that is more difficult to reverse engineer. Because ProGuard makes your 48 application harder to reverse engineer, it is important that you use it 49 when your application utilizes features that are sensitive to security like when you are 50 <a href="{@docRoot}google/play/licensing/index.html">Licensing Your Applications</a>.</p> 51 52 <p>ProGuard is integrated into the Android build system, so you do not have to invoke it 53 manually. ProGuard runs only when you build your application in release mode, so you do not 54 have to deal with obfuscated code when you build your application in debug mode. 55 Having ProGuard run is completely optional, but highly recommended.</p> 56 57 <p>This document describes how to enable and configure ProGuard as well as use the 58 <code>retrace</code> tool to decode obfuscated stack traces.</p> 59 60 61 <h2 id="enabling-gradle">Enabling ProGuard (Gradle Builds)</h2> 62 <p>When you create a project in Android Studio or with the Gradle build system, the 63 <code>minifyEnabled</code> property in the <code>build.gradle</code> file enables and disables 64 ProGuard for release builds. The <code>minifyEnabled</code> property is part of the 65 <code>buildTypes</code> <code>release</code> block that controls the settings applied to 66 release builds. Set the <code>minifyEnabled</code> property to <code>true</code> to enable 67 ProGuard, as shown in this example. </p> 68 69 <pre class="no-pretty-print"> 70 android { 71 ... 72 73 buildTypes { 74 release { 75 minifyEnabled true 76 proguardFiles getDefaultProguardFile('proguard-android.txt'), 77 'proguard-rules.pro' 78 } 79 } 80 } 81 </pre> 82 83 <p>The <code>getDefaultProguardFile('proguard-android.txt')</code> method obtains the default 84 ProGuard settings from the Android SDK <code>tools/proguard/</code> folder. The 85 <code>proguard-android-optimize.txt</code> file is also available in this Android SDK 86 folder with the same rules but with optimizations enabled. ProGuard optimizations perform 87 analysis at the bytecode level, inside and across methods to help make your app smaller and run 88 faster. Android Studio adds the <code>proguard-rules.pro</code> file at the root of the module, 89 so you can also easily add custom ProGuard rules specific to the current module. </p> 90 91 <p>You can also add ProGuard files to the <code>getDefaultProguardFile</code> 92 directive for all release builds or as part of the <code>productFlavor</code> settings in the 93 <code>build.gradle</code> file to customize the settings applied to build variants. This example 94 adds the <code>proguard-rules-new.pro</code> to the <code>proguardFiles</code> 95 directive and the <code>other-rules.pro</code> file to the <code>flavor2</code> product flavor. </p> 96 97<pre class="no-pretty-print"> 98 android { 99 ... 100 101 buildTypes { 102 release { 103 minifyEnabled true 104 proguardFiles getDefaultProguardFile('proguard-android.txt'), 105 'proguard-rules.pro', 'proguard-rules-new.pro' 106 } 107 } 108 109 productFlavors { 110 flavor1 { 111 } 112 flavor2 { 113 proguardFile 'other-rules.pro' 114 } 115 } 116 } 117 </pre> 118 119 120 121 <h2 id="enabling">Enabling ProGuard (Ant Builds)</h2> 122 123 <p>When you create an Android project, a <code>proguard.cfg</code> file is automatically 124 generated in the root directory of the project. This file defines how ProGuard optimizes and 125 obfuscates your code, so it is very important that you understand how to customize it for your 126 needs. The default configuration file only covers general cases, so you most likely have to edit 127 it for your own needs. See the following section about <a href="#configuring">Configuring 128 ProGuard</a> for information on customizing the ProGuard configuration file.</p> 129 130 <p>To enable ProGuard so that it runs as part of an Ant or Eclipse build, set the 131 <code>proguard.config</code> property in the <code><project_root>/project.properties</code> 132 file. The path can be an absolute path or a path relative to the project's root.</p> 133 134 <p>If you left the <code>proguard.cfg</code> file in its default location (the project's root 135 directory), you can specify its location like this:</p> 136 137<pre class="no-pretty-print"> 138proguard.config=proguard.cfg 139</pre> 140 141<p> 142You can also move the the file to anywhere you want, and specify the absolute path to it: 143</p> 144 145<pre class="no-pretty-print"> 146proguard.config=/path/to/proguard.cfg 147</pre> 148 149 <p>When you build your application in release mode, either by running <code>ant release</code> or 150 by using the <em>Export Wizard</em> in Eclipse, the build system automatically checks to see if 151 the <code>proguard.config</code> property is set. If it is, ProGuard automatically processes 152 the application's bytecode before packaging everything into an <code>.apk</code> file. Building in debug mode 153 does not invoke ProGuard, because it makes debugging more cumbersome.</p> 154 155 <p>ProGuard outputs the following files after it runs:</p> 156 157 <dl> 158 <dt><code>dump.txt</code></dt> 159 <dd>Describes the internal structure of all the class files in the <code>.apk</code> file</dd> 160 161 <dt><code>mapping.txt</code></dt> 162 <dd>Lists the mapping between the original and obfuscated class, method, and field names. 163 This file is important when you receive a bug report from a release build, because it 164 translates the obfuscated stack trace back to the original class, method, and member names. 165 See <a href="#decoding">Decoding Obfuscated Stack Traces</a> for more information.</dd> 166 167 <dt><code>seeds.txt</code></dt> 168 <dd>Lists the classes and members that are not obfuscated</dd> 169 170 <dt><code>usage.txt</code></dt> 171 <dd>Lists the code that was stripped from the <code>.apk</code></dd> 172 </ul> 173 174 <p>These files are located in the following directories:</p> 175 176 <ul> 177 <li><code><project_root>/bin/proguard</code> if you are using Ant.</li> 178 179 <li><code><project_root>/proguard</code> if you are using Eclipse.</li> 180 </ul> 181 182 183 <p class="caution"><strong>Caution:</strong> Every time you run a build in release mode, these files are 184 overwritten with the latest files generated by ProGuard. Save a copy of them each time you release your 185 application in order to de-obfuscate bug reports from your release builds. 186 For more information on why saving these files is important, see 187 <a href="#considerations">Debugging considerations for published applications</a>. 188 </p> 189 190 <h2 id="configuring">Configuring ProGuard</h2> 191 192 <p>For some situations, the default configurations in the ProGuard configuration file will 193 suffice. However, many situations are hard for ProGuard to analyze correctly and it might remove 194 code that it thinks is not used, but your application actually needs. Some examples include:</p> 195 196 <ul> 197 <li>a class that is referenced only in the <code>AndroidManifest.xml</code> file</li> 198 199 <li>a method called from JNI</li> 200 201 <li>dynamically referenced fields and methods</li> 202 </ul> 203 204 <p>The default ProGuard configuration file tries to cover general cases, but you might 205 encounter exceptions such as <code>ClassNotFoundException</code>, which happens when ProGuard 206 strips away an entire class that your application calls.</p> 207 208 <p>You can fix errors when ProGuard strips away your code by adding a <code>-keep</code> line in 209 the ProGuard configuration file. For example:</p> 210 <pre> 211-keep public class <MyClass> 212</pre> 213 214 <p>There are many options and considerations when using the <code>-keep</code> option, so it is 215 highly recommended that you read the 216 <a href="http://stuff.mit.edu/afs/sipb/project/android/sdk/android-sdk-linux/tools/proguard/docs/index.html#manual/introduction.html">ProGuard 217 Manual</a> for more information about customizing your configuration file. The 218 <em>Overview of Keep options</em> and <em>Examples</em> sections are particularly helpful. 219 The <a href= 220 "http://stuff.mit.edu/afs/sipb/project/android/sdk/android-sdk-linux/tools/proguard/docs/index.html#manual/troubleshooting.html">Troubleshooting 221 </a> section of the ProGuard Manual outlines other common problems you might encounter 222 when your code gets stripped away.</p> 223 224 <h2 id="decoding">Decoding Obfuscated Stack Traces</h2> 225 226 <p>When your obfuscated code outputs a stack trace, the method names are obfuscated, which makes 227 debugging hard, if not impossible. Fortunately, whenever ProGuard runs, it outputs a 228 <code>mapping.txt</code> file, which shows you the original class, method, and field names 229 mapped to their obfuscated names.</p> 230 231 <p>The <code>retrace.bat</code> script on Windows or the <code>retrace.sh</code> script on Linux 232 or Mac OS X can convert an obfuscated stack trace to a readable one. It is located 233 in the <code><sdk_root>/tools/proguard/</code> directory. The syntax for executing the 234 <code>retrace</code> tool is:</p> 235 <pre>retrace.bat|retrace.sh [-verbose] mapping.txt [<stacktrace_file>]</pre> 236 <p>For example:</p> 237 238 <pre>retrace.bat -verbose mapping.txt obfuscated_trace.txt</pre> 239 240 <p>If you do not specify a value for <em><stacktrace_file></em>, the <code>retrace</code> tool reads 241 from standard input.</p> 242 243 <h3 id="considerations">Debugging considerations for published applications</h3> 244 245 <p>Save the <code>mapping.txt</code> file for every release that you publish to your users. 246 By retaining a copy of the <code>mapping.txt</code> file for each release build, 247 you ensure that you can debug a problem if a user encounters a bug and submits an obfuscated stack trace. 248 A project's <code>mapping.txt</code> file is overwritten every time you do a release build, so you must be 249 careful about saving the versions that you need. For Eclipse, this file is stored in 250 <code><project_root>/bin/proguard/</code>. For Android Studio, this file is stored in 251 the app <code>build/outs/</code> folder. </p> 252 253 <p>For example, say you publish an application and continue developing new features of 254 the application for a new version. You then do a release build using ProGuard soon after. The 255 build overwrites the previous <code>mapping.txt</code> file. A user submits a bug report 256 containing a stack trace from the application that is currently published. You no longer have a way 257 of debugging the user's stack trace, because the <code>mapping.txt</code> file associated with the version 258 on the user's device is gone. There are other situations where your <code>mapping.txt</code> file can be overwritten, so 259 ensure that you save a copy for every release that you anticipate you have to debug.</p> 260 261 <p>How you save the <code>mapping.txt</code> files is your decision. For example, you can rename 262 the files to include a version or build number, or you can version control them along with your 263 source code.</p> 264