1 <!doctype html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> 2 <html> 3 <head> 4 <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"> 5 <meta http-equiv="content-style-type" content="text/css"> 6 <link rel="stylesheet" type="text/css" href="style.css"> 7 <title>ProGuard Introduction</title> 8 </head> 9 <body> 10 11 <h2>Introduction</h2> 12 13 <b>ProGuard</b> is a Java class file shrinker, optimizer, obfuscator, and 14 preverifier. The shrinking step detects and removes unused classes, fields, 15 methods, and attributes. The optimization step analyzes and optimizes the 16 bytecode of the methods. The obfuscation step renames the remaining classes, 17 fields, and methods using short meaningless names. These first steps make the 18 code base smaller, more efficient, and harder to reverse-engineer. The final 19 preverification step adds preverification information to the classes, which is 20 required for Java Micro Edition or which improves the start-up time for Java 21 6. 22 <p> 23 Each of these steps is optional. For instance, ProGuard can also be used to 24 just list dead code in an application, or to preverify class files for 25 efficient use in Java 6. 26 <p> 27 28 <table class="diagram" align="center"> 29 30 <tr> 31 <td rowspan="4" class="lightblock">Input jars</td> 32 <td colspan="8" class="transparentblock"></td> 33 </tr> 34 35 <tr> 36 <td rowspan="2" class="transparentblock"></td> 37 <td rowspan="3" class="lightblock">Shrunk code</td> 38 <td colspan="6" class="transparentblock"></td> 39 </tr> 40 41 <tr> 42 <td class="transparentblock"></td> 43 <td rowspan="2" class="lightblock">Optim. code</td> 44 <td colspan="3" class="transparentblock"></td> 45 <td rowspan="2" class="lightblock">Output jars</td> 46 </tr> 47 48 <tr> 49 <td class="transparentblock">- shrink →</td> 50 <td class="transparentblock">- optimize →</td> 51 <td class="transparentblock">- obfuscate →</td> 52 <td class="lightblock">Obfusc. code</td> 53 <td class="transparentblock">- preverify →</td> 54 </tr> 55 56 <tr> 57 <td class="darkblock">Library jars</td> 58 <td colspan="7" class="transparentblock">------------------------------- (unchanged) -------------------------------→</td> 59 <td class="darkblock">Library jars</td> 60 </tr> 61 62 </table> 63 <p> 64 65 ProGuard typically reads the <b>input jars</b> (or wars, ears, zips, or 66 directories). It then shrinks, optimizes, obfuscates, and preverifies them. 67 Optionally, multiple optimization passes can be performed, each typically 68 followed by another shrinking step. ProGuard writes the processed results to 69 one or more <b>output jars</b> (or wars, ears, zips, or directories). The 70 input may contain resource files, whose names and contents can optionally be 71 updated to reflect the obfuscated class names. 72 <p> 73 ProGuard requires the <b>library jars</b> (or wars, ears, zips, or 74 directories) of the input jars to be specified. These are essentially the 75 libraries that you would need for compiling the code. ProGuard uses them to 76 reconstruct the class dependencies that are necessary for proper processing. 77 The library jars themselves always remain unchanged. You should still put them 78 in the class path of your final application. 79 <p> 80 In order to determine which code has to be preserved and which code can be 81 discarded or obfuscated, you have to specify one or more <i>entry points</i> to 82 your code. These entry points are typically classes with main methods, applets, 83 midlets, etc. 84 <ul> 85 <li>In the <b>shrinking step</b>, ProGuard starts from these seeds and 86 recursively determines which classes and class members are used. All other 87 classes and class members are discarded. 88 89 <li>In the <b>optimization step</b>, ProGuard further optimizes the code. 90 Among other optimizations, classes and methods that are not entry points 91 can be made private, static, or final, unused parameters can be removed, 92 and some methods may be inlined. 93 94 <li>In the <b>obfuscation step</b>, ProGuard renames classes and class members 95 that are not entry points. In this entire process, keeping the entry 96 points ensures that they can still be accessed by their original names. 97 98 <li>The <b>preverification step</b> is the only step that doesn't have to know 99 the entry points. 100 </ul> 101 <p> 102 The <a href="usage.html">Usage section</a> of this manual describes the 103 necessary <a href="usage.html#keepoptions"><code>-keep</code> options</a> and 104 the <a href="examples.html">Examples section</a> provides plenty of examples. 105 106 <h3>Introspection</h3> 107 108 Introspection presents particular problems for any automatic processing of 109 code. In ProGuard, classes or class members in your code that are created or 110 invoked dynamically (that is, by name) have to be specified as entry points 111 too. For example, <code>Class.forName()</code> constructs may refer to any 112 class at run-time. It is generally impossible to foresee which classes have to 113 be preserved (with their original names), since the class names might be read 114 from a configuration file, for instance. You therefore have to specify them in 115 your ProGuard configuration, with the same simple <code>-keep</code> options. 116 <p> 117 However, ProGuard will already detect and handle the following cases for you: 118 119 <ul> 120 <li><code>Class.forName("SomeClass")</code> 121 <li><code>SomeClass.class</code> 122 <li><code>SomeClass.class.getField("someField")</code> 123 <li><code>SomeClass.class.getDeclaredField("someField")</code> 124 <li><code>SomeClass.class.getMethod("someMethod", new Class[] {})</code> 125 <li><code>SomeClass.class.getMethod("someMethod", new Class[] { A.class })</code> 126 <li><code>SomeClass.class.getMethod("someMethod", new Class[] { A.class, B.class })</code> 127 <li><code>SomeClass.class.getDeclaredMethod("someMethod", new Class[] {})</code> 128 <li><code>SomeClass.class.getDeclaredMethod("someMethod", new Class[] { A.class })</code> 129 <li><code>SomeClass.class.getDeclaredMethod("someMethod", new Class[] { A.class, B.class })</code> 130 </ul> 131 132 The names of the classes and class members may of course be different, but the 133 constructs should be literally the same for ProGuard to recognize them. The 134 referenced classes and class members are preserved in the shrinking phase, and 135 the string arguments are properly replaced in the obfuscation phase. 136 <p> 137 Furthermore, ProGuard will offer some suggestions if keeping some classes or 138 class members appears necessary. For example, ProGuard will note constructs 139 like "<code>(SomeClass)Class.forName(variable).newInstance()</code>". These 140 might be an indication that the class or interface <code>SomeClass</code> 141 and/or its implementations may need to be preserved. You can then adapt your 142 configuration accordingly. 143 <p> 144 For proper results, you should at least be somewhat familiar with the code 145 that you are processing. Obfuscating code that performs a lot of introspection 146 may require trial and error, especially without the necessary information 147 about the internals of the code. 148 <p> 149 150 <hr> 151 <address> 152 Copyright © 2002-2009 153 <a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. 154 </address> 155 </body> 156 </html> 157
