File: usage.html

package info (click to toggle)
proguard 3.4-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 4,036 kB
ctags: 6,190
sloc: java: 33,225; xml: 279; makefile: 17; sh: 2
file content (886 lines) | stat: -rw-r--r-- 41,730 bytes
<!doctype html PUBLIC "-//W3C//DTD HTML 3.2 Final//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>

<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. Options can also be put in one or more configuration
files. 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 simply combine command line options and options from configuration
files, e.g.:
<p class="code">
<code><b>java -jar proguard.jar @myconfig.pro -verbose</b></code>
</p>
<p>
In a configuration file, a <code><b>#</b></code> sign and all remaining
characters on that line are ignored, allowing you to add comments.
<p>
Extra whitespace between words and delimiters is ignored. To specify file
names with spaces or special characters, words can be quoted with single or
double quotes. Note that the quotes may need to be escaped when used on the
command line, to avoid them being gobbled by the shell.
<p>
Options can be grouped arbitrarily in arguments on the command line and in
lines in configuration files. This means that you can quote any arbitrary
section of command line options, to avoid shell expansion of special
characters, for instance.
<p>
The order of the options is generally irrelevant. They can be abbreviated to
their first unique characters.
<p>

The sections below provide more details:
<ul>
<li><a href="#iooptions">Input/Output Options</a>
<li><a href="#keepoptions">Keep Options</a>
<li><a href="#shrinkingoptions">Shrinking Options</a>
<li><a href="#optimizationoptions">Optimization Options</a>
<li><a href="#obfuscationoptions">Obfuscation Options</a>
<li><a href="#classpath">Class Paths</a>
<li><a href="#filename">File Names</a>
<li><a href="#filters">Filters</a>
<li><a href="#keepoverview">Overview of <code>Keep</code> Options</a>
<li><a href="#classspecification">Class Specifications</a>
</ul>

<a name="iooptions">&nbsp;</a>
<h2>Input/Output Options</h2>

<dl>
<dt><code><b>@</b></code><a href="#filename"><i>filename</i></a></dt>

<dd>Short for '<code>-include</code> <i>filename</i>'.</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 wars, ears, zips, or directories) of the
    application to be processed. The class files in these jars will be
    processed and written to the output jars. 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="#filters">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 wars, ears, zips, 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="#filters">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 wars, ears, zips, 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="#filters">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">J2ME midlets</a>, just by specifying the
    appropriate run-time jar.</dd>

<dt><a name="dontskipnonpubliclibraryclasses"><code><b>-dontskipnonpubliclibraryclasses</b></code></a></dt>

<dd>Specifies not to ignore non-public library classes. By default, non-public
    library classes are skipped while parsing library jars. The classes are
    typically not relevant during processing, since they don't affect the
    actual program code in the input jars. Ignoring them reduces memory usage
    and processing time. Occasionally, a badly designed library may contain a
    non-public library class that is extended/implemented by a public library
    class. If the latter library class in turn is extended/implemented by a
    program class, ProGuard will complain that it can't find the non-public
    library class, which it had ignored during parsing. This option will
    overcome that problem, at the cost of greater memory usage and longer
    processing time.</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, these class members are skipped 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>

</dl>
<p>

<a name="keepoptions">&nbsp;</a>
<h2>Keep Options</h2>

<dl>
<dt><a name="keep"><code><b>-keep</b></code></a>
    <a href="#classspecification"><i>class_specification</i></a></dt>

<dd>Specifies classes and class members (fields and methods) to be preserved.
    They will be preserved with their original names. This is typically the
    required seed for recursively determining which other classes and class
    members need to be preserved. 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 items.</dd>

<dt><a name="keepclassmembers"><code><b>-keepclassmembers</b></code></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="#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>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>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>, 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>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>

<a name="shrinkingoptions">&nbsp;</a>
<h2>Shrinking Options</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.</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 reasonings -- these do not
    reflect the actual shrinking process.</i> If the <a
    href="#verbose"><code><b>-verbose</b></code></a> option if specified, the
    traces include full field and method signatures. Only applicable when
    shrinking.</dd>

</dl>
<p>

<a name="optimizationoptions">&nbsp;</a>
<h2>Optimization Options</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="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. Note that ProGuard will analyze your program code to find such
    methods automatically. It will not analyze library code, for which this
    option can thus be useful. For example, you could specify the method
    <code>System.currentTimeMillis()</code>, so that any idle calls to it will
    be removed. Only applicable when optimizing. In general, making
    assumptions can be dangerous; you can break your application. <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
    modified 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 (cfr. <a href=
    "http://java.sun.com/docs/books/jls/second_edition/html/j.title.doc.html"
    >The Java Language Specification, Second Edition</a>, <a href=
    "http://java.sun.com/docs/books/jls/second_edition/html/binaryComp.doc.html#47259"
    >Section 13.4.6</a>) formally do not require this, some virtual machines
    would have problems with the processed code otherwise. Only applicable
    when optimizing.</dd>

</dl>
<p>

