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 46 Java source code (.java files) is typically compiled to bytecode (.class 47 files). Bytecode is more compact than Java source code, but it may still 48 contain a lot of unused code, especially if it includes program libraries. 49 Shrinking programs such as <b>ProGuard</b> can analyze bytecode and remove 50 unused classes, fields, and methods. The program remains functionally 51 equivalent, including the information given in exception stack traces. 52 53 <a name="obfuscation"> </a> 54 <h3>What is obfuscation?</h3> 55 56 By default, compiled bytecode still contains a lot of debugging information: 57 source file names, line numbers, field names, method names, argument names, 58 variable names, etc. This information makes it straightforward to decompile 59 the bytecode and reverse-engineer entire programs. Sometimes, this is not 60 desirable. Obfuscators such as <b>ProGuard</b> can remove the debugging 61 information and replace all names by meaningless character sequences, making 62 it much harder to reverse-engineer the code. It further compacts the code as a 63 bonus. The program remains functionally equivalent, except for the class 64 names, method names, and line numbers given in exception stack traces. 65 66 <a name="preverification"> </a> 67 <h3>What is preverification?</h3> 68 69 When loading class files, the class loader performs some sophisticated 70 verification of the byte code. This analysis makes sure the code can't 71 accidentally or intentionally break out of the sandbox of the virtual machine. 72 Java Micro Edition and Java 6 introduced split verification. This means that 73 the JME preverifier and the Java 6 compiler add preverification information to 74 the class files (StackMap and StackMapTable attributes, respectively), in order 75 to simplify the actual verification step for the class loader. Class files can 76 then be loaded faster and in a more memory-efficient way. <b>ProGuard</b> can 77 perform the preverification step too, for instance allowing to retarget older 78 class files at Java 6. 79 80 <a name="optimization"> </a> 81 <h3>What kind of optimizations does <b>ProGuard</b> support?</h3> 82 83 Apart from removing unused classes, fields, and methods in the shrinking step, 84 <b>ProGuard</b> can also perform optimizations at the bytecode level, inside 85 and across methods. Thanks to techniques like control flow analysis, data flow 86 analysis, partial evaluation, static single assignment, global value numbering, 87 and 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> 109 The positive effects of these optimizations will depend on your code and on 110 the virtual machine on which the code is executed. Simple virtual machines may 111 benefit more than advanced virtual machines with sophisticated JIT compilers. 112 At the very least, your bytecode may become a bit smaller. 113 <p> 114 Some 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 123 Yes, you can. <b>ProGuard</b> itself is distributed under the GPL, but this 124 doesn't affect the programs that you process. Your code remains yours, and 125 its 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 130 Yes, <b>ProGuard</b> supports all JDKs from 1.1 up to and including 6.0. Java 2 131 introduced some small differences in the class file format. Java 5 added 132 attributes for generics and for annotations. Java 6 introduced preverification 133 attributes. <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 138 Yes. <b>ProGuard</b> itself runs in Java Standard Edition, but you can freely 139 specify the run-time environment at which your programs are targeted, 140 including Java Micro Edition. <b>ProGuard</b> then also performs the required 141 preverification, producing more compact results than the traditional external 142 preverifier. 143 <p> 144 <b>ProGuard</b> also comes with an obfuscator plug-in for the JME Wireless 145 Toolkit. 146 147 <a name="android"> </a> 148 <h3>Does <b>ProGuard</b> work for Google Android code?</h3> 149 150 Yes. Google's <code>dx</code> compiler converts ordinary jar files into files 151 that 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 153 performance of the code. 154 155 <a name="blackberry"> </a> 156 <h3>Does <b>ProGuard</b> work for Blackberry code?</h3> 157 158 It should. RIM's proprietary <code>rapc</code> compiler converts ordinary JME 159 jar files into cod files that run on Blackberry devices. The compiler performs 160 quite a few optimizations, but preprocessing the jar files with 161 <b>ProGuard</b> can generally still reduce the final code size by a few 162 percent. However, the <code>rapc</code> compiler also seems to contain some 163 bugs. It sometimes fails on obfuscated code that is valid and accepted by other 164 JME 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 169 Yes. <b>ProGuard</b> provides an Ant task, so that it integrates seamlessly 170 into your Ant build processes. You can still use configurations in 171 <b>ProGuard</b>'s own readable format. Alternatively, if you prefer XML, you 172 can specify the equivalent XML configuration. 173 174 <a name="gui"> </a> 175 <h3>Does <b>ProGuard</b> come with a GUI?</h3> 176 177 Yes. First of all, <b>ProGuard</b> is perfectly usable as a command-line tool 178 that can easily be integrated into any automatic build process. For casual 179 users, there's also a graphical user interface that simplifies creating, 180 loading, 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 185 Yes. <b>ProGuard</b> automatically handles constructs like 186 <code>Class.forName("SomeClass")</code> and <code>SomeClass.class</code>. The 187 referenced classes are preserved in the shrinking phase, and the string 188 arguments are properly replaced in the obfuscation phase. 189 <p> 190 With variable string arguments, it's generally not possible to determine their 191 possible values. They might be read from a configuration file, for instance. 192 However, <b>ProGuard</b> will note a number of constructs like 193 "<code>(SomeClass)Class.forName(variable).newInstance()</code>". These might 194 be an indication that the class or interface <code>SomeClass</code> and/or its 195 implementations may need to be preserved. The user can adapt his configuration 196 accordingly. 197 198 <a name="resource"> </a> 199 <h3>Does <b>ProGuard</b> handle resource files?</h3> 200 201 Yes. <b>ProGuard</b> copies all non-class resource files, optionally adapting 202 their 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 207 No. Storing encrypted string constants in program code is fairly futile, since 208 the encryption has to be perfectly reversible by definition. Moreover, the 209 decryption costs additional memory and computation at run-time. If this feature 210 is 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 215 Not explicitly. Control flow obfuscation injects additional branches into the 216 bytecode, in an attempt to fool decompilers. <b>ProGuard</b> does not do this, 217 in order to avoid any negative effects on performance and size. However, the 218 optimization step often already restructures the code to the point where most 219 decompilers get confused. 220 221 <a name="incremental"> </a> 222 <h3>Does <b>ProGuard</b> support incremental obfuscation?</h3> 223 224 Yes. This feature allows you to specify a previous obfuscation mapping file in 225 a new obfuscation step, in order to produce add-ons or patches for obfuscated 226 code. 227 228 <a name="keywords"> </a> 229 <h3>Can <b>ProGuard</b> obfuscate using reserved keywords?</h3> 230 231 Yes. You can specify your own obfuscation dictionary, such as a list of 232 reserved key words, identifiers with foreign characters, random source files, 233 or a text by Shakespeare. Note that this hardly improves the obfuscation. 234 Decent decompilers can automatically replace reserved keywords, and the effect 235 can 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 240 Yes. <b>ProGuard</b> comes with a companion tool, <b>ReTrace</b>, that can 241 'de-obfuscate' stack traces produced by obfuscated applications. The 242 reconstruction is based on the mapping file that <b>ProGuard</b> can write 243 out. If line numbers have been obfuscated away, a list of alternative method 244 names is presented for each obfuscated method name that has an ambiguous 245 reverse mapping. Please refer to the <a href="manual/index.html">ProGuard User 246 Manual</a> for more details. 247 248 <hr> 249 <address> 250 Copyright © 2002-2009 251 <a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. 252 </address> 253 </body> 254 </html> 255
