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 FAQ</title> 8</head> 9<body> 10 11<h2>Frequently Asked Questions</h2> 12 13<h3>Contents</h3> 14 15<ol> 16<li><a href="#shrinking">What is shrinking?</a> 17<li><a href="#obfuscation">What is obfuscation?</a> 18<li><a href="#preverification">What is preverification?</a> 19<li><a href="#optimization">What kind of optimizations does <b>ProGuard</b> 20 support?</a> 21<li><a href="#commercial">Can I use <b>ProGuard</b> to process my commercial 22 application?</a> 23<li><a href="#jdk1.4">Does <b>ProGuard</b> work with Java 2? Java 5? Java 24 6?</a> 25<li><a href="#jme">Does <b>ProGuard</b> work with Java Micro Edition?</a> 26<li><a href="#android">Does <b>ProGuard</b> work for Google Android code?</a> 27<li><a href="#blackberry">Does <b>ProGuard</b> work for Blackberry code?</a> 28<li><a href="#ant">Does <b>ProGuard</b> have support for Ant?</a> 29<li><a href="#gui">Does <b>ProGuard</b> come with a GUI?</a> 30<li><a href="#forname">Does <b>ProGuard</b> handle <code>Class.forName</code> 31 calls?</a> 32<li><a href="#resource">Does <b>ProGuard</b> handle resource files?</a> 33<li><a href="#encrypt">Does <b>ProGuard</b> encrypt strings constants?</a> 34<li><a href="#flow">Does <b>ProGuard</b> perform control flow obfuscation?</a> 35<li><a href="#incremental">Does <b>ProGuard</b> support incremental 36 obfuscation?</a> 37<li><a href="#keywords">Can <b>ProGuard</b> obfuscate using reserved 38 keywords?</a> 39<li><a href="#stacktrace">Can <b>ProGuard</b> reconstruct obfuscated stack 40 traces?</a> 41</ol> 42 43<a name="shrinking"> </a> 44<h3>What is shrinking?</h3> 45 46Java source code (.java files) is typically compiled to bytecode (.class 47files). Bytecode is more compact than Java source code, but it may still 48contain a lot of unused code, especially if it includes program libraries. 49Shrinking programs such as <b>ProGuard</b> can analyze bytecode and remove 50unused classes, fields, and methods. The program remains functionally 51equivalent, including the information given in exception stack traces. 52 53<a name="obfuscation"> </a> 54<h3>What is obfuscation?</h3> 55 56By default, compiled bytecode still contains a lot of debugging information: 57source file names, line numbers, field names, method names, argument names, 58variable names, etc. This information makes it straightforward to decompile 59the bytecode and reverse-engineer entire programs. Sometimes, this is not 60desirable. Obfuscators such as <b>ProGuard</b> can remove the debugging 61information and replace all names by meaningless character sequences, making 62it much harder to reverse-engineer the code. It further compacts the code as a 63bonus. The program remains functionally equivalent, except for the class 64names, method names, and line numbers given in exception stack traces. 65 66<a name="preverification"> </a> 67<h3>What is preverification?</h3> 68 69When loading class files, the class loader performs some sophisticated 70verification of the byte code. This analysis makes sure the code can't 71accidentally or intentionally break out of the sandbox of the virtual machine. 72Java Micro Edition and Java 6 introduced split verification. This means that 73the JME preverifier and the Java 6 compiler add preverification information to 74the class files (StackMap and StackMapTable attributes, respectively), in order 75to simplify the actual verification step for the class loader. Class files can 76then be loaded faster and in a more memory-efficient way. <b>ProGuard</b> can 77perform the preverification step too, for instance allowing to retarget older 78class files at Java 6. 79 80<a name="optimization"> </a> 81<h3>What kind of optimizations does <b>ProGuard</b> support?</h3> 82 83Apart from removing unused classes, fields, and methods in the shrinking step, 84<b>ProGuard</b> can also perform optimizations at the bytecode level, inside 85and across methods. Thanks to techniques like control flow analysis, data flow 86analysis, partial evaluation, static single assignment, global value numbering, 87and liveness analysis, <b>ProGuard</b> can: 88 89<ul> 90<li>Evaluate constant expressions. 91<li>Remove unnecessary field accesses and method calls. 92<li>Remove unnecessary branches. 93<li>Remove unnecessary comparisons and instanceof tests. 94<li>Remove unused code blocks. 95<li>Merge identical code blocks. 96<li>Reduce variable allocation. 97<li>Remove write-only fields and unused method parameters. 98<li>Inline constant fields, method parameters, and return values. 99<li>Inline methods that are short or only called once. 100<li>Simplify tail recursion calls. 101<li>Merge classes and interfaces. 102<li>Make methods private, static, and final when possible. 103<li>Make classes static and final when possible. 104<li>Replace interfaces that have single implementations. 105<li>Perform over 200 peephole optimizations, like replacing ...*2 by 106 ...<<1. 107<li>Optionally remove logging code. 108</ul> 109The positive effects of these optimizations will depend on your code and on 110the virtual machine on which the code is executed. Simple virtual machines may 111benefit more than advanced virtual machines with sophisticated JIT compilers. 112At the very least, your bytecode may become a bit smaller. 113<p> 114Some notable optimizations that aren't supported yet: 115<ul> 116<li>Moving constant expressions out of loops. 117<li>Optimizations that require escape analysis. 118</ul> 119 120<a name="commercial"> </a> 121<h3>Can I use <b>ProGuard</b> to process my commercial application?</h3> 122 123Yes, you can. <b>ProGuard</b> itself is distributed under the GPL, but this 124doesn't affect the programs that you process. Your code remains yours, and 125its license can remain the same. 126 127<a name="jdk1.4"> </a> 128<h3>Does <b>ProGuard</b> work with Java 2? Java 5? Java 6?</h3> 129 130Yes, <b>ProGuard</b> supports all JDKs from 1.1 up to and including 6.0. Java 2 131introduced some small differences in the class file format. Java 5 added 132attributes for generics and for annotations. Java 6 introduced preverification 133attributes. <b>ProGuard</b> handles all versions correctly. 134 135<a name="jme"> </a> 136<h3>Does <b>ProGuard</b> work with Java Micro Edition?</h3> 137 138Yes. <b>ProGuard</b> itself runs in Java Standard Edition, but you can freely 139specify the run-time environment at which your programs are targeted, 140including Java Micro Edition. <b>ProGuard</b> then also performs the required 141preverification, producing more compact results than the traditional external 142preverifier. 143<p> 144<b>ProGuard</b> also comes with an obfuscator plug-in for the JME Wireless 145Toolkit. 146 147<a name="android"> </a> 148<h3>Does <b>ProGuard</b> work for Google Android code?</h3> 149 150Yes. Google's <code>dx</code> compiler converts ordinary jar files into files 151that run on Android devices. By preprocessing the original jar files, 152<b>ProGuard</b> can significantly reduce the file sizes and boost the run-time 153performance of the code. 154 155<a name="blackberry"> </a> 156<h3>Does <b>ProGuard</b> work for Blackberry code?</h3> 157 158It should. RIM's proprietary <code>rapc</code> compiler converts ordinary JME 159jar files into cod files that run on Blackberry devices. The compiler performs 160quite a few optimizations, but preprocessing the jar files with 161<b>ProGuard</b> can generally still reduce the final code size by a few 162percent. However, the <code>rapc</code> compiler also seems to contain some 163bugs. It sometimes fails on obfuscated code that is valid and accepted by other 164JME tools and VMs. Your mileage may therefore vary. 165 166<a name="ant"> </a> 167<h3>Does <b>ProGuard</b> have support for Ant?</h3> 168 169Yes. <b>ProGuard</b> provides an Ant task, so that it integrates seamlessly 170into your Ant build processes. You can still use configurations in 171<b>ProGuard</b>'s own readable format. Alternatively, if you prefer XML, you 172can specify the equivalent XML configuration. 173 174<a name="gui"> </a> 175<h3>Does <b>ProGuard</b> come with a GUI?</h3> 176 177Yes. First of all, <b>ProGuard</b> is perfectly usable as a command-line tool 178that can easily be integrated into any automatic build process. For casual 179users, there's also a graphical user interface that simplifies creating, 180loading, editing, executing, and saving ProGuard configurations. 181 182<a name="forname"> </a> 183<h3>Does <b>ProGuard</b> handle <code>Class.forName</code> calls?</h3> 184 185Yes. <b>ProGuard</b> automatically handles constructs like 186<code>Class.forName("SomeClass")</code> and <code>SomeClass.class</code>. The 187referenced classes are preserved in the shrinking phase, and the string 188arguments are properly replaced in the obfuscation phase. 189<p> 190With variable string arguments, it's generally not possible to determine their 191possible values. They might be read from a configuration file, for instance. 192However, <b>ProGuard</b> will note a number of constructs like 193"<code>(SomeClass)Class.forName(variable).newInstance()</code>". These might 194be an indication that the class or interface <code>SomeClass</code> and/or its 195implementations may need to be preserved. The user can adapt his configuration 196accordingly. 197 198<a name="resource"> </a> 199<h3>Does <b>ProGuard</b> handle resource files?</h3> 200 201Yes. <b>ProGuard</b> copies all non-class resource files, optionally adapting 202their names and their contents to the obfuscation that has been applied. 203 204<a name="encrypt"> </a> 205<h3>Does <b>ProGuard</b> encrypt strings constants?</h3> 206 207No. Storing encrypted string constants in program code is fairly futile, since 208the encryption has to be perfectly reversible by definition. Moreover, the 209decryption costs additional memory and computation at run-time. If this feature 210is ever incorporated, I'll provide a tool to decrypt the strings as well. 211 212<a name="flow"> </a> 213<h3>Does <b>ProGuard</b> perform flow obfuscation?</h3> 214 215Not explicitly. Control flow obfuscation injects additional branches into the 216bytecode, in an attempt to fool decompilers. <b>ProGuard</b> does not do this, 217in order to avoid any negative effects on performance and size. However, the 218optimization step often already restructures the code to the point where most 219decompilers get confused. 220 221<a name="incremental"> </a> 222<h3>Does <b>ProGuard</b> support incremental obfuscation?</h3> 223 224Yes. This feature allows you to specify a previous obfuscation mapping file in 225a new obfuscation step, in order to produce add-ons or patches for obfuscated 226code. 227 228<a name="keywords"> </a> 229<h3>Can <b>ProGuard</b> obfuscate using reserved keywords?</h3> 230 231Yes. You can specify your own obfuscation dictionary, such as a list of 232reserved key words, identifiers with foreign characters, random source files, 233or a text by Shakespeare. Note that this hardly improves the obfuscation. 234Decent decompilers can automatically replace reserved keywords, and the effect 235can be undone fairly easily, by obfuscating again with simpler names. 236 237<a name="stacktrace"> </a> 238<h3>Can <b>ProGuard</b> reconstruct obfuscated stack traces?</h3> 239 240Yes. <b>ProGuard</b> comes with a companion tool, <b>ReTrace</b>, that can 241'de-obfuscate' stack traces produced by obfuscated applications. The 242reconstruction is based on the mapping file that <b>ProGuard</b> can write 243out. If line numbers have been obfuscated away, a list of alternative method 244names is presented for each obfuscated method name that has an ambiguous 245reverse mapping. Please refer to the <a href="manual/index.html">ProGuard User 246Manual</a> for more details. 247 248<hr> 249<address> 250Copyright © 2002-2009 251<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. 252</address> 253</body> 254</html> 255