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