<a name="obfuscationoptions">&nbsp;</a>
<h2>Obfuscation Options</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. It is required for subsequent
    incremental obfuscation, 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. 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
    method names. White space, punctuation characters, duplicate words, and
    comments after a <code><b>#</b></code> sign are ignored. By default, short
    names like 'a', 'b', etc. are used as obfuscated method names. With an
    obfuscation dictionary, you can specify a list of reserved key words, or
    identifiers with foreign characters, for instance. Note that this 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' and
    'Exceptions'), thus reducing the class file sizes just a little bit more.
    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 (not just their arguments). This option can
    make the output jar even smaller (and less comprehensible). Only
    applicable when obfuscating.
    <p>
    Counter-indications: the resulting class files fall within the Java
    bytecode specification (cfr. <a href=
    "http://java.sun.com/docs/books/vmspec/2nd-edition/html/VMSpecTOC.doc.html"
    >The Java Virtual Machine Specification, Second Edition</a>, first
    paragraphs of <a href=
    "http://java.sun.com/docs/books/vmspec/2nd-edition/html/ClassFile.doc.html#2877"
    >Section 4.5</a> and <a href=
    "http://java.sun.com/docs/books/vmspec/2nd-edition/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://java.sun.com/docs/books/jls/second_edition/html/j.title.doc.html"
    >The Java Language Specification, Second Edition</a>, <a href=
    "http://java.sun.com/docs/books/jls/second_edition/html/classes.doc.html#40898"
    >Section 8.3</a> and <a href=
    "http://java.sun.com/docs/books/jls/second_edition/html/classes.doc.html#227768"
    >Section 8.4.7</a>). Still, some tools have problems with it. Notably,
    Sun's JREs 1.4 and later fail to serialize objects with overloaded
    primitive fields. Also, Sun's JDK 1.2.2 javac compiler produces an
    exception when compiling with such a library (cfr. <a href=
    "http://developer.java.sun.com/developer/bugParade/bugs/4216736.html">Bug
    #4216736</a>). You therefore probably shouldn't use this option for
    processing libraries.</dd>

<dt><a name="defaultpackage"><code><b>-defaultpackage</b></code></a>
    [<i>package_name</i>]</dt>

<dd>Specifies to repackage all class files that are renamed into the single
    given package. Without argument or with an empty string (''), the package
    is removed completely. This option can make the output jar even smaller
    (and less comprehensible). Only applicable when obfuscating.
    <p>
    This option implies the <a
    href="#allowaccessmodification"><code><b>-allowaccessmodification</b></code></a>
    option. In this case, ProGuard avoids access permissions becoming
    inconsistent, by making all package visible classes and class members
    public. These changes don't affect the functioning of applications. It
    might be confusing and therefore less desirable when processing libraries.
    <p>
    Counter-indications: 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="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. Note that the obfuscated jars
    will become larger as a result. Only applicable when obfuscating.</dd>

<dt><a name="keepattributes"><code><b>-keepattributes</b></code></a>
    [<i>attribute_name<b>,</b>...</i>]</dt>

<dd>Specifies any optional attributes to be preserved. The attributes can be
    specified with one or more <code>-keepattributes</code> directives.
    Multiple attributes should be separated by commas. An empty list preserves
    all attributes. Attribute names can contain <b>?</b> and
    <b>*</b> wildcards, and they can be preceded by the <b>!</b> negator (much
    like file name filters). Typical optional attributes are
    <code>LineNumberTable</code>, <code>LocalVariableTable</code>,
    <code>LocalVariableTypeTable</code>, <code>SourceFile</code>,
    <code>SourceDir</code>, <code>Deprecated</code>, <code>Synthetic</code>,
    <code>Signature</code>, <code>EnclosingMethod</code>,
    <code>RuntimeVisibleAnnotations</code>,
    <code>RuntimeInvisibleAnnotations</code>,
    <code>RuntimeVisibleParameterAnnotations</code>,
    <code>RuntimeInvisibleParameterAnnotations</code>, and
    <code>AnnotationDefault</code>. The <code>InnerClasses</code> attribute
    name can be specified as well, referring to the source name part of this
    attribute. For example, you could keep the <code>Deprecated</code>
    attribute when <a href="examples.html#library">processing a library</a>.
    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>

</dl>
<p>

<a name="generaloptions">&nbsp;</a>
<h2>General Options</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></dt>

<dd>Specifies not to print notes about class casts of variable dynamically
    created objects. These notes provide hints about classes that may have to
    be kept.</dd>

<dt><a name="dontwarn"><code><b>-dontwarn</b></code></a></dt>

<dd>Specifies not to warn about unresolved references at all. Again, if the
    unresolved classes or class members are indeed required for processing,
    the output jar 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 to
    superclasses, interfaces, or class members, but to continue processing in
    any case. If the classes or class members are indeed required for
    processing, the output jar will not function properly. <i>Only use this
    option if you know what you're doing!</i></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 shrinking or obfuscating it first.</dd>

</dl>
<p>

<a name="classpath">&nbsp;</a>
<h2>Class Paths</h2>

ProGuard accepts a generalization of class paths to specify input files and
output files. A class path consists of entries, separated by the 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>A jar file, containing any of the above,
<li>A war file, containing any of the above,
<li>An ear file, containing any of the above,
<li>A zip file, containing any of the above,
<li>A directory (structure), containing any of the above.
</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, 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>A jar file, in which all processed class files and resource files will be
    collected.
<li>A war file, in which any and all of the above will be collected,
<li>An ear file, in which any and all of the above will be collected,
<li>A zip file, in which any and all of the above will be collected,
<li>A directory, in which any and all of the above will be collected.
</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.
<p>
Files and directories can be specified as discussed in the section on <a
href="#filename">file names</a> below.
<p>
In addition, the individual class patch entries and their contents can be
filtered, as explained in the <a href="#filters">filters</a> section below.
This allows for an almost infinite number of packaging and repackaging
possibilities.
<p>

<a name="filename">&nbsp;</a>
<h2>File Names</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>relative to the configuration file in which it is specified, if any, or
    otherwise
<li>relative to the working directory.
</ul>
<p>
The names can contain Java system properties delimited by '<b>&lt;</b>' and
'<b>&gt;</b>'. The system properties
are automatically replaced by their respective values.
<p>
For example, <code>&lt;java.home&gt;/lib/rt.jar</code> will automatically be
expanded to something like <code>/usr/local/java/jdk/jre/lib/rt.jar</code>.
Similarly, <code>&lt;user.home&gt;</code> will be expanded to the user's home
directory, and <code>&lt;user.dir&gt;</code> will be expanded to the current
working directory.
<p>
Names with special characters like spaces and parentheses must be quoted with
single or double quotes. Note that each file name in a list of names has to be
quoted individually. Also 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>

<a name="filters">&nbsp;</a>
<h2>Filters</h2>

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 5 types of filters between parentheses, separated by
semi-colons:
<ul>
<li>A filter for all zip names that are encountered,
<li>A filter for all ear names that are encountered,
<li>A filter for all war names that are encountered,
<li>A filter for all jar names that are encountered,
<li>A filter for all class file names and resource file names that are
    encountered.
</ul>
<p>
If fewer than 5 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>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>
A filter consists of one or more comma-separated 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>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>

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. You can think of the filtering mechanism as a
conveyor belt, with pushers that accept or reject files as they pass by.
<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>

Note that 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.

<a name="keepoverview">&nbsp;</a>
<h2>Overview of <code>Keep</code> Options</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"><code>-keep</code></td>
<td bgcolor="#E0E0E0"><code>-keepnames</code></td>
</tr>

<tr>
<td>Class members only</td>
<td bgcolor="#E0E0E0"><code>-keepclassmembers</code></td>
<td bgcolor="#E0E0E0"><code>-keepclassmembernames</code></td>
</tr>

<tr>
<td>Classes and class members, if class members present</td>
<td bgcolor="#E0E0E0"><code>-keepclasseswithmembers</code></td>
<td bgcolor="#E0E0E0"><code>-keepclasseswithmembernames</code></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>

<a name="classspecification">&nbsp;</a>
<h2>Class Specifications</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>]<b>public</b>|<b>final</b>|<b>abstract</b> ...] ([<b>!</b>]<b>interface</b>)|<b>class</b> <i>classname</i>
    [<b>extends</b>|<b>implements</b> <i>classname</i>]
