/external/proguard/docs/FAQ.html
HTML | 254 lines | 213 code | 41 blank | 0 comment | 0 complexity | b0369c00eeb78e8635022e0968b7562b MD5 | raw file
- <!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 FAQ</title>
- </head>
- <body>
- <h2>Frequently Asked Questions</h2>
- <h3>Contents</h3>
- <ol>
- <li><a href="#shrinking">What is shrinking?</a>
- <li><a href="#obfuscation">What is obfuscation?</a>
- <li><a href="#preverification">What is preverification?</a>
- <li><a href="#optimization">What kind of optimizations does <b>ProGuard</b>
- support?</a>
- <li><a href="#commercial">Can I use <b>ProGuard</b> to process my commercial
- application?</a>
- <li><a href="#jdk1.4">Does <b>ProGuard</b> work with Java 2? Java 5? Java
- 6?</a>
- <li><a href="#jme">Does <b>ProGuard</b> work with Java Micro Edition?</a>
- <li><a href="#android">Does <b>ProGuard</b> work for Google Android code?</a>
- <li><a href="#blackberry">Does <b>ProGuard</b> work for Blackberry code?</a>
- <li><a href="#ant">Does <b>ProGuard</b> have support for Ant?</a>
- <li><a href="#gui">Does <b>ProGuard</b> come with a GUI?</a>
- <li><a href="#forname">Does <b>ProGuard</b> handle <code>Class.forName</code>
- calls?</a>
- <li><a href="#resource">Does <b>ProGuard</b> handle resource files?</a>
- <li><a href="#encrypt">Does <b>ProGuard</b> encrypt strings constants?</a>
- <li><a href="#flow">Does <b>ProGuard</b> perform control flow obfuscation?</a>
- <li><a href="#incremental">Does <b>ProGuard</b> support incremental
- obfuscation?</a>
- <li><a href="#keywords">Can <b>ProGuard</b> obfuscate using reserved
- keywords?</a>
- <li><a href="#stacktrace">Can <b>ProGuard</b> reconstruct obfuscated stack
- traces?</a>
- </ol>
- <a name="shrinking"> </a>
- <h3>What is shrinking?</h3>
- Java source code (.java files) is typically compiled to bytecode (.class
- files). Bytecode is more compact than Java source code, but it may still
- contain a lot of unused code, especially if it includes program libraries.
- Shrinking programs such as <b>ProGuard</b> can analyze bytecode and remove
- unused classes, fields, and methods. The program remains functionally
- equivalent, including the information given in exception stack traces.
- <a name="obfuscation"> </a>
- <h3>What is obfuscation?</h3>
- By default, compiled bytecode still contains a lot of debugging information:
- source file names, line numbers, field names, method names, argument names,
- variable names, etc. This information makes it straightforward to decompile
- the bytecode and reverse-engineer entire programs. Sometimes, this is not
- desirable. Obfuscators such as <b>ProGuard</b> can remove the debugging
- information and replace all names by meaningless character sequences, making
- it much harder to reverse-engineer the code. It further compacts the code as a
- bonus. The program remains functionally equivalent, except for the class
- names, method names, and line numbers given in exception stack traces.
- <a name="preverification"> </a>
- <h3>What is preverification?</h3>
- When loading class files, the class loader performs some sophisticated
- verification of the byte code. This analysis makes sure the code can't
- accidentally or intentionally break out of the sandbox of the virtual machine.
- Java Micro Edition and Java 6 introduced split verification. This means that
- the JME preverifier and the Java 6 compiler add preverification information to
- the class files (StackMap and StackMapTable attributes, respectively), in order
- to simplify the actual verification step for the class loader. Class files can
- then be loaded faster and in a more memory-efficient way. <b>ProGuard</b> can
- perform the preverification step too, for instance allowing to retarget older
- class files at Java 6.
- <a name="optimization"> </a>
- <h3>What kind of optimizations does <b>ProGuard</b> support?</h3>
- Apart from removing unused classes, fields, and methods in the shrinking step,
- <b>ProGuard</b> can also perform optimizations at the bytecode level, inside
- and across methods. Thanks to techniques like control flow analysis, data flow
- analysis, partial evaluation, static single assignment, global value numbering,
- and liveness analysis, <b>ProGuard</b> can:
- <ul>
- <li>Evaluate constant expressions.
- <li>Remove unnecessary field accesses and method calls.
- <li>Remove unnecessary branches.
- <li>Remove unnecessary comparisons and instanceof tests.
- <li>Remove unused code blocks.
- <li>Merge identical code blocks.
- <li>Reduce variable allocation.
- <li>Remove write-only fields and unused method parameters.
- <li>Inline constant fields, method parameters, and return values.
- <li>Inline methods that are short or only called once.
- <li>Simplify tail recursion calls.
- <li>Merge classes and interfaces.
- <li>Make methods private, static, and final when possible.
- <li>Make classes static and final when possible.
- <li>Replace interfaces that have single implementations.
- <li>Perform over 200 peephole optimizations, like replacing ...*2 by
- ...<<1.
- <li>Optionally remove logging code.
- </ul>
- The positive effects of these optimizations will depend on your code and on
- the virtual machine on which the code is executed. Simple virtual machines may
- benefit more than advanced virtual machines with sophisticated JIT compilers.
- At the very least, your bytecode may become a bit smaller.
- <p>
- Some notable optimizations that aren't supported yet:
- <ul>
- <li>Moving constant expressions out of loops.
- <li>Optimizations that require escape analysis.
- </ul>
- <a name="commercial"> </a>
- <h3>Can I use <b>ProGuard</b> to process my commercial application?</h3>
- Yes, you can. <b>ProGuard</b> itself is distributed under the GPL, but this
- doesn't affect the programs that you process. Your code remains yours, and
- its license can remain the same.
- <a name="jdk1.4"> </a>
- <h3>Does <b>ProGuard</b> work with Java 2? Java 5? Java 6?</h3>
- Yes, <b>ProGuard</b> supports all JDKs from 1.1 up to and including 6.0. Java 2
- introduced some small differences in the class file format. Java 5 added
- attributes for generics and for annotations. Java 6 introduced preverification
- attributes. <b>ProGuard</b> handles all versions correctly.
- <a name="jme"> </a>
- <h3>Does <b>ProGuard</b> work with Java Micro Edition?</h3>
- Yes. <b>ProGuard</b> itself runs in Java Standard Edition, but you can freely
- specify the run-time environment at which your programs are targeted,
- including Java Micro Edition. <b>ProGuard</b> then also performs the required
- preverification, producing more compact results than the traditional external
- preverifier.
- <p>
- <b>ProGuard</b> also comes with an obfuscator plug-in for the JME Wireless
- Toolkit.
- <a name="android"> </a>
- <h3>Does <b>ProGuard</b> work for Google Android code?</h3>
- Yes. Google's <code>dx</code> compiler converts ordinary jar files into files
- that run on Android devices. By preprocessing the original jar files,
- <b>ProGuard</b> can significantly reduce the file sizes and boost the run-time
- performance of the code.
- <a name="blackberry"> </a>
- <h3>Does <b>ProGuard</b> work for Blackberry code?</h3>
- It should. RIM's proprietary <code>rapc</code> compiler converts ordinary JME
- jar files into cod files that run on Blackberry devices. The compiler performs
- quite a few optimizations, but preprocessing the jar files with
- <b>ProGuard</b> can generally still reduce the final code size by a few
- percent. However, the <code>rapc</code> compiler also seems to contain some
- bugs. It sometimes fails on obfuscated code that is valid and accepted by other
- JME tools and VMs. Your mileage may therefore vary.
- <a name="ant"> </a>
- <h3>Does <b>ProGuard</b> have support for Ant?</h3>
- Yes. <b>ProGuard</b> provides an Ant task, so that it integrates seamlessly
- into your Ant build processes. You can still use configurations in
- <b>ProGuard</b>'s own readable format. Alternatively, if you prefer XML, you
- can specify the equivalent XML configuration.
- <a name="gui"> </a>
- <h3>Does <b>ProGuard</b> come with a GUI?</h3>
- Yes. First of all, <b>ProGuard</b> is perfectly usable as a command-line tool
- that can easily be integrated into any automatic build process. For casual
- users, there's also a graphical user interface that simplifies creating,
- loading, editing, executing, and saving ProGuard configurations.
- <a name="forname"> </a>
- <h3>Does <b>ProGuard</b> handle <code>Class.forName</code> calls?</h3>
- Yes. <b>ProGuard</b> automatically handles constructs like
- <code>Class.forName("SomeClass")</code> and <code>SomeClass.class</code>. The
- referenced classes are preserved in the shrinking phase, and the string
- arguments are properly replaced in the obfuscation phase.
- <p>
- With variable string arguments, it's generally not possible to determine their
- possible values. They might be read from a configuration file, for instance.
- However, <b>ProGuard</b> will note a number of 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. The user can adapt his configuration
- accordingly.
- <a name="resource"> </a>
- <h3>Does <b>ProGuard</b> handle resource files?</h3>
- Yes. <b>ProGuard</b> copies all non-class resource files, optionally adapting
- their names and their contents to the obfuscation that has been applied.
- <a name="encrypt"> </a>
- <h3>Does <b>ProGuard</b> encrypt strings constants?</h3>
- No. Storing encrypted string constants in program code is fairly futile, since
- the encryption has to be perfectly reversible by definition. Moreover, the
- decryption costs additional memory and computation at run-time. If this feature
- is ever incorporated, I'll provide a tool to decrypt the strings as well.
- <a name="flow"> </a>
- <h3>Does <b>ProGuard</b> perform flow obfuscation?</h3>
- Not explicitly. Control flow obfuscation injects additional branches into the
- bytecode, in an attempt to fool decompilers. <b>ProGuard</b> does not do this,
- in order to avoid any negative effects on performance and size. However, the
- optimization step often already restructures the code to the point where most
- decompilers get confused.
- <a name="incremental"> </a>
- <h3>Does <b>ProGuard</b> support incremental obfuscation?</h3>
- Yes. This feature allows you to specify a previous obfuscation mapping file in
- a new obfuscation step, in order to produce add-ons or patches for obfuscated
- code.
- <a name="keywords"> </a>
- <h3>Can <b>ProGuard</b> obfuscate using reserved keywords?</h3>
- Yes. You can specify your own obfuscation dictionary, such as a list of
- reserved key words, identifiers with foreign characters, random source files,
- or a text by Shakespeare. Note that this hardly improves the obfuscation.
- Decent decompilers can automatically replace reserved keywords, and the effect
- can be undone fairly easily, by obfuscating again with simpler names.
- <a name="stacktrace"> </a>
- <h3>Can <b>ProGuard</b> reconstruct obfuscated stack traces?</h3>
- Yes. <b>ProGuard</b> comes with a companion tool, <b>ReTrace</b>, that can
- 'de-obfuscate' stack traces produced by obfuscated applications. The
- reconstruction is based on the mapping file that <b>ProGuard</b> can write
- out. If line numbers have been obfuscated away, a list of alternative method
- names is presented for each obfuscated method name that has an ambiguous
- reverse mapping. Please refer to the <a href="manual/index.html">ProGuard User
- Manual</a> for more details.
- <hr>
- <address>
- Copyright © 2002-2009
- <a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>.
- </address>
- </body>
- </html>