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