• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<!doctype html PUBLIC "-//W3C//DTD HTML 3.2 Final//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 Examples</title>
8</head>
9<body>
10
11<h2>Examples</h2>
12
13Some typical useful configurations:
14<ol>
15<li><a href="#application">A typical application</a>
16<li><a href="#applet">A typical applet</a>
17<li><a href="#midlet">A typical midlet</a>
18<li><a href="#jcapplet">A typical Java Card applet</a>
19<li><a href="#xlet">A typical xlet</a>
20<li><a href="#androidapplication">A typical Android application</a>
21<li><a href="#library">A typical library</a>
22<li><a href="#applications">All possible applications in the input jars</a>
23<li><a href="#applets">All possible applets in the input jars</a>
24<li><a href="#midlets">All possible midlets in the input jars</a>
25<li><a href="#jcapplets">All possible Java Card applets in the input jars</a>
26<li><a href="#xlets">All possible xlets in the input jars</a>
27<li><a href="#androidapplications">All possible Android applications in the input jars</a>
28<li><a href="#servlets">All possible servlets in the input jars</a>
29<li><a href="#native">Processing native methods</a>
30<li><a href="#callback">Processing callback methods</a>
31<li><a href="#enumerations">Processing enumeration classes</a>
32<li><a href="#serializable">Processing serializable classes</a>
33<li><a href="#beans">Processing bean classes</a>
34<li><a href="#annotations">Processing annotations</a>
35<li><a href="#database">Processing database drivers</a>
36<li><a href="#componentui">Processing ComponentUI classes</a>
37<li><a href="#rmi">Processing RMI code</a>
38<li><a href="#resourcefiles">Processing resource files</a>
39<li><a href="#stacktrace">Producing useful obfuscated stack traces</a>
40<li><a href="#repackaging">Obfuscating package names</a>
41<li><a href="#restructuring">Restructuring the output archives</a>
42<li><a href="#filtering">Filtering the input and the output</a>
43<li><a href="#multiple">Processing multiple applications at once</a>
44<li><a href="#incremental">Incremental obfuscation</a>
45<li><a href="#microedition">Preverifying class files for Java Micro Edition</a>
46<li><a href="#upgrade">Upgrading class files to Java 6</a>
47<li><a href="#deadcode">Finding dead code</a>
48<li><a href="#structure">Printing out the internal structure of class files</a>
49<li><a href="#annotated">Using annotations to configure ProGuard</a>
50</ol>
51
52You can find some sample configuration files in the <code>examples</code>
53directory of the ProGuard distribution.
54
55<a name="application">&nbsp;</a>
56<h3>A typical application</h3>
57To shrink, optimize, and obfuscate the ProGuard application itself, one would
58typically create a configuration file <code>proguard.pro</code> and then type:
59<pre>
60java -jar proguard.jar @proguard.pro
61</pre>
62<p>
63The configuration file would contain the following options:
64<pre>
65-injars       proguard.jar
66-outjars      proguard_out.jar
67-libraryjars  &lt;java.home&gt;/lib/rt.jar
68-printmapping proguard.map
69
70-keep public class proguard.ProGuard {
71    public static void main(java.lang.String[]);
72}
73</pre>
74<p>
75Note the use of the <code>&lt;java.home&gt;</code> system property; it is
76replaced automatically.
77<p>
78Also note that all type names are fully specified:
79<code>proguard.ProGuard</code> and <code>java.lang.String[]</code>.
80<p>
81The access modifiers <code>public</code> and <code>static</code> are not
82really required in this case, since we know a priori that the specified class
83and method have the proper access flags. It just looks more familiar this way.
84<p>
85We're writing out an obfuscation mapping file with <a
86href="usage.html#printmapping"><code>-printmapping</code></a>, for
87de-obfuscating any stack traces later on, or for incremental obfuscation of
88extensions.
89<p>
90We can further improve the results with a few additional options:
91<pre>
92-optimizationpasses 3
93-overloadaggressively
94-repackageclasses ''
95-allowaccessmodification
96</pre>
97These options are not required; they just shave off some extra bytes from the
98output jar, by performing up to 3 optimization passes, and by aggressively
99obfuscating class members and <a href="#repackaging">package names</a>.
100<p>
101In general, you might need a few additional options for processing <a
102href="#native">native methods</a>, <a href="#callback">callback methods</a>,
103<a href="#enumerations">enumerations</a>, <a href="#serializable">serializable
104classes</a>, <a href="#beans">bean classes</a>, <a
105href="#annotations">annotations</a>, and <a href="#resourcefiles">resource
106files</a>. For processing 'simple' applications like ProGuard, that is not
107required.
108
109<a name="applet">&nbsp;</a>
110<h3>A typical applet</h3>
111These options shrink, optimize, and obfuscate the applet
112<code>mypackage.MyApplet</code>:
113<pre>
114-injars      in.jar
115-outjars     out.jar
116-libraryjars &lt;java.home&gt;/lib/rt.jar
117
118-keep public class mypackage.MyApplet
119</pre>
120<p>
121The typical applet methods will be preserved automatically, since
122<code>mypackage.MyApplet</code> is an extension of the <code>Applet</code>
123class in the library <code>rt.jar</code>.
124<p>
125If applicable, you should add options for processing <a href="#native">native
126methods</a>, <a href="#callback">callback methods</a>, <a
127href="#enumerations">enumerations</a>, <a href="#serializable">serializable
128classes</a>, <a href="#beans">bean classes</a>, <a
129href="#annotations">annotations</a>, and <a href="#resourcefiles">resource
130files</a>.
131
132<a name="midlet">&nbsp;</a>
133<h3>A typical midlet</h3>
134These options shrink, optimize, obfuscate, and preverify the midlet
135<code>mypackage.MyMIDlet</code>:
136<pre>
137-injars      in.jar
138-outjars     out.jar
139-libraryjars /usr/local/java/wtk2.1/lib/midpapi20.jar
140-libraryjars /usr/local/java/wtk2.1/lib/cldcapi11.jar
141-overloadaggressively
142-repackageclasses ''
143-allowaccessmodification
144-microedition
145
146-keep public class mypackage.MyMIDlet
147</pre>
148<p>
149Note how we're now targeting the Java Micro Edition run-time environment of
150<code>midpapi20.jar</code> and <code>cldcapi11.jar</code>, instead of the Java
151Standard Edition run-time environment <code>rt.jar</code>. You can target
152other JME environments by picking the appropriate jars.
153<p>
154The typical midlet methods will be preserved automatically, since
155<code>mypackage.MyMIDlet</code> is an extension of the <code>MIDlet</code>
156class in the library <code>midpapi20.jar</code>.
157<p>
158The <a href="usage.html#microedition"><code>-microedition</code></a> option
159makes sure the class files are preverified for Java Micro Edition, producing
160compact <code>StackMap</code> attributes. It is no longer necessary to run an
161external preverifier.
162<p>
163Be careful if you do use the external <code>preverify</code> tool on a platform
164with a case-insensitive filing system, such as Windows. Because this tool
165unpacks your processed jars, you should then use ProGuard's <a
166href="usage.html#dontusemixedcaseclassnames"><code>-dontusemixedcaseclassnames</code></a>
167option.
168<p>
169If applicable, you should add options for processing <a href="#native">native
170methods</a> and <a href="#resourcefiles">resource files</a>.
171<p>
172Note that you will still have to adapt the midlet jar size in the
173corresponding jad file; ProGuard doesn't do that for you.
174
175<a name="jcapplet">&nbsp;</a>
176<h3>A typical Java Card applet</h3>
177These options shrink, optimize, and obfuscate the Java Card applet
178<code>mypackage.MyApplet</code>:
179<pre>
180-injars      in.jar
181-outjars     out.jar
182-libraryjars /usr/local/java/javacard2.2.2/lib/api.jar
183-dontwarn    java.lang.Class
184-overloadaggressively
185-repackageclasses ''
186-allowaccessmodification
187
188-keep public class mypackage.MyApplet
189</pre>
190<p>
191The configuration is very similar to the configuration for midlets, except that
192it now targets the Java Card run-time environment. This environment doesn't
193have java.lang.Class, so we're telling ProGuard not to worry about it.
194
195<a name="xlet">&nbsp;</a>
196<h3>A typical xlet</h3>
197These options shrink, optimize, and obfuscate the xlet
198<code>mypackage.MyXlet</code>:
199<pre>
200-injars      in.jar
201-outjars     out.jar
202-libraryjars /usr/local/java/jtv1.1/javatv.jar
203-libraryjars /usr/local/java/cdc1.1/lib/cdc.jar
204-libraryjars /usr/local/java/cdc1.1/lib/btclasses.zip
205-overloadaggressively
206-repackageclasses ''
207-allowaccessmodification
208
209-keep public class mypackage.MyXlet
210</pre>
211<p>
212The configuration is very similar to the configuration for midlets, except that
213it now targets the CDC run-time environment with the Java TV API.
214
215<a name="androidapplication">&nbsp;</a>
216<h3>A typical Android application</h3>
217These options shrink, optimize, and obfuscate the simple Android application
218based on a single activity <code>mypackage.MyActivity</code>:
219<pre>
220-injars      in.jar
221-outjars     out.jar
222-libraryjars /usr/local/java/android-1.5_r1/platforms/android-1.5/android.jar
223-overloadaggressively
224-repackageclasses ''
225-allowaccessmodification
226-optimizations !code/simplification/arithmetic
227
228-keep public class mypackage.MyActivity
229</pre>
230<p>
231The configuration is very similar to the configuration for midlets, except that
232it now targets the Android run-time environment.
233<p>
234The <a href="usage.html#optimizations"><code>-optimizations</code></a> option
235disables some arithmetic simplifications that Dalvik 1.0 and 1.5 can't handle.
236<p>
237If applicable, you should add options for processing <a href="#native">native
238methods</a>, <a href="#callback">callback methods</a>, and <a
239href="#resourcefiles">resource files</a>.
240
241<a name="library">&nbsp;</a>
242<h3>A typical library</h3>
243These options shrink, optimize, and obfuscate an entire library, keeping all
244public and protected classes and class members, native method names, and
245serialization code:
246<pre>
247-injars       in.jar
248-outjars      out.jar
249-libraryjars  &lt;java.home&gt;/lib/rt.jar
250-printmapping out.map
251
252-renamesourcefileattribute SourceFile
253-keepattributes Exceptions,InnerClasses,Signature,Deprecated,
254                SourceFile,LineNumberTable,*Annotation*,EnclosingMethod
255
256-keep public class * {
257    public protected *;
258}
259
260-keepclassmembernames class * {
261    java.lang.Class class$(java.lang.String);
262    java.lang.Class class$(java.lang.String, boolean);
263}
264
265-keepclasseswithmembernames class * {
266    native &lt;methods&gt;;
267}
268
269-keepclassmembers enum * {
270    public static **[] values();
271    public static ** valueOf(java.lang.String);
272}
273
274-keepclassmembers class * implements java.io.Serializable {
275    static final long serialVersionUID;
276    private void writeObject(java.io.ObjectOutputStream);
277    private void readObject(java.io.ObjectInputStream);
278    java.lang.Object writeReplace();
279    java.lang.Object readResolve();
280}
281</pre>
282<p>
283This configuration should preserve everything we'll ever want to access in the
284library. Only if there are any other non-public classes or methods that are
285invoked dynamically, they should be specified using additional <a
286href="usage.html#keep"><code>-keep</code></a> options.
287<p>
288The <a
289href="usage.html#keepclassmembernames"><code>-keepclassmembernames</code></a>
290option for the <code>class$</code> methods is not strictly necessary. These
291methods are inserted by the <code>javac</code> compiler and the
292<code>jikes</code> compiler respectively, to implement the <code>.class</code>
293construct. ProGuard will automatically detect them and deal with them, even
294when their names have been obfuscated. However, older versions of ProGuard and
295other obfuscators may rely on the original method names. It may therefore be
296helpful to preserve them, in case these other obfuscators are ever used for
297further obfuscation of the library.
298<p>
299The "Exceptions" attribute has to be preserved, so the compiler knows which
300exceptions methods may throw.
301<p>
302The "InnerClasses" attribute (or more precisely, its source name part) has to
303be preserved too, for any inner classes that can be referenced from outside the
304library. The <code>javac</code> compiler would be unable to find the inner
305classes otherwise.
306<p>
307The "Signature" attribute is required to be able to access generic types when
308compiling in JDK 5.0 and higher.
309<p>
310Finally, we're keeping the "Deprecated" attribute and the attributes for
311producing <a href="#stacktrace">useful stack traces</a>.
312<p>
313We've also added some options for for processing <a href="#native">native
314methods</a>, <a href="#enumerations">enumerations</a>, <a
315href="#serializable">serializable classes</a>, and <a
316href="#annotations">annotations</a>, which are all discussed in their
317respective examples.
318
319<a name="applications">&nbsp;</a>
320<h3>All possible applications in the input jars</h3>
321These options shrink, optimize, and obfuscate all public applications in
322<code>in.jar</code>:
323<pre>
324-injars      in.jar
325-outjars     out.jar
326-libraryjars &lt;java.home&gt;/lib/rt.jar
327-printseeds
328
329-keepclasseswithmembers public class * {
330    public static void main(java.lang.String[]);
331}
332</pre>
333<p>
334Note the use of <a
335href="usage.html#keepclasseswithmembers"><code>-keepclasseswithmembers</code></a>.
336We don't want to preserve all classes, just all classes that have main
337methods, and those methods.
338<p>
339The <a href="usage.html#printseeds"><code>-printseeds</code></a> option prints
340out which classes exactly will be preserved, so we know for sure we're getting
341what we want.
342<p>
343If applicable, you should add options for processing <a href="#native">native
344methods</a>, <a href="#callback">callback methods</a>, <a
345href="#enumerations">enumerations</a>, <a href="#serializable">serializable
346classes</a>, <a href="#beans">bean classes</a>, <a
347href="#annotations">annotations</a>, and <a href="#resourcefiles">resource
348files</a>.
349
350<a name="applets">&nbsp;</a>
351<h3>All possible applets in the input jars</h3>
352These options shrink, optimize, and obfuscate all public applets in
353<code>in.jar</code>:
354<pre>
355-injars      in.jar
356-outjars     out.jar
357-libraryjars &lt;java.home&gt;/lib/rt.jar
358-printseeds
359
360-keep public class * extends java.applet.Applet
361</pre>
362<p>
363We're simply keeping all classes that extend the <code>Applet</code> class.
364<p>
365Again, the <a href="usage.html#printseeds"><code>-printseeds</code></a> option
366prints out which applets exactly will be preserved.
367<p>
368If applicable, you should add options for processing <a href="#native">native
369methods</a>, <a href="#callback">callback methods</a>, <a
370href="#enumerations">enumerations</a>, <a href="#serializable">serializable
371classes</a>, <a href="#beans">bean classes</a>, <a
372href="#annotations">annotations</a>, and <a href="#resourcefiles">resource
373files</a>.
374
375<a name="midlets">&nbsp;</a>
376<h3>All possible midlets in the input jars</h3>
377These options shrink, optimize, obfuscate, and preverify all public midlets in
378<code>in.jar</code>:
379<pre>
380-injars      in.jar
381-outjars     out.jar
382-libraryjars /usr/local/java/wtk2.1/lib/midpapi20.jar
383-libraryjars /usr/local/java/wtk2.1/lib/cldcapi11.jar
384-overloadaggressively
385-repackageclasses ''
386-allowaccessmodification
387-microedition
388-printseeds
389
390-keep public class * extends javax.microedition.midlet.MIDlet
391</pre>
392<p>
393We're simply keeping all classes that extend the <code>MIDlet</code> class.
394<p>
395The <a href="usage.html#microedition"><code>-microedition</code></a> option
396makes sure the class files are preverified for Java Micro Edition, producing
397compact <code>StackMap</code> attributes. It is no longer necessary to run an
398external preverifier.
399<p>
400Be careful if you do use the external <code>preverify</code> tool on a platform
401with a case-insensitive filing system, such as Windows. Because this tool
402unpacks your processed jars, you should then use ProGuard's <a
403href="usage.html#dontusemixedcaseclassnames"><code>-dontusemixedcaseclassnames</code></a>
404option.
405<p>
406The <a href="usage.html#printseeds"><code>-printseeds</code></a> option prints
407out which midlets exactly will be preserved.
408<p>
409If applicable, you should add options for processing <a href="#native">native
410methods</a> and <a href="#resourcefiles">resource files</a>.
411<p>
412Note that you will still have to adapt the midlet jar size in the
413corresponding jad file; ProGuard doesn't do that for you.
414
415<a name="jcapplets">&nbsp;</a>
416<h3>All possible Java Card applets in the input jars</h3>
417These options shrink, optimize, and obfuscate all public Java Card applets in
418<code>in.jar</code>:
419<pre>
420-injars      in.jar
421-outjars     out.jar
422-libraryjars /usr/local/java/javacard2.2.2/lib/api.jar
423-dontwarn    java.lang.Class
424-overloadaggressively
425-repackageclasses ''
426-allowaccessmodification
427-printseeds
428
429-keep public class * implements javacard.framework.Applet
430</pre>
431<p>
432We're simply keeping all classes that implement the <code>Applet</code>
433interface.
434<p>
435The <a href="usage.html#printseeds"><code>-printseeds</code></a> option prints
436out which applets exactly will be preserved.
437
438<a name="xlets">&nbsp;</a>
439<h3>All possible xlets in the input jars</h3>
440These options shrink, optimize, and obfuscate all public xlets in
441<code>in.jar</code>:
442<pre>
443-injars      in.jar
444-outjars     out.jar
445-libraryjars /usr/local/java/jtv1.1/javatv.jar
446-libraryjars /usr/local/java/cdc1.1/lib/cdc.jar
447-libraryjars /usr/local/java/cdc1.1/lib/btclasses.zip
448-overloadaggressively
449-repackageclasses ''
450-allowaccessmodification
451-printseeds
452
453-keep public class * implements javax.tv.xlet.Xlet
454</pre>
455<p>
456We're simply keeping all classes that implement the <code>Xlet</code> interface.
457<p>
458The <a href="usage.html#printseeds"><code>-printseeds</code></a> option prints
459out which xlets exactly will be preserved.
460
461<a name="androidapplications">&nbsp;</a>
462<h3>All possible Android applications in the input jars</h3>
463These options shrink, optimize, and obfuscate all public activities, services,
464broadcast receivers, and content providers in <code>in.jar</code>:
465<pre>
466-injars      in.jar
467-outjars     out.jar
468-libraryjars /usr/local/java/android-1.5_r1/platforms/android-1.5/android.jar
469-overloadaggressively
470-repackageclasses ''
471-allowaccessmodification
472-optimizations !code/simplification/arithmetic
473-printseeds
474
475-keep public class * extends android.app.Activity
476-keep public class * extends android.app.Service
477-keep public class * extends android.content.BroadcastReceiver
478-keep public class * extends android.content.ContentProvider
479</pre>
480<p>
481We're keeping all classes that extend the base classes that may be referenced
482by the <code>AndroidManifest.xml</code> file of the application.
483<p>
484The <a href="usage.html#printseeds"><code>-printseeds</code></a> option prints
485out which implementations exactly will be preserved.
486<p>
487If applicable, you should add options for processing <a href="#native">native
488methods</a>, <a href="#callback">callback methods</a>, and <a
489href="#resourcefiles">resource files</a>.
490
491<a name="servlets">&nbsp;</a>
492<h3>All possible servlets in the input jars</h3>
493These options shrink, optimize, and obfuscate all public servlets in
494<code>in.jar</code>:
495<pre>
496-injars      in.jar
497-outjars     out.jar
498-libraryjars &lt;java.home&gt;/lib/rt.jar
499-libraryjars /usr/local/java/servlet/servlet.jar
500-printseeds
501
502-keep public class * implements javax.servlet.Servlet
503</pre>
504<p>
505Keeping all servlets is very similar to keeping all applets. The servlet API
506is not part of the standard run-time jar, so we're specifying it as a library.
507Don't forget to use the right path name.
508<p>
509We're then keeping all classes that implement the <code>Servlet</code>
510interface. We're using the <code>implements</code> keyword because it looks
511more familiar in this context, but it is equivalent to <code>extends</code>,
512as far as ProGuard is concerned.
513<p>
514The <a href="usage.html#printseeds"><code>-printseeds</code></a> option prints
515out which servlets exactly will be preserved.
516<p>
517If applicable, you should add options for processing <a href="#native">native
518methods</a>, <a href="#callback">callback methods</a>, <a
519href="#enumerations">enumerations</a>, <a href="#serializable">serializable
520classes</a>, <a href="#beans">bean classes</a>, <a
521href="#annotations">annotations</a>, and <a href="#resourcefiles">resource
522files</a>.
523
524<a name="native">&nbsp;</a>
525<h3>Processing native methods</h3>
526If your application, applet, servlet, library, etc., contains native methods,
527you'll want to preserve their names and their classes' names, so they can
528still be linked to the native library. The following additional option will
529ensure that:
530<pre>
531-keepclasseswithmembernames class * {
532    native &lt;methods&gt;;
533}
534</pre>
535<p>
536Note the use of <a
537href="usage.html#keepclasseswithmembernames"><code>-keepclasseswithmembernames</code></a>.
538We don't want to preserve all classes or all native methods; we just want to
539keep the relevant names from being obfuscated.
540<p>
541ProGuard doesn't look at your native code, so it won't automatically preserve
542the classes or class members that are invoked by the native code. These are
543entry points, which you'll have to specify explicitly.  <a
544href="callback">Callback methods</a> are discussed below as a typical example.
545
546<a name="callback">&nbsp;</a>
547<h3>Processing callback methods</h3>
548If your application, applet, servlet, library, etc., contains callback
549methods, which are called from external code (native code, scripts,...),
550you'll want to preserve them, and probably their classes too. They are just
551entry points to your code, much like, say, the main method of an application.
552If they aren't preserved by other <code>-keep</code> options, something like
553the following option will keep the callback class and method:
554<pre>
555-keep class mypackage.MyCallbackClass {
556    void myCallbackMethod(java.lang.String);
557}
558</pre>
559<p>
560This will preserve the given class and method from being removed or renamed.
561
562<a name="enumerations">&nbsp;</a>
563<h3>Processing enumeration classes</h3>
564If your application, applet, servlet, library, etc., contains enumeration
565classes, you'll have to preserve some special methods. Enumerations were
566introduced in Java 5. The java compiler translates enumerations into classes
567with a special structure. Notably, the classes contain implementations of some
568static methods that the run-time environment accesses by introspection (Isn't
569that just grand? Introspection is the self-modifying code of a new
570generation). You have to specify these explicitly, to make sure they aren't
571removed or obfuscated:
572<pre>
573-keepclassmembers enum * {
574    public static **[] values();
575    public static ** valueOf(java.lang.String);
576}
577</pre>
578
579<a name="serializable">&nbsp;</a>
580<h3>Processing serializable classes</h3>
581More complex applications, applets, servlets, libraries, etc., may contain
582classes that are serialized. Depending on the way in which they are used, they
583may require special attention:
584<ul>
585
586<li>Often, serialization is simply a means of transporting data, without
587    long-term storage. Classes that are shrunk and obfuscated should then
588    continue to function fine with the following additional options:
589
590<pre>
591-keepclassmembers class * implements java.io.Serializable {
592    private void writeObject(java.io.ObjectOutputStream);
593    private void readObject(java.io.ObjectInputStream);
594    java.lang.Object writeReplace();
595    java.lang.Object readResolve();
596}
597</pre>
598<p>
599
600    The <a
601    href="usage.html#keepclassmembers"><code>-keepclassmembers</code></a>
602    option makes sure that any serialization methods are kept. By using this
603    option instead of the basic <code>-keep</code> option, we're not
604    forcing preservation of <i>all</i> serializable classes, just preservation
605    of the listed members of classes that are actually used.
606    <p>
607
608<li>Sometimes, the serialized data are stored, and read back later into newer
609    versions of the serializable classes. One then has to take care the classes
610    remain compatible with their unprocessed versions and with future
611    processed versions. In such cases, the relevant classes will most likely
612    have <code>serialVersionUID</code> fields. The following options should
613    then be sufficient to ensure compatibility over time:
614
615<pre>
616-keepnames class * implements java.io.Serializable
617
618-keepclassmembers class * implements java.io.Serializable {
619    static final long serialVersionUID;
620    static final java.io.ObjectStreamField[] serialPersistentFields;
621    !static !transient &lt;fields&gt;;
622    private void writeObject(java.io.ObjectOutputStream);
623    private void readObject(java.io.ObjectInputStream);
624    java.lang.Object writeReplace();
625    java.lang.Object readResolve();
626}
627</pre>
628<p>
629
630    The <code>serialVersionUID</code> and <code>serialPersistentFields</code>
631    lines makes sure those fields are preserved, if they are present.
632    The <code>&lt;fields&gt;</code> line preserves all non-static,
633    non-transient fields, with their original names. The introspection of the
634    serialization process and the de-serialization process will then find
635    consistent names.
636
637<li>Occasionally, the serialized data have to remain compatible, but the
638    classes involved lack <code>serialVersionUID</code> fields. I imagine the
639    original code will then be hard to maintain, since the serial version UID
640    is then computed from a list of features the serializable class. Changing
641    the class ever so slightly may change the computed serial version UID. The
642    list of features is specified in the section on <a
643    href="http://java.sun.com/javase/6/docs/platform/serialization/spec/class.html#4100">Stream
644    Unique Identifiers</a> of Sun's <a
645    href="http://java.sun.com/javase/6/docs/platform/serialization/spec/serialTOC.html">Java
646    Object Serialization Specification</a>. The following directives should at
647    least partially ensure compatibility with the original classes:
648
649<pre>
650-keepnames class * implements java.io.Serializable
651
652-keepclassmembers class * implements java.io.Serializable {
653    static final long serialVersionUID;
654    static final java.io.ObjectStreamField[] serialPersistentFields;
655    !static !transient &lt;fields&gt;;
656    !private &lt;fields&gt;;
657    !private &lt;methods&gt;;
658    private void writeObject(java.io.ObjectOutputStream);
659    private void readObject(java.io.ObjectInputStream);
660    java.lang.Object writeReplace();
661    java.lang.Object readResolve();
662}
663</pre>
664<p>
665
666    The new options force preservation of the elements involved in the UID
667    computation. In addition, the user will have to manually specify all
668    interfaces of the serializable classes (using something like "<code>-keep
669    interface MyInterface</code>"), since these names are also used when
670    computing the UID. A fast but sub-optimal alternative would be simply
671    keeping all interfaces with "<code>-keep interface *</code>".
672
673</ul>
674<p>
675
676Note that the above options may preserve more classes and class members
677than strictly necessary. For instance, a large number of classes may implement
678the <code>Serialization</code> interface, yet only a small number may actually
679ever be serialized. Knowing your application and tuning the configuration
680often produces more compact results.
681
682<a name="beans">&nbsp;</a>
683<h3>Processing bean classes</h3>
684If your application, applet, servlet, library, etc., makes extensive use of
685introspection on bean classes to find bean editor classes, or getter and
686setter methods, then configuration may become painful. There's not much else
687you can do than making sure the bean class names, or the getter and setter
688names don't change. For instance:
689<pre>
690-keep public class mypackage.MyBean {
691    public void setMyProperty(int);
692    public int getMyProperty();
693}
694
695-keep public class mypackage.MyBeanEditor
696</pre>
697<p>
698If there are too many elements to list explicitly, wildcards in class names
699and method signatures might be helpful. This example should encompasses all
700possible setters and getters in classes in the package <code>mybeans</code>:
701<pre>
702-keep class mybeans.** {
703    void set*(***);
704    void set*(int, ***);
705
706    boolean is*();
707    boolean is*(int);
708
709    *** get*();
710    *** get*(int);
711}
712</pre>
713<p>
714The '<code>***</code>' wildcard matches any type (primitive or non-primitive,
715array or non-array). The methods with the '<code>int</code>' arguments matches
716properties that are lists.
717
718<a name="annotations">&nbsp;</a>
719<h3>Processing annotations</h3>
720If your application, applet, servlet, library, etc., uses annotations, you may
721want to preserve them in the processed output. Annotations are represented by
722attributes that have no direct effect on the execution of the code. However,
723their values can be retrieved through introspection, allowing developers to
724adapt the execution behavior accordingly. By default, ProGuard treats
725annotation attributes as optional, and removes them in the obfuscation step.
726If they are required, you'll have to specify this explicitly:
727<pre>
728-keepattributes *Annotation*
729</pre>
730<p>
731For brevity, we're specifying a wildcarded attribute name, which will match
732<code>RuntimeVisibleAnnotations</code>,
733<code>RuntimeInvisibleAnnotations</code>,
734<code>RuntimeVisibleParameterAnnotations</code>,
735<code>RuntimeInvisibleParameterAnnotations</code>, and
736<code>AnnotationDefault</code>. Depending on the purpose of the processed
737code, you could refine this selection, for instance not keeping the run-time
738invisible annotations (which are only used at compile-time).
739<p>
740Some code may make further use of introspection to figure out the enclosing
741methods of anonymous inner classes. In that case, the corresponding attribute
742has to be preserved as well:
743<pre>
744-keepattributes EnclosingMethod
745</pre>
746
747<a name="database">&nbsp;</a>
748<h3>Processing database drivers</h3>
749Database drivers are implementations of the <code>Driver</code> interface.
750Since they are often created dynamically, you may want to preserve any
751implementations that you are processing as entry points:
752<pre>
753-keep class * implements java.sql.Driver
754</pre>
755<p>
756This option also gets rid of the note that ProGuard prints out about
757<code>(java.sql.Driver)Class.forName</code> constructs, if you are
758instantiating a driver in your code (without necessarily implementing any
759drivers yourself).
760
761<a name="componentui">&nbsp;</a>
762<h3>Processing ComponentUI classes</h3>
763Swing UI look and feels are implemented as extensions of the
764<code>ComponentUI</code> class. For some reason, these have to contain a
765static method <code>createUI</code>, which the Swing API invokes using
766introspection. You should therefore always preserve the method as an entry
767point, for instance like this:
768<pre>
769-keep class * extends javax.swing.plaf.ComponentUI {
770    public static javax.swing.plaf.ComponentUI createUI(javax.swing.JComponent);
771}
772</pre>
773<p>
774This option also keeps the classes themselves.
775
776<a name="rmi">&nbsp;</a>
777<h3>Processing RMI code</h3>
778Reportedly, the easiest way to handle RMI code is to process the code with
779ProGuard first and then invoke the <code>rmic</code> tool. If that is not
780possible, you may want to try something like this:
781<pre>
782-keepattributes Exceptions
783
784-keep interface * extends java.rmi.Remote {
785    &lt;methods&gt;;
786}
787
788-keep class * implements java.rmi.Remote {
789    &lt;init&gt;(java.rmi.activation.ActivationID, java.rmi.MarshalledObject);
790}
791</pre>
792<p>
793The first <code>-keep</code> option keeps all your Remote interfaces and their
794methods. The second one keeps all the implementations, along with their
795particular RMI constructors, if any.
796<p>
797The <code>Exceptions</code> attribute has to be kept too, because the RMI
798handling code performs introspection to check whether the method signatures
799are compatible.
800
801<a name="resourcefiles">&nbsp;</a>
802<h3>Processing resource files</h3>
803If your application, applet, servlet, library, etc., contains resource files,
804it may be necessary to adapt their names and/or their contents when the
805application is obfuscated. The following two options can achieve this
806automatically:
807<pre>
808-adaptresourcefilenames    **.properties,**.gif,**.jpg
809-adaptresourcefilecontents **.properties,META-INF/MANIFEST.MF
810</pre>
811<p>
812The <a href="usage.html#adaptresourcefilenames">-adaptresourcefilenames</a>
813option in this case renames properties files and image files in the processed
814output, based on the obfuscated names of their corresponding class files (if
815any). The <a
816href="usage.html#adaptresourcefilecontents">-adaptresourcefilecontents</a>
817option looks for class names in properties files and in the manifest file, and
818replaces these names by the obfuscated names (if any). You'll probably want to
819adapt the filters to suit your application.
820
821<a name="stacktrace">&nbsp;</a>
822<h3>Producing useful obfuscated stack traces</h3>
823These options let obfuscated applications or libraries produce stack traces
824that can still be deciphered later on:
825<pre>
826-printmapping out.map
827
828-renamesourcefileattribute SourceFile
829-keepattributes SourceFile,LineNumberTable
830</pre>
831<p>
832We're keeping all source file attributes, but we're replacing their values by
833the string "SourceFile". We could use any string. This string is already
834present in all class files, so it doesn't take up any extra space. If you're
835working with J++, you'll want to keep the "SourceDir" attribute as well.
836<p>
837We're also keeping the line number tables of all methods.
838<p>
839Whenever both of these attributes are present, the Java run-time environment
840will include line number information when printing out exception stack traces.
841<p>
842The information will only be useful if we can map the obfuscated names back to
843their original names, so we're saving the mapping to a file
844<code>out.map</code>. The information can then be used by the <a
845href="retrace/index.html">ReTrace</a> tool to restore the original stack trace.
846
847<a name="repackaging">&nbsp;</a>
848<h3>Obfuscating package names</h3>
849Package names can be obfuscated in various ways, with increasing levels of
850obfuscation and compactness. For example, consider the following classes:
851<pre>
852mycompany.myapplication.MyMain
853mycompany.myapplication.Foo
854mycompany.myapplication.Bar
855mycompany.myapplication.extra.FirstExtra
856mycompany.myapplication.extra.SecondExtra
857mycompany.util.FirstUtil
858mycompany.util.SecondUtil
859</pre>
860<p>
861Let's assume the class name <code>mycompany.myapplication.MyMain</code> is the
862main application class that is kept by the configuration. All other class names
863can be obfuscated.
864<p>
865By default, packages that contain classes that can't be renamed aren't renamed
866either, and the package hierarchy is preserved. This results in obfuscated
867class names like these:
868<pre>
869mycompany.myapplication.MyMain
870mycompany.myapplication.a
871mycompany.myapplication.b
872mycompany.myapplication.a.a
873mycompany.myapplication.a.b
874mycompany.a.a
875mycompany.a.b
876</pre>
877<p>
878The <a
879href="usage.html#flattenpackagehierarchy"><code>-flattenpackagehierarchy</code></a>
880option obfuscates the package names further, by flattening the package
881hierarchy of obfuscated packages:
882<pre>
883-flattenpackagehierarchy 'myobfuscated'
884</pre>
885<p>
886The obfuscated class names then look as follows:
887<pre>
888mycompany.myapplication.MyMain
889mycompany.myapplication.a
890mycompany.myapplication.b
891myobfuscated.a.a
892myobfuscated.a.b
893myobfuscated.b.a
894myobfuscated.b.b
895</pre>
896<p>
897Alternatively, the <a
898href="usage.html#repackageclasses"><code>-repackageclasses</code></a> option
899obfuscates the entire packaging, by combining obfuscated classes into a single
900package:
901<pre>
902-repackageclasses 'myobfuscated'
903</pre>
904The obfuscated class names then look as follows:
905<pre>
906mycompany.myapplication.MyMain
907mycompany.myapplication.a
908mycompany.myapplication.b
909myobfuscated.a
910myobfuscated.b
911myobfuscated.c
912myobfuscated.d
913</pre>
914<p>
915Additionally specifying the <a
916href="usage.html#allowaccessmodification"><code>-allowaccessmodification</code></a>
917option allows access permissions of classes and class members to
918be broadened, opening up the opportunity to repackage all obfuscated classes:
919<pre>
920-repackageclasses 'myobfuscated'
921-allowaccessmodification
922</pre>
923The obfuscated class names then look as follows:
924<pre>
925mycompany.myapplication.MyMain
926myobfuscated.a
927myobfuscated.b
928myobfuscated.c
929myobfuscated.d
930myobfuscated.e
931myobfuscated.f
932</pre>
933<p>
934The specified target package can always be the root package. For instance:
935<pre>
936-repackageclasses ''
937-allowaccessmodification
938</pre>
939The obfuscated class names are then the shortest possible names:
940<pre>
941mycompany.myapplication.MyMain
942a
943b
944c
945d
946e
947f
948</pre>
949<p>
950Note that not all levels of obfuscation of package names may be acceptable for
951all code. Notably, you may have to take into account that your application may
952contain <a href="#resourcefiles">resource files</a> that have to be adapted.
953
954<a name="restructuring">&nbsp;</a>
955<h3>Restructuring the output archives</h3>
956In simple applications, all output classes and resources files are merged into
957a single jar. For example:
958<pre>
959-injars  classes
960-injars  in1.jar
961-injars  in2.jar
962-injars  in3.jar
963-outjars out.jar
964</pre>
965<p>
966This configuration merges the processed versions of the files in the
967<code>classes</code> directory and the three jars into a single output jar
968<code>out.jar</code>.
969<p>
970If you want to preserve the structure of your input jars (and/or wars, ears,
971zips, or directories), you can specify an output directory (or a war, an ear,
972or a zip). For example:
973<pre>
974-injars  in1.jar
975-injars  in2.jar
976-injars  in3.jar
977-outjars out
978</pre>
979<p>
980The input jars will then be reconstructed in the directory <code>out</code>,
981with their original names.
982<p>
983You can also combine archives into higher level archives. For example:
984<pre>
985-injars  in1.jar
986-injars  in2.jar
987-injars  in3.jar
988-outjars out.war
989</pre>
990<p>
991The other way around, you can flatten the archives inside higher level
992archives into simple archives:
993<pre>
994-injars  in.war
995-outjars out.jar
996</pre>
997<p>
998This configuration puts the processed contents of all jars inside
999<code>in.war</code> (plus any other contents of <code>in.war</code>) into
1000<code>out.jar</code>.
1001<p>
1002If you want to combine input jars (and/or wars, ears, zips, or directories)
1003into output jars (and/or wars, ears, zips, or directories), you can group the
1004<a href="usage.html#injars"><code>-injars</code></a> and <a
1005href="usage.html#outjars"><code>-outjars</code></a> options. For example:
1006<pre>
1007-injars base_in1.jar
1008-injars base_in2.jar
1009-injars base_in3.jar
1010-outjars base_out.jar
1011
1012-injars  extra_in.jar
1013-outjars extra_out.jar
1014</pre>
1015<p>
1016This configuration puts the processed results of all <code>base_in*.jar</code>
1017jars into <code>base_out.jar</code>, and the processed results of the
1018<code>extra_in.jar</code> into <code>extra_out.jar</code>. Note that only the
1019order of the options matters; the additional whitespace is just for clarity.
1020<p>
1021This grouping, archiving, and flattening can be arbitrarily complex. ProGuard
1022always tries to package output archives in a sensible way, reconstructing the
1023input entries as much as required.
1024
1025<a name="filtering">&nbsp;</a>
1026<h3>Filtering the input and the output</h3>
1027
1028If you want even greater control, you can add filters to the input and the
1029output, filtering out zips, ears, wars, jars, and/or ordinary files. For
1030example, if you want to disregard certain files from an input jar:
1031<pre>
1032-injars  in.jar(!images/**)
1033-outjars out.jar
1034</pre>
1035<p>
1036This configuration removes any files in the <code>images</code> directory and
1037its subdirectories.
1038<p>
1039Such filters can be convenient for avoiding warnings about duplicate files in
1040the output. For example, only keeping the manifest file from a first input jar:
1041<pre>
1042-injars  in1.jar
1043-injars  in2.jar(!META-INF/MANIFEST.MF)
1044-injars  in3.jar(!META-INF/MANIFEST.MF)
1045-outjars out.jar
1046</pre>
1047<p>
1048Another useful application is speeding up the processing by ProGuard, by
1049disregarding a large number of irrelevant classes in the runtime library jar:
1050<pre>
1051-libraryjars &lt;java.home&gt;/lib/rt.jar(java/**,javax/**)
1052</pre>
1053<p>
1054The filter makes ProGuard disregard <code>com.sun.**</code> classes, for
1055instance , which don't affect the processing of ordinary applications.
1056<p>
1057It is also possible to filter the jars (and/or wars, ears, zips) themselves,
1058based on their names. For example:
1059<pre>
1060-injars  in(**/acme_*.jar;)
1061-outjars out.jar
1062</pre>
1063<p>
1064Note the semi-colon in the filter; the filter in front of it applies to jar
1065names. In this case, only <code>acme_*.jar</code> jars are read from the
1066directory <code>in</code> and its subdirectories. Filters for war names, ear
1067names, and zip names can be prefixed with additional semi-colons. All types of
1068filters can be combined. They are orthogonal.
1069<p>
1070On the other hand, you can also filter the output, in order to control what
1071content goes where. For example:
1072<pre>
1073-injars  in.jar
1074-outjars code_out.jar(**.class)
1075-outjars resources_out.jar
1076</pre>
1077<p>
1078This configuration splits the processed output, sending <code>**.class</code>
1079files to <code>code_out.jar</code>, and all remaining files to
1080<code>resources_out.jar</code>.
1081<p>
1082Again, the filtering can be arbitrarily complex, especially when combined with
1083the grouping of input and output.
1084
1085<a name="multiple">&nbsp;</a>
1086<h3>Processing multiple applications at once</h3>
1087You can process several dependent or independent applications (or applets,
1088midlets,...) in one go, in order to save time and effort. ProGuard's input and
1089output handling offers various ways to keep the output nicely structured.
1090<p>
1091The easiest way is to specify your input jars (and/or wars, ears, zips, and
1092directories) and a single output directory. ProGuard will then reconstruct the
1093input in this directory, using the original jar names. For example, showing
1094just the input and output options:
1095<pre>
1096-injars  application1.jar
1097-injars  application2.jar
1098-injars  application3.jar
1099-outjars processed_applications
1100</pre>
1101<p>
1102After processing, the directory <code>processed_applications</code> will
1103contain the processed application jars, with their original names.
1104
1105<a name="incremental">&nbsp;</a>
1106<h3>Incremental obfuscation</h3>
1107After having <a href="#application">processed an application</a>, e.g.
1108ProGuard itself, you can still incrementally add other pieces of code that
1109depend on it, e.g. the ProGuard GUI:
1110<pre>
1111-injars       proguardgui.jar
1112-outjars      proguardgui_out.jar
1113-injars       proguard.jar
1114-outjars      proguard_out.jar
1115-libraryjars  &lt;java.home&gt;/lib/rt.jar
1116-applymapping proguard.map
1117
1118-keep public class proguard.gui.ProGuardGUI {
1119    public static void main(java.lang.String[]);
1120}
1121</pre>
1122<p>
1123We're reading both unprocessed jars as input. Their processed contents will go
1124to the respective output jars. The <a
1125href="usage.html#applymapping"><code>-applymapping</code></a> option then
1126makes sure the ProGuard part of the code gets the previously produced
1127obfuscation mapping. The final application will consist of the obfuscated
1128ProGuard jar and the additional obfuscated GUI jar.
1129<p>
1130The added code in this example is straightforward; it doesn't affect the
1131original code. The <code>proguard_out.jar</code> will be identical to the one
1132produced in the initial processing step. If you foresee adding more complex
1133extensions to your code, you should specify the options <a
1134href="usage.html#useuniqueclassmembernames"><code>-useuniqueclassmembernames</code></a>,
1135<a href="usage.html#dontshrink"><code>-dontshrink</code></a>, and <a
1136href="usage.html#dontoptimize"><code>-dontoptimize</code></a> <i>in the
1137original processing step</i>. These options ensure that the obfuscated base
1138jar will always remain usable without changes. You can then specify the base
1139jar as a library jar:
1140<pre>
1141-injars       proguardgui.jar
1142-outjars      proguardgui_out.jar
1143-libraryjars  proguard.jar
1144-libraryjars  &lt;java.home&gt;/lib/rt.jar
1145-applymapping proguard.map
1146
1147-keep public class proguard.gui.ProGuardGUI {
1148    public static void main(java.lang.String[]);
1149}
1150</pre>
1151
1152<a name="microedition">&nbsp;</a>
1153<h3>Preverifying class files for Java Micro Edition</h3>
1154Even if you're not interested in shrinking, optimizing, and obfuscating your
1155midlets, as shown in the <a href="#midlets">midlets example</a>, you can still
1156use ProGuard to preverify the class files for Java Micro Edition. ProGuard
1157produces slightly more compact results compared to the traditional external
1158preverifier.
1159<pre>
1160-injars      in.jar
1161-outjars     out.jar
1162-libraryjars /usr/local/java/wtk2.1/lib/midpapi20.jar
1163-libraryjars /usr/local/java/wtk2.1/lib/cldcapi11.jar
1164
1165-dontshrink
1166-dontoptimize
1167-dontobfuscate
1168
1169-microedition
1170</pre>
1171<p>
1172We're not processing the input, just making sure the class files are
1173preverified by targeting them at Java Micro Edition with the <a
1174href="usage.html#microedition"><code>-microedition</code></a> option. Note
1175that we don't need any <code>-keep</code> options to specify entry points; all
1176class files are simply preverified.
1177
1178<a name="upgrade">&nbsp;</a>
1179<h3>Upgrading class files to Java 6</h3>
1180The following options upgrade class files to Java 6, by updating their
1181internal version numbers and preverifying them. The class files can then be
1182loaded more efficiently by the Java 6 Virtual Machine.
1183<pre>
1184-injars      in.jar
1185-outjars     out.jar
1186-libraryjars &lt;java.home&gt;/lib/rt.jar
1187
1188-dontshrink
1189-dontoptimize
1190-dontobfuscate
1191
1192-target 1.6
1193</pre>
1194<p>
1195We're not processing the input, just retargeting the class files with the <a
1196href="usage.html#target"><code>-target</code></a> option. They will
1197automatically be preverified for Java 6 as a result. Note that we don't need
1198any <code>-keep</code> options to specify entry points; all class files are
1199simply updated and preverified.
1200
1201<a name="deadcode">&nbsp;</a>
1202<h3>Finding dead code</h3>
1203These options list unused classes, fields, and methods in the application
1204<code>mypackage.MyApplication</code>:
1205<pre>
1206-injars      in.jar
1207-libraryjars &lt;java.home&gt;/lib/rt.jar
1208
1209-dontoptimize
1210-dontobfuscate
1211-dontpreverify
1212-printusage
1213
1214-keep public class mypackage.MyApplication {
1215    public static void main(java.lang.String[]);
1216}
1217</pre>
1218<p>
1219We're not specifying an output jar, just printing out some results. We're
1220saving some processing time by skipping the other processing steps.
1221<p>
1222The java compiler inlines primitive constants and String constants
1223(<code>static final</code> fields). ProGuard would therefore list such fields
1224as not being used in the class files that it analyzes, even if they <i>are</i>
1225used in the source files. We can add a <a
1226href="usage.html#keepclassmembers"><code>-keepclassmembers</code></a> option
1227that keeps those fields a priori, in order to avoid having them listed:
1228<pre>
1229-keepclassmembers class * {
1230    static final %                *;
1231    static final java.lang.String *;
1232}
1233</pre>
1234
1235<a name="structure">&nbsp;</a>
1236<h3>Printing out the internal structure of class files</h3>
1237These options print out the internal structure of all class files in the input
1238jar:
1239<pre>
1240-injars in.jar
1241
1242-dontshrink
1243-dontoptimize
1244-dontobfuscate
1245-dontpreverify
1246
1247-dump
1248</pre>
1249<p>
1250Note how we don't need to specify the Java run-time jar, because we're not
1251processing the input jar at all.
1252
1253<a name="annotated">&nbsp;</a>
1254<h3>Using annotations to configure ProGuard</h3>
1255
1256The traditional ProGuard configuration allows to keep a clean separation
1257between the code and the configuration for shrinking, optimization, and
1258obfuscation. However, it is also possible to define specific annotations,
1259and then annotate the code to configure the processing.
1260<p>
1261You can find a set of such predefined annotations in the directory
1262<code>examples/annotations/lib</code> in the ProGuard distribution.
1263The annotation classes are defined in <code>annotations.jar</code>. The
1264corresponding ProGuard configuration (or meta-configuration, if you prefer)
1265is specified in <code>annotations.pro</code>. With these files, you can start
1266annotating your code. For instance, a java source file
1267<code>Application.java</code> can be annotated as follows:
1268<pre>
1269@KeepApplication
1270public class Application {
1271  ....
1272}
1273</pre>
1274<p>
1275The ProGuard configuration file for the application can then be simplified by
1276leveraging off these annotations:
1277<pre>
1278-injars      in.jar
1279-outjars     out.jar
1280-libraryjars &lt;java.home&gt;/lib/rt.jar
1281
1282-include lib/annotations.pro
1283</pre>
1284<p>
1285The annotations are effectively replacing the application-dependent
1286<code>-keep</code> options. You may still wish to add traditional
1287<code>-keep</code> options for processing <a href="#native">native
1288methods</a>, <a href="#enumerations">enumerations</a>, <a
1289href="#serializable">serializable classes</a>, and <a
1290href="#annotations">annotations</a>.
1291<p>
1292The directory <code>examples/annotations</code> contains more examples that
1293illustrate some of the possibilities.
1294<p>
1295
1296<hr>
1297<address>
1298Copyright &copy; 2002-2009
1299<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>.
1300</address>
1301</body>
1302</html>
1303