examples
directory of the ProGuard distribution.
proguard.pro
and then type:
java -jar proguard.jar @proguard.pro
The configuration file would contain the following options:
-injars proguard.jar -outjars proguard_out.jar -libraryjars <java.home>/lib/rt.jar -printmapping proguard.map -overloadaggressively -defaultpackage '' -allowaccessmodification -keep public class proguard.ProGuard { public static void main(java.lang.String[]); }
Note the use of the <java.home>
system property; it is
replaced automatically.
Also note that the type names are fully specified:
proguard.ProGuard
and java.lang.String[]
.
The access modifiers public
and static
are not
really required in this case, since we know a priori that the specified class
and method have the proper access flags. It just looks more familiar this way.
We're using the -overloadaggressively
,
-defaultpackage
, and -allowaccessmodification
options to shave off some extra bytes, but we could leave them out as well.
The -defaultpackage
directive moves all classes to the given package, in this case the root
package. Only proguard.ProGuard
keeps its original name.
We're writing out an obfuscation mapping file with -printmapping
, for
de-obfuscating any stack traces later on, or for incremental obfuscation of
extensions.
In general, you might need a few additional directives for processing native methods, enumerations, serializable classes, or bean classes. For processing 'simple' applications like ProGuard, that is not required.
mypackage.MyApplet
:
-injars in.jar -outjars out.jar -libraryjars <java.home>/lib/rt.jar -keep public class mypackage.MyApplet
The typical applet methods will be preserved automatically, since
mypackage.MyApplet
is an extension of the Applet
class in the library rt.jar
.
If applicable, you should add directives for processing native methods, enumerations, serializable classes, or bean classes.
mypackage.MyMIDlet
:
-injars in.jar -outjars out.jar -libraryjars /usr/local/java/wtk2.1/lib/midpapi20.jar -libraryjars /usr/local/java/wtk2.1/lib/cldcapi11.jar -overloadaggressively -defaultpackage '' -allowaccessmodification -keep public class mypackage.MyMIDlet
Note how we're now targeting the J2ME run-time environment of
midpapi20.jar
and cldcapi11.jar
, instead of the J2SE
run-time environment rt.jar
. You can target other J2ME
environments by picking the appropriate jars.
The typical midlet methods will be preserved automatically, since
mypackage.MyMIDlet
is an extension of the MIDlet
class in the library midpapi20.jar
.
If applicable, you should add directives for processing native methods, enumerations, serializable classes, or bean classes.
You must preverify your midlets after having processed them, using
J2ME's preverify
tool. Because this tool unpacks your processed
jars, you should use ProGuard's -dontusemixedcaseclassnames
option on platforms with case-insensitive filing systems, such as Windows.
Please note the in-depth article "Obfuscating MIDlet Suites with ProGuard" at developers.sun.com.
in.jar
:
-injars in.jar -outjars out.jar -libraryjars <java.home>/lib/rt.jar -printseeds -keepclasseswithmembers public class * { public static void main(java.lang.String[]); }
Note the use of -keepclasseswithmembers
.
We don't want to preserve all classes, just all classes that have main
methods, and those methods.
The -printseeds
option prints
out which classes exactly will be preserved, so we know for sure we're getting
what we want.
If applicable, you should add directives for processing native methods, enumerations, serializable classes, or bean classes.
in.jar
:
-injars in.jar -outjars out.jar -libraryjars <java.home>/lib/rt.jar -printseeds -keep public class * extends java.applet.Applet
We're simply keeping all classes that extend the Applet
class.
Again, the -printseeds
option
prints out which applets exactly will be preserved.
If applicable, you should add directives for processing native methods, enumerations, serializable classes, or bean classes.
in.jar
:
-injars in.jar -outjars out.jar -libraryjars /usr/local/java/wtk2.1/lib/midpapi20.jar -libraryjars /usr/local/java/wtk2.1/lib/cldcapi11.jar -overloadaggressively -defaultpackage '' -allowaccessmodification -printseeds -keep public class * extends javax.microedition.midlet.MIDlet
We're simply keeping all classes that extend the MIDlet
class.
And again, the -printseeds
option prints out which midlets exactly will be preserved.
If applicable, you should add directives for processing native methods, enumerations, serializable classes, or bean classes.
You must preverify your midlets after having processed them, using
J2ME's preverify
tool. Because this tool unpacks your processed
jars, you should use ProGuard's -dontusemixedcaseclassnames
option on platforms with case-insensitive filing systems, such as Windows.
in.jar
:
-injars in.jar -outjars out.jar -libraryjars <java.home>/lib/rt.jar -libraryjars /usr/local/java/servlet/servlet.jar -printseeds -keep public class * implements javax.servlet.Servlet
Keeping all servlets is very similar to keeping all applets. The servlet API is not part of the standard run-time jar, so we're specifying it as a library. Don't forget to use the right path name.
We're then keeping all classes that implement the Servlet
interface. We're using the implements
keyword because it looks
more familiar in this context, but it is equivalent to extends
,
as far as ProGuard is concerned.
And again, the -printseeds
option prints out which servlets exactly will be preserved.
If applicable, you should add directives for processing native methods, enumerations, serializable classes, or bean classes.
-injars in.jar -outjars out.jar -libraryjars <java.home>/lib/rt.jar -printmapping out.map -renamesourcefileattribute SourceFile -keepattributes InnerClasses,SourceFile,LineNumberTable,Deprecated, Signature,*Annotation*,EnclosingMethod -keep public class * { public protected *; } -keepclassmembernames class * { java.lang.Class class$(java.lang.String); java.lang.Class class$(java.lang.String, boolean); } -keepclasseswithmembernames class * { native <methods>; } -keepclassmembers class * extends java.lang.Enum { public static **[] values(); public static ** valueOf(java.lang.String); } -keepclassmembers class * implements java.io.Serializable { static final long serialVersionUID; private void writeObject(java.io.ObjectOutputStream); private void readObject(java.io.ObjectInputStream); java.lang.Object writeReplace(); java.lang.Object readResolve(); }
This configuration should preserve everything we'll ever want to access in the
library. Only if there are any other non-public classes or methods that are
invoked dynamically, they should be specified using additional -keep
directives.
The -keepclassmembernames
directive for the class$
methods is not strictly necessary. These
methods are inserted by the javac
compiler and the
jikes
compiler respectively, to implement the .class
construct. ProGuard will automatically detect them and deal with them, even
when their names have been obfuscated. However, older versions of ProGuard and
other obfuscators may rely on the original method names. It may therefore be
helpful to preserve them, in case these other obfuscators are ever used for
further obfuscation of the library.
We've added some directives for keeping the "Deprecated" attribute, for producing useful stack traces, and for processing native methods, enumerations, serializable classes, and annotations, which are all discussed in their respective examples.
The "InnerClasses" attribute (or more precisely, its source name part) has to
be preserved as well, for any inner classes that can be referenced from
outside the library. The javac
compiler would be unable to find
the inner classes otherwise.
The "Signature" attribute is required to be able to access generic types when compiling in JDK 5.0.
-keepclasseswithmembernames class * { native <methods>; }
Note the use of -keepclasseswithmembernames
.
We don't want to preserve all classes or all native methods; we just want to
keep the relevant names from being obfuscated.
ProGuard doesn't have your native code, so it can't automatically preserve the classes or class members that are invoked by the native code. These are entry points, which you'll have to specify explicitly.
-keepclassmembers class * extends java.lang.Enum { public static **[] values(); public static ** valueOf(java.lang.String); }
-keepclassmembers class * implements java.io.Serializable { private void writeObject(java.io.ObjectOutputStream); private void readObject(java.io.ObjectInputStream); java.lang.Object writeReplace(); java.lang.Object readResolve(); }
The -keepclassmembers
option makes sure that any serialization methods are kept. By using this
directive instead of the basic -keep
directive, we're not
forcing preservation of all serializable classes, just preservation
of the listed members of classes that are actually used.
serialVersionUID
fields. The following directives should
then be sufficient to ensure compatibility over time:
-keepnames class * implements java.io.Serializable -keepclassmembers class * implements java.io.Serializable { static final long serialVersionUID; static final java.io.ObjectStreamField[] serialPersistentFields; !static !transient <fields>; private void writeObject(java.io.ObjectOutputStream); private void readObject(java.io.ObjectInputStream); java.lang.Object writeReplace(); java.lang.Object readResolve(); }
The serialVersionUID
and serialPersistentFields
lines makes sure those fields are preserved, if they are present.
The <fields>
line preserves all non-static,
non-transient fields, with their original names. The introspection of the
serialization process and the de-serialization process will then find
consistent names.
serialVersionUID
fields. I imagine the
original code will then be hard to maintain, since the serial version UID
is then computed from a list of features the serializable class. Changing
the class ever so slightly may change the computed serial version UID. The
list of features is specified in the section on Stream
Unique Identifiers of Sun's Java
Object Serialization Specification. The following directives should at
least partially ensure compatibility with the original classes:
-keepnames class * implements java.io.Serializable -keepclassmembers class * implements java.io.Serializable { static final long serialVersionUID; static final java.io.ObjectStreamField[] serialPersistentFields; !static !transient <fields>; !private <fields>; !private <methods>; private void writeObject(java.io.ObjectOutputStream); private void readObject(java.io.ObjectInputStream); java.lang.Object writeReplace(); java.lang.Object readResolve(); }
The new directives force preservation of the elements involved in the UID
computation. In addition, the user will have to manually specify all
interfaces of the serializable classes (using something like "-keep
interface MyInterface
"), since these names are also used when
computing the UID. A fast but sub-optimal alternative would be simply
keeping all interfaces with "-keep interface *
".
Note that the above directives may preserve more classes and class members
than strictly necessary. For instance, a large number of classes may implement
the Serialization
interface, yet only a small number may actually
ever be serialized. Knowing your application and tuning the configuration
often produces more compact results.
-keep public class mypackage.MyBean { public void setMyProperty(int); public int getMyProperty(); } -keep public class mypackage.MyBeanEditor
If there are too many elements to list explicitly, wildcards in class names and method signatures might be helpful. This example encompasses a wide range of setters and getters:
-keep class mybeans.** { void set*(%); void set*(**); void set*(%[]); void set*(**[]); void set*(int, %); void set*(int, **); % get*(); ** get*(); %[] get*(); **[] get*(); % get*(int); ** get*(int); }
The '%
' wildcard matches any primitive type, while the
'**
' wildcard matches any class name. Array types have to be
specified explicitly. This results in a short list of alternative method
signatures.
-keepattributes *Annotation*
For brevity, we're specifying a wildcarded attribute name, which will match
RuntimeVisibleAnnotations
,
RuntimeInvisibleAnnotations
,
RuntimeVisibleParameterAnnotations
,
RuntimeInvisibleParameterAnnotations
, and
AnnotationDefault
. Depending on the purpose of the processed
code, you could refine this selection, for instance not keeping the run-time
invisible annotations (which are only used at compile-time).
Some code may make further use of introspection to figure out the enclosing methods of anonymous inner classes. In that case, the corresponding attribute has to be preserved as well:
-keepattributes EnclosingMethod
Driver
interface.
Since they are often created dynamically, you may want to preserve any
implementations that you are processing as entry points:
-keep class * implements java.sql.Driver
This directive also gets rid of the note that ProGuard prints out about
(java.sql.Driver)Class.forName
constructs, if you are
instantiating a driver in your code (without necessarily implementing any
drivers yourself).
ComponentUI
class. For some reason, these have to contain a
static method createUI
, which the Swing API invokes using
introspection. You should therefore always preserve the method as an entry
point, for instance like this:
-keep class * extends javax.swing.plaf.ComponentUI { public static javax.swing.plaf.ComponentUI createUI(javax.swing.JComponent); }
This directive also keeps the classes themselves.
rmic
tool. If that is not
possible, you may want to try something like this:
-keep interface * extends java.rmi.Remote { <methods>; } -keep class * implements java.rmi.Remote { <init>(java.rmi.activation.ActivationID, java.rmi.MarshalledObject); }
The first directive keeps all your Remote interfaces and their methods. The second one keeps all the implementations, along with their particular RMI constructors, if any.
-printmapping out.map -renamesourcefileattribute SourceFile -keepattributes SourceFile,LineNumberTable
We're keeping all source file attributes, but we're replacing their values by the string "SourceFile". We could use any string. This string is already present in all class files, so it doesn't take up any extra space. If you're working with J++, you'll want to keep the "SourceDir" attribute as well.
We're also keeping the line number tables of all methods.
Whenever both of these attributes are present, the Java run-time environment will include line number information when printing out exception stack traces.
The information will only be useful if we can map the obfuscated names back to
their original names, so we're saving the mapping to a file
out.map
. The information can then be used by the ReTrace tool to restore the original stack trace.
-injars classes -injars in1.jar -injars in2.jar -injars in3.jar -outjars out.jar
This configuration merges the processed versions of the files in the
classes
directory and the three jars into a single output jar
out.jar
.
If you want to preserve the structure of your input jars (and/or wars, ears, zips, or directories), you can specify an output directory (or a war, an ear, or a zip). For example:
-injars in1.jar -injars in2.jar -injars in3.jar -outjars out
The input jars will then be reconstructed in the directory out
,
with their original names.
You can also combine archives into higher level archives. For example:
-injars in1.jar -injars in2.jar -injars in3.jar -outjars out.war
The other way around, you can flatten the archives inside higher level archives into simple archives:
-injars in.war -outjars out.jar
This configuration puts the processed contents of all jars inside
in.war
(plus any other contents of in.war
) into
out.jar
.
If you want to combine input jars (and/or wars, ears, zips, or directories)
into output jars (and/or wars, ears, zips, or directories), you can group the
-injars
and -outjars
options. For example:
-injars base_in1.jar -injars base_in2.jar -injars base_in3.jar -outjars base_out.jar -injars extra_in.jar -outjars extra_out.jar
This configuration puts the processed results of all base_in*.jar
jars into base_out.jar
, and the processed results of the
extra_in.jar
into extra_out.jar
. Note that only the
order of the options matters; the additional whitespace is just for clarity.
This grouping, archiving, and flattening can be arbitrarily complex. ProGuard always tries to package output archives in a sensible way, reconstructing the input entries as much as required.
-injars in.jar(!images/**) -outjars out.jar
This configuration removes any files in the images
directory and
its subdirectories.
Such filters can be convenient for avoiding warnings about duplicate files in the output. For example, only keeping the manifest file from a first input jar:
-injars in1.jar -injars in2.jar(!META-INF/MANIFEST.MF) -injars in3.jar(!META-INF/MANIFEST.MF) -outjars out.jar
Another useful application is speeding up the processing by ProGuard, by disregarding a large number of irrelevant classes in the runtime library jar:
-libraryjars <java.home>/lib/rt.jar(java/**,javax/**)
The filter makes ProGuard disregard com.sun.**
classes, for
instance , which don't affect the processing of ordinary applications.
It is also possible to filter the jars (and/or wars, ears, zips) themselves, based on their names. For example:
-injars in(**/acme_*.jar;) -outjars out.jar
Note the semi-colon in the filter; the filter in front of it applies to jar
names. In this case, only acme_*.jar
jars are read from the
directory in
and its subdirectories. Filters for war names, ear
names, and zip names can be prefixed with additional semi-colons. All types of
filters can be combined. They are orthogonal.
On the other hand, you can also filter the output, in order to control what content goes where. For example:
-injars in.jar -outjars code_out.jar(**.class) -outjars resources_out.jar
This configuration splits the processed output, sending **.class
files to code_out.jar
, and all remaining files to
resources_out.jar
.
Again, the filtering can be arbitrarily complex, especially when combined with the grouping of input and output.
The easiest way is to specify your input jars (and/or wars, ears, zips, and directories) and a single output directory. ProGuard will then reconstruct the input in this directory, using the original jar names. For example, showing just the input and output options:
-injars application1.jar -injars application2.jar -injars application3.jar -outjars processed_applications
After processing, the directory processed_applications
will
contain the processed application jars, with their original names.
-injars proguardgui.jar -outjars proguardgui_out.jar -injars proguard.jar -outjars proguard_out.jar -libraryjars <java.home>/lib/rt.jar -applymapping proguard.map -keep public class proguard.gui.ProGuardGUI { public static void main(java.lang.String[]); }
We're reading both unprocessed jars as input. Their processed contents will go
to the respective output jars. The -applymapping
option then
makes sure the ProGuard part of the code gets the previously produced
obfuscation mapping. The final application will consist of the obfuscated
ProGuard jar and the additional obfuscated GUI jar.
The added code in this example is straightforward; it doesn't affect the
original code. The proguard_out.jar
will be identical to the one
produced in the initial processing step. If you foresee adding more complex
extensions to your code, you should specify the options -useuniqueclassmembernames
,
-dontshrink
, and -dontoptimize
in the
original processing step. These options ensure that the obfuscated base
jar will always remain usable without changes. You can then specify the base
jar as a library jar:
-injars proguardgui.jar -outjars proguardgui_out.jar -libraryjars proguard.jar -libraryjars <java.home>/lib/rt.jar -applymapping proguard.map -keep public class proguard.gui.ProGuardGUI { public static void main(java.lang.String[]); }
mypackage.MyApplication
:
-injars in.jar -libraryjars <java.home>/lib/rt.jar -dontoptimize -dontobfuscate -printusage -keep public class mypackage.MyApplication { public static void main(java.lang.String[]); }
We're not specifying an output jar, just printing out some results. We're saving some processing time by skipping the optimization and obfuscation steps.
The java compiler inlines primitive constants (primitive static
final
fields). ProGuard would therefore list such fields as not being
used in the class files that it analyzes, even if they are used in the
source files. We can add a -keepclassmembers
option
that keeps those fields a priori, in order to avoid listing them:
-keepclassmembers class * { static final % *; }
-injars in.jar -dontshrink -dontoptimize -dontobfuscate -dump
Note how we don't need to specify the Java run-time jar, because we're not processing the input jar at all.