| <!doctype html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> | |
| <html> | |
| <head> | |
| <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"> | |
| <meta http-equiv="content-style-type" content="text/css"> | |
| <link rel="stylesheet" type="text/css" href="style.css"> | |
| <title>ProGuard Usage</title> | |
| </head> | |
| <body> | |
| <script type="text/javascript" language="JavaScript"> | |
| <!-- | |
| if (window.self==window.top) | |
| document.write('<a class="largebutton" target="_top" href="../index.html#manual/usage.html">ProGuard index</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> <a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>') | |
| //--> | |
| </script> | |
| <noscript> | |
| <a class="largebutton" target="_top" href="../index.html#manual/usage.html">ProGuard index</a> | |
| <a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> | |
| <a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> | |
| <a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a> | |
| </noscript> | |
| <h2>Usage</h2> | |
| To run ProGuard, just type: | |
| <p class="code"> | |
| <code><b>java -jar proguard.jar </b></code><i>options</i> ... | |
| </p> | |
| You can find the ProGuard jar in the <code>lib</code> directory of the | |
| ProGuard distribution. Alternatively, the <code>bin</code> directory contains | |
| some short Linux and Windows scripts containing this command. Typically, you'll | |
| put most options in a configuration file (say, <code>myconfig.pro</code>), and | |
| just call: | |
| <p class="code"> | |
| <code><b>java -jar proguard.jar @myconfig.pro</b></code> | |
| </p> | |
| You can combine command line options and options from configuration files. For | |
| instance: | |
| <p class="code"> | |
| <code><b>java -jar proguard.jar @myconfig.pro -verbose</b></code> | |
| </p> | |
| <p> | |
| You can add comments in a configuration file, starting with a | |
| <code><b>#</b></code> character and continuing until the end of the line. | |
| <p> | |
| Extra whitespace between words and delimiters is ignored. File names with | |
| spaces or special characters should be quoted with single or double quotes. | |
| <p> | |
| Options can be grouped arbitrarily in arguments on the command line and in | |
| lines in configuration files. This means that you can quote arbitrary sections | |
| of command line options, to avoid shell expansion of special characters, for | |
| instance. | |
| <p> | |
| The order of the options is generally irrelevant. For quick experiments, you | |
| can abbreviate them to their first unique characters. | |
| <p> | |
| The sections below provide more details: | |
| <ul> | |
| <li><a href="#iooptions">Input/Output Options</a></li> | |
| <li><a href="#keepoptions">Keep Options</a></li> | |
| <li><a href="#shrinkingoptions">Shrinking Options</a></li> | |
| <li><a href="#optimizationoptions">Optimization Options</a></li> | |
| <li><a href="#obfuscationoptions">Obfuscation Options</a></li> | |
| <li><a href="#preverificationoptions">Preverification Options</a></li> | |
| <li><a href="#generaloptions">General Options</a></li> | |
| <li><a href="#classpath">Class Paths</a></li> | |
| <li><a href="#filename">File Names</a></li> | |
| <li><a href="#filefilters">File Filters</a></li> | |
| <li><a href="#filters">Filters</a></li> | |
| <li><a href="#keepoverview">Overview of <code>Keep</code> Options</a></li> | |
| <li><a href="#keepoptionmodifiers">Keep Option Modifiers</a></li> | |
| <li><a href="#classspecification">Class Specifications</a></li> | |
| </ul> | |
| <h2><a name="iooptions">Input/Output Options</a></h2> | |
| <dl> | |
| <dt><a name="at"><code><b>@</b></code></a><a href="#filename"><i>filename</i></a></dt> | |
| <dd>Short for '<a href="#include"><code>-include</code></a> | |
| <a href="#filename"><i>filename</i></a>'.</dd> | |
| <dt><a name="include"><code><b>-include</b></code></a> | |
| <a href="#filename"><i>filename</i></a></dt> | |
| <dd>Recursively reads configuration options from the given file | |
| <i>filename</i>.</dd> | |
| <dt><a name="basedirectory"><code><b>-basedirectory</b></code></a> | |
| <a href="#filename"><i>directoryname</i></a></dt> | |
| <dd>Specifies the base directory for all subsequent relative file names in | |
| these configuration arguments or this configuration file.</dd> | |
| <dt><a name="injars"><code><b>-injars</b></code></a> | |
| <a href="#classpath"><i>class_path</i></a></dt> | |
| <dd>Specifies the input jars (or aars, wars, ears, zips, apks, or directories) | |
| of the application to be processed. The class files in these jars will be | |
| processed and written to the output jars. By default, any non-class files | |
| will be copied without changes. Please be aware of any temporary files | |
| (e.g. created by IDEs), especially if you are reading your input files | |
| straight from directories. The entries in the class path can be filtered, | |
| as explained in the <a href="#filefilters">filters</a> section. For better | |
| readability, class path entries can be specified using multiple | |
| <code>-injars</code> options.</dd> | |
| <dt><a name="outjars"><code><b>-outjars</b></code></a> | |
| <a href="#classpath"><i>class_path</i></a></dt> | |
| <dd>Specifies the names of the output jars (or aars, wars, ears, zips, apks, | |
| or directories). The processed input of the preceding <code>-injars</code> | |
| options will be written to the named jars. This allows you to collect the | |
| contents of groups of input jars into corresponding groups of output jars. | |
| In addition, the output entries can be filtered, as explained in | |
| the <a href="#filefilters">filters</a> section. Each processed class file | |
| or resource file is then written to the first output entry with a matching | |
| filter, within the group of output jars. | |
| <p> | |
| You must avoid letting the output files overwrite any input files. For | |
| better readability, class path entries can be specified using multiple | |
| <code>-outjars</code> options. Without any <code>-outjars</code> options, | |
| no jars will be written.</dd> | |
| <dt><a name="libraryjars"><code><b>-libraryjars</b></code></a> | |
| <a href="#classpath"><i>class_path</i></a></dt> | |
| <dd>Specifies the library jars (or aars, wars, ears, zips, apks, or | |
| directories) of the application to be processed. The files in these jars | |
| will not be included in the output jars. The specified library jars should | |
| at least contain the class files that are <i>extended</i> by application | |
| class files. Library class files that are only <i>called</i> needn't be | |
| present, although their presence can improve the results of the | |
| optimization step. The entries in the class path can be filtered, as | |
| explained in the <a href="#filefilters">filters</a> section. For better | |
| readability, class path entries can be specified using | |
| multiple <code>-libraryjars</code> options. | |
| <p> | |
| Please note that the boot path and the class path set for running ProGuard | |
| are not considered when looking for library classes. This means that you | |
| explicitly have to specify the run-time jar that your code will use. | |
| Although this may seem cumbersome, it allows you to process applications | |
| targeted at different run-time environments. For example, you can process | |
| <a href="examples.html#application">J2SE applications</a> as well as <a | |
| href="examples.html#midlet">JME midlets</a> or <a | |
| href="examples.html#androidapplication">Android apps</a>, just by | |
| specifying the appropriate run-time jar.</dd> | |
| <dt><a name="skipnonpubliclibraryclasses"><code><b>-skipnonpubliclibraryclasses</b></code></a></dt> | |
| <dd>Specifies to skip non-public classes while reading library jars, to speed | |
| up processing and reduce memory usage of ProGuard. By default, ProGuard | |
| reads non-public and public library classes alike. However, non-public | |
| classes are often not relevant, if they don't affect the actual program | |
| code in the input jars. Ignoring them then speeds up ProGuard, without | |
| affecting the output. Unfortunately, some libraries, including recent JSE | |
| run-time libraries, contain non-public library classes that are extended | |
| by public library classes. You then can't use this option. ProGuard will | |
| print out warnings if it can't find classes due to this option being | |
| set.</dd> | |
| <dt><a name="dontskipnonpubliclibraryclasses"><code><b>-dontskipnonpubliclibraryclasses</b></code></a></dt> | |
| <dd>Specifies not to ignore non-public library classes. As of version 4.5, this | |
| is the default setting.</dd> | |
| <dt><a name="dontskipnonpubliclibraryclassmembers"><code><b>-dontskipnonpubliclibraryclassmembers</b></code></a></dt> | |
| <dd>Specifies not to ignore package visible library class members (fields and | |
| methods). By default, ProGuard skips these class members while parsing | |
| library classes, as program classes will generally not refer to them. | |
| Sometimes however, program classes reside in the same packages as library | |
| classes, and they do refer to their package visible class members. In | |
| those cases, it can be useful to actually read the class members, in order | |
| to make sure the processed code remains consistent.</dd> | |
| <dt><a name="keepdirectories"><code><b>-keepdirectories</b></code></a> | |
| [<i><a href="#filefilters">directory_filter</a></i>]</dt> | |
| <dd>Specifies the directories to be kept in the output jars (or aars, wars, | |
| ears, zips, apks, or directories). By default, directory entries are | |
| removed. This reduces the jar size, but it may break your program if the | |
| code tries to find them with constructs like | |
| "<code>mypackage.MyClass.class.getResource("")</code>". You'll then want | |
| to keep the directory corresponding to the package, | |
| "<code>-keepdirectories mypackage</code>". If the option is specified | |
| without a filter, all directories are kept. With a filter, only matching | |
| directories are kept. For instance, | |
| "<code>-keepdirectories mydirectory</code>" matches the specified | |
| directory, "<code>-keepdirectories mydirectory/*</code>" matches its | |
| immediate subdirectories, and | |
| "<code>-keepdirectories mydirectory/**</code>" matches all of its | |
| subdirectories.</dd> | |
| <dt><a name="target"><code><b>-target</b></code></a> <i>version</i></dt> | |
| <dd>Specifies the version number to be set in the processed class files. The | |
| version number can be one of <code>1.0</code>, <code>1.1</code>, | |
| <code>1.2</code>, <code>1.3</code>, <code>1.4</code>, <code>1.5</code> (or | |
| just <code>5</code>), <code>1.6</code> (or just <code>6</code>), | |
| <code>1.7</code> (or just <code>7</code>), or <code>1.8</code> (or | |
| just <code>8</code>). By default, the version numbers of the class files | |
| are left unchanged. For example, you may want to | |
| <a href="examples.html#upgrade">upgrade class files to Java 6</a>, by | |
| changing their version numbers and having them preverified. You probably | |
| shouldn't downgrade the version numbers of class files, since the code | |
| may contain constructs that are not supported in older versions.</dd> | |
| <dt><a name="forceprocessing"><code><b>-forceprocessing</b></code></a></dt> | |
| <dd>Specifies to process the input, even if the output seems up to date. The | |
| up-to-dateness test is based on a comparison of the date stamps of the | |
| specified input, output, and configuration files or directories.</dd> | |
| </dl> | |
| <p> | |
| <h2><a name="keepoptions">Keep Options</a></h2> | |
| <dl> | |
| <dt><a name="keep"><code><b>-keep</b></code></a> | |
| [<a href="#keepoptionmodifiers">,<i>modifier</i></a>,...] | |
| <a href="#classspecification"><i>class_specification</i></a></dt> | |
| <dd>Specifies classes and class members (fields and methods) to be preserved | |
| as entry points to your code. For example, in order to <a | |
| href="examples.html#application">keep an application</a>, you can specify | |
| the main class along with its main method. In order to <a | |
| href="examples.html#library">process a library</a>, you should specify all | |
| publicly accessible elements.</dd> | |
| <dt><a name="keepclassmembers"><code><b>-keepclassmembers</b></code></a> | |
| [<a href="#keepoptionmodifiers">,<i>modifier</i></a>,...] | |
| <a href="#classspecification"><i>class_specification</i></a></dt> | |
| <dd>Specifies class members to be preserved, if their classes are preserved as | |
| well. For example, you may want to <a | |
| href="examples.html#serializable">keep all serialization fields and | |
| methods</a> of classes that implement the <code>Serializable</code> | |
| interface.</dd> | |
| <dt><a name="keepclasseswithmembers"><code><b>-keepclasseswithmembers</b></code></a> | |
| [<a href="#keepoptionmodifiers">,<i>modifier</i></a>,...] | |
| <a href="#classspecification"><i>class_specification</i></a></dt> | |
| <dd>Specifies classes and class members to be preserved, on the condition that | |
| all of the specified class members are present. For example, you may want | |
| to <a href="examples.html#applications">keep all applications</a> that | |
| have a main method, without having to list them explicitly.</dd> | |
| <dt><a name="keepnames"><code><b>-keepnames</b></code></a> | |
| <a href="#classspecification"><i>class_specification</i></a></dt> | |
| <dd>Short for <a href="#keep"><code>-keep</code></a>,<a href="#allowshrinking"><code>allowshrinking</code></a> | |
| <a href="#classspecification"><i>class_specification</i></a> | |
| <p> | |
| Specifies classes and class members whose names are to be preserved, if | |
| they aren't removed in the shrinking phase. For example, you may want to | |
| <a href="examples.html#serializable">keep all class names</a> of classes | |
| that implement the <code>Serializable</code> interface, so that the | |
| processed code remains compatible with any originally serialized classes. | |
| Classes that aren't used at all can still be removed. Only applicable when | |
| obfuscating.</dd> | |
| <dt><a name="keepclassmembernames"><code><b>-keepclassmembernames</b></code></a> | |
| <a href="#classspecification"><i>class_specification</i></a></dt> | |
| <dd>Short for <a href="#keepclassmembers"><code>-keepclassmembers</code></a>,<a href="#allowshrinking"><code>allowshrinking</code></a> | |
| <a href="#classspecification"><i>class_specification</i></a> | |
| <p> | |
| Specifies class members whose names are to be preserved, if they aren't | |
| removed in the shrinking phase. For example, you may want to preserve the | |
| name of the synthetic <code>class$</code> methods | |
| when <a href="examples.html#library">processing a library</a> compiled by | |
| JDK 1.2 or older, so obfuscators can detect it again when processing an | |
| application that uses the processed library (although ProGuard itself | |
| doesn't need this). Only applicable when obfuscating.</dd> | |
| <dt><a name="keepclasseswithmembernames"><code><b>-keepclasseswithmembernames</b></code></a> | |
| <a href="#classspecification"><i>class_specification</i></a></dt> | |
| <dd>Short for <a href="#keepclasseswithmembers"><code>-keepclasseswithmembers</code></a>,<a href="#allowshrinking"><code>allowshrinking</code></a> | |
| <a href="#classspecification"><i>class_specification</i></a> | |
| <p> | |
| Specifies classes and class members whose names are to be preserved, on | |
| the condition that all of the specified class members are present after | |
| the shrinking phase. For example, you may want to <a | |
| href="examples.html#native">keep all native method names</a> and the names | |
| of their classes, so that the processed code can still link with the | |
| native library code. Native methods that aren't used at all can still be | |
| removed. If a class file is used, but none of its native methods are, its | |
| name will still be obfuscated. Only applicable when obfuscating.</dd> | |
| <dt><a name="printseeds"><code><b>-printseeds</b></code></a> | |
| [<a href="#filename"><i>filename</i></a>]</dt> | |
| <dd>Specifies to exhaustively list classes and class members matched by the | |
| various <code>-keep</code> options. The list is printed to the standard | |
| output or to the given file. The list can be useful to verify if the | |
| intended class members are really found, especially if you're using | |
| wildcards. For example, you may want to list all the <a | |
| href="examples.html#applications">applications</a> or all the <a | |
| href="examples.html#applets">applets</a> that you are keeping.</dd> | |
| </dl> | |
| <p> | |
| <h2><a name="shrinkingoptions">Shrinking Options</a></h2> | |
| <dl> | |
| <dt><a name="dontshrink"><code><b>-dontshrink</b></code></a></dt> | |
| <dd>Specifies not to shrink the input class files. By default, shrinking is | |
| applied; all classes and class members are removed, except for the ones | |
| listed by the various <code>-keep</code> options, and the ones on which | |
| they depend, directly or indirectly. A shrinking step is also applied | |
| after each optimization step, since some optimizations may open the | |
| possibility to remove more classes and class members.</dd> | |
| <dt><a name="printusage"><code><b>-printusage</b></code></a> | |
| [<a href="#filename"><i>filename</i></a>]</dt> | |
| <dd>Specifies to list dead code of the input class files. The list is printed | |
| to the standard output or to the given file. For example, you can <a | |
| href="examples.html#deadcode">list the unused code of an application</a>. | |
| Only applicable when shrinking.</dd> | |
| <dt><a name="whyareyoukeeping"><code><b>-whyareyoukeeping</b></code></a> | |
| <a href="#classspecification"><i>class_specification</i></a></dt> | |
| <dd>Specifies to print details on why the given classes and class members are | |
| being kept in the shrinking step. This can be useful if you are wondering | |
| why some given element is present in the output. In general, there can be | |
| many different reasons. This option prints the shortest chain of methods | |
| to a specified seed or entry point, for each specified class and class | |
| member. <i>In the current implementation, the shortest chain that is | |
| printed out may sometimes contain circular deductions -- these do not | |
| reflect the actual shrinking process.</i> If the <a | |
| href="#verbose"><code>-verbose</code></a> option if specified, the traces | |
| include full field and method signatures. Only applicable when | |
| shrinking.</dd> | |
| </dl> | |
| <p> | |
| <h2><a name="optimizationoptions">Optimization Options</a></h2> | |
| <dl> | |
| <dt><a name="dontoptimize"><code><b>-dontoptimize</b></code></a></dt> | |
| <dd>Specifies not to optimize the input class files. By default, optimization | |
| is enabled; all methods are optimized at a bytecode level.</dd> | |
| <dt><a name="optimizations"><code><b>-optimizations</b></code></a> | |
| <a href="optimizations.html"><i>optimization_filter</i></a></dt> | |
| <dd>Specifies the optimizations to be enabled and disabled, at a more | |
| fine-grained level. Only applicable when optimizing. <i>This is an expert | |
| option.</i></dd> | |
| <dt><a name="optimizationpasses"><code><b>-optimizationpasses</b></code></a> <i>n</i></dt> | |
| <dd>Specifies the number of optimization passes to be performed. By default, a | |
| single pass is performed. Multiple passes may result in further | |
| improvements. If no improvements are found after an optimization pass, the | |
| optimization is ended. Only applicable when optimizing.</dd> | |
| <dt><a name="assumenosideeffects"><code><b>-assumenosideeffects</b></code></a> | |
| <a href="#classspecification"><i>class_specification</i></a></dt> | |
| <dd>Specifies methods that don't have any side effects (other than maybe | |
| returning a value). In the optimization step, ProGuard will then remove | |
| calls to such methods, if it can determine that the return values aren't | |
| used. ProGuard will analyze your program code to find such methods | |
| automatically. It will not analyze library code, for which this option can | |
| therefore be useful. For example, you could specify the method | |
| <code>System.currentTimeMillis()</code>, so that any idle calls to it will | |
| be removed. With some care, you can also use the option to | |
| <a href="examples.html#logging">remove logging code</a>. Note that | |
| ProGuard applies the option to the entire hierarchy of the specified | |
| methods. Only applicable when optimizing. In general, making assumptions | |
| can be dangerous; you can easily break the processed code. <i>Only use | |
| this option if you know what you're doing!</i></dd> | |
| <dt><a name="allowaccessmodification"><code><b>-allowaccessmodification</b></code></a></dt> | |
| <dd>Specifies that the access modifiers of classes and class members may be | |
| broadened during processing. This can improve the results of the | |
| optimization step. For instance, when inlining a public getter, it may be | |
| necessary to make the accessed field public too. Although Java's binary | |
| compatibility specifications formally do not require this (cfr. <a href= | |
| "http://docs.oracle.com/javase/specs/jls/se5.0/html/j3TOC.html" | |
| >The Java Language Specification, Third Edition</a>, <a href= | |
| "http://docs.oracle.com/javase/specs/jls/se5.0/html/binaryComp.html#13.4.6" | |
| >Section 13.4.6</a>), some virtual machines would have problems with the | |
| processed code otherwise. Only applicable when optimizing (and when | |
| obfuscating with the <a | |
| href="#repackageclasses"><code>-repackageclasses</code></a> option). | |
| <p> | |
| <i>Counter-indication:</i> you probably shouldn't use this option when | |
| processing code that is to be used as a library, since classes and class | |
| members that weren't designed to be public in the API may become | |
| public.</dd> | |
| <dt><a name="mergeinterfacesaggressively"><code><b>-mergeinterfacesaggressively</b></code></a></dt> | |
| <dd>Specifies that interfaces may be merged, even if their implementing | |
| classes don't implement all interface methods. This can reduce the size of | |
| the output by reducing the total number of classes. Note that Java's | |
| binary compatibility specifications allow such constructs (cfr. <a href= | |
| "http://docs.oracle.com/javase/specs/jls/se5.0/html/j3TOC.html" | |
| >The Java Language Specification, Third Edition</a>, <a href= | |
| "http://docs.oracle.com/javase/specs/jls/se5.0/html/binaryComp.html#13.5.3" | |
| >Section 13.5.3</a>), even if they are not allowed in the Java language | |
| (cfr. <a href= | |
| "http://docs.oracle.com/javase/specs/jls/se5.0/html/j3TOC.html" | |
| >The Java Language Specification, Third Edition</a>, <a href= | |
| "http://docs.oracle.com/javase/specs/jls/se5.0/html/classes.html#8.1.4" | |
| >Section 8.1.4</a>). Only applicable when optimizing. | |
| <p> | |
| <i>Counter-indication:</i> setting this option can reduce the performance | |
| of the processed code on some JVMs, since advanced just-in-time | |
| compilation tends to favor more interfaces with fewer implementing | |
| classes. Worse, some JVMs may not be able to handle the resulting code. | |
| Notably: | |
| <ul> | |
| <li>Sun's JRE 1.3 may throw an <code>InternalError</code> when | |
| encountering more than 256 <i>Miranda</i> methods (interface methods | |
| without implementations) in a class.</li> | |
| </ul></dd> | |
| </dl> | |
| <p> | |
| <h2><a name="obfuscationoptions">Obfuscation Options</a></h2> | |
| <dl> | |
| <dt><a name="dontobfuscate"><code><b>-dontobfuscate</b></code></a></dt> | |
| <dd>Specifies not to obfuscate the input class files. By default, obfuscation | |
| is applied; classes and class members receive new short random names, | |
| except for the ones listed by the various <code>-keep</code> options. | |
| Internal attributes that are useful for debugging, such as source files | |
| names, variable names, and line numbers are removed.</dd> | |
| <dt><a name="printmapping"><code><b>-printmapping</b></code></a> | |
| [<a href="#filename"><i>filename</i></a>]</dt> | |
| <dd>Specifies to print the mapping from old names to new names for classes and | |
| class members that have been renamed. The mapping is printed to the | |
| standard output or to the given file. For example, it is required for | |
| subsequent <a href="examples.html#incremental">incremental | |
| obfuscation</a>, or if you ever want to make sense again of <a | |
| href="examples.html#stacktrace">obfuscated stack traces</a>. Only | |
| applicable when obfuscating.</dd> | |
| <dt><a name="applymapping"><code><b>-applymapping</b></code></a> | |
| <a href="#filename"><i>filename</i></a></dt> | |
| <dd>Specifies to reuse the given name mapping that was printed out in a | |
| previous obfuscation run of ProGuard. Classes and class members that are | |
| listed in the mapping file receive the names specified along with them. | |
| Classes and class members that are not mentioned receive new names. The | |
| mapping may refer to input classes as well as library classes. This option | |
| can be useful for <a href="examples.html#incremental">incremental | |
| obfuscation</a>, i.e. processing add-ons or small patches to an existing | |
| piece of code. If the structure of the code changes fundamentally, | |
| ProGuard may print out warnings that applying a mapping is causing | |
| conflicts. You may be able to reduce this risk by specifying the option <a | |
| href="#useuniqueclassmembernames"><code>-useuniqueclassmembernames</code></a> | |
| in both obfuscation runs. Only a single mapping file is allowed. Only | |
| applicable when obfuscating.</dd> | |
| <dt><a name="obfuscationdictionary"><code><b>-obfuscationdictionary</b></code></a> | |
| <a href="#filename"><i>filename</i></a></dt> | |
| <dd>Specifies a text file from which all valid words are used as obfuscated | |
| field and method names. By default, short names like 'a', 'b', etc. are | |
| used as obfuscated names. With an obfuscation dictionary, you can specify | |
| a list of reserved key words, or identifiers with foreign characters, for | |
| instance. White space, punctuation characters, duplicate words, and | |
| comments after a <code><b>#</b></code> sign are ignored. Note that an | |
| obfuscation dictionary hardly improves the obfuscation. Decent compilers | |
| can automatically replace them, and the effect can fairly simply be undone | |
| by obfuscating again with simpler names. The most useful application is | |
| specifying strings that are typically already present in class files (such | |
| as 'Code'), thus reducing the class file sizes just a little bit more. | |
| Only applicable when obfuscating.</dd> | |
| <dt><a name="classobfuscationdictionary"><code><b>-classobfuscationdictionary</b></code></a> | |
| <a href="#filename"><i>filename</i></a></dt> | |
| <dd>Specifies a text file from which all valid words are used as obfuscated | |
| class names. The obfuscation dictionary is similar to the one of the | |
| option <a | |
| href="#obfuscationdictionary"><code>-obfuscationdictionary</code></a>. | |
| Only applicable when obfuscating.</dd> | |
| <dt><a name="packageobfuscationdictionary"><code><b>-packageobfuscationdictionary</b></code></a> | |
| <a href="#filename"><i>filename</i></a></dt> | |
| <dd>Specifies a text file from which all valid words are used as obfuscated | |
| package names. The obfuscation dictionary is similar to the one of the | |
| option <a | |
| href="#obfuscationdictionary"><code>-obfuscationdictionary</code></a>. | |
| Only applicable when obfuscating.</dd> | |
| <dt><a name="overloadaggressively"><code><b>-overloadaggressively</b></code></a></dt> | |
| <dd>Specifies to apply aggressive overloading while obfuscating. Multiple | |
| fields and methods can then get the same names, as long as their arguments | |
| and return types are different, as required by Java bytecode (not just | |
| their arguments, as required by the Java language). This option can make | |
| the processed code even smaller (and less comprehensible). Only applicable | |
| when obfuscating. | |
| <p> | |
| <i>Counter-indication:</i> the resulting class files fall within the Java | |
| bytecode specification (cfr. <a href= | |
| "http://docs.oracle.com/javase/specs/jvms/se5.0/html/VMSpecTOC.doc.html" | |
| >The Java Virtual Machine Specification, Second Edition</a>, first | |
| paragraphs of <a href= | |
| "http://docs.oracle.com/javase/specs/jvms/se5.0/html/ClassFile.doc.html#2877" | |
| >Section 4.5</a> and <a href= | |
| "http://docs.oracle.com/javase/specs/jvms/se5.0/html/ClassFile.doc.html#1513" | |
| >Section 4.6</a>), even though this kind of overloading is not allowed in | |
| the Java language (cfr. <a href= | |
| "http://docs.oracle.com/javase/specs/jls/se5.0/html/j3TOC.html" | |
| >The Java Language Specification, Third Edition</a>, <a href= | |
| "http://docs.oracle.com/javase/specs/jls/se5.0/html/classes.html#8.3" | |
| >Section 8.3</a> and <a href= | |
| "http://docs.oracle.com/javase/specs/jls/se5.0/html/classes.html#8.4.5" | |
| >Section 8.4.5</a>). Still, some tools have problems with it. Notably: | |
| <ul> | |
| <li>Sun's JDK 1.2.2 <code>javac</code> compiler produces an exception when | |
| compiling with such a library (cfr. <a href= | |
| "http://bugs.sun.com/view_bug.do?bug_id=4216736">Bug #4216736</a>). | |
| You probably shouldn't use this option for processing libraries.</li> | |
| <li>Sun's JRE 1.4 and later fail to serialize objects with overloaded | |
| primitive fields.</li> | |
| <li>Sun's JRE 1.5 <code>pack200</code> tool reportedly has problems with | |
| overloaded class members.</li> | |
| <li>The class <code>java.lang.reflect.Proxy</code> can't handle overloaded | |
| methods.</li> | |
| <li>Google's Dalvik VM can't handle overloaded static fields.</li> | |
| </ul></dd> | |
| <dt><a name="useuniqueclassmembernames"><code><b>-useuniqueclassmembernames</b></code></a></dt> | |
| <dd>Specifies to assign the same obfuscated names to class members that have | |
| the same names, and different obfuscated names to class members that have | |
| different names (for each given class member signature). Without the | |
| option, more class members can be mapped to the same short names like 'a', | |
| 'b', etc. The option therefore increases the size of the resulting code | |
| slightly, but it ensures that the saved obfuscation name mapping can | |
| always be respected in subsequent incremental obfuscation steps. | |
| <p> | |
| For instance, consider two distinct interfaces containing methods with the | |
| same name and signature. Without this option, these methods may get | |
| different obfuscated names in a first obfuscation step. If a patch is then | |
| added containing a class that implements both interfaces, ProGuard will | |
| have to enforce the same method name for both methods in an incremental | |
| obfuscation step. The original obfuscated code is changed, in order to | |
| keep the resulting code consistent. With this option <i>in the initial | |
| obfuscation step</i>, such renaming will never be necessary. | |
| <p> | |
| This option is only applicable when obfuscating. In fact, if you are | |
| planning on performing incremental obfuscation, you probably want to avoid | |
| shrinking and optimization altogether, since these steps could remove or | |
| modify parts of your code that are essential for later additions.</dd> | |
| <dt><a name="dontusemixedcaseclassnames"><code><b>-dontusemixedcaseclassnames</b></code></a></dt> | |
| <dd>Specifies not to generate mixed-case class names while obfuscating. By | |
| default, obfuscated class names can contain a mix of upper-case characters | |
| and lower-case characters. This creates perfectly acceptable and usable | |
| jars. Only if a jar is unpacked on a platform with a case-insensitive | |
| filing system (say, Windows), the unpacking tool may let similarly named | |
| class files overwrite each other. Code that self-destructs when it's | |
| unpacked! Developers who really want to unpack their jars on Windows can | |
| use this option to switch off this behavior. Obfuscated jars will become | |
| slightly larger as a result. Only applicable when obfuscating.</dd> | |
| <dt><a name="keeppackagenames"><code><b>-keeppackagenames</b></code></a> | |
| [<i><a href="#filters">package_filter</a></i>]</dt> | |
| <dd>Specifies not to obfuscate the given package names. The optional filter is | |
| a comma-separated list of package names. Package names can contain | |
| <b>?</b>, <b>*</b>, and <b>**</b> wildcards, and they can be preceded by | |
| the <b>!</b> negator. Only applicable when obfuscating.</dd> | |
| <dt><a name="flattenpackagehierarchy"><code><b>-flattenpackagehierarchy</b></code></a> | |
| [<i>package_name</i>]</dt> | |
| <dd>Specifies to repackage all packages that are renamed, by moving them into | |
| the single given parent package. Without argument or with an empty string | |
| (''), the packages are moved into the root package. This option is one | |
| example of further <a href="examples.html#repackaging">obfuscating package | |
| names</a>. It can make the processed code smaller and less comprehensible. | |
| Only applicable when obfuscating.</dd> | |
| <dt><a name="repackageclasses"><code><b>-repackageclasses</b></code></a> | |
| [<i>package_name</i>]</dt> | |
| <dd>Specifies to repackage all class files that are renamed, by moving them | |
| into the single given package. Without argument or with an empty string | |
| (''), the package is removed completely. This option overrides the | |
| <a | |
| href="#flattenpackagehierarchy"><code>-flattenpackagehierarchy</code></a> | |
| option. It is another example of further <a | |
| href="examples.html#repackaging">obfuscating package names</a>. It can | |
| make the processed code even smaller and less comprehensible. Its | |
| deprecated name is <code>-defaultpackage</code>. Only applicable when | |
| obfuscating. | |
| <p> | |
| <i>Counter-indication:</i> classes that look for resource files in their | |
| package directories will no longer work properly if they are moved | |
| elsewhere. When in doubt, just leave the packaging untouched by not using | |
| this option.</dd> | |
| <dt><a name="keepattributes"><code><b>-keepattributes</b></code></a> | |
| [<i><a href="attributes.html">attribute_filter</a></i>]</dt> | |
| <dd>Specifies any optional attributes to be preserved. The attributes can be | |
| specified with one or more <code>-keepattributes</code> directives. The | |
| optional filter is a comma-separated list | |
| of <a href="attributes.html">attribute names</a> that Java virtual | |
| machines and ProGuard support. Attribute names can | |
| contain <b>?</b>, <b>*</b>, and <b>**</b> wildcards, and they can be | |
| preceded by the <b>!</b> negator. For example, you should at least keep | |
| the <code>Exceptions</code>, <code>InnerClasses</code>, and | |
| <code>Signature</code> attributes when | |
| <a href="examples.html#library">processing a library</a>. You should also | |
| keep the <code>SourceFile</code> and <code>LineNumberTable</code> | |
| attributes for <a href="examples.html#stacktrace">producing useful | |
| obfuscated stack traces</a>. Finally, you may want | |
| to <a href="examples.html#annotations">keep annotations</a> if your code | |
| depends on them. Only applicable when obfuscating.</dd> | |
| <dt><a name="keepparameternames"><code><b>-keepparameternames</b></code></a></dt> | |
| <dd>Specifies to keep the parameter names and types of methods that are kept. | |
| This option actually keeps trimmed versions of the debugging attributes | |
| <code>LocalVariableTable</code> and | |
| <code>LocalVariableTypeTable</code>. It can be useful when | |
| <a href="examples.html#library">processing a library</a>. Some IDEs can | |
| use the information to assist developers who use the library, for example | |
| with tool tips or autocompletion. Only applicable when obfuscating.</dd> | |
| <dt><a name="renamesourcefileattribute"><code><b>-renamesourcefileattribute</b></code></a> | |
| [<i>string</i>]</dt> | |
| <dd>Specifies a constant string to be put in the <code>SourceFile</code> | |
| attributes (and <code>SourceDir</code> attributes) of the class files. | |
| Note that the attribute has to be present to start with, so it also has to | |
| be preserved explicitly using the <code>-keepattributes</code> directive. | |
| For example, you may want to have your processed libraries and | |
| applications produce <a href="examples.html#stacktrace">useful obfuscated | |
| stack traces</a>. Only applicable when obfuscating.</dd> | |
| <dt><a name="adaptclassstrings"><code><b>-adaptclassstrings</b></code></a> | |
| [<i><a href="#filters">class_filter</a></i>]</dt> | |
| <dd>Specifies that string constants that correspond to class names should be | |
| obfuscated as well. Without a filter, all string constants that correspond | |
| to class names are adapted. With a filter, only string constants in | |
| classes that match the filter are adapted. For example, if your code | |
| contains a large number of hard-coded strings that refer to classes, and | |
| you prefer not to keep their names, you may want to use this option. | |
| Primarily applicable when obfuscating, although corresponding classes are | |
| automatically kept in the shrinking step too.</dd> | |
| <dt><a name="adaptresourcefilenames"><code><b>-adaptresourcefilenames</b></code></a> | |
| [<i><a href="#filefilters">file_filter</a></i>]</dt> | |
| <dd>Specifies the resource files to be renamed, based on the obfuscated names | |
| of the corresponding class files (if any). Without a filter, all resource | |
| files that correspond to class files are renamed. With a filter, only | |
| matching files are renamed. For example, see <a | |
| href="examples.html#resourcefiles">processing resource files</a>. Only | |
| applicable when obfuscating.</dd> | |
| <dt><a name="adaptresourcefilecontents"><code><b>-adaptresourcefilecontents</b></code></a> | |
| [<i><a href="#filefilters">file_filter</a></i>]</dt> | |
| <dd>Specifies the resource files whose contents are to be updated. Any class | |
| names mentioned in the resource files are renamed, based on the obfuscated | |
| names of the corresponding classes (if any). Without a filter, the | |
| contents of all resource files updated. With a filter, only matching files | |
| are updated. The resource files are parsed and written using the | |
| platform's default character set. You can change this default character set | |
| by setting the environment variable <code>LANG</code> or the Java system | |
| property <code>file.encoding</code>. For an example, | |
| see <a href="examples.html#resourcefiles">processing resource files</a>. | |
| Only applicable when obfuscating. | |
| <p> | |
| <i>Caveat:</i> You probably only want to apply this option to text files, | |
| since parsing and adapting binary files as text files can cause unexpected | |
| problems. Therefore, make sure that you specify a sufficiently narrow | |
| filter.</dd> | |
| </dl> | |
| <p> | |
| <h2><a name="preverificationoptions">Preverification Options</a></h2> | |
| <dl> | |
| <dt><a name="dontpreverify"><code><b>-dontpreverify</b></code></a></dt> | |
| <dd>Specifies not to preverify the processed class files. By default, class | |
| files are preverified if they are targeted at Java Micro Edition or at | |
| Java 6 or higher. For Java Micro Edition, preverification is required, so | |
| you will need to run an external preverifier on the processed code if you | |
| specify this option. For Java 6, preverification is optional, but as of | |
| Java 7, it is required. Only when eventually targeting Android, it is not | |
| necessary, so you can then switch it off to reduce the processing time a | |
| bit.</dd> | |
| <dt><a name="microedition"><code><b>-microedition</b></code></a></dt> | |
| <dd>Specifies that the processed class files are targeted at Java Micro | |
| Edition. The preverifier will then add the appropriate StackMap | |
| attributes, which are different from the default StackMapTable attributes | |
| for Java Standard Edition. For example, you will need this option if you | |
| are <a href="examples.html#midlets">processing midlets</a>.</dd> | |
| </dl> | |
| <p> | |
| <h2><a name="generaloptions">General Options</a></h2> | |
| <dl> | |
| <dt><a name="verbose"><code><b>-verbose</b></code></a></dt> | |
| <dd>Specifies to write out some more information during processing. If the | |
| program terminates with an exception, this option will print out the entire | |
| stack trace, instead of just the exception message.</dd> | |
| <dt><a name="dontnote"><code><b>-dontnote</b></code></a> | |
| [<i><a href="#filters">class_filter</a></i>]</dt> | |
| <dd>Specifies not to print notes about potential mistakes or omissions in the | |
| configuration, such as typos in class names or missing options that | |
| might be useful. The optional filter is a regular expression; ProGuard | |
| doesn't print notes about classes with matching names.</dd> | |
| <dt><a name="dontwarn"><code><b>-dontwarn</b></code></a> | |
| [<i><a href="#filters">class_filter</a></i>]</dt> | |
| <dd>Specifies not to warn about unresolved references and other important | |
| problems at all. The optional filter is a regular expression; ProGuard | |
| doesn't print warnings about classes with matching names. Ignoring | |
| warnings can be dangerous. For instance, if the unresolved classes or | |
| class members are indeed required for processing, the processed code will | |
| not function properly. <i>Only use this option if you know what you're | |
| doing!</i></dd> | |
| <dt><a name="ignorewarnings"><code><b>-ignorewarnings</b></code></a></dt> | |
| <dd>Specifies to print any warnings about unresolved references and other | |
| important problems, but to continue processing in any case. Ignoring | |
| warnings can be dangerous. For instance, if the unresolved classes or | |
| class members are indeed required for processing, the processed code will | |
| not function properly. <i>Only use this option if you know what you're | |
| doing!</i></dd> | |
| <dt><a name="printconfiguration"><code><b>-printconfiguration</b></code></a> | |
| [<a href="#filename"><i>filename</i></a>]</dt> | |
| <dd>Specifies to write out the entire configuration that has been parsed, with | |
| included files and replaced variables. The structure is printed to the | |
| standard output or to the given file. This can sometimes be useful for | |
| debugging configurations, or for converting XML configurations into a more | |
| readable format.</dd> | |
| <dt><a name="dump"><code><b>-dump</b></code></a> | |
| [<a href="#filename"><i>filename</i></a>]</dt> | |
| <dd>Specifies to write out the internal structure of the class files, after | |
| any processing. The structure is printed to the standard output or to the | |
| given file. For example, you may want to <a | |
| href="examples.html#structure">write out the contents of a given jar | |
| file</a>, without processing it at all.</dd> | |
| </dl> | |
| <p> | |
| <h2><a name="classpath">Class Paths</a></h2> | |
| ProGuard accepts a generalization of class paths to specify input files and | |
| output files. A class path consists of entries, separated by the traditional | |
| path separator (e.g. '<b>:</b>' on Unix, or '<b>;</b>' on Windows platforms). | |
| The order of the entries determines their priorities, in case of duplicates. | |
| <p> | |
| Each input entry can be: | |
| <ul> | |
| <li>A class file or resource file,</li> | |
| <li>An apk file, containing any of the above,</li> | |
| <li>A jar file, containing any of the above,</li> | |
| <li>An aar file, containing any of the above,</li> | |
| <li>A war file, containing any of the above,</li> | |
| <li>An ear file, containing any of the above,</li> | |
| <li>A zip file, containing any of the above,</li> | |
| <li>A directory (structure), containing any of the above.</li> | |
| </ul> | |
| <p> | |
| The paths of directly specified class files and resource files is ignored, so | |
| class files should generally be part of a jar file, an aar file, a war file, | |
| an ear file, a zip file, or a directory. In addition, the paths of class files | |
| should not have any additional directory prefixes inside the archives or | |
| directories. | |
| <p> | |
| Each output entry can be: | |
| <ul> | |
| <li>An apk file, in which all class files and resource files will be | |
| collected.</li> | |
| <li>A jar file, in which any and all of the above will be collected,</li> | |
| <li>An aar file, in which any and all of the above will be collected,</li> | |
| <li>A war file, in which any and all of the above will be collected,</li> | |
| <li>An ear file, in which any and all of the above will be collected,</li> | |
| <li>A zip file, in which any and all of the above will be collected,</li> | |
| <li>A directory, in which any and all of the above will be collected.</li> | |
| </ul> | |
| <p> | |
| When writing output entries, ProGuard will generally package the results in a | |
| sensible way, reconstructing the input entries as much as required. Writing | |
| everything to an output directory is the most straightforward option: the | |
| output directory will contain a complete reconstruction of the input entries. | |
| The packaging can be almost arbitrarily complex though: you could process an | |
| entire application, packaged in a zip file along with its documentation, | |
| writing it out as a zip file again. The Examples section shows a few ways | |
| to <a href="examples.html#restructuring">restructure output archives</a>. | |
| <p> | |
| Files and directories can be specified as discussed in the section on <a | |
| href="#filename">file names</a> below. | |
| <p> | |
| In addition, ProGuard provides the possibility to filter the class path | |
| entries and their contents, based on their full relative file names. Each | |
| class path entry can be followed by up to 7 types of <a | |
| href="#filefilters">file filters</a> between parentheses, separated by | |
| semi-colons: | |
| <ul> | |
| <li>A filter for all aar names that are encountered,</li> | |
| <li>A filter for all apk names that are encountered,</li> | |
| <li>A filter for all zip names that are encountered,</li> | |
| <li>A filter for all ear names that are encountered,</li> | |
| <li>A filter for all war names that are encountered,</li> | |
| <li>A filter for all jar names that are encountered,</li> | |
| <li>A filter for all class file names and resource file names that are | |
| encountered.</li> | |
| </ul> | |
| <p> | |
| If fewer than 7 filters are specified, they are assumed to be the latter | |
| filters. Any empty filters are ignored. More formally, a filtered class path | |
| entry looks like this: | |
| <pre> | |
| <i>classpathentry</i><b>(</b>[[[[[[<i>aarfilter</i><b>;</b>]<i>apkfilter</i><b>;</b>]<i>zipfilter</i><b>;</b>]<i>earfilter</i><b>;</b>]<i>warfilter</i><b>;</b>]<i>jarfilter</i><b>;</b>]<i>filefilter</i><b>)</b> | |
| </pre> | |
| <p> | |
| Square brackets "[]" mean that their contents are optional. | |
| <p> | |
| For example, "<code>rt.jar(java/**.class,javax/**.class)</code>" matches all | |
| class files in the <code>java</code> and <code>javax</code> directories inside | |
| the <code>rt</code> jar. | |
| <p> | |
| For example, "<code>input.jar(!**.gif,images/**)</code>" matches all files in | |
| the <code>images</code> directory inside the <code>input</code> jar, except | |
| gif files. | |
| <p> | |
| The different filters are applied to all corresponding file types, irrespective | |
| of their nesting levels in the input; they are orthogonal. | |
| <p> | |
| For example, | |
| "<code>input.war(lib/**.jar,support/**.jar;**.class,**.gif)</code>" only | |
| considers jar files in the <code>lib</code> and <code>support</code> | |
| directories in the <code>input</code> war, not any other jar files. It then | |
| matches all class files and gif files that are encountered. | |
| <p> | |
| The filters allow for an almost infinite number of packaging and repackaging | |
| possibilities. The Examples section provides a few more examples | |
| for <a href="examples.html#filtering">filtering input and output</a>. | |
| <p> | |
| <h2><a name="filename">File Names</a></h2> | |
| ProGuard accepts absolute paths and relative paths for the various file names | |
| and directory names. A relative path is interpreted as follows: | |
| <ul> | |
| <li>relative to the base directory, if set, or otherwise</li> | |
| <li>relative to the configuration file in which it is specified, if any, or | |
| otherwise</li> | |
| <li>relative to the working directory.</li> | |
| </ul> | |
| <p> | |
| The names can contain Java system properties (or Ant properties, when using | |
| Ant), delimited by angular brackets, '<b><</b>' and '<b>></b>'. The | |
| properties are automatically replaced by their corresponding values. | |
| <p> | |
| For example, <code><java.home>/lib/rt.jar</code> is automatically | |
| expanded to something like <code>/usr/local/java/jdk/jre/lib/rt.jar</code>. | |
| Similarly, <code><user.home></code> is expanded to the user's home | |
| directory, and <code><user.dir></code> is expanded to the current | |
| working directory. | |
| <p> | |
| Names with special characters like spaces and parentheses must be quoted with | |
| single or double quotes. Each file name in a list of names has to be quoted | |
| individually. Note that the quotes themselves may need to be escaped when used | |
| on the command line, to avoid them being gobbled by the shell. | |
| <p> | |
| For example, on the command line, you could use an option like <code>'-injars | |
| "my program.jar":"/your directory/your program.jar"'</code>. | |
| <p> | |
| <h2><a name="filefilters">File Filters</a></h2> | |
| Like general <a href="#filters">filters</a>, a file filter is a | |
| comma-separated list of file names that can contain wildcards. Only files with | |
| matching file names are read (in the case of input jars), or written (in the | |
| case of output jars). The following wildcards are supported: | |
| <table cellspacing="10"> | |
| <tr><td valign="top"><code><b>?</b></code></td> | |
| <td>matches any single character in a file name.</td></tr> | |
| <tr><td valign="top"><code><b>*</b></code></td> | |
| <td>matches any part of a filename not containing the directory | |
| separator.</td></tr> | |
| <tr><td valign="top"><code><b>**</b></code></td> | |
| <td>matches any part of a filename, possibly containing any number of | |
| directory separators.</td></tr> | |
| </table> | |
| For example, "<code>java/**.class,javax/**.class</code>" matches all | |
| class files in the <code>java</code> and <code>javax</code>. | |
| <p> | |
| Furthermore, a file name can be preceded by an exclamation mark '<b>!</b>' to | |
| <i>exclude</i> the file name from further attempts to match with | |
| <i>subsequent</i> file names. | |
| <p> | |
| For example, "<code>!**.gif,images/**</code>" matches all files in the | |
| <code>images</code> directory, except gif files. | |
| <p> | |
| The Examples section provides a few more examples for <a | |
| href="examples.html#filtering">filtering input and output</a>. | |
| <h2><a name="filters">Filters</a></h2> | |
| ProGuard offers options with filters for many different aspects of the | |
| configuration: names of files, directories, classes, packages, attributes, | |
| optimizations, etc. | |
| <p> | |
| A filter is a list of comma-separated names that can contain wildcards. Only | |
| names that match an item on the list pass the filter. The supported wildcards | |
| depend on the type of names for which the filter is being used, but the | |
| following wildcards are typical: | |
| <table cellspacing="10"> | |
| <tr><td valign="top"><code><b>?</b></code></td> | |
| <td>matches any single character in a name.</td></tr> | |
| <tr><td valign="top"><code><b>*</b></code></td> | |
| <td>matches any part of a name not containing the package separator or | |
| directory separator.</td></tr> | |
| <tr><td valign="top"><code><b>**</b></code></td> | |
| <td>matches any part of a name, possibly containing any number of | |
| package separators or directory separators.</td></tr> | |
| </table> | |
| For example, "<code>foo,*bar</code>" matches the name <code>foo</code> and | |
| all names ending with <code>bar</code>. | |
| <p> | |
| Furthermore, a name can be preceded by a negating exclamation mark '<b>!</b>' | |
| to <i>exclude</i> the name from further attempts to match | |
| with <i>subsequent</i> names. So, if a name matches an item in the filter, it | |
| is accepted or rejected right away, depending on whether the item has a | |
| negator. If the name doesn't match the item, it is tested against the next | |
| item, and so on. It if doesn't match any items, it is accepted or rejected, | |
| depending on the whether the last item has a negator or not. | |
| <p> | |
| For example, "<code>!foobar,*bar</code>" matches all names ending with | |
| <code>bar</code>, except <code>foobar</code>. | |
| <p> | |
| <h2><a name="keepoverview">Overview of <code>Keep</code> Options</a></h2> | |
| The various <code>-keep</code> options for shrinking and obfuscation may seem | |
| a bit confusing at first, but there's actually a pattern behind them. The | |
| following table summarizes how they are related: | |
| <p> | |
| <table cellpadding="5"> | |
| <tr> | |
| <th>Keep</th> | |
| <td>From being removed or renamed</td> | |
| <td>From being renamed</td> | |
| </tr> | |
| <tr> | |
| <td>Classes and class members</td> | |
| <td bgcolor="#E0E0E0"><a href="#keep"><code>-keep</code></a></td> | |
| <td bgcolor="#E0E0E0"><a href="#keepnames"><code>-keepnames</code></a></td> | |
| </tr> | |
| <tr> | |
| <td>Class members only</td> | |
| <td bgcolor="#E0E0E0"><a href="#keepclassmembers"><code>-keepclassmembers</code></a></td> | |
| <td bgcolor="#E0E0E0"><a href="#keepclassmembernames"><code>-keepclassmembernames</code></a></td> | |
| </tr> | |
| <tr> | |
| <td>Classes and class members, if class members present</td> | |
| <td bgcolor="#E0E0E0"><a href="#keepclasseswithmembers"><code>-keepclasseswithmembers</code></a></td> | |
| <td bgcolor="#E0E0E0"><a href="#keepclasseswithmembernames"><code>-keepclasseswithmembernames</code></a></td> | |
| </tr> | |
| </table> | |
| <p> | |
| Each of these <code>-keep</code> options is of course followed by a | |
| <a href="#classspecification">specification</a> of the classes and class | |
| members (fields and methods) to which it should be applied. | |
| <p> | |
| If you're not sure which option you need, you should probably simply use | |
| <code>-keep</code>. It will make sure the specified classes and class members | |
| are not removed in the shrinking step, and not renamed in the obfuscation step. | |
| <p> | |
| <img class="float" src="attention.gif" width="64" height="64" alt="attention" /> | |
| <ul class="shifted"> | |
| <li>If you specify a class, without class members, ProGuard only preserves the | |
| class and its parameterless constructor as entry points. It may | |
| still remove, optimize, or obfuscate its other class members.</li> | |
| <li>If you specify a method, ProGuard only preserves the method as an entry | |
| point. Its code may still be optimized and adapted.</li> | |
| </ul> | |
| <p> | |
| <h2><a name="keepoptionmodifiers">Keep Option Modifiers</a></h2> | |
| <dl> | |
| <dt><a name="includedescriptorclasses"><code><b>includedescriptorclasses</b></code></a></dt> | |
| <dd>Specifies that any classes in the type descriptors of the methods and | |
| fields that the <a href="#keep">-keep</a> option keeps should be kept as | |
| well. This is typically useful when <a href="examples.html#native">keeping | |
| native method names</a>, to make sure that the parameter types of native | |
| methods aren't renamed either. Their signatures then remain completely | |
| unchanged and compatible with the native libraries.</dd> | |
| <dt><a name="allowshrinking"><code><b>allowshrinking</b></code></a></dt> | |
| <dd>Specifies that the entry points specified in the <a href="#keep">-keep</a> | |
| option may be shrunk, even if they have to be preserved otherwise. That | |
| is, the entry points may be removed in the shrinking step, but if they are | |
| necessary after all, they may not be optimized or obfuscated.</dd> | |
| <dt><a name="allowoptimization"><code><b>allowoptimization</b></code></a></dt> | |
| <dd>Specifies that the entry points specified in the <a href="#keep">-keep</a> | |
| option may be optimized, even if they have to be preserved otherwise. That | |
| is, the entry points may be altered in the optimization step, but they may | |
| not be removed or obfuscated. This modifier is only useful for achieving | |
| unusual requirements.</dd> | |
| <dt><a name="allowobfuscation"><code><b>allowobfuscation</b></code></a></dt> | |
| <dd>Specifies that the entry points specified in the <a href="#keep">-keep</a> | |
| option may be obfuscated, even if they have to be preserved otherwise. That | |
| is, the entry points may be renamed in the obfuscation step, but they may | |
| not be removed or optimized. This modifier is only useful for achieving | |
| unusual requirements.</dd> | |
| </dl> | |
| <p> | |
| <h2><a name="classspecification">Class Specifications</a></h2> | |
| A class specification is a template of classes and class members (fields and | |
| methods). It is used in the various <code>-keep</code> options and in the | |
| <code>-assumenosideeffects</code> option. The corresponding option is only | |
| applied to classes and class members that match the template. | |
| <p> | |
| The template was designed to look very Java-like, with some extensions for | |
| wildcards. To get a feel for the syntax, you should probably look at the <a | |
| href="examples.html">examples</a>, but this is an attempt at a complete formal | |
| definition: | |
| <p> | |
| <pre> | |
| [<b>@</b><i>annotationtype</i>] [[<b>!</b>]<b>public</b>|<b>final</b>|<b>abstract</b>|<b>@</b> ...] [<b>!</b>]<b>interface</b>|<b>class</b>|<b>enum</b> <i>classname</i> | |
| [<b>extends</b>|<b>implements</b> [<b>@</b><i>annotationtype</i>] <i>classname</i>] | |
| [<b>{</b> | |
| [<b>@</b><i>annotationtype</i>] [[<b>!</b>]<b>public</b>|<b>private</b>|<b>protected</b>|<b>static</b>|<b>volatile</b>|<b>transient</b> ...] <b><fields></b> | | |
| (<i>fieldtype fieldname</i>)<b>;</b> | |
| [<b>@</b><i>annotationtype</i>] [[<b>!</b>]<b>public</b>|<b>private</b>|<b>protected</b>|<b>static</b>|<b>synchronized</b>|<b>native</b>|<b>abstract</b>|<b>strictfp</b> ...] <b><methods></b> | | |
| <b><init>(</b><i>argumenttype,...</i><b>)</b> | | |
| <i>classname</i><b>(</b><i>argumenttype,...</i><b>)</b> | | |
| (<i>returntype methodname</i><b>(</b><i>argumenttype,...</i><b>)</b>)<b>;</b> | |
| [<b>@</b><i>annotationtype</i>] [[<b>!</b>]<b>public</b>|<b>private</b>|<b>protected</b>|<b>static</b> ... ] <b>*;</b> | |
| ... | |
| <b>}</b>] | |
| </pre> | |
| <p> | |
| Square brackets "[]" mean that their contents are optional. Ellipsis dots | |
| "..." mean that any number of the preceding items may be specified. A vertical | |
| bar "|" delimits two alternatives. Non-bold parentheses "()" just group parts | |
| of the specification that belong together. The indentation tries to clarify | |
| the intended meaning, but white-space is irrelevant in actual configuration | |
| files. | |
| <p> | |
| <ul class="spacious"> | |
| <li>The <code><b>class</b></code> keyword refers to any interface or class. | |
| The <code><b>interface</b></code> keyword restricts matches to interface | |
| classes. The <code><b>enum</b></code> keyword restricts matches to | |
| enumeration classes. Preceding the <code><b>interface</b></code> or | |
| <code><b>enum</b></code> keywords by a <code><b>!</b></code> restricts | |
| matches to classes that are not interfaces or enumerations, | |
| respectively.</li> | |
| <li>Every <i>classname</i> must be fully qualified, e.g. | |
| <code>java.lang.String</code>. Inner classes are separated by a dollar sign | |
| "<code>$</code>", e.g. <code>java.lang.Thread$State</code>. Class names | |
| may be specified as regular | |
| expressions containing the following wildcards: | |
| <table cellspacing="10"> | |
| <tr><td valign="top"><code><b>?</b></code></td> | |
| <td>matches any single character in a class name, but not the package | |
| separator. For example, "<code>mypackage.Test?</code>" matches | |
| "<code>mypackage.Test1</code>" and "<code>mypackage.Test2</code>", but not | |
| "<code>mypackage.Test12</code>".</td></tr> | |
| <tr><td valign="top"><code><b>*</b></code></td> | |
| <td>matches any part of a class name not containing the package separator. For | |
| example, "<code>mypackage.*Test*</code>" matches | |
| "<code>mypackage.Test</code>" and | |
| "<code>mypackage.YourTestApplication</code>", but not | |
| "<code>mypackage.mysubpackage.MyTest</code>". Or, more generally, | |
| "<code>mypackage.*</code>" matches all classes in | |
| "<code>mypackage</code>", but not in its subpackages.</td></tr> | |
| <tr><td valign="top"><code><b>**</b></code></td> | |
| <td>matches any part of a class name, possibly containing any number of | |
| package separators. For example, "<code>**.Test</code>" matches all | |
| <code>Test</code> classes in all packages except the root package. Or, | |
| "<code>mypackage.**</code>" matches all classes in | |
| "<code>mypackage</code>" and in its subpackages.</td></tr> | |
| </table> | |
| For additional flexibility, class names can actually be comma-separated | |
| lists of class names, with optional <code><b>!</b></code> negators, just | |
| like file name filters. This notation doesn't look very Java-like, so it | |
| should be used with moderation. | |
| <p> | |
| For convenience and for backward compatibility, the class name | |
| <code><b>*</b></code> refers to any class, irrespective of its package.</li> | |
| <li>The <code><b>extends</b></code> and <code><b>implements</b></code> | |
| specifications are typically used to restrict classes with wildcards. They | |
| are currently equivalent, specifying that only classes extending or | |
| implementing the given class qualify. Note that the given class itself is | |
| not included in this set. If required, it should be specified in a | |
| separate option.</li> | |
| <li>The <code><b>@</b></code> specifications can be used to restrict classes | |
| and class members to the ones that are annotated with the specified | |
| annotation types. An <i>annotationtype</i> is specified just like a | |
| <i>classname</i>.</li> | |
| <li>Fields and methods are specified much like in Java, except that method | |
| argument lists don't contain argument names (just like in other tools | |
| like <code>javadoc</code> and <code>javap</code>). The specifications can | |
| also contain the following catch-all wildcards: | |
| <table cellspacing="10"> | |
| <tr><td valign="top"><code><b><init></b></code></td> | |
| <td>matches any constructor.</td></tr> | |
| <tr><td valign="top"><code><b><fields></b></code></td> | |
| <td>matches any field.</td></tr> | |
| <tr><td valign="top"><code><b><methods></b></code></td> | |
| <td>matches any method.</td></tr> | |
| <tr><td valign="top"><code><b>*</b></code></td> | |
| <td>matches any field or method.</td></tr> | |
| </table> | |
| Note that the above wildcards don't have return types. Only the | |
| <code><b><init></b></code> wildcard has an argument list. | |
| <p> | |
| Fields and methods may also be specified using regular expressions. Names | |
| can contain the following wildcards: | |
| <table cellspacing="10"> | |
| <tr><td valign="top"><code><b>?</b></code></td> | |
| <td>matches any single character in a method name.</td></tr> | |
| <tr><td valign="top"><code><b>*</b></code></td> | |
| <td>matches any part of a method name.</td></tr> | |
| </table> | |
| Types in descriptors can contain the following wildcards: | |
| <table cellspacing="10"> | |
| <tr><td valign="top"><code><b>%</b></code></td> | |
| <td>matches any primitive type ("<code>boolean</code>", "<code>int</code>", | |
| etc, but not "<code>void</code>").</td></tr> | |
| <tr><td valign="top"><code><b>?</b></code></td> | |
| <td>matches any single character in a class name.</td></tr> | |
| <tr><td valign="top"><code><b>*</b></code></td> | |
| <td>matches any part of a class name not containing the package separator.</td></tr> | |
| <tr><td valign="top"><code><b>**</b></code></td> | |
| <td>matches any part of a class name, possibly containing any number of | |
| package separators.</td></tr> | |
| <tr><td valign="top"><code><b>***</b></code></td> | |
| <td>matches any type (primitive or non-primitive, array or | |
| non-array).</td></tr> | |
| <tr><td valign="top"><code><b>...</b></code></td> | |
| <td>matches any number of arguments of any type.</td></tr> | |
| </table> | |
| Note that the <code>?</code>, <code>*</code>, and <code>**</code> | |
| wildcards will never match primitive types. Furthermore, only the | |
| <code>***</code> wildcards will match array types of any dimension. For | |
| example, "<code>** get*()</code>" matches "<code>java.lang.Object | |
| getObject()</code>", but not "<code>float getFloat()</code>", nor | |
| "<code>java.lang.Object[] getObjects()</code>".</li> | |
| <li>Constructors can also be specified using their short class names (without | |
| package) or using their full class names. As in the Java language, the | |
| constructor specification has an argument list, but no return type.</li> | |
| <li>The class access modifiers and class member access modifiers are typically | |
| used to restrict wildcarded classes and class members. They specify that | |
| the corresponding access flags have to be set for the member to match. A | |
| preceding <code><b>!</b></code> specifies that the corresponding access | |
| flag should be unset. | |
| <p> | |
| Combining multiple flags is allowed (e.g. <code>public static</code>). It | |
| means that both access flags have to be set (e.g. <code>public</code> | |
| <i>and</i> <code>static</code>), except when they are conflicting, in | |
| which case at least one of them has to be set (e.g. at least | |
| <code>public</code> | |
| <i>or</i> <code>protected</code>). | |
| <p> | |
| ProGuard supports the additional modifiers <code><b>synthetic</b></code>, | |
| <code><b>bridge</b></code>, and <code><b>varargs</b></code>, which may be | |
| set by compilers.</li> | |
| </ul> | |
| <hr /> | |
| <address> | |
| Copyright © 2002-2017 | |
| <a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.guardsquare.com/">GuardSquare</a>. | |
| </address> | |
| </body> | |
| </html> |