ProGuard FAQ

Frequently Asked Questions

What is shrinking?
What is obfuscation?
What kind of optimizations does ProGuard support?
Can I use ProGuard to process my commercial application?
Does ProGuard work with JDK1.4? JDK5.0? JDK6.0?
Does ProGuard work with J2ME?
Does ProGuard have support for Ant?
Does ProGuard come with a GUI?
Does ProGuard handle Class.forName calls?
Does ProGuard handle resource files?
Does ProGuard encrypt strings constants?
Does ProGuard perform control flow obfuscation?
Does ProGuard support incremental obfuscation?
Can ProGuard obfuscate using reserved keywords?
Can ProGuard reconstruct obfuscated stack traces?

What is shrinking?

Java source code (.java files) is typically compiled to bytecode (.class files). Complete programs or program libraries are usually zipped up and distributed as Java archives (.jar files). Bytecode is more compact than Java source code, but it may still contain a lot of unused code, especially if it uses program libraries. Shrinking programs such as ProGuard can analyze bytecode and remove unused classes, fields, and methods. The program remains functionally equivalent, including the information given in exception stack traces.

What is obfuscation?

By default, compiled bytecode still contains a lot of debugging information: source file names, line numbers, field names, method names, argument names, variable names, etc. This information makes it straightforward to decompile the bytecode and reverse-engineer entire programs. Sometimes, this is not desirable. Obfuscators such as ProGuard can remove the debugging information and replace all names by meaningless character sequences, making it much harder to reverse-engineer the code. It further compacts the code as a bonus. The program remains functionally equivalent, except for the class names, method names, and line numbers given in exception stack traces.

What kind of optimizations does ProGuard support?

Apart from removing unused classes, fields, and methods in the shrinking step, ProGuard can also perform optimizations at the bytecode level, inside methods:

Evaluate constant expressions.
Remove unnecessary field accesses.
Remove unnecessary method calls.
Remove unnecessary branches.
Remove unnecessary comparisons and instanceof tests.
Remove unused code.
Remove write-only fields.
Remove unused method parameters.
Various peephole optimizations like push/pop simplification.
Make classes static and final when possible.
Make methods private, static, and final when possible.
Inline simple getters and setters when possible.
Replace interfaces that have single implementations.
Optionally remove logging code.

The positive effects of these optimizations will depend on your code and on the virtual machine on which the code is executed. Simple virtual machines may benefit more than advanced virtual machines with sophisticated JIT compilers. At the very least, your bytecode may become a bit smaller.

Some notable optimizations that aren't supported yet:

Inlining of constant fields that are not marked as final.
Inlining of other methods than getters and setters.
Moving constant expressions out of loops.
Optimizations that require escape analysis.

Can I use ProGuard to process my commercial application?

Yes, you can. ProGuard itself is distributed under the GPL, but this doesn't affect the programs that you process. Your code remains yours, and its license can remain the same.

Does ProGuard work with JDK1.4? JDK5.0? JDK6.0?

Yes, ProGuard supports all JDKs up to and including 6.0. Class files compiled with JDK1.4 are targeted at JRE1.2 by default. Class files compiled with JDK5.0 may have additional attributes for generics and annotations. The compiled class files have slightly different structures from older class files. ProGuard handles all versions correctly.

The upcoming ProGuard 4.0 supports preverification, which improves the start-up performance in JDK6.0.

Does ProGuard work with J2ME?

Yes. ProGuard itself runs in J2SE, but you can freely specify the run-time environment at which your programs are targeted, including J2ME. For instance, you can specify midpapi20.jar and cldcapi11.jar as the run-time libraries, instead of J2SE's traditional rt.jar. All of ProGuard's powerful configuration options remain available. The example section of the ProGuard User Manual illustrates how to process a single midlet or all midlets in your input jar, for instance.

In addition, ProGuard provides an obfuscator plug-in for the J2ME Wireless Toolkit.

Does ProGuard have support for Ant?

Yes. ProGuard provides an Ant task, so that it integrates seamlessly into your Ant build processes. You can still use configurations in ProGuard's own readable format. Alternatively, if you prefer XML, you can specify the equivalent XML configuration.

Does ProGuard come with a GUI?

Yes. First of all, ProGuard is perfectly usable as a command-line tool that can easily be integrated into any automatic build process. For casual users, there's also a graphical user interface that makes creating, loading, editing, executing, and saving ProGuard configurations a breeze.

Does ProGuard handle `Class.forName` calls?

Yes. ProGuard automatically handles Class.forName("SomeClass") and SomeClass.class constructs. The referenced classes are preserved in the shrinking phase, and the string arguments are properly replaced in the obfuscation phase.

With variable string arguments, it's generally not possible to determine their possible values. They might be read from a configuration file, for instance. However, ProGuard will note constructs like "(SomeClass)Class.forName(variable).newInstance()". These might be an indication that the class or interface SomeClass and/or its implementations may need to be preserved. The user can adapt his configuration accordingly.

Does ProGuard handle resource files?

Yes, in the sense that ProGuard copies all non-class resource files from the given input jars to the output jars. Their names and contents remain unchanged.

Does ProGuard encrypt strings constants?

No. Storing encrypted string constants in program code is fairly futile, since the encryption has to be perfectly reversible by definition. Moreover, the decryption costs additional memory and computation at run-time. If this feature is ever incorporated, I'll provide a tool to decrypt the strings as well.

Does ProGuard perform flow obfuscation?

No. Control obfuscation injects additional branches into the bytecode, in an attempt to fool decompilers. This operation may confuse JIT compilers as well, adversely affecting performance. It may be added as an option in the future, but it doesn't have the highest priority. I will focus mostly on the optimization step, which may already restructure the code to the point where decompilers get confused.

Does ProGuard support incremental obfuscation?

Yes. This feature allows you to specify a previous obfuscation mapping file in a new obfuscation step, in order to produce add-ons or patches for obfuscated code.

Can ProGuard obfuscate using reserved keywords?

Yes. You can specify your own obfuscation dictionary, such as a list of reserved key words, identifiers with foreign characters, random source files, or a text by Shakespeare. Note that this hardly improves the obfuscation. Decent decompilers can automatically replace reserved keywords, and the effect can be undone fairly easily, by obfuscating again with simpler names.

Can ProGuard reconstruct obfuscated stack traces?

Yes. ProGuard comes with a companion tool, ReTrace, that can 'de-obfuscate' stack traces produced by obfuscated applications. The reconstruction is based on the mapping file that ProGuard can write out. If line numbers have been obfuscated away, a list of alternative method names is presented for each obfuscated method name that has an ambiguous reverse mapping. Please refer to the ProGuard User Manual for more details.