1<!doctype html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//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<script type="text/javascript" language="JavaScript">
12<!--
13if (window.self==window.top)
14  document.write('<a class="largebutton" target="_top" href="../index.html#manual/examples.html">ProGuard index</a> <a class="largebutton" target="_top" href="http://www.saikoa.com/dexguard">DexGuard</a> <a class="largebutton" target="_top" href="http://www.saikoa.com/">Saikoa</a> <a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>')
15//-->
16</script>
17<noscript>
18<a class="largebutton" target="_top"  href="../index.html#manual/examples.html">ProGuard index</a>
19<a class="largebutton" target="_top"  href="http://www.saikoa.com/dexguard">DexGuard</a>
20<a class="largebutton" target="_top"  href="http://www.saikoa.com/">Saikoa</a>
21<a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>
22</noscript>
23
24<h2>Examples</h2>
25
26Some typical useful configurations:
27<ol>
28<li><a href="#application">A typical application</a></li>
29<li><a href="#applet">A typical applet</a></li>
30<li><a href="#midlet">A typical midlet</a></li>
31<li><a href="#jcapplet">A typical Java Card applet</a></li>
32<li><a href="#xlet">A typical xlet</a></li>
33<li><a href="#androidactivity">A simple Android activity</a></li>
34<li><a href="#androidapplication">A complete Android application</a></li>
35<li><a href="#library">A typical library</a></li>
36<li><a href="#applications">All possible applications in the input jars</a></li>
37<li><a href="#applets">All possible applets in the input jars</a></li>
38<li><a href="#midlets">All possible midlets in the input jars</a></li>
39<li><a href="#jcapplets">All possible Java Card applets in the input jars</a></li>
40<li><a href="#xlets">All possible xlets in the input jars</a></li>
41<li><a href="#servlets">All possible servlets in the input jars</a></li>
42<li><a href="#scala">Scala applications with the Scala runtime</a></li>
43<li><a href="#native">Processing native methods</a></li>
44<li><a href="#callback">Processing callback methods</a></li>
45<li><a href="#enumerations">Processing enumeration classes</a></li>
46<li><a href="#serializable">Processing serializable classes</a></li>
47<li><a href="#beans">Processing bean classes</a></li>
48<li><a href="#annotations">Processing annotations</a></li>
49<li><a href="#database">Processing database drivers</a></li>
50<li><a href="#componentui">Processing ComponentUI classes</a></li>
51<li><a href="#rmi">Processing RMI code</a></li>
52<li><a href="#injection">Processing resource injection</a></li>
53<li><a href="#resourcefiles">Processing resource files</a></li>
54<li><a href="#manifestfiles">Processing manifest files</a></li>
55<li><a href="#stacktrace">Producing useful obfuscated stack traces</a></li>
56<li><a href="#repackaging">Obfuscating package names</a></li>
57<li><a href="#logging">Removing logging code</a></li>
58<li><a href="#restructuring">Restructuring the output archives</a></li>
59<li><a href="#filtering">Filtering the input and the output</a></li>
60<li><a href="#multiple">Processing multiple applications at once</a></li>
61<li><a href="#incremental">Incremental obfuscation</a></li>
62<li><a href="#microedition">Preverifying class files for Java Micro Edition</a></li>
63<li><a href="#upgrade">Upgrading class files to Java 6</a></li>
64<li><a href="#deadcode">Finding dead code</a></li>
65<li><a href="#structure">Printing out the internal structure of class files</a></li>
66<li><a href="#annotated">Using annotations to configure ProGuard</a></li>
67</ol>
68
69You can find some sample configuration files in the <code>examples</code>
70directory of the ProGuard distribution.
71
72<h3><a name="application">A typical application</a></h3>
73
74To shrink, optimize, and obfuscate a simple Java application, you typically
75create a configuration file like <code>myconfig.pro</code>, which can be used
76with
77<pre>
78bin/proguard @myconfig.pro
79</pre>
80<p>
81The configuration file specifies the input, the output, and the entry points
82of the application:
83<pre>
84-injars       myapplication.jar
85-outjars      myapplication_out.jar
86-libraryjars  &lt;java.home&gt;/lib/rt.jar
87-printmapping myapplication.map
88
89-keep public class mypackage.MyMain {
90    public static void main(java.lang.String[]);
91}
92</pre>
93<p>
94Note the use of the <code>&lt;java.home&gt;</code> system property. ProGuard
95automatically replaces it when parsing the file.
96<p>
97The <a href="usage.html#keep"><code>-keep</code></a> option specifies the
98entry point of the application that has to be preserved.
99The access modifiers <code>public</code> and <code>static</code> are not
100really required in this case, since we know a priori that the specified class
101and method have the proper access flags. It just looks more familiar this way.
102<p>
103Note that all type names are fully specified:
104<code>mypackage.MyMain</code> and <code>java.lang.String[]</code>.
105<p>
106We're writing out an obfuscation mapping file with <a
107href="usage.html#printmapping"><code>-printmapping</code></a>, for
108de-obfuscating any stack traces later on, or for incremental obfuscation of
109extensions.
110<p>
111We can further improve the results with a few additional options:
112<pre>
113-optimizationpasses 3
114-overloadaggressively
115-repackageclasses ''
116-allowaccessmodification
117</pre>
118These options are not required; they just shave off some extra bytes from the
119output jar, by performing up to 3 optimization passes, and by aggressively
120obfuscating class members and <a href="#repackaging">package names</a>.
121<p>
122In general, you might need a few additional options for processing <a
123href="#native">native methods</a>, <a href="#callback">callback methods</a>,
124<a href="#enumerations">enumerations</a>, <a href="#serializable">serializable
125classes</a>, <a href="#beans">bean classes</a>, <a
126href="#annotations">annotations</a>, and <a href="#resourcefiles">resource
127files</a>.
128
129<h3><a name="applet">A typical applet</a></h3>
130
131These options shrink, optimize, and obfuscate the applet
132<code>mypackage.MyApplet</code>:
133<pre>
134-injars      in.jar
135-outjars     out.jar
136-libraryjars &lt;java.home&gt;/lib/rt.jar
137
138-keep public class mypackage.MyApplet
139</pre>
140<p>
141The typical applet methods will be preserved automatically, since
142<code>mypackage.MyApplet</code> is an extension of the <code>Applet</code>
143class in the library <code>rt.jar</code>.
144<p>
145If applicable, you should add options for processing <a href="#native">native
146methods</a>, <a href="#callback">callback methods</a>, <a
147href="#enumerations">enumerations</a>, <a href="#serializable">serializable
148classes</a>, <a href="#beans">bean classes</a>, <a
149href="#annotations">annotations</a>, and <a href="#resourcefiles">resource
150files</a>.
151
152<h3><a name="midlet">A typical midlet</a></h3>
153
154These options shrink, optimize, obfuscate, and preverify the midlet
155<code>mypackage.MyMIDlet</code>:
156<pre>
157-injars      in.jar
158-outjars     out.jar
159-libraryjars /usr/local/java/wtk2.5.2/lib/midpapi20.jar
160-libraryjars /usr/local/java/wtk2.5.2/lib/cldcapi11.jar
161-overloadaggressively
162-repackageclasses ''
163-allowaccessmodification
164-microedition
165
166-keep public class mypackage.MyMIDlet
167</pre>
168<p>
169Note how we're now targeting the Java Micro Edition run-time environment of
170<code>midpapi20.jar</code> and <code>cldcapi11.jar</code>, instead of the Java
171Standard Edition run-time environment <code>rt.jar</code>. You can target
172other JME environments by picking the appropriate jars.
173<p>
174The typical midlet methods will be preserved automatically, since
175<code>mypackage.MyMIDlet</code> is an extension of the <code>MIDlet</code>
176class in the library <code>midpapi20.jar</code>.
177<p>
178The <a href="usage.html#microedition"><code>-microedition</code></a> option
179makes sure the class files are preverified for Java Micro Edition, producing
180compact <code>StackMap</code> attributes. It is no longer necessary to run an
181external preverifier.
182<p>
183Be careful if you do use the external <code>preverify</code> tool on a platform
184with a case-insensitive filing system, such as Windows. Because this tool
185unpacks your processed jars, you should then use ProGuard's <a
186href="usage.html#dontusemixedcaseclassnames"><code>-dontusemixedcaseclassnames</code></a>
187option.
188<p>
189If applicable, you should add options for processing <a href="#native">native
190methods</a> and <a href="#resourcefiles">resource files</a>.
191<p>
192Note that you will still have to adapt the midlet jar size in the
193corresponding jad file; ProGuard doesn't do that for you.
194
195<h3><a name="jcapplet">A typical Java Card applet</a></h3>
196
197These options shrink, optimize, and obfuscate the Java Card applet
198<code>mypackage.MyApplet</code>:
199<pre>
200-injars      in.jar
201-outjars     out.jar
202-libraryjars /usr/local/java/javacard2.2.2/lib/api.jar
203-dontwarn    java.lang.Class
204-overloadaggressively
205-repackageclasses ''
206-allowaccessmodification
207
208-keep public class mypackage.MyApplet
209</pre>
210<p>
211The configuration is very similar to the configuration for midlets, except that
212it now targets the Java Card run-time environment. This environment doesn't
213have java.lang.Class, so we're telling ProGuard not to worry about it.
214
215<h3><a name="xlet">A typical xlet</a></h3>
216
217These options shrink, optimize, and obfuscate the xlet
218<code>mypackage.MyXlet</code>:
219<pre>
220-injars      in.jar
221-outjars     out.jar
222-libraryjars /usr/local/java/jtv1.1/javatv.jar
223-libraryjars /usr/local/java/cdc1.1/lib/cdc.jar
224-libraryjars /usr/local/java/cdc1.1/lib/btclasses.zip
225-overloadaggressively
226-repackageclasses ''
227-allowaccessmodification
228
229-keep public class mypackage.MyXlet
230</pre>
231<p>
232The configuration is very similar to the configuration for midlets, except that
233it now targets the CDC run-time environment with the Java TV API.
234
235<h3><a name="androidactivity">A simple Android activity</a></h3>
236
237These options shrink, optimize, and obfuscate the single Android
238activity <code>mypackage.MyActivity</code>:
239<pre>
240-injars      bin/classes
241-outjars     bin/classes-processed.jar
242-libraryjars /usr/local/java/android-sdk/platforms/android-9/android.jar
243
244-dontpreverify
245-repackageclasses ''
246-allowaccessmodification
247-optimizations !code/simplification/arithmetic
248
249-keep public class mypackage.MyActivity
250</pre>
251<p>
252We're targeting the Android run-time and keeping the activity as an entry
253point.
254<p>
255Preverification is irrelevant for the dex compiler and the Dalvik VM, so we
256can switch it off with the
257<a href="usage.html#dontpreverify"><code>-dontpreverify</code></a> option.
258<p>
259The <a href="usage.html#optimizations"><code>-optimizations</code></a> option
260disables some arithmetic simplifications that Dalvik 1.0 and 1.5 can't handle.
261Note that the Dalvik VM also can't
262handle <a href="usage.html#overloadaggressively">aggressive overloading</a>
263(of static fields).
264<p>
265If applicable, you should add options for processing <a href="#native">native
266methods</a>, <a href="#callback">callback methods</a>,
267<a href="#enumerations">enumerations</a>,
268<a href="#annotations">annotations</a>, and
269<a href="#resourcefiles">resource files</a>.
270
271<h3><a name="androidapplication">A complete Android application</a></h3>
272
273<img class="float" src="attention.gif" width="64" height="64" alt="attention"
274/> The standard build processes of the Android SDK (with Ant, Gradle, Android
275Studio, and Eclipse) already integrate ProGuard with all the proper settings.
276You only need to enable ProGuard by uncommenting the line
277"<code>proguard.config=.....</code>" in the
278file <code>project.properties</code> (created or updated by Android SDK
279revision 17 or higher) or by adapting your <code>build.gradle</code> file. You
280then <em>don't</em> need any of the configuration below.
281<p>
282Notes:
283<ul>
284<li>In case of problems, you may want to check if the configuration files that
285    are listed on this line (<code>proguard-project.txt</code>,...) contain
286    the necessary settings for your application.</li>
287<li>Android SDK revision 20 and higher have a different configuration file for
288    enabling optimization:
289    <code>${sdk.dir}/tools/proguard/proguard-android-optimize.txt</code>
290    instead of the default
291    <code>${sdk.dir}/tools/proguard/proguard-android.txt</code>.</li>
292<li>The build processes are already setting the necessary program jars,
293    library jars, and output jars for you &mdash; don't specify them again.</li>
294<li>If you get warnings about missing referenced classes: it's all too common
295    that libraries refer to missing classes.
296    See <a href="troubleshooting.html#unresolvedclass">"Warning: can't find
297    referenced class"</a> in the Troubleshooting section.</li>
298</ul>
299<p>
300For more information, you can consult the official <a target="other"
301href="http://developer.android.com/guide/developing/tools/proguard.html">Developer
302Guide</a> in the Android SDK.
303<p>
304If you're constructing a build process <em>from scratch</em>: these options
305shrink, optimize, and obfuscate all public activities, services, broadcast
306receivers, and content providers from the compiled classes and external
307libraries:
308<pre>
309-injars      bin/classes
310-injars      libs
311-outjars     bin/classes-processed.jar
312-libraryjars /usr/local/java/android-sdk/platforms/android-9/android.jar
313
314-dontpreverify
315-repackageclasses ''
316-allowaccessmodification
317-optimizations !code/simplification/arithmetic
318-keepattributes *Annotation*
319
320-keep public class * extends android.app.Activity
321-keep public class * extends android.app.Application
322-keep public class * extends android.app.Service
323-keep public class * extends android.content.BroadcastReceiver
324-keep public class * extends android.content.ContentProvider
325
326-keep public class * extends android.view.View {
327    public &lt;init&gt;(android.content.Context);
328    public &lt;init&gt;(android.content.Context, android.util.AttributeSet);
329    public &lt;init&gt;(android.content.Context, android.util.AttributeSet, int);
330    public void set*(...);
331}
332
333-keepclasseswithmembers class * {
334    public &lt;init&gt;(android.content.Context, android.util.AttributeSet);
335}
336
337-keepclasseswithmembers class * {
338    public &lt;init&gt;(android.content.Context, android.util.AttributeSet, int);
339}
340
341-keepclassmembers class * extends android.content.Context {
342   public void *(android.view.View);
343   public void *(android.view.MenuItem);
344}
345
346-keepclassmembers class * implements android.os.Parcelable {
347    static ** CREATOR;
348}
349
350-keepclassmembers class **.R$* {
351    public static &lt;fields&gt;;
352}
353
354-keepclassmembers class * {
355    @android.webkit.JavascriptInterface &lt;methods&gt;;
356}
357</pre>
358<p>
359Most importantly, we're keeping all fundamental classes that may be referenced
360by the <code>AndroidManifest.xml</code> file of the application. If your
361manifest file contains other classes and methods, you may have to specify
362those as well.
363<p>
364We're keeping annotations, since they might be used by custom
365<code>RemoteViews</code>.
366<p>
367We're keeping any custom <code>View</code> extensions and other classes with
368typical constructors, since they might be referenced from XML layout files.
369<p>
370We're also keeping possible <code>onClick</code> handlers in
371custom <code>Context</code> extensions, since they might be referenced from
372XML layout files.
373<p>
374We're also keeping the required static fields in <code>Parcelable</code>
375implementations, since they are accessed by introspection.
376<p>
377We're keeping the static fields of referenced inner classes of auto-generated
378 <code>R</code> classes, just in case your code is accessing those fields by
379introspection. Note that the compiler already inlines primitive fields, so
380ProGuard can generally remove all these classes entirely anyway (because the
381classes are not referenced and therefore not required).
382<p>
383Finally, we're keeping annotated Javascript interface methods, so they can be
384exported and accessed by their original names. Javascript interface methods
385that are not annotated (in code targeted at Android versions older than 4.2)
386still need to be preserved manually.
387<p>
388If you're using additional Google APIs, you'll have to specify
389those as well, for instance:
390<pre>
391-libraryjars /usr/local/android-sdk/add-ons/google_apis-7_r01/libs/maps.jar
392</pre>
393<p>
394If you're using Google's optional License Verification Library, you can
395obfuscate its code along with your own code. You do have to preserve
396its <code>ILicensingService</code> interface for the library to work:
397<pre>
398-keep public interface com.android.vending.licensing.ILicensingService
399</pre>
400<p>
401If you're using the Android Compatibility library, you should add the
402following line, to let ProGuard know it's ok that the library references some
403classes that are not available in all versions of the API:
404<pre>
405-dontwarn android.support.**
406</pre>
407<p>
408If applicable, you should add options for processing <a href="#native">native
409methods</a>, <a href="#callback">callback methods</a>,
410<a href="#enumerations">enumerations</a>,
411and <a href="#resourcefiles">resource files</a>. You may also want to add
412options for producing <a href="#stacktrace">useful stack traces</a> and
413to <a href="#logging">remove logging</a>. You can find a complete sample
414configuration in <code>examples/android.pro</code> in the ProGuard
415distribution.
416
417<h3><a name="library">A typical library</a></h3>
418
419These options shrink, optimize, and obfuscate an entire library, keeping all
420public and protected classes and class members, native method names, and
421serialization code. The processed version of the library can then still be
422used as such, for developing code based on its public API.
423<pre>
424-injars       in.jar
425-outjars      out.jar
426-libraryjars  &lt;java.home&gt;/lib/rt.jar
427-printmapping out.map
428
429-keepparameternames
430-renamesourcefileattribute SourceFile
431-keepattributes Exceptions,InnerClasses,Signature,Deprecated,
432                SourceFile,LineNumberTable,*Annotation*,EnclosingMethod
433
434-keep public class * {
435    public protected *;
436}
437
438-keepclassmembernames class * {
439    java.lang.Class class$(java.lang.String);
440    java.lang.Class class$(java.lang.String, boolean);
441}
442
443-keepclasseswithmembernames,includedescriptorclasses class * {
444    native &lt;methods&gt;;
445}
446
447-keepclassmembers,allowoptimization enum * {
448    public static **[] values();
449    public static ** valueOf(java.lang.String);
450}
451
452-keepclassmembers class * implements java.io.Serializable {
453    static final long serialVersionUID;
454    private static final java.io.ObjectStreamField[] serialPersistentFields;
455    private void writeObject(java.io.ObjectOutputStream);
456    private void readObject(java.io.ObjectInputStream);
457    java.lang.Object writeReplace();
458    java.lang.Object readResolve();
459}
460</pre>
461<p>
462This configuration should preserve everything we'll ever want to access in the
463library. Only if there are any other non-public classes or methods that are
464invoked dynamically, they should be specified using additional <a
465href="usage.html#keep"><code>-keep</code></a> options.
466<p>
467The <a
468href="usage.html#keepclassmembernames"><code>-keepclassmembernames</code></a>
469option for the <code>class$</code> methods is not strictly necessary. These
470methods are inserted by the <code>javac</code> compiler and the
471<code>jikes</code> compiler respectively, in JDK 1.2 and older, to implement
472the <code>.class</code> construct. ProGuard will automatically detect them and
473deal with them, even when their names have been obfuscated. However, other
474obfuscators may rely on the original method names. It may therefore be helpful
475to preserve them, in case these other obfuscators are ever used for further
476obfuscation of the library.
477<p>
478The "Exceptions" attribute has to be preserved, so the compiler knows which
479exceptions methods may throw.
480<p>
481The "InnerClasses" attribute (or more precisely, its source name part) has to
482be preserved too, for any inner classes that can be referenced from outside the
483library. The <code>javac</code> compiler would be unable to find the inner
484classes otherwise.
485<p>
486The "Signature" attribute is required to be able to access generic types when
487compiling in JDK 5.0 and higher.
488<p>
489The <a href="usage.html#keepparameternames"><code>-keepparameternames</code></a>
490option keeps the parameter names in the "LocalVariableTable" and
491"LocalVariableTypeTable" attributes of public library methods. Some IDEs can
492present these names to the developers who use the library.
493<p>
494Finally, we're keeping the "Deprecated" attribute and the attributes for
495producing <a href="#stacktrace">useful stack traces</a>.
496<p>
497We've also added some options for for processing <a href="#native">native
498methods</a>, <a href="#enumerations">enumerations</a>, <a
499href="#serializable">serializable classes</a>, and <a
500href="#annotations">annotations</a>, which are all discussed in their
501respective examples.
502
503<h3><a name="applications">All possible applications in the input jars</a></h3>
504
505These options shrink, optimize, and obfuscate all public applications in
506<code>in.jar</code>:
507<pre>
508-injars      in.jar
509-outjars     out.jar
510-libraryjars &lt;java.home&gt;/lib/rt.jar
511-printseeds
512
513-keepclasseswithmembers public class * {
514    public static void main(java.lang.String[]);
515}
516</pre>
517<p>
518Note the use of <a
519href="usage.html#keepclasseswithmembers"><code>-keepclasseswithmembers</code></a>.
520We don't want to preserve all classes, just all classes that have main
521methods, and those methods.
522<p>
523The <a href="usage.html#printseeds"><code>-printseeds</code></a> option prints
524out which classes exactly will be preserved, so we know for sure we're getting
525what we want.
526<p>
527If applicable, you should add options for processing <a href="#native">native
528methods</a>, <a href="#callback">callback methods</a>, <a
529href="#enumerations">enumerations</a>, <a href="#serializable">serializable
530classes</a>, <a href="#beans">bean classes</a>, <a
531href="#annotations">annotations</a>, and <a href="#resourcefiles">resource
532files</a>.
533
534<h3><a name="applets">All possible applets in the input jars</a></h3>
535
536These options shrink, optimize, and obfuscate all public applets in
537<code>in.jar</code>:
538<pre>
539-injars      in.jar
540-outjars     out.jar
541-libraryjars &lt;java.home&gt;/lib/rt.jar
542-printseeds
543
544-keep public class * extends java.applet.Applet
545</pre>
546<p>
547We're simply keeping all classes that extend the <code>Applet</code> class.
548<p>
549Again, the <a href="usage.html#printseeds"><code>-printseeds</code></a> option
550prints out which applets exactly will be preserved.
551<p>
552If applicable, you should add options for processing <a href="#native">native
553methods</a>, <a href="#callback">callback methods</a>, <a
554href="#enumerations">enumerations</a>, <a href="#serializable">serializable
555classes</a>, <a href="#beans">bean classes</a>, <a
556href="#annotations">annotations</a>, and <a href="#resourcefiles">resource
557files</a>.
558
559<h3><a name="midlets">All possible midlets in the input jars</a></h3>
560
561These options shrink, optimize, obfuscate, and preverify all public midlets in
562<code>in.jar</code>:
563<pre>
564-injars      in.jar
565-outjars     out.jar
566-libraryjars /usr/local/java/wtk2.5.2/lib/midpapi20.jar
567-libraryjars /usr/local/java/wtk2.5.2/lib/cldcapi11.jar
568-overloadaggressively
569-repackageclasses ''
570-allowaccessmodification
571-microedition
572-printseeds
573
574-keep public class * extends javax.microedition.midlet.MIDlet
575</pre>
576<p>
577We're simply keeping all classes that extend the <code>MIDlet</code> class.
578<p>
579The <a href="usage.html#microedition"><code>-microedition</code></a> option
580makes sure the class files are preverified for Java Micro Edition, producing
581compact <code>StackMap</code> attributes. It is no longer necessary to run an
582external preverifier.
583<p>
584Be careful if you do use the external <code>preverify</code> tool on a platform
585with a case-insensitive filing system, such as Windows. Because this tool
586unpacks your processed jars, you should then use ProGuard's <a
587href="usage.html#dontusemixedcaseclassnames"><code>-dontusemixedcaseclassnames</code></a>
588option.
589<p>
590The <a href="usage.html#printseeds"><code>-printseeds</code></a> option prints
591out which midlets exactly will be preserved.
592<p>
593If applicable, you should add options for processing <a href="#native">native
594methods</a> and <a href="#resourcefiles">resource files</a>.
595<p>
596Note that you will still have to adapt the midlet jar size in the
597corresponding jad file; ProGuard doesn't do that for you.
598
599<h3><a name="jcapplets">All possible Java Card applets in the input jars</a></h3>
600
601These options shrink, optimize, and obfuscate all public Java Card applets in
602<code>in.jar</code>:
603<pre>
604-injars      in.jar
605-outjars     out.jar
606-libraryjars /usr/local/java/javacard2.2.2/lib/api.jar
607-dontwarn    java.lang.Class
608-overloadaggressively
609-repackageclasses ''
610-allowaccessmodification
611-printseeds
612
613-keep public class * implements javacard.framework.Applet
614</pre>
615<p>
616We're simply keeping all classes that implement the <code>Applet</code>
617interface.
618<p>
619The <a href="usage.html#printseeds"><code>-printseeds</code></a> option prints
620out which applets exactly will be preserved.
621
622<h3><a name="xlets">All possible xlets in the input jars</a></h3>
623
624These options shrink, optimize, and obfuscate all public xlets in
625<code>in.jar</code>:
626<pre>
627-injars      in.jar
628-outjars     out.jar
629-libraryjars /usr/local/java/jtv1.1/javatv.jar
630-libraryjars /usr/local/java/cdc1.1/lib/cdc.jar
631-libraryjars /usr/local/java/cdc1.1/lib/btclasses.zip
632-overloadaggressively
633-repackageclasses ''
634-allowaccessmodification
635-printseeds
636
637-keep public class * implements javax.tv.xlet.Xlet
638</pre>
639<p>
640We're simply keeping all classes that implement the <code>Xlet</code> interface.
641<p>
642The <a href="usage.html#printseeds"><code>-printseeds</code></a> option prints
643out which xlets exactly will be preserved.
644
645<h3><a name="servlets">All possible servlets in the input jars</a></h3>
646
647These options shrink, optimize, and obfuscate all public servlets in
648<code>in.jar</code>:
649<pre>
650-injars      in.jar
651-outjars     out.jar
652-libraryjars &lt;java.home&gt;/lib/rt.jar
653-libraryjars /usr/local/java/servlet/servlet.jar
654-printseeds
655
656-keep public class * implements javax.servlet.Servlet
657</pre>
658<p>
659Keeping all servlets is very similar to keeping all applets. The servlet API
660is not part of the standard run-time jar, so we're specifying it as a library.
661Don't forget to use the right path name.
662<p>
663We're then keeping all classes that implement the <code>Servlet</code>
664interface. We're using the <code>implements</code> keyword because it looks
665more familiar in this context, but it is equivalent to <code>extends</code>,
666as far as ProGuard is concerned.
667<p>
668The <a href="usage.html#printseeds"><code>-printseeds</code></a> option prints
669out which servlets exactly will be preserved.
670<p>
671If applicable, you should add options for processing <a href="#native">native
672methods</a>, <a href="#callback">callback methods</a>, <a
673href="#enumerations">enumerations</a>, <a href="#serializable">serializable
674classes</a>, <a href="#beans">bean classes</a>, <a
675href="#annotations">annotations</a>, and <a href="#resourcefiles">resource
676files</a>.
677
678<h3><a name="scala">Scala applications with the Scala runtime</a></h3>
679
680These options shrink, optimize, and obfuscate all public Scala applications in
681<code>in.jar</code>:
682<pre>
683-injars      in.jar
684-injars      /usr/local/java/scala-2.9.1/lib/scala-library.jar
685-outjars     out.jar
686-libraryjars &lt;java.home&gt;/lib/rt.jar
687
688-dontwarn scala.**
689
690-keepclasseswithmembers public class * {
691    public static void main(java.lang.String[]);
692}
693
694-keep class * implements org.xml.sax.EntityResolver
695
696-keepclassmembers class * {
697    ** MODULE$;
698}
699
700-keepclassmembernames class scala.concurrent.forkjoin.ForkJoinPool {
701    long eventCount;
702    int  workerCounts;
703    int  runControl;
704    scala.concurrent.forkjoin.ForkJoinPool$WaitQueueNode syncStack;
705    scala.concurrent.forkjoin.ForkJoinPool$WaitQueueNode spareStack;
706}
707
708-keepclassmembernames class scala.concurrent.forkjoin.ForkJoinWorkerThread {
709    int base;
710    int sp;
711    int runState;
712}
713
714-keepclassmembernames class scala.concurrent.forkjoin.ForkJoinTask {
715    int status;
716}
717
718-keepclassmembernames class scala.concurrent.forkjoin.LinkedTransferQueue {
719    scala.concurrent.forkjoin.LinkedTransferQueue$PaddedAtomicReference head;
720    scala.concurrent.forkjoin.LinkedTransferQueue$PaddedAtomicReference tail;
721    scala.concurrent.forkjoin.LinkedTransferQueue$PaddedAtomicReference cleanMe;
722}
723</pre>
724<p>
725The configuration is essentially the same as
726for <a href="#applications">processing applications</a>, because Scala is
727compiled to ordinary Java bytecode. However, the example processes the Scala
728runtime library as well. The processed jar can be an order of magnitude
729smaller and a few times faster than the original code (for the Scala code
730examples, for instance).
731<p>
732The <a href="usage.html#dontwarn"><code>-dontwarn</code></a> option tells
733ProGuard not to complain about some artefacts in the Scala runtime, the way it
734is compiled by the <code>scalac</code> compiler (at least in Scala 2.9.1 and
735older). Note that this option should always be used with care.
736<p>
737The additional <a href="usage.html#keepoverview"><code>-keep</code></a>
738options make sure that some classes and some fields that are accessed by means
739of introspection are not removed or renamed.
740<p>
741If applicable, you should add options for processing <a href="#native">native
742methods</a>, <a href="#callback">callback methods</a>, <a
743href="#enumerations">enumerations</a>, <a href="#serializable">serializable
744classes</a>, <a href="#beans">bean classes</a>, <a
745href="#annotations">annotations</a>, and <a href="#resourcefiles">resource
746files</a>.
747<h3><a name="native">Processing native methods</a></h3>
748
749If your application, applet, servlet, library, etc., contains native methods,
750you'll want to preserve their names and their classes' names, so they can
751still be linked to the native library. The following additional option will
752ensure that:
753<pre>
754-keepclasseswithmembernames,includedescriptorclasses class * {
755    native &lt;methods&gt;;
756}
757</pre>
758<p>
759Note the use of
760<a href="usage.html#keepclasseswithmembernames"><code>-keepclasseswithmembernames</code></a>.
761We don't want to preserve all classes or all native methods; we just want to
762keep the relevant names from being obfuscated. The modifier
763<a href="usage.html#includedescriptorclasses">includedescriptorclasses</a>
764additionally makes sure that the return types and parameter types aren't
765renamed either, so the entire signatures remain compatible with the native
766libraries.
767<p>
768ProGuard doesn't look at your native code, so it won't automatically preserve
769the classes or class members that are invoked by the native code. These are
770entry points, which you'll have to specify explicitly.  <a
771href="callback">Callback methods</a> are discussed below as a typical example.
772
773<h3><a name="callback">Processing callback methods</a></h3>
774
775If your application, applet, servlet, library, etc., contains callback
776methods, which are called from external code (native code, scripts,...),
777you'll want to preserve them, and probably their classes too. They are just
778entry points to your code, much like, say, the main method of an application.
779If they aren't preserved by other <code>-keep</code> options, something like
780the following option will keep the callback class and method:
781<pre>
782-keep class mypackage.MyCallbackClass {
783    void myCallbackMethod(java.lang.String);
784}
785</pre>
786<p>
787This will preserve the given class and method from being removed or renamed.
788
789<h3><a name="enumerations">Processing enumeration classes</a></h3>
790
791If your application, applet, servlet, library, etc., contains enumeration
792classes, you'll have to preserve some special methods. Enumerations were
793introduced in Java 5. The java compiler translates enumerations into classes
794with a special structure. Notably, the classes contain implementations of some
795static methods that the run-time environment accesses by introspection (Isn't
796that just grand? Introspection is the self-modifying code of a new
797generation). You have to specify these explicitly, to make sure they aren't
798removed or obfuscated:
799<pre>
800-keepclassmembers,allowoptimization enum * {
801    public static **[] values();
802    public static ** valueOf(java.lang.String);
803}
804</pre>
805
806<h3><a name="serializable">Processing serializable classes</a></h3>
807
808More complex applications, applets, servlets, libraries, etc., may contain
809classes that are serialized. Depending on the way in which they are used, they
810may require special attention:
811<ul>
812
813<li>Often, serialization is simply a means of transporting data, without
814    long-term storage. Classes that are shrunk and obfuscated should then
815    continue to function fine with the following additional options:
816
817<pre>
818-keepclassmembers class * implements java.io.Serializable {
819    private static final java.io.ObjectStreamField[] serialPersistentFields;
820    private void writeObject(java.io.ObjectOutputStream);
821    private void readObject(java.io.ObjectInputStream);
822    java.lang.Object writeReplace();
823    java.lang.Object readResolve();
824}
825</pre>
826<p>
827
828    The <a
829    href="usage.html#keepclassmembers"><code>-keepclassmembers</code></a>
830    option makes sure that any serialization methods are kept. By using this
831    option instead of the basic <code>-keep</code> option, we're not
832    forcing preservation of <i>all</i> serializable classes, just preservation
833    of the listed members of classes that are actually used.</li>
834
835<li>Sometimes, the serialized data are stored, and read back later into newer
836    versions of the serializable classes. One then has to take care the classes
837    remain compatible with their unprocessed versions and with future
838    processed versions. In such cases, the relevant classes will most likely
839    have <code>serialVersionUID</code> fields. The following options should
840    then be sufficient to ensure compatibility over time:
841
842<pre>
843-keepnames class * implements java.io.Serializable
844
845-keepclassmembers class * implements java.io.Serializable {
846    static final long serialVersionUID;
847    private static final java.io.ObjectStreamField[] serialPersistentFields;
848    !static !transient &lt;fields&gt;;
849    private void writeObject(java.io.ObjectOutputStream);
850    private void readObject(java.io.ObjectInputStream);
851    java.lang.Object writeReplace();
852    java.lang.Object readResolve();
853}
854</pre>
855<p>
856
857    The <code>serialVersionUID</code> and <code>serialPersistentFields</code>
858    lines makes sure those fields are preserved, if they are present.
859    The <code>&lt;fields&gt;</code> line preserves all non-static,
860    non-transient fields, with their original names. The introspection of the
861    serialization process and the de-serialization process will then find
862    consistent names.</li>
863
864<li>Occasionally, the serialized data have to remain compatible, but the
865    classes involved lack <code>serialVersionUID</code> fields. I imagine the
866    original code will then be hard to maintain, since the serial version UID
867    is then computed from a list of features the serializable class. Changing
868    the class ever so slightly may change the computed serial version UID. The
869    list of features is specified in the section on <a
870    href="http://docs.oracle.com/javase/8/docs/platform/serialization/spec/class.html#a4100">Stream
871    Unique Identifiers</a> of Sun's <a
872    href="http://docs.oracle.com/javase/8/docs/platform/serialization/spec/serialTOC.html">Java
873    Object Serialization Specification</a>. The following directives should at
874    least partially ensure compatibility with the original classes:
875
876<pre>
877-keepnames class * implements java.io.Serializable
878
879-keepclassmembers class * implements java.io.Serializable {
880    static final long serialVersionUID;
881    private static final java.io.ObjectStreamField[] serialPersistentFields;
882    !static !transient &lt;fields&gt;;
883    !private &lt;fields&gt;;
884    !private &lt;methods&gt;;
885    private void writeObject(java.io.ObjectOutputStream);
886    private void readObject(java.io.ObjectInputStream);
887    java.lang.Object writeReplace();
888    java.lang.Object readResolve();
889}
890</pre>
891<p>
892
893    The new options force preservation of the elements involved in the UID
894    computation. In addition, the user will have to manually specify all
895    interfaces of the serializable classes (using something like "<code>-keep
896    interface MyInterface</code>"), since these names are also used when
897    computing the UID. A fast but sub-optimal alternative would be simply
898    keeping all interfaces with "<code>-keep interface *</code>".</li>
899
900<li>In the rare event that you are serializing lambda expressions in Java 8 or
901    higher, you need to preserve some methods and adapt the hard-coded names
902    of the classes in which they occur:
903
904<pre>
905-keepclassmembers class * {
906    private static synthetic java.lang.Object $deserializeLambda$(java.lang.invoke.SerializedLambda);
907}
908
909-keepclassmembernames class * {
910    private static synthetic *** lambda$*(...);
911}
912
913-adaptclassstrings com.example.Test
914</pre>
915<p>
916
917    This should satisfy the reflection in the deserialization code of the
918    Java run-time.
919
920</ul>
921<p>
922
923Note that the above options may preserve more classes and class members
924than strictly necessary. For instance, a large number of classes may implement
925the <code>Serialization</code> interface, yet only a small number may actually
926ever be serialized. Knowing your application and tuning the configuration
927often produces more compact results.
928
929<h3><a name="beans">Processing bean classes</a></h3>
930
931If your application, applet, servlet, library, etc., makes extensive use of
932introspection on bean classes to find bean editor classes, or getter and
933setter methods, then configuration may become painful. There's not much else
934you can do than making sure the bean class names, or the getter and setter
935names don't change. For instance:
936<pre>
937-keep public class mypackage.MyBean {
938    public void setMyProperty(int);
939    public int getMyProperty();
940}
941
942-keep public class mypackage.MyBeanEditor
943</pre>
944<p>
945If there are too many elements to list explicitly, wildcards in class names
946and method signatures might be helpful. This example preserves all possible
947setters and getters in classes in the package <code>mybeans</code>:
948<pre>
949-keep class mybeans.** {
950    void set*(***);
951    void set*(int, ***);
952
953    boolean is*();
954    boolean is*(int);
955
956    *** get*();
957    *** get*(int);
958}
959</pre>
960<p>
961The '<code>***</code>' wildcard matches any type (primitive or non-primitive,
962array or non-array). The methods with the '<code>int</code>' arguments matches
963properties that are lists.
964
965<h3><a name="annotations">Processing annotations</a></h3>
966
967If your application, applet, servlet, library, etc., uses annotations, you may
968want to preserve them in the processed output. Annotations are represented by
969attributes that have no direct effect on the execution of the code. However,
970their values can be retrieved through introspection, allowing developers to
971adapt the execution behavior accordingly. By default, ProGuard treats
972annotation attributes as optional, and removes them in the obfuscation step.
973If they are required, you'll have to specify this explicitly:
974<pre>
975-keepattributes *Annotation*
976</pre>
977<p>
978For brevity, we're specifying a wildcarded attribute name, which will match
979<code>RuntimeVisibleAnnotations</code>,
980<code>RuntimeInvisibleAnnotations</code>,
981<code>RuntimeVisibleParameterAnnotations</code>,
982<code>RuntimeInvisibleParameterAnnotations</code>, and
983<code>AnnotationDefault</code>. Depending on the purpose of the processed
984code, you could refine this selection, for instance not keeping the run-time
985invisible annotations (which are only used at compile-time).
986<p>
987Some code may make further use of introspection to figure out the enclosing
988methods of anonymous inner classes. In that case, the corresponding attribute
989has to be preserved as well:
990<pre>
991-keepattributes EnclosingMethod
992</pre>
993
994<h3><a name="database">Processing database drivers</a></h3>
995
996Database drivers are implementations of the <code>Driver</code> interface.
997Since they are often created dynamically, you may want to preserve any
998implementations that you are processing as entry points:
999<pre>
1000-keep class * implements java.sql.Driver
1001</pre>
1002<p>
1003This option also gets rid of the note that ProGuard prints out about
1004<code>(java.sql.Driver)Class.forName</code> constructs, if you are
1005instantiating a driver in your code (without necessarily implementing any
1006drivers yourself).
1007
1008<h3><a name="componentui">Processing ComponentUI classes</a></h3>
1009
1010Swing UI look and feels are implemented as extensions of the
1011<code>ComponentUI</code> class. For some reason, these have to contain a
1012static method <code>createUI</code>, which the Swing API invokes using
1013introspection. You should therefore always preserve the method as an entry
1014point, for instance like this:
1015<pre>
1016-keep class * extends javax.swing.plaf.ComponentUI {
1017    public static javax.swing.plaf.ComponentUI createUI(javax.swing.JComponent);
1018}
1019</pre>
1020<p>
1021This option also keeps the classes themselves.
1022
1023<h3><a name="rmi">Processing RMI code</a></h3>
1024
1025Reportedly, the easiest way to handle RMI code is to process the code with
1026ProGuard first and then invoke the <code>rmic</code> tool. If that is not
1027possible, you may want to try something like this:
1028<pre>
1029-keepattributes Exceptions
1030
1031-keep interface * extends java.rmi.Remote {
1032    &lt;methods&gt;;
1033}
1034
1035-keep class * implements java.rmi.Remote {
1036    &lt;init&gt;(java.rmi.activation.ActivationID, java.rmi.MarshalledObject);
1037}
1038</pre>
1039<p>
1040The first <code>-keep</code> option keeps all your Remote interfaces and their
1041methods. The second one keeps all the implementations, along with their
1042particular RMI constructors, if any.
1043<p>
1044The <code>Exceptions</code> attribute has to be kept too, because the RMI
1045handling code performs introspection to check whether the method signatures
1046are compatible.
1047
1048<h3><a name="injection">Processing resource injection</a></h3>
1049
1050If your application is using JEE-style resource injection, the application
1051container will automatically assign instances of resource classes to fields and
1052methods that are annotated with <code>@Resource</code>. The container applies
1053introspection, even accessing private class members directly. It typically
1054constructs a resource name based on the type name and the class member name.
1055We then have to avoid that such class members are removed or renamed:
1056<pre>
1057-keepclassmembers class * {
1058    @javax.annotation.Resource *;
1059}
1060</pre>
1061<p>
1062The Spring framework has another similar annotation <code>@Autowired</code>:
1063<pre>
1064-keepclassmembers class * {
1065    @org.springframework.beans.factory.annotation.Autowired *;
1066}
1067</pre>
1068
1069<h3><a name="resourcefiles">Processing resource files</a></h3>
1070
1071If your application, applet, servlet, library, etc., contains resource files,
1072it may be necessary to adapt their names and/or their contents when the
1073application is obfuscated. The following two options can achieve this
1074automatically:
1075<pre>
1076-adaptresourcefilenames    **.properties,**.gif,**.jpg
1077-adaptresourcefilecontents **.properties,META-INF/MANIFEST.MF
1078</pre>
1079<p>
1080The <a href="usage.html#adaptresourcefilenames">-adaptresourcefilenames</a>
1081option in this case renames properties files and image files in the processed
1082output, based on the obfuscated names of their corresponding class files (if
1083any). The <a
1084href="usage.html#adaptresourcefilecontents">-adaptresourcefilecontents</a>
1085option looks for class names in properties files and in the manifest file, and
1086replaces these names by the obfuscated names (if any). You'll probably want to
1087adapt the filters to suit your application.
1088
1089<h3><a name="manifestfiles">Processing manifest files</a></h3>
1090
1091As illustrated in the previous section, manifest files can be treated like
1092ordinary resource files. ProGuard can adapt obfuscated class names in the
1093files, but it won't make any other changes. If you want anything else, you
1094should apply an external tool. For instance, if a manifest file contains
1095signing information, you should sign the jar again after it has been
1096processed.
1097<p>
1098If you're merging several input jars into a single output jar, you'll have to
1099pick one, typically by specifying <a href="usage.html#filters">filters</a>:
1100<pre>
1101-injars  in1.jar
1102-injars  in2.jar(!META-INF/MANIFEST.MF)
1103-injars  in3.jar(!META-INF/MANIFEST.MF)
1104-outjars out.jar
1105</pre>
1106<p>
1107The filters will let ProGuard copy the manifest file from the first jar and
1108ignore any manifest files in the second and third input jars. Note that
1109ProGuard will leave the order of the files in the jars unchanged; manifest
1110files are not necessarily put first.
1111
1112<h3><a name="stacktrace">Producing useful obfuscated stack traces</a></h3>
1113
1114These options let obfuscated applications or libraries produce stack traces
1115that can still be deciphered later on:
1116<pre>
1117-printmapping out.map
1118
1119-renamesourcefileattribute SourceFile
1120-keepattributes SourceFile,LineNumberTable
1121</pre>
1122<p>
1123We're keeping all source file attributes, but we're replacing their values by
1124the string "SourceFile". We could use any string. This string is already
1125present in all class files, so it doesn't take up any extra space. If you're
1126working with J++, you'll want to keep the "SourceDir" attribute as well.
1127<p>
1128We're also keeping the line number tables of all methods.
1129<p>
1130Whenever both of these attributes are present, the Java run-time environment
1131will include line number information when printing out exception stack traces.
1132<p>
1133The information will only be useful if we can map the obfuscated names back to
1134their original names, so we're saving the mapping to a file
1135<code>out.map</code>. The information can then be used by the <a
1136href="retrace/index.html">ReTrace</a> tool to restore the original stack trace.
1137
1138<h3><a name="repackaging">Obfuscating package names</a></h3>
1139
1140Package names can be obfuscated in various ways, with increasing levels of
1141obfuscation and compactness. For example, consider the following classes:
1142<pre>
1143mycompany.myapplication.MyMain
1144mycompany.myapplication.Foo
1145mycompany.myapplication.Bar
1146mycompany.myapplication.extra.FirstExtra
1147mycompany.myapplication.extra.SecondExtra
1148mycompany.util.FirstUtil
1149mycompany.util.SecondUtil
1150</pre>
1151<p>
1152Let's assume the class name <code>mycompany.myapplication.MyMain</code> is the
1153main application class that is kept by the configuration. All other class names
1154can be obfuscated.
1155<p>
1156By default, packages that contain classes that can't be renamed aren't renamed
1157either, and the package hierarchy is preserved. This results in obfuscated
1158class names like these:
1159<pre>
1160mycompany.myapplication.MyMain
1161mycompany.myapplication.a
1162mycompany.myapplication.b
1163mycompany.myapplication.a.a
1164mycompany.myapplication.a.b
1165mycompany.a.a
1166mycompany.a.b
1167</pre>
1168<p>
1169The <a
1170href="usage.html#flattenpackagehierarchy"><code>-flattenpackagehierarchy</code></a>
1171option obfuscates the package names further, by flattening the package
1172hierarchy of obfuscated packages:
1173<pre>
1174-flattenpackagehierarchy 'myobfuscated'
1175</pre>
1176<p>
1177The obfuscated class names then look as follows:
1178<pre>
1179mycompany.myapplication.MyMain
1180mycompany.myapplication.a
1181mycompany.myapplication.b
1182myobfuscated.a.a
1183myobfuscated.a.b
1184myobfuscated.b.a
1185myobfuscated.b.b
1186</pre>
1187<p>
1188Alternatively, the <a
1189href="usage.html#repackageclasses"><code>-repackageclasses</code></a> option
1190obfuscates the entire packaging, by combining obfuscated classes into a single
1191package:
1192<pre>
1193-repackageclasses 'myobfuscated'
1194</pre>
1195The obfuscated class names then look as follows:
1196<pre>
1197mycompany.myapplication.MyMain
1198mycompany.myapplication.a
1199mycompany.myapplication.b
1200myobfuscated.a
1201myobfuscated.b
1202myobfuscated.c
1203myobfuscated.d
1204</pre>
1205<p>
1206Additionally specifying the <a
1207href="usage.html#allowaccessmodification"><code>-allowaccessmodification</code></a>
1208option allows access permissions of classes and class members to
1209be broadened, opening up the opportunity to repackage all obfuscated classes:
1210<pre>
1211-repackageclasses 'myobfuscated'
1212-allowaccessmodification
1213</pre>
1214The obfuscated class names then look as follows:
1215<pre>
1216mycompany.myapplication.MyMain
1217myobfuscated.a
1218myobfuscated.b
1219myobfuscated.c
1220myobfuscated.d
1221myobfuscated.e
1222myobfuscated.f
1223</pre>
1224<p>
1225The specified target package can always be the root package. For instance:
1226<pre>
1227-repackageclasses ''
1228-allowaccessmodification
1229</pre>
1230The obfuscated class names are then the shortest possible names:
1231<pre>
1232mycompany.myapplication.MyMain
1233a
1234b
1235c
1236d
1237e
1238f
1239</pre>
1240<p>
1241Note that not all levels of obfuscation of package names may be acceptable for
1242all code. Notably, you may have to take into account that your application may
1243contain <a href="#resourcefiles">resource files</a> that have to be adapted.
1244
1245<h3><a name="logging">Removing logging code</a></h3>
1246
1247You can let ProGuard remove logging code. The trick is to specify that the
1248logging methods don't have side-effects &mdash; even though they actually do,
1249since they write to the console or to a log file. ProGuard will take your word
1250for it and remove the invocations (in the optimization step) and if possible
1251the logging classes and methods themselves (in the shrinking step).
1252<p>
1253For example, this configuration removes invocations of the Android logging
1254methods:
1255<pre>
1256-assumenosideeffects class android.util.Log {
1257    public static boolean isLoggable(java.lang.String, int);
1258    public static int v(...);
1259    public static int i(...);
1260    public static int w(...);
1261    public static int d(...);
1262    public static int e(...);
1263}
1264</pre>
1265<p>
1266The wildcards are a shortcut to match all versions of the methods.
1267<p>
1268Note that you generally can't remove logging code that uses
1269<code>System.out.println</code>, since you would be removing all invocations
1270of <code>java.io.PrintStream#println</code>, which could break your
1271application. You can work around it by creating your own logging methods and
1272let ProGuard remove those.
1273
1274<h3><a name="restructuring">Restructuring the output archives</a></h3>
1275
1276In simple applications, all output classes and resources files are merged into
1277a single jar. For example:
1278<pre>
1279-injars  classes
1280-injars  in1.jar
1281-injars  in2.jar
1282-injars  in3.jar
1283-outjars out.jar
1284</pre>
1285<p>
1286This configuration merges the processed versions of the files in the
1287<code>classes</code> directory and the three jars into a single output jar
1288<code>out.jar</code>.
1289<p>
1290If you want to preserve the structure of your input jars (and/or wars, ears,
1291zips, or directories), you can specify an output directory (or a war, an ear,
1292or a zip). For example:
1293<pre>
1294-injars  in1.jar
1295-injars  in2.jar
1296-injars  in3.jar
1297-outjars out
1298</pre>
1299<p>
1300The input jars will then be reconstructed in the directory <code>out</code>,
1301with their original names.
1302<p>
1303You can also combine archives into higher level archives. For example:
1304<pre>
1305-injars  in1.jar
1306-injars  in2.jar
1307-injars  in3.jar
1308-outjars out.war
1309</pre>
1310<p>
1311The other way around, you can flatten the archives inside higher level
1312archives into simple archives:
1313<pre>
1314-injars  in.war
1315-outjars out.jar
1316</pre>
1317<p>
1318This configuration puts the processed contents of all jars inside
1319<code>in.war</code> (plus any other contents of <code>in.war</code>) into
1320<code>out.jar</code>.
1321<p>
1322If you want to combine input jars (and/or wars, ears, zips, or directories)
1323into output jars (and/or wars, ears, zips, or directories), you can group the
1324<a href="usage.html#injars"><code>-injars</code></a> and <a
1325href="usage.html#outjars"><code>-outjars</code></a> options. For example:
1326<pre>
1327-injars base_in1.jar
1328-injars base_in2.jar
1329-injars base_in3.jar
1330-outjars base_out.jar
1331
1332-injars  extra_in.jar
1333-outjars extra_out.jar
1334</pre>
1335<p>
1336This configuration puts the processed results of all <code>base_in*.jar</code>
1337jars into <code>base_out.jar</code>, and the processed results of the
1338<code>extra_in.jar</code> into <code>extra_out.jar</code>. Note that only the
1339order of the options matters; the additional whitespace is just for clarity.
1340<p>
1341This grouping, archiving, and flattening can be arbitrarily complex. ProGuard
1342always tries to package output archives in a sensible way, reconstructing the
1343input entries as much as required.
1344
1345<h3><a name="filtering">Filtering the input and the output</a></h3>
1346
1347If you want even greater control, you can add
1348<a href="usage.html#filters">filters</a> to the input and the output,
1349filtering out zips, ears, wars, jars, and/or ordinary files. For example, if
1350you want to disregard certain files from an input jar:
1351<pre>
1352-injars  in.jar(!images/**)
1353-outjars out.jar
1354</pre>
1355<p>
1356This configuration removes any files in the <code>images</code> directory and
1357its subdirectories.
1358<p>
1359Such filters can be convenient for avoiding warnings about duplicate files in
1360the output. For example, only keeping the manifest file from a first input jar:
1361<pre>
1362-injars  in1.jar
1363-injars  in2.jar(!META-INF/MANIFEST.MF)
1364-injars  in3.jar(!META-INF/MANIFEST.MF)
1365-outjars out.jar
1366</pre>
1367<p>
1368Another useful application is speeding up the processing by ProGuard, by
1369disregarding a large number of irrelevant classes in the runtime library jar:
1370<pre>
1371-libraryjars &lt;java.home&gt;/lib/rt.jar(java/**,javax/**)
1372</pre>
1373<p>
1374The filter makes ProGuard disregard <code>com.sun.**</code> classes, for
1375instance , which don't affect the processing of ordinary applications.
1376<p>
1377It is also possible to filter the jars (and/or wars, ears, zips) themselves,
1378based on their names. For example:
1379<pre>
1380-injars  in(**/acme_*.jar;)
1381-outjars out.jar
1382</pre>
1383<p>
1384Note the semi-colon in the filter; the filter in front of it applies to jar
1385names. In this case, only <code>acme_*.jar</code> jars are read from the
1386directory <code>in</code> and its subdirectories. Filters for war names, ear
1387names, and zip names can be prefixed with additional semi-colons. All types of
1388filters can be combined. They are orthogonal.
1389<p>
1390On the other hand, you can also filter the output, in order to control what
1391content goes where. For example:
1392<pre>
1393-injars  in.jar
1394-outjars code_out.jar(**.class)
1395-outjars resources_out.jar
1396</pre>
1397<p>
1398This configuration splits the processed output, sending <code>**.class</code>
1399files to <code>code_out.jar</code>, and all remaining files to
1400<code>resources_out.jar</code>.
1401<p>
1402Again, the filtering can be arbitrarily complex, especially when combined with
1403grouping input and output.
1404
1405<h3><a name="multiple">Processing multiple applications at once</a></h3>
1406
1407You can process several dependent or independent applications (or applets,
1408midlets,...) in one go, in order to save time and effort. ProGuard's input and
1409output handling offers various ways to keep the output nicely structured.
1410<p>
1411The easiest way is to specify your input jars (and/or wars, ears, zips, and
1412directories) and a single output directory. ProGuard will then reconstruct the
1413input in this directory, using the original jar names. For example, showing
1414just the input and output options:
1415<pre>
1416-injars  application1.jar
1417-injars  application2.jar
1418-injars  application3.jar
1419-outjars processed_applications
1420</pre>
1421<p>
1422After processing, the directory <code>processed_applications</code> will
1423contain processed versions of application jars, with their original names.
1424
1425<h3><a name="incremental">Incremental obfuscation</a></h3>
1426
1427After having <a href="#application">processed an application</a>, e.g.
1428ProGuard itself, you can still incrementally add other pieces of code that
1429depend on it, e.g. the ProGuard GUI:
1430<pre>
1431-injars       proguardgui.jar
1432-outjars      proguardgui_out.jar
1433-injars       proguard.jar
1434-outjars      proguard_out.jar
1435-libraryjars  &lt;java.home&gt;/lib/rt.jar
1436-applymapping proguard.map
1437
1438-keep public class proguard.gui.ProGuardGUI {
1439    public static void main(java.lang.String[]);
1440}
1441</pre>
1442<p>
1443We're reading both unprocessed jars as input. Their processed contents will go
1444to the respective output jars. The <a
1445href="usage.html#applymapping"><code>-applymapping</code></a> option then
1446makes sure the ProGuard part of the code gets the previously produced
1447obfuscation mapping. The final application will consist of the obfuscated
1448ProGuard jar and the additional obfuscated GUI jar.
1449<p>
1450The added code in this example is straightforward; it doesn't affect the
1451original code. The <code>proguard_out.jar</code> will be identical to the one
1452produced in the initial processing step. If you foresee adding more complex
1453extensions to your code, you should specify the options <a
1454href="usage.html#useuniqueclassmembernames"><code>-useuniqueclassmembernames</code></a>,
1455<a href="usage.html#dontshrink"><code>-dontshrink</code></a>, and <a
1456href="usage.html#dontoptimize"><code>-dontoptimize</code></a> <i>in the
1457original processing step</i>. These options ensure that the obfuscated base
1458jar will always remain usable without changes. You can then specify the base
1459jar as a library jar:
1460<pre>
1461-injars       proguardgui.jar
1462-outjars      proguardgui_out.jar
1463-libraryjars  proguard.jar
1464-libraryjars  &lt;java.home&gt;/lib/rt.jar
1465-applymapping proguard.map
1466
1467-keep public class proguard.gui.ProGuardGUI {
1468    public static void main(java.lang.String[]);
1469}
1470</pre>
1471
1472<h3><a name="microedition">Preverifying class files for Java Micro Edition</a></h3>
1473
1474Even if you're not interested in shrinking, optimizing, and obfuscating your
1475midlets, as shown in the <a href="#midlets">midlets example</a>, you can still
1476use ProGuard to preverify the class files for Java Micro Edition. ProGuard
1477produces slightly more compact results than the traditional external
1478preverifier.
1479<pre>
1480-injars      in.jar
1481-outjars     out.jar
1482-libraryjars /usr/local/java/wtk2.5.2/lib/midpapi20.jar
1483-libraryjars /usr/local/java/wtk2.5.2/lib/cldcapi11.jar
1484
1485-dontshrink
1486-dontoptimize
1487-dontobfuscate
1488
1489-microedition
1490</pre>
1491<p>
1492We're not processing the input, just making sure the class files are
1493preverified by targeting them at Java Micro Edition with the <a
1494href="usage.html#microedition"><code>-microedition</code></a> option. Note
1495that we don't need any <code>-keep</code> options to specify entry points; all
1496class files are simply preverified.
1497
1498<h3><a name="upgrade">Upgrading class files to Java 6</a></h3>
1499
1500The following options upgrade class files to Java 6, by updating their
1501internal version numbers and preverifying them. The class files can then be
1502loaded more efficiently by the Java 6 Virtual Machine.
1503<pre>
1504-injars      in.jar
1505-outjars     out.jar
1506-libraryjars &lt;java.home&gt;/lib/rt.jar
1507
1508-dontshrink
1509-dontoptimize
1510-dontobfuscate
1511
1512-target 1.6
1513</pre>
1514<p>
1515We're not processing the input, just retargeting the class files with the <a
1516href="usage.html#target"><code>-target</code></a> option. They will
1517automatically be preverified for Java 6 as a result. Note that we don't need
1518any <code>-keep</code> options to specify entry points; all class files are
1519simply updated and preverified.
1520
1521<h3><a name="deadcode">Finding dead code</a></h3>
1522
1523These options list unused classes, fields, and methods in the application
1524<code>mypackage.MyApplication</code>:
1525<pre>
1526-injars      in.jar
1527-libraryjars &lt;java.home&gt;/lib/rt.jar
1528
1529-dontoptimize
1530-dontobfuscate
1531-dontpreverify
1532-printusage
1533
1534-keep public class mypackage.MyApplication {
1535    public static void main(java.lang.String[]);
1536}
1537</pre>
1538<p>
1539We're not specifying an output jar, just printing out some results. We're
1540saving some processing time by skipping the other processing steps.
1541<p>
1542The java compiler inlines primitive constants and String constants
1543(<code>static final</code> fields). ProGuard would therefore list such fields
1544as not being used in the class files that it analyzes, even if they <i>are</i>
1545used in the source files. We can add a <a
1546href="usage.html#keepclassmembers"><code>-keepclassmembers</code></a> option
1547that keeps those fields a priori, in order to avoid having them listed:
1548<pre>
1549-keepclassmembers class * {
1550    static final %                *;
1551    static final java.lang.String *;
1552}
1553</pre>
1554
1555<h3><a name="structure">Printing out the internal structure of class files</a></h3>
1556
1557These options print out the internal structure of all class files in the input
1558jar:
1559<pre>
1560-injars in.jar
1561
1562-dontshrink
1563-dontoptimize
1564-dontobfuscate
1565-dontpreverify
1566
1567-dump
1568</pre>
1569<p>
1570Note how we don't need to specify the Java run-time jar, because we're not
1571processing the input jar at all.
1572
1573<h3><a name="annotated">Using annotations to configure ProGuard</a></h3>
1574
1575The traditional ProGuard configuration allows to keep a clean separation
1576between the code and the configuration for shrinking, optimization, and
1577obfuscation. However, it is also possible to define specific annotations,
1578and then annotate the code to configure the processing.
1579<p>
1580You can find a set of such predefined annotations in the directory
1581<code>examples/annotations/lib</code> in the ProGuard distribution.
1582The annotation classes are defined in <code>annotations.jar</code>. The
1583corresponding ProGuard configuration (or meta-configuration, if you prefer)
1584is specified in <code>annotations.pro</code>. With these files, you can start
1585annotating your code. For instance, a java source file
1586<code>Application.java</code> can be annotated as follows:
1587<pre>
1588@KeepApplication
1589public class Application {
1590  ....
1591}
1592</pre>
1593<p>
1594The ProGuard configuration file for the application can then be simplified by
1595leveraging off these annotations:
1596<pre>
1597-injars      in.jar
1598-outjars     out.jar
1599-libraryjars &lt;java.home&gt;/lib/rt.jar
1600
1601-include lib/annotations.pro
1602</pre>
1603<p>
1604The annotations are effectively replacing the application-dependent
1605<code>-keep</code> options. You may still wish to add traditional
1606<code>-keep</code> options for processing <a href="#native">native
1607methods</a>, <a href="#enumerations">enumerations</a>, <a
1608href="#serializable">serializable classes</a>, and <a
1609href="#annotations">annotations</a>.
1610<p>
1611The directory <code>examples/annotations</code> contains more examples that
1612illustrate some of the possibilities.
1613
1614<hr />
1615<address>
1616Copyright &copy; 2002-2014
1617<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.saikoa.com/">Saikoa</a>.
1618</address>
1619</body>
1620</html>
1621