diff options
Diffstat (limited to 'docs/manual/usage.html')
| -rw-r--r-- | docs/manual/usage.html | 1271 |
1 files changed, 0 insertions, 1271 deletions
diff --git a/docs/manual/usage.html b/docs/manual/usage.html deleted file mode 100644 index 3bf94ef..0000000 --- a/docs/manual/usage.html +++ /dev/null @@ -1,1271 +0,0 @@ -<!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.saikoa.com/dexguard">DexGuard</a> <a class="largebutton" target="_top" href="http://www.saikoa.com/">Saikoa</a> <a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>') -//--> -</script> -<noscript> -<a class="largebutton" target="_top" href="../index.html#manual/usage.html">ProGuard index</a> -<a class="largebutton" target="_top" href="http://www.saikoa.com/dexguard">DexGuard</a> -<a class="largebutton" target="_top" href="http://www.saikoa.com/">Saikoa</a> -<a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a> -</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-2014 -<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.saikoa.com/">Saikoa</a>. -</address> -</body> -</html> |