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"> </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 <java.home>/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><java.home></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"> </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 <java.home>/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"> </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"> </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"> </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"> </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"> </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 <java.home>/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 <methods>; 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"> </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 <java.home>/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"> </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 <java.home>/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"> </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"> </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"> </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"> </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"> </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 <java.home>/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"> </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 <methods>; 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"> </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"> </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"> </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 <fields>; 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><fields></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 <fields>; 656 !private <fields>; 657 !private <methods>; 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"> </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"> </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"> </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"> </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"> </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 <methods>; 786} 787 788-keep class * implements java.rmi.Remote { 789 <init>(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"> </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"> </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"> </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"> </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"> </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 <java.home>/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"> </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"> </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 <java.home>/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 <java.home>/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"> </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"> </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 <java.home>/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"> </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 <java.home>/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"> </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"> </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 <java.home>/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 © 2002-2009 1299<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. 1300</address> 1301</body> 1302</html> 1303