gui.html revision cfead78069f3dc32998dc118ee08cab3867acea2
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 GUI</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>Graphical User Interface</h2> 23 24You can find the ProGuard GUI jar in the <code>lib</code> directory of the 25ProGuard distribution. To run the ProGuard graphical user interface, just type: 26<p class="code"> 27<code><b>java -jar proguardgui.jar</b> [-nosplash] </code>[<i>configuration_file</i>] 28</p> 29The GUI will pop up in a window. With the <code>-nosplash</code> option, you 30can switch off the short opening animation. If you have specified a ProGuard 31configuration file, it will be loaded. The GUI works like a wizard. You can 32edit the configuration and execute ProGuard through a few tabs: 33<p> 34 35<table cellspacing="5" cellpadding="5"> 36<tr><td class="button"><a href="#proguard">ProGuard</a></td> 37 <td>Optionally load an existing configuration file.</td></tr> 38<tr><td class="button"><a href="#inputoutput">Input/Output</a></td> 39 <td>Specify the program jars and library jars.</td></tr> 40<tr><td class="button"><a href="#shrinking">Shrinking</a></td> 41 <td>Specify the shrinking options.</td></tr> 42<tr><td class="button"><a href="#obfuscation">Obfuscation</a></td> 43 <td>Specify the obfuscation options.</td></tr> 44<tr><td class="button"><a href="#optimization">Optimization</a></td> 45 <td>Specify the optimization options.</td></tr> 46<tr><td class="button"><a href="#information">Information</a></td> 47 <td>Specify some options to get information.</td></tr> 48<tr><td class="button"><a href="#process">Process</a></td> 49 <td>View and save the resulting configuration, and run ProGuard.</td></tr> 50</table> 51<p> 52 53In addition, there is a tab to execute ReTrace interactively: 54<p> 55 56<table cellspacing="5" cellpadding="5"> 57<tr><td class="button"><a href="#retrace">ReTrace</a></td> 58 <td>Set up and run ReTrace, to de-obfuscate stack traces.</td></tr> 59</table> 60<p> 61 62You can freely toggle between the tabs by means of the buttons on the 63left-hand side of the window, or by means of the <b>Previous</b> and 64<b>Next</b> buttons at the bottom of the tabs. Tool tips briefly explain the 65purpose of the numerous options and text fields, although a basic 66understanding of the shrinking/optimization/obfuscation/preverification 67process is assumed. Please refer to the <a 68href="introduction.html">Introduction</a> of this manual. 69<p> 70 71<h2><a name="proguard">The ProGuard Tab</a></h2> 72 73The <i>ProGuard</i> tab presents a welcome message and one important button at 74the bottom: 75<p> 76 77<table cellspacing="5" cellpadding="5"> 78<tr><td class="button">Load configuration...</td> 79 <td>opens a file chooser to load an existing ProGuard configuration 80 file.</td></tr> 81</table> 82<p> 83 84If you don't want to load an existing configuration, you can just continue 85creating a new configuration from scratch. 86<p> 87 88<h2><a name="inputoutput">The Input/Output Tab</a></h2> 89 90The <i>Input/Output</i> tab contains two lists, respectively to specify the 91program jars (or wars, ears, zips, or directories), and the library jars (or 92wars, ears, zips, or directories). 93 94<ul> 95<li>The list of program jars contains input entries and output entries. Input 96 entries contain the class files and resource files to be processed. Output 97 entries specify the destinations to which the processed results will be 98 written. They are preceded by arrows, to distinguish them from input 99 entries. The results of each consecutive list of input entries will be 100 written to the subsequent consecutive list of output entries.</li> 101 102<li>The library jars are not copied to the output jars; they contain class 103 files that are used by class files in the program jars and that are 104 necessary for correct processing. This list typically at least contains the 105 targeted Java runtime jar.</li> 106</ul> 107<p> 108 109Each of these lists can be edited by means of a couple of buttons on the 110right-hand side: 111<p> 112 113<table cellspacing="5" cellpadding="5"> 114<tr><td class="button">Add input...</td> <td>opens a file chooser to add an 115 input entry to the list of program jars.</td></tr> 116<tr><td class="button">Add output...</td> <td>opens a file chooser to add an 117 output entry to the list of program jars.</td></tr> 118<tr><td class="button">Add...</td> 119 <td>opens a file chooser to add an entry to the list of library 120 jars.</td></tr> 121<tr><td class="button">Edit...</td> 122 <td>opens a file chooser to edit the selected entry in the list.</td></tr> 123<tr><td class="button">Filter...</td> 124 <td>opens a text entry field to add or edit the filters of the selected 125 entries in the list.</td></tr> 126<tr><td class="button">Remove</td> 127 <td>removes the selected entries from the list.</td></tr> 128<tr><td class="button">Move up</td> 129 <td>moves the selected entries one position up the list.</td></tr> 130<tr><td class="button">Move down</td> 131 <td>moves the selected entries one position down the list.</td></tr> 132<tr><td class="button">Move to libraries</td> 133 <td>moves the selected entries in the list of program jars to the list of 134 library jars.</td></tr> 135<tr><td class="button">Move to program</td> 136 <td>moves the selected entries in the list of library jars to the list of 137 program jars.</td></tr> 138</table> 139<p> 140 141Filters allow to filter files based on their names. One can specify filters 142for class file names and resource file names, for jar file names, for war file 143names, for ear file names, and for zip file names. Multiple entries in the 144program list only make sense when combined with filters; each output file is 145written to the first entry with a matching filter. 146<p> 147 148Input entries that are currently not readable are colored red. 149<p> 150 151The order of the entries in each list may matter, as the first occurrence of 152any duplicate entries gets precedence, just as in conventional class paths. 153<p> 154 155Corresponding configuration options: 156<ul type="none"> 157<li>-<a href="usage.html#injars">injars</a></li> 158<li>-<a href="usage.html#outjars">outjars</a></li> 159<li>-<a href="usage.html#libraryjars">libraryjars</a></li> 160<li><a href="usage.html#classpath"><i>class_path</i></a></li> 161<li><a href="usage.html#filters"><i>filters</i></a></li> 162</ul> 163<p> 164 165<h2><a name="shrinking">The Shrinking Tab</a></h2> 166 167The <i>Shrinking</i> tab presents a number of options that affect the 168shrinking step. The basic options are followed by a few lists of classes and 169class members (fields and methods) that must be protected from shrinking (and 170implicitly from obfuscation as well). 171<p> 172 173The fixed lists contain predefined entries that are typically useful for many 174applications. Each of these entries can be toggled by means of a check box. 175The text field following each entry allows to constrain the applicable classes 176by means of a comma-separated list of wildcarded, fully-qualified class 177names. The default is "*", which means that all input classes of the 178corresponding type are considered. 179<p> 180 181For example, checking the <b>Applications</b> entry and filling in 182"myapplications.**" after it would mean: keep all classes that have main 183methods in the "myapplications" package and all of its subpackages. 184<p> 185 186The variable list at the bottom allows to define additional entries 187yourself. The list can be edited by means of a couple of buttons on the 188right-hand side: 189<p> 190 191<table cellspacing="5" cellpadding="5"> 192<tr><td class="button">Add...</td> 193 <td>opens a window to add a new entry to the list.</td></tr> 194<tr><td class="button">Edit...</td> 195 <td>opens a window to edit the selected entry in the list.</td></tr> 196<tr><td class="button">Remove</td> 197 <td>removes the selected entries from the list.</td></tr> 198<tr><td class="button">Move up</td> 199 <td>moves the selected entries one position up the list.</td></tr> 200<tr><td class="button">Move down</td> 201 <td>moves the selected entries one position down the list.</td></tr> 202</table> 203<p> 204 205The interface windows allow to specify classes, fields, and methods. They 206contain text fields and check boxes to constrain these items. They have 207<b>Ok</b> and <b>Cancel</b> buttons to apply or to cancel the operation. 208<p> 209 210For example, your application may be creating some classes dynamically using 211<code>Class.forName</code>. You should then specify them here, so they are kept 212by their original names. Press the <b>Add...</b> button to open the class 213window. Fill out the fully-qualified class name in the <b>Code</b> text field, 214and press the <b>Ok</b> button. Repeat this for all required classes. Wildcards 215can be helpful to specify a large number of related classes in one go. If you 216want to specify all implementations of a certain interface, fill out the 217fully qualified interface name in the <b>Extends/implements class</b> instead. 218<p> 219 220For more advanced settings, it is advisable to become familiar with ProGuard's 221configuration options through the <a href="usage.html">Usage section</a> and 222the <a href="examples.html">Examples section</a>. We'll suffice with a brief 223overview of the three dialogs provided by the GUI. 224<p> 225 226The <i>keep class</i> dialog appears when adding or editing new special keep 227entries. It has text fields and selections for specifying and constraining 228classes and class members to keep. The <b>Advanced options</b> / <b>Basic 229options</b> button at the bottom of the dialog allows to toggle showing the 230advanced options. 231 232<ul> 233<li>The <b>Comments</b> text field allows to add optional comments to this 234 entry. The comments will identify the entry in the list and they will 235 appear as comments in the configuration file.</li> 236 237<li>The <b>Keep</b> selection allows to specify whether you want to protect 238 the specified classes and their specified class members, or just the 239 specified class members from the specified classes, or the specified 240 classes and the specified class members, if the class members are present. 241 Note that class members will only be protected if they are explicitly 242 specified, even if only by means of a wildcard.</li> 243 244<li>The <b>Allow</b> selection allows to specify whether you want to allow the 245 the specified classes and their specified class members to be shrunk, 246 optimized and/or obfuscated.</li> 247 248<li>The <b>Access</b> selections allows to specify constraints on the class or 249 classes, based on their access modifiers.</li> 250 251<li>The <b>Annotation</b> text field takes the fully-qualified name of an 252 annotation that is required for matching classes. The annotation name can 253 contain wildcards. This is an advanced option for defining <i>keep</i> 254 annotations.</li> 255 256<li>The <b>Class</b> text field takes the fully-qualified name of the class or 257 classes. The class name can contain wildcards.</li> 258 259<li>The <b>Annotation</b> text field takes the fully-qualified name of an 260 annotation that is required for the class or interface that the above 261 class must extend. The annotation name can contain wildcards. This is an 262 advanced option for defining <i>keep</i> annotations.</li> 263 264<li>The <b>Extends/implements class</b> text field takes the fully-qualified 265 name of the class or interface that the above classes must extend.</li> 266 267<li>The <b>Class members</b> list allows to specify a list of fields and 268 methods to keep. It can be edited by means of a list of buttons on the 269 right-hand side.</li> 270</ul> 271<p> 272 273The <i>keep field</i> dialog appears when adding or editing fields within the 274above dialog. It has text fields and selections for specifying and 275constraining fields to keep. Again, the <b>Advanced options</b> / <b>Basic 276options</b> button at the bottom of the dialog allows to toggle showing the 277advanced options. 278 279<ul> 280<li>The <b>Access</b> selections allows to specify constraints on the field or 281 fields, based on their access modifiers.</li> 282 283<li>The <b>Annotation</b> text field takes the fully-qualified name of an 284 annotation that is required for matching fields. The annotation name can 285 contain wildcards. This is an advanced option for defining <i>keep</i> 286 annotations.</li> 287 288<li>The <b>Return type</b> text field takes the fully-qualified type of the 289 field or fields. The type can contain wildcards.</li> 290 291<li>The <b>Name</b> text field takes the name of the field or fields. The field 292 name can contain wildcards.</li> 293</ul> 294<p> 295 296Similarly, the <i>keep method</i> dialog appears when adding or editing 297methods within the keep class dialog. It has text fields and selections for 298specifying and constraining methods to keep. Again, the <b>Advanced 299options</b> / <b>Basic options</b> button at the bottom of the dialog allows 300to toggle showing the advanced options. 301 302<ul> 303<li>The <b>Access</b> selections allows to specify constraints on the method or 304 methods, based on their access modifiers.</li> 305 306<li>The <b>Annotation</b> text field takes the fully-qualified name of an 307 annotation that is required for matching methods. The annotation name can 308 contain wildcards. This is an advanced option for defining <i>keep</i> 309 annotations.</li> 310 311<li>The <b>Return type</b> text field takes the fully-qualified type of the method or methods. The type can contain wildcards.</li> 312 313<li>The <b>Name</b> text field takes the name of the method or methods. The 314 method name can contain wildcards.</li> 315 316<li>The <b>Arguments</b> text field takes the comma-separated list of 317 fully-qualified method arguments. Each of these arguments can contain 318 wildcards.</li> 319</ul> 320<p> 321 322Corresponding configuration options: 323<ul type="none"> 324<li>-<a href="usage.html#dontshrink">dontshrink</a></li> 325<li>-<a href="usage.html#printusage">printusage</a></li> 326<li>-<a href="usage.html#keep">keep</a></li> 327<li>-<a href="usage.html#keepclassmembers">keepclassmembers</a></li> 328<li>-<a href="usage.html#keepclasseswithmembers">keepclasseswithmembers</a></li> 329</ul> 330<p> 331 332<h2><a name="obfuscation">The Obfuscation Tab</a></h2> 333 334The <i>Obfuscation</i> tab presents a number of options that affect the 335obfuscation step. The basic options are followed by a few lists of classes and 336class members (fields and methods) that must be protected from obfuscation 337(but not necessarily from shrinking). 338<p> 339 340The lists are manipulated in the same way as in the <a 341href="#shrinking">Shrinking Tab</a>. 342<p> 343 344Corresponding configuration options: 345<ul type="none"> 346<li>-<a href="usage.html#dontobfuscate">dontobfuscate</a></li> 347<li>-<a href="usage.html#printmapping">printmapping</a></li> 348<li>-<a href="usage.html#applymapping">applymapping</a></li> 349<li>-<a href="usage.html#obfuscationdictionary">obfuscationdictionary</a></li> 350<li>-<a href="usage.html#classobfuscationdictionary">classobfuscationdictionary</a></li> 351<li>-<a href="usage.html#packageobfuscationdictionary">packageobfuscationdictionary</a></li> 352<li>-<a href="usage.html#overloadaggressively">overloadaggressively</a></li> 353<li>-<a href="usage.html#useuniqueclassmembernames">useuniqueclassmembernames</a></li> 354<li>-<a href="usage.html#dontusemixedcaseclassnames">dontusemixedcaseclassnames</a></li> 355<li>-<a href="usage.html#keeppackagenames">keeppackagenames</a></li> 356<li>-<a href="usage.html#flattenpackagehierarchy">flattenpackagehierarchy</a></li> 357<li>-<a href="usage.html#repackageclasses">repackageclasses</a></li> 358<li>-<a href="usage.html#keepattributes">keepattributes</a></li> 359<li>-<a href="usage.html#keepparameternames">keepparameternames</a></li> 360<li>-<a href="usage.html#renamesourcefileattribute">renamesourcefileattribute</a></li> 361<li>-<a href="usage.html#adaptclassstrings">adaptclassstrings</a></li> 362<li>-<a href="usage.html#adaptresourcefilenames">adaptresourcefilenames</a></li> 363<li>-<a href="usage.html#adaptresourcefilecontents">adaptresourcefilecontents</a></li> 364<li>-<a href="usage.html#keepnames">keepnames</a></li> 365<li>-<a href="usage.html#keepclassmembernames">keepclassmembernames</a></li> 366<li>-<a href="usage.html#keepclasseswithmembernames">keepclasseswithmembernames</a></li> 367<li><a href="usage.html#classspecification"><i>class_specification</i></a></li> 368</ul> 369<p> 370 371<h2><a name="optimization">The Optimization Tab</a></h2> 372 373The <i>Optimization</i> tab presents a number of options that affect the 374optimization step. The basic options are followed by a few lists of class 375method calls that can be removed if ProGuard can determine that their results 376are not being used. 377<p> 378 379The lists are manipulated in much the same way as in the <a 380href="#shrinking">Shrinking Tab</a>. 381<p> 382 383Corresponding configuration options: 384<ul type="none"> 385<li>-<a href="usage.html#dontoptimize">dontoptimize</a></li> 386<li>-<a href="usage.html#optimizations">optimizations</a></li> 387<li>-<a href="usage.html#optimizationpasses">optimizationpasses</a></li> 388<li>-<a href="usage.html#allowaccessmodification">allowaccessmodification</a></li> 389<li>-<a href="usage.html#mergeinterfacesaggressively">mergeinterfacesaggressively</a></li> 390<li>-<a href="usage.html#assumenosideeffects">assumenosideeffects</a></li> 391<li><a href="usage.html#classspecification"><i>class_specification</i></a></li> 392</ul> 393<p> 394 395<h2><a name="information">The Information Tab</a></h2> 396 397The <i>Information</i> tab presents a number of options for preverification 398and targeting, and for the information that ProGuard returns when processing 399your code. The bottom list allows you to query ProGuard about why given 400classes and class members are being kept in the shrinking step. 401<p> 402 403Corresponding configuration options: 404<ul type="none"> 405<li>-<a href="usage.html#dontpreverify">dontpreverify</a></li> 406<li>-<a href="usage.html#microedition">microedition</a></li> 407<li>-<a href="usage.html#target">target</a></li> 408<li>-<a href="usage.html#verbose">verbose</a></li> 409<li>-<a href="usage.html#dontnote">dontnote</a></li> 410<li>-<a href="usage.html#dontwarn">dontwarn</a></li> 411<li>-<a href="usage.html#ignorewarnings">ignorewarnings</a></li> 412<li>-<a href="usage.html#skipnonpubliclibraryclasses">skipnonpubliclibraryclasses</a></li> 413<li>-<a href="usage.html#dontskipnonpubliclibraryclasses">dontskipnonpubliclibraryclasses</a></li> 414<li>-<a href="usage.html#dontskipnonpubliclibraryclassmembers">dontskipnonpubliclibraryclassmembers</a></li> 415<li>-<a href="usage.html#keepdirectories">keepdirectories</a></li> 416<li>-<a href="usage.html#forceprocessing">forceprocessing</a></li> 417<li>-<a href="usage.html#printseeds">printseeds</a></li> 418<li>-<a href="usage.html#printconfiguration">printconfiguration</a></li> 419<li>-<a href="usage.html#dump">dump</a></li> 420<li>-<a href="usage.html#whyareyoukeeping">whyareyoukeeping</a></li> 421</ul> 422<p> 423 424<h2><a name="process">The Process Tab</a></h2> 425 426The <i>Process</i> tab has an output console for displaying the configuration 427and the messages while processing. There are three important buttons at the 428bottom: 429<p> 430 431<table cellspacing="5" cellpadding="5"> 432<tr><td class="button">View configuration</td> 433 <td>displays the current ProGuard configuration in the console.</td></tr> 434<tr><td class="button">Save configuration...</td> 435 <td>opens a file chooser to save the current ProGuard 436 configuration.</td></tr> 437<tr><td class="button">Process!</td> 438 <td>executes ProGuard with the current configuration.</td></tr> 439</table> 440<p> 441 442<h2><a name="retrace">The ReTrace Tab</a></h2> 443 444The <i>ReTrace</i> tab has a panel with a few settings, an input text area for 445the obfuscated stack trace, and an output console to view the de-obfuscated 446stack trace: 447 448<ul> 449<li>The <b>Verbose</b> check box in the settings panel allows to toggle between 450 normal mode and verbose mode.</li> 451 452<li>The <b>Mapping file</b> text field takes the name of the required mapping 453 file that ProGuard wrote while processing the original code. The file name 454 can be entered manually or by means of the <b>Browse...</b> button that 455 opens a file chooser.</li> 456 457<li>The <b>Obfuscated stack trace</b> text area allows to enter the stack 458 trace, typically by copying and pasting it from elsewhere. Alternatively, 459 it can be loaded from a file by means of the load button below.</li> 460</ul> 461 462There are two buttons at the bottom: 463<p> 464 465<table cellspacing="5" cellpadding="5"> 466<tr><td class="button">Load stack trace...</td> 467 <td>opens a file chooser to load an obfuscated stack trace.</td></tr> 468<tr><td class="button">ReTrace!</td> 469 <td>executes ReTrace with the current settings.</td></tr> 470</table> 471 472<hr /> 473<noscript><div><a target="_top" href="/index.html" class="button">Show menu</a></div></noscript> 474<address> 475Copyright © 2002-2011 476<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a>. 477</address> 478</body> 479</html> 480