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