Usage

java -jar proguard.jar options ...

java -jar proguard.jar @myconfig.pro

java -jar proguard.jar @myconfig.pro -verbose

You can add comments in a configuration file, starting with a # character and continuing until the end of the line.

Extra whitespace between words and delimiters is ignored. File names with spaces or special characters should be quoted with single or double quotes.

Options can be grouped arbitrarily in arguments on the command line and in lines in configuration files. This means that you can quote arbitrary sections of command line options, to avoid shell expansion of special characters, for instance.

The order of the options is generally irrelevant. For quick experiments, you can abbreviate them to their first unique characters.

The sections below provide more details:

• Input/Output Options
• Keep Options
• Shrinking Options
• Optimization Options
• Obfuscation Options
• Preverification Options
• General Options
• Class Paths
• File Names
• File Filters
• Filters
• Overview of Keep Options
• Keep Option Modifiers
• Class Specifications

Input/Output Options

You must avoid letting the output files overwrite any input files. For better readability, class path entries can be specified using multiple -outjars options. Without any -outjarsoptions, no jars will be written.

Please note that the boot path and the class path set for running ProGuard are not considered when looking for library classes. This means that you explicitly have to specify the run-time jar that your code will use. Although this may seem cumbersome, it allows you to process applications targeted at different run-time environments. For example, you can process J2SE applications as well as JME midlets, just by specifying the appropriate run-time jar.

Keep Options

Specifies classes and class members whose names are to be preserved, if they aren‘t removed in the shrinking phase. For example, you may want to keep all class names of classes that implement the Serializable interface, so that the processed code remains compatible with any originally serialized classes. Classes that aren‘t used at all can still be removed. Only applicable when obfuscating.

Specifies class members whose names are to be preserved, if they aren‘t removed in the shrinking phase. For example, you may want to preserve the name of the syntheticclass$ methods when processing a library compiled by JDK 1.2 or older, so obfuscators can detect it again when processing an application that uses the processed library (although ProGuard itself doesn‘t need this). Only applicable when obfuscating.

Specifies classes and class members whose names are to be preserved, on the condition that all of the specified class members are present after the shrinking phase. For example, you may want to keep all native method names and the names of their classes, so that the processed code can still link with the native library code. Native methods that aren‘t used at all can still be removed. If a class file is used, but none of its native methods are, its name will still be obfuscated. Only applicable when obfuscating.

Shrinking Options

Optimization Options

Counter-indication: you probably shouldn‘t use this option when processing code that is to be used as a library, since classes and class members that weren‘t designed to be public in the API may become public.

Counter-indication: setting this option can reduce the performance of the processed code on some JVMs, since advanced just-in-time compilation tends to favor more interfaces with fewer implementing classes. Worse, some JVMs may not be able to handle the resulting code. Notably:

• Sun‘s JRE 1.3 may throw an InternalError when encountering more than 256 Miranda methods (interface methods without implementations) in a class.

Obfuscation Options

Counter-indication: the resulting class files fall within the Java bytecode specification (cfr. The Java Virtual Machine Specification, Second Edition, first paragraphs of Section 4.5and Section 4.6), even though this kind of overloading is not allowed in the Java language (cfr. The Java Language Specification, Second Edition, Section 8.3 and Section 8.4.7). Still, some tools have problems with it. Notably:

