docs/html/tools/help/proguard.jd

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