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