Doc change: Proguard tool
Change-Id: I98602bf61a971f00cbd41284b457bcb2c15ea441
diff --git a/docs/html/guide/developing/tools/proguard.jd b/docs/html/guide/developing/tools/proguard.jd
new file mode 100644
index 0000000..6abbd36
--- /dev/null
+++ b/docs/html/guide/developing/tools/proguard.jd
@@ -0,0 +1,187 @@
+page.title=ProGuard
+@jd:body
+
+ <div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+
+ <ol>
+ <li><a href="#enabling">Enabling ProGuard</a></li>
+
+ <li><a href="#configuring">Configuring ProGuard</a></li>
+
+ <li>
+ <a href="#decoding">Decoding Obfuscated Stack Traces</a>
+
+ <ol>
+ <li><a href="#considerations">Debugging considerations for published
+ applications</a></li>
+ </ol>
+ </li>
+ </ol>
+
+ <h2>See also</h2>
+
+ <ol>
+ <li><a href="http://proguard.sourceforge.net/manual/introduction.html">ProGuard
+ Manual</a></li>
+
+ <li><a href="http://proguard.sourceforge.net/manual/retrace/introduction.html">ProGuard
+ ReTrace Manual</a></li>
+ </ol>
+ </div>
+ </div>
+
+ <p>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 <code>.apk</code> 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
+ <a href="{@docRoot}guide/publishing/licensing.html">Licensing Your Applications</a>.</p>
+
+ <p>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.</p>
+
+ <p>This document describes how to enable and configure ProGuard as well as use the
+ <code>retrace</code> tool to decode obfuscated stack traces.</p>
+
+ <h2 id="enabling">Enabling ProGuard</h2>
+
+ <p>When you create an Android project, a <code>proguard.cfg</code> 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 <a href="#configuring">Configuring ProGuard</a> for information on
+ customizing the ProGuard configuration file.</p>
+
+ <p>To enable ProGuard so that it runs as part of an Ant or Eclipse build, set the
+ <code>proguard.config</code> property in the <code><project_root>/default.properties</code>
+ file. The path can be an absolute path or a path relative to the project's root.</p>
+<p>If you left the <code>proguard.cfg</code> file in its default location (the project's root directory),
+you can specify its location like this:</p>
+<pre class="no-pretty-print">
+proguard.config=proguard.cfg
+</pre>
+<p>
+You can also move the the file to anywhere you want, and specify the absolute path to it:
+</p>
+<pre class="no-pretty-print">
+proguard.config=/path/to/proguard.cfg
+</pre>
+
+
+ <p>When you build your application in release mode, either by running <code>ant release</code> or
+ by using the <em>Export Wizard</em> in Eclipse, the build system automatically checks to see if
+ the <code>proguard.config</code> property is set. If it is, ProGuard automatically processes
+ the application's bytecode before packaging everything into an <code>.apk</code> file. Building in debug mode
+ does not invoke ProGuard, because it makes debugging more cumbersome.</p>
+
+ <p>ProGuard outputs the following files after it runs:</p>
+
+ <dl>
+ <dt><code>dump.txt</code></dt>
+ <dd>Describes the internal structure of all the class files in the <code>.apk</code> file</dd>
+
+ <dt><code>mapping.txt</code></dt>
+ <dd>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 <a href="#decoding">Decoding Obfuscated Stack Traces</a> for more information.</dd>
+
+ <dt><code>seeds.txt</code></dt>
+ <dd>Lists the classes and members that are not obfuscated</dd>
+
+ <dt><code>usage.txt</code></dt>
+ <dd>Lists the code that was stripped from the <code>.apk</code></dd>
+ </ul>
+
+ <p>These files are located in the following directories:</p>
+
+ <ul>
+ <li><code><project_root>/bin/proguard</code> if you are using Ant.</li>
+
+ <li><code><project_root>/proguard</code> if you are using Eclipse.</li>
+ </ul>
+
+
+ <p class="caution"><strong>Caution:</strong> 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
+ <a href="#considerations">Debugging considerations for published applications</a>.
+ </p>
+
+ <h2 id="configuring">Configuring ProGuard</h2>
+
+ <p>For some situations, the default configurations in the <code>proguard.cfg</code> 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:</p>
+
+ <ul>
+ <li>a class that is referenced only in the <code>AndroidManifest.xml</code> file</li>
+
+ <li>a method called from JNI</li>
+
+ <li>dynamically referenced fields and methods</li>
+ </ul>
+
+ <p>The default <code>proguard.cfg</code> file tries to cover general cases, but you might
+ encounter exceptions such as <code>ClassNotFoundException</code>, which happens when ProGuard
+ strips away an entire class that your application calls.</p>
+
+ <p>You can fix errors when ProGuard strips away your code by adding a <code>-keep</code> line in
+ the <code>proguard.cfg</code> file. For example:</p>
+ <pre>
+-keep public class <MyClass>
+</pre>
+
+ <p>There are many options and considerations when using the <code>-keep</code> option, so it is
+ highly recommended that you read the <a href="http://proguard.sourceforge.net/manual/introduction.html">ProGuard
+ Manual</a> for more information about customizing your configuration file. The <a href=
+ "http://proguard.sourceforge.net/manual/usage.html#keepoverview">Overview of Keep options</a> and
+ <a href="http://proguard.sourceforge.net/index.html#/manual/examples.html">Examples section</a>
+ are particularly helpful. The <a href=
+ "http://proguard.sourceforge.net/manual/troubleshooting.html">Troubleshooting</a> section of the
+ ProGuard Manual outlines other common problems you might encounter when your code gets stripped
+ away.</p>
+
+ <h2 id="decoding">Decoding Obfuscated Stack Traces</h2>
+
+ <p>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
+ <code><project_root>/bin/proguard/mapping.txt</code> file, which shows you the original
+ class, method, and field names mapped to their obfuscated names.</p>
+
+ <p>The <code>retrace.bat</code> script on Windows or the <code>retrace.sh</code> script on Linux
+ or Mac OS X can convert an obfuscated stack trace to a readable one. It is located in the
+ <code><sdk_root>/tools/proguard/</code> directory. The syntax for executing the
+ <code>retrace</code> tool is:</p>
+ <pre>retrace.bat|retrace.sh [-verbose] mapping.txt [<stacktrace_file>]</pre>
+ <p>For example:</p>
+
+ <pre>retrace.bat -verbose mapping.txt obfuscated_trace.txt</pre>
+
+ <p>If you do not specify a value for <em><stacktrace_file></em>, the <code>retrace</code> tool reads
+ from standard input.</p>
+
+ <h3 id="considerations">Debugging considerations for published applications</h3>
+
+ <p>Save the <code>mapping.txt</code> file for every release that you publish to your users.
+ By retaining a copy of the <code>mapping.txt</code> 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 <code>mapping.txt</code> file is overwritten every time you do a release build, so you must be
+ careful about saving the versions that you need.</p>
+
+ <p>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 <code>mapping.txt</code> 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 <code>mapping.txt</code> file associated with the version
+ on the user's device is gone. There are other situations where your <code>mapping.txt</code> file can be overwritten, so
+ ensure that you save a copy for every release that you anticipate you have to debug.</p>
+
+ <p>How you save the <code>mapping.txt</code> 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.</p>
\ No newline at end of file
diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs
index 9c0fcff..545807e 100644
--- a/docs/html/guide/guide_toc.cs
+++ b/docs/html/guide/guide_toc.cs
@@ -375,7 +375,7 @@
<li><a href="<?cs var:toroot ?>guide/developing/tools/layoutopt.html">layoutopt</a></li>
<li><a href="<?cs var:toroot ?>guide/developing/tools/othertools.html#mksdcard">mksdcard</a></li>
<li><a href="<?cs var:toroot ?>guide/developing/tools/monkey.html">Monkey</a></li>
- <li class="toggle-list">
+ <li class="toggle-list">
<div>
<a href="<?cs var:toroot?>guide/developing/tools/monkeyrunner_concepts.html">
<span class="en">monkeyrunner</span>
@@ -403,6 +403,7 @@
</li>
</ul>
</li>
+ <li><a href="<?cs var:toroot ?>guide/developing/tools/proguard.html">Proguard</a></li>
<li><a href="<?cs var:toroot ?>guide/developing/tools/adb.html#sqlite">sqlite3</a></li>
<li><a href="<?cs var:toroot ?>guide/developing/tools/traceview.html" >Traceview</a></li>
<li><a href="<?cs var:toroot ?>guide/developing/tools/zipalign.html" >zipalign</a></li>