| <!doctype html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
| <html> |
| <head> |
| <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"> |
| <meta http-equiv="content-style-type" content="text/css"> |
| <link rel="stylesheet" type="text/css" href="style.css"> |
| <title>ProGuard Introduction</title> |
| </head> |
| <body> |
| |
| <h2>Introduction</h2> |
| |
| <b>ProGuard</b> is a Java class file shrinker, optimizer, obfuscator, and |
| preverifier. The shrinking step detects and removes unused classes, fields, |
| methods, and attributes. The optimization step analyzes and optimizes the |
| bytecode of the methods. The obfuscation step renames the remaining classes, |
| fields, and methods using short meaningless names. These first steps make the |
| code base smaller, more efficient, and harder to reverse-engineer. The final |
| preverification step adds preverification information to the classes, which is |
| required for Java Micro Edition or which improves the start-up time for Java |
| 6. |
| <p> |
| Each of these steps is optional. For instance, ProGuard can also be used to |
| just list dead code in an application, or to preverify class files for |
| efficient use in Java 6. |
| <p> |
| |
| <table class="diagram" align="center"> |
| |
| <tr> |
| <td rowspan="4" class="lightblock">Input jars</td> |
| <td colspan="8" class="transparentblock"></td> |
| </tr> |
| |
| <tr> |
| <td rowspan="2" class="transparentblock"></td> |
| <td rowspan="3" class="lightblock">Shrunk code</td> |
| <td colspan="6" class="transparentblock"></td> |
| </tr> |
| |
| <tr> |
| <td class="transparentblock"></td> |
| <td rowspan="2" class="lightblock">Optim. code</td> |
| <td colspan="3" class="transparentblock"></td> |
| <td rowspan="2" class="lightblock">Output jars</td> |
| </tr> |
| |
| <tr> |
| <td class="transparentblock">- shrink →</td> |
| <td class="transparentblock">- optimize →</td> |
| <td class="transparentblock">- obfuscate →</td> |
| <td class="lightblock">Obfusc. code</td> |
| <td class="transparentblock">- preverify →</td> |
| </tr> |
| |
| <tr> |
| <td class="darkblock">Library jars</td> |
| <td colspan="7" class="transparentblock">------------------------------- (unchanged) -------------------------------→</td> |
| <td class="darkblock">Library jars</td> |
| </tr> |
| |
| </table> |
| <p> |
| |
| ProGuard typically reads the <b>input jars</b> (or wars, ears, zips, or |
| directories). It then shrinks, optimizes, obfuscates, and preverifies them. |
| Optionally, multiple optimization passes can be performed, each typically |
| followed by another shrinking step. ProGuard writes the processed results to |
| one or more <b>output jars</b> (or wars, ears, zips, or directories). The |
| input may contain resource files, whose names and contents can optionally be |
| updated to reflect the obfuscated class names. |
| <p> |
| ProGuard requires the <b>library jars</b> (or wars, ears, zips, or |
| directories) of the input jars to be specified. These are essentially the |
| libraries that you would need for compiling the code. ProGuard uses them to |
| reconstruct the class dependencies that are necessary for proper processing. |
| The library jars themselves always remain unchanged. You should still put them |
| in the class path of your final application. |
| <p> |
| In order to determine which code has to be preserved and which code can be |
| discarded or obfuscated, you have to specify one or more <i>entry points</i> to |
| your code. These entry points are typically classes with main methods, applets, |
| midlets, etc. |
| <ul> |
| <li>In the <b>shrinking step</b>, ProGuard starts from these seeds and |
| recursively determines which classes and class members are used. All other |
| classes and class members are discarded. |
| |
| <li>In the <b>optimization step</b>, ProGuard further optimizes the code. |
| Among other optimizations, classes and methods that are not entry points |
| can be made private, static, or final, unused parameters can be removed, |
| and some methods may be inlined. |
| |
| <li>In the <b>obfuscation step</b>, ProGuard renames classes and class members |
| that are not entry points. In this entire process, keeping the entry |
| points ensures that they can still be accessed by their original names. |
| |
| <li>The <b>preverification step</b> is the only step that doesn't have to know |
| the entry points. |
| </ul> |
| <p> |
| The <a href="usage.html">Usage section</a> of this manual describes the |
| necessary <a href="usage.html#keepoptions"><code>-keep</code> options</a> and |
| the <a href="examples.html">Examples section</a> provides plenty of examples. |
| |
| <h3>Introspection</h3> |
| |
| Introspection presents particular problems for any automatic processing of |
| code. In ProGuard, classes or class members in your code that are created or |
| invoked dynamically (that is, by name) have to be specified as entry points |
| too. For example, <code>Class.forName()</code> constructs may refer to any |
| class at run-time. It is generally impossible to foresee which classes have to |
| be preserved (with their original names), since the class names might be read |
| from a configuration file, for instance. You therefore have to specify them in |
| your ProGuard configuration, with the same simple <code>-keep</code> options. |
| <p> |
| However, ProGuard will already detect and handle the following cases for you: |
| |
| <ul> |
| <li><code>Class.forName("SomeClass")</code> |
| <li><code>SomeClass.class</code> |
| <li><code>SomeClass.class.getField("someField")</code> |
| <li><code>SomeClass.class.getDeclaredField("someField")</code> |
| <li><code>SomeClass.class.getMethod("someMethod", new Class[] {})</code> |
| <li><code>SomeClass.class.getMethod("someMethod", new Class[] { A.class })</code> |
| <li><code>SomeClass.class.getMethod("someMethod", new Class[] { A.class, B.class })</code> |
| <li><code>SomeClass.class.getDeclaredMethod("someMethod", new Class[] {})</code> |
| <li><code>SomeClass.class.getDeclaredMethod("someMethod", new Class[] { A.class })</code> |
| <li><code>SomeClass.class.getDeclaredMethod("someMethod", new Class[] { A.class, B.class })</code> |
| </ul> |
| |
| The names of the classes and class members may of course be different, but the |
| constructs should be literally the same for ProGuard to recognize them. The |
| referenced classes and class members are preserved in the shrinking phase, and |
| the string arguments are properly replaced in the obfuscation phase. |
| <p> |
| Furthermore, ProGuard will offer some suggestions if keeping some classes or |
| class members appears necessary. For example, ProGuard will note constructs |
| like "<code>(SomeClass)Class.forName(variable).newInstance()</code>". These |
| might be an indication that the class or interface <code>SomeClass</code> |
| and/or its implementations may need to be preserved. You can then adapt your |
| configuration accordingly. |
| <p> |
| For proper results, you should at least be somewhat familiar with the code |
| that you are processing. Obfuscating code that performs a lot of introspection |
| may require trial and error, especially without the necessary information |
| about the internals of the code. |
| <p> |
| |
| <hr> |
| <address> |
| Copyright © 2002-2009 |
| <a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. |
| </address> |
| </body> |
| </html> |