[<b>{</b>
    [[<b>!</b>]<b>public</b>|<b>private</b>|<b>protected</b>|<b>static</b>|<b>volatile</b>|<b>transient</b> ...] <b>&lt;fields&gt;</b> |
                                                                      (<i>fieldtype fieldname</i>)<b>;</b>
    [[<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>&lt;methods&gt;</b> |
                                                                                           <b>&lt;init&gt;(</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>]<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>

<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. Preceding the <code><b>interface</b></code> keyword by a
    <code><b>!</b></code> restricts matches to classes that are not
    interfaces.
    <p>

<li>Every <i>classname</i> must be fully qualified, e.g.
    <code>java.lang.String</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.
    <p>

<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.
    <p>

<li>Fields and methods are specified much like in Java, except that method
    argument lists don't contain argument names (as is common 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>&lt;init&gt;</b></code></td>
<td>matches any constructor.</td></tr>

<tr><td valign="top"><code><b>&lt;fields&gt;</b></code></td>
<td>matches any field.</td></tr>

<tr><td valign="top"><code><b>&lt;methods&gt;</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>&lt;init&gt;</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 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 primitive type ("<code>boolean</code>", "<code>int</code>",
        etc, but not "<code>void</code>").</td></tr>
</table>

    Note that the <code>?</code>, <code>*</code>, and <code>**</code>
    wildcards will never match primitive types. None of the wildcards will
    match array types of different dimensions than specified by the regular
    expression. 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>".
    <p>

<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.
    <p>

<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>).

</ul>
<p>

<hr>
<address>
Copyright &copy; 2002-2005
<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>.
</address>
</body>
</html>