• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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     ...&lt;&lt;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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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 &copy; 2002-2009
251 <a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>.
252 </address>
253 </body>
254 </html>
255