• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<!doctype html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3<head>
4<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
5<meta http-equiv="content-style-type" content="text/css">
6<link rel="stylesheet" type="text/css" href="style.css">
7<title>ProGuard Introduction</title>
8</head>
9<body>
10
11<script type="text/javascript" language="JavaScript">
12<!--
13if (window.self==window.top)
14  document.write('<a class="largebutton" target="_top" href="../index.html#manual/introduction.html">ProGuard index</a> <a class="largebutton" target="_top" href="http://www.saikoa.com/dexguard">DexGuard</a> <a class="largebutton" target="_top" href="http://www.saikoa.com/">Saikoa</a> <a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>')
15//-->
16</script>
17<noscript>
18<a class="largebutton" target="_top"  href="../index.html#manual/introduction.html">ProGuard index</a>
19<a class="largebutton" target="_top"  href="http://www.saikoa.com/dexguard">DexGuard</a>
20<a class="largebutton" target="_top"  href="http://www.saikoa.com/">Saikoa</a>
21<a class="largebutton" target="other" href="http://sourceforge.net/projects/proguard/">Sourceforge</a>
22</noscript>
23
24<h2>Introduction</h2>
25
26<b>ProGuard</b> is a Java class file shrinker, optimizer, obfuscator, and
27preverifier. The shrinking step detects and removes unused classes, fields,
28methods, and attributes. The optimization step analyzes and optimizes the
29bytecode of the methods. The obfuscation step renames the remaining classes,
30fields, and methods using short meaningless names. These first steps make the
31code base smaller, more efficient, and harder to reverse-engineer. The final
32preverification step adds preverification information to the classes, which is
33required for Java Micro Edition and for Java 6 and higher.
34<p>
35Each of these steps is optional. For instance, ProGuard can also be used to
36just list dead code in an application, or to preverify class files for
37efficient use in Java 6.
38<p>
39
40<table class="diagram" align="center">
41
42<tr>
43<td rowspan="4" class="lightblock">Input jars</td>
44<td colspan="8" class="transparentblock"></td>
45</tr>
46
47<tr>
48<td rowspan="2" class="transparentblock"></td>
49<td rowspan="3" class="lightblock">Shrunk code</td>
50<td colspan="6" class="transparentblock"></td>
51</tr>
52
53<tr>
54<td             class="transparentblock"></td>
55<td rowspan="2" class="lightblock">Optim. code</td>
56<td colspan="3" class="transparentblock"></td>
57<td rowspan="2" class="lightblock">Output jars</td>
58</tr>
59
60<tr>
61<td             class="transparentblock">- shrink &rarr;</td>
62<td             class="transparentblock">- optimize &rarr;</td>
63<td             class="transparentblock">- obfuscate &rarr;</td>
64<td             class="lightblock">Obfusc. code</td>
65<td             class="transparentblock">- preverify &rarr;</td>
66</tr>
67
68<tr>
69<td             class="darkblock">Library jars</td>
70<td colspan="7" class="transparentblock">------------------------------- (unchanged) -------------------------------&rarr;</td>
71<td             class="darkblock">Library jars</td>
72</tr>
73
74</table>
75<p>
76
77ProGuard first reads the <b>input jars</b> (or aars, wars, ears, zips, apks,
78or directories). It then subsequently shrinks, optimizes, obfuscates, and
79preverifies them. You can optionally let ProGuard perform multiple
80optimization passes. ProGuard writes the processed results to one or
81more <b>output jars</b> (or aars, wars, ears, zips, apks, or directories). The
82input may contain resource files, whose names and contents can optionally be
83updated to reflect the obfuscated class names.
84<p>
85ProGuard requires the <b>library jars</b> (or aars, wars, ears, zips, apks, or
86directories) of the input jars to be specified. These are essentially the
87libraries that you would need for compiling the code. ProGuard uses them to
88reconstruct the class dependencies that are necessary for proper processing.
89The library jars themselves always remain unchanged. You should still put them
90in the class path of your final application.
91
92<h3>Entry points</h3>
93
94In order to determine which code has to be preserved and which code can be
95discarded or obfuscated, you have to specify one or more <i>entry points</i> to
96your code. These entry points are typically classes with main methods, applets,
97midlets, activities, etc.
98<ul>
99<li>In the <b>shrinking step</b>, ProGuard starts from these seeds and
100    recursively determines which classes and class members are used. All other
101    classes and class members are discarded.</li>
102
103<li>In the <b>optimization step</b>, ProGuard further optimizes the code.
104    Among other optimizations, classes and methods that are not entry points
105    can be made private, static, or final, unused parameters can be removed,
106    and some methods may be inlined.</li>
107
108<li>In the <b>obfuscation step</b>, ProGuard renames classes and class members
109    that are not entry points. In this entire process, keeping the entry
110    points ensures that they can still be accessed by their original names.</li>
111
112<li>The <b>preverification step</b> is the only step that doesn't have to know
113    the entry points.</li>
114</ul>
115<p>
116The <a href="usage.html">Usage section</a> of this manual describes the
117necessary <a href="usage.html#keepoptions"><code>-keep</code> options</a> and
118the <a href="examples.html">Examples section</a> provides plenty of examples.
119
120<h3>Reflection</h3>
121
122Reflection and introspection present particular problems for any automatic
123processing of code. In ProGuard, classes or class members in your code that
124are created or invoked dynamically (that is, by name) have to be specified as
125entry points too. For example, <code>Class.forName()</code> constructs may
126refer to any class at run-time. It is generally impossible to compute which
127classes have to be preserved (with their original names), since the class
128names might be read from a configuration file, for instance. You therefore
129have to specify them in your ProGuard configuration, with the same
130simple <code>-keep</code> options.
131<p>
132However, ProGuard will already detect and handle the following cases for you:
133
134<ul>
135<li><code>Class.forName("SomeClass")</code></li>
136<li><code>SomeClass.class</code></li>
137<li><code>SomeClass.class.getField("someField")</code></li>
138<li><code>SomeClass.class.getDeclaredField("someField")</code></li>
139<li><code>SomeClass.class.getMethod("someMethod", new Class[] {})</code></li>
140<li><code>SomeClass.class.getMethod("someMethod", new Class[] { A.class })</code></li>
141<li><code>SomeClass.class.getMethod("someMethod", new Class[] { A.class, B.class })</code></li>
142<li><code>SomeClass.class.getDeclaredMethod("someMethod", new Class[] {})</code></li>
143<li><code>SomeClass.class.getDeclaredMethod("someMethod", new Class[] { A.class })</code></li>
144<li><code>SomeClass.class.getDeclaredMethod("someMethod", new Class[] { A.class, B.class })</code></li>
145<li><code>AtomicIntegerFieldUpdater.newUpdater(SomeClass.class, "someField")</code></li>
146<li><code>AtomicLongFieldUpdater.newUpdater(SomeClass.class, "someField")</code></li>
147<li><code>AtomicReferenceFieldUpdater.newUpdater(SomeClass.class, SomeType.class, "someField")</code></li>
148</ul>
149
150The names of the classes and class members may of course be different, but the
151constructs should be literally the same for ProGuard to recognize them. The
152referenced classes and class members are preserved in the shrinking phase, and
153the string arguments are properly updated in the obfuscation phase.
154<p>
155Furthermore, ProGuard will offer some suggestions if keeping some classes or
156class members appears necessary. For example, ProGuard will note constructs
157like "<code>(SomeClass)Class.forName(variable).newInstance()</code>". These
158might be an indication that the class or interface <code>SomeClass</code>
159and/or its implementations may need to be preserved. You can then adapt your
160configuration accordingly.
161<p>
162For proper results, you should at least be somewhat familiar with the code
163that you are processing. Obfuscating code that performs a lot of reflection
164may require trial and error, especially without the necessary information
165about the internals of the code.
166
167<hr />
168<address>
169Copyright &copy; 2002-2014
170<a target="other" href="http://www.lafortune.eu/">Eric Lafortune</a> @ <a target="top" href="http://www.saikoa.com/">Saikoa</a>.
171</address>
172</body>
173</html>
174