• Sun‘s JDK 1.2.2 javac compiler produces an exception when compiling with such a library (cfr. Bug #4216736). You probably shouldn‘t use this option for processing libraries.
• Sun‘s JRE 1.4 and later fail to serialize objects with overloaded primitive fields.
• Sun‘s JRE 1.5 pack200 tool reportedly has problems with overloaded class members.
• Google‘s Dalvik VM can‘t handle overloaded static fields.

For instance, consider two distinct interfaces containing methods with the same name and signature. Without this option, these methods may get different obfuscated names in a first obfuscation step. If a patch is then added containing a class that implements both interfaces, ProGuard will have to enforce the same method name for both methods in an incremental obfuscation step. The original obfuscated code is changed, in order to keep the resulting code consistent. With this option in the initial obfuscation step, such renaming will never be necessary.

This option is only applicable when obfuscating. In fact, if you are planning on performing incremental obfuscation, you probably want to avoid shrinking and optimization altogether, since these steps could remove or modify parts of your code that are essential for later additions.

Counter-indication: classes that look for resource files in their package directories will no longer work properly if they are moved elsewhere. When in doubt, just leave the packaging untouched by not using this option.

Preverification Options

General Options

Class Paths

Each input entry can be:

• A class file or resource file,
• A jar file, containing any of the above,
• A war file, containing any of the above,
• An ear file, containing any of the above,
• A zip file, containing any of the above,
• A directory (structure), containing any of the above.

The paths of directly specified class files and resource files is ignored, so class files should generally be part of a jar file, a war file, an ear file, a zip file, or a directory. In addition, the paths of class files should not have any additional directory prefixes inside the archives or directories.

Each output entry can be:

• A jar file, in which all processed class files and resource files will be collected.
• A war file, in which any and all of the above will be collected,
• An ear file, in which any and all of the above will be collected,
• A zip file, in which any and all of the above will be collected,
• A directory, in which any and all of the above will be collected.

When writing output entries, ProGuard will generally package the results in a sensible way, reconstructing the input entries as much as required. Writing everything to an output directory is the most straightforward option: the output directory will contain a complete reconstruction of the input entries. The packaging can be almost arbitrarily complex though: you could process an entire application, packaged in a zip file along with its documentation, writing it out as a zip file again. The Examples section shows a few ways to restructure output archives.

Files and directories can be specified as discussed in the section on file names below.

In addition, ProGuard provides the possibility to filter the class path entries and their contents, based on their full relative file names. Each class path entry can be followed by up to 5 types of file filters between parentheses, separated by semi-colons:

• A filter for all zip names that are encountered,
• A filter for all ear names that are encountered,
• A filter for all war names that are encountered,
• A filter for all jar names that are encountered,
• A filter for all class file names and resource file names that are encountered.

If fewer than 5 filters are specified, they are assumed to be the latter filters. Any empty filters are ignored. More formally, a filtered class path entry looks like this:

classpathentry([[[[zipfilter;]earfilter;]warfilter;]jarfilter;]filefilter)

Square brackets "[]" mean that their contents are optional.

For example, "rt.jar(java/**.class,javax/**.class)" matches all class files in the java and javax directories inside the rt jar.

For example, "input.jar(!**.gif,images/**)" matches all files in the images directory inside the input jar, except gif files.

Note that the different filters are applied to all corresponding file types, irrespective of their nesting levels in the input; they are orthogonal.

For example, "input.war(lib/**.jar,support/**.jar;**.class,**.gif)" only considers jar files in the lib and support directories in the input war, not any other jar files. It then matches all class files and gif files that are encountered.

The filters allow for an almost infinite number of packaging and repackaging possibilities. The Examples section provides a few more examples for filtering input and output.

File Names

• relative to the base directory, if set, or otherwise
• relative to the configuration file in which it is specified, if any, or otherwise
• relative to the working directory.

The names can contain Java system properties delimited by ‘<‘ and ‘>‘. The system properties are automatically replaced by their respective values.

For example, <java.home>/lib/rt.jar will automatically be expanded to something like /usr/local/java/jdk/jre/lib/rt.jar. Similarly, <user.home> will be expanded to the user‘s home directory, and<user.dir> will be expanded to the current working directory.

Names with special characters like spaces and parentheses must be quoted with single or double quotes. Note that each file name in a list of names has to be quoted individually. Also note that the quotes themselves may need to be escaped when used on the command line, to avoid them being gobbled by the shell.

For example, on the command line, you could use an option like ‘-injars "my program.jar":"/your directory/your program.jar"‘.

File Filters

Furthermore, a file name can be preceded by an exclamation mark ‘!‘ to exclude the file name from further attempts to match with subsequent file names.

For example, "!**.gif,images/**" matches all files in the images directory, except gif files.

The Examples section provides a few more examples for filtering input and output.

Filters

A filter is a list of comma-separated names that can contain wildcards. Only names that match an item on the list pass the filter. The supported wildcards depend on the type of names for which the filter is being used, but the following wildcards are typical:

For example, "foo,*bar" matches the name foo and all names ending with bar.

Furthermore, a name can be preceded by a negating exclamation mark ‘!‘ to exclude the name from further attempts to match with subsequent names. So, if a name matches an item in the filter, it is accepted or rejected right away, depending on whether the item has a negator. If the name doesn‘t match the item, it is tested against the next item, and so on. It if doesn‘t match any items, it is accepted or rejected, depending on the whether the last item has a negator or not.

For example, "!foobar,*bar" matches all names ending with bar, except foobar.

Overview of Keep Options

Each of these -keep options is of course followed by a specification of the classes and class members (fields and methods) to which it should be applied.

If you‘re not sure which option you need, you should probably simply use -keep. It will make sure the specified classes and class members are not removed in the shrinking step, and not renamed in the obfuscation step.

Always remember: Specifying a class without class members only preserves the class as an entry point — any class members may then still be removed, optimized, or obfuscated. Specifying a class member only preserves the class member as an entry point — any associated code may still be optimized and adapted.

Keep Option Modifiers

Class Specifications

The template was designed to look very Java-like, with some extensions for wildcards. To get a feel for the syntax, you should probably look at the examples, but this is an attempt at a complete formal definition:

[@annotationtype] [[!]public|final|abstract|@ ...] [!]interface|class|enum classname [extends|implements [@annotationtype] classname]
[{ [@annotationtype] [[!]public|private|protected|static|volatile|transient ...] <fields> |
                                                                      (fieldtype fieldname); [@annotationtype] [[!]public|private|protected|static|synchronized|native|abstract|strictfp ...] <methods> | <init>(argumenttype,...) | classname(argumenttype,...) |
                                                                                           (returntype methodname(argumenttype,...)); [@annotationtype] [[!]public|private|protected|static ... ] *; ... }]

Square brackets "[]" mean that their contents are optional. Ellipsis dots "..." mean that any number of the preceding items may be specified. A vertical bar "|" delimits two alternatives. Non-bold parentheses "()" just group parts of the specification that belong together. The indentation tries to clarify the intended meaning, but white-space is irrelevant in actual configuration files.

• The class keyword refers to any interface or class. The interface keyword restricts matches to interface classes. The enum keyword restricts matches to enumeration classes. Preceding the interface or enum keywords by a ! restricts matches to classes that are not interfaces or enumerations, respectively.
• Every classname must be fully qualified, e.g. java.lang.String. Class names may be specified as regular expressions containing the following wildcards:

  ?	matches any single character in a class name, but not the package separator. For example, "mypackage.Test?" matches "mypackage.Test1" and "mypackage.Test2", but not "mypackage.Test12".
  *	matches any part of a class name not containing the package separator. For example, "mypackage.*Test*" matches "mypackage.Test" and "mypackage.YourTestApplication", but not "mypackage.mysubpackage.MyTest". Or, more generally, "mypackage.*" matches all classes in "mypackage", but not in its subpackages.
  **	matches any part of a class name, possibly containing any number of package separators. For example, "**.Test" matches all Test classes in all packages except the root package. Or, "mypackage.**" matches all classes in "mypackage" and in its subpackages.

  For additional flexibility, class names can actually be comma-separated lists of class names, with optional ! negators, just like file name filters. This notation doesn‘t look very Java-like, so it should be used with moderation.

  For convenience and for backward compatibility, the class name * refers to any class, irrespective of its package.

• The extends and implements specifications are typically used to restrict classes with wildcards. They are currently equivalent, specifying that only classes extending or implementing the given class qualify. Note that the given class itself is not included in this set. If required, it should be specified in a separate option.
• The @ specifications can be used to restrict classes and class members to the ones that are annotated with the specified annotation types. An annotationtype is specified just like a classname.
• Fields and methods are specified much like in Java, except that method argument lists don‘t contain argument names (just like in other tools like javadoc and javap). The specifications can also contain the following catch-all wildcards:

  <init>	matches any constructor.
  <fields>	matches any field.
  <methods>	matches any method.
  *	matches any field or method.

  Note that the above wildcards don‘t have return types. Only the <init> wildcard has an argument list.

  Fields and methods may also be specified using regular expressions. Names can contain the following wildcards:

  ?	matches any single character in a method name.
  *	matches any part of a method name.

  Types in descriptors can contain the following wildcards:

  %	matches any primitive type ("boolean", "int", etc, but not "void").
  ?	matches any single character in a class name.
  *	matches any part of a class name not containing the package separator.
  **	matches any part of a class name, possibly containing any number of package separators.
  ***	matches any type (primitive or non-primitive, array or non-array).
  ...	matches any number of arguments of any type.

  Note that the ?, *, and ** wildcards will never match primitive types. Furthermore, only the *** wildcards will match array types of any dimension. For example, "** get*()" matches "java.lang.Object getObject()", but not "float getFloat()", nor "java.lang.Object[] getObjects()".

• Constructors can also be specified using their short class names (without package) or using their full class names. As in the Java language, the constructor specification has an argument list, but no return type.
• The class access modifiers and class member access modifiers are typically used to restrict wildcarded classes and class members. They specify that the corresponding access flags have to be set for the member to match. A preceding ! specifies that the corresponding access flag should be unset.

  Combining multiple flags is allowed (e.g. public static). It means that both access flags have to be set (e.g. public and static), except when they are conflicting, in which case at least one of them has to be set (e.g. at least public or protected).

  ProGuard supports the additional modifiers synthetic, bridge, and varargs, which may be set by compilers.

proguard usage