ProGuard Introduction

Introduction

ProGuard is a Java class file shrinker, optimizer, obfuscator, and preverifier. The shrinking step detects and removes unused classes, fields, methods, and attributes. The optimization step analyzes and optimizes the bytecode of the methods. The obfuscation step renames the remaining classes, fields, and methods using short meaningless names. These first steps make the code base smaller, more efficient, and harder to reverse-engineer. The final preverification step adds preverification information to the classes, which is required for Java Micro Edition or which improves the start-up time for Java 6.

Each of these steps is optional. For instance, ProGuard can also be used to just list dead code in an application, or to preverify class files for efficient use in Java 6.

Input jars

Shrunk code

Optim. code Output jars

- shrink → - optimize → - obfuscate → Obfusc. code - preverify →

Library jars ------------------------------- (unchanged) -------------------------------→ Library jars

ProGuard typically reads the input jars (or wars, ears, zips, or directories). It then shrinks, optimizes, obfuscates, and preverifies them. Optionally, multiple optimization passes can be performed, each typically followed by another shrinking step. ProGuard writes the processed results to one or more output jars (or wars, ears, zips, or directories). The input may contain resource files, whose names and contents can optionally be updated to reflect the obfuscated class names.

ProGuard requires the library jars (or wars, ears, zips, or directories) of the input jars to be specified. These are essentially the libraries that you would need for compiling the code. ProGuard uses them to reconstruct the class dependencies that are necessary for proper processing. The library jars themselves always remain unchanged. You should still put them in the class path of your final application.

In order to determine which code has to be preserved and which code can be discarded or obfuscated, you have to specify one or more entry points to your code. These entry points are typically classes with main methods, applets, midlets, etc.

In the shrinking step, ProGuard starts from these seeds and recursively determines which classes and class members are used. All other classes and class members are discarded.
In the optimization step, ProGuard further optimizes the code. Among other optimizations, classes and methods that are not entry points can be made private, static, or final, unused parameters can be removed, and some methods may be inlined.
In the obfuscation step, ProGuard renames classes and class members that are not entry points. In this entire process, keeping the entry points ensures that they can still be accessed by their original names.
The preverification step is the only step that doesn't have to know the entry points.

The Usage section of this manual describes the necessary -keep options and the Examples section provides plenty of examples.

Introspection

Introspection presents particular problems for any automatic processing of code. In ProGuard, classes or class members in your code that are created or invoked dynamically (that is, by name) have to be specified as entry points too. For example, Class.forName() constructs may refer to any class at run-time. It is generally impossible to foresee which classes have to be preserved (with their original names), since the class names might be read from a configuration file, for instance. You therefore have to specify them in your ProGuard configuration, with the same simple -keep options.

However, ProGuard will already detect and handle the following cases for you:

Class.forName("SomeClass")
SomeClass.class
SomeClass.class.getField("someField")
SomeClass.class.getDeclaredField("someField")
SomeClass.class.getMethod("someMethod", new Class[] {})
SomeClass.class.getMethod("someMethod", new Class[] { A.class })
SomeClass.class.getMethod("someMethod", new Class[] { A.class, B.class })
SomeClass.class.getDeclaredMethod("someMethod", new Class[] {})
SomeClass.class.getDeclaredMethod("someMethod", new Class[] { A.class })
SomeClass.class.getDeclaredMethod("someMethod", new Class[] { A.class, B.class })

The names of the classes and class members may of course be different, but the constructs should be literally the same for ProGuard to recognize them. The referenced classes and class members are preserved in the shrinking phase, and the string arguments are properly replaced in the obfuscation phase.

Furthermore, ProGuard will offer some suggestions if keeping some classes or class members appears necessary. For example, 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. You can then adapt your configuration accordingly.

For proper results, you should at least be somewhat familiar with the code that you are processing. Obfuscating code that performs a lot of introspection may require trial and error, especially without the necessary information about the internals of the code.

Input jars
		Shrunk code
				Optim. code				Output jars
	- shrink →		- optimize →		- obfuscate →	Obfusc. code	- preverify →
Library jars	------------------------------- (unchanged) -------------------------------→							Library jars