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