diff options
Diffstat (limited to 'third_party/java/proguard/proguard5.3.3/docs/manual')
21 files changed, 7531 insertions, 0 deletions
diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/android_small.png b/third_party/java/proguard/proguard5.3.3/docs/manual/android_small.png Binary files differnew file mode 100644 index 0000000000..0313515a09 --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/android_small.png diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/ant.html b/third_party/java/proguard/proguard5.3.3/docs/manual/ant.html new file mode 100644 index 0000000000..9116640bcb --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/ant.html @@ -0,0 +1,661 @@ +<!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>Ant Task</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/ant.html">ProGuard index</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> <a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>') +//--> +</script> +<noscript> +<a class="largebutton" target="_top" href="../index.html#manual/ant.html">ProGuard index</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> +<a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a> +</noscript> + +<h2>Ant Task</h2> + +<b>ProGuard</b> can be run as a task in the Java-based build tool Ant (version +1.8 or higher). +<p> + +Before you can use the <code>proguard</code> task, you have to tell Ant about +this new task. The easiest way is to add the following line to your +<code>build.xml</code> file: +<p> + +<pre> +<taskdef resource="proguard/ant/task.properties" + classpath="/usr/local/java/proguard/lib/proguard.jar" /> +</pre> +<p> + +Please make sure the class path is set correctly for your system. +<p> + +There are three ways to configure the ProGuard task: +<ol> +<li>using an external configuration file,</li> +<li>using embedded ProGuard configuration options, or</li> +<li>using the equivalent XML configuration tags.</li> +</ol> +These three ways can be combined, depending on practical circumstances and +personal preference. +<p> + +<h3>1. An external ProGuard configuration file</h3> + +The simplest way to use the ProGuard task in an Ant build file is to keep your +ProGuard configuration file, and include it from Ant. You can include your +ProGuard configuration file by setting +the <a href="#configuration_attribute"><code>configuration</code></a> +attribute of your +<code>proguard</code> task. Your ant build file will then look like this: +<p> + +<pre> +<taskdef resource="proguard/ant/task.properties" + classpath="/usr/local/java/proguard/lib/proguard.jar" /> +<proguard configuration="myconfigfile.pro"/> +</pre> +<p> + +This is a convenient option if you prefer ProGuard's configuration style over +XML, if you want to keep your build file small, or if you have to share your +configuration with developers who don't use Ant. +<p> + +<h3>2. Embedded ProGuard configuration options</h3> + +Instead of keeping an external ProGuard configuration file, you can also copy +the contents of the file into the nested text of the <code>proguard</code> task +(the PCDATA area). Your Ant build file will then look like this: +<p> + +<pre> +<taskdef resource="proguard/ant/task.properties" + classpath="/usr/local/java/proguard/lib/proguard.jar" /> +<proguard> + -libraryjars ${java.home}/lib/rt.jar + -injars in.jar + -outjars out.jar + + -keepclasseswithmembers public class * { + public static void main(java.lang.String[]); + } +</proguard> +</pre> +<p> + +Some minor syntactical changes are required in order to conform with the XML +standard. +<p> + +Firstly, the <code>#</code> character cannot be used for comments in an XML +file. Comments must be enclosed by an opening <code><!--</code> and a +closing <code>--></code>. All occurrences of the <code>#</code> character +can be removed. +<p> + +Secondly, the use of <code><</code> and <code>></code> characters would +upset the structure of the XML build file. Environment variables can be +specified with the usual Ant style <code>${...}</code>, instead of the ProGuard +style <code><...></code>. Other occurrences of <code><</code> and +<code>></code> have to be encoded as <code>&lt;</code> and +<code>&gt;</code> respectively. +<p> + +<h3>3. XML configuration tags</h3> + +If you really prefer a full-blown XML configuration, you can replace the +ProGuard configuration options by XML configuration tags. The resulting +configuration will be equivalent, but much more verbose and difficult to read, +as XML goes. The remainder of this page presents the supported tags. For a +more extensive discussion of their meaning, please consult the traditional <a +href="usage.html">Usage</a> section. You can find some sample configuration +files in the <code>examples/ant</code> directory of the ProGuard distribution. +<p> + +<h2><a name="proguard">Task Attributes and Nested Elements</a></h2> + +The <code><b><proguard></b></code> task and the +<code><b><proguardconfiguration></b></code> task can have the following +attributes (only for <code><proguard></code>) and nested +elements: + +<dl> + +<dt><a name="configuration_attribute"><code><b>configuration</b></code></a> + = "<i>filename</i>"</dt> +<dd>Read and merge options from the given ProGuard-style configuration + file. Note: for reading multiple configuration files or XML-style + configurations, use the <a + href="#configuration_element"><code>configuration</code></a> + <i>element</i>.</dd> + +<dt><a href="usage.html#skipnonpubliclibraryclasses"><code><b>skipnonpubliclibraryclasses</b></code></a> + = "<i>boolean</i>" + (default = false)</dt> +<dd>Ignore non-public library classes.</dd> + +<dt><a href="usage.html#dontskipnonpubliclibraryclassmembers"><code><b>skipnonpubliclibraryclassmembers</b></code></a> + = "<i>boolean</i>" + (default = true)</dt> +<dd>Ignore package visible library class members.</dd> + +<dt><a href="usage.html#target"><code><b>target</b></code></a> + = "<i>version</i>" + (default = none)</dt> +<dd>Set the given version number in the processed classes.</dd> + +<dt><a href="usage.html#forceprocessing"><code><b>forceprocessing</b></code></a> + = "<i>boolean</i>" + (default = false)</dt> +<dd>Process the input, even if the output seems up to date.</dd> + +<dt><a href="usage.html#printseeds"><code><b>printseeds</b></code></a> + = "<i>boolean or filename</i>" + (default = false)</dt> +<dd>List classes and class members matched by the various <code>keep</code> + commands, to the standard output or to the given file.</dd> + +<dt><a href="usage.html#dontshrink"><code><b>shrink</b></code></a> + = "<i>boolean</i>" + (default = true)</dt> +<dd>Shrink the input class files.</dd> + +<dt><a href="usage.html#printusage"><code><b>printusage</b></code></a> + = "<i>boolean or filename</i>" + (default = false)</dt> +<dd>List dead code of the input class files, to the standard output or to the + given file.</dd> + +<dt><a href="usage.html#dontoptimize"><code><b>optimize</b></code></a> + = "<i>boolean</i>" + (default = true)</dt> +<dd>Optimize the input class files.</dd> + +<dt><a href="usage.html#optimizationpasses"><code><b>optimizationpasses</b></code></a> + = "<i>n</i>" + (default = 1)</dt> +<dd>The number of optimization passes to be performed.</dd> + +<dt><a href="usage.html#allowaccessmodification"><code><b>allowaccessmodification</b></code></a> + = "<i>boolean</i>" + (default = false)</dt> +<dd>Allow the access modifiers of classes and class members to be modified, + while optimizing.</dd> + +<dt><a href="usage.html#mergeinterfacesaggressively"><code><b>mergeinterfacesaggressively</b></code></a> + = "<i>boolean</i>" + (default = false)</dt> +<dd>Allow any interfaces to be merged, while optimizing.</dd> + +<dt><a href="usage.html#dontobfuscate"><code><b>obfuscate</b></code></a> + = "<i>boolean</i>" + (default = true)</dt> +<dd>Obfuscate the input class files.</dd> + +<dt><a href="usage.html#printmapping"><code><b>printmapping</b></code></a> + = "<i>boolean or filename</i>" + (default = false)</dt> +<dd>Print the mapping from old names to new names for classes and class members + that have been renamed, to the standard output or to the given file.</dd> + +<dt><a href="usage.html#applymapping"><code><b>applymapping</b></code></a> + = "<i>filename</i>" + (default = none)</dt> +<dd>Reuse the given mapping, for incremental obfuscation.</dd> + +<dt><a href="usage.html#obfuscationdictionary"><code><b>obfuscationdictionary</b></code></a> + = "<i>filename</i>" + (default = none)</dt> +<dd>Use the words in the given text file as obfuscated field names and method + names.</dd> + +<dt><a href="usage.html#classobfuscationdictionary"><code><b>classobfuscationdictionary</b></code></a> + = "<i>filename</i>" + (default = none)</dt> +<dd>Use the words in the given text file as obfuscated class names.</dd> + +<dt><a href="usage.html#packageobfuscationdictionary"><code><b>packageobfuscationdictionary</b></code></a> + = "<i>filename</i>" + (default = none)</dt> +<dd>Use the words in the given text file as obfuscated package names.</dd> + +<dt><a href="usage.html#overloadaggressively"><code><b>overloadaggressively</b></code></a> + = "<i>boolean</i>" + (default = false)</dt> +<dd>Apply aggressive overloading while obfuscating.</dd> + +<dt><a href="usage.html#useuniqueclassmembernames"><code><b>useuniqueclassmembernames</b></code></a> + = "<i>boolean</i>" + (default = false)</dt> +<dd>Ensure uniform obfuscated class member names for subsequent incremental + obfuscation.</dd> + +<dt><a href="usage.html#dontusemixedcaseclassnames"><code><b>usemixedcaseclassnames</b></code></a> + = "<i>boolean</i>" + (default = true)</dt> +<dd>Generate mixed-case class names while obfuscating.</dd> + +<dt><a href="usage.html#flattenpackagehierarchy"><code><b>flattenpackagehierarchy</b></code></a> + = "<i>package_name</i>" + (default = none)</dt> +<dd>Repackage all packages that are renamed into the single given parent + package.</dd> + +<dt><a href="usage.html#repackageclasses"><code><b>repackageclasses</b></code></a> + = "<i>package_name</i>" + (default = none)</dt> +<dd>Repackage all class files that are renamed into the single given + package.</dd> + +<dt><a href="usage.html#keepparameternames"><code><b>keepparameternames</b></code></a> + = "<i>boolean</i>" + (default = false)</dt> +<dd>Keep the parameter names and types of methods that are kept.</dd> + +<dt><a href="usage.html#renamesourcefileattribute"><code><b>renamesourcefileattribute</b></code></a> + = "<i>string</i>" + (default = none)</dt> +<dd>Put the given constant string in the <code>SourceFile</code> + attributes.</dd> + +<dt><a href="usage.html#dontpreverify"><code><b>preverify</b></code></a> + = "<i>boolean</i>" + (default = true)</dt> +<dd>Preverify the processed class files if they are targeted at Java Micro + Edition or at Java 6 or higher.</dd> + +<dt><a href="usage.html#microedition"><code><b>microedition</b></code></a> + = "<i>boolean</i>" + (default = false)</dt> +<dd>Target the processed class files at Java Micro Edition.</dd> + +<dt><a href="usage.html#verbose"><code><b>verbose</b></code></a> + = "<i>boolean</i>" + (default = false)</dt> +<dd>Write out some more information during processing.</dd> + +<dt><a href="usage.html#dontnote"><code><b>note</b></code></a> + = "<i>boolean</i>" + (default = true)</dt> +<dd>Print notes about potential mistakes or omissions in the configuration. + Use the nested element <a href="#dontnote">dontnote</a> for more + fine-grained control.</dd> + +<dt><a href="usage.html#dontwarn"><code><b>warn</b></code></a> + = "<i>boolean</i>" + (default = true)</dt> +<dd>Print warnings about unresolved references. Use the nested + element <a href="#dontwarn">dontwarn</a> for more fine-grained + control. <i>Only use this option if you know what you're doing!</i></dd> + +<dt><a href="usage.html#ignorewarnings"><code><b>ignorewarnings</b></code></a> + = "<i>boolean</i>" + (default = false)</dt> +<dd>Print warnings about unresolved references, but continue processing + anyhow. <i>Only use this option if you know what you're doing!</i></dd> + +<dt><a href="usage.html#printconfiguration"><code><b>printconfiguration</b></code></a> + = "<i>boolean or filename</i>" + (default = false)</dt> +<dd>Write out the entire configuration in traditional ProGuard style, to the + standard output or to the given file. Useful to replace unreadable + XML configurations.</dd> + +<dt><a href="usage.html#dump"><code><b>dump</b></code></a> + = "<i>boolean or filename</i>" + (default = false)</dt> +<dd>Write out the internal structure of the processed class files, to the + standard output or to the given file.</dd> + +<dt><a href="usage.html#injars"><code><b><injar</b></code></a> + <a href="#classpath"><i>class_path</i></a> + <code><b>/></b></code></dt> +<dd>Specifies the program jars (or aars, wars, ears, zips, apks, or + directories).</dd> + +<dt><a href="usage.html#outjars"><code><b><outjar</b></code></a> + <a href="#classpath"><i>class_path</i></a> + <code><b>/></b></code></dt> +<dd>Specifies the names of the output jars (or aars, wars, ears, zips, apks, or + directories).</dd> + +<dt><a href="usage.html#libraryjars"><code><b><libraryjar</b></code></a> + <a href="#classpath"><i>class_path</i></a> + <code><b>/></b></code></dt> +<dd>Specifies the library jars (or aars, wars, ears, zips, apks, or + directories).</dd> + +<dt><a href="usage.html#keepdirectories"><code><b><keepdirectory name = </b></code></a>"<i>directory_name</i>" + <code><b>/></b></code><br/> + <a href="usage.html#keepdirectories"><code><b><keepdirectories filter = </b></code></a>"<a href="usage.html#filefilters"><i>directory_filter</i></a>" + <code><b>/></b></code></dt> +<dd>Keep the specified directories in the output jars (or aars, wars, ears, + zips, apks, or directories).</dd> + +<dt><a href="usage.html#keep"><code><b><keep</b></code></a> + <a href="#keepmodifier"><i>modifiers</i></a> + <a href="#classspecification"><i>class_specification</i></a> + <code><b>></b></code> + <a href="#classmemberspecification"><i>class_member_specifications</i></a> + <code><b></keep></b></code></dt> +<dd>Preserve the specified classes <i>and</i> class members.</dd> + +<dt><a href="usage.html#keepclassmembers"><code><b><keepclassmembers</b></code></a> + <a href="#keepmodifier"><i>modifiers</i></a> + <a href="#classspecification"><i>class_specification</i></a> + <code><b>></b></code> + <a href="#classmemberspecification"><i>class_member_specifications</i></a> + <code><b></keepclassmembers></b></code></dt> +<dd>Preserve the specified class members, if their classes are preserved as + well.</dd> + +<dt><a href="usage.html#keepclasseswithmembers"><code><b><keepclasseswithmembers</b></code></a> + <a href="#keepmodifier"><i>modifiers</i></a> + <a href="#classspecification"><i>class_specification</i></a> + <code><b>></b></code> + <a href="#classmemberspecification"><i>class_member_specifications</i></a> + <code><b></keepclasseswithmembers></b></code></dt> +<dd>Preserve the specified classes <i>and</i> class members, if all of the + specified class members are present.</dd> + +<dt><a href="usage.html#keepnames"><code><b><keepnames</b></code></a> + <a href="#classspecification"><i>class_specification</i></a> + <code><b>></b></code> + <a href="#classmemberspecification"><i>class_member_specifications</i></a> + <code><b></keepnames></b></code></dt> +<dd>Preserve the names of the specified classes <i>and</i> class members (if + they aren't removed in the shrinking step).</dd> + +<dt><a href="usage.html#keepclassmembernames"><code><b><keepclassmembernames</b></code></a> + <a href="#classspecification"><i>class_specification</i></a> + <code><b>></b></code> + <a href="#classmemberspecification"><i>class_member_specifications</i></a> + <code><b></keepclassmembernames></b></code></dt> +<dd>Preserve the names of the specified class members (if they aren't removed + in the shrinking step).</dd> + +<dt><a href="usage.html#keepclasseswithmembernames"><code><b><keepclasseswithmembernames</b></code></a> + <a href="#classspecification"><i>class_specification</i></a> + <code><b>></b></code> + <a href="#classmemberspecification"><i>class_member_specifications</i></a> + <code><b></keepclasseswithmembernames></b></code></dt> +<dd>Preserve the names of the specified classes <i>and</i> class members, if + all of the specified class members are present (after the shrinking + step).</dd> + +<dt><a href="usage.html#whyareyoukeeping"><code><b><whyareyoukeeping</b></code></a> + <a href="#classspecification"><i>class_specification</i></a> + <code><b>></b></code> + <a href="#classmemberspecification"><i>class_member_specifications</i></a> + <code><b></whyareyoukeeping></b></code></dt> +<dd>Print details on why the given classes and class members are being kept in + the shrinking step.</dd> + +<dt><a href="usage.html#assumenosideeffects"><code><b><assumenosideeffects</b></code></a> + <a href="#classspecification"><i>class_specification</i></a> + <code><b>></b></code> + <a href="#classmemberspecification"><i>class_member_specifications</i></a> + <code><b></assumenosideeffects></b></code></dt> +<dd>Assume that the specified methods don't have any side effects, while + optimizing. <i>Only use this option if you know what you're + doing!</i></dd> + +<dt><a href="usage.html#optimizations"><code><b><optimization name = </b></code></a>"<a href="optimizations.html"><i>optimization_name</i></a>" + <code><b>/></b></code><br/> + <a href="usage.html#optimizations"><code><b><optimizations filter = </b></code></a>""<a href="optimizations.html"><i>optimization_filter</i></a>" + <code><b>/></b></code></dt> +<dd>Perform only the specified optimizations.</dd> + +<dt><a href="usage.html#keeppackagenames"><code><b><keeppackagename name = </b></code></a>"<i>package_name</i>" + <code><b>/></b></code><br/> + <a href="usage.html#keeppackagenames"><code><b><keeppackagenames filter = </b></code></a>"<a href="usage.html#filters"><i>package_filter</i></a>" + <code><b>/></b></code></dt> +<dd>Keep the specified package names from being obfuscated. If no name is + given, all package names are preserved.</dd> + +<dt><a href="usage.html#keepattributes"><code><b><keepattribute name = </b></code></a>"<i>attribute_name</i>" + <code><b>/></b></code><br/> + <a href="usage.html#keepattributes"><code><b><keepattributes filter = </b></code></a>"<a href="usage.html#filters"><i>attribute_filter</i></a>" + <code><b>/></b></code></dt> +<dd>Preserve the specified optional Java bytecode attributes, with optional + wildcards. If no name is given, all attributes are preserved.</dd> + +<dt><a href="usage.html#adaptclassstrings"><code><b><adaptclassstrings filter = </b></code></a>"<a href="usage.html#filters"><i>class_filter</i></a>" + <code><b>/></b></code></dt> +<dd>Adapt string constants in the specified classes, based on the obfuscated + names of any corresponding classes.</dd> + +<dt><a href="usage.html#adaptresourcefilenames"><code><b><adaptresourcefilenames filter = </b></code></a>"<a href="usage.html#filefilters"><i>file_filter</i></a>" + <code><b>/></b></code></dt> +<dd>Rename the specified resource files, based on the obfuscated names of the + corresponding class files.</dd> + +<dt><a href="usage.html#adaptresourcefilecontents"><code><b><adaptresourcefilecontents filter = </b></code></a>"<a href="usage.html#filefilters"><i>file_filter</i></a>" + <code><b>/></b></code></dt> +<dd>Update the contents of the specified resource files, based on the + obfuscated names of the processed classes.</dd> + +<dt><a name="dontnote" /> + <a href="usage.html#dontnote"><code><b><dontnote filter = </b></code></a>"<a href="usage.html#filters"><i>class_filter</i></a>" + <code><b>/></b></code></dt> +<dd>Don't print notes about classes matching the specified class name + filter.</dd> + +<dt><a name="dontwarn" /> + <a href="usage.html#dontwarn"><code><b><dontwarn filter = </b></code></a>"<a href="usage.html#filters"><i>class_filter</i></a>" + <code><b>/></b></code></dt> +<dd>Don't print warnings about classes matching the specified class name + filter. <i>Only use this option if you know what you're doing!</i></dd> + +<dt><a name="configuration_element"><code><b><configuration refid = </b></code></a>"<i>ref_id</i>" + <code><b>/></b></code><br/> + <code><b><configuration file = </b></code>"<i>name</i>" + <code><b>/></b></code></dt> +<dd>The first form includes the XML-style configuration specified in a + <code><proguardconfiguration></code> task (or + <code><proguard></code> task) with attribute <code>id</code> = + "<i>ref_id</i>". Only the nested elements of this configuration are + considered, not the attributes. + <p> + The second form includes the ProGuard-style configuration from the specified + file. The element is actually a <code>fileset</code> element and supports + all of its attributes and nested elements, including multiple files. + </dd> + +</dl> + +<h2><a name="classpath">Class Path Attributes and Nested Elements</a></h2> + +The jar elements are <code>path</code> elements, so they can have any of the +standard <code>path</code> attributes and nested elements. The most common +attributes are: + +<dl> + +<dt><code><b>path</b></code> = "<i>path</i>"</dt> +<dd>The names of the jars (or aars, wars, ears, zips, apks, or directories), + separated by the path separator.</dd> + +<dt><code><b>location</b></code> = "<i>name</i>" (or <code><b>file</b></code> + = "<i>name</i>", or <code><b>dir</b></code> = "<i>name</i>", or + <code><b>name</b></code> = "<i>name</i>")</dt> +<dd>Alternatively, the name of a single jar (or aar, war, ear, zip, or + directory).</dd> + +<dt><code><b>refid</b></code> = "<i>ref_id</i>"</dt> +<dd>Alternatively, a reference to the path or file set with the attribute + <code>id</code> = "<i>ref_id</i>".</dd> + +</dl> + +In addition, the jar elements can have ProGuard-style filter attributes: + +<dl> + +<dt><code><b>filter</b></code> = + "<a href="usage.html#filefilters"><i>file_filter</i></a>"</dt> +<dd>An optional filter for all class file names and resource file names that + are encountered.</dd> + +<dt><code><b>apkfilter</b></code> = + "<a href="usage.html#filefilters"><i>file_filter</i></a>"</dt> +<dd>An optional filter for all apk names that are encountered.</dd> + +<dt><code><b>jarfilter</b></code> = + "<a href="usage.html#filefilters"><i>file_filter</i></a>"</dt> +<dd>An optional filter for all jar names that are encountered.</dd> + +<dt><code><b>aarfilter</b></code> = + "<a href="usage.html#filefilters"><i>file_filter</i></a>"</dt> +<dd>An optional filter for all aar names that are encountered.</dd> + +<dt><code><b>warfilter</b></code> = + "<a href="usage.html#filefilters"><i>file_filter</i></a>"</dt> +<dd>An optional filter for all war names that are encountered.</dd> + +<dt><code><b>earfilter</b></code> = + "<a href="usage.html#filefilters"><i>file_filter</i></a>"</dt> +<dd>An optional filter for all ear names that are encountered.</dd> + +<dt><code><b>zipfilter</b></code> = + "<a href="usage.html#filefilters"><i>file_filter</i></a>"</dt> +<dd>An optional filter for all zip names that are encountered.</dd> + +</dl> + +<h2><a name="keepmodifier">Keep Modifier Attributes</a></h2> + +The keep tags can have the following <i>modifier</i> attributes: + +<dl> + +<dt><a href="usage.html#includedescriptorclasses"><code><b>includedescriptorclasses</b></code></a> + = "<i>boolean</i>" + (default = false)</dt> +<dd>Specifies whether the classes of the fields and methods specified in the + keep tag must be kept as well.</dd> + +<dt><a href="usage.html#allowshrinking"><code><b>allowshrinking</b></code></a> + = "<i>boolean</i>" + (default = false)</dt> +<dd>Specifies whether the entry points specified in the keep tag may be + shrunk.</dd> + +<dt><a href="usage.html#allowoptimization"><code><b>allowoptimization</b></code></a> + = "<i>boolean</i>" + (default = false)</dt> +<dd>Specifies whether the entry points specified in the keep tag may be + optimized.</dd> + +<dt><a href="usage.html#allowobfuscation"><code><b>allowobfuscation</b></code></a> + = "<i>boolean</i>" + (default = false)</dt> +<dd>Specifies whether the entry points specified in the keep tag may be + obfuscated.</dd> + +</dl> + +<h2><a name="classspecification">Class Specification Attributes and Nested Elements</a></h2> + +The keep tags can have the following <i>class_specification</i> attributes and +<i>class_member_specifications</i> nested elements: + +<dl> + +<dt><code><b>access</b></code> = "<i>access_modifiers</i>"</dt> +<dd>The optional access modifiers of the class. Any space-separated list of + "public", "final", and "abstract", with optional negators "!".</dd> + +<dt><code><b>annotation</b></code> = "<i>annotation_name</i>"</dt> +<dd>The optional fully qualified name of an annotation of the class, with + optional wildcards.</dd> + +<dt><code><b>type</b></code> = "<i>type</i>"</dt> +<dd>The optional type of the class: one of "class", "interface", or + "!interface".</dd> + +<dt><code><b>name</b></code> = "<i>class_name</i>"</dt> +<dd>The optional fully qualified name of the class, with optional + wildcards.</dd> + +<dt><code><b>extendsannotation</b></code> = "<i>annotation_name</i>"</dt> +<dd>The optional fully qualified name of an annotation of the the class that + the specified classes must extend, with optional wildcards.</dd> + +<dt><code><b>extends</b></code> = "<i>class_name</i>"</dt> +<dd>The optional fully qualified name of the class the specified classes + must extend, with optional wildcards.</dd> + +<dt><code><b>implements</b></code> = "<i>class_name</i>"</dt> +<dd>The optional fully qualified name of the class the specified classes + must implement, with optional wildcards.</dd> + +<dt><code><b><field</b></code> + <a href="#classmemberspecification"><i>class_member_specification</i></a> + <code><b>/></b></code></dt> +<dd>Specifies a field.</dd> + +<dt><code><b><method</b></code> + <a href="#classmemberspecification"><i>class_member_specification</i></a> + <code><b>/></b></code></dt> +<dd>Specifies a method.</dd> + +<dt><code><b><constructor</b></code> + <a href="#classmemberspecification"><i>class_member_specification</i></a> + <code><b>/></b></code></dt> +<dd>Specifies a constructor.</dd> + +</dl> + +<h2><a name="classmemberspecification">Class Member Specification Attributes</a></h2> + +The class member tags can have the following <i>class_member_specification</i> +attributes: + +<dl> + +<dt><code><b>access</b></code> = "<i>access_modifiers</i>"</dt> +<dd>The optional access modifiers of the class. Any space-separated list of + "public", "protected", "private", "static", etc., with optional negators + "!".</dd> + +<dt><code><b>annotation</b></code> = "<i>annotation_name</i>"</dt> +<dd>The optional fully qualified name of an annotation of the class member, + with optional wildcards.</dd> + +<dt><code><b>type</b></code> = "<i>type</i>"</dt> +<dd>The optional fully qualified type of the class member, with optional + wildcards. Not applicable for constructors, but required for methods for + which the <code>parameters</code> attribute is specified.</dd> + +<dt><code><b>name</b></code> = "<i>name</i>"</dt> +<dd>The optional name of the class member, with optional wildcards. Not + applicable for constructors.</dd> + +<dt><code><b>parameters</b></code> = "<i>parameters</i>"</dt> +<dd>The optional comma-separated list of fully qualified method parameters, + with optional wildcards. Not applicable for fields, but required for + constructors, and for methods for which the <code>type</code> attribute is + specified.</dd> + +</dl> + +<hr /> +<address> +Copyright © 2002-2017 +<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.guardsquare.com/">GuardSquare</a>. +</address> +</body> +</html> diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/attention.gif b/third_party/java/proguard/proguard5.3.3/docs/manual/attention.gif Binary files differnew file mode 100644 index 0000000000..1a0c712d60 --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/attention.gif diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/attributes.html b/third_party/java/proguard/proguard5.3.3/docs/manual/attributes.html new file mode 100644 index 0000000000..7f237cb9b8 --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/attributes.html @@ -0,0 +1,217 @@ +<!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>Attributes</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/attributes.html">ProGuard index</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> <a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>') +//--> +</script> +<noscript> +<a class="largebutton" target="_top" href="../index.html#manual/attributes.html">ProGuard index</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> +<a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a> +</noscript> + +<h2>Attributes</h2> + +Class files essentially define classes, their fields, and their methods. A lot +of essential and non-essential data are attached to these classes, fields, and +methods as <i>attributes</i>. For instance, attributes can contain bytecode, +source file names, line number tables, etc. +<p> + +ProGuard's obfuscation step removes attributes that are generally not +necessary for executing the code. With +the <a href="usage.html#keepattributes"><code>-keepattributes</code></a> +option, you can specify a filter for attributes that you do want to keep, for +instance, if your code accesses them through reflection or if you want to +preserve some compilation or debugging information. The filter works like +any <a href="usage.html#filters">filter</a> in ProGuard. +<p> + +The following wildcards are supported: + +<table cellspacing="10"> +<tr><td valign="top"><code><b>?</b></code></td> + <td>matches any single character in an attribute name.</td></tr> +<tr><td valign="top"><code><b>*</b></code></td> + <td>matches any part of an attribute name.</td></tr> +</table> + +An attribute name that is preceded by an exclamation mark '<b>!</b>' is +<i>excluded</i> from further attempts to match with <i>subsequent</i> +attribute names in the filter. Make sure to specify filters correctly, since +they are not checked for potential typos. +<p> + +For example, the following setting preserves the optional attributes that are +typically necessary when processing code that is intended to be used as a +library: +<pre> +-keepattributes Exceptions,InnerClasses,Signature,Deprecated, + SourceFile,LineNumberTable,*Annotation*,EnclosingMethod +</pre> +<p> + +The Java bytecode specifications currently specify the following list of +attributes. + +<h3>Optional attributes</h3> + +ProGuard's obfuscation step by default discards the following optional +attributes. You can keep them with +the <a href="usage.html#keepattributes"><code>-keepattributes</code></a> +option. + +<dl> +<dt><code><b>SourceFile</b></code></dt> +<dd>Specifies the name of the source file from which the class file was + compiled. If present, this name is reported in stack traces.</dd> + +<dt><div>(J++ extension)</div> + <code><b>SourceDir</b></code></dt> +<dd>Specifies the name of the source directory from which the class file was + compiled.</dd> + +<dt><code><b>InnerClasses</b></code></dt> +<dd>Specifies the relationship between a class and its inner classes and outer + classes. Other than this and the naming convention with a '$' separator + between the names of inner classes and outer classes, inner classes are + just like ordinary classes. Compilers may need this information to find + classes referenced in a compiled library. Code may access this information + by reflection, for instance to derive the simple name of the class.</dd> + +<dt><div>(Java 5 or higher)</div> + <code><b>EnclosingMethod</b></code></dt> +<dd>Specifies the method in which the class was defined. Compilers may need + this information to find classes referenced in a compiled library. Code + may access this information by reflection, for instance to derive the + simple name of the class.</dd> + +<dt><code><b>Deprecated</b></code></dt> +<dd>Indicates that the class, field, or method is deprecated.</dd> + +<dt><code><b>Synthetic</b></code></dt> +<dd>Indicates that the class, field, or method was generated by the + compiler.</dd> + +<dt><div>(Java 5 or higher)</div> + <code><b>Signature</b></code></dt> +<dd>Specifies the generic signature of the class, field, or method. Compilers + may need this information to properly compile classes that use generic + types from compiled libraries. Code may access this signature by + reflection.</dd> + +<dt><div>(Java 8 or higher)</div> + <code><b>MethodParameters</b></code></dt> +<dd>Specifies the names and access flags of the parameters of the method. Code + may access this information by reflection.</dd> + +<dt><code><b>Exceptions</b></code></dt> +<dd>Specifies the exceptions that a method may throw. Compilers may use this + information to enforce catching them.</dd> + +<dt><code><b>LineNumberTable</b></code></dt> +<dd>Specifies the line numbers of the method. If present, these line numbers + are reported in stack traces.</dd> + +<dt><code><b>LocalVariableTable</b></code></dt> +<dd>Specifies the names and types of local variables of the method. If present, + some IDEs may use this information for helping with auto-completion.</dd> + +<dt><div>(Java 5 or higher)</div> + <code><b>LocalVariableTypeTable</b></code></dt> +<dd>Specifies the names and generic types of local variables of the method. If + present, some IDEs may use this information for helping with + auto-completion.</dd> + +<dt><div>(Java 5 or higher)</div> + <code><b>RuntimeVisibleAnnotations</b></code></dt> +<dd>Specifies the annotations that are visible at run-time, for classes, + fields, and methods. Compilers and annotation processors may use these + annotations. Code may access them by reflection.</dd> + +<dt><div>(Java 5 or higher)</div> + <code><b>RuntimeInvisibleAnnotations</b></code></dt> +<dd>Specifies the annotations that are visible at compile-time, for classes, + fields, and methods. Compilers and annotation processors may use these + annotations.</dd> + +<dt><div>(Java 5 or higher)</div> + <code><b>RuntimeVisibleParameterAnnotations</b></code></dt> +<dd>Specifies the annotations that are visible at run-time, for method + parameters. Compilers and annotation processors may use these + annotations. Code may access them by reflection.</dd> + +<dt><div>(Java 5 or higher)</div> + <code><b>RuntimeInvisibleParameterAnnotations</b></code></dt> +<dd>Specifies the annotations that are visible at compile-time, for method + parameters. Compilers and annotation processors may use these + annotations.</dd> + +<dt><div>(Java 8 or higher)</div> + <code><b>RuntimeVisibleTypeAnnotations</b></code></dt> +<dd>Specifies the annotations that are visible at run-time, for generic types, + instructions, etc. Compilers and annotation processors may use these + annotations. Code may access them by reflection.</dd> + +<dt><div>(Java 8 or higher)</div> + <code><b>RuntimeInvisibleTypeAnnotations</b></code></dt> +<dd>Specifies the annotations that are visible at compile-time, for generic + types, instructions, etc. Compilers and annotation processors may use + these annotations.</dd> + +<dt><div>(Java 5 or higher)</div> + <code><b>AnnotationDefault</b></code></dt> +<dd>Specifies a default value for an annotation.</dd> + +</dl> +<p> + +<h3>Essential attributes</h3> + +ProGuard automatically keeps the following essential attributes, processing +them as necessary. We're listing them for the sake of completeness. + +<dl> +<dt><code><b>ConstantValue</b></code></dt> +<dd>Specifies a constant integer, float, class, string, etc.</dd> + +<dt><code><b>Code</b></code></dt> +<dd>Specifies the actual bytecode of a method.</dd> + +<dt><div>(Java Micro Edition)</div> + <code><b>StackMap</b></code></dt> +<dd>Provides preverification information. The Java Virtual Machine can use + this information to speed up the verification step when loading a + class.</dd> + +<dt><div>(Java 6 or higher)</div> + <code><b>StackMapTable</b></code></dt> +<dd>Provides preverification information. The Java Virtual Machine can use + this information to speed up the verification step when loading a + class.</dd> + +<dt><div>(Java 7 or higher)</div> + <code><b>BootstrapMethods</b></code></dt> +<dd>Specifies the methods to bootstrap dynamic method invocations.</dd> + +</dl> +<p> + +<hr /> +<address> +Copyright © 2002-2017 +<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.guardsquare.com/">GuardSquare</a>. +</address> +</body> +</html> diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/examples.html b/third_party/java/proguard/proguard5.3.3/docs/manual/examples.html new file mode 100644 index 0000000000..bb0b11a559 --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/examples.html @@ -0,0 +1,1693 @@ +<!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 Examples</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/examples.html">ProGuard index</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> <a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>') +//--> +</script> +<noscript> +<a class="largebutton" target="_top" href="../index.html#manual/examples.html">ProGuard index</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> +<a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a> +</noscript> + +<h2>Examples</h2> + +Some typical useful configurations: +<ol> +<li><a href="#application">A typical application</a></li> +<li><a href="#applet">A typical applet</a></li> +<li><a href="#midlet">A typical midlet</a></li> +<li><a href="#jcapplet">A typical Java Card applet</a></li> +<li><a href="#xlet">A typical xlet</a></li> +<li><a href="#androidactivity">A simple Android activity</a></li> +<li><a href="#androidapplication">A complete Android application</a></li> +<li><a href="#library">A typical library</a></li> +<li><a href="#applications">All possible applications in the input jars</a></li> +<li><a href="#applets">All possible applets in the input jars</a></li> +<li><a href="#midlets">All possible midlets in the input jars</a></li> +<li><a href="#jcapplets">All possible Java Card applets in the input jars</a></li> +<li><a href="#xlets">All possible xlets in the input jars</a></li> +<li><a href="#servlets">All possible servlets in the input jars</a></li> +<li><a href="#scala">Scala applications with the Scala runtime</a></li> +<li><a href="#native">Processing native methods</a></li> +<li><a href="#callback">Processing callback methods</a></li> +<li><a href="#enumerations">Processing enumeration classes</a></li> +<li><a href="#serializable">Processing serializable classes</a></li> +<li><a href="#beans">Processing bean classes</a></li> +<li><a href="#annotations">Processing annotations</a></li> +<li><a href="#database">Processing database drivers</a></li> +<li><a href="#componentui">Processing ComponentUI classes</a></li> +<li><a href="#rmi">Processing RMI code</a></li> +<li><a href="#injection">Processing dependency injection</a></li> +<li><a href="#dagger">Processing Dagger code</a></li> +<li><a href="#butterknife">Processing Butterknife code</a></li> +<li><a href="#resourcefiles">Processing resource files</a></li> +<li><a href="#manifestfiles">Processing manifest files</a></li> +<li><a href="#stacktrace">Producing useful obfuscated stack traces</a></li> +<li><a href="#repackaging">Obfuscating package names</a></li> +<li><a href="#logging">Removing logging code</a></li> +<li><a href="#restructuring">Restructuring the output archives</a></li> +<li><a href="#filtering">Filtering the input and the output</a></li> +<li><a href="#multiple">Processing multiple applications at once</a></li> +<li><a href="#incremental">Incremental obfuscation</a></li> +<li><a href="#microedition">Preverifying class files for Java Micro Edition</a></li> +<li><a href="#upgrade">Upgrading class files to Java 6</a></li> +<li><a href="#deadcode">Finding dead code</a></li> +<li><a href="#structure">Printing out the internal structure of class files</a></li> +<li><a href="#annotated">Using annotations to configure ProGuard</a></li> +</ol> + +You can find some sample configuration files in the <code>examples</code> +directory of the ProGuard distribution. + +<h3><a name="application">A typical application</a></h3> + +To shrink, optimize, and obfuscate a simple Java application, you typically +create a configuration file like <code>myconfig.pro</code>, which can be used +with +<pre> +bin/proguard @myconfig.pro +</pre> +<p> +The configuration file specifies the input, the output, and the entry points +of the application: +<pre> +-injars myapplication.jar +-outjars myapplication_out.jar +-libraryjars <java.home>/lib/rt.jar +-printmapping myapplication.map + +-keep public class mypackage.MyMain { + public static void main(java.lang.String[]); +} +</pre> +<p> +Note the use of the <code><java.home></code> system property. ProGuard +automatically replaces it when parsing the file. +<p> +The <a href="usage.html#keep"><code>-keep</code></a> option specifies the +entry point of the application that has to be preserved. +The access modifiers <code>public</code> and <code>static</code> are not +really required in this case, since we know a priori that the specified class +and method have the proper access flags. It just looks more familiar this way. +<p> +Note that all type names are fully specified: +<code>mypackage.MyMain</code> and <code>java.lang.String[]</code>. +<p> +We're writing out an obfuscation mapping file with <a +href="usage.html#printmapping"><code>-printmapping</code></a>, for +de-obfuscating any stack traces later on, or for incremental obfuscation of +extensions. +<p> +We can further improve the results with a few additional options: +<pre> +-optimizationpasses 3 +-overloadaggressively +-repackageclasses '' +-allowaccessmodification +</pre> +These options are not required; they just shave off some extra bytes from the +output jar, by performing up to 3 optimization passes, and by aggressively +obfuscating class members and <a href="#repackaging">package names</a>. +<p> +In general, you might need a few additional options for processing <a +href="#native">native methods</a>, <a href="#callback">callback methods</a>, +<a href="#enumerations">enumerations</a>, <a href="#serializable">serializable +classes</a>, <a href="#beans">bean classes</a>, <a +href="#annotations">annotations</a>, and <a href="#resourcefiles">resource +files</a>. + +<h3><a name="applet">A typical applet</a></h3> + +These options shrink, optimize, and obfuscate the applet +<code>mypackage.MyApplet</code>: +<pre> +-injars in.jar +-outjars out.jar +-libraryjars <java.home>/lib/rt.jar + +-keep public class mypackage.MyApplet +</pre> +<p> +The typical applet methods will be preserved automatically, since +<code>mypackage.MyApplet</code> is an extension of the <code>Applet</code> +class in the library <code>rt.jar</code>. +<p> +If applicable, you should add options for processing <a href="#native">native +methods</a>, <a href="#callback">callback methods</a>, <a +href="#enumerations">enumerations</a>, <a href="#serializable">serializable +classes</a>, <a href="#beans">bean classes</a>, <a +href="#annotations">annotations</a>, and <a href="#resourcefiles">resource +files</a>. + +<h3><a name="midlet">A typical midlet</a></h3> + +These options shrink, optimize, obfuscate, and preverify the midlet +<code>mypackage.MyMIDlet</code>: +<pre> +-injars in.jar +-outjars out.jar +-libraryjars /usr/local/java/wtk2.5.2/lib/midpapi20.jar +-libraryjars /usr/local/java/wtk2.5.2/lib/cldcapi11.jar +-overloadaggressively +-repackageclasses '' +-allowaccessmodification +-microedition + +-keep public class mypackage.MyMIDlet +</pre> +<p> +Note how we're now targeting the Java Micro Edition run-time environment of +<code>midpapi20.jar</code> and <code>cldcapi11.jar</code>, instead of the Java +Standard Edition run-time environment <code>rt.jar</code>. You can target +other JME environments by picking the appropriate jars. +<p> +The typical midlet methods will be preserved automatically, since +<code>mypackage.MyMIDlet</code> is an extension of the <code>MIDlet</code> +class in the library <code>midpapi20.jar</code>. +<p> +The <a href="usage.html#microedition"><code>-microedition</code></a> option +makes sure the class files are preverified for Java Micro Edition, producing +compact <code>StackMap</code> attributes. It is no longer necessary to run an +external preverifier. +<p> +Be careful if you do use the external <code>preverify</code> tool on a platform +with a case-insensitive filing system, such as Windows. Because this tool +unpacks your processed jars, you should then use ProGuard's <a +href="usage.html#dontusemixedcaseclassnames"><code>-dontusemixedcaseclassnames</code></a> +option. +<p> +If applicable, you should add options for processing <a href="#native">native +methods</a> and <a href="#resourcefiles">resource files</a>. +<p> +Note that you will still have to adapt the midlet jar size in the +corresponding jad file; ProGuard doesn't do that for you. + +<h3><a name="jcapplet">A typical Java Card applet</a></h3> + +These options shrink, optimize, and obfuscate the Java Card applet +<code>mypackage.MyApplet</code>: +<pre> +-injars in.jar +-outjars out.jar +-libraryjars /usr/local/java/javacard2.2.2/lib/api.jar +-dontwarn java.lang.Class +-overloadaggressively +-repackageclasses '' +-allowaccessmodification + +-keep public class mypackage.MyApplet +</pre> +<p> +The configuration is very similar to the configuration for midlets, except that +it now targets the Java Card run-time environment. This environment doesn't +have java.lang.Class, so we're telling ProGuard not to worry about it. + +<h3><a name="xlet">A typical xlet</a></h3> + +These options shrink, optimize, and obfuscate the xlet +<code>mypackage.MyXlet</code>: +<pre> +-injars in.jar +-outjars out.jar +-libraryjars /usr/local/java/jtv1.1/javatv.jar +-libraryjars /usr/local/java/cdc1.1/lib/cdc.jar +-libraryjars /usr/local/java/cdc1.1/lib/btclasses.zip +-overloadaggressively +-repackageclasses '' +-allowaccessmodification + +-keep public class mypackage.MyXlet +</pre> +<p> +The configuration is very similar to the configuration for midlets, except that +it now targets the CDC run-time environment with the Java TV API. + +<h3><a name="androidactivity">A simple Android activity</a></h3> + +These options shrink, optimize, and obfuscate the single Android +activity <code>mypackage.MyActivity</code>: +<pre> +-injars bin/classes +-outjars bin/classes-processed.jar +-libraryjars /usr/local/java/android-sdk/platforms/android-9/android.jar + +-dontpreverify +-repackageclasses '' +-allowaccessmodification +-optimizations !code/simplification/arithmetic + +-keep public class mypackage.MyActivity +</pre> +<p> +We're targeting the Android run-time and keeping the activity as an entry +point. +<p> +Preverification is irrelevant for the dex compiler and the Dalvik VM, so we +can switch it off with the +<a href="usage.html#dontpreverify"><code>-dontpreverify</code></a> option. +<p> +The <a href="usage.html#optimizations"><code>-optimizations</code></a> option +disables some arithmetic simplifications that Dalvik 1.0 and 1.5 can't handle. +Note that the Dalvik VM also can't +handle <a href="usage.html#overloadaggressively">aggressive overloading</a> +(of static fields). +<p> +If applicable, you should add options for processing <a href="#native">native +methods</a>, <a href="#callback">callback methods</a>, +<a href="#enumerations">enumerations</a>, +<a href="#annotations">annotations</a>, and +<a href="#resourcefiles">resource files</a>. + +<h3><a name="androidapplication">A complete Android application</a></h3> + +<img class="float" src="attention.gif" width="64" height="64" alt="attention" +/> The standard build processes of the Android SDK (with Ant, Gradle, Android +Studio, and Eclipse) already integrate ProGuard with all the proper settings. +You only need to enable ProGuard by uncommenting the line +"<code>proguard.config=.....</code>" in the +file <code>project.properties</code> (created or updated by Android SDK +revision 17 or higher) or by adapting your <code>build.gradle</code> file. You +then <em>don't</em> need any of the configuration below. +<p> +Notes: +<ul> +<li>In case of problems, you may want to check if the configuration files that + are listed on this line (<code>proguard-project.txt</code>,...) contain + the necessary settings for your application.</li> +<li>Android SDK revision 20 and higher have a different configuration file for + enabling optimization: + <code>${sdk.dir}/tools/proguard/proguard-android-optimize.txt</code> + instead of the default + <code>${sdk.dir}/tools/proguard/proguard-android.txt</code>.</li> +<li>The build processes are already setting the necessary program jars, + library jars, and output jars for you — don't specify them again.</li> +<li>If you get warnings about missing referenced classes: it's all too common + that libraries refer to missing classes. + See <a href="troubleshooting.html#unresolvedclass">"Warning: can't find + referenced class"</a> in the Troubleshooting section.</li> +</ul> +<p> +For more information, you can consult the official <a target="other" +href="http://developer.android.com/guide/developing/tools/proguard.html">Developer +Guide</a> in the Android SDK. +<p> +If you're constructing a build process <em>from scratch</em>: these options +shrink, optimize, and obfuscate all public activities, services, broadcast +receivers, and content providers from the compiled classes and external +libraries: +<pre> +-injars bin/classes +-injars libs +-outjars bin/classes-processed.jar +-libraryjars /usr/local/java/android-sdk/platforms/android-9/android.jar + +-dontpreverify +-repackageclasses '' +-allowaccessmodification +-optimizations !code/simplification/arithmetic +-keepattributes *Annotation* + +-keep public class * extends android.app.Activity +-keep public class * extends android.app.Application +-keep public class * extends android.app.Service +-keep public class * extends android.content.BroadcastReceiver +-keep public class * extends android.content.ContentProvider + +-keep public class * extends android.view.View { + public <init>(android.content.Context); + public <init>(android.content.Context, android.util.AttributeSet); + public <init>(android.content.Context, android.util.AttributeSet, int); + public void set*(...); +} + +-keepclasseswithmembers class * { + public <init>(android.content.Context, android.util.AttributeSet); +} + +-keepclasseswithmembers class * { + public <init>(android.content.Context, android.util.AttributeSet, int); +} + +-keepclassmembers class * extends android.content.Context { + public void *(android.view.View); + public void *(android.view.MenuItem); +} + +-keepclassmembers class * implements android.os.Parcelable { + static ** CREATOR; +} + +-keepclassmembers class **.R$* { + public static <fields>; +} + +-keepclassmembers class * { + @android.webkit.JavascriptInterface <methods>; +} +</pre> +<p> +Most importantly, we're keeping all fundamental classes that may be referenced +by the <code>AndroidManifest.xml</code> file of the application. If your +manifest file contains other classes and methods, you may have to specify +those as well. +<p> +We're keeping annotations, since they might be used by custom +<code>RemoteViews</code>. +<p> +We're keeping any custom <code>View</code> extensions and other classes with +typical constructors, since they might be referenced from XML layout files. +<p> +We're also keeping possible <code>onClick</code> handlers in +custom <code>Context</code> extensions, since they might be referenced from +XML layout files. +<p> +We're also keeping the required static fields in <code>Parcelable</code> +implementations, since they are accessed by introspection. +<p> +We're keeping the static fields of referenced inner classes of auto-generated + <code>R</code> classes, just in case your code is accessing those fields by +introspection. Note that the compiler already inlines primitive fields, so +ProGuard can generally remove all these classes entirely anyway (because the +classes are not referenced and therefore not required). +<p> +Finally, we're keeping annotated Javascript interface methods, so they can be +exported and accessed by their original names. Javascript interface methods +that are not annotated (in code targeted at Android versions older than 4.2) +still need to be preserved manually. +<p> +If you're using additional Google APIs, you'll have to specify +those as well, for instance: +<pre> +-libraryjars /usr/local/android-sdk/add-ons/google_apis-7_r01/libs/maps.jar +</pre> +<p> +If you're using Google's optional License Verification Library, you can +obfuscate its code along with your own code. You do have to preserve +its <code>ILicensingService</code> interface for the library to work: +<pre> +-keep public interface com.android.vending.licensing.ILicensingService +</pre> +<p> +If you're using the Android Compatibility library, you should add the +following line, to let ProGuard know it's ok that the library references some +classes that are not available in all versions of the API: +<pre> +-dontwarn android.support.** +</pre> +<p> +If applicable, you should add options for processing <a href="#native">native +methods</a>, <a href="#callback">callback methods</a>, +<a href="#enumerations">enumerations</a>, +and <a href="#resourcefiles">resource files</a>. You may also want to add +options for producing <a href="#stacktrace">useful stack traces</a> and +to <a href="#logging">remove logging</a>. You can find a complete sample +configuration in <code>examples/android.pro</code> in the ProGuard +distribution. + +<h3><a name="library">A typical library</a></h3> + +These options shrink, optimize, and obfuscate an entire library, keeping all +public and protected classes and class members, native method names, and +serialization code. The processed version of the library can then still be +used as such, for developing code based on its public API. +<pre> +-injars in.jar +-outjars out.jar +-libraryjars <java.home>/lib/rt.jar +-printmapping out.map + +-keepparameternames +-renamesourcefileattribute SourceFile +-keepattributes Exceptions,InnerClasses,Signature,Deprecated, + SourceFile,LineNumberTable,*Annotation*,EnclosingMethod + +-keep public class * { + public protected *; +} + +-keepclassmembernames class * { + java.lang.Class class$(java.lang.String); + java.lang.Class class$(java.lang.String, boolean); +} + +-keepclasseswithmembernames,includedescriptorclasses class * { + native <methods>; +} + +-keepclassmembers,allowoptimization enum * { + public static **[] values(); + public static ** valueOf(java.lang.String); +} + +-keepclassmembers class * implements java.io.Serializable { + static final long serialVersionUID; + private static final java.io.ObjectStreamField[] serialPersistentFields; + private void writeObject(java.io.ObjectOutputStream); + private void readObject(java.io.ObjectInputStream); + java.lang.Object writeReplace(); + java.lang.Object readResolve(); +} +</pre> +<p> +This configuration should preserve everything we'll ever want to access in the +library. Only if there are any other non-public classes or methods that are +invoked dynamically, they should be specified using additional <a +href="usage.html#keep"><code>-keep</code></a> options. +<p> +The <a +href="usage.html#keepclassmembernames"><code>-keepclassmembernames</code></a> +option for the <code>class$</code> methods is not strictly necessary. These +methods are inserted by the <code>javac</code> compiler and the +<code>jikes</code> compiler respectively, in JDK 1.2 and older, to implement +the <code>.class</code> construct. ProGuard will automatically detect them and +deal with them, even when their names have been obfuscated. However, other +obfuscators may rely on the original method names. It may therefore be helpful +to preserve them, in case these other obfuscators are ever used for further +obfuscation of the library. +<p> +The "Exceptions" attribute has to be preserved, so the compiler knows which +exceptions methods may throw. +<p> +The "InnerClasses" attribute (or more precisely, its source name part) has to +be preserved too, for any inner classes that can be referenced from outside the +library. The <code>javac</code> compiler would be unable to find the inner +classes otherwise. +<p> +The "Signature" attribute is required to be able to access generic types when +compiling in JDK 5.0 and higher. +<p> +The <a href="usage.html#keepparameternames"><code>-keepparameternames</code></a> +option keeps the parameter names in the "LocalVariableTable" and +"LocalVariableTypeTable" attributes of public library methods. Some IDEs can +present these names to the developers who use the library. +<p> +Finally, we're keeping the "Deprecated" attribute and the attributes for +producing <a href="#stacktrace">useful stack traces</a>. +<p> +We've also added some options for for processing <a href="#native">native +methods</a>, <a href="#enumerations">enumerations</a>, <a +href="#serializable">serializable classes</a>, and <a +href="#annotations">annotations</a>, which are all discussed in their +respective examples. + +<h3><a name="applications">All possible applications in the input jars</a></h3> + +These options shrink, optimize, and obfuscate all public applications in +<code>in.jar</code>: +<pre> +-injars in.jar +-outjars out.jar +-libraryjars <java.home>/lib/rt.jar +-printseeds + +-keepclasseswithmembers public class * { + public static void main(java.lang.String[]); +} +</pre> +<p> +Note the use of <a +href="usage.html#keepclasseswithmembers"><code>-keepclasseswithmembers</code></a>. +We don't want to preserve all classes, just all classes that have main +methods, and those methods. +<p> +The <a href="usage.html#printseeds"><code>-printseeds</code></a> option prints +out which classes exactly will be preserved, so we know for sure we're getting +what we want. +<p> +If applicable, you should add options for processing <a href="#native">native +methods</a>, <a href="#callback">callback methods</a>, <a +href="#enumerations">enumerations</a>, <a href="#serializable">serializable +classes</a>, <a href="#beans">bean classes</a>, <a +href="#annotations">annotations</a>, and <a href="#resourcefiles">resource +files</a>. + +<h3><a name="applets">All possible applets in the input jars</a></h3> + +These options shrink, optimize, and obfuscate all public applets in +<code>in.jar</code>: +<pre> +-injars in.jar +-outjars out.jar +-libraryjars <java.home>/lib/rt.jar +-printseeds + +-keep public class * extends java.applet.Applet +</pre> +<p> +We're simply keeping all classes that extend the <code>Applet</code> class. +<p> +Again, the <a href="usage.html#printseeds"><code>-printseeds</code></a> option +prints out which applets exactly will be preserved. +<p> +If applicable, you should add options for processing <a href="#native">native +methods</a>, <a href="#callback">callback methods</a>, <a +href="#enumerations">enumerations</a>, <a href="#serializable">serializable +classes</a>, <a href="#beans">bean classes</a>, <a +href="#annotations">annotations</a>, and <a href="#resourcefiles">resource +files</a>. + +<h3><a name="midlets">All possible midlets in the input jars</a></h3> + +These options shrink, optimize, obfuscate, and preverify all public midlets in +<code>in.jar</code>: +<pre> +-injars in.jar +-outjars out.jar +-libraryjars /usr/local/java/wtk2.5.2/lib/midpapi20.jar +-libraryjars /usr/local/java/wtk2.5.2/lib/cldcapi11.jar +-overloadaggressively +-repackageclasses '' +-allowaccessmodification +-microedition +-printseeds + +-keep public class * extends javax.microedition.midlet.MIDlet +</pre> +<p> +We're simply keeping all classes that extend the <code>MIDlet</code> class. +<p> +The <a href="usage.html#microedition"><code>-microedition</code></a> option +makes sure the class files are preverified for Java Micro Edition, producing +compact <code>StackMap</code> attributes. It is no longer necessary to run an +external preverifier. +<p> +Be careful if you do use the external <code>preverify</code> tool on a platform +with a case-insensitive filing system, such as Windows. Because this tool +unpacks your processed jars, you should then use ProGuard's <a +href="usage.html#dontusemixedcaseclassnames"><code>-dontusemixedcaseclassnames</code></a> +option. +<p> +The <a href="usage.html#printseeds"><code>-printseeds</code></a> option prints +out which midlets exactly will be preserved. +<p> +If applicable, you should add options for processing <a href="#native">native +methods</a> and <a href="#resourcefiles">resource files</a>. +<p> +Note that you will still have to adapt the midlet jar size in the +corresponding jad file; ProGuard doesn't do that for you. + +<h3><a name="jcapplets">All possible Java Card applets in the input jars</a></h3> + +These options shrink, optimize, and obfuscate all public Java Card applets in +<code>in.jar</code>: +<pre> +-injars in.jar +-outjars out.jar +-libraryjars /usr/local/java/javacard2.2.2/lib/api.jar +-dontwarn java.lang.Class +-overloadaggressively +-repackageclasses '' +-allowaccessmodification +-printseeds + +-keep public class * implements javacard.framework.Applet +</pre> +<p> +We're simply keeping all classes that implement the <code>Applet</code> +interface. +<p> +The <a href="usage.html#printseeds"><code>-printseeds</code></a> option prints +out which applets exactly will be preserved. + +<h3><a name="xlets">All possible xlets in the input jars</a></h3> + +These options shrink, optimize, and obfuscate all public xlets in +<code>in.jar</code>: +<pre> +-injars in.jar +-outjars out.jar +-libraryjars /usr/local/java/jtv1.1/javatv.jar +-libraryjars /usr/local/java/cdc1.1/lib/cdc.jar +-libraryjars /usr/local/java/cdc1.1/lib/btclasses.zip +-overloadaggressively +-repackageclasses '' +-allowaccessmodification +-printseeds + +-keep public class * implements javax.tv.xlet.Xlet +</pre> +<p> +We're simply keeping all classes that implement the <code>Xlet</code> interface. +<p> +The <a href="usage.html#printseeds"><code>-printseeds</code></a> option prints +out which xlets exactly will be preserved. + +<h3><a name="servlets">All possible servlets in the input jars</a></h3> + +These options shrink, optimize, and obfuscate all public servlets in +<code>in.jar</code>: +<pre> +-injars in.jar +-outjars out.jar +-libraryjars <java.home>/lib/rt.jar +-libraryjars /usr/local/java/servlet/servlet.jar +-printseeds + +-keep public class * implements javax.servlet.Servlet +</pre> +<p> +Keeping all servlets is very similar to keeping all applets. The servlet API +is not part of the standard run-time jar, so we're specifying it as a library. +Don't forget to use the right path name. +<p> +We're then keeping all classes that implement the <code>Servlet</code> +interface. We're using the <code>implements</code> keyword because it looks +more familiar in this context, but it is equivalent to <code>extends</code>, +as far as ProGuard is concerned. +<p> +The <a href="usage.html#printseeds"><code>-printseeds</code></a> option prints +out which servlets exactly will be preserved. +<p> +If applicable, you should add options for processing <a href="#native">native +methods</a>, <a href="#callback">callback methods</a>, <a +href="#enumerations">enumerations</a>, <a href="#serializable">serializable +classes</a>, <a href="#beans">bean classes</a>, <a +href="#annotations">annotations</a>, and <a href="#resourcefiles">resource +files</a>. + +<h3><a name="scala">Scala applications with the Scala runtime</a></h3> + +These options shrink, optimize, and obfuscate all public Scala applications in +<code>in.jar</code>: +<pre> +-injars in.jar +-injars /usr/local/java/scala-2.9.1/lib/scala-library.jar +-outjars out.jar +-libraryjars <java.home>/lib/rt.jar + +-dontwarn scala.** + +-keepclasseswithmembers public class * { + public static void main(java.lang.String[]); +} + +-keep class * implements org.xml.sax.EntityResolver + +-keepclassmembers class * { + ** MODULE$; +} + +-keepclassmembernames class scala.concurrent.forkjoin.ForkJoinPool { + long eventCount; + int workerCounts; + int runControl; + scala.concurrent.forkjoin.ForkJoinPool$WaitQueueNode syncStack; + scala.concurrent.forkjoin.ForkJoinPool$WaitQueueNode spareStack; +} + +-keepclassmembernames class scala.concurrent.forkjoin.ForkJoinWorkerThread { + int base; + int sp; + int runState; +} + +-keepclassmembernames class scala.concurrent.forkjoin.ForkJoinTask { + int status; +} + +-keepclassmembernames class scala.concurrent.forkjoin.LinkedTransferQueue { + scala.concurrent.forkjoin.LinkedTransferQueue$PaddedAtomicReference head; + scala.concurrent.forkjoin.LinkedTransferQueue$PaddedAtomicReference tail; + scala.concurrent.forkjoin.LinkedTransferQueue$PaddedAtomicReference cleanMe; +} +</pre> +<p> +The configuration is essentially the same as +for <a href="#applications">processing applications</a>, because Scala is +compiled to ordinary Java bytecode. However, the example processes the Scala +runtime library as well. The processed jar can be an order of magnitude +smaller and a few times faster than the original code (for the Scala code +examples, for instance). +<p> +The <a href="usage.html#dontwarn"><code>-dontwarn</code></a> option tells +ProGuard not to complain about some artefacts in the Scala runtime, the way it +is compiled by the <code>scalac</code> compiler (at least in Scala 2.9.1 and +older). Note that this option should always be used with care. +<p> +The additional <a href="usage.html#keepoverview"><code>-keep</code></a> +options make sure that some classes and some fields that are accessed by means +of introspection are not removed or renamed. +<p> +If applicable, you should add options for processing <a href="#native">native +methods</a>, <a href="#callback">callback methods</a>, <a +href="#enumerations">enumerations</a>, <a href="#serializable">serializable +classes</a>, <a href="#beans">bean classes</a>, <a +href="#annotations">annotations</a>, and <a href="#resourcefiles">resource +files</a>. +<h3><a name="native">Processing native methods</a></h3> + +If your application, applet, servlet, library, etc., contains native methods, +you'll want to preserve their names and their classes' names, so they can +still be linked to the native library. The following additional option will +ensure that: +<pre> +-keepclasseswithmembernames,includedescriptorclasses class * { + native <methods>; +} +</pre> +<p> +Note the use of +<a href="usage.html#keepclasseswithmembernames"><code>-keepclasseswithmembernames</code></a>. +We don't want to preserve all classes or all native methods; we just want to +keep the relevant names from being obfuscated. The modifier +<a href="usage.html#includedescriptorclasses">includedescriptorclasses</a> +additionally makes sure that the return types and parameter types aren't +renamed either, so the entire signatures remain compatible with the native +libraries. +<p> +ProGuard doesn't look at your native code, so it won't automatically preserve +the classes or class members that are invoked by the native code. These are +entry points, which you'll have to specify explicitly. <a +href="callback">Callback methods</a> are discussed below as a typical example. + +<h3><a name="callback">Processing callback methods</a></h3> + +If your application, applet, servlet, library, etc., contains callback +methods, which are called from external code (native code, scripts,...), +you'll want to preserve them, and probably their classes too. They are just +entry points to your code, much like, say, the main method of an application. +If they aren't preserved by other <code>-keep</code> options, something like +the following option will keep the callback class and method: +<pre> +-keep class mypackage.MyCallbackClass { + void myCallbackMethod(java.lang.String); +} +</pre> +<p> +This will preserve the given class and method from being removed or renamed. + +<h3><a name="enumerations">Processing enumeration classes</a></h3> + +If your application, applet, servlet, library, etc., contains enumeration +classes, you'll have to preserve some special methods. Enumerations were +introduced in Java 5. The java compiler translates enumerations into classes +with a special structure. Notably, the classes contain implementations of some +static methods that the run-time environment accesses by introspection (Isn't +that just grand? Introspection is the self-modifying code of a new +generation). You have to specify these explicitly, to make sure they aren't +removed or obfuscated: +<pre> +-keepclassmembers,allowoptimization enum * { + public static **[] values(); + public static ** valueOf(java.lang.String); +} +</pre> + +<h3><a name="serializable">Processing serializable classes</a></h3> + +More complex applications, applets, servlets, libraries, etc., may contain +classes that are serialized. Depending on the way in which they are used, they +may require special attention: +<ul> + +<li>Often, serialization is simply a means of transporting data, without + long-term storage. Classes that are shrunk and obfuscated should then + continue to function fine with the following additional options: + +<pre> +-keepclassmembers class * implements java.io.Serializable { + private static final java.io.ObjectStreamField[] serialPersistentFields; + private void writeObject(java.io.ObjectOutputStream); + private void readObject(java.io.ObjectInputStream); + java.lang.Object writeReplace(); + java.lang.Object readResolve(); +} +</pre> +<p> + + The <a + href="usage.html#keepclassmembers"><code>-keepclassmembers</code></a> + option makes sure that any serialization methods are kept. By using this + option instead of the basic <code>-keep</code> option, we're not + forcing preservation of <i>all</i> serializable classes, just preservation + of the listed members of classes that are actually used.</li> + +<li>Sometimes, the serialized data are stored, and read back later into newer + versions of the serializable classes. One then has to take care the classes + remain compatible with their unprocessed versions and with future + processed versions. In such cases, the relevant classes will most likely + have <code>serialVersionUID</code> fields. The following options should + then be sufficient to ensure compatibility over time: + +<pre> +-keepnames class * implements java.io.Serializable + +-keepclassmembers class * implements java.io.Serializable { + static final long serialVersionUID; + private static final java.io.ObjectStreamField[] serialPersistentFields; + !static !transient <fields>; + private void writeObject(java.io.ObjectOutputStream); + private void readObject(java.io.ObjectInputStream); + java.lang.Object writeReplace(); + java.lang.Object readResolve(); +} +</pre> +<p> + + The <code>serialVersionUID</code> and <code>serialPersistentFields</code> + lines makes sure those fields are preserved, if they are present. + The <code><fields></code> line preserves all non-static, + non-transient fields, with their original names. The introspection of the + serialization process and the de-serialization process will then find + consistent names.</li> + +<li>Occasionally, the serialized data have to remain compatible, but the + classes involved lack <code>serialVersionUID</code> fields. I imagine the + original code will then be hard to maintain, since the serial version UID + is then computed from a list of features the serializable class. Changing + the class ever so slightly may change the computed serial version UID. The + list of features is specified in the section on <a + href="http://docs.oracle.com/javase/8/docs/platform/serialization/spec/class.html#a4100">Stream + Unique Identifiers</a> of Sun's <a + href="http://docs.oracle.com/javase/8/docs/platform/serialization/spec/serialTOC.html">Java + Object Serialization Specification</a>. The following directives should at + least partially ensure compatibility with the original classes: + +<pre> +-keepnames class * implements java.io.Serializable + +-keepclassmembers class * implements java.io.Serializable { + static final long serialVersionUID; + private static final java.io.ObjectStreamField[] serialPersistentFields; + !static !transient <fields>; + !private <fields>; + !private <methods>; + private void writeObject(java.io.ObjectOutputStream); + private void readObject(java.io.ObjectInputStream); + java.lang.Object writeReplace(); + java.lang.Object readResolve(); +} +</pre> +<p> + + The new options force preservation of the elements involved in the UID + computation. In addition, the user will have to manually specify all + interfaces of the serializable classes (using something like "<code>-keep + interface MyInterface</code>"), since these names are also used when + computing the UID. A fast but sub-optimal alternative would be simply + keeping all interfaces with "<code>-keep interface *</code>".</li> + +<li>In the rare event that you are serializing lambda expressions in Java 8 or + higher, you need to preserve some methods and adapt the hard-coded names + of the classes in which they occur: + +<pre> +-keepclassmembers class * { + private static synthetic java.lang.Object $deserializeLambda$(java.lang.invoke.SerializedLambda); +} + +-keepclassmembernames class * { + private static synthetic *** lambda$*(...); +} + +-adaptclassstrings com.example.Test +</pre> +<p> + + This should satisfy the reflection in the deserialization code of the + Java run-time. + +</ul> +<p> + +Note that the above options may preserve more classes and class members +than strictly necessary. For instance, a large number of classes may implement +the <code>Serialization</code> interface, yet only a small number may actually +ever be serialized. Knowing your application and tuning the configuration +often produces more compact results. + +<h3><a name="beans">Processing bean classes</a></h3> + +If your application, applet, servlet, library, etc., makes extensive use of +introspection on bean classes to find bean editor classes, or getter and +setter methods, then configuration may become painful. There's not much else +you can do than making sure the bean class names, or the getter and setter +names don't change. For instance: +<pre> +-keep public class mypackage.MyBean { + public void setMyProperty(int); + public int getMyProperty(); +} + +-keep public class mypackage.MyBeanEditor +</pre> +<p> +If there are too many elements to list explicitly, wildcards in class names +and method signatures might be helpful. This example preserves all possible +setters and getters in classes in the package <code>mybeans</code>: +<pre> +-keep class mybeans.** { + void set*(***); + void set*(int, ***); + + boolean is*(); + boolean is*(int); + + *** get*(); + *** get*(int); +} +</pre> +<p> +The '<code>***</code>' wildcard matches any type (primitive or non-primitive, +array or non-array). The methods with the '<code>int</code>' arguments matches +properties that are lists. + +<h3><a name="annotations">Processing annotations</a></h3> + +If your application, applet, servlet, library, etc., uses annotations, you may +want to preserve them in the processed output. Annotations are represented by +attributes that have no direct effect on the execution of the code. However, +their values can be retrieved through introspection, allowing developers to +adapt the execution behavior accordingly. By default, ProGuard treats +annotation attributes as optional, and removes them in the obfuscation step. +If they are required, you'll have to specify this explicitly: +<pre> +-keepattributes *Annotation* +</pre> +<p> +For brevity, we're specifying a wildcarded attribute name, which will match +<code>RuntimeVisibleAnnotations</code>, +<code>RuntimeInvisibleAnnotations</code>, +<code>RuntimeVisibleParameterAnnotations</code>, +<code>RuntimeInvisibleParameterAnnotations</code>, and +<code>AnnotationDefault</code>. Depending on the purpose of the processed +code, you could refine this selection, for instance not keeping the run-time +invisible annotations (which are only used at compile-time). +<p> +Some code may make further use of introspection to figure out the enclosing +methods of anonymous inner classes. In that case, the corresponding attribute +has to be preserved as well: +<pre> +-keepattributes EnclosingMethod +</pre> + +<h3><a name="database">Processing database drivers</a></h3> + +Database drivers are implementations of the <code>Driver</code> interface. +Since they are often created dynamically, you may want to preserve any +implementations that you are processing as entry points: +<pre> +-keep class * implements java.sql.Driver +</pre> +<p> +This option also gets rid of the note that ProGuard prints out about +<code>(java.sql.Driver)Class.forName</code> constructs, if you are +instantiating a driver in your code (without necessarily implementing any +drivers yourself). + +<h3><a name="componentui">Processing ComponentUI classes</a></h3> + +Swing UI look and feels are implemented as extensions of the +<code>ComponentUI</code> class. For some reason, these have to contain a +static method <code>createUI</code>, which the Swing API invokes using +introspection. You should therefore always preserve the method as an entry +point, for instance like this: +<pre> +-keep class * extends javax.swing.plaf.ComponentUI { + public static javax.swing.plaf.ComponentUI createUI(javax.swing.JComponent); +} +</pre> +<p> +This option also keeps the classes themselves. + +<h3><a name="rmi">Processing RMI code</a></h3> + +Reportedly, the easiest way to handle RMI code is to process the code with +ProGuard first and then invoke the <code>rmic</code> tool. If that is not +possible, you may want to try something like this: +<pre> +-keepattributes Exceptions + +-keep interface * extends java.rmi.Remote { + <methods>; +} + +-keep class * implements java.rmi.Remote { + <init>(java.rmi.activation.ActivationID, java.rmi.MarshalledObject); +} +</pre> +<p> +The first <code>-keep</code> option keeps all your Remote interfaces and their +methods. The second one keeps all the implementations, along with their +particular RMI constructors, if any. +<p> +The <code>Exceptions</code> attribute has to be kept too, because the RMI +handling code performs introspection to check whether the method signatures +are compatible. + +<h3><a name="injection">Processing dependency injection</a></h3> + +If your application is using JEE-style dependency injection, the application +container will automatically assign instances of resource classes to fields and +methods that are annotated with <code>@Resource</code>. The container applies +introspection, even accessing private class members directly. It typically +constructs a resource name based on the type name and the class member name. +We then have to avoid that such class members are removed or renamed: +<pre> +-keepclassmembers class * { + @javax.annotation.Resource *; +} +</pre> +<p> +The Spring framework has another similar annotation <code>@Autowired</code>: +<pre> +-keepclassmembers class * { + @org.springframework.beans.factory.annotation.Autowired *; +} +</pre> + +<h3><a name="dagger">Processing Dagger code</a></h3> + +If your Android application includes Dagger for dependency injection, you need +a few lines of configuration, since Dagger heavily relies on reflection to tie +together the code at runtime. You need to preserve the annotated class +members, the generated classes, and a utility class: +<pre> +-keepclassmembers,allowobfuscation class * { + @dagger.** *; +} + +-keep class **$$ModuleAdapter +-keep class **$$InjectAdapter +-keep class **$$StaticInjection + +-keepnames class dagger.Lazy +</pre> +<p> +Unfortunately, you still need to explicitly preserve the corresponding base +classes from your project. For example, for a generated class like +<code>com.example.SomeClass$$ModuleAdapter</code>, you still need to specify: +<pre> +-keep class com.example.SomeClass +</pre> +<p> +Dagger can then still combine the corresponding pairs of classes, based on +their names. You can figure out the base classes by listing the generated +classes in the <code>gen</code> directory of your project (e.g. +<code>com/examples/SomeClass$$ModuleAdapter.class</code>). +<p> +Dagger 2 no longer relies on reflection with these naming conventions, which +makes life a lot easier. + +<h3><a name="butterknife">Processing Butterknife code</a></h3> + +If your Android application includes Butterknife to inject views, you also +need a few lines of configuration, since Butterknife relies on reflection to +tie together the code at runtime: +<pre> +-keep @interface butterknife.* + +-keepclasseswithmembers class * { + @butterknife.* <fields>; +} + +-keepclasseswithmembers class * { + @butterknife.* <methods>; +} + +-keepclasseswithmembers class * { + @butterknife.On* <methods>; +} + +-keep class **$$ViewInjector { + public static void inject(...); + public static void reset(...); +} + +-keep class **$$ViewBinder { + public static void bind(...); + public static void unbind(...); +} +</pre> +<p> +These settings preserve the Butterknife annotations, the annotated fields and +methods, and the generated classes and methods that Butterknife accesses by +reflection. + +<h3><a name="resourcefiles">Processing resource files</a></h3> + +If your application, applet, servlet, library, etc., contains resource files, +it may be necessary to adapt their names and/or their contents when the +application is obfuscated. The following two options can achieve this +automatically: +<pre> +-adaptresourcefilenames **.properties,**.gif,**.jpg +-adaptresourcefilecontents **.properties,META-INF/MANIFEST.MF +</pre> +<p> +The <a href="usage.html#adaptresourcefilenames">-adaptresourcefilenames</a> +option in this case renames properties files and image files in the processed +output, based on the obfuscated names of their corresponding class files (if +any). The <a +href="usage.html#adaptresourcefilecontents">-adaptresourcefilecontents</a> +option looks for class names in properties files and in the manifest file, and +replaces these names by the obfuscated names (if any). You'll probably want to +adapt the filters to suit your application. + +<h3><a name="manifestfiles">Processing manifest files</a></h3> + +As illustrated in the previous section, manifest files can be treated like +ordinary resource files. ProGuard can adapt obfuscated class names in the +files, but it won't make any other changes. If you want anything else, you +should apply an external tool. For instance, if a manifest file contains +signing information, you should sign the jar again after it has been +processed. +<p> +If you're merging several input jars into a single output jar, you'll have to +pick one, typically by specifying <a href="usage.html#filters">filters</a>: +<pre> +-injars in1.jar +-injars in2.jar(!META-INF/MANIFEST.MF) +-injars in3.jar(!META-INF/MANIFEST.MF) +-outjars out.jar +</pre> +<p> +The filters will let ProGuard copy the manifest file from the first jar and +ignore any manifest files in the second and third input jars. Note that +ProGuard will leave the order of the files in the jars unchanged; manifest +files are not necessarily put first. + +<h3><a name="stacktrace">Producing useful obfuscated stack traces</a></h3> + +These options let obfuscated applications or libraries produce stack traces +that can still be deciphered later on: +<pre> +-printmapping out.map + +-renamesourcefileattribute SourceFile +-keepattributes SourceFile,LineNumberTable +</pre> +<p> +We're keeping all source file attributes, but we're replacing their values by +the string "SourceFile". We could use any string. This string is already +present in all class files, so it doesn't take up any extra space. If you're +working with J++, you'll want to keep the "SourceDir" attribute as well. +<p> +We're also keeping the line number tables of all methods. +<p> +Whenever both of these attributes are present, the Java run-time environment +will include line number information when printing out exception stack traces. +<p> +The information will only be useful if we can map the obfuscated names back to +their original names, so we're saving the mapping to a file +<code>out.map</code>. The information can then be used by the <a +href="retrace/index.html">ReTrace</a> tool to restore the original stack trace. + +<h3><a name="repackaging">Obfuscating package names</a></h3> + +Package names can be obfuscated in various ways, with increasing levels of +obfuscation and compactness. For example, consider the following classes: +<pre> +mycompany.myapplication.MyMain +mycompany.myapplication.Foo +mycompany.myapplication.Bar +mycompany.myapplication.extra.FirstExtra +mycompany.myapplication.extra.SecondExtra +mycompany.util.FirstUtil +mycompany.util.SecondUtil +</pre> +<p> +Let's assume the class name <code>mycompany.myapplication.MyMain</code> is the +main application class that is kept by the configuration. All other class names +can be obfuscated. +<p> +By default, packages that contain classes that can't be renamed aren't renamed +either, and the package hierarchy is preserved. This results in obfuscated +class names like these: +<pre> +mycompany.myapplication.MyMain +mycompany.myapplication.a +mycompany.myapplication.b +mycompany.myapplication.a.a +mycompany.myapplication.a.b +mycompany.a.a +mycompany.a.b +</pre> +<p> +The <a +href="usage.html#flattenpackagehierarchy"><code>-flattenpackagehierarchy</code></a> +option obfuscates the package names further, by flattening the package +hierarchy of obfuscated packages: +<pre> +-flattenpackagehierarchy 'myobfuscated' +</pre> +<p> +The obfuscated class names then look as follows: +<pre> +mycompany.myapplication.MyMain +mycompany.myapplication.a +mycompany.myapplication.b +myobfuscated.a.a +myobfuscated.a.b +myobfuscated.b.a +myobfuscated.b.b +</pre> +<p> +Alternatively, the <a +href="usage.html#repackageclasses"><code>-repackageclasses</code></a> option +obfuscates the entire packaging, by combining obfuscated classes into a single +package: +<pre> +-repackageclasses 'myobfuscated' +</pre> +The obfuscated class names then look as follows: +<pre> +mycompany.myapplication.MyMain +mycompany.myapplication.a +mycompany.myapplication.b +myobfuscated.a +myobfuscated.b +myobfuscated.c +myobfuscated.d +</pre> +<p> +Additionally specifying the <a +href="usage.html#allowaccessmodification"><code>-allowaccessmodification</code></a> +option allows access permissions of classes and class members to +be broadened, opening up the opportunity to repackage all obfuscated classes: +<pre> +-repackageclasses 'myobfuscated' +-allowaccessmodification +</pre> +The obfuscated class names then look as follows: +<pre> +mycompany.myapplication.MyMain +myobfuscated.a +myobfuscated.b +myobfuscated.c +myobfuscated.d +myobfuscated.e +myobfuscated.f +</pre> +<p> +The specified target package can always be the root package. For instance: +<pre> +-repackageclasses '' +-allowaccessmodification +</pre> +The obfuscated class names are then the shortest possible names: +<pre> +mycompany.myapplication.MyMain +a +b +c +d +e +f +</pre> +<p> +Note that not all levels of obfuscation of package names may be acceptable for +all code. Notably, you may have to take into account that your application may +contain <a href="#resourcefiles">resource files</a> that have to be adapted. + +<h3><a name="logging">Removing logging code</a></h3> + +You can let ProGuard remove logging code. The trick is to specify that the +logging methods don't have side-effects — even though they actually do, +since they write to the console or to a log file. ProGuard will take your word +for it and remove the invocations (in the optimization step) and if possible +the logging classes and methods themselves (in the shrinking step). +<p> +For example, this configuration removes invocations of the Android logging +methods: +<pre> +-assumenosideeffects class android.util.Log { + public static boolean isLoggable(java.lang.String, int); + public static int v(...); + public static int i(...); + public static int w(...); + public static int d(...); + public static int e(...); +} +</pre> +<p> +The wildcards are a shortcut to match all versions of the methods. Be careful +not to use a <code>*</code> wildcard to match all methods, because it would +also match methods like <code>wait()</code>, higher up the hierarchy. Removing +those invocations will generally break your code. +<p> +Note that you generally can't remove logging code that uses +<code>System.out.println</code>, since you would be removing all invocations +of <code>java.io.PrintStream#println</code>, which could break your +application. You can work around it by creating your own logging methods and +let ProGuard remove those. + +<h3><a name="restructuring">Restructuring the output archives</a></h3> + +In simple applications, all output classes and resources files are merged into +a single jar. For example: +<pre> +-injars classes +-injars in1.jar +-injars in2.jar +-injars in3.jar +-outjars out.jar +</pre> +<p> +This configuration merges the processed versions of the files in the +<code>classes</code> directory and the three jars into a single output jar +<code>out.jar</code>. +<p> +If you want to preserve the structure of your input jars (and/or wars, ears, +zips, or directories), you can specify an output directory (or a war, an ear, +or a zip). For example: +<pre> +-injars in1.jar +-injars in2.jar +-injars in3.jar +-outjars out +</pre> +<p> +The input jars will then be reconstructed in the directory <code>out</code>, +with their original names. +<p> +You can also combine archives into higher level archives. For example: +<pre> +-injars in1.jar +-injars in2.jar +-injars in3.jar +-outjars out.war +</pre> +<p> +The other way around, you can flatten the archives inside higher level +archives into simple archives: +<pre> +-injars in.war +-outjars out.jar +</pre> +<p> +This configuration puts the processed contents of all jars inside +<code>in.war</code> (plus any other contents of <code>in.war</code>) into +<code>out.jar</code>. +<p> +If you want to combine input jars (and/or wars, ears, zips, or directories) +into output jars (and/or wars, ears, zips, or directories), you can group the +<a href="usage.html#injars"><code>-injars</code></a> and <a +href="usage.html#outjars"><code>-outjars</code></a> options. For example: +<pre> +-injars base_in1.jar +-injars base_in2.jar +-injars base_in3.jar +-outjars base_out.jar + +-injars extra_in.jar +-outjars extra_out.jar +</pre> +<p> +This configuration puts the processed results of all <code>base_in*.jar</code> +jars into <code>base_out.jar</code>, and the processed results of the +<code>extra_in.jar</code> into <code>extra_out.jar</code>. Note that only the +order of the options matters; the additional whitespace is just for clarity. +<p> +This grouping, archiving, and flattening can be arbitrarily complex. ProGuard +always tries to package output archives in a sensible way, reconstructing the +input entries as much as required. + +<h3><a name="filtering">Filtering the input and the output</a></h3> + +If you want even greater control, you can add +<a href="usage.html#filters">filters</a> to the input and the output, +filtering out zips, ears, wars, jars, and/or ordinary files. For example, if +you want to disregard certain files from an input jar: +<pre> +-injars in.jar(!images/**) +-outjars out.jar +</pre> +<p> +This configuration removes any files in the <code>images</code> directory and +its subdirectories. +<p> +Such filters can be convenient for avoiding warnings about duplicate files in +the output. For example, only keeping the manifest file from a first input jar: +<pre> +-injars in1.jar +-injars in2.jar(!META-INF/MANIFEST.MF) +-injars in3.jar(!META-INF/MANIFEST.MF) +-outjars out.jar +</pre> +<p> +Another useful application is speeding up the processing by ProGuard, by +disregarding a large number of irrelevant classes in the runtime library jar: +<pre> +-libraryjars <java.home>/lib/rt.jar(java/**,javax/**) +</pre> +<p> +The filter makes ProGuard disregard <code>com.sun.**</code> classes, for +instance , which don't affect the processing of ordinary applications. +<p> +It is also possible to filter the jars (and/or wars, ears, zips) themselves, +based on their names. For example: +<pre> +-injars in(**/acme_*.jar;) +-outjars out.jar +</pre> +<p> +Note the semi-colon in the filter; the filter in front of it applies to jar +names. In this case, only <code>acme_*.jar</code> jars are read from the +directory <code>in</code> and its subdirectories. Filters for war names, ear +names, and zip names can be prefixed with additional semi-colons. All types of +filters can be combined. They are orthogonal. +<p> +On the other hand, you can also filter the output, in order to control what +content goes where. For example: +<pre> +-injars in.jar +-outjars code_out.jar(**.class) +-outjars resources_out.jar +</pre> +<p> +This configuration splits the processed output, sending <code>**.class</code> +files to <code>code_out.jar</code>, and all remaining files to +<code>resources_out.jar</code>. +<p> +Again, the filtering can be arbitrarily complex, especially when combined with +grouping input and output. + +<h3><a name="multiple">Processing multiple applications at once</a></h3> + +You can process several dependent or independent applications (or applets, +midlets,...) in one go, in order to save time and effort. ProGuard's input and +output handling offers various ways to keep the output nicely structured. +<p> +The easiest way is to specify your input jars (and/or wars, ears, zips, and +directories) and a single output directory. ProGuard will then reconstruct the +input in this directory, using the original jar names. For example, showing +just the input and output options: +<pre> +-injars application1.jar +-injars application2.jar +-injars application3.jar +-outjars processed_applications +</pre> +<p> +After processing, the directory <code>processed_applications</code> will +contain processed versions of application jars, with their original names. + +<h3><a name="incremental">Incremental obfuscation</a></h3> + +After having <a href="#application">processed an application</a>, e.g. +ProGuard itself, you can still incrementally add other pieces of code that +depend on it, e.g. the ProGuard GUI: +<pre> +-injars proguardgui.jar +-outjars proguardgui_out.jar +-injars proguard.jar +-outjars proguard_out.jar +-libraryjars <java.home>/lib/rt.jar +-applymapping proguard.map + +-keep public class proguard.gui.ProGuardGUI { + public static void main(java.lang.String[]); +} +</pre> +<p> +We're reading both unprocessed jars as input. Their processed contents will go +to the respective output jars. The <a +href="usage.html#applymapping"><code>-applymapping</code></a> option then +makes sure the ProGuard part of the code gets the previously produced +obfuscation mapping. The final application will consist of the obfuscated +ProGuard jar and the additional obfuscated GUI jar. +<p> +The added code in this example is straightforward; it doesn't affect the +original code. The <code>proguard_out.jar</code> will be identical to the one +produced in the initial processing step. If you foresee adding more complex +extensions to your code, you should specify the options <a +href="usage.html#useuniqueclassmembernames"><code>-useuniqueclassmembernames</code></a>, +<a href="usage.html#dontshrink"><code>-dontshrink</code></a>, and <a +href="usage.html#dontoptimize"><code>-dontoptimize</code></a> <i>in the +original processing step</i>. These options ensure that the obfuscated base +jar will always remain usable without changes. You can then specify the base +jar as a library jar: +<pre> +-injars proguardgui.jar +-outjars proguardgui_out.jar +-libraryjars proguard.jar +-libraryjars <java.home>/lib/rt.jar +-applymapping proguard.map + +-keep public class proguard.gui.ProGuardGUI { + public static void main(java.lang.String[]); +} +</pre> + +<h3><a name="microedition">Preverifying class files for Java Micro Edition</a></h3> + +Even if you're not interested in shrinking, optimizing, and obfuscating your +midlets, as shown in the <a href="#midlets">midlets example</a>, you can still +use ProGuard to preverify the class files for Java Micro Edition. ProGuard +produces slightly more compact results than the traditional external +preverifier. +<pre> +-injars in.jar +-outjars out.jar +-libraryjars /usr/local/java/wtk2.5.2/lib/midpapi20.jar +-libraryjars /usr/local/java/wtk2.5.2/lib/cldcapi11.jar + +-dontshrink +-dontoptimize +-dontobfuscate + +-microedition +</pre> +<p> +We're not processing the input, just making sure the class files are +preverified by targeting them at Java Micro Edition with the <a +href="usage.html#microedition"><code>-microedition</code></a> option. Note +that we don't need any <code>-keep</code> options to specify entry points; all +class files are simply preverified. + +<h3><a name="upgrade">Upgrading class files to Java 6</a></h3> + +The following options upgrade class files to Java 6, by updating their +internal version numbers and preverifying them. The class files can then be +loaded more efficiently by the Java 6 Virtual Machine. +<pre> +-injars in.jar +-outjars out.jar +-libraryjars <java.home>/lib/rt.jar + +-dontshrink +-dontoptimize +-dontobfuscate + +-target 1.6 +</pre> +<p> +We're not processing the input, just retargeting the class files with the <a +href="usage.html#target"><code>-target</code></a> option. They will +automatically be preverified for Java 6 as a result. Note that we don't need +any <code>-keep</code> options to specify entry points; all class files are +simply updated and preverified. + +<h3><a name="deadcode">Finding dead code</a></h3> + +These options list unused classes, fields, and methods in the application +<code>mypackage.MyApplication</code>: +<pre> +-injars in.jar +-libraryjars <java.home>/lib/rt.jar + +-dontoptimize +-dontobfuscate +-dontpreverify +-printusage + +-keep public class mypackage.MyApplication { + public static void main(java.lang.String[]); +} +</pre> +<p> +We're not specifying an output jar, just printing out some results. We're +saving some processing time by skipping the other processing steps. +<p> +The java compiler inlines primitive constants and String constants +(<code>static final</code> fields). ProGuard would therefore list such fields +as not being used in the class files that it analyzes, even if they <i>are</i> +used in the source files. We can add a <a +href="usage.html#keepclassmembers"><code>-keepclassmembers</code></a> option +that keeps those fields a priori, in order to avoid having them listed: +<pre> +-keepclassmembers class * { + static final % *; + static final java.lang.String *; +} +</pre> + +<h3><a name="structure">Printing out the internal structure of class files</a></h3> + +These options print out the internal structure of all class files in the input +jar: +<pre> +-injars in.jar + +-dontshrink +-dontoptimize +-dontobfuscate +-dontpreverify + +-dump +</pre> +<p> +Note how we don't need to specify the Java run-time jar, because we're not +processing the input jar at all. + +<h3><a name="annotated">Using annotations to configure ProGuard</a></h3> + +The traditional ProGuard configuration allows to keep a clean separation +between the code and the configuration for shrinking, optimization, and +obfuscation. However, it is also possible to define specific annotations, +and then annotate the code to configure the processing. +<p> +You can find a set of such predefined annotations in the directory +<code>examples/annotations/lib</code> in the ProGuard distribution. +The annotation classes are defined in <code>annotations.jar</code>. The +corresponding ProGuard configuration (or meta-configuration, if you prefer) +is specified in <code>annotations.pro</code>. With these files, you can start +annotating your code. For instance, a java source file +<code>Application.java</code> can be annotated as follows: +<pre> +@KeepApplication +public class Application { + .... +} +</pre> +<p> +The ProGuard configuration file for the application can then be simplified by +leveraging off these annotations: +<pre> +-injars in.jar +-outjars out.jar +-libraryjars <java.home>/lib/rt.jar + +-include lib/annotations.pro +</pre> +<p> +The annotations are effectively replacing the application-dependent +<code>-keep</code> options. You may still wish to add traditional +<code>-keep</code> options for processing <a href="#native">native +methods</a>, <a href="#enumerations">enumerations</a>, <a +href="#serializable">serializable classes</a>, and <a +href="#annotations">annotations</a>. +<p> +The directory <code>examples/annotations</code> contains more examples that +illustrate some of the possibilities. + +<hr /> +<address> +Copyright © 2002-2017 +<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.guardsquare.com/">GuardSquare</a>. +</address> +</body> +</html> diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/gradle.html b/third_party/java/proguard/proguard5.3.3/docs/manual/gradle.html new file mode 100644 index 0000000000..55b00027af --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/gradle.html @@ -0,0 +1,561 @@ +<!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>Gradle Task</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/gradle.html">ProGuard index</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> <a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>') +//--> +</script> +<noscript> +<a class="largebutton" target="_top" href="../index.html#manual/gradle.html">ProGuard index</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> +<a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a> +</noscript> + +<h2>Gradle Task</h2> + +<b>ProGuard</b> can be run as a task in the Java-based build tool Gradle +(version 2.1 or higher). +<p> + +Before you can use the <code>proguard</code> task, you have to make sure +Gradle can find it in its class path at build time. One way is to add the +following line to your <code>build.gradle</code> file: +<p> + +<pre> +buildscript { + repositories { + flatDir dirs: '/usr/local/java/proguard/lib' + } + dependencies { + classpath ':proguard:' + } +} +</pre> +<p> + +Please make sure the class path is set correctly for your system. +<p> + +You can then define a task: +<p> +<pre> +task myProguardTask(type: proguard.gradle.ProGuardTask) { + ..... +} +</pre> +<p> + +The embedded configuration is much like a standard ProGuard configuration. +Notable similarities and differences: +<ul> +<li>Like in ProGuard-style configurations, we're using all lower-case names + for the settings.</li> +<li>The options don't have a dash as prefix.</li> +<li>Arguments typically have quotes.</li> +<li>Some settings are specified as named arguments.</li> +</ul> +<p> +You can find some sample build files in the <code>examples/gradle</code> +directory of the ProGuard distribution. +<p> +If you prefer a more verbose configuration derived from the Ant task, you can +import the Ant task as a <a href="#anttask">Gradle task</a>. + +<h2><a name="proguard">Settings</a></h2> + +The ProGuard task supports the following settings in its closure: + +<dl> + +<dt><a name="configuration_attribute"><code><b>configuration</b></code></a> + <a href="#file"><i>files</i></a></dt> +<dd>Read and merge options from the given ProGuard-style configuration + files. The files are resolved and parsed lazily, during the execution + phase.</dd> + +<dt><a href="usage.html#injars"><code><b>injars</b></code></a> + <a href="#classpath"><i>class_path</i></a></dt> +<dd>Specifies the program jars (or aars, wars, ears, zips, apks, or + directories). The files are resolved and read lazily, during the execution + phase.</dd> + +<dt><a href="usage.html#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 files are resolved and written lazily, during the + execution phase.</dd> + +<dt><a href="usage.html#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). The files are resolved and read lazily, during the execution + phase.</dd> + +<dt><a href="usage.html#skipnonpubliclibraryclasses"><code><b>skipnonpubliclibraryclasses</b></code></a></dt> +<dd>Ignore non-public library classes.</dd> + +<dt><a href="usage.html#dontskipnonpubliclibraryclassmembers"><code><b>dontskipnonpubliclibraryclassmembers</b></code></a></dt> +<dd>Don't ignore package visible library class members.</dd> + +<dt><a href="usage.html#keepdirectories"><code><b>keepdirectories</b></code></a> + ['<a href="usage.html#filefilters"><i>directory_filter</i></a>']</dt> +<dd>Keep the specified directories in the output jars (or aars, wars, ears, + zips, apks, or directories).</dd> + +<dt><a href="usage.html#target"><code><b>target</b></code></a> + '<i>version</i>'</dt> +<dd>Set the given version number in the processed classes.</dd> + +<dt><a href="usage.html#forceprocessing"><code><b>forceprocessing</b></code></a></dt> +<dd>Process the input, even if the output seems up to date.</dd> + +<dt><a href="usage.html#keep"><code><b>keep</b></code></a> + [<a href="#keepmodifier"><i>modifier</i>,...</a>] + <a href="#classspecification"><i>class_specification</i></a></dt> +<dd>Preserve the specified classes <i>and</i> class members.</dd> + +<dt><a href="usage.html#keepclassmembers"><code><b>keepclassmembers</b></code></a> + [<a href="#keepmodifier"><i>modifier</i>,...</a>] + <a href="#classspecification"><i>class_specification</i></a></dt> +<dd>Preserve the specified class members, if their classes are preserved as + well.</dd> + +<dt><a href="usage.html#keepclasseswithmembers"><code><b>keepclasseswithmembers</b></code></a> + [<a href="#keepmodifier"><i>modifier</i>,...</a>] + <a href="#classspecification"><i>class_specification</i></a></dt> +<dd>Preserve the specified classes <i>and</i> class members, if all of the + specified class members are present.</dd> + +<dt><a href="usage.html#keepnames"><code><b>keepnames</b></code></a> + <a href="#classspecification"><i>class_specification</i></a></dt> +<dd>Preserve the names of the specified classes <i>and</i> class members (if + they aren't removed in the shrinking step).</dd> + +<dt><a href="usage.html#keepclassmembernames"><code><b>keepclassmembernames</b></code></a> + <a href="#classspecification"><i>class_specification</i></a></dt> +<dd>Preserve the names of the specified class members (if they aren't removed + in the shrinking step).</dd> + +<dt><a href="usage.html#keepclasseswithmembernames"><code><b>keepclasseswithmembernames</b></code></a> + <a href="#classspecification"><i>class_specification</i></a></dt> +<dd>Preserve the names of the specified classes <i>and</i> class members, if + all of the specified class members are present (after the shrinking + step).</dd> + +<dt><a href="usage.html#printseeds"><code><b>printseeds</b></code></a> + [<a href="#file"><i>file</i></a>]</dt> +<dd>List classes and class members matched by the various <code>keep</code> + commands, to the standard output or to the given file.</dd> + +<dt><a href="usage.html#dontshrink"><code><b>dontshrink</b></code></a></dt> +<dd>Don't shrink the input class files.</dd> + +<dt><a href="usage.html#printusage"><code><b>printusage</b></code></a> + [<a href="#file"><i>file</i></a>]</dt> +<dd>List dead code of the input class files, to the standard output or to the + given file.</dd> + +<dt><a href="usage.html#whyareyoukeeping"><code><b>whyareyoukeeping</b></code></a> + <a href="#classspecification"><i>class_specification</i></a></dt> +<dd>Print details on why the given classes and class members are being kept in + the shrinking step.</dd> + +<dt><a href="usage.html#dontoptimize"><code><b>dontoptimize</b></code></a></dt> +<dd>Don't optimize the input class files.</dd> + +<dt><a href="usage.html#optimizations"><code><b>optimizations</b></code></a> '<a href="optimizations.html"><i>optimization_filter</i></a>'</dt> +<dd>Perform only the specified optimizations.</dd> + +<dt><a href="usage.html#optimizationpasses"><code><b>optimizationpasses</b></code></a> + <i>n</i></dt> +<dd>The number of optimization passes to be performed.</dd> + +<dt><a href="usage.html#assumenosideeffects"><code><b>assumenosideeffects</b></code></a> + <a href="#classspecification"><i>class_specification</i></a></dt> +<dd>Assume that the specified methods don't have any side effects, while + optimizing. <i>Only use this option if you know what you're + doing!</i></dd> + +<dt><a href="usage.html#allowaccessmodification"><code><b>allowaccessmodification</b></code></a></dt> +<dd>Allow the access modifiers of classes and class members to be modified, + while optimizing.</dd> + +<dt><a href="usage.html#mergeinterfacesaggressively"><code><b>mergeinterfacesaggressively</b></code></a></dt> +<dd>Allow any interfaces to be merged, while optimizing.</dd> + +<dt><a href="usage.html#dontobfuscate"><code><b>dontobfuscate</b></code></a></dt> +<dd>Don't obfuscate the input class files.</dd> + +<dt><a href="usage.html#printmapping"><code><b>printmapping</b></code></a> + [<a href="#file"><i>file</i></a>]</dt> +<dd>Print the mapping from old names to new names for classes and class members + that have been renamed, to the standard output or to the given file.</dd> + +<dt><a href="usage.html#applymapping"><code><b>applymapping</b></code></a> + <a href="#file"><i>file</i></a></dt> +<dd>Reuse the given mapping, for incremental obfuscation.</dd> + +<dt><a href="usage.html#obfuscationdictionary"><code><b>obfuscationdictionary</b></code></a> + <a href="#file"><i>file</i></a></dt> +<dd>Use the words in the given text file as obfuscated field names and method + names.</dd> + +<dt><a href="usage.html#classobfuscationdictionary"><code><b>classobfuscationdictionary</b></code></a> + <a href="#file"><i>file</i></a></dt> +<dd>Use the words in the given text file as obfuscated class names.</dd> + +<dt><a href="usage.html#packageobfuscationdictionary"><code><b>packageobfuscationdictionary</b></code></a> + <a href="#file"><i>file</i></a></dt> +<dd>Use the words in the given text file as obfuscated package names.</dd> + +<dt><a href="usage.html#overloadaggressively"><code><b>overloadaggressively</b></code></a></dt> +<dd>Apply aggressive overloading while obfuscating.</dd> + +<dt><a href="usage.html#useuniqueclassmembernames"><code><b>useuniqueclassmembernames</b></code></a></dt> +<dd>Ensure uniform obfuscated class member names for subsequent incremental + obfuscation.</dd> + +<dt><a href="usage.html#dontusemixedcaseclassnames"><code><b>dontusemixedcaseclassnames</b></code></a></dt> +<dd>Don't generate mixed-case class names while obfuscating.</dd> + +<dt><a href="usage.html#keeppackagenames"><code><b>keeppackagenames</b></code></a> ['<a href="usage.html#filters"><i>package_filter</i></a>']</dt> +<dd>Keep the specified package names from being obfuscated. If no name is + given, all package names are preserved.</dd> + +<dt><a href="usage.html#flattenpackagehierarchy"><code><b>flattenpackagehierarchy</b></code></a> + '<i>package_name</i>'</dt> +<dd>Repackage all packages that are renamed into the single given parent + package.</dd> + +<dt><a href="usage.html#repackageclasses"><code><b>repackageclasses</b></code></a> + ['<i>package_name</i>']</dt> +<dd>Repackage all class files that are renamed into the single given + package.</dd> + +<dt><a href="usage.html#keepattributes"><code><b>keepattributes</b></code></a> ['<a href="usage.html#filters"><i>attribute_filter</i></a>']</dt> +<dd>Preserve the specified optional Java bytecode attributes, with optional + wildcards. If no name is given, all attributes are preserved.</dd> + +<dt><a href="usage.html#keepparameternames"><code><b>keepparameternames</b></code></a></dt> +<dd>Keep the parameter names and types of methods that are kept.</dd> + +<dt><a href="usage.html#renamesourcefileattribute"><code><b>renamesourcefileattribute</b></code></a> + ['<i>string</i>']</dt> +<dd>Put the given constant string in the <code>SourceFile</code> + attributes.</dd> + +<dt><a href="usage.html#adaptclassstrings"><code><b>adaptclassstrings</b></code></a> + ['<a href="usage.html#filters"><i>class_filter</i></a>']</dt> +<dd>Adapt string constants in the specified classes, based on the obfuscated + names of any corresponding classes.</dd> + +<dt><a href="usage.html#adaptresourcefilenames"><code><b>adaptresourcefilenames</b></code></a> + ['<a href="usage.html#filefilters"><i>file_filter</i></a>']</dt> +<dd>Rename the specified resource files, based on the obfuscated names of the + corresponding class files.</dd> + +<dt><a href="usage.html#adaptresourcefilecontents"><code><b>adaptresourcefilecontents</b></code></a> + ['<a href="usage.html#filefilters"><i>file_filter</i></a>']</dt> +<dd>Update the contents of the specified resource files, based on the + obfuscated names of the processed classes.</dd> + +<dt><a href="usage.html#dontpreverify"><code><b>dontpreverify</b></code></a></dt> +<dd>Don't preverify the processed class files if they are targeted at Java Micro + Edition or at Java 6 or higher.</dd> + +<dt><a href="usage.html#microedition"><code><b>microedition</b></code></a></dt> +<dd>Target the processed class files at Java Micro Edition.</dd> + +<dt><a href="usage.html#verbose"><code><b>verbose</b></code></a></dt> +<dd>Write out some more information during processing.</dd> + +<dt><a href="usage.html#dontnote"><code><b>dontnote</b></code></a> '<a href="usage.html#filters"><i>class_filter</i></a>'</dt> +<dd>Don't print notes about classes matching the specified class name + filter.</dd> + +<dt><a href="usage.html#dontwarn"><code><b>dontwarn</b></code></a> '<a href="usage.html#filters"><i>class_filter</i></a>'</dt> +<dd>Don't print warnings about classes matching the specified class name + filter. <i>Only use this option if you know what you're doing!</i></dd> + +<dt><a href="usage.html#ignorewarnings"><code><b>ignorewarnings</b></code></a></dt> +<dd>Print warnings about unresolved references, but continue processing + anyhow. <i>Only use this option if you know what you're doing!</i></dd> + +<dt><a href="usage.html#printconfiguration"><code><b>printconfiguration</b></code></a> + [<a href="#file"><i>file</i></a>]</dt> +<dd>Write out the entire configuration in traditional ProGuard style, to the + standard output or to the given file. Useful to replace unreadable + XML configurations.</dd> + +<dt><a href="usage.html#dump"><code><b>dump</b></code></a> + [<a href="#file"><i>file</i></a>]</dt> +<dd>Write out the internal structure of the processed class files, to the + standard output or to the given file.</dd> + +</dl> + +<h2><a name="classpath">Class Paths</a></h2> + +Class paths are specified as Gradle file collections, which means they can be +specified as simple strings, with <code>files(Object)</code>, etc. +<p> +In addition, they can have ProGuard-style filters, specified as +comma-separated named arguments after the file: + +<dl> + +<dt><code><b>filter:</b></code> + '<a href="usage.html#filefilters"><i>file_filter</i></a>'</dt> +<dd>An optional filter for all class file names and resource file names that + are encountered.</dd> + +<dt><code><b>apkfilter:</b></code> + '<a href="usage.html#filefilters"><i>file_filter</i></a>'</dt> +<dd>An optional filter for all apk names that are encountered.</dd> + +<dt><code><b>jarfilter:</b></code> + '<a href="usage.html#filefilters"><i>file_filter</i></a>'</dt> +<dd>An optional filter for all jar names that are encountered.</dd> + +<dt><code><b>aarfilter:</b></code> + '<a href="usage.html#filefilters"><i>file_filter</i></a>'</dt> +<dd>An optional filter for all aar names that are encountered.</dd> + +<dt><code><b>warfilter:</b></code> + '<a href="usage.html#filefilters"><i>file_filter</i></a>'</dt> +<dd>An optional filter for all war names that are encountered.</dd> + +<dt><code><b>earfilter:</b></code> + '<a href="usage.html#filefilters"><i>file_filter</i></a>'</dt> +<dd>An optional filter for all ear names that are encountered.</dd> + +<dt><code><b>zipfilter:</b></code> + '<a href="usage.html#filefilters"><i>file_filter</i></a>'</dt> +<dd>An optional filter for all zip names that are encountered.</dd> + +</dl> + +<h2><a name="file">Files</a></h2> + +Files are specified as Gradle files, which means they can be specified +as simple strings, as File instances, with <code>file(Object)</code>, etc. +<p> +In Gradle, file names (any strings really) in double quotes can contain +properties or code inside <code>${...}</code>. These are automatically +expanded. +<p> +For example, <code>"${System.getProperty('java.home')}/lib/rt.jar"</code> is +expanded to something like <code>'/usr/local/java/jdk/jre/lib/rt.jar'</code>. +Similarly, <code>System.getProperty('user.home')</code> is expanded to the +user's home directory, and <code>System.getProperty('user.dir')</code> is +expanded to the current working directory. + +<h2><a name="keepmodifier">Keep Modifiers</a></h2> + +The keep settings can have the following named arguments that modify their +behaviors: + +<dl> + +<dt><a href="usage.html#includedescriptorclasses"><code><b>includedescriptorclasses:</b></code></a> + <i>boolean</i> + (default = false)</dt> +<dd>Specifies whether the classes of the fields and methods specified in the + keep tag must be kept as well.</dd> + +<dt><a href="usage.html#allowshrinking"><code><b>allowshrinking:</b></code></a> + <i>boolean</i> + (default = false)</dt> +<dd>Specifies whether the entry points specified in the keep tag may be + shrunk.</dd> + +<dt><a href="usage.html#allowoptimization"><code><b>allowoptimization:</b></code></a> + <i>boolean</i> + (default = false)</dt> +<dd>Specifies whether the entry points specified in the keep tag may be + optimized.</dd> + +<dt><a href="usage.html#allowobfuscation"><code><b>allowobfuscation:</b></code></a> + <i>boolean</i> + (default = false)</dt> +<dd>Specifies whether the entry points specified in the keep tag may be + obfuscated.</dd> + +</dl> + +Names arguments are comma-separated, as usual. + +<h2><a name="classspecification">Class Specifications</a></h2> + +A class specification is a template of classes and class members (fields and methods). There are two alternative ways to specify such a template: + +<ol> +<li>As a string containing a ProGuard-style class specification. This is the + most compact and most readable way. The specification looks like a Java + declaration of a class with fields and methods. For example: +<pre> +keep 'public class mypackage.MyMainClass { \ + public static void main(java.lang.String[]); \ +}' +</pre></li> +<li>As a Gradle-style setting: a method calls with named arguments and a + closure. This is more verbose, but it might be useful for programmatic + specifications. For example: +<pre> +keep access: 'public', + name: 'mypackage.MyMainClass', { + method access: 'public static', + type: 'void', + name: 'main', + parameters: 'java.lang.String[]' +} +</pre></li> +</ol> +<p> + +The <a href="usage.html#classspecification">ProGuard-style class +specification</a> is described on the traditional Usage page. +<p> +A Gradle-style class specification can have the following named arguments: + +<dl> + +<dt><code><b>access:</b></code> '<i>access_modifiers</i>'</dt> +<dd>The optional access modifiers of the class. Any space-separated list of + "public", "final", and "abstract", with optional negators "!".</dd> + +<dt><code><b>annotation:</b></code> '<i>annotation_name</i>'</dt> +<dd>The optional fully qualified name of an annotation of the class, with + optional wildcards.</dd> + +<dt><code><b>type:</b></code> '<i>type</i>'</dt> +<dd>The optional type of the class: one of "class", "interface", or + "!interface".</dd> + +<dt><code><b>name:</b></code> '<i>class_name</i>'</dt> +<dd>The optional fully qualified name of the class, with optional + wildcards.</dd> + +<dt><code><b>extendsannotation:</b></code> '<i>annotation_name</i>'</dt> +<dd>The optional fully qualified name of an annotation of the the class that + the specified classes must extend, with optional wildcards.</dd> + +<dt><code><b>'extends':</b></code> '<i>class_name</i>'</dt> +<dd>The optional fully qualified name of the class the specified classes + must extend, with optional wildcards.</dd> + +<dt><code><b>'implements':</b></code> '<i>class_name</i>'</dt> +<dd>The optional fully qualified name of the class the specified classes + must implement, with optional wildcards.</dd> + +</dl> + +The named arguments are optional. Without any arguments, there are no +constraints, so the settings match all classes. +<p> + +<h3><a name="classmemberspecification">Gradle-style Class Member Specifications</a></h3> + +The closure of a Gradle-style class specification can specify class members +with these settings: + +<dl> + +<dt><code><b>field</b></code> <i>field_constraints</i></dt> +<dd>Specifies a field.</dd> + +<dt><code><b>method</b></code> <i>method_constraints</i></dt> +<dd>Specifies a method.</dd> + +<dt><code><b>constructor</b></code> <i>constructor_constraints</i></dt> +<dd>Specifies a constructor.</dd> + +</dl> + +A class member setting can have the following named arguments to express +constraints: + +<dl> + +<dt><code><b>access:</b></code> '<i>access_modifiers</i>'</dt> +<dd>The optional access modifiers of the class. Any space-separated list of + "public", "protected", "private", "static", etc., with optional negators + "!".</dd> + +<dt><code><b>'annotation':</b></code> '<i>annotation_name</i>'</dt> +<dd>The optional fully qualified name of an annotation of the class member, + with optional wildcards.</dd> + +<dt><code><b>type:</b></code> '<i>type</i>'</dt> +<dd>The optional fully qualified type of the class member, with optional + wildcards. Not applicable for constructors, but required for methods for + which the <code>parameters</code> argument is specified.</dd> + +<dt><code><b>name:</b></code> '<i>name</i>'</dt> +<dd>The optional name of the class member, with optional wildcards. Not + applicable for constructors.</dd> + +<dt><code><b>parameters:</b></code> '<i>parameters</i>'</dt> +<dd>The optional comma-separated list of fully qualified method parameters, + with optional wildcards. Not applicable for fields, but required for + constructors, and for methods for which the <code>type</code> argument is + specified.</dd> + +</dl> + +The named arguments are optional. Without any arguments, there are no +constraints, so the settings match all constructors, fields, or methods. +<p> +A class member setting doesn't have a closure. + +<h2><a name="anttask">Alternative: imported Ant task</a></h2> + +Instead of using the Gradle task, you could also integrate the Ant task in +your Gradle build file: +<p> +<pre> +ant.project.basedir = '../..' + +ant.taskdef(resource: 'proguard/ant/task.properties', + classpath: '/usr/local/java/proguard/lib/proguard.jar') +</pre> +<p> + +Gradle automatically converts the elements and attributes to Groovy methods, +so converting the configuration is essentially mechanical. The one-on-one +mapping can be useful, but the resulting configuration is more verbose. For +instance: +<pre> +task proguard << { + ant.proguard(printmapping: 'proguard.map', + overloadaggressively: 'on', + repackageclasses: '', + renamesourcefileattribute: 'SourceFile') { + + injar(file: 'application.jar') + injar(file: 'gui.jar', filter: '!META-INF/**') + + ..... + } +} +</pre> +<p> + +<hr /> +<address> +Copyright © 2002-2017 +<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.guardsquare.com/">GuardSquare</a>. +</address> +</body> +</html> diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/gui.html b/third_party/java/proguard/proguard5.3.3/docs/manual/gui.html new file mode 100644 index 0000000000..3831370dae --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/gui.html @@ -0,0 +1,483 @@ +<!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 GUI</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/gui.html">ProGuard index</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> <a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>') +//--> +</script> +<noscript> +<a class="largebutton" target="_top" href="../index.html#manual/gui.html">ProGuard index</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> +<a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a> +</noscript> + +<h2>Graphical User Interface</h2> + +You can find the ProGuard GUI jar in the <code>lib</code> directory of the +ProGuard distribution. To run the ProGuard graphical user interface, just type: +<p class="code"> +<code><b>java -jar proguardgui.jar</b> [-nosplash] </code>[<i>configuration_file</i>] +</p> +Alternatively, the <code>bin</code> directory contains some short Linux and +Windows scripts containing this command. The GUI will pop up in a window. With +the <code>-nosplash</code> option, you can switch off the short opening +animation. If you have specified a ProGuard configuration file, it will be +loaded. The GUI works like a wizard. You can edit the configuration and +execute ProGuard through a few tabs: +<p> + +<table cellspacing="5" cellpadding="5"> +<tr><td class="button"><a href="#proguard">ProGuard</a></td> + <td>Optionally load an existing configuration file.</td></tr> +<tr><td class="button"><a href="#inputoutput">Input/Output</a></td> + <td>Specify the program jars and library jars.</td></tr> +<tr><td class="button"><a href="#shrinking">Shrinking</a></td> + <td>Specify the shrinking options.</td></tr> +<tr><td class="button"><a href="#obfuscation">Obfuscation</a></td> + <td>Specify the obfuscation options.</td></tr> +<tr><td class="button"><a href="#optimization">Optimization</a></td> + <td>Specify the optimization options.</td></tr> +<tr><td class="button"><a href="#information">Information</a></td> + <td>Specify some options to get information.</td></tr> +<tr><td class="button"><a href="#process">Process</a></td> + <td>View and save the resulting configuration, and run ProGuard.</td></tr> +</table> +<p> + +In addition, there is a tab to execute ReTrace interactively: +<p> + +<table cellspacing="5" cellpadding="5"> +<tr><td class="button"><a href="#retrace">ReTrace</a></td> + <td>Set up and run ReTrace, to de-obfuscate stack traces.</td></tr> +</table> +<p> + +You can freely toggle between the tabs by means of the buttons on the +left-hand side of the window, or by means of the <b>Previous</b> and +<b>Next</b> buttons at the bottom of the tabs. Tool tips briefly explain the +purpose of the numerous options and text fields, although a basic +understanding of the shrinking/optimization/obfuscation/preverification +process is assumed. Please refer to the <a +href="introduction.html">Introduction</a> of this manual. +<p> + +<h2><a name="proguard">The ProGuard Tab</a></h2> + +The <i>ProGuard</i> tab presents a welcome message and one important button at +the bottom: +<p> + +<table cellspacing="5" cellpadding="5"> +<tr><td class="button">Load configuration...</td> + <td>opens a file chooser to load an existing ProGuard configuration + file.</td></tr> +</table> +<p> + +If you don't want to load an existing configuration, you can just continue +creating a new configuration from scratch. +<p> + +<h2><a name="inputoutput">The Input/Output Tab</a></h2> + +The <i>Input/Output</i> tab contains two lists, respectively to specify the +program jars (or aars, wars, ears, zips, apks, or directories), and the +library jars (or aars, wars, ears, zips, apks, or directories). + +<ul> +<li>The list of program jars contains input entries and output entries. Input + entries contain the class files and resource files to be processed. Output + entries specify the destinations to which the processed results will be + written. They are preceded by arrows, to distinguish them from input + entries. The results of each consecutive list of input entries will be + written to the subsequent consecutive list of output entries.</li> + +<li>The library jars are not copied to the output jars; they contain class + files that are used by class files in the program jars and that are + necessary for correct processing. This list typically at least contains the + targeted Java runtime jar.</li> +</ul> +<p> + +Each of these lists can be edited by means of a couple of buttons on the +right-hand side: +<p> + +<table cellspacing="5" cellpadding="5"> +<tr><td class="button">Add input...</td> <td>opens a file chooser to add an + input entry to the list of program jars.</td></tr> +<tr><td class="button">Add output...</td> <td>opens a file chooser to add an + output entry to the list of program jars.</td></tr> +<tr><td class="button">Add...</td> + <td>opens a file chooser to add an entry to the list of library + jars.</td></tr> +<tr><td class="button">Edit...</td> + <td>opens a file chooser to edit the selected entry in the list.</td></tr> +<tr><td class="button">Filter...</td> + <td>opens a text entry field to add or edit the filters of the selected + entries in the list.</td></tr> +<tr><td class="button">Remove</td> + <td>removes the selected entries from the list.</td></tr> +<tr><td class="button">Move up</td> + <td>moves the selected entries one position up the list.</td></tr> +<tr><td class="button">Move down</td> + <td>moves the selected entries one position down the list.</td></tr> +<tr><td class="button">Move to libraries</td> + <td>moves the selected entries in the list of program jars to the list of + library jars.</td></tr> +<tr><td class="button">Move to program</td> + <td>moves the selected entries in the list of library jars to the list of + program jars.</td></tr> +</table> +<p> + +Filters allow to filter files based on their names. You can specify filters +for class file names and resource file names, for jar file names, for aar file +names, for war file names, for ear file names, for zip file names, and for +apk file names. Multiple entries in the program list only make sense when +combined with filters; each output file is written to the first entry with a +matching filter. +<p> + +Input entries that are currently not readable are colored red. +<p> + +The order of the entries in each list may matter, as the first occurrence of +any duplicate entries gets precedence, just as in conventional class paths. +<p> + +Corresponding configuration options: +<ul type="none"> +<li>-<a href="usage.html#injars">injars</a></li> +<li>-<a href="usage.html#outjars">outjars</a></li> +<li>-<a href="usage.html#libraryjars">libraryjars</a></li> +<li><a href="usage.html#classpath"><i>class_path</i></a></li> +<li><a href="usage.html#filters"><i>filters</i></a></li> +</ul> +<p> + +<h2><a name="shrinking">The Shrinking Tab</a></h2> + +The <i>Shrinking</i> tab presents a number of options that affect the +shrinking step. The basic options are followed by a few lists of classes and +class members (fields and methods) that must be protected from shrinking (and +implicitly from obfuscation as well). +<p> + +The fixed lists contain predefined entries that are typically useful for many +applications. Each of these entries can be toggled by means of a check box. +The text field following each entry allows to constrain the applicable classes +by means of a comma-separated list of wildcarded, fully-qualified class +names. The default is "*", which means that all input classes of the +corresponding type are considered. +<p> + +For example, checking the <b>Applications</b> entry and filling in +"myapplications.**" after it would mean: keep all classes that have main +methods in the "myapplications" package and all of its subpackages. +<p> + +The variable list at the bottom allows to define additional entries +yourself. The list can be edited by means of a couple of buttons on the +right-hand side: +<p> + +<table cellspacing="5" cellpadding="5"> +<tr><td class="button">Add...</td> + <td>opens a window to add a new entry to the list.</td></tr> +<tr><td class="button">Edit...</td> + <td>opens a window to edit the selected entry in the list.</td></tr> +<tr><td class="button">Remove</td> + <td>removes the selected entries from the list.</td></tr> +<tr><td class="button">Move up</td> + <td>moves the selected entries one position up the list.</td></tr> +<tr><td class="button">Move down</td> + <td>moves the selected entries one position down the list.</td></tr> +</table> +<p> + +The interface windows allow to specify classes, fields, and methods. They +contain text fields and check boxes to constrain these items. They have +<b>Ok</b> and <b>Cancel</b> buttons to apply or to cancel the operation. +<p> + +For example, your application may be creating some classes dynamically using +<code>Class.forName</code>. You should then specify them here, so they are kept +by their original names. Press the <b>Add...</b> button to open the class +window. Fill out the fully-qualified class name in the <b>Code</b> text field, +and press the <b>Ok</b> button. Repeat this for all required classes. Wildcards +can be helpful to specify a large number of related classes in one go. If you +want to specify all implementations of a certain interface, fill out the +fully qualified interface name in the <b>Extends/implements class</b> instead. +<p> + +For more advanced settings, it is advisable to become familiar with ProGuard's +configuration options through the <a href="usage.html">Usage section</a> and +the <a href="examples.html">Examples section</a>. We'll suffice with a brief +overview of the three dialogs provided by the GUI. +<p> + +The <i>keep class</i> dialog appears when adding or editing new special keep +entries. It has text fields and selections for specifying and constraining +classes and class members to keep. The <b>Advanced options</b> / <b>Basic +options</b> button at the bottom of the dialog allows to toggle showing the +advanced options. + +<ul> +<li>The <b>Comments</b> text field allows to add optional comments to this + entry. The comments will identify the entry in the list and they will + appear as comments in the configuration file.</li> + +<li>The <b>Keep</b> selection allows to specify whether you want to protect + the specified classes and their specified class members, or just the + specified class members from the specified classes, or the specified + classes and the specified class members, if the class members are present. + Note that class members will only be protected if they are explicitly + specified, even if only by means of a wildcard.</li> + +<li>The <b>Allow</b> selection allows to specify whether you want to allow the + the specified classes and their specified class members to be shrunk, + optimized and/or obfuscated.</li> + +<li>The <b>Access</b> selections allows to specify constraints on the class or + classes, based on their access modifiers.</li> + +<li>The <b>Annotation</b> text field takes the fully-qualified name of an + annotation that is required for matching classes. The annotation name can + contain wildcards. This is an advanced option for defining <i>keep</i> + annotations.</li> + +<li>The <b>Class</b> text field takes the fully-qualified name of the class or + classes. The class name can contain wildcards.</li> + +<li>The <b>Annotation</b> text field takes the fully-qualified name of an + annotation that is required for the class or interface that the above + class must extend. The annotation name can contain wildcards. This is an + advanced option for defining <i>keep</i> annotations.</li> + +<li>The <b>Extends/implements class</b> text field takes the fully-qualified + name of the class or interface that the above classes must extend.</li> + +<li>The <b>Class members</b> list allows to specify a list of fields and + methods to keep. It can be edited by means of a list of buttons on the + right-hand side.</li> +</ul> +<p> + +The <i>keep field</i> dialog appears when adding or editing fields within the +above dialog. It has text fields and selections for specifying and +constraining fields to keep. Again, the <b>Advanced options</b> / <b>Basic +options</b> button at the bottom of the dialog allows to toggle showing the +advanced options. + +<ul> +<li>The <b>Access</b> selections allows to specify constraints on the field or + fields, based on their access modifiers.</li> + +<li>The <b>Annotation</b> text field takes the fully-qualified name of an + annotation that is required for matching fields. The annotation name can + contain wildcards. This is an advanced option for defining <i>keep</i> + annotations.</li> + +<li>The <b>Return type</b> text field takes the fully-qualified type of the + field or fields. The type can contain wildcards.</li> + +<li>The <b>Name</b> text field takes the name of the field or fields. The field + name can contain wildcards.</li> +</ul> +<p> + +Similarly, the <i>keep method</i> dialog appears when adding or editing +methods within the keep class dialog. It has text fields and selections for +specifying and constraining methods to keep. Again, the <b>Advanced +options</b> / <b>Basic options</b> button at the bottom of the dialog allows +to toggle showing the advanced options. + +<ul> +<li>The <b>Access</b> selections allows to specify constraints on the method or + methods, based on their access modifiers.</li> + +<li>The <b>Annotation</b> text field takes the fully-qualified name of an + annotation that is required for matching methods. The annotation name can + contain wildcards. This is an advanced option for defining <i>keep</i> + annotations.</li> + +<li>The <b>Return type</b> text field takes the fully-qualified type of the method or methods. The type can contain wildcards.</li> + +<li>The <b>Name</b> text field takes the name of the method or methods. The + method name can contain wildcards.</li> + +<li>The <b>Arguments</b> text field takes the comma-separated list of + fully-qualified method arguments. Each of these arguments can contain + wildcards.</li> +</ul> +<p> + +Corresponding configuration options: +<ul type="none"> +<li>-<a href="usage.html#dontshrink">dontshrink</a></li> +<li>-<a href="usage.html#printusage">printusage</a></li> +<li>-<a href="usage.html#keep">keep</a></li> +<li>-<a href="usage.html#keepclassmembers">keepclassmembers</a></li> +<li>-<a href="usage.html#keepclasseswithmembers">keepclasseswithmembers</a></li> +</ul> +<p> + +<h2><a name="obfuscation">The Obfuscation Tab</a></h2> + +The <i>Obfuscation</i> tab presents a number of options that affect the +obfuscation step. The basic options are followed by a few lists of classes and +class members (fields and methods) that must be protected from obfuscation +(but not necessarily from shrinking). +<p> + +The lists are manipulated in the same way as in the <a +href="#shrinking">Shrinking Tab</a>. +<p> + +Corresponding configuration options: +<ul type="none"> +<li>-<a href="usage.html#dontobfuscate">dontobfuscate</a></li> +<li>-<a href="usage.html#printmapping">printmapping</a></li> +<li>-<a href="usage.html#applymapping">applymapping</a></li> +<li>-<a href="usage.html#obfuscationdictionary">obfuscationdictionary</a></li> +<li>-<a href="usage.html#classobfuscationdictionary">classobfuscationdictionary</a></li> +<li>-<a href="usage.html#packageobfuscationdictionary">packageobfuscationdictionary</a></li> +<li>-<a href="usage.html#overloadaggressively">overloadaggressively</a></li> +<li>-<a href="usage.html#useuniqueclassmembernames">useuniqueclassmembernames</a></li> +<li>-<a href="usage.html#dontusemixedcaseclassnames">dontusemixedcaseclassnames</a></li> +<li>-<a href="usage.html#keeppackagenames">keeppackagenames</a></li> +<li>-<a href="usage.html#flattenpackagehierarchy">flattenpackagehierarchy</a></li> +<li>-<a href="usage.html#repackageclasses">repackageclasses</a></li> +<li>-<a href="usage.html#keepattributes">keepattributes</a></li> +<li>-<a href="usage.html#keepparameternames">keepparameternames</a></li> +<li>-<a href="usage.html#renamesourcefileattribute">renamesourcefileattribute</a></li> +<li>-<a href="usage.html#adaptclassstrings">adaptclassstrings</a></li> +<li>-<a href="usage.html#adaptresourcefilenames">adaptresourcefilenames</a></li> +<li>-<a href="usage.html#adaptresourcefilecontents">adaptresourcefilecontents</a></li> +<li>-<a href="usage.html#keepnames">keepnames</a></li> +<li>-<a href="usage.html#keepclassmembernames">keepclassmembernames</a></li> +<li>-<a href="usage.html#keepclasseswithmembernames">keepclasseswithmembernames</a></li> +<li><a href="usage.html#classspecification"><i>class_specification</i></a></li> +</ul> +<p> + +<h2><a name="optimization">The Optimization Tab</a></h2> + +The <i>Optimization</i> tab presents a number of options that affect the +optimization step. The basic options are followed by a few lists of class +method calls that can be removed if ProGuard can determine that their results +are not being used. +<p> + +The lists are manipulated in much the same way as in the <a +href="#shrinking">Shrinking Tab</a>. +<p> + +Corresponding configuration options: +<ul type="none"> +<li>-<a href="usage.html#dontoptimize">dontoptimize</a></li> +<li>-<a href="usage.html#optimizations">optimizations</a></li> +<li>-<a href="usage.html#optimizationpasses">optimizationpasses</a></li> +<li>-<a href="usage.html#allowaccessmodification">allowaccessmodification</a></li> +<li>-<a href="usage.html#mergeinterfacesaggressively">mergeinterfacesaggressively</a></li> +<li>-<a href="usage.html#assumenosideeffects">assumenosideeffects</a></li> +<li><a href="usage.html#classspecification"><i>class_specification</i></a></li> +</ul> +<p> + +<h2><a name="information">The Information Tab</a></h2> + +The <i>Information</i> tab presents a number of options for preverification +and targeting, and for the information that ProGuard returns when processing +your code. The bottom list allows you to query ProGuard about why given +classes and class members are being kept in the shrinking step. +<p> + +Corresponding configuration options: +<ul type="none"> +<li>-<a href="usage.html#dontpreverify">dontpreverify</a></li> +<li>-<a href="usage.html#microedition">microedition</a></li> +<li>-<a href="usage.html#target">target</a></li> +<li>-<a href="usage.html#verbose">verbose</a></li> +<li>-<a href="usage.html#dontnote">dontnote</a></li> +<li>-<a href="usage.html#dontwarn">dontwarn</a></li> +<li>-<a href="usage.html#ignorewarnings">ignorewarnings</a></li> +<li>-<a href="usage.html#skipnonpubliclibraryclasses">skipnonpubliclibraryclasses</a></li> +<li>-<a href="usage.html#dontskipnonpubliclibraryclasses">dontskipnonpubliclibraryclasses</a></li> +<li>-<a href="usage.html#dontskipnonpubliclibraryclassmembers">dontskipnonpubliclibraryclassmembers</a></li> +<li>-<a href="usage.html#keepdirectories">keepdirectories</a></li> +<li>-<a href="usage.html#forceprocessing">forceprocessing</a></li> +<li>-<a href="usage.html#printseeds">printseeds</a></li> +<li>-<a href="usage.html#printconfiguration">printconfiguration</a></li> +<li>-<a href="usage.html#dump">dump</a></li> +<li>-<a href="usage.html#whyareyoukeeping">whyareyoukeeping</a></li> +</ul> +<p> + +<h2><a name="process">The Process Tab</a></h2> + +The <i>Process</i> tab has an output console for displaying the configuration +and the messages while processing. There are three important buttons at the +bottom: +<p> + +<table cellspacing="5" cellpadding="5"> +<tr><td class="button">View configuration</td> + <td>displays the current ProGuard configuration in the console.</td></tr> +<tr><td class="button">Save configuration...</td> + <td>opens a file chooser to save the current ProGuard + configuration.</td></tr> +<tr><td class="button">Process!</td> + <td>executes ProGuard with the current configuration.</td></tr> +</table> +<p> + +<h2><a name="retrace">The ReTrace Tab</a></h2> + +The <i>ReTrace</i> tab has a panel with a few settings, an input text area for +the obfuscated stack trace, and an output console to view the de-obfuscated +stack trace: + +<ul> +<li>The <b>Verbose</b> check box in the settings panel allows to toggle between + normal mode and verbose mode.</li> + +<li>The <b>Mapping file</b> text field takes the name of the required mapping + file that ProGuard wrote while processing the original code. The file name + can be entered manually or by means of the <b>Browse...</b> button that + opens a file chooser.</li> + +<li>The <b>Obfuscated stack trace</b> text area allows to enter the stack + trace, typically by copying and pasting it from elsewhere. Alternatively, + it can be loaded from a file by means of the load button below.</li> +</ul> + +There are two buttons at the bottom: +<p> + +<table cellspacing="5" cellpadding="5"> +<tr><td class="button">Load stack trace...</td> + <td>opens a file chooser to load an obfuscated stack trace.</td></tr> +<tr><td class="button">ReTrace!</td> + <td>executes ReTrace with the current settings.</td></tr> +</table> + +<hr /> +<address> +Copyright © 2002-2017 +<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.guardsquare.com/">GuardSquare</a>. +</address> +</body> +</html> diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/index.html b/third_party/java/proguard/proguard5.3.3/docs/manual/index.html new file mode 100644 index 0000000000..8bf62eb5f0 --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/index.html @@ -0,0 +1,41 @@ +<!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 Manual</title> +</head> +<body> + +<h2>ProGuard</h2> + +<ol> +<li><a href="introduction.html">Introduction</a></li> +<li><a href="usage.html">Usage</a></li> +<li><a href="limitations.html">Limitations</a></li> +<li><a href="examples.html">Examples</a></li> +<li><a href="troubleshooting.html">Troubleshooting</a></li> +<li><a href="refcard.html">Reference Card</a></li> +<li><a href="gui.html">Graphical User Interface</a></li> +<li><a href="ant.html">Ant Task</a></li> +<li><a href="gradle.html">Gradle Task</a></li> +<li><a href="wtk.html">JME Wireless Toolkit Integration</a></li> +</ol> + +<h2>ReTrace</h2> + +<ol> +<li><a href="retrace/introduction.html">Introduction</a></li> +<li><a href="retrace/usage.html">Usage</a></li> +<li><a href="retrace/examples.html">Examples</a></li> +</ol> + +<hr /> +<noscript><div><a target="_top" href="../index.html" class="button">Show menu</a></div></noscript> +<address> +Copyright © 2002-2017 +<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.guardsquare.com/">GuardSquare</a>. +</address> +</body> +</html> diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/introduction.html b/third_party/java/proguard/proguard5.3.3/docs/manual/introduction.html new file mode 100644 index 0000000000..f07e290e23 --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/introduction.html @@ -0,0 +1,173 @@ +<!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 Introduction</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/introduction.html">ProGuard index</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> <a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>') +//--> +</script> +<noscript> +<a class="largebutton" target="_top" href="../index.html#manual/introduction.html">ProGuard index</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> +<a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a> +</noscript> + +<h2>Introduction</h2> + +<b>ProGuard</b> is a Java class file shrinker, optimizer, obfuscator, and +preverifier. The shrinking step detects and removes unused classes, fields, +methods, and attributes. The optimization step analyzes and optimizes the +bytecode of the methods. The obfuscation step renames the remaining classes, +fields, and methods using short meaningless names. These first steps make the +code base smaller, more efficient, and harder to reverse-engineer. The final +preverification step adds preverification information to the classes, which is +required for Java Micro Edition and for Java 6 and higher. +<p> +Each of these steps is optional. For instance, ProGuard can also be used to +just list dead code in an application, or to preverify class files for +efficient use in Java 6. +<p> + +<table class="diagram" align="center"> + +<tr> +<td rowspan="4" class="lightblock">Input jars</td> +<td colspan="8" class="transparentblock"></td> +</tr> + +<tr> +<td rowspan="2" class="transparentblock"></td> +<td rowspan="3" class="lightblock">Shrunk code</td> +<td colspan="6" class="transparentblock"></td> +</tr> + +<tr> +<td class="transparentblock"></td> +<td rowspan="2" class="lightblock">Optim. code</td> +<td colspan="3" class="transparentblock"></td> +<td rowspan="2" class="lightblock">Output jars</td> +</tr> + +<tr> +<td class="transparentblock">- shrink →</td> +<td class="transparentblock">- optimize →</td> +<td class="transparentblock">- obfuscate →</td> +<td class="lightblock">Obfusc. code</td> +<td class="transparentblock">- preverify →</td> +</tr> + +<tr> +<td class="darkblock">Library jars</td> +<td colspan="7" class="transparentblock">------------------------------- (unchanged) -------------------------------→</td> +<td class="darkblock">Library jars</td> +</tr> + +</table> +<p> + +ProGuard first reads the <b>input jars</b> (or aars, wars, ears, zips, apks, +or directories). It then subsequently shrinks, optimizes, obfuscates, and +preverifies them. You can optionally let ProGuard perform multiple +optimization passes. ProGuard writes the processed results to one or +more <b>output jars</b> (or aars, wars, ears, zips, apks, or directories). The +input may contain resource files, whose names and contents can optionally be +updated to reflect the obfuscated class names. +<p> +ProGuard requires the <b>library jars</b> (or aars, wars, ears, zips, apks, or +directories) of the input jars to be specified. These are essentially the +libraries that you would need for compiling the code. ProGuard uses them to +reconstruct the class dependencies that are necessary for proper processing. +The library jars themselves always remain unchanged. You should still put them +in the class path of your final application. + +<h3>Entry points</h3> + +In order to determine which code has to be preserved and which code can be +discarded or obfuscated, you have to specify one or more <i>entry points</i> to +your code. These entry points are typically classes with main methods, applets, +midlets, activities, etc. +<ul> +<li>In the <b>shrinking step</b>, ProGuard starts from these seeds and + recursively determines which classes and class members are used. All other + classes and class members are discarded.</li> + +<li>In the <b>optimization step</b>, ProGuard further optimizes the code. + Among other optimizations, classes and methods that are not entry points + can be made private, static, or final, unused parameters can be removed, + and some methods may be inlined.</li> + +<li>In the <b>obfuscation step</b>, ProGuard renames classes and class members + that are not entry points. In this entire process, keeping the entry + points ensures that they can still be accessed by their original names.</li> + +<li>The <b>preverification step</b> is the only step that doesn't have to know + the entry points.</li> +</ul> +<p> +The <a href="usage.html">Usage section</a> of this manual describes the +necessary <a href="usage.html#keepoptions"><code>-keep</code> options</a> and +the <a href="examples.html">Examples section</a> provides plenty of examples. + +<h3>Reflection</h3> + +Reflection and introspection present particular problems for any automatic +processing of code. In ProGuard, classes or class members in your code that +are created or invoked dynamically (that is, by name) have to be specified as +entry points too. For example, <code>Class.forName()</code> constructs may +refer to any class at run-time. It is generally impossible to compute which +classes have to be preserved (with their original names), since the class +names might be read from a configuration file, for instance. You therefore +have to specify them in your ProGuard configuration, with the same +simple <code>-keep</code> options. +<p> +However, ProGuard will already detect and handle the following cases for you: + +<ul> +<li><code>Class.forName("SomeClass")</code></li> +<li><code>SomeClass.class</code></li> +<li><code>SomeClass.class.getField("someField")</code></li> +<li><code>SomeClass.class.getDeclaredField("someField")</code></li> +<li><code>SomeClass.class.getMethod("someMethod", new Class[] {})</code></li> +<li><code>SomeClass.class.getMethod("someMethod", new Class[] { A.class })</code></li> +<li><code>SomeClass.class.getMethod("someMethod", new Class[] { A.class, B.class })</code></li> +<li><code>SomeClass.class.getDeclaredMethod("someMethod", new Class[] {})</code></li> +<li><code>SomeClass.class.getDeclaredMethod("someMethod", new Class[] { A.class })</code></li> +<li><code>SomeClass.class.getDeclaredMethod("someMethod", new Class[] { A.class, B.class })</code></li> +<li><code>AtomicIntegerFieldUpdater.newUpdater(SomeClass.class, "someField")</code></li> +<li><code>AtomicLongFieldUpdater.newUpdater(SomeClass.class, "someField")</code></li> +<li><code>AtomicReferenceFieldUpdater.newUpdater(SomeClass.class, SomeType.class, "someField")</code></li> +</ul> + +The names of the classes and class members may of course be different, but the +constructs should be literally the same for ProGuard to recognize them. The +referenced classes and class members are preserved in the shrinking phase, and +the string arguments are properly updated in the obfuscation phase. +<p> +Furthermore, ProGuard will offer some suggestions if keeping some classes or +class members appears necessary. For example, ProGuard will note constructs +like "<code>(SomeClass)Class.forName(variable).newInstance()</code>". These +might be an indication that the class or interface <code>SomeClass</code> +and/or its implementations may need to be preserved. You can then adapt your +configuration accordingly. +<p> +For proper results, you should at least be somewhat familiar with the code +that you are processing. Obfuscating code that performs a lot of reflection +may require trial and error, especially without the necessary information +about the internals of the code. + +<hr /> +<address> +Copyright © 2002-2017 +<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.guardsquare.com/">GuardSquare</a>. +</address> +</body> +</html> diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/limitations.html b/third_party/java/proguard/proguard5.3.3/docs/manual/limitations.html new file mode 100644 index 0000000000..a7769be0f7 --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/limitations.html @@ -0,0 +1,63 @@ +<!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 Limitations</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/limitations.html">ProGuard index</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> <a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>') +//--> +</script> +<noscript> +<a class="largebutton" target="_top" href="../index.html#manual/limitations.html">ProGuard index</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> +<a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a> +</noscript> + +<h2>Limitations</h2> + +When using ProGuard, you should be aware of a few technical issues, all of +which are easily avoided or resolved: +<p> +<ul class="spacious"> + +<li>For best results, ProGuard's optimization algorithms assume that the + processed code never <b>intentionally throws NullPointerExceptions</b> or + ArrayIndexOutOfBoundsExceptions, or even OutOfMemoryErrors or + StackOverflowErrors, in order to achieve something useful. For instance, + it may remove a method call <code>myObject.myMethod()</code> if that call + wouldn't have any effect. It ignores the possibility that + <code>myObject</code> might be null, causing a NullPointerException. In + some way this is a good thing: optimized code may throw fewer exceptions. + Should this entire assumption be false, you'll have to switch off + optimization using the <code>-dontoptimize</code> option.</li> + +<li>ProGuard's optimization algorithms currently also assume that the + processed code never creates <b>busy-waiting loops</b> without at least + testing on a volatile field. Again, it may remove such loops. Should this + assumption be false, you'll have to switch off optimization using + the <code>-dontoptimize</code> option.</li> + +<li>When obfuscating, ProGuard writes out class files named + "<code>a.class</code>", "<code>b.class</code>", etc. If a package contains + a large number of classes, ProGuard may also write out + <b>"<code>aux.class</code>"</b>. Inconveniently, Windows refuses to create + files with this reserved name (among a few other names). It's generally + better to write the output to a jar, in order to avoid such problems.</li> + +</ul> + +<hr /> +<address> +Copyright © 2002-2017 +<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.guardsquare.com/">GuardSquare</a>. +</address> +</body> +</html> diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/optimizations.html b/third_party/java/proguard/proguard5.3.3/docs/manual/optimizations.html new file mode 100644 index 0000000000..09270e2ca5 --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/optimizations.html @@ -0,0 +1,202 @@ +<!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>Optimizations</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/optimizations.html">ProGuard index</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> <a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>') +//--> +</script> +<noscript> +<a class="largebutton" target="_top" href="../index.html#manual/optimizations.html">ProGuard index</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> +<a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a> +</noscript> + +<h2>Optimizations</h2> + +The optimization step of ProGuard can be switched off with the +<a href="usage.html#dontoptimize"><code>-dontoptimize</code></a> option. For +more fine-grained control over individual optimizations, experts can use the +<a href="usage.html#optimizations"><code>-optimizations</code></a> option, +with a filter based on the optimization names listed below. The filter works +like any <a href="usage.html#filters">filter</a> in ProGuard. +<p> + +The following wildcards are supported: + +<table cellspacing="10"> +<tr><td valign="top"><code><b>?</b></code></td> + <td>matches any single character in an optimization name.</td></tr> +<tr><td valign="top"><code><b>*</b></code></td> + <td>matches any part of an optimization name.</td></tr> +</table> + +An optimization that is preceded by an exclamation mark '<b>!</b>' is +<i>excluded</i> from further attempts to match with <i>subsequent</i> +optimization names in the filter. Make sure to specify filters correctly, +since they are not checked for potential typos. +<p> + +For example, +"<code>code/simplification/variable,code/simplification/arithmetic</code>" +only performs the two specified peephole optimizations. +<p> + +For example, "<code>!method/propagation/*</code>" performs all optimizations, +except the ones that propagate values between methods. +<p> + +For example, +"<code>!code/simplification/advanced,code/simplification/*</code>" only +performs all peephole optimizations. +<p> +Some optimizations necessarily imply other optimizations. These are then +indicated. Note that the list is likely to change over time, as optimizations +are added and reorganized. +<p> + +<dl> +<dt><code><b>class/marking/final</b></code></dt> +<dd>Marks classes as final, whenever possible.</dd> + +<dt><code><b>class/unboxing/enum</b></code></dt> +<dd>Simplifies enum types to integer constants, whenever possible.</dd> + +<dt><code><b>class/merging/vertical</b></code></dt> +<dd>Merges classes vertically in the class hierarchy, whenever possible.</dd> + +<dt><code><b>class/merging/horizontal</b></code></dt> +<dd>Merges classes horizontally in the class hierarchy, whenever possible.</dd> + +<dt><div>(⇒ <code>code/removal/advanced</code>)</div> + <code><b>field/removal/writeonly</b></code></dt> +<dd>Removes write-only fields.</dd> + +<dt><code><b>field/marking/private</b></code></dt> +<dd>Marks fields as private, whenever possible.</dd> + +<dt><div>(⇒ <code>code/simplification/advanced</code>)</div> + <code><b>field/propagation/value</b></code></dt> +<dd>Propagates the values of fields across methods.</dd> + +<dt><code><b>method/marking/private</b></code></dt> +<dd>Marks methods as private, whenever possible (<i>devirtualization</i>).</dd> + +<dt><div>(⇒ <code>code/removal/advanced</code>)</div> + <code><b>method/marking/static</b></code></dt> +<dd>Marks methods as static, whenever possible (<i>devirtualization</i>).</dd> + +<dt><code><b>method/marking/final</b></code></dt> +<dd>Marks methods as final, whenever possible.</dd> + +<dt><div>(⇒ <code>code/removal/advanced</code>)</div> + <code><b>method/removal/parameter</b></code></dt> +<dd>Removes unused method parameters.</dd> + +<dt><div>(⇒ <code>code/simplification/advanced</code>)</div> + <code><b>method/propagation/parameter</b></code></dt> +<dd>Propagates the values of method parameters from method invocations to + the invoked methods.</dd> + +<dt><div>(⇒ <code>code/simplification/advanced</code>)</div> + <code><b>method/propagation/returnvalue</b></code></dt> +<dd>Propagates the values of method return values from methods to their + invocations.</dd> + +<dt><code><b>method/inlining/short</b></code></dt> +<dd>Inlines short methods.</dd> + +<dt><code><b>method/inlining/unique</b></code></dt> +<dd>Inlines methods that are only called once.</dd> + +<dt><code><b>method/inlining/tailrecursion</b></code></dt> +<dd>Simplifies tail recursion calls, whenever possible.</dd> + +<dt><code><b>code/merging</b></code></dt> +<dd>Merges identical blocks of code by modifying branch targets.</dd> + +<dt><code><b>code/simplification/variable</b></code></dt> +<dd>Performs peephole optimizations for variable loading and storing.</dd> + +<dt><code><b>code/simplification/arithmetic</b></code></dt> +<dd>Performs peephole optimizations for arithmetic instructions.</dd> + +<dt><code><b>code/simplification/cast</b></code></dt> +<dd>Performs peephole optimizations for casting operations.</dd> + +<dt><code><b>code/simplification/field</b></code></dt> +<dd>Performs peephole optimizations for field loading and storing.</dd> + +<dt><div>(⇒ <code>code/removal/simple</code>)</div> + <code><b>code/simplification/branch</b></code></dt> +<dd>Performs peephole optimizations for branch instructions.</dd> + +<dt><code><b>code/simplification/string</b></code></dt> +<dd>Performs peephole optimizations for constant strings.</dd> + +<dt><div>(<i>best used with</i> <code>code/removal/advanced</code>)</div> + <code><b>code/simplification/advanced</b></code></dt> +<dd>Simplifies code based on control flow analysis and data flow + analysis.</dd> + +<dt><div>(⇒ <code>code/removal/exception</code>)</div> + <code><b>code/removal/advanced</b></code></dt> +<dd>Removes dead code based on control flow analysis and data flow + analysis.</dd> + +<dt><div>(⇒ <code>code/removal/exception</code>)</div> + <code><b>code/removal/simple</b></code></dt> +<dd>Removes dead code based on a simple control flow analysis.</dd> + +<dt><code><b>code/removal/variable</b></code></dt> +<dd>Removes unused variables from the local variable frame.</dd> + +<dt><code><b>code/removal/exception</b></code></dt> +<dd>Removes exceptions with empty try blocks.</dd> + +<dt><code><b>code/allocation/variable</b></code></dt> +<dd>Optimizes variable allocation on the local variable frame.</dd> +</dl> +<p> + +ProGuard also provides some unofficial settings to control optimizations, that +may disappear in future versions. These are Java system properties, which +can be set as JVM arguments (with <code>-D.....)</code>: +<dl> +<dt><code><b>maximum.inlined.code.length</b></code> (default = 8 bytes)</dt> +<dd>Specifies the maximum code length (expressed in bytes) of short methods + that are eligible to be inlined. Inlining methods that are too long may + unnecessarily inflate the code size.</dd> + +<dt><code><b>maximum.resulting.code.length</b></code> (default = 8000 bytes + for JSE, 2000 bytes for JME)</dt> +<dd>Specifies the maximum resulting code length (expressed in bytes) allowed + when inlining methods. Many Java virtual machines do not apply just-in-time + compilation to methods that are too long, so it's important not to let them + grow too large.</dd> + +<dt><code><b>optimize.conservatively</b></code> (default = unset)</dt> +<dd>Allows input code with ordinary instructions intentionally throwing + <code>NullPointerException</code>, + <code>ArrayIndexOutOfBoundsException</code>, or + <code>ClassCastException</code>, without any other useful purposes. By + default, ProGuard may just discard such seemingly useless instructions, + resulting in better optimization of most common code.</dd> +</dl> + +<hr /> +<address> +Copyright © 2002-2017 +<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.guardsquare.com/">GuardSquare</a>. +</address> +</body> +</html> diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/refcard.html b/third_party/java/proguard/proguard5.3.3/docs/manual/refcard.html new file mode 100644 index 0000000000..0555c33204 --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/refcard.html @@ -0,0 +1,493 @@ +<!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 Reference Card</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/refcard.html">ProGuard index</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> <a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>') +//--> +</script> +<noscript> +<a class="largebutton" target="_top" href="../index.html#manual/refcard.html">ProGuard index</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> +<a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a> +</noscript> + +<h1>ProGuard Reference Card</h1> + +<h2>Usage</h2> + +<code><b>java -jar proguard.jar </b></code><i>options</i> ... +<p> + Typically: +<p> +<code><b>java -jar proguard.jar @myconfig.pro</b></code> +<p> + +<h2>Options</h2> + +<table cellspacing="10"> + +<tr> +<td valign="top"><a href="usage.html#at"><code><b>@</b></code></a><a href="usage.html#filename"><i>filename</i></a></td> + +<td>Short for '<code>-include</code> <i>filename</i>'.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#include"><code><b>-include</b></code></a> + <a href="usage.html#filename"><i>filename</i></a></td> + +<td>Read configuration options from the given file.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#basedirectory"><code><b>-basedirectory</b></code></a> + <a href="usage.html#filename"><i>directoryname</i></a></td> + +<td>Specifies the base directory for subsequent relative file names.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#injars"><code><b>-injars</b></code></a> + <a href="usage.html#classpath"><i>class_path</i></a></td> +<td>Specifies the program jars (or wars, ears, zips, or directories).</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#outjars"><code><b>-outjars</b></code></a> + <a href="usage.html#classpath"><i>class_path</i></a></td> +<td>Specifies the names of the output jars (or wars, ears, zips, or + directories).</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#libraryjars"><code><b>-libraryjars</b></code></a> + <a href="usage.html#classpath"><i>class_path</i></a></td> +<td>Specifies the library jars (or wars, ears, zips, or directories).</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#skipnonpubliclibraryclasses"><code><b>-skipnonpubliclibraryclasses</b></code></a></td> +<td>Ignore non-public library classes.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#dontskipnonpubliclibraryclasses"><code><b>-dontskipnonpubliclibraryclasses</b></code></a></td> +<td>Don't ignore non-public library classes (the default).</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#dontskipnonpubliclibraryclassmembers"><code><b>-dontskipnonpubliclibraryclassmembers</b></code></a></td> +<td>Don't ignore package visible library class members.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#keepdirectories"><code><b>-keepdirectories</b></code></a> + [<a href="usage.html#filters"><i>directory_filter</i></a>]</td> +<td>Keep the specified directories in the output jars (or wars, ears, zips, or + directories).</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#target"><code><b>-target</b></code></a> + <i>version</i></td> +<td>Set the given version number in the processed classes.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#forceprocessing"><code><b>-forceprocessing</b></code></a></td> +<td>Process the input, even if the output seems up to date.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#keep"><code><b>-keep</b></code></a> + [<a href="usage.html#keepoptionmodifiers">,<i>modifier</i></a>,...] + <a href="usage.html#classspecification"><i>class_specification</i></a></td> +<td>Preserve the specified classes <i>and</i> class members.</td> + +</tr> +<tr> +<td valign="top"><a href="usage.html#keepclassmembers"><code><b>-keepclassmembers</b></code></a> + [<a href="usage.html#keepoptionmodifiers">,<i>modifier</i></a>,...] + <a href="usage.html#classspecification"><i>class_specification</i></a></td> +<td>Preserve the specified class members, if their classes are preserved as + well.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#keepclasseswithmembers"><code><b>-keepclasseswithmembers</b></code></a> + [<a href="usage.html#keepoptionmodifiers">,<i>modifier</i></a>,...] + <a href="usage.html#classspecification"><i>class_specification</i></a></td> +<td>Preserve the specified classes <i>and</i> class members, if all of the + specified class members are present.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#keepnames"><code><b>-keepnames</b></code></a> + <a href="usage.html#classspecification"><i>class_specification</i></a></td> +<td>Preserve the names of the specified classes <i>and</i> class members (if + they aren't removed in the shrinking step).</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#keepclassmembernames"><code><b>-keepclassmembernames</b></code></a> + <a href="usage.html#classspecification"><i>class_specification</i></a></td> +<td>Preserve the names of the specified class members (if they aren't removed + in the shrinking step).</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#keepclasseswithmembernames"><code><b>-keepclasseswithmembernames</b></code></a> + <a href="usage.html#classspecification"><i>class_specification</i></a></td> +<td>Preserve the names of the specified classes <i>and</i> class members, if + all of the specified class members are present (after the shrinking + step).</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#printseeds"><code><b>-printseeds</b></code></a> + [<a href="usage.html#filename"><i>filename</i></a>]</td> +<td>List classes and class members matched by the various <code>-keep</code> + options, to the standard output or to the given file.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#dontshrink"><code><b>-dontshrink</b></code></a></td> +<td>Don't shrink the input class files.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#printusage"><code><b>-printusage</b></code></a> + [<a href="usage.html#filename"><i>filename</i></a>]</td> +<td>List dead code of the input class files, to the standard output or to the + given file.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#whyareyoukeeping"><code><b>-whyareyoukeeping</b></code></a> + <a href="usage.html#classspecification"><i>class_specification</i></a></td> +<td>Print details on why the given classes and class members are being kept in + the shrinking step.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#dontoptimize"><code><b>-dontoptimize</b></code></a></td> +<td>Don't optimize the input class files.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#optimizations"><code><b>-optimizations</b></code></a> + <a href="optimizations.html"><i>optimization_filter</i></a></td> +<td>The optimizations to be enabled and disabled.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#optimizationpasses"><code><b>-optimizationpasses</b></code></a> + <i>n</i></td> +<td>The number of optimization passes to be performed.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#assumenosideeffects"><code><b>-assumenosideeffects</b></code></a> + <a href="usage.html#classspecification"><i>class_specification</i></a></td> +<td>Assume that the specified methods don't have any side effects, while + optimizing.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#allowaccessmodification"><code><b>-allowaccessmodification</b></code></a></td> +<td>Allow the access modifiers of classes and class members to be modified, + while optimizing.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#mergeinterfacesaggressively"><code><b>-mergeinterfacesaggressively</b></code></a></td> +<td>Allow any interfaces to be merged, while optimizing.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#dontobfuscate"><code><b>-dontobfuscate</b></code></a></td> +<td>Don't obfuscate the input class files.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#printmapping"><code><b>-printmapping</b></code></a> + [<a href="usage.html#filename"><i>filename</i></a>]</td> +<td>Print the mapping from old names to new names for classes and class members + that have been renamed, to the standard output or to the given file.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#applymapping"><code><b>-applymapping</b></code></a> + <a href="usage.html#filename"><i>filename</i></a></td> +<td>Reuse the given mapping, for incremental obfuscation.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#obfuscationdictionary"><code><b>-obfuscationdictionary</b></code></a> + <a href="usage.html#filename"><i>filename</i></a></td> +<td>Use the words in the given text file as obfuscated field names and method names.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#classobfuscationdictionary"><code><b>-classobfuscationdictionary</b></code></a> + <a href="usage.html#filename"><i>filename</i></a></td> +<td>Use the words in the given text file as obfuscated class names.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#packageobfuscationdictionary"><code><b>-packageobfuscationdictionary</b></code></a> + <a href="usage.html#filename"><i>filename</i></a></td> +<td>Use the words in the given text file as obfuscated package names.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#overloadaggressively"><code><b>-overloadaggressively</b></code></a></td> +<td>Apply aggressive overloading while obfuscating.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#useuniqueclassmembernames"><code><b>-useuniqueclassmembernames</b></code></a></td> +<td>Ensure uniform obfuscated class member names for subsequent incremental + obfuscation.</td> </tr> + +<tr> +<td valign="top"><a href="usage.html#dontusemixedcaseclassnames"><code><b>-dontusemixedcaseclassnames</b></code></a></td> +<td>Don't generate mixed-case class names while obfuscating.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#keeppackagenames"><code><b>-keeppackagenames</b></code></a> + [<i><a href="usage.html#filters">package_filter</a></i>]</td> +<td>Keep the specified package names from being obfuscated.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#flattenpackagehierarchy"><code><b>-flattenpackagehierarchy</b></code></a> + [<i>package_name</i>]</td> +<td>Repackage all packages that are renamed into the single given parent + package.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#repackageclasses"><code><b>-repackageclasses</b></code></a> + [<i>package_name</i>]</td> +<td>Repackage all class files that are renamed into the single given + package.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#keepattributes"><code><b>-keepattributes</b></code></a> + [<i><a href="usage.html#filters">attribute_filter</a></i>]</td> +<td>Preserve the given optional attributes; typically + <code>Exceptions</code>, <code>InnerClasses</code>, + <code>Signature</code>, <code>Deprecated</code>, + <code>SourceFile</code>, <code>SourceDir</code>, + <code>LineNumberTable</code>, + <code>LocalVariableTable</code>, <code>LocalVariableTypeTable</code>, + <code>Synthetic</code>, <code>EnclosingMethod</code>, and + <code>*Annotation*</code>.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#keepparameternames"><code><b>-keepparameternames</b></code></a></td> +<td>Keep the parameter names and types of methods that are kept.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#renamesourcefileattribute"><code><b>-renamesourcefileattribute</b></code></a> + [<i>string</i>]</td> +<td>Put the given constant string in the <code>SourceFile</code> + attributes.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#adaptclassstrings"><code><b>-adaptclassstrings</b></code></a> + [<a href="usage.html#filters"><i>class_filter</i></a>]</td> +<td>Adapt string constants in the specified classes, based on the obfuscated + names of any corresponding classes.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#adaptresourcefilenames"><code><b>-adaptresourcefilenames</b></code></a> + [<a href="usage.html#filefilters"><i>file_filter</i></a>]</td> +<td>Rename the specified resource files, based on the obfuscated names of the + corresponding class files.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#adaptresourcefilecontents"><code><b>-adaptresourcefilecontents</b></code></a> + [<a href="usage.html#filefilters"><i>file_filter</i></a>]</td> +<td>Update the contents of the specified resource files, based on the + obfuscated names of the processed classes.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#dontpreverify"><code><b>-dontpreverify</b></code></a></td> +<td>Don't preverify the processed class files.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#microedition"><code><b>-microedition</b></code></a></td> +<td>Target the processed class files at Java Micro Edition.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#verbose"><code><b>-verbose</b></code></a></td> +<td>Write out some more information during processing.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#dontnote"><code><b>-dontnote</b></code></a> + [<a href="usage.html#filters"><i>class_filter</i></a>]</td> +<td>Don't print notes about potential mistakes or omissions in the + configuration.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#dontwarn"><code><b>-dontwarn</b></code></a> + [<a href="usage.html#filters"><i>class_filter</i></a>]</td> +<td>Don't warn about unresolved references at all.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#ignorewarnings"><code><b>-ignorewarnings</b></code></a></td> +<td>Print warnings about unresolved references, but continue processing + anyhow.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#printconfiguration"><code><b>-printconfiguration</b></code></a> + [<a href="usage.html#filename"><i>filename</i></a>]</td> +<td>Write out the entire configuration in traditional ProGuard style, to the + standard output or to the given file.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#dump"><code><b>-dump</b></code></a> + [<a href="usage.html#filename"><i>filename</i></a>]</td> +<td>Write out the internal structure of the processed class files, to the + standard output or to the given file.</td> +</tr> + +</table> +<p> +Notes: +<ul> + +<li><i>class_path</i> is a list of jars, wars, ears, zips, and directories, + with optional filters, separated by path separators.</li> +<li><i>filename</i> can contain Java system properties delimited by + '<b><</b>' and '<b>></b>'.</li> +<li>If <i>filename</i> contains special characters, the entire name + should be quoted with single or double quotes.</li> +</ul> +<p> + +<h2>Overview of <code>Keep</code> Options</h2> + +<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="usage.html#keep"><code>-keep</code></a></td> +<td bgcolor="#E0E0E0"><a href="usage.html#keepnames"><code>-keepnames</code></a></td> +</tr> + +<tr> +<td>Class members only</td> +<td bgcolor="#E0E0E0"><a href="usage.html#keepclassmembers"><code>-keepclassmembers</code></a></td> +<td bgcolor="#E0E0E0"><a href="usage.html#keepclassmembernames"><code>-keepclassmembernames</code></a></td> +</tr> + +<tr> +<td>Classes and class members, if class members present</td> +<td bgcolor="#E0E0E0"><a href="usage.html#keepclasseswithmembers"><code>-keepclasseswithmembers</code></a></td> +<td bgcolor="#E0E0E0"><a href="usage.html#keepclasseswithmembernames"><code>-keepclasseswithmembernames</code></a></td> +</tr> + +</table> +<p> + +<h2>Keep Option Modifiers</h2> + +<table cellspacing="10"> + +<tr> +<td valign="top"><a href="usage.html#includedescriptorclasses"><code><b>includedescriptorclasses</b></code></a></td> +<td>Also keep any classes in the descriptors of specified fields and methods. +</tr> + +<tr> +<td valign="top"><a href="usage.html#allowshrinking"><code><b>allowshrinking</b></code></a></td> +<td>Allow the specified entry points to be removed in the shrinking step.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#allowoptimization"><code><b>allowoptimization</b></code></a></td> +<td>Allow the specified entry points to be modified in the optimization + step.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#allowobfuscation"><code><b>allowobfuscation</b></code></a></td> +<td>Allow the specified entry points to be renamed in the obfuscation step.</td> +</tr> + +</table> +<p> + +<h2>Class Specifications</h2> + +<pre> +[<b>@</b><i>annotationtype</i>] [[<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> [<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> +Notes: +<ul> +<li>Class names must always be fully qualified, i.e. including their package + names.</li> +<li>Types in <i>classname</i>, <i>annotationtype</i>, <i>returntype</i>, and + <i>argumenttype</i> can contain wildcards: '<code><b>?</b></code>' for a + single character, '<code><b>*</b></code>' for any number of characters + (but not the package separator), '<code><b>**</b></code>' for any number + of (any) characters, '<code><b>%</b></code>' for any primitive type, + '<code><b>***</b></code>' for any type, and '<code><b>...</b></code>' for any number of arguments.</li> +<li><i>fieldname</i> and <i>methodname</i> can contain wildcards as well: + '<code><b>?</b></code>' for a single character and '<code><b>*</b></code>' + for any number of characters.</li> +</ul> + +<hr /> +<address> +Copyright © 2002-2017 +<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.guardsquare.com/">GuardSquare</a>. +</address> +</body> +</html> diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/retrace/examples.html b/third_party/java/proguard/proguard5.3.3/docs/manual/retrace/examples.html new file mode 100644 index 0000000000..ec2a99bbc3 --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/retrace/examples.html @@ -0,0 +1,182 @@ +<!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>ReTrace Examples</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/retrace/examples.html">ProGuard index</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> <a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>') +//--> +</script> +<noscript> +<a class="largebutton" target="_top" href="../../index.html#manual/retrace/examples.html">ProGuard index</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> +<a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a> +</noscript> + +<h2>Examples</h2> + +Some typical example uses: +<ol> +<li><a href="#with">Restoring a stack trace with line numbers</a></li> +<li><a href="#withverbose">Restoring a stack trace with line numbers + (verbose)</a></li> +<li><a href="#without">Restoring a stack trace without line numbers</a></li> +</ol> + +<h3><a name="with">Restoring a stack trace with line numbers</a></h3> + +Assume for instance ProGuard itself has been obfuscated using the following +extra options: +<pre> +-printmapping mapping.txt + +-renamesourcefileattribute MyApplication +-keepattributes SourceFile,LineNumberTable +</pre> +<p> + +Now assume the processed application throws an exception: +<pre> +java.io.IOException: Can't read [dummy.jar] (No such file or directory) + at proguard.y.a(MyApplication:188) + at proguard.y.a(MyApplication:158) + at proguard.y.a(MyApplication:136) + at proguard.y.a(MyApplication:66) + at proguard.ProGuard.c(MyApplication:218) + at proguard.ProGuard.a(MyApplication:82) + at proguard.ProGuard.main(MyApplication:538) +Caused by: java.io.IOException: No such file or directory + at proguard.d.q.a(MyApplication:50) + at proguard.y.a(MyApplication:184) + ... 6 more +</pre> +<p> + +If we have saved the stack trace in a file <code>stacktrace.txt</code>, we can +use the following command to recover the stack trace: +<pre> +<b>java -jar retrace.jar mapping.txt stacktrace.txt</b> +</pre> +<p> + +The output will correspond to the original stack trace: +<pre> +java.io.IOException: Can't read [dummy.jar] (No such file or directory) + at proguard.InputReader.readInput(InputReader.java:188) + at proguard.InputReader.readInput(InputReader.java:158) + at proguard.InputReader.readInput(InputReader.java:136) + at proguard.InputReader.execute(InputReader.java:66) + at proguard.ProGuard.readInput(ProGuard.java:218) + at proguard.ProGuard.execute(ProGuard.java:82) + at proguard.ProGuard.main(ProGuard.java:538) +Caused by: java.io.IOException: No such file or directory + at proguard.io.DirectoryPump.pumpDataEntries(DirectoryPump.java:50) + at proguard.InputReader.readInput(InputReader.java:184) + ... 6 more +</pre> + +<h3><a name="withverbose">Restoring a stack trace with line numbers (verbose)</a></h3> + +In the previous example, we could also use the verbose flag: +<pre> +<b>java -jar retrace.jar -verbose mapping.txt stacktrace.txt</b> +</pre> +<p> + +The output will then look as follows: +<pre> +java.io.IOException: Can't read [dummy.jar] (No such file or directory) + at proguard.InputReader.void readInput(java.lang.String,proguard.ClassPathEntry,proguard.io.DataEntryReader)(InputReader.java:188) + at proguard.InputReader.void readInput(java.lang.String,proguard.ClassPath,int,int,proguard.io.DataEntryReader)(InputReader.java:158) + at proguard.InputReader.void readInput(java.lang.String,proguard.ClassPath,proguard.io.DataEntryReader)(InputReader.java:136) + at proguard.InputReader.void execute(proguard.classfile.ClassPool,proguard.classfile.ClassPool)(InputReader.java:66) + at proguard.ProGuard.void readInput()(ProGuard.java:218) + at proguard.ProGuard.void execute()(ProGuard.java:82) + at proguard.ProGuard.void main(java.lang.String[])(ProGuard.java:538) +Caused by: java.io.IOException: No such file or directory + at proguard.io.DirectoryPump.void pumpDataEntries(proguard.io.DataEntryReader)(DirectoryPump.java:50) + at proguard.InputReader.void readInput(java.lang.String,proguard.ClassPathEntry,proguard.io.DataEntryReader)(InputReader.java:184) + ... 6 more +</pre> + + +<h3><a name="without">Restoring a stack trace without line numbers</a></h3> + +Assume for instance ProGuard itself has been obfuscated using the following +extra options, this time without preserving the line number tables: +<pre> +-printmapping mapping.txt +</pre> +<p> + +A stack trace <code>stacktrace.txt</code> will then lack line number +information, showing "Unknown source" instead: +<pre> +java.io.IOException: Can't read [dummy.jar] (No such file or directory) + at proguard.y.a(Unknown Source) + at proguard.y.a(Unknown Source) + at proguard.y.a(Unknown Source) + at proguard.y.a(Unknown Source) + at proguard.ProGuard.c(Unknown Source) + at proguard.ProGuard.a(Unknown Source) + at proguard.ProGuard.main(Unknown Source) +Caused by: java.io.IOException: No such file or directory + at proguard.d.q.a(Unknown Source) + ... 7 more +</pre> +<p> + +We can still use the same command to recover the stack trace: +<pre> +<b>java -jar retrace.jar mapping.txt stacktrace.txt</b> +</pre> +<p> + +The output will now list all alternative original method names for each +ambiguous obfuscated method name: +<pre> +java.io.IOException: Can't read [dummy.jar] (No such file or directory) + at proguard.InputReader.execute(InputReader.java) + readInput(InputReader.java) + at proguard.InputReader.execute(InputReader.java) + readInput(InputReader.java) + at proguard.InputReader.execute(InputReader.java) + readInput(InputReader.java) + at proguard.InputReader.execute(InputReader.java) + readInput(InputReader.java) + at proguard.ProGuard.readInput(ProGuard.java) + at proguard.ProGuard.execute(ProGuard.java) + optimize(ProGuard.java) + createPrintStream(ProGuard.java) + closePrintStream(ProGuard.java) + fileName(ProGuard.java) + at proguard.ProGuard.main(ProGuard.java) +Caused by: java.io.IOException: No such file or directory + at proguard.io.DirectoryPump.pumpDataEntries(DirectoryPump.java) + readFiles(DirectoryPump.java) +</pre> +<p> + +For instance, ReTrace can't tell if the method <code>a</code> corresponds +to <code>execute</code> or to <code>readInput</code>, so it lists both. You +need to figure it out based on your knowledge of the application. Having line +numbers and unambiguous names clearly is a lot easier, so you should consider +<a href="../examples.html#stacktrace">preserving the line numbers</a> when you +obfuscate your application. + +<hr /> +<address> +Copyright © 2002-2017 +<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.guardsquare.com/">GuardSquare</a>. +</address> +</body> +</html> + diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/retrace/index.html b/third_party/java/proguard/proguard5.3.3/docs/manual/retrace/index.html new file mode 100644 index 0000000000..71cc0acd58 --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/retrace/index.html @@ -0,0 +1,26 @@ +<!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>ReTrace Manual</title> +</head> +<body> + +<h2>ReTrace</h2> + +<ol> +<li><a href="introduction.html">Introduction</a></li> +<li><a href="usage.html">Usage</a></li> +<li><a href="examples.html">Examples</a></li> +</ol> + +<hr /> +<noscript><div><a target="_top" href="../../index.html" class="button">Show menu</a></div></noscript> +<address> +Copyright © 2002-2017 +<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.guardsquare.com/">GuardSquare</a>. +</address> +</body> +</html> diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/retrace/introduction.html b/third_party/java/proguard/proguard5.3.3/docs/manual/retrace/introduction.html new file mode 100644 index 0000000000..3158ad9246 --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/retrace/introduction.html @@ -0,0 +1,80 @@ +<!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>ReTrace Introduction</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/retrace/introduction.html">ProGuard index</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> <a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>') +//--> +</script> +<noscript> +<a class="largebutton" target="_top" href="../../index.html#manual/retrace/introduction.html">ProGuard index</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> +<a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a> +</noscript> + +<h2>Introduction</h2> + +<b>ReTrace</b> is a companion tool for <b>ProGuard</b> that 'de-obfuscates' +stack traces. +<p> +When an obfuscated program throws an exception, the resulting stack trace +typically isn't very informative. Class names and method names have been +replaced by short meaningless strings. Source file names and line numbers are +missing altogether. While this may be intentional, it can also be inconvenient +when debugging problems. +<p> + +<table class="diagram" align="center"> + +<tr> +<td rowspan="1" class="lightblock">Original code</td> +<td class="transparentblock">- <b>ProGuard</b> →</td> +<td rowspan="1" class="lightblock">Obfuscated code</td> +</tr> + +<tr> +<td rowspan="3" class="transparentblock"></td> +<td class="transparentblock">↓</td> +<td class="transparentblock">↓</td> +</tr> + +<tr> +<td class="whiteblock">Mapping file</td> +<td class="transparentblock">↓</td> +</tr> + +<tr> +<td class="transparentblock">↓</td> +<td class="transparentblock">↓</td> +</tr> + +<tr> +<td class="whiteblock">Readable stack trace</td> +<td class="transparentblock">← <b>ReTrace</b> -</td> +<td class="whiteblock">Obfuscated stack trace</td> +</tr> + +</table> +<p> +ReTrace can read an obfuscated stack trace and restore it to what it would +look like without obfuscation. The restoration is based on the mapping file +that ProGuard can write out during obfuscation. The mapping file links the +original class names and class member names to their obfuscated names. + +<hr /> +<address> +Copyright © 2002-2017 +<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.guardsquare.com/">GuardSquare</a>. +</address> +</body> +</html> + diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/retrace/usage.html b/third_party/java/proguard/proguard5.3.3/docs/manual/retrace/usage.html new file mode 100644 index 0000000000..aefcf67b30 --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/retrace/usage.html @@ -0,0 +1,143 @@ +<!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>ReTrace 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/retrace/usage.html">ProGuard index</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> <a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>') +//--> +</script> +<noscript> +<a class="largebutton" target="_top" href="../../index.html#manual/retrace/usage.html">ProGuard index</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> +<a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a> +</noscript> + +<h2>Usage</h2> + +You can find the ReTrace jar in the <code>lib</code> directory of the +ProGuard distribution. To run ReTrace, just type: +<p> +<p class="code"> +<code><b>java -jar retrace.jar </b></code>[<i>options...</i>] + <i>mapping_file</i> [<i>stacktrace_file</i>] +</p> +Alternatively, the <code>bin</code> directory contains some short Linux and +Windows scripts containing this command. These are the arguments: + +<dl> +<dt><i>mapping_file</i></dt> + +<dd>Specifies the name of the mapping file, produced by ProGuard with the + option + "<a href="../usage.html#printmapping"><code>-printmapping</code></a> <i>mapping_file</i>", + while obfuscating the application that produced the stack trace.</dd> + +<dt><i>stacktrace_file</i></dt> + +<dd>Optionally specifies the name of the file containing the stack trace. If + no file is specified, a stack trace is read from the standard input. Blank + lines and unrecognized lines are ignored, as far as possible.</dd> +</dl> + +The following options are supported: +<dl> +<dt><code><b>-verbose</b></code></dt> + +<dd>Specifies to print out more informative stack traces that include not only + method names, but also method return types and arguments.</dd> + +<dt><code><b>-regex</b></code> <i>regular_expression</i></dt> + +<dd>Specifies the regular expression that is used to parse the lines in the + stack trace. Specifying a different regular expression allows to + de-obfuscate more general types of input than just stack traces. The + default is suitable for stack traces produced by most JVMs: + <pre> +(?:.*?\bat\s+%c\.%m\s*\(%s(?::%l)?\)\s*(?:~\[.*\])?)|(?:(?:.*?[:"]\s+)?%c(?::.*)?) + </pre> + The regular expression is a Java regular expression (cfr. the documentation + of <code>java.util.regex.Pattern</code>), with a few additional wildcards: + <table cellspacing="10"> + <tr><td valign="top"><code><b>%c</b></code></td> + <td>matches a class name (e.g. + "<code>myapplication.MyClass</code>").</td></tr> + <tr><td valign="top"><code><b>%C</b></code></td> + <td>matches a class name with slashes (e.g. + "<code>myapplication/MyClass</code>").</td></tr> + <tr><td valign="top"><code><b>%t</b></code></td> + <td>matches a field type or method return type (e.g. + "<code>myapplication.MyClass[]</code>").</td></tr> + <tr><td valign="top"><code><b>%f</b></code></td> + <td>matches a field name (e.g. + "<code>myField</code>").</td></tr> + <tr><td valign="top"><code><b>%m</b></code></td> + <td>matches a method name (e.g. + "<code>myMethod</code>").</td></tr> + <tr><td valign="top"><code><b>%a</b></code></td> + <td>matches a list of method arguments (e.g. + "<code>boolean,int</code>").</td></tr> + <tr><td valign="top"><code><b>%s</b></code></td> + <td>matches a source file name (e.g. + "<code>MyClass.java</code>").</td></tr> + <tr><td valign="top"><code><b>%l</b></code></td> + <td>matches a line number inside a method (e.g. + "<code>123</code>").</td></tr> + </table> + Elements that match these wildcards are de-obfuscated, when possible. Note + that regular expressions must not contain any capturing groups. Use + non-capturing groups instead: <code>(?:</code>...<code>)</code> + <p> + The default expression for instance matches the following lines: + <pre> +Exception in thread "main" myapplication.MyException: Some message + at myapplication.MyClass.myMethod(SourceFile:123) + </pre> + </dd> +</dl> + +The restored stack trace is printed to the standard output. The completeness +of the restored stack trace depends on the presence of line number tables in +the obfuscated class files: + +<ul> +<li>If all line numbers have been preserved while obfuscating the application, + ReTrace will be able to restore the stack trace completely.</li> + +<li>If the line numbers have been removed, mapping obfuscated method names + back to their original names has become ambiguous. Retrace will list all + possible original method names for each line in the stack trace. The user + can then try to deduce the actual stack trace manually, based on the logic + of the program.</li> + +</ul> +<p> + +Preserving line number tables is explained in detail in this <a +href="../examples.html#stacktrace">example</a> in the ProGuard User Manual. +<p> + +Source file names are currently restored based on the names of the outer-most +classes. If you prefer to keep the obfuscated name, you can +replace <code>%s</code> in the default regular expression by <code>.*</code> +<p> + +Unobfuscated elements and obfuscated elements for which no mapping is available +will be left unchanged. + +<hr /> +<address> +Copyright © 2002-2017 +<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.guardsquare.com/">GuardSquare</a>. +</address> +</body> +</html> + diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/sections.html b/third_party/java/proguard/proguard5.3.3/docs/manual/sections.html new file mode 100644 index 0000000000..1b04ed6349 --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/sections.html @@ -0,0 +1,54 @@ +<!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-script-type" content="text/javascript"> +<meta http-equiv="content-style-type" content="text/css"> +<link rel="stylesheet" type="text/css" href="../style.css"> +<title>Sections</title> +</head> +<body class="navigation"> + +<ul class="navigation"> +<li><a href="../sections.html"><< Main menu</a></li> + +<li class="title">ProGuard Manual</li> +<li><a target="main" href="introduction.html">Introduction</a></li> +<li><a target="main" href="usage.html">Usage</a></li> +<li><a target="main" href="limitations.html">Limitations</a></li> +<li><a target="main" href="examples.html">Examples</a></li> +<li><a target="main" href="troubleshooting.html">Troubleshooting</a></li> +<li><a target="main" href="refcard.html">Ref Card</a></li> +<li><a target="main" href="gui.html">GUI</a></li> +<li><a target="main" href="ant.html">Ant Task</a></li> +<li><a target="main" href="gradle.html">Gradle Task</a></li> +<li><a target="main" href="wtk.html">JME WTK</a></li> + +<li class="title">ReTrace Manual</li> +<li><a target="main" href="retrace/introduction.html">Introduction</a></li> +<li><a target="main" href="retrace/usage.html">Usage</a></li> +<li><a target="main" href="retrace/examples.html">Examples</a></li> +</ul> + +<p> +<center> +<small>More Android code protection:</small> +<p> +<a href="http://www.guardsquare.com/dexguard" target="_top"> +<img src="../dexguard.png" width="88" height="55" alt="DexGuard" /></a> + +<p> +<small>With support of</small> + +<p> +<a href="http://www.guardsquare.com/" target="_top"> +<img src="../guardsquare.png" width="88" height="25" alt="GuardSquare" /></a> + +<p> +<a href="http://sourceforge.net/projects/proguard/" target="other"> +<img src="../sflogo.png" width="88" height="31" alt="SourceForge" /></a> + +</center> + +</body> +</html> diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/style.css b/third_party/java/proguard/proguard5.3.3/docs/manual/style.css new file mode 100644 index 0000000000..415b8ef3cb --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/style.css @@ -0,0 +1,184 @@ +@charset "iso-8859-1"; + +/* Fonts. */ + +@font-face +{ + font-family: 'Open Sans'; + font-style: normal; + font-weight: 400; + src: url('fonts/OpenSans-Regular.eot'); + src: local('Open Sans'), + local('OpenSans'), + url('fonts/OpenSans-Regular.eot?#iefix') format('embedded-opentype'), + url('fonts/OpenSans-Regular.woff') format('woff'), + url('fonts/OpenSans-Regular.ttf') format('truetype'), + url('fonts/OpenSans-Regular.svg#OpenSansRegular') format('svg'); +} + +@font-face +{ + font-family: 'Open Sans'; + font-style: normal; + font-weight: 700; + src: url('fonts/OpenSans-Bold.eot'); + src: local('Open Sans Bold'), + local('OpenSans-Bold'), + url('fonts/OpenSans-Bold.eot?#iefix') format('embedded-opentype'), + url('fonts/OpenSans-Bold.woff') format('woff'), + url('fonts/OpenSans-Bold.ttf') format('truetype'), + url('fonts/OpenSans-Bold.svg#OpenSansBold') format('svg'); +} + +@font-face +{ + font-family: 'Open Sans'; + font-style: italic; + font-weight: 400; + src: url('fonts/OpenSans-Italic.eot'); + src: local('Open Sans Italic'), + local('OpenSans-Italic'), + url('fonts/OpenSans-Italic.eot?#iefix') format('embedded-opentype'), + url('fonts/OpenSans-Italic.woff') format('woff'), + url('fonts/OpenSans-Italic.ttf') format('truetype'), + url('fonts/OpenSans-Italic.svg#OpenSansItalic') format('svg'); +} + +/* Global settings. */ + +body +{ + background: #FFFFFF; + font-family: "Open Sans",Verdana,sans-serif; +} + +h1 +{ + text-align: center; +} + +h2 +{ + background: #EEEEFF; + padding: 10px; +} + +dt +{ + padding: 6px; +} + +dt div +{ + color: grey; + float: right; +} + +dd +{ + padding: 6px; +} + +pre +{ + padding: 10px; + background: #E0E0E0; +} + +.spacious li +{ + padding: 8px; +} + +.shifted li +{ + margin-left: 50px; +} + +img.float +{ + float: left; +} + +a +{ + text-decoration: none; +} + +a.button +{ + color: #000000; + text-decoration: none; + background: #E0E0E0; + border: 1px outset #FFFFFF; + float: right; +} + +a.largebutton { + font-weight: bold; + color: #000000; + margin: 0px; + padding: 10px; + background: #D0D0D0; + text-decoration: none; + border: 1px outset #FFFFFF; +} + +/* Settings for variable width code. */ + +p.code +{ + padding: 10px; + background: #E0E0E0; +} + + +/* Settings for diagrams. */ + +table.diagram +{ + padding: 8px; + border: none; + border-spacing: 2px; +} + +td.transparentblock +{ + text-align: center; + padding: 10px 0px; +} + +td.whiteblock +{ + width: 100px; + text-align: center; + border: 1px solid #C0C0C0; + background: #E0E0E0; + padding: 10px 0px; +} + +td.lightblock +{ + width: 100px; + text-align: center; + border: 1px solid #8888FF; + background: #BBBBFF; + padding: 20px 0px; +} + +td.darkblock +{ + width: 100px; + text-align: center; + background: #8888FF; + padding: 20px 0px; +} + +/* Settings for buttons. */ + +td.button +{ + background: #E0E0E0; + border: 1px outset #FFFFFF; + font-weight: bold; +} diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/troubleshooting.html b/third_party/java/proguard/proguard5.3.3/docs/manual/troubleshooting.html new file mode 100644 index 0000000000..81c49b53e1 --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/troubleshooting.html @@ -0,0 +1,933 @@ +<!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 Troubleshooting</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/troubleshooting.html">ProGuard index</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> <a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>') +//--> +</script> +<noscript> +<a class="largebutton" target="_top" href="../index.html#manual/troubleshooting.html">ProGuard index</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> +<a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a> +</noscript> + +<h2>Troubleshooting</h2> + +While preparing a configuration for processing your code, you may bump into a +few problems. The following sections discuss some common issues and solutions: + +<h3><a href="#processing">Problems while processing</a></h3> +<ul> +<li><a href="#dynamicalclass">Note: can't find dynamically referenced class ...</a></li> +<li><a href="#dynamicalclasscast">Note: ... calls '(...)Class.forName(variable).newInstance()'</a></li> +<li><a href="#dynamicalclassmember">Note: ... accesses a field/method '...' dynamically</a></li> +<li><a href="#attributes">Note: ... calls 'Class.get...', 'Field.get...', or 'Method.get...'</a></li> +<li><a href="#unknownclass">Note: the configuration refers to the unknown class '...'</a></li> +<li><a href="#descriptorclass">Note: the configuration keeps the entry point '...', but not the descriptor class '...'</a></li> +<li><a href="#libraryclass">Note: the configuration explicitly specifies '...' to keep library class '...'</a></li> +<li><a href="#classmembers">Note: the configuration doesn't specify which class members to keep for class '...'</a></li> +<li><a href="#nosideeffects">Note: the configuration specifies that none of the methods of class '...' have any side effects</a></li> +<li><a href="#duplicateclass">Note: duplicate definition of program/library class</a></li> +<li><a href="#duplicatezipentry">Warning: can't write resource ... Duplicate zip entry</a></li> +<li><a href="#unresolvedclass">Warning: can't find superclass or interface</a></li> +<li><a href="#unresolvedclass">Warning: can't find referenced class</a></li> +<li><a href="#superclass">Error: Can't find any super classes of ... (not even immediate super class ...)</a></li> +<li><a href="#superclass">Error: Can't find common super class of ... and ...</a></li> +<li><a href="#unresolvedprogramclassmember">Warning: can't find referenced field/method '...' in program class ...</a></li> +<li><a href="#unresolvedlibraryclassmember">Warning: can't find referenced field/method '...' in library class ...</a></li> +<li><a href="#unresolvedenclosingmethod">Warning: can't find enclosing class/method</a></li> +<li><a href="#dependency">Warning: library class ... depends on program class ...</a></li> +<li><a href="#unexpectedclass">Warning: class file ... unexpectedly contains class ...</a></li> +<li><a href="#mappingconflict1">Warning: ... is not being kept as ..., but remapped to ...</a></li> +<li><a href="#mappingconflict2">Warning: field/method ... can't be mapped to ...</a></li> +<li><a href="#unsupportedclassversion">Error: Unsupported class version number</a></li> +<li><a href="#keep">Error: You have to specify '-keep' options</a></li> +<li><a href="#filename">Error: Expecting class path separator ';' before 'Files\Java\...' (in Windows)</a></li> +<li><a href="#macosx">Error: Can't read [.../lib/rt.jar] (No such file or directory) (in MacOS X)</a></li> +<li><a href="#cantread">Error: Can't read ...</a></li> +<li><a href="#cantwrite">Error: Can't write ...</a></li> +<li><a href="#startinggui">Internal problem starting the ProGuard GUI (Cannot write XdndAware property) (in Linux)</a></li> +<li><a href="#outofmemoryerror">OutOfMemoryError</a></li> +<li><a href="#stackoverflowerror">StackOverflowError</a></li> +<li><a href="#unexpectederror">Unexpected error</a></li> +<li><a href="#otherwise">Otherwise...</a></li> +</ul> + +<h3><a href="#afterprocessing">Unexpected observations after processing</a></h3> +<ul> +<li><a href="#disappearingclasses">Disappearing classes</a></li> +<li><a href="#notkept">Classes or class members not being kept</a></li> +<li><a href="#notobfuscated">Variable names not being obfuscated</a></li> +</ul> + +<h3><a href="#dalvik">Problems while converting to Android Dalvik bytecode</a></h3> + +<ul> +<li><a href="#simexception">SimException: local variable type mismatch</a></li> +<li><a href="#conversionerror">Conversion to Dalvik format failed with error 1</a></li> +</ul> + +<h3><a href="#preverifying">Problems while preverifying for Java Micro Edition</a></h3> + +<ul> +<li><a href="#invalidclassexception1">InvalidClassException, class loading error, or verification error</a></li> +</ul> + +<h3><a href="#runtime">Problems at run-time</a></h3> +<ul> +<li><a href="#stacktraces">Stack traces without class names or line numbers</a></li> +<li><a href="#noclassdeffounderror">NoClassDefFoundError</a></li> +<li><a href="#classnotfoundexception">ClassNotFoundException</a></li> +<li><a href="#nosuchfieldexception">NoSuchFieldException</a></li> +<li><a href="#nosuchmethodexception">NoSuchMethodException</a></li> +<li><a href="#missingresourceexception">MissingResourceException or NullPointerException</a></li> +<li><a href="#disappearingannotations">Disappearing annotations</a></li> +<li><a href="#invalidjarfile">Invalid or corrupt jarfile</a></li> +<li><a href="#invalidjarindexexception">InvalidJarIndexException: Invalid index</a></li> +<li><a href="#invalidclassexception2">InvalidClassException, class loading error, or verification error (in Java Micro Edition)</a></li> +<li><a href="#nosuchfieldormethod">Error: No Such Field or Method, Error verifying method (in a Java Micro Edition emulator)</a></li> +<li><a href="#failingmidlets">Failing midlets (on a Java Micro Edition device)</a></li> +<li><a href="#disappearingloops">Disappearing loops</a></li> +<li><a href="#securityexception">SecurityException: SHA1 digest error</a></li> +<li><a href="#classcastexception">ClassCastException: class not an enum</a></li><li><a href="#classcastexception">IllegalArgumentException: class not an enum type</a></li> +<li><a href="#arraystoreexception">ArrayStoreException: sun.reflect.annotation.EnumConstantNotPresentExceptionProxy</a></li> +<li><a href="#illegalargumentexception">IllegalArgumentException: methods with same signature but incompatible return types</a></li> +<li><a href="#compilererror">CompilerError: duplicate addition</a></li> +<li><a href="#classformaterror1">ClassFormatError: repetitive field name/signature</a></li> +<li><a href="#classformaterror2">ClassFormatError: Invalid index in LocalVariableTable in class file</a></li> +<li><a href="#nosuchmethoderror">NoSuchMethodError or AbstractMethodError</a></li> +<li><a href="#verifyerror">VerifyError</a></li> +</ul> + + +<h2><a name="processing">Problems while processing</a></h2> + +ProGuard may print out some notes and non-fatal warnings: + +<dl> +<dt><a name="dynamicalclass"><b>Note: can't find dynamically referenced class ...</b></a></dt> + +<dd>ProGuard can't find a class or interface that your code is accessing by + means of introspection. You should consider adding the jar that contains + this class.</dd> + +<dt><a name="dynamicalclasscast"><b>Note: ... calls '(...)Class.forName(variable).newInstance()'</b></a></dt> + +<dd>Your code uses reflection to dynamically create class instances, with a + construct like + "<code>(MyClass)Class.forName(variable).newInstance()</code>". Depending + on your application, you may need to keep the mentioned classes with an + option like "<code>-keep class MyClass</code>", or their implementations + with an option like "<code>-keep class * implements MyClass</code>". You + can switch off these notes by specifying the + <a href="usage.html#dontnote"><code>-dontnote</code></a> option.</dd> + +<dt><a name="dynamicalclassmember"><b>Note: ... accesses a field/method '...' dynamically</b></a></dt> + +<dd>Your code uses reflection to find a fields or a method, with a construct + like "<code>.getField("myField")</code>". Depending on your application, + you may need to figure out where the mentioned class members are defined + and keep them with an option like "<code>-keep class MyClass { MyFieldType + myField; }</code>". Otherwise, ProGuard might remove or obfuscate the + class members, since it can't know which ones they are exactly. It does + list possible candidates, for your information. You can switch off these + notes by specifying + the <a href="usage.html#dontnote"><code>-dontnote</code></a> option.</dd> + +<dt><a name="attributes"><b>Note: ... calls 'Class.get...'</b>, <b>'Field.get...'</b>, or <b>'Method.get...'</b></a></dt> +<dd>Your code uses reflection to access metadata from the code, with an + invocation like "<code>class.getAnnotations()</code>". You then generally + need to preserve optional <a href="attributes.html">class file + attributes</a>, which ProGuard removes by default. The attributes contain + information about annotations, enclosing classes, enclosing methods, etc. + In a summary in the log, ProGuard provides a suggested configuration, + like <a href="usage.html#keepattributes"><code>-keepattributes + *Annotation*</code></a>. If you're sure the attributes are not necessary, + you can switch off these notes by specifying + the <a href="usage.html#dontnote"><code>-dontnote</code></a> option.</dd> + +<dt><a name="unknownclass"><b>Note: the configuration refers to the unknown class '...'</b></a></dt> + +<dd>Your configuration refers to the name of a class that is not present in + the program jars or library jars. You should check whether the name is + correct. Notably, you should make sure that you always specify + fully-qualified names, not forgetting the package names.</dd> + +<dt><a name="descriptorclass"><b>Note: the configuration keeps the entry point '...', but not the descriptor class '...'</b></a></dt> + +<dd>Your configuration contains a <code>-keep</code> option to preserve the + given method (or field), but no <code>-keep</code> option for the given + class that is an argument type or return type in the method's descriptor. + You may then want to keep the class too. Otherwise, ProGuard will + obfuscate its name, thus changing the method's signature. The method might + then become unfindable as an entry point, e.g. if it is part of a public + API. You can automatically keep such descriptor classes with + the <code>-keep</code> option modifier + <a href="usage.html#includedescriptorclasses"><code>includedescriptorclasses</code></a> + (<code>-keep,includedescriptorclasses</code> ...). You can switch off + these notes by specifying + the <a href="usage.html#dontnote"><code>-dontnote</code></a> option.</dd> + +<dt><a name="libraryclass"><b>Note: the configuration explicitly specifies '...' to keep library class '...'</b></a></dt> + +<dd>Your configuration contains a <code>-keep</code> option to preserve the + given library class. However, you don't need to keep any library classes. + ProGuard always leaves underlying libraries unchanged. You can switch off + these notes by specifying the + <a href="usage.html#dontnote"><code>-dontnote</code></a> option.</dd> + +<dt><a name="classmembers"><b>Note: the configuration doesn't specify which class members to keep for class '...'</b></a></dt> + +<dd>Your configuration contains a + <a href="usage.html#keepclassmembers"><code>-keepclassmembers</code></a>/<a href="usage.html#keepclasseswithmembers"><code>-keepclasseswithmembers</code></a> + option to preserve fields or methods in the given class, but it doesn't + specify which fields or methods. This way, the option simply won't have + any effect. You probably want to specify one or more fields or methods, as + usual between curly braces. You can specify all fields or methods with a + wildcard "<code>*;</code>". You should also consider if you just need the + more common <a href="usage.html#keep"><code>-keep</code></a> option, which + preserves all specified classes <i>and</i> class members. + The <a href="usage.html#keepoverview">overview of all <code>keep</code> + options</a> can help. You can switch off these notes by specifying + the <a href="usage.html#dontnote"><code>-dontnote</code></a> option.</dd> + +<dt><a name="nosideeffects"><b>Note: the configuration specifies that none of the methods of class '...' have any side effects</b></a></dt> + +<dd>Your configuration contains an option + <a href="usage.html#assumenosideeffects"><code>-assumenosideeffects</code></a> + to indicate that the specified methods don't have any side effects. + However, the configuration tries to match <i>all</i> methods, by using a + wildcard like "<code>*;</code>". This includes methods + from <code>java.lang.Object</code>, such as <code>wait()</code> and + <code>notify()</code>. Removing invocations of those methods will most + likely break your application. You should list the methods without side + effects more conservatively. You can switch off these notes by specifying + the <a href="usage.html#dontnote"><code>-dontnote</code></a> option.</dd> + +<dt><a name="duplicateclass"><b>Note: duplicate definition of program/library class</b></a></dt> + +<dd>Your program jars or library jars contain multiple definitions of the + listed classes. ProGuard continues processing as usual, only considering + the first definitions. The warning may be an indication of some problem + though, so it's advisable to remove the duplicates. A convenient way to do + so is by specifying filters on the input jars or library jars. You can + switch off these notes by specifying the <a + href="usage.html#dontnote"><code>-dontnote</code></a> option. + <p> + <img class="float" src="android_small.png" width="32" height="32" + alt="android" /> The standard Android build process automatically + specifies the input jars for you. There may not be an easy way to filter + them to remove these notes. You could remove the duplicate classes + manually from your libraries. You should never explicitly specify the + input jars yourself (with <code>-injars</code> or + <code>-libraryjars</code>), since you'll then get duplicate definitions. + You should also not add libraries to your application that are already + part of the Android run-time (notably <code>org.w3c.dom</code>, + <code>org.xml.sax</code>, <code>org.xmlpull.v1</code>, + <code>org.apache.commons.logging.Log</code>, <code>org.apache.http</code>, + and <code>org.json</code>). They are possibly inconsistent, and the + run-time libraries would get precedence anyway.</dd> + +<dt><a name="duplicatezipentry"><b>Warning: can't write resource ... Duplicate zip entry</b></a></dt> + +<dd>Your input jars contain multiple resource files with the same name. + ProGuard continues copying the resource files as usual, skipping any files + with previously used names. Once more, the warning may be an indication of + some problem though, so it's advisable to remove the duplicates. A + convenient way to do so is by specifying filters on the input jars. There + is no option to switch off these warnings. + <p> + <img class="float" src="android_small.png" width="32" height="32" + alt="android" /> The standard Android build process automatically + specifies the input jars for you. There may not be an easy way to filter + them to remove these warnings. You could remove the duplicate resource files + manually from the input and the libraries.</dd> + +</dl> +<p> + +ProGuard may terminate when it encounters parsing errors or I/O errors, or +some more serious warnings: + +<dl> +<dt><a name="unresolvedclass"><b>Warning: can't find superclass or interface</b><br/><b>Warning: can't find referenced class</b></a></dt> + +<dd>A class in one of your program jars or library jars is referring to a + class or interface that is missing from the input. The warning lists both + the referencing class(es) and the missing referenced class(es). There can + be a few reasons, with their own solutions: + <p> + <ol> + <li>If the missing class is referenced from your own code, you may have + forgotten to specify an essential library. Just like when compiling + all code from scratch, you must specify all libraries that the code is + referencing, directly or indirectly. If the library should be + processed and included in the output, you should specify it with + <a href="usage.html#injars"><code>-injars</code></a>, otherwise you + should specify it with + <a href="usage.html#libraryjars"><code>-libraryjars</code></a>. + <p> + For example, if ProGuard complains that it can't find a + <code>java.lang</code> class, you have to make sure that you are + specifying the run-time library of your platform. For JSE, these are + typically packaged in <code>lib/rt.jar</code> (<code>vm.jar</code> for + IBM's JVM, and <code>classes.jar</code> in MacOS X). Other platforms + like JME and Android have their own run-time libraries. + The <a href="examples.html">examples section</a> provides more details + for the various platforms. + <p> + If ProGuard still complains that it can't find a + <code>javax.crypto</code> class, you probably still have to specify + <code>jce.jar</code>, next to the more common <code>rt.jar</code>.</li> + <li>If the missing class is referenced from a pre-compiled third-party + library, and your original code runs fine without it, then the missing + dependency doesn't seem to hurt. The cleanest solution is to + <a href="usage.html#filters">filter out</a> the <i>referencing</i> + class or classes from the input, with a filter like "<code>-libraryjars + mylibrary.jar(!somepackage/SomeUnusedReferencingClass.class)</code>". + ProGuard will then skip this class entirely in the input, and it will + not bump into the problem of its missing reference. However, you may + then have to filter out other classes that are in turn referencing the + removed class. In practice, this works best if you can filter out + entire unused packages at once, with a wildcard filter like + "<code>-libraryjars + mylibrary.jar(!someunusedpackage/**)</code>".<p></li> + <li>If you don't feel like filtering out the problematic classes, you can + try your luck with the <a + href="usage.html#ignorewarnings"><code>-ignorewarnings</code></a> + option, or even + the <a href="usage.html#dontwarn"><code>-dontwarn</code></a> option. + Only use these options if you really know what you're doing though.</li> + </ol> + <p> + <img class="float" src="android_small.png" width="32" height="32" + alt="android" /> The standard Android build process automatically + specifies the input jars for you. Unfortunately, many pre-compiled + third-party libraries refer to other libraries that are not actually used + and therefore not present. This works fine in debug builds, but in release + builds, ProGuard expects all libraries, so it can perform a proper static + analysis. For example, if ProGuard complains that it can't find + a <code>java.awt</code> class, then some library that you are using is + referring to <code>java.awt</code>. This is a bit shady, since Android + doesn't have this package at all, but if your application works anyway, + you can let ProGuard accept it with "<code>-dontwarn java.awt.**</code>", + for instance. + <p> + If the missing class is an Android run-time class, you should make sure + that you are building against an Android run-time that is sufficiently + recent. You may need to change the build target in your + <code>project.properties</code> file or <code>build.gradle</code> file to + that recent version. You can still specify a different + <code>minSdkVersion</code> and a different <code>targetSdkVersion</code> + in your <code>AndroidManifest.xml</code> file.</dd> + +<dt><a name="superclass"><b>Error: Can't find any super classes of ... (not even immediate super class ...)</b><br/><b>Error: Can't find common super class of ... and ...</b></a></dt> + +<dd>It seems like you tried to avoid the warnings from the previous paragraph + by specifying + <a href="usage.html#ignorewarnings"><code>-ignorewarnings</code></a> + or <a href="usage.html#dontwarn"><code>-dontwarn</code></a>, but it didn't + work out. ProGuard's optimization step and preverification step really + need the missing classes to make sense of the code. Preferably, you would + solve the problem by adding the missing library, as discussed. If you're + sure the class that references the missing class isn't used either, you + could also try filtering it out from the input, by adding a filter to the + corresponding <a href="usage.html#injars"><code>-injars</code></a> option: + "<code>-injars + myapplication.jar(!somepackage/SomeUnusedClass.class)</code>". As a final + solution, you could switch off optimization + (<a href="usage.html#dontoptimize"><code>-dontoptimize</code></a>) and + preverification + (<a href="usage.html#dontpreverify"><code>-dontpreverify</code></a>).</dd> + +<dt><a name="unresolvedprogramclassmember"><b>Warning: can't find referenced field/method '...' in program class ...</b></a></dt> + +<dd>A program class is referring to a field or a method that is missing from + another program class. The warning lists both the referencing class and + the missing referenced class member. Your compiled class files are most + likely inconsistent. Possibly, some class file didn't get recompiled + properly, or some class file was left behind after its source file was + removed. Try removing all compiled class files and rebuilding your + project.</dd> + +<dt><a name="unresolvedlibraryclassmember"><b>Warning: can't find referenced field/method '...' in library class ...</b></a></dt> + +<dd>A program class is referring to a field or a method that is missing from a + library class. The warning lists both the referencing class and the + missing referenced class member. Your compiled class files are + inconsistent with the libraries. You may need to recompile the class + files, or otherwise upgrade the libraries to consistent versions. + <p> + <img class="float" src="android_small.png" width="32" height="32" + alt="android" /> If you're developing for Android and ProGuard complains + that it can't find a method that is only available in a recent version of + the Android run-time, you should change the build target in your + <code>project.properties</code> file or <code>build.gradle</code> file to + that recent version. You can still specify a different + <code>minSdkVersion</code> and a different <code>targetSdkVersion</code> + in your <code>AndroidManifest.xml</code> file. + <p> + Alternatively, you may get away with ignoring the inconsistency with the + options + <a href="usage.html#ignorewarnings"><code>-ignorewarnings</code></a> or + even + <a href="usage.html#dontwarn"><code>-dontwarn</code></a>. For instance, you + can specify "<code>-dontwarn mypackage.MyInconsistentClass</code>". + <p> + Finally, should your program classes reside in the same packages as + library classes and should they refer to their package visible class + members, then you should also specify the + <a href="usage.html#dontskipnonpubliclibraryclassmembers"><code>-dontskipnonpubliclibraryclassmembers</code></a> + option.</dd> + +<dt><a name="unresolvedenclosingmethod"><b>Warning: can't find enclosing class/method</b></a></dt> + +<dd>If there are unresolved references to classes that are defined inside + methods in your input, once more, your compiled class files are most likely + inconsistent. Possibly, some class file didn't get recompiled properly, or + some class file was left behind after its source file was removed. Try + removing all compiled class files and rebuilding your project.</dd> + +<dt><a name="dependency"><b>Warning: library class ... depends on program class ...</b></a></dt> + +<dd>If any of your library classes depend on your program classes, by + extending, implementing or just referencing them, your processed code will + generally be unusable. Program classes can depend on library classes, but + not the other way around. Program classes are processed, while library + classes always remain unchanged. It is therefore impossible to adapt + references from library classes to program classes, for instance if the + program classes are renamed. You should define a clean separation between + program code (specified with <a + href="usage.html#injars"><code>-injars</code></a>) and library code + (specified with <a + href="usage.html#libraryjars"><code>-libraryjars</code></a>), and try + again. + <p> + <img class="float" src="android_small.png" width="32" height="32" + alt="android" /> In Android development, sloppy libraries may contain + duplicates of classes that are already present in the Android run-time + (notably <code>org.w3c.dom</code>, <code>org.xml.sax</code>, + <code>org.xmlpull.v1</code>, <code>org.apache.commons.logging.Log</code>, + <code>org.apache.http</code>, and <code>org.json</code>). You must remove + these classes from your libraries, since they are possibly inconsistent, + and the run-time libraries would get precedence anyway.</dd> + +<dt><a name="unexpectedclass"><b>Warning: class file ... unexpectedly contains class ...</b></a></dt> + +<dd>The given class file contains a definition for the given class, but the + directory name of the file doesn't correspond to the package name of the + class. ProGuard will accept the class definition, but the current + implementation will not write out the processed version. Please make sure + your input classes are packaged correctly. Notably, class files that are + in the <code>WEB-INF/classes</code> directory in a war should be packaged + in a jar and put in the <code>WEB-INF/lib</code> directory. If you don't + mind these classes not being written to the output, you can specify the <a + href="usage.html#ignorewarnings"><code>-ignorewarnings</code></a> option, + or even the <a href="usage.html#dontwarn"><code>-dontwarn</code></a> + option.</dd> + +<dt><a name="mappingconflict1"><b>Warning: ... is not being kept as ..., but remapped to ...</b></a></dt> + +<dd>There is a conflict between a <code>-keep</code> option in the + configuration, and the mapping file, in the obfuscation step. The given + class name or class member name can't be kept by its original name, as + specified in the configuration, but it has to be mapped to the other given + name, as specified in the mapping file. You should adapt your + configuration or your mapping file to remove the conflict. Alternatively, + if you're sure the renaming won't hurt, you can specify the <a + href="usage.html#ignorewarnings"><code>-ignorewarnings</code></a> option, + or even the <a href="usage.html#dontwarn"><code>-dontwarn</code></a> + option.</dd> + +<dt><a name="mappingconflict2"><b>Warning: field/method ... can't be mapped to ...</b></a></dt> + +<dd>There is a conflict between some new program code and the mapping file, in + the obfuscation step. The given class member can't be mapped to the given + name, because it would conflict with another class member that is already + being mapped to the same name. This can happen if you are performing + incremental obfuscation, applying an obfuscation mapping file from an + initial obfuscation step. For instance, some new class may have been added + that extends two existing classes, introducing a conflict in the name + space of its class members. If you're sure the class member receiving + another name than the one specified won't hurt, you can specify the <a + href="usage.html#ignorewarnings"><code>-ignorewarnings</code></a> option, + or even the <a href="usage.html#dontwarn"><code>-dontwarn</code></a> + option. Note that you should always use the <a + href="usage.html#useuniqueclassmembernames"><code>-useuniqueclassmembernames</code></a> + option in the initial obfuscation step, in order to reduce the risk of + conflicts.</dd> + +<dt><a name="unsupportedclassversion"><b>Error: Unsupported class version number</b></a></dt> + +<dd>You are trying to process class files compiled for a recent version of + Java that your copy of ProGuard doesn't support yet. You + should <a href="http://proguard.sourceforge.net/downloads.html">check + on-line</a> if there is a more recent release.</dd> + +<dt><a name="keep"><b>Error: You have to specify '-keep' options</b></a></dt> + +<dd>You either forgot to specify <a + href="usage.html#keep"><code>-keep</code></a> options, or you mistyped the + class names. ProGuard has to know exactly what you want to keep: an + application, an applet, a servlet, a midlet,..., or any combination of + these. Without the proper seed specifications, ProGuard would shrink, + optimize, or obfuscate all class files away.</dd> + +<dt><a name="filename"><b>Error: Expecting class path separator ';' before 'Files\Java\</b>...<b>'</b> (in Windows)</a></dt> + +<dd>If the path of your run-time jar contains spaces, like in "Program Files", + you have to enclose it with single or double quotes, as explained in the + section on <a href="usage.html#filename">file names</a>. This is actually + true for all file names containing special characters, on all + platforms.</dd> + +<dt><a name="macosx"><b>Error: Can't read [</b>...<b>/lib/rt.jar] (No such file or directory)</b> (in MacOS X)</a></dt> + +<dd>In MacOS X, the run-time classes may be in a different place than on most + other platforms. You'll then have to adapt your configuration, replacing + the path <code><java.home>/lib/rt.jar</code> by + <code><java.home>/../Classes/classes.jar</code>.</dd> + +<dt><a name="cantread"><b>Error: Can't read ...</b></a></dt> + +<dd>ProGuard can't read the specified file or directory. Double-check that the + name is correct in your configuration, that the file is readable, and that + it is not corrupt. An additional message "Unexpected end of ZLIB input + stream" suggests that the file is truncated. You should then make sure + that the file is complete on disk when ProGuard starts (asynchronous + copying? unflushed buffer or cache?), and that it is not somehow + overwritten by ProGuard's own output.</dd> + +<dt><a name="cantwrite"><b>Error: Can't write ...</b></a></dt> + +<dd>ProGuard can't write the specified file or directory. Double-check that + the name is correct in your configuration and that the file is + writable.</dd> + +<dt><a name="startinggui"><b>Internal problem starting the ProGuard GUI (Cannot write XdndAware property)</b> (in Linux)</a></dt> + +<dd>In Linux, at least with Java 6, the GUI may not start properly, due to + <a href="http://bugs.sun.com/view_bug.do?bug_id=7027598">Sun + Bug #7027598</a>. The work-around at this time is to specify the JVM + option <code>-DsuppressSwingDropSupport=true</code> when running the + GUI.</dd> + +</dl> +<p> + +Should ProGuard crash while processing your application: + +<dl> +<dt><a name="outofmemoryerror"><b>OutOfMemoryError</b></a></dt> + +<dd>You can try increasing the heap size of the Java virtual machine, with the + usual <code>-Xmx</code> option: + <ul> + <li>In Java, specify the option as an argument to the JVM: <code>java + -Xmx1024m</code> ... + <li>In Ant, set the environment variable <code>ANT_OPTS=-Xmx1024m</code> + <li>In Gradle, set the environment variable + <code>GRADLE_OPTS=-Xmx1024m</code> + <li>In Maven, set the environment variable + <code>MAVEN_OPTS=-Xmx1024m</code> + <li>In Eclipse, add the line <code>-Xmx1024m</code> to the file + <code>eclipse.ini</code> inside your Eclipse install. + </ul> + You can also reduce the amount of memory that ProGuard needs by removing + unnecessary library jars from your configuration, or by filtering out + unused library packages and classes.</dd> + +<dt><a name="stackoverflowerror"><b>StackOverflowError</b></a></dt> + +<dd>This error might occur when processing a large code base on Windows + (surprisingly, not so easily on Linux). In theory, increasing the stack + size of the Java virtual machine (with the usual <code>-Xss</code> option) + should help too. In practice however, the <code>-Xss</code> setting + doesn't have any effect on the main thread, due to <a + href="http://bugs.sun.com/view_bug.do?bug_id=4362291">Sun Bug + #4362291</a>. As a result, this solution will only work when running + ProGuard in a different thread, e.g. from its GUI.</dd> + +<dt><a name="unexpectederror"><b>Unexpected error</b></a></dt> + +<dd>ProGuard has encountered an unexpected condition, typically in the + optimization step. It may or may not recover. You should be able to avoid + it using the <a + href="usage.html#dontoptimize"><code>-dontoptimize</code></a> option. In + any case, please report the problem, preferably with the simplest example + that causes ProGuard to crash.</dd> + +<dt><a name="otherwise"><b>Otherwise...</b></a></dt> + +<dd>Maybe your class files are corrupt. See if recompiling them and trying + again helps. If not, please report the problem, preferably with the + simplest example that causes ProGuard to crash.</dd> + +</dl> +<p> + +<h2><a name="afterprocessing">Unexpected observations after processing</a></h2> + +If ProGuard seems to run fine, but your processed code doesn't look right, +there might be a couple of reasons: + +<dl> +<dt><a name="disappearingclasses"><b>Disappearing classes</b></a></dt> + +<dd>If you are working on Windows and it looks like some classes have + disappeared from your output, you should make sure you're not writing your + output class files to a directory (or unpacking the output jar). On + platforms with case-insensitive file systems, such as Windows, unpacking + tools often let class files with similar lower-case and upper-case names + overwrite each other. If you really can't switch to a different operating + system, you could consider using ProGuard's <a + href="usage.html#dontusemixedcaseclassnames"><code>-dontusemixedcaseclassnames</code></a> + option. + <p> + Also, you should make sure your class files are in directories that + correspond to their package names. ProGuard will read misplaced class + files, but it will currently not write their processed versions. Notably, + class files that are in the <code>WEB-INF/classes</code> directory in a + war should be packaged in a jar and put in the <code>WEB-INF/lib</code> + directory.</dd> + +<dt><a name="notkept"><b>Classes or class members not being kept</b></a></dt> + +<dd>If ProGuard is not keeping the right classes or class members, make sure + you are using fully qualified class names. If the package name of some + class is missing, ProGuard won't match the elements that you might be + expecting. It may help to double-check for typos too. You can use the <a + href="usage.html#printseeds"><code>-printseeds</code></a> option to see + which elements are being kept exactly. + <p> + If you are using marker interfaces to keep other classes, the marker + interfaces themselves are probably being removed in the shrinking step. + You should therefore always explicitly keep any marker interfaces, with + an option like "<code>-keep interface MyMarkerInterface</code>". + <p> + Similarly, if you are keeping classes based on annotations, you may have + to avoid that the annotation classes themselves are removed in the + shrinking step. You should package the annotation classes as a library, or + explicitly keep them in your program code with an option like "<code>-keep + @interface *</code>".</dd> + +<dt><a name="notobfuscated"><b>Variable names not being obfuscated</b></a></dt> + +<dd>If the names of the local variables and parameters in your obfuscated code + don't look obfuscated, because they suspiciously resemble the names of + their types, it's probably because the decompiler that you are using is + coming up with those names. ProGuard's obfuscation step does remove the + original names entirely, unless you explicitly keep the + <code>LocalVariableTable</code> or <code>LocalVariableTypeTable</code> + attributes.</dd> + +</dl> + +<h2><a name="dalvik">Problems while converting to Android Dalvik bytecode</a></h2> + +If ProGuard seems to run fine, but the dx tool in the Android SDK subsequently +fails with an error: + +<dl> +<dt><a name="simexception"><b>SimException: local variable type mismatch</b></a></dt> + +<dd>This error indicates that ProGuard's optimization step has not been able + to maintain the correct debug information about local variables. This can + happen if some code is optimized radically. Possible work-arounds: let the + java compiler not produce debug information (<code>-g:none</code>), or let + ProGuard's obfuscation step remove the debug information again + (by <i>not</i> keeping the attributes <code>LocalVariableTable</code> + and <code>LocalVariableTypeTable</code> + with <a href="usage.html#keepattributes"><code>-keepattributes</code></a>), + or otherwise just disable optimization + (<a href="usage.html#dontoptimize"><code>-dontoptimize</code></a>).</dd> + +<dt><a name="conversionerror"><b>Conversion to Dalvik format failed with error 1</b></a></dt> + +<dd>This error may have various causes, but if dx is tripping over some code + processed by ProGuard, you should make sure that you are using the latest + version of ProGuard. You can just copy the ProGuard jars + to <code>android-sdk/tools/proguard/lib</code>. If that doesn't help, + please report the problem, preferably with the simplest example that still + brings out the error.</dd> + +</dl> + +<h2><a name="preverifying">Problems while preverifying for Java Micro Edition</a></h2> + +If ProGuard seems to run fine, but the external preverifier subsequently +produces errors, it's usually for a single reason: + +<dl> +<dt><a name="invalidclassexception1"><b>InvalidClassException</b>, <b>class loading error</b>, or <b>verification error</b></a></dt> + +<dd>If you get any such message from the preverifier, you are probably working + on a platform with a case-insensitive file system, such as Windows. The + <code>preverify</code> tool always unpacks the jars, so class files with + similar lower-case and upper-case names overwrite each other. You can use + ProGuard's <a + href="usage.html#dontusemixedcaseclassnames"><code>-dontusemixedcaseclassnames</code></a> + option to work around this problem. + <p> + If the above doesn't help, there is probably a bug in the optimization + step of ProGuard. Make sure you are using the latest version. You should + be able to work around the problem by using the <a + href="usage.html#dontoptimize"><code>-dontoptimize</code></a> option. You + can check the bug database to see if it is a known problem (often with a + fix). Otherwise, please report it, preferably with the simplest example on + which you can find ProGuard to fail.</dd> + +</dl> + +Note that it is no longer necessary to use an external preverifier. With the +<a href="usage.html#microedition"><code>-microedition</code></a> option, +ProGuard will preverify the class files for Java Micro Edition. +<p> + +<h2><a name="runtime">Problems at run-time</a></h2> + +If ProGuard runs fine, but your processed application doesn't work, there +might be several reasons: + +<dl> +<dt><a name="stacktraces"><b>Stack traces without class names or line numbers</b></a></dt> + +<dd>If your stack traces don't contain any class names or lines numbers, + even though you are keeping the proper attributes, make sure this debugging + information is present in your compiled code to start with. Notably the Ant + javac task has debugging information switched off by default.</dd> + +<dt><a name="noclassdeffounderror"><b>NoClassDefFoundError</b></a></dt> + +<dd>Your class path is probably incorrect. It should at least contain all + library jars and, of course, your processed program jar.</dd> + +<dt><a name="classnotfoundexception"><b>ClassNotFoundException</b></a></dt> + +<dd>Your code is probably calling <code>Class.forName</code>, trying to create + the missing class dynamically. ProGuard can only detect constant name + arguments, like <code>Class.forName("mypackage.MyClass")</code>. For + variable name arguments like <code>Class.forName(someClass)</code>, you + have to keep all possible classes using the appropriate <a + href="usage.html#keep"><code>-keep</code></a> option, e.g. "<code>-keep + class mypackage.MyClass</code>" or "<code>-keep class * implements + mypackage.MyInterface</code>".</dd> + +<dt><a name="nosuchfieldexception"><b>NoSuchFieldException</b></a></dt> + +<dd>Your code is probably calling something like + <code>myClass.getField</code>, trying to find some field dynamically. + Since ProGuard can't always detect this automatically, you have to keep + the missing field in using the + appropriate <a href="usage.html#keep"><code>-keep</code></a> option, e.g. + "<code>-keepclassmembers class mypackage.MyClass { int myField; + }</code>".</dd> + +<dt><a name="nosuchmethodexception"><b>NoSuchMethodException</b></a></dt> + +<dd>Your code is probably calling something like + <code>myClass.getMethod</code>, trying to find some method dynamically. + Since ProGuard can't always detect this automatically, you have to keep + the missing method in using the + appropriate <a href="usage.html#keep"><code>-keep</code></a> option, e.g. + "<code>-keepclassmembers class mypackage.MyClass { void myMethod(); + }</code>". + <p> + More specifically, if the method reported as missing is + <code>values</code> or <code>valueOf</code>, you probably have to keep + some methods related to <a + href="examples.html#enumerations">enumerations</a>.</dd> + +<dt><a name="missingresourceexception"><b>MissingResourceException</b> or <b>NullPointerException</b></a></dt> + +<dd>Your processed code may be unable to find some resource files. ProGuard + simply copies resource files over from the input jars to the output jars. + Their names and contents remain unchanged, unless you specify the options + <a + href="usage.html#adaptresourcefilenames"><code>-adaptresourcefilenames</code></a> + and/or <a + href="usage.html#adaptresourcefilecontents"><code>-adaptresourcefilecontents</code></a>. + <p> + Furthermore, directory entries in jar files aren't copied, unless you + specify the option <a + href="usage.html#keepdirectories"><code>-keepdirectories</code></a>. + Note that Sun advises against calling <code>Class.getResource()</code> for + directories (<a href="http://bugs.sun.com/view_bug.do?bug_id=4761949">Sun + Bug #4761949</a>).</dd> + +<dt><a name="disappearingannotations"><b>Disappearing annotations</b></a></dt> + +<dd>By default, the obfuscation step removes all annotations. If your + application relies on annotations to function properly, you should + explicitly keep them with + <code><a href="usage.html#keepattributes">-keepattributes</a> + *Annotation*</code>.</dd> + +<dt><a name="invalidjarfile"><b>Invalid or corrupt jarfile</b></a></dt> + +<dd>You are probably starting your application with the java option + <code>-jar</code> instead of the option <code>-classpath</code>. The java + virtual machine returns with this error message if your jar doesn't + contain a manifest file (<code>META-INF/MANIFEST.MF</code>), if the + manifest file doesn't specify a main class (<code>Main-Class:</code> ...), + or if the jar doesn't contain this main class. You should then make sure + that the input jar contains a valid manifest file to start with, that this + manifest file is the one that is copied (the first manifest file that is + encountered), and that the main class is kept in your configuration,</dd> + +<dt><a name="invalidjarindexexception"><b>InvalidJarIndexException: Invalid index</b></a></dt> + +<dd>At least one of your processed jar files contains an index file + <code>META-INF/INDEX.LIST</code>, listing all class files in the jar. + ProGuard by default copies files like these unchanged. ProGuard may however + remove or rename classes, thus invalidating the file. You should filter the + index file out of the input + (<code>-injars in.jar(!META-INF/INDEX.LIST)</code>) or update the file + after having applied ProGuard (<code>jar -i out.jar</code>). + </dd> + +<dt><a name="invalidclassexception2"><b>InvalidClassException</b>, <b>class loading error</b>, or <b>verification error</b> (in Java Micro Edition)</a></dt> + +<dd>If you get such an error in Java Micro Edition, you may have forgotten to + specify the <a + href="usage.html#microedition"><code>-microedition</code></a> option, so + the processed class files are preverified properly.</dd> + +<dt><a name="nosuchfieldormethod"><b>Error: No Such Field or Method</b>, <b>Error verifying method</b> (in a Java Micro Edition emulator)</a></dt> + +<dd>If you get such a message in a Motorola or Sony Ericsson phone emulator, + it's because these emulators don't like packageless classes and/or + overloaded fields and methods. You can work around it by not using the + options <code><a href="usage.html#repackageclasses">-repackageclasses</a> + ''</code> and <a + href="usage.html#overloadaggressively"><code>-overloadaggressively</code></a>. + If you're using the JME WTK plugin, you can adapt the configuration + <code>proguard/wtk/default.pro</code> that's inside the + <code>proguard.jar</code>.</dd> + +<dt><a name="failingmidlets"><b>Failing midlets</b> (on a Java Micro Edition device)</a></dt> + +<dd>If your midlet runs in an emulator and on some devices, but not on some + other devices, this is probably due to a bug in the latter devices. For + some older Motorola and Nokia phones, you might try specifying the <a + href="usage.html#useuniqueclassmembernames"><code>-useuniqueclassmembernames</code></a> + option. It avoids overloading class member names, which triggers a bug in + their java virtual machine. + <p> + You might also try using the <a + href="usage.html#dontusemixedcaseclassnames"><code>-dontusemixedcaseclassnames</code></a> + option. Even if the midlet has been properly processed and then + preverified on a case-sensitive file system, the device itself might not + like the mixed-case class names. Notably, the Nokia N-Gage emulator works + fine, but the actual device seems to exhibit this problem.</dd> + +<dt><a name="disappearingloops"><b>Disappearing loops</b></a></dt> + +<dd>If your code contains empty busy-waiting loops, ProGuard's optimization + step may remove them. More specifically, this happens if a loop + continuously checks the value of a non-volatile field that is changed in a + different thread. The specifications of the Java Virtual Machine require + that you always mark fields that are accessed across different threads + without further synchronization as <code>volatile</code>. If this is not + possible for some reason, you'll have to switch off optimization using the + <a href="usage.html#dontoptimize"><code>-dontoptimize</code></a> + option.</dd> + +<dt><a name="securityexception"><b>SecurityException: SHA1 digest error</b></a></dt> + +<dd>You may have forgotten to sign your program jar <i>after</i> having + processed it with ProGuard.</dd> + +<dt><a name="classcastexception"><b>ClassCastException: class not an enum</b>, or <br /><b>IllegalArgumentException: class not an enum type</b></a></dt> + +<dd>You should make sure you're preserving the special methods of enumeration + types, which the run-time environment calls by introspection. The required + options are shown in the <a + href="examples.html#enumerations">examples</a>.</dd> + +<dt><a name="arraystoreexception"><b>ArrayStoreException: sun.reflect.annotation.EnumConstantNotPresentExceptionProxy</b></a></dt> + +<dd>You are probably processing annotations involving enumerations. Again, you + should make sure you're preserving the special methods of the enumeration + type, as shown in the examples.</dd> + +<dt><a name="illegalargumentexception"><b>IllegalArgumentException: methods with same signature but incompatible return types</b></a></dt> + +<dd>You are probably running some code that has been obfuscated + with the <a + href="usage.html#overloadaggressively"><code>-overloadaggressively</code></a> + option. The class <code>java.lang.reflect.Proxy</code> can't handle + classes that contain methods with the same names and signatures, but + different return types. Its method <code>newProxyInstance</code> then + throws this exception. You can avoid the problem by not using the + option.</dd> + +<dt><a name="compilererror"><b>CompilerError: duplicate addition</b></a></dt> + +<dd>You are probably compiling or running some code that has been obfuscated + with the <a + href="usage.html#overloadaggressively"><code>-overloadaggressively</code></a> + option. This option triggers a bug in + <code>sun.tools.java.MethodSet.add</code> in Sun's JDK 1.2.2, which is + used for (dynamic) compilation. You should then avoid this option.</dd> + +<dt><a name="classformaterror1"><b>ClassFormatError: repetitive field name/signature</b></a></dt> + +<dd>You are probably processing some code that has been obfuscated before with + the <a + href="usage.html#overloadaggressively"><code>-overloadaggressively</code></a> + option. You should then use the same option again in the second processing + round.</dd> + +<dt><a name="classformaterror2"><b>ClassFormatError: Invalid index in LocalVariableTable in class file</b></a></dt> + +<dd>If you are keeping the <code>LocalVariableTable</code> or + <code>LocalVariableTypeTable</code> attributes, ProGuard's optimizing step + is sometimes unable to update them consistently. You should then let the + obfuscation step remove these attributes or disable the optimization + step.</dd> + +<dt><a name="nosuchmethoderror"><b>NoSuchMethodError</b> or <b>AbstractMethodError</b></a></dt> + +<dd>You should make sure you're not writing your output class files to a + directory on a platform with a case-insensitive file system, such as + Windows. Please refer to the section about <a + href="#disappearingclasses">disappearing classes</a> for details. + <p> + Furthermore, you should check whether you have specified your program jars + and library jars properly. Program classes can refer to library classes, + but not the other way around. + <p> + If all of this seems ok, perhaps there's a bug in ProGuard (gasp!). If so, + please report it, preferably with the simplest example on which you can + find ProGuard to fail.</dd> + +<dt><a name="verifyerror"><b>VerifyError</b></a></dt> + +<dd>Verification errors when executing a program are almost certainly the + result of a bug in the optimization step of ProGuard. Make sure you are + using the latest version. You should be able to work around the problem by + using the <a href="usage.html#dontoptimize"><code>-dontoptimize</code></a> + option. You can check the bug database to see if it is a known problem + (often with a fix). Otherwise, please report it, preferably with the + simplest example on which ProGuard fails.</dd> + +</dl> + +<hr /> +<address> +Copyright © 2002-2017 +<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.guardsquare.com/">GuardSquare</a>. +</address> +</body> +</html> diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/usage.html b/third_party/java/proguard/proguard5.3.3/docs/manual/usage.html new file mode 100644 index 0000000000..5ed5e6654c --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/usage.html @@ -0,0 +1,1271 @@ +<!doctype html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="content-type" content="text/html; charset=iso-8859-1"> +<meta http-equiv="content-style-type" content="text/css"> +<link rel="stylesheet" type="text/css" href="style.css"> +<title>ProGuard Usage</title> +</head> +<body> + +<script type="text/javascript" language="JavaScript"> +<!-- +if (window.self==window.top) + document.write('<a class="largebutton" target="_top" href="../index.html#manual/usage.html">ProGuard index</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> <a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>') +//--> +</script> +<noscript> +<a class="largebutton" target="_top" href="../index.html#manual/usage.html">ProGuard index</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> +<a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a> +</noscript> + +<h2>Usage</h2> + +To run ProGuard, just type: +<p class="code"> +<code><b>java -jar proguard.jar </b></code><i>options</i> ... +</p> +You can find the ProGuard jar in the <code>lib</code> directory of the +ProGuard distribution. Alternatively, the <code>bin</code> directory contains +some short Linux and Windows scripts containing this command. Typically, you'll +put most options in a configuration file (say, <code>myconfig.pro</code>), and +just call: +<p class="code"> +<code><b>java -jar proguard.jar @myconfig.pro</b></code> +</p> +You can combine command line options and options from configuration files. For +instance: +<p class="code"> +<code><b>java -jar proguard.jar @myconfig.pro -verbose</b></code> +</p> +<p> +You can add comments in a configuration file, starting with a +<code><b>#</b></code> character and continuing until the end of the line. +<p> +Extra whitespace between words and delimiters is ignored. File names with +spaces or special characters should be quoted with single or double quotes. +<p> +Options can be grouped arbitrarily in arguments on the command line and in +lines in configuration files. This means that you can quote arbitrary sections +of command line options, to avoid shell expansion of special characters, for +instance. +<p> +The order of the options is generally irrelevant. For quick experiments, you +can abbreviate them to their first unique characters. +<p> + +The sections below provide more details: +<ul> +<li><a href="#iooptions">Input/Output Options</a></li> +<li><a href="#keepoptions">Keep Options</a></li> +<li><a href="#shrinkingoptions">Shrinking Options</a></li> +<li><a href="#optimizationoptions">Optimization Options</a></li> +<li><a href="#obfuscationoptions">Obfuscation Options</a></li> +<li><a href="#preverificationoptions">Preverification Options</a></li> +<li><a href="#generaloptions">General Options</a></li> +<li><a href="#classpath">Class Paths</a></li> +<li><a href="#filename">File Names</a></li> +<li><a href="#filefilters">File Filters</a></li> +<li><a href="#filters">Filters</a></li> +<li><a href="#keepoverview">Overview of <code>Keep</code> Options</a></li> +<li><a href="#keepoptionmodifiers">Keep Option Modifiers</a></li> +<li><a href="#classspecification">Class Specifications</a></li> +</ul> + +<h2><a name="iooptions">Input/Output Options</a></h2> + +<dl> +<dt><a name="at"><code><b>@</b></code></a><a href="#filename"><i>filename</i></a></dt> + +<dd>Short for '<a href="#include"><code>-include</code></a> + <a href="#filename"><i>filename</i></a>'.</dd> + +<dt><a name="include"><code><b>-include</b></code></a> + <a href="#filename"><i>filename</i></a></dt> + +<dd>Recursively reads configuration options from the given file + <i>filename</i>.</dd> + +<dt><a name="basedirectory"><code><b>-basedirectory</b></code></a> + <a href="#filename"><i>directoryname</i></a></dt> + +<dd>Specifies the base directory for all subsequent relative file names in + these configuration arguments or this configuration file.</dd> + +<dt><a name="injars"><code><b>-injars</b></code></a> + <a href="#classpath"><i>class_path</i></a></dt> + +<dd>Specifies the input jars (or aars, wars, ears, zips, apks, or directories) + of the application to be processed. The class files in these jars will be + processed and written to the output jars. By default, any non-class files + will be copied without changes. Please be aware of any temporary files + (e.g. created by IDEs), especially if you are reading your input files + straight from directories. The entries in the class path can be filtered, + as explained in the <a href="#filefilters">filters</a> section. For better + readability, class path entries can be specified using multiple + <code>-injars</code> options.</dd> + +<dt><a name="outjars"><code><b>-outjars</b></code></a> + <a href="#classpath"><i>class_path</i></a></dt> + +<dd>Specifies the names of the output jars (or aars, wars, ears, zips, apks, + or directories). The processed input of the preceding <code>-injars</code> + options will be written to the named jars. This allows you to collect the + contents of groups of input jars into corresponding groups of output jars. + In addition, the output entries can be filtered, as explained in + the <a href="#filefilters">filters</a> section. Each processed class file + or resource file is then written to the first output entry with a matching + filter, within the group of output jars. + <p> + You must avoid letting the output files overwrite any input files. For + better readability, class path entries can be specified using multiple + <code>-outjars</code> options. Without any <code>-outjars</code> options, + no jars will be written.</dd> + +<dt><a name="libraryjars"><code><b>-libraryjars</b></code></a> + <a href="#classpath"><i>class_path</i></a></dt> + +<dd>Specifies the library jars (or aars, wars, ears, zips, apks, or + directories) of the application to be processed. The files in these jars + will not be included in the output jars. The specified library jars should + at least contain the class files that are <i>extended</i> by application + class files. Library class files that are only <i>called</i> needn't be + present, although their presence can improve the results of the + optimization step. The entries in the class path can be filtered, as + explained in the <a href="#filefilters">filters</a> section. For better + readability, class path entries can be specified using + multiple <code>-libraryjars</code> options. + <p> + Please note that the boot path and the class path set for running ProGuard + are not considered when looking for library classes. This means that you + explicitly have to specify the run-time jar that your code will use. + Although this may seem cumbersome, it allows you to process applications + targeted at different run-time environments. For example, you can process + <a href="examples.html#application">J2SE applications</a> as well as <a + href="examples.html#midlet">JME midlets</a> or <a + href="examples.html#androidapplication">Android apps</a>, just by + specifying the appropriate run-time jar.</dd> + +<dt><a name="skipnonpubliclibraryclasses"><code><b>-skipnonpubliclibraryclasses</b></code></a></dt> + +<dd>Specifies to skip non-public classes while reading library jars, to speed + up processing and reduce memory usage of ProGuard. By default, ProGuard + reads non-public and public library classes alike. However, non-public + classes are often not relevant, if they don't affect the actual program + code in the input jars. Ignoring them then speeds up ProGuard, without + affecting the output. Unfortunately, some libraries, including recent JSE + run-time libraries, contain non-public library classes that are extended + by public library classes. You then can't use this option. ProGuard will + print out warnings if it can't find classes due to this option being + set.</dd> + +<dt><a name="dontskipnonpubliclibraryclasses"><code><b>-dontskipnonpubliclibraryclasses</b></code></a></dt> + +<dd>Specifies not to ignore non-public library classes. As of version 4.5, this + is the default setting.</dd> + +<dt><a name="dontskipnonpubliclibraryclassmembers"><code><b>-dontskipnonpubliclibraryclassmembers</b></code></a></dt> + +<dd>Specifies not to ignore package visible library class members (fields and + methods). By default, ProGuard skips these class members while parsing + library classes, as program classes will generally not refer to them. + Sometimes however, program classes reside in the same packages as library + classes, and they do refer to their package visible class members. In + those cases, it can be useful to actually read the class members, in order + to make sure the processed code remains consistent.</dd> + +<dt><a name="keepdirectories"><code><b>-keepdirectories</b></code></a> + [<i><a href="#filefilters">directory_filter</a></i>]</dt> + +<dd>Specifies the directories to be kept in the output jars (or aars, wars, + ears, zips, apks, or directories). By default, directory entries are + removed. This reduces the jar size, but it may break your program if the + code tries to find them with constructs like + "<code>mypackage.MyClass.class.getResource("")</code>". You'll then want + to keep the directory corresponding to the package, + "<code>-keepdirectories mypackage</code>". If the option is specified + without a filter, all directories are kept. With a filter, only matching + directories are kept. For instance, + "<code>-keepdirectories mydirectory</code>" matches the specified + directory, "<code>-keepdirectories mydirectory/*</code>" matches its + immediate subdirectories, and + "<code>-keepdirectories mydirectory/**</code>" matches all of its + subdirectories.</dd> + +<dt><a name="target"><code><b>-target</b></code></a> <i>version</i></dt> + +<dd>Specifies the version number to be set in the processed class files. The + version number can be one of <code>1.0</code>, <code>1.1</code>, + <code>1.2</code>, <code>1.3</code>, <code>1.4</code>, <code>1.5</code> (or + just <code>5</code>), <code>1.6</code> (or just <code>6</code>), + <code>1.7</code> (or just <code>7</code>), or <code>1.8</code> (or + just <code>8</code>). By default, the version numbers of the class files + are left unchanged. For example, you may want to + <a href="examples.html#upgrade">upgrade class files to Java 6</a>, by + changing their version numbers and having them preverified. You probably + shouldn't downgrade the version numbers of class files, since the code + may contain constructs that are not supported in older versions.</dd> + +<dt><a name="forceprocessing"><code><b>-forceprocessing</b></code></a></dt> + +<dd>Specifies to process the input, even if the output seems up to date. The + up-to-dateness test is based on a comparison of the date stamps of the + specified input, output, and configuration files or directories.</dd> + +</dl> +<p> + +<h2><a name="keepoptions">Keep Options</a></h2> + +<dl> +<dt><a name="keep"><code><b>-keep</b></code></a> + [<a href="#keepoptionmodifiers">,<i>modifier</i></a>,...] + <a href="#classspecification"><i>class_specification</i></a></dt> + +<dd>Specifies classes and class members (fields and methods) to be preserved + as entry points to your code. For example, in order to <a + href="examples.html#application">keep an application</a>, you can specify + the main class along with its main method. In order to <a + href="examples.html#library">process a library</a>, you should specify all + publicly accessible elements.</dd> + +<dt><a name="keepclassmembers"><code><b>-keepclassmembers</b></code></a> + [<a href="#keepoptionmodifiers">,<i>modifier</i></a>,...] + <a href="#classspecification"><i>class_specification</i></a></dt> + +<dd>Specifies class members to be preserved, if their classes are preserved as + well. For example, you may want to <a + href="examples.html#serializable">keep all serialization fields and + methods</a> of classes that implement the <code>Serializable</code> + interface.</dd> + +<dt><a name="keepclasseswithmembers"><code><b>-keepclasseswithmembers</b></code></a> + [<a href="#keepoptionmodifiers">,<i>modifier</i></a>,...] + <a href="#classspecification"><i>class_specification</i></a></dt> + +<dd>Specifies classes and class members to be preserved, on the condition that + all of the specified class members are present. For example, you may want + to <a href="examples.html#applications">keep all applications</a> that + have a main method, without having to list them explicitly.</dd> + +<dt><a name="keepnames"><code><b>-keepnames</b></code></a> + <a href="#classspecification"><i>class_specification</i></a></dt> + +<dd>Short for <a href="#keep"><code>-keep</code></a>,<a href="#allowshrinking"><code>allowshrinking</code></a> + <a href="#classspecification"><i>class_specification</i></a> + <p> + Specifies classes and class members whose names are to be preserved, if + they aren't removed in the shrinking phase. For example, you may want to + <a href="examples.html#serializable">keep all class names</a> of classes + that implement the <code>Serializable</code> interface, so that the + processed code remains compatible with any originally serialized classes. + Classes that aren't used at all can still be removed. Only applicable when + obfuscating.</dd> + +<dt><a name="keepclassmembernames"><code><b>-keepclassmembernames</b></code></a> + <a href="#classspecification"><i>class_specification</i></a></dt> + +<dd>Short for <a href="#keepclassmembers"><code>-keepclassmembers</code></a>,<a href="#allowshrinking"><code>allowshrinking</code></a> + <a href="#classspecification"><i>class_specification</i></a> + <p> + Specifies class members whose names are to be preserved, if they aren't + removed in the shrinking phase. For example, you may want to preserve the + name of the synthetic <code>class$</code> methods + when <a href="examples.html#library">processing a library</a> compiled by + JDK 1.2 or older, so obfuscators can detect it again when processing an + application that uses the processed library (although ProGuard itself + doesn't need this). Only applicable when obfuscating.</dd> + +<dt><a name="keepclasseswithmembernames"><code><b>-keepclasseswithmembernames</b></code></a> + <a href="#classspecification"><i>class_specification</i></a></dt> + +<dd>Short for <a href="#keepclasseswithmembers"><code>-keepclasseswithmembers</code></a>,<a href="#allowshrinking"><code>allowshrinking</code></a> + <a href="#classspecification"><i>class_specification</i></a> + <p> + Specifies classes and class members whose names are to be preserved, on + the condition that all of the specified class members are present after + the shrinking phase. For example, you may want to <a + href="examples.html#native">keep all native method names</a> and the names + of their classes, so that the processed code can still link with the + native library code. Native methods that aren't used at all can still be + removed. If a class file is used, but none of its native methods are, its + name will still be obfuscated. Only applicable when obfuscating.</dd> + +<dt><a name="printseeds"><code><b>-printseeds</b></code></a> + [<a href="#filename"><i>filename</i></a>]</dt> + +<dd>Specifies to exhaustively list classes and class members matched by the + various <code>-keep</code> options. The list is printed to the standard + output or to the given file. The list can be useful to verify if the + intended class members are really found, especially if you're using + wildcards. For example, you may want to list all the <a + href="examples.html#applications">applications</a> or all the <a + href="examples.html#applets">applets</a> that you are keeping.</dd> + +</dl> +<p> + +<h2><a name="shrinkingoptions">Shrinking Options</a></h2> + +<dl> +<dt><a name="dontshrink"><code><b>-dontshrink</b></code></a></dt> + +<dd>Specifies not to shrink the input class files. By default, shrinking is + applied; all classes and class members are removed, except for the ones + listed by the various <code>-keep</code> options, and the ones on which + they depend, directly or indirectly. A shrinking step is also applied + after each optimization step, since some optimizations may open the + possibility to remove more classes and class members.</dd> + +<dt><a name="printusage"><code><b>-printusage</b></code></a> + [<a href="#filename"><i>filename</i></a>]</dt> + +<dd>Specifies to list dead code of the input class files. The list is printed + to the standard output or to the given file. For example, you can <a + href="examples.html#deadcode">list the unused code of an application</a>. + Only applicable when shrinking.</dd> + +<dt><a name="whyareyoukeeping"><code><b>-whyareyoukeeping</b></code></a> + <a href="#classspecification"><i>class_specification</i></a></dt> + +<dd>Specifies to print details on why the given classes and class members are + being kept in the shrinking step. This can be useful if you are wondering + why some given element is present in the output. In general, there can be + many different reasons. This option prints the shortest chain of methods + to a specified seed or entry point, for each specified class and class + member. <i>In the current implementation, the shortest chain that is + printed out may sometimes contain circular deductions -- these do not + reflect the actual shrinking process.</i> If the <a + href="#verbose"><code>-verbose</code></a> option if specified, the traces + include full field and method signatures. Only applicable when + shrinking.</dd> + +</dl> +<p> + +<h2><a name="optimizationoptions">Optimization Options</a></h2> + +<dl> +<dt><a name="dontoptimize"><code><b>-dontoptimize</b></code></a></dt> + +<dd>Specifies not to optimize the input class files. By default, optimization + is enabled; all methods are optimized at a bytecode level.</dd> + +<dt><a name="optimizations"><code><b>-optimizations</b></code></a> + <a href="optimizations.html"><i>optimization_filter</i></a></dt> + +<dd>Specifies the optimizations to be enabled and disabled, at a more + fine-grained level. Only applicable when optimizing. <i>This is an expert + option.</i></dd> + +<dt><a name="optimizationpasses"><code><b>-optimizationpasses</b></code></a> <i>n</i></dt> + +<dd>Specifies the number of optimization passes to be performed. By default, a + single pass is performed. Multiple passes may result in further + improvements. If no improvements are found after an optimization pass, the + optimization is ended. Only applicable when optimizing.</dd> + +<dt><a name="assumenosideeffects"><code><b>-assumenosideeffects</b></code></a> + <a href="#classspecification"><i>class_specification</i></a></dt> + +<dd>Specifies methods that don't have any side effects (other than maybe + returning a value). In the optimization step, ProGuard will then remove + calls to such methods, if it can determine that the return values aren't + used. ProGuard will analyze your program code to find such methods + automatically. It will not analyze library code, for which this option can + therefore be useful. For example, you could specify the method + <code>System.currentTimeMillis()</code>, so that any idle calls to it will + be removed. With some care, you can also use the option to + <a href="examples.html#logging">remove logging code</a>. Note that + ProGuard applies the option to the entire hierarchy of the specified + methods. Only applicable when optimizing. In general, making assumptions + can be dangerous; you can easily break the processed code. <i>Only use + this option if you know what you're doing!</i></dd> + +<dt><a name="allowaccessmodification"><code><b>-allowaccessmodification</b></code></a></dt> + +<dd>Specifies that the access modifiers of classes and class members may be + broadened during processing. This can improve the results of the + optimization step. For instance, when inlining a public getter, it may be + necessary to make the accessed field public too. Although Java's binary + compatibility specifications formally do not require this (cfr. <a href= + "http://docs.oracle.com/javase/specs/jls/se5.0/html/j3TOC.html" + >The Java Language Specification, Third Edition</a>, <a href= + "http://docs.oracle.com/javase/specs/jls/se5.0/html/binaryComp.html#13.4.6" + >Section 13.4.6</a>), some virtual machines would have problems with the + processed code otherwise. Only applicable when optimizing (and when + obfuscating with the <a + href="#repackageclasses"><code>-repackageclasses</code></a> option). + <p> + <i>Counter-indication:</i> you probably shouldn't use this option when + processing code that is to be used as a library, since classes and class + members that weren't designed to be public in the API may become + public.</dd> + +<dt><a name="mergeinterfacesaggressively"><code><b>-mergeinterfacesaggressively</b></code></a></dt> + +<dd>Specifies that interfaces may be merged, even if their implementing + classes don't implement all interface methods. This can reduce the size of + the output by reducing the total number of classes. Note that Java's + binary compatibility specifications allow such constructs (cfr. <a href= + "http://docs.oracle.com/javase/specs/jls/se5.0/html/j3TOC.html" + >The Java Language Specification, Third Edition</a>, <a href= + "http://docs.oracle.com/javase/specs/jls/se5.0/html/binaryComp.html#13.5.3" + >Section 13.5.3</a>), even if they are not allowed in the Java language + (cfr. <a href= + "http://docs.oracle.com/javase/specs/jls/se5.0/html/j3TOC.html" + >The Java Language Specification, Third Edition</a>, <a href= + "http://docs.oracle.com/javase/specs/jls/se5.0/html/classes.html#8.1.4" + >Section 8.1.4</a>). Only applicable when optimizing. + <p> + <i>Counter-indication:</i> setting this option can reduce the performance + of the processed code on some JVMs, since advanced just-in-time + compilation tends to favor more interfaces with fewer implementing + classes. Worse, some JVMs may not be able to handle the resulting code. + Notably: + <ul> + <li>Sun's JRE 1.3 may throw an <code>InternalError</code> when + encountering more than 256 <i>Miranda</i> methods (interface methods + without implementations) in a class.</li> + </ul></dd> + +</dl> +<p> + +<h2><a name="obfuscationoptions">Obfuscation Options</a></h2> + +<dl> +<dt><a name="dontobfuscate"><code><b>-dontobfuscate</b></code></a></dt> + +<dd>Specifies not to obfuscate the input class files. By default, obfuscation + is applied; classes and class members receive new short random names, + except for the ones listed by the various <code>-keep</code> options. + Internal attributes that are useful for debugging, such as source files + names, variable names, and line numbers are removed.</dd> + +<dt><a name="printmapping"><code><b>-printmapping</b></code></a> + [<a href="#filename"><i>filename</i></a>]</dt> + +<dd>Specifies to print the mapping from old names to new names for classes and + class members that have been renamed. The mapping is printed to the + standard output or to the given file. For example, it is required for + subsequent <a href="examples.html#incremental">incremental + obfuscation</a>, or if you ever want to make sense again of <a + href="examples.html#stacktrace">obfuscated stack traces</a>. Only + applicable when obfuscating.</dd> + +<dt><a name="applymapping"><code><b>-applymapping</b></code></a> + <a href="#filename"><i>filename</i></a></dt> + +<dd>Specifies to reuse the given name mapping that was printed out in a + previous obfuscation run of ProGuard. Classes and class members that are + listed in the mapping file receive the names specified along with them. + Classes and class members that are not mentioned receive new names. The + mapping may refer to input classes as well as library classes. This option + can be useful for <a href="examples.html#incremental">incremental + obfuscation</a>, i.e. processing add-ons or small patches to an existing + piece of code. If the structure of the code changes fundamentally, + ProGuard may print out warnings that applying a mapping is causing + conflicts. You may be able to reduce this risk by specifying the option <a + href="#useuniqueclassmembernames"><code>-useuniqueclassmembernames</code></a> + in both obfuscation runs. Only a single mapping file is allowed. Only + applicable when obfuscating.</dd> + +<dt><a name="obfuscationdictionary"><code><b>-obfuscationdictionary</b></code></a> + <a href="#filename"><i>filename</i></a></dt> + +<dd>Specifies a text file from which all valid words are used as obfuscated + field and method names. By default, short names like 'a', 'b', etc. are + used as obfuscated names. With an obfuscation dictionary, you can specify + a list of reserved key words, or identifiers with foreign characters, for + instance. White space, punctuation characters, duplicate words, and + comments after a <code><b>#</b></code> sign are ignored. Note that an + obfuscation dictionary hardly improves the obfuscation. Decent compilers + can automatically replace them, and the effect can fairly simply be undone + by obfuscating again with simpler names. The most useful application is + specifying strings that are typically already present in class files (such + as 'Code'), thus reducing the class file sizes just a little bit more. + Only applicable when obfuscating.</dd> + +<dt><a name="classobfuscationdictionary"><code><b>-classobfuscationdictionary</b></code></a> + <a href="#filename"><i>filename</i></a></dt> + +<dd>Specifies a text file from which all valid words are used as obfuscated + class names. The obfuscation dictionary is similar to the one of the + option <a + href="#obfuscationdictionary"><code>-obfuscationdictionary</code></a>. + Only applicable when obfuscating.</dd> + +<dt><a name="packageobfuscationdictionary"><code><b>-packageobfuscationdictionary</b></code></a> + <a href="#filename"><i>filename</i></a></dt> + +<dd>Specifies a text file from which all valid words are used as obfuscated + package names. The obfuscation dictionary is similar to the one of the + option <a + href="#obfuscationdictionary"><code>-obfuscationdictionary</code></a>. + Only applicable when obfuscating.</dd> + +<dt><a name="overloadaggressively"><code><b>-overloadaggressively</b></code></a></dt> + +<dd>Specifies to apply aggressive overloading while obfuscating. Multiple + fields and methods can then get the same names, as long as their arguments + and return types are different, as required by Java bytecode (not just + their arguments, as required by the Java language). This option can make + the processed code even smaller (and less comprehensible). Only applicable + when obfuscating. + <p> + <i>Counter-indication:</i> the resulting class files fall within the Java + bytecode specification (cfr. <a href= + "http://docs.oracle.com/javase/specs/jvms/se5.0/html/VMSpecTOC.doc.html" + >The Java Virtual Machine Specification, Second Edition</a>, first + paragraphs of <a href= + "http://docs.oracle.com/javase/specs/jvms/se5.0/html/ClassFile.doc.html#2877" + >Section 4.5</a> and <a href= + "http://docs.oracle.com/javase/specs/jvms/se5.0/html/ClassFile.doc.html#1513" + >Section 4.6</a>), even though this kind of overloading is not allowed in + the Java language (cfr. <a href= + "http://docs.oracle.com/javase/specs/jls/se5.0/html/j3TOC.html" + >The Java Language Specification, Third Edition</a>, <a href= + "http://docs.oracle.com/javase/specs/jls/se5.0/html/classes.html#8.3" + >Section 8.3</a> and <a href= + "http://docs.oracle.com/javase/specs/jls/se5.0/html/classes.html#8.4.5" + >Section 8.4.5</a>). Still, some tools have problems with it. Notably: + <ul> + <li>Sun's JDK 1.2.2 <code>javac</code> compiler produces an exception when + compiling with such a library (cfr. <a href= + "http://bugs.sun.com/view_bug.do?bug_id=4216736">Bug #4216736</a>). + You probably shouldn't use this option for processing libraries.</li> + <li>Sun's JRE 1.4 and later fail to serialize objects with overloaded + primitive fields.</li> + <li>Sun's JRE 1.5 <code>pack200</code> tool reportedly has problems with + overloaded class members.</li> + <li>The class <code>java.lang.reflect.Proxy</code> can't handle overloaded + methods.</li> + <li>Google's Dalvik VM can't handle overloaded static fields.</li> + </ul></dd> + +<dt><a name="useuniqueclassmembernames"><code><b>-useuniqueclassmembernames</b></code></a></dt> + +<dd>Specifies to assign the same obfuscated names to class members that have + the same names, and different obfuscated names to class members that have + different names (for each given class member signature). Without the + option, more class members can be mapped to the same short names like 'a', + 'b', etc. The option therefore increases the size of the resulting code + slightly, but it ensures that the saved obfuscation name mapping can + always be respected in subsequent incremental obfuscation steps. + <p> + For instance, consider two distinct interfaces containing methods with the + same name and signature. Without this option, these methods may get + different obfuscated names in a first obfuscation step. If a patch is then + added containing a class that implements both interfaces, ProGuard will + have to enforce the same method name for both methods in an incremental + obfuscation step. The original obfuscated code is changed, in order to + keep the resulting code consistent. With this option <i>in the initial + obfuscation step</i>, such renaming will never be necessary. + <p> + This option is only applicable when obfuscating. In fact, if you are + planning on performing incremental obfuscation, you probably want to avoid + shrinking and optimization altogether, since these steps could remove or + modify parts of your code that are essential for later additions.</dd> + +<dt><a name="dontusemixedcaseclassnames"><code><b>-dontusemixedcaseclassnames</b></code></a></dt> + +<dd>Specifies not to generate mixed-case class names while obfuscating. By + default, obfuscated class names can contain a mix of upper-case characters + and lower-case characters. This creates perfectly acceptable and usable + jars. Only if a jar is unpacked on a platform with a case-insensitive + filing system (say, Windows), the unpacking tool may let similarly named + class files overwrite each other. Code that self-destructs when it's + unpacked! Developers who really want to unpack their jars on Windows can + use this option to switch off this behavior. Obfuscated jars will become + slightly larger as a result. Only applicable when obfuscating.</dd> + +<dt><a name="keeppackagenames"><code><b>-keeppackagenames</b></code></a> + [<i><a href="#filters">package_filter</a></i>]</dt> + +<dd>Specifies not to obfuscate the given package names. The optional filter is + a comma-separated list of package names. Package names can contain + <b>?</b>, <b>*</b>, and <b>**</b> wildcards, and they can be preceded by + the <b>!</b> negator. Only applicable when obfuscating.</dd> + +<dt><a name="flattenpackagehierarchy"><code><b>-flattenpackagehierarchy</b></code></a> + [<i>package_name</i>]</dt> + +<dd>Specifies to repackage all packages that are renamed, by moving them into + the single given parent package. Without argument or with an empty string + (''), the packages are moved into the root package. This option is one + example of further <a href="examples.html#repackaging">obfuscating package + names</a>. It can make the processed code smaller and less comprehensible. + Only applicable when obfuscating.</dd> + +<dt><a name="repackageclasses"><code><b>-repackageclasses</b></code></a> + [<i>package_name</i>]</dt> + +<dd>Specifies to repackage all class files that are renamed, by moving them + into the single given package. Without argument or with an empty string + (''), the package is removed completely. This option overrides the + <a + href="#flattenpackagehierarchy"><code>-flattenpackagehierarchy</code></a> + option. It is another example of further <a + href="examples.html#repackaging">obfuscating package names</a>. It can + make the processed code even smaller and less comprehensible. Its + deprecated name is <code>-defaultpackage</code>. Only applicable when + obfuscating. + <p> + <i>Counter-indication:</i> classes that look for resource files in their + package directories will no longer work properly if they are moved + elsewhere. When in doubt, just leave the packaging untouched by not using + this option.</dd> + +<dt><a name="keepattributes"><code><b>-keepattributes</b></code></a> + [<i><a href="attributes.html">attribute_filter</a></i>]</dt> + +<dd>Specifies any optional attributes to be preserved. The attributes can be + specified with one or more <code>-keepattributes</code> directives. The + optional filter is a comma-separated list + of <a href="attributes.html">attribute names</a> that Java virtual + machines and ProGuard support. Attribute names can + contain <b>?</b>, <b>*</b>, and <b>**</b> wildcards, and they can be + preceded by the <b>!</b> negator. For example, you should at least keep + the <code>Exceptions</code>, <code>InnerClasses</code>, and + <code>Signature</code> attributes when + <a href="examples.html#library">processing a library</a>. You should also + keep the <code>SourceFile</code> and <code>LineNumberTable</code> + attributes for <a href="examples.html#stacktrace">producing useful + obfuscated stack traces</a>. Finally, you may want + to <a href="examples.html#annotations">keep annotations</a> if your code + depends on them. Only applicable when obfuscating.</dd> + +<dt><a name="keepparameternames"><code><b>-keepparameternames</b></code></a></dt> + +<dd>Specifies to keep the parameter names and types of methods that are kept. + This option actually keeps trimmed versions of the debugging attributes + <code>LocalVariableTable</code> and + <code>LocalVariableTypeTable</code>. It can be useful when + <a href="examples.html#library">processing a library</a>. Some IDEs can + use the information to assist developers who use the library, for example + with tool tips or autocompletion. Only applicable when obfuscating.</dd> + +<dt><a name="renamesourcefileattribute"><code><b>-renamesourcefileattribute</b></code></a> + [<i>string</i>]</dt> + +<dd>Specifies a constant string to be put in the <code>SourceFile</code> + attributes (and <code>SourceDir</code> attributes) of the class files. + Note that the attribute has to be present to start with, so it also has to + be preserved explicitly using the <code>-keepattributes</code> directive. + For example, you may want to have your processed libraries and + applications produce <a href="examples.html#stacktrace">useful obfuscated + stack traces</a>. Only applicable when obfuscating.</dd> + +<dt><a name="adaptclassstrings"><code><b>-adaptclassstrings</b></code></a> + [<i><a href="#filters">class_filter</a></i>]</dt> + +<dd>Specifies that string constants that correspond to class names should be + obfuscated as well. Without a filter, all string constants that correspond + to class names are adapted. With a filter, only string constants in + classes that match the filter are adapted. For example, if your code + contains a large number of hard-coded strings that refer to classes, and + you prefer not to keep their names, you may want to use this option. + Primarily applicable when obfuscating, although corresponding classes are + automatically kept in the shrinking step too.</dd> + +<dt><a name="adaptresourcefilenames"><code><b>-adaptresourcefilenames</b></code></a> + [<i><a href="#filefilters">file_filter</a></i>]</dt> + +<dd>Specifies the resource files to be renamed, based on the obfuscated names + of the corresponding class files (if any). Without a filter, all resource + files that correspond to class files are renamed. With a filter, only + matching files are renamed. For example, see <a + href="examples.html#resourcefiles">processing resource files</a>. Only + applicable when obfuscating.</dd> + +<dt><a name="adaptresourcefilecontents"><code><b>-adaptresourcefilecontents</b></code></a> + [<i><a href="#filefilters">file_filter</a></i>]</dt> + +<dd>Specifies the resource files whose contents are to be updated. Any class + names mentioned in the resource files are renamed, based on the obfuscated + names of the corresponding classes (if any). Without a filter, the + contents of all resource files updated. With a filter, only matching files + are updated. The resource files are parsed and written using the + platform's default character set. You can change this default character set + by setting the environment variable <code>LANG</code> or the Java system + property <code>file.encoding</code>. For an example, + see <a href="examples.html#resourcefiles">processing resource files</a>. + Only applicable when obfuscating. + <p> + <i>Caveat:</i> You probably only want to apply this option to text files, + since parsing and adapting binary files as text files can cause unexpected + problems. Therefore, make sure that you specify a sufficiently narrow + filter.</dd> + + +</dl> +<p> + +<h2><a name="preverificationoptions">Preverification Options</a></h2> + +<dl> +<dt><a name="dontpreverify"><code><b>-dontpreverify</b></code></a></dt> + +<dd>Specifies not to preverify the processed class files. By default, class + files are preverified if they are targeted at Java Micro Edition or at + Java 6 or higher. For Java Micro Edition, preverification is required, so + you will need to run an external preverifier on the processed code if you + specify this option. For Java 6, preverification is optional, but as of + Java 7, it is required. Only when eventually targeting Android, it is not + necessary, so you can then switch it off to reduce the processing time a + bit.</dd> + +<dt><a name="microedition"><code><b>-microedition</b></code></a></dt> + +<dd>Specifies that the processed class files are targeted at Java Micro + Edition. The preverifier will then add the appropriate StackMap + attributes, which are different from the default StackMapTable attributes + for Java Standard Edition. For example, you will need this option if you + are <a href="examples.html#midlets">processing midlets</a>.</dd> + +</dl> +<p> + +<h2><a name="generaloptions">General Options</a></h2> + +<dl> +<dt><a name="verbose"><code><b>-verbose</b></code></a></dt> + +<dd>Specifies to write out some more information during processing. If the + program terminates with an exception, this option will print out the entire + stack trace, instead of just the exception message.</dd> + +<dt><a name="dontnote"><code><b>-dontnote</b></code></a> + [<i><a href="#filters">class_filter</a></i>]</dt> + +<dd>Specifies not to print notes about potential mistakes or omissions in the + configuration, such as typos in class names or missing options that + might be useful. The optional filter is a regular expression; ProGuard + doesn't print notes about classes with matching names.</dd> + +<dt><a name="dontwarn"><code><b>-dontwarn</b></code></a> + [<i><a href="#filters">class_filter</a></i>]</dt> + +<dd>Specifies not to warn about unresolved references and other important + problems at all. The optional filter is a regular expression; ProGuard + doesn't print warnings about classes with matching names. Ignoring + warnings can be dangerous. For instance, if the unresolved classes or + class members are indeed required for processing, the processed code will + not function properly. <i>Only use this option if you know what you're + doing!</i></dd> + +<dt><a name="ignorewarnings"><code><b>-ignorewarnings</b></code></a></dt> + +<dd>Specifies to print any warnings about unresolved references and other + important problems, but to continue processing in any case. Ignoring + warnings can be dangerous. For instance, if the unresolved classes or + class members are indeed required for processing, the processed code will + not function properly. <i>Only use this option if you know what you're + doing!</i></dd> + +<dt><a name="printconfiguration"><code><b>-printconfiguration</b></code></a> + [<a href="#filename"><i>filename</i></a>]</dt> + +<dd>Specifies to write out the entire configuration that has been parsed, with + included files and replaced variables. The structure is printed to the + standard output or to the given file. This can sometimes be useful for + debugging configurations, or for converting XML configurations into a more + readable format.</dd> + +<dt><a name="dump"><code><b>-dump</b></code></a> + [<a href="#filename"><i>filename</i></a>]</dt> + +<dd>Specifies to write out the internal structure of the class files, after + any processing. The structure is printed to the standard output or to the + given file. For example, you may want to <a + href="examples.html#structure">write out the contents of a given jar + file</a>, without processing it at all.</dd> + +</dl> +<p> + +<h2><a name="classpath">Class Paths</a></h2> + +ProGuard accepts a generalization of class paths to specify input files and +output files. A class path consists of entries, separated by the traditional +path separator (e.g. '<b>:</b>' on Unix, or '<b>;</b>' on Windows platforms). +The order of the entries determines their priorities, in case of duplicates. +<p> +Each input entry can be: +<ul> +<li>A class file or resource file,</li> +<li>An apk file, containing any of the above,</li> +<li>A jar file, containing any of the above,</li> +<li>An aar file, containing any of the above,</li> +<li>A war file, containing any of the above,</li> +<li>An ear file, containing any of the above,</li> +<li>A zip file, containing any of the above,</li> +<li>A directory (structure), containing any of the above.</li> +</ul> +<p> +The paths of directly specified class files and resource files is ignored, so +class files should generally be part of a jar file, an aar file, a war file, +an ear file, a zip file, or a directory. In addition, the paths of class files +should not have any additional directory prefixes inside the archives or +directories. + +<p> +Each output entry can be: +<ul> +<li>An apk file, in which all class files and resource files will be + collected.</li> +<li>A jar file, in which any and all of the above will be collected,</li> +<li>An aar file, in which any and all of the above will be collected,</li> +<li>A war file, in which any and all of the above will be collected,</li> +<li>An ear file, in which any and all of the above will be collected,</li> +<li>A zip file, in which any and all of the above will be collected,</li> +<li>A directory, in which any and all of the above will be collected.</li> +</ul> +<p> +When writing output entries, ProGuard will generally package the results in a +sensible way, reconstructing the input entries as much as required. Writing +everything to an output directory is the most straightforward option: the +output directory will contain a complete reconstruction of the input entries. +The packaging can be almost arbitrarily complex though: you could process an +entire application, packaged in a zip file along with its documentation, +writing it out as a zip file again. The Examples section shows a few ways +to <a href="examples.html#restructuring">restructure output archives</a>. +<p> +Files and directories can be specified as discussed in the section on <a +href="#filename">file names</a> below. +<p> +In addition, ProGuard provides the possibility to filter the class path +entries and their contents, based on their full relative file names. Each +class path entry can be followed by up to 7 types of <a +href="#filefilters">file filters</a> between parentheses, separated by +semi-colons: +<ul> +<li>A filter for all aar names that are encountered,</li> +<li>A filter for all apk names that are encountered,</li> +<li>A filter for all zip names that are encountered,</li> +<li>A filter for all ear names that are encountered,</li> +<li>A filter for all war names that are encountered,</li> +<li>A filter for all jar names that are encountered,</li> +<li>A filter for all class file names and resource file names that are + encountered.</li> +</ul> +<p> +If fewer than 7 filters are specified, they are assumed to be the latter +filters. Any empty filters are ignored. More formally, a filtered class path +entry looks like this: +<pre> +<i>classpathentry</i><b>(</b>[[[[[[<i>aarfilter</i><b>;</b>]<i>apkfilter</i><b>;</b>]<i>zipfilter</i><b>;</b>]<i>earfilter</i><b>;</b>]<i>warfilter</i><b>;</b>]<i>jarfilter</i><b>;</b>]<i>filefilter</i><b>)</b> +</pre> +<p> +Square brackets "[]" mean that their contents are optional. +<p> +For example, "<code>rt.jar(java/**.class,javax/**.class)</code>" matches all +class files in the <code>java</code> and <code>javax</code> directories inside +the <code>rt</code> jar. +<p> +For example, "<code>input.jar(!**.gif,images/**)</code>" matches all files in +the <code>images</code> directory inside the <code>input</code> jar, except +gif files. +<p> +The different filters are applied to all corresponding file types, irrespective +of their nesting levels in the input; they are orthogonal. +<p> +For example, +"<code>input.war(lib/**.jar,support/**.jar;**.class,**.gif)</code>" only +considers jar files in the <code>lib</code> and <code>support</code> +directories in the <code>input</code> war, not any other jar files. It then +matches all class files and gif files that are encountered. +<p> +The filters allow for an almost infinite number of packaging and repackaging +possibilities. The Examples section provides a few more examples +for <a href="examples.html#filtering">filtering input and output</a>. +<p> + +<h2><a name="filename">File Names</a></h2> + +ProGuard accepts absolute paths and relative paths for the various file names +and directory names. A relative path is interpreted as follows: +<ul> +<li>relative to the base directory, if set, or otherwise</li> +<li>relative to the configuration file in which it is specified, if any, or + otherwise</li> +<li>relative to the working directory.</li> +</ul> +<p> +The names can contain Java system properties (or Ant properties, when using +Ant), delimited by angular brackets, '<b><</b>' and '<b>></b>'. The +properties are automatically replaced by their corresponding values. +<p> +For example, <code><java.home>/lib/rt.jar</code> is automatically +expanded to something like <code>/usr/local/java/jdk/jre/lib/rt.jar</code>. +Similarly, <code><user.home></code> is expanded to the user's home +directory, and <code><user.dir></code> is expanded to the current +working directory. +<p> +Names with special characters like spaces and parentheses must be quoted with +single or double quotes. Each file name in a list of names has to be quoted +individually. Note that the quotes themselves may need to be escaped when used +on the command line, to avoid them being gobbled by the shell. +<p> +For example, on the command line, you could use an option like <code>'-injars +"my program.jar":"/your directory/your program.jar"'</code>. +<p> + +<h2><a name="filefilters">File Filters</a></h2> + +Like general <a href="#filters">filters</a>, a file filter is a +comma-separated list of file names that can contain wildcards. Only files with +matching file names are read (in the case of input jars), or written (in the +case of output jars). The following wildcards are supported: + +<table cellspacing="10"> +<tr><td valign="top"><code><b>?</b></code></td> + <td>matches any single character in a file name.</td></tr> +<tr><td valign="top"><code><b>*</b></code></td> + <td>matches any part of a filename not containing the directory + separator.</td></tr> +<tr><td valign="top"><code><b>**</b></code></td> + <td>matches any part of a filename, possibly containing any number of + directory separators.</td></tr> +</table> + +For example, "<code>java/**.class,javax/**.class</code>" matches all +class files in the <code>java</code> and <code>javax</code>. +<p> + +Furthermore, a file name can be preceded by an exclamation mark '<b>!</b>' to +<i>exclude</i> the file name from further attempts to match with +<i>subsequent</i> file names. +<p> +For example, "<code>!**.gif,images/**</code>" matches all files in the +<code>images</code> directory, except gif files. +<p> +The Examples section provides a few more examples for <a +href="examples.html#filtering">filtering input and output</a>. + +<h2><a name="filters">Filters</a></h2> + +ProGuard offers options with filters for many different aspects of the +configuration: names of files, directories, classes, packages, attributes, +optimizations, etc. +<p> +A filter is a list of comma-separated names that can contain wildcards. Only +names that match an item on the list pass the filter. The supported wildcards +depend on the type of names for which the filter is being used, but the +following wildcards are typical: + +<table cellspacing="10"> +<tr><td valign="top"><code><b>?</b></code></td> + <td>matches any single character in a name.</td></tr> +<tr><td valign="top"><code><b>*</b></code></td> + <td>matches any part of a name not containing the package separator or + directory separator.</td></tr> +<tr><td valign="top"><code><b>**</b></code></td> + <td>matches any part of a name, possibly containing any number of + package separators or directory separators.</td></tr> +</table> + +For example, "<code>foo,*bar</code>" matches the name <code>foo</code> and +all names ending with <code>bar</code>. +<p> + +Furthermore, a name can be preceded by a negating exclamation mark '<b>!</b>' +to <i>exclude</i> the name from further attempts to match +with <i>subsequent</i> names. So, if a name matches an item in the filter, it +is accepted or rejected right away, depending on whether the item has a +negator. If the name doesn't match the item, it is tested against the next +item, and so on. It if doesn't match any items, it is accepted or rejected, +depending on the whether the last item has a negator or not. +<p> +For example, "<code>!foobar,*bar</code>" matches all names ending with +<code>bar</code>, except <code>foobar</code>. +<p> + +<h2><a name="keepoverview">Overview of <code>Keep</code> Options</a></h2> + +The various <code>-keep</code> options for shrinking and obfuscation may seem +a bit confusing at first, but there's actually a pattern behind them. The +following table summarizes how they are related: +<p> + +<table cellpadding="5"> + +<tr> +<th>Keep</th> +<td>From being removed or renamed</td> +<td>From being renamed</td> +</tr> + +<tr> +<td>Classes and class members</td> +<td bgcolor="#E0E0E0"><a href="#keep"><code>-keep</code></a></td> +<td bgcolor="#E0E0E0"><a href="#keepnames"><code>-keepnames</code></a></td> +</tr> + +<tr> +<td>Class members only</td> +<td bgcolor="#E0E0E0"><a href="#keepclassmembers"><code>-keepclassmembers</code></a></td> +<td bgcolor="#E0E0E0"><a href="#keepclassmembernames"><code>-keepclassmembernames</code></a></td> +</tr> + +<tr> +<td>Classes and class members, if class members present</td> +<td bgcolor="#E0E0E0"><a href="#keepclasseswithmembers"><code>-keepclasseswithmembers</code></a></td> +<td bgcolor="#E0E0E0"><a href="#keepclasseswithmembernames"><code>-keepclasseswithmembernames</code></a></td> +</tr> + +</table> +<p> + +Each of these <code>-keep</code> options is of course followed by a +<a href="#classspecification">specification</a> of the classes and class +members (fields and methods) to which it should be applied. +<p> +If you're not sure which option you need, you should probably simply use +<code>-keep</code>. It will make sure the specified classes and class members +are not removed in the shrinking step, and not renamed in the obfuscation step. +<p> +<img class="float" src="attention.gif" width="64" height="64" alt="attention" /> +<ul class="shifted"> +<li>If you specify a class, without class members, ProGuard only preserves the + class and its parameterless constructor as entry points. It may + still remove, optimize, or obfuscate its other class members.</li> +<li>If you specify a method, ProGuard only preserves the method as an entry + point. Its code may still be optimized and adapted.</li> +</ul> +<p> + +<h2><a name="keepoptionmodifiers">Keep Option Modifiers</a></h2> + +<dl> +<dt><a name="includedescriptorclasses"><code><b>includedescriptorclasses</b></code></a></dt> + +<dd>Specifies that any classes in the type descriptors of the methods and + fields that the <a href="#keep">-keep</a> option keeps should be kept as + well. This is typically useful when <a href="examples.html#native">keeping + native method names</a>, to make sure that the parameter types of native + methods aren't renamed either. Their signatures then remain completely + unchanged and compatible with the native libraries.</dd> + +<dt><a name="allowshrinking"><code><b>allowshrinking</b></code></a></dt> + +<dd>Specifies that the entry points specified in the <a href="#keep">-keep</a> + option may be shrunk, even if they have to be preserved otherwise. That + is, the entry points may be removed in the shrinking step, but if they are + necessary after all, they may not be optimized or obfuscated.</dd> + +<dt><a name="allowoptimization"><code><b>allowoptimization</b></code></a></dt> + +<dd>Specifies that the entry points specified in the <a href="#keep">-keep</a> + option may be optimized, even if they have to be preserved otherwise. That + is, the entry points may be altered in the optimization step, but they may + not be removed or obfuscated. This modifier is only useful for achieving + unusual requirements.</dd> + +<dt><a name="allowobfuscation"><code><b>allowobfuscation</b></code></a></dt> + +<dd>Specifies that the entry points specified in the <a href="#keep">-keep</a> + option may be obfuscated, even if they have to be preserved otherwise. That + is, the entry points may be renamed in the obfuscation step, but they may + not be removed or optimized. This modifier is only useful for achieving + unusual requirements.</dd> + +</dl> +<p> + +<h2><a name="classspecification">Class Specifications</a></h2> + +A class specification is a template of classes and class members (fields and +methods). It is used in the various <code>-keep</code> options and in the +<code>-assumenosideeffects</code> option. The corresponding option is only +applied to classes and class members that match the template. +<p> +The template was designed to look very Java-like, with some extensions for +wildcards. To get a feel for the syntax, you should probably look at the <a +href="examples.html">examples</a>, but this is an attempt at a complete formal +definition: +<p> + +<pre> +[<b>@</b><i>annotationtype</i>] [[<b>!</b>]<b>public</b>|<b>final</b>|<b>abstract</b>|<b>@</b> ...] [<b>!</b>]<b>interface</b>|<b>class</b>|<b>enum</b> <i>classname</i> + [<b>extends</b>|<b>implements</b> [<b>@</b><i>annotationtype</i>] <i>classname</i>] +[<b>{</b> + [<b>@</b><i>annotationtype</i>] [[<b>!</b>]<b>public</b>|<b>private</b>|<b>protected</b>|<b>static</b>|<b>volatile</b>|<b>transient</b> ...] <b><fields></b> | + (<i>fieldtype fieldname</i>)<b>;</b> + [<b>@</b><i>annotationtype</i>] [[<b>!</b>]<b>public</b>|<b>private</b>|<b>protected</b>|<b>static</b>|<b>synchronized</b>|<b>native</b>|<b>abstract</b>|<b>strictfp</b> ...] <b><methods></b> | + <b><init>(</b><i>argumenttype,...</i><b>)</b> | + <i>classname</i><b>(</b><i>argumenttype,...</i><b>)</b> | + (<i>returntype methodname</i><b>(</b><i>argumenttype,...</i><b>)</b>)<b>;</b> + [<b>@</b><i>annotationtype</i>] [[<b>!</b>]<b>public</b>|<b>private</b>|<b>protected</b>|<b>static</b> ... ] <b>*;</b> + ... +<b>}</b>] +</pre> +<p> +Square brackets "[]" mean that their contents are optional. Ellipsis dots +"..." mean that any number of the preceding items may be specified. A vertical +bar "|" delimits two alternatives. Non-bold parentheses "()" just group parts +of the specification that belong together. The indentation tries to clarify +the intended meaning, but white-space is irrelevant in actual configuration +files. +<p> +<ul class="spacious"> + +<li>The <code><b>class</b></code> keyword refers to any interface or class. + The <code><b>interface</b></code> keyword restricts matches to interface + classes. The <code><b>enum</b></code> keyword restricts matches to + enumeration classes. Preceding the <code><b>interface</b></code> or + <code><b>enum</b></code> keywords by a <code><b>!</b></code> restricts + matches to classes that are not interfaces or enumerations, + respectively.</li> + +<li>Every <i>classname</i> must be fully qualified, e.g. + <code>java.lang.String</code>. Inner classes are separated by a dollar sign + "<code>$</code>", e.g. <code>java.lang.Thread$State</code>. Class names + may be specified as regular + expressions containing the following wildcards: + +<table cellspacing="10"> + +<tr><td valign="top"><code><b>?</b></code></td> + +<td>matches any single character in a class name, but not the package + separator. For example, "<code>mypackage.Test?</code>" matches + "<code>mypackage.Test1</code>" and "<code>mypackage.Test2</code>", but not + "<code>mypackage.Test12</code>".</td></tr> + +<tr><td valign="top"><code><b>*</b></code></td> + +<td>matches any part of a class name not containing the package separator. For + example, "<code>mypackage.*Test*</code>" matches + "<code>mypackage.Test</code>" and + "<code>mypackage.YourTestApplication</code>", but not + "<code>mypackage.mysubpackage.MyTest</code>". Or, more generally, + "<code>mypackage.*</code>" matches all classes in + "<code>mypackage</code>", but not in its subpackages.</td></tr> + +<tr><td valign="top"><code><b>**</b></code></td> + +<td>matches any part of a class name, possibly containing any number of + package separators. For example, "<code>**.Test</code>" matches all + <code>Test</code> classes in all packages except the root package. Or, + "<code>mypackage.**</code>" matches all classes in + "<code>mypackage</code>" and in its subpackages.</td></tr> + +</table> + + For additional flexibility, class names can actually be comma-separated + lists of class names, with optional <code><b>!</b></code> negators, just + like file name filters. This notation doesn't look very Java-like, so it + should be used with moderation. + <p> + For convenience and for backward compatibility, the class name + <code><b>*</b></code> refers to any class, irrespective of its package.</li> + +<li>The <code><b>extends</b></code> and <code><b>implements</b></code> + specifications are typically used to restrict classes with wildcards. They + are currently equivalent, specifying that only classes extending or + implementing the given class qualify. Note that the given class itself is + not included in this set. If required, it should be specified in a + separate option.</li> + +<li>The <code><b>@</b></code> specifications can be used to restrict classes + and class members to the ones that are annotated with the specified + annotation types. An <i>annotationtype</i> is specified just like a + <i>classname</i>.</li> + +<li>Fields and methods are specified much like in Java, except that method + argument lists don't contain argument names (just like in other tools + like <code>javadoc</code> and <code>javap</code>). The specifications can + also contain the following catch-all wildcards: + +<table cellspacing="10"> + +<tr><td valign="top"><code><b><init></b></code></td> +<td>matches any constructor.</td></tr> + +<tr><td valign="top"><code><b><fields></b></code></td> +<td>matches any field.</td></tr> + +<tr><td valign="top"><code><b><methods></b></code></td> +<td>matches any method.</td></tr> + +<tr><td valign="top"><code><b>*</b></code></td> +<td>matches any field or method.</td></tr> + +</table> + + Note that the above wildcards don't have return types. Only the + <code><b><init></b></code> wildcard has an argument list. + <p> + + Fields and methods may also be specified using regular expressions. Names + can contain the following wildcards: + +<table cellspacing="10"> +<tr><td valign="top"><code><b>?</b></code></td> + <td>matches any single character in a method name.</td></tr> +<tr><td valign="top"><code><b>*</b></code></td> + <td>matches any part of a method name.</td></tr> +</table> + + Types in descriptors can contain the following wildcards: + +<table cellspacing="10"> +<tr><td valign="top"><code><b>%</b></code></td> + <td>matches any primitive type ("<code>boolean</code>", "<code>int</code>", + etc, but not "<code>void</code>").</td></tr> +<tr><td valign="top"><code><b>?</b></code></td> + <td>matches any single character in a class name.</td></tr> +<tr><td valign="top"><code><b>*</b></code></td> + <td>matches any part of a class name not containing the package separator.</td></tr> +<tr><td valign="top"><code><b>**</b></code></td> + <td>matches any part of a class name, possibly containing any number of + package separators.</td></tr> +<tr><td valign="top"><code><b>***</b></code></td> + <td>matches any type (primitive or non-primitive, array or + non-array).</td></tr> +<tr><td valign="top"><code><b>...</b></code></td> + <td>matches any number of arguments of any type.</td></tr> + +</table> + + Note that the <code>?</code>, <code>*</code>, and <code>**</code> + wildcards will never match primitive types. Furthermore, only the + <code>***</code> wildcards will match array types of any dimension. For + example, "<code>** get*()</code>" matches "<code>java.lang.Object + getObject()</code>", but not "<code>float getFloat()</code>", nor + "<code>java.lang.Object[] getObjects()</code>".</li> + +<li>Constructors can also be specified using their short class names (without + package) or using their full class names. As in the Java language, the + constructor specification has an argument list, but no return type.</li> + +<li>The class access modifiers and class member access modifiers are typically + used to restrict wildcarded classes and class members. They specify that + the corresponding access flags have to be set for the member to match. A + preceding <code><b>!</b></code> specifies that the corresponding access + flag should be unset. + <p> + Combining multiple flags is allowed (e.g. <code>public static</code>). It + means that both access flags have to be set (e.g. <code>public</code> + <i>and</i> <code>static</code>), except when they are conflicting, in + which case at least one of them has to be set (e.g. at least + <code>public</code> + <i>or</i> <code>protected</code>). + <p> + ProGuard supports the additional modifiers <code><b>synthetic</b></code>, + <code><b>bridge</b></code>, and <code><b>varargs</b></code>, which may be + set by compilers.</li> + +</ul> + +<hr /> +<address> +Copyright © 2002-2017 +<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.guardsquare.com/">GuardSquare</a>. +</address> +</body> +</html> diff --git a/third_party/java/proguard/proguard5.3.3/docs/manual/wtk.html b/third_party/java/proguard/proguard5.3.3/docs/manual/wtk.html new file mode 100644 index 0000000000..2787a1a6b9 --- /dev/null +++ b/third_party/java/proguard/proguard5.3.3/docs/manual/wtk.html @@ -0,0 +1,71 @@ +<!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 JME Wireless Toolkit Integration</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/wtk.html">ProGuard index</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> <a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> <a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>') +//--> +</script> +<noscript> +<a class="largebutton" target="_top" href="../index.html#manual/wtk.html">ProGuard index</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/dexguard">DexGuard</a> +<a class="largebutton" target="_top" href="http://www.guardsquare.com/">GuardSquare</a> +<a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a> +</noscript> + +<h2>JME Wireless Toolkit Integration</h2> + +<b>ProGuard</b> can be seamlessly integrated in Oracle's Wireless Toolkit (WTK) +for Java Micro Edition (JME). +<p> + +The WTK already comes with a plug-in for ProGuard. Alternatively, ProGuard +offers its own plug-in. This latter implementation is recommended, as it more +up to date and it solves some problems. It is also somewhat more efficient, +invoking the ProGuard engine directly, instead of writing out a configuration +file and running ProGuard in a separate virtual machine. +<p> + +In order to integrate this plug-in in the toolkit, you'll have to put the +following lines in the file +{j2mewtk.dir}<code>/wtklib/Linux/ktools.properties</code> or +{j2mewtk.dir}<code>\wtklib\Windows\ktools.properties</code> (whichever is +applicable). +<p> + +<pre> +obfuscator.runner.class.name: proguard.wtk.ProGuardObfuscator +obfuscator.runner.classpath: /usr/local/java/proguard/lib/proguard.jar +</pre> +<p> + +Please make sure the class path is set correctly for your system. +<p> + +Once ProGuard has been set up, you can apply it to your projects as part of +the build process. The build process is started from the WTK menu bar: +<p> +<center><b>Project -> Package -> Create Obfuscated Package</b></center> +<p> +This option will compile, shrink, obfuscate, verify, and install your midlets +for testing. +<p> +Should you ever need to customize your ProGuard configuration for the JME WTK, +you can adapt the configuration file <code>proguard/wtk/default.pro</code> +that's inside the <code>proguard.jar</code>. + +<hr /> +<address> +Copyright © 2002-2017 +<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.guardsquare.com/">GuardSquare</a>. +</address> +</body> +</html> |
