diff options
Diffstat (limited to 'docs/manual/introduction.html')
| -rw-r--r-- | docs/manual/introduction.html | 156 |
1 files changed, 156 insertions, 0 deletions
diff --git a/docs/manual/introduction.html b/docs/manual/introduction.html new file mode 100644 index 0000000..cdab330 --- /dev/null +++ b/docs/manual/introduction.html @@ -0,0 +1,156 @@ +<!doctype html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<html> +<head> +<meta http-equiv="content-type" content="text/html; charset=iso-8859-1"> +<meta http-equiv="content-style-type" content="text/css"> +<link rel="stylesheet" type="text/css" href="style.css"> +<title>ProGuard Introduction</title> +</head> +<body> + +<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 or which improves the start-up time for Java +6. +<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 typically reads the <b>input jars</b> (or wars, ears, zips, or +directories). It then shrinks, optimizes, obfuscates, and preverifies them. +Optionally, multiple optimization passes can be performed, each typically +followed by another shrinking step. ProGuard writes the processed results to +one or more <b>output jars</b> (or wars, ears, zips, 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 wars, ears, zips, 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. +<p> +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, 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>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>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>The <b>preverification step</b> is the only step that doesn't have to know + the entry points. +</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>Introspection</h3> + +Introspection presents 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 foresee 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><code>SomeClass.class</code> +<li><code>SomeClass.class.getField("someField")</code> +<li><code>SomeClass.class.getDeclaredField("someField")</code> +<li><code>SomeClass.class.getMethod("someMethod", new Class[] {})</code> +<li><code>SomeClass.class.getMethod("someMethod", new Class[] { A.class })</code> +<li><code>SomeClass.class.getMethod("someMethod", new Class[] { A.class, B.class })</code> +<li><code>SomeClass.class.getDeclaredMethod("someMethod", new Class[] {})</code> +<li><code>SomeClass.class.getDeclaredMethod("someMethod", new Class[] { A.class })</code> +<li><code>SomeClass.class.getDeclaredMethod("someMethod", new Class[] { A.class, B.class })</code> +</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 replaced 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 introspection +may require trial and error, especially without the necessary information +about the internals of the code. +<p> + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</html> |