diff options
| author | Joe Onorato <joeo@android.com> | 2009-08-31 10:12:00 -0700 |
|---|---|---|
| committer | Joe Onorato <joeo@android.com> | 2009-08-31 10:12:00 -0700 |
| commit | b72c5c2e5482cf10117b2b25f642f7616b2326c3 (patch) | |
| tree | f02ba1bc29f4fe6853d9b7008eed37cdcfb96e81 /docs | |
| parent | a23344a828357fe4b6596f8af5fed467d72757ab (diff) | |
| download | proguard-b72c5c2e5482cf10117b2b25f642f7616b2326c3.tar.gz | |
ProGuard 4.4android-sdk-tools_r4android-sdk-tools_r3android-sdk-2.1_r1android-sdk-2.0_r1android-sdk-2.0.1_r1android-sdk-2.0.1-docs_r1android-2.1_r2.1sandroid-2.1_r2.1p2android-2.1_r2.1pandroid-2.1_r2android-2.1_r1android-2.0_r1android-2.0.1_r1eclair-sholes-release2eclair-sholes-releaseeclair-releaseeclair-passion-release
Diffstat (limited to 'docs')
56 files changed, 8792 insertions, 0 deletions
diff --git a/docs/FAQ.html b/docs/FAQ.html new file mode 100644 index 0000000..8f19b15 --- /dev/null +++ b/docs/FAQ.html @@ -0,0 +1,254 @@ +<!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> diff --git a/docs/GPL.html b/docs/GPL.html new file mode 100644 index 0000000..c7a2458 --- /dev/null +++ b/docs/GPL.html @@ -0,0 +1,406 @@ +<!DOCTYPE html PUBLIC "-//IETF//DTD HTML 2.0//EN"> +<HTML> +<HEAD> +<TITLE>GNU General Public License</TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#1F00FF" ALINK="#FF0000" VLINK="#9900DD"> +<H1>GNU General Public License</H1> +<H2>Table of Contents</H2> +<UL> + + <LI><A NAME="TOC1" HREF="#SEC1">GNU GENERAL PUBLIC LICENSE</A> +<UL> +<LI><A NAME="TOC2" HREF="#SEC2">Preamble</A> +<LI><A NAME="TOC3" HREF="#SEC3">TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</A> + +</UL> +</UL> + +<P> + +<HR> + +<P> + + + +<H2><A NAME="SEC1" HREF="#TOC1">GNU GENERAL PUBLIC LICENSE</A></H2> +<P> +Version 2, June 1991 + +</P> + +<PRE> +Copyright (C) 1989, 1991 Free Software Foundation, Inc. +59 Temple Place - Suite 330, Boston, MA 02111-1307, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +</PRE> + + + +<H2><A NAME="SEC2" HREF="#TOC2">Preamble</A></H2> + +<P> + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + +</P> +<P> + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + +</P> +<P> + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + +</P> +<P> + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + +</P> +<P> + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + +</P> +<P> + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + +</P> +<P> + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + +</P> +<P> + The precise terms and conditions for copying, distribution and +modification follow. + +</P> + + +<H2><A NAME="SEC3" HREF="#TOC3">TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</A></H2> + + +<P> + +<STRONG>0.</STRONG> + This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". +<P> + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + +<P> + +<STRONG>1.</STRONG> + You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. +<P> + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. +<P> + +<STRONG>2.</STRONG> + You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: +<P> + +<UL> + +<LI><STRONG>a)</STRONG> + You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + +<P> +<LI><STRONG>b)</STRONG> + You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + +<P> +<LI><STRONG>c)</STRONG> + If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) +</UL> + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. +<P> + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. +<P> + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +<P> + +<STRONG>3.</STRONG> + You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + +<!-- we use this doubled UL to get the sub-sections indented, --> +<!-- while making the bullets as unobvious as possible. --> +<UL> + +<LI><STRONG>a)</STRONG> + Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + +<P> +<LI><STRONG>b)</STRONG> + Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + +<P> +<LI><STRONG>c)</STRONG> + Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) +</UL> + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. +<P> + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. +<P> + +<STRONG>4.</STRONG> + You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + +<P> + +<STRONG>5.</STRONG> + You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + +<P> + +<STRONG>6.</STRONG> + Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + +<P> + +<STRONG>7.</STRONG> + If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. +<P> + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. +<P> + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. +<P> + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +<P> + +<STRONG>8.</STRONG> + If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + +<P> + +<STRONG>9.</STRONG> + The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. +<P> + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + +<P> + + +<STRONG>10.</STRONG> + If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + + +<P><STRONG>NO WARRANTY</STRONG></P> + +<P> + +<STRONG>11.</STRONG> + BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + +<P> + +<STRONG>12.</STRONG> + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + +<P> + + +<H2>END OF TERMS AND CONDITIONS</H2> +</BODY> +</HTML> diff --git a/docs/GPL_exception.html b/docs/GPL_exception.html new file mode 100644 index 0000000..0a44d66 --- /dev/null +++ b/docs/GPL_exception.html @@ -0,0 +1,52 @@ +<!DOCTYPE html PUBLIC "-//IETF//DTD HTML 2.0//EN"> +<HTML> +<HEAD> +<TITLE>Special Exception to the GNU General Public License</TITLE> +</HEAD> +<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#1F00FF" ALINK="#FF0000" VLINK="#9900DD"> +<H1>Special Exception to the GNU General Public License</H1> + +<P> +Copyright © 2002-2009 Eric Lafortune +</P> + +<P> +This program is free software; you can redistribute it and/or modify it under +the terms of the GNU General Public License as published by the Free Software +Foundation; either version 2 of the License, or (at your option) any later +version. +</P> + +<P> +This program is distributed in the hope that it will be useful, but WITHOUT +ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. +</P> + +<P> +You should have received a copy of the GNU General Public License along with +this program; if not, write to the Free Software Foundation, Inc., 59 Temple +Place, Suite 330, Boston, MA 02111-1307 USA +</P> + +<P> +In addition, as a special exception, Eric Lafortune gives permission to link +the code of this program with the following stand-alone applications: +<ul> +<li>Apache Ant, +<li>Apache Maven, +<li>the Eclipse ProGuardDT GUI, +<li>the EclipseME JME IDE, +<li>the Sun NetBeans Java IDE, +<li>the Sun JME Wireless Toolkit, and +<li>the Javaground Tools, +</ul> +and distribute linked combinations including the two. You must obey the GNU +General Public License in all respects for all of the code used other than +these programs. If you modify this file, you may extend this exception to your +version of the file, but you are not obligated to do so. If you do not wish to +do so, delete this exception statement from your version. +</P> + +</BODY> +</HTML> diff --git a/docs/acknowledgements.html b/docs/acknowledgements.html new file mode 100644 index 0000000..af19461 --- /dev/null +++ b/docs/acknowledgements.html @@ -0,0 +1,68 @@ +<!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 Acknowledgements</title> +</head> +<body> + +<h2>Acknowledgements</h2> + +The first versions of <b>ProGuard</b> grew out of <b>RetroGuard</b>, which its +author Mark Welsh kindly made available under the GNU Lesser General Public +License. <b>RetroGuard</b> is a very nice piece of code, but it only performed +obfuscation. I started from the class file parsing code and wrote my own +shrinker, optimizer, obfuscator, and preverifier. As of version 4.0, all of the +original code has been rewritten, so the most obvious remaining similarity are +the program names. +<p> + +Dirk Schnelle has contributed and maintained the first versions of the Ant +task. I have rewritten the implementation for version 3.0, but the XML schema +is still based on his work. +<p> + +Since its first public release, many people have expressed their enthusiasm and +have chimed in with interesting ideas, bug reports, and bug fixes: Thorsten +Heit, Oliver Retzl, Jonathan Knudsen, Tarcisio Camara, Bob Drury, Dave Jarvis, +Marc Chapman, Dave Morehouse, Richard Osbaldeston, Peter Hawkins, Mark +Sherington, David Sitsky, James Manning, Ptolemy Oberin, Frank-Michael Moser, +QZ Shines, Thomas Singer, Michele Puccini, Roman Bednarek, Natalia Pujol, +Daniel Sjöblom, Jan Filipsky, Charles Smith, Gerrit Telkamp, Noel +Grandin, Torbjörn Söderstedt, Clemens Eisserer, Clark Bassett, +Eduard Welch, Dawid Weiss, Andrew Wilson, Sean Owen, Niels Gron, Ishan Mehta, +Steven Adams, Xavier Kral, +and many others. Thanks! Your feedback has been invaluable. +<p> + +I am developing ProGuard in my spare time, which is possible thanks to my +day-time job at <a href="http://www.luciad.com/" target="other">Luciad</a>. +<p> + +<a href="http://sourceforge.net/projects/proguard/" +target="other">SourceForge</a> is generously providing the resources for +hosting this project and many other projects. +<p> + +JetBrains is kindly providing a license for its IntelliJ IDEA development +environment. +<p> + +The code and these web pages were written using Sun's JDKs, Linux, IntelliJ +IDEA, GNU emacs, bash, sed, awk, and a whole host of other tools that continue +to make programming interesting. +<p> + +And finally, I'm a great fan of the <a +href="http://www.javadocking.com/" target="other">Java Docking Library</a>. + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> + +</body> +</html> diff --git a/docs/alternatives.html b/docs/alternatives.html new file mode 100644 index 0000000..fa5db0c --- /dev/null +++ b/docs/alternatives.html @@ -0,0 +1,657 @@ +<!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 Alternatives</title> +</head> +<body> + +<h2>Alternatives</h2> + +There are quite a few Java class file shrinkers, optimizers, obfuscators, and +preverifiers out there. Users of <b>ProGuard</b> tell me it easily compares +with the best of them. However, you may want to check that out yourself. +<p> +This is a list of the programs of which I'm aware. Obviously, I've never +personally tested all of them. Many programs, even commercial ones, have been +abandoned. Please drop me a note if you know of any other shrinkers, +optimizers, obfuscators, or preverifiers, or if some information provided +below is incorrect. +<p> + +<table> + +<tr> +<th>Author/Company</th> +<th>Program</th> +<th>Shrink.</th> +<th>Optim.</th> +<th>Obfusc.</th> +<th>Preverif.</th> +<th>License</th> +</tr> + +<tr> +<td><a target="other" href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a></td> +<td><a target="_top" href="http://proguard.sourceforge.net/">ProGuard</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td>Free (GPL)</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.informatik.uni-oldenburg.de/leute/hoenicke.html">Jochen Hoenicke</a></td> +<td><a target="other" href="http://jode.sourceforge.net/">Jode</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Free (GPL)</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.nq4.de/">NQ4</a></td> +<td><a target="other" href="http://www.nq4.de/">Joga</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Free (no source)</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.cs.cornell.edu/nystrom/">Nate Nystrom</a></td> +<td><a target="other" href="http://www.cs.purdue.edu/homes/hosking/bloat/">Bloat</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td>Free</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://sourceforge.net/users/hchacha/">Hidetoshi Ohuchi</a></td> +<td><a target="other" href="http://jarg.sourceforge.net/">Jarg</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Free (BSD)</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.geocities.com/CapeCanaveral/Hall/2334/resume.html">Alexander Shvets</a></td> +<td><a target="other" href="http://www.geocities.com/CapeCanaveral/Hall/2334/Programs/cafebabe.html">CafeBabe</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Free</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.yworks.com/">yWorks</a></td> +<td><a target="other" href="http://www.yworks.com/en/products_yguard_about.htm">yGuard</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Free (no source)</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.cs.purdue.edu/homes/grothoff/">Christian Grothoff</a></td> +<td><a target="other" href="http://www.ovmj.org/jamit/">Jamit</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td>Free (GPL)</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://mojo.codehaus.org/">Mojo</a></td> +<td><a target="other" href="http://mojo.codehaus.org/minijar-maven-plugin/">Minijar</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td>Free (Apache)</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.riggshill.com/">RiggsHill Software</a></td> +<td><a target="other" href="http://genjar.sourceforge.net/">GenJar</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td>Free (Apache)</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://ant.apache.org/">Apache</a></td> +<td><a target="other" href="http://ant.apache.org/manual/OptionalTypes/classfileset.html">Ant Classfileset</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td>Free (Apache)</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.curious-creature.org/">Romain Guy</a></td> +<td><a target="other" href="http://www.jroller.com/gfx/entry/get_what_you_need_from">Harvester</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td>Free (BSD)</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="https://dcd.dev.java.net/">Emeric Vernat</a></td> +<td><a target="other" href="https://dcd.dev.java.net/">DCD</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td>Free (LGPL)</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://sadun-util.sourceforge.net/">Cristiano Sadun</a></td> +<td><a target="other" href="http://sadun-util.sourceforge.net/pack.html">Pack</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td>Free (LGPL)</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://darcs.brianweb.net/">Brian Alliet</a></td> +<td><a target="other" href="http://darcs.brianweb.net/gcclass/">Gcclass</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td>Free (LGPL)</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.sable.mcgill.ca/">Sable</a></td> +<td><a target="other" href="http://www.sable.mcgill.ca/soot/">Soot</a></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td>Free (LGPL)</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.garret.ru/~knizhnik/">Konstantin Knizhnik</a></td> +<td><a target="other" href="http://www.garret.ru/~knizhnik/javago/ReadMe.htm">JavaGO</a></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td>Free</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://donquixote.cafebabe.jp/">Haruaki Tamada</a></td> +<td><a target="other" href="http://donquixote.cafebabe.jp/">DonQuixote</a></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Free</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.sable.mcgill.ca/">Sable</a></td> +<td><a target="other" href="http://www.sable.mcgill.ca/JBCO/">JBCO</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Free (LGPL)</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://sourceforge.net/users/glurk/">Thorsten Heit</a></td> +<td><a target="other" href="http://sourceforge.net/projects/javaguard/">JavaGuard</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Free (LGPL)</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://mwobfu.sourceforge.net/">Patrick Mueller</a></td> +<td><a target="other" href="http://mwobfu.sourceforge.net/">Mwobfu</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Free (GPL)</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.elegant-software.com/">Elegant Software</a></td> +<td><a target="other" href="http://www.elegant-software.com/software/jmangle/">JMangle</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Free</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.bebbosoft.de/">BebboSoft</a></td> +<td><a target="other" href="http://www.bebbosoft.de/index.html#java/mug/index.html">Bb_mug</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Free (no source)</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.drjava.de/">Dr. Java</a></td> +<td><a target="other" href="http://www.drjava.de/obfuscator/">Marvin Obfuscator</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Free (no source)</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.ibm.com/">IBM</a></td> +<td><a target="other" href="http://www-306.ibm.com/software/wireless/wsdd/">WSDD</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.preemptive.com/">PreEmptive</a></td> +<td><a target="other" href="http://www.preemptive.com/products/dasho/index.html">DashOPro</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.zelix.com/">Zelix</a></td> +<td><a target="other" href="http://www.zelix.com/klassmaster/index.html">KlassMaster</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.s5systems.com/">S5 Systems</a></td> +<td><a target="other" href="http://www.s5systems.com/jPresto.htm">jPresto</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.s-cradle.com/english/index.html">Sophia Cradle</a></td> +<td><a target="other" href="http://www.s-cradle.com/english/products/sophiacompress_java/index.html">SophiaCompress</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.retrologic.com/">RetroLogic</a></td> +<td><a target="other" href="http://www.retrologic.com/">RetroGuard</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.codingart.com/">CodingArt</a></td> +<td><a target="other" href="http://www.codingart.com/codeshield.html">CodeShield</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.e-t.com/">Eastridge Technology</a></td> +<td><a target="other" href="http://www.e-t.com/jshrink.html">Jshrink</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.helseth.com/">Helseth</a></td> +<td><a target="other" href="http://www.helseth.com/HJO.htm">JObfuscator</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.leesw.com/">LeeSoftware</a></td> +<td><a target="other" href="http://www.leesw.com/">Smokescreen Obfuscator</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.vegatech.com/">Vega Technologies</a></td> +<td><a target="other" href="http://www.vegatech.com/jzipper/">JZipper</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.innaworks.com/">Innaworks</a></td> +<td><a target="other" href="http://www.innaworks.com/">mBooster</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.uni-vologda.ac.ru/~c3c/">Sergey Sverdlov</a></td> +<td><a target="other" href="http://www.uni-vologda.ac.ru/~c3c/jco/">J.Class Optimizer</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.smardec.com/">Smardec</a></td> +<td><a target="other" href="//www.allatori.com/">Allatori</a></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://cs.arizona.edu/">U. of Arizona</a></td> +<td><a target="other" href="http://sandmark.cs.arizona.edu/">SandMark</a></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.force5.com/">Force 5</a></td> +<td><a target="other" href="http://www.force5.com/">JCloak</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.semdesigns.com/">Semantic Designs</a></td> +<td><a target="other" href="http://www.semdesigns.com/Products/Obfuscators/JavaObfuscator.html">Obfuscator</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.duckware.com/">Duckware</a></td> +<td><a target="other" href="http://www.duckware.com/jobfuscate/">Jobfuscate</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.jproof.com/">JProof</a></td> +<td><a target="other" href="http://www.jproof.com/">JProof</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.solutia.ro/">GITS</a></td> +<td><a target="other" href="http://www.solutia.ro/pages/javadc/">Blurfuscator</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.chainkey.com/">ChainKey</a></td> +<td><a target="other" href="http://www.chainkey.com/en/jcp/">Java Code Protector</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://sourceforge.net/projects/flmobf/">Alain Moran</a></td> +<td><a target="other" href="http://sourceforge.net/projects/flmobf/">flmObf</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Free (BSD)</td> +</tr> + +<tr> +<td><a target="other" rel="nofollow" href="http://www.chez.com/vasile/">Vasile Calmatui</a></td> +<td><a target="other" href="http://www.chez.com/vasile/obfu/VasObfuLite.html">VasObfuLite</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Free</td> +</tr> + +<tr class="disappeared"> +<td><a target="other" rel="nofollow" href="http://www.alphaworks.ibm.com/">IBM AlphaWorks</a></td> +<td><a target="other" href="http://www.research.ibm.com/jax/">JAX</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>(discontinued)</td> +</tr> + +<tr class="disappeared"> +<td><a target="other" rel="nofollow" href="http://www-i2.informatik.rwth-aachen.de/~markusj/">Markus Jansen</a></td> +<td><a target="other" rel="nofollow" href="http://www-i2.informatik.rwth-aachen.de/~markusj/jopt/">Jopt</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>(disappeared?)</td> +</tr> + +<tr class="disappeared"> +<td><a target="other" rel="nofollow" href="http://www.primenet.com/~ej">Eron Jokipii</a></td> +<td><a target="other" rel="nofollow" href="http://www.primenet.com/~ej">Jobe</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>(disappeared?)</td> +</tr> + +<tr class="disappeared"> +<td><a target="other" rel="nofollow" href="http://jrc.krdl.org.sg/">JRC</a></td> +<td><a target="other" rel="nofollow" href="http://jrc.krdl.org.sg/decaf/">DeCaf</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>(disappeared?)</td> +</tr> + +<tr class="disappeared"> +<td><a target="other" rel="nofollow" href="http://www.utdallas.edu/~gxz014000/">Bajie</a></td> +<td><a target="other" rel="nofollow" href="http://www.utdallas.edu/~gxz014000/jcmp/">JCMP</a></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>(disappeared?)</td> +</tr> + +<tr class="disappeared"> +<td><a target="other" rel="nofollow" href="http://www.plumbdesign.com/">Plumb Design</a></td> +<td><a target="other" rel="nofollow" href="http://www.condensity.com/">Condensity</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial (discontinued)</td> +</tr> + +<tr class="disappeared"> +<td><a target="other" rel="nofollow" href="http://www.4thpass.com/">4th Pass</a></td> +<td><a target="other" rel="nofollow" href="http://www.4thpass.com/">SourceGuard</a></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial (discontinued?)</td> +</tr> + +<tr class="disappeared"> +<td><a target="other" rel="nofollow" href="http://www.software4j.com/">Software4j</a></td> +<td><a target="other" rel="nofollow" href="http://www.software4j.com/obfuscate4j/">Obfuscate4j</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial (discontinued?)</td> +</tr> + +<tr class="disappeared"> +<td><a target="other" rel="nofollow" href="http://www.jammconsulting.com/">JAMM Consulting</a></td> +<td><a target="other" rel="nofollow" href="http://www.jammconsulting.com/jamm/servlet/com.jammconsulting.servlet.JAMMServlet?pageId=ObfuscateProPage">ObfuscatePro</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial (discontinued?)</td> +</tr> + +<tr class="disappeared"> +<td><a target="other" rel="nofollow" href="http://www.jdevelop.com/">JDevelop</a></td> +<td><a target="other" rel="nofollow" href="http://www.jdevelop.com/best-java-obfuscator.html">JSCO</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial (discontinued?)</td> +</tr> + +<tr class="disappeared"> +<td><a target="other" rel="nofollow" href="http://www.4fang.net/">4Fang</a></td> +<td><a target="other" rel="nofollow" href="http://www.4fang.net/jmix/">JMix</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial (discontinued?)</td> +</tr> + +<tr class="disappeared"> +<td><a target="other" rel="nofollow" href="http://www.2lkit.com/">2LKit</a></td> +<td><a target="other" rel="nofollow" href="http://www.2lkit.com/products/2LKitObf/index.htm">2LKit Obfuscator</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial (disappeared?)</td> +</tr> + +<tr class="disappeared"> +<td><a target="other" rel="nofollow" href="http://www.wingsoft.com/">WingSoft</a></td> +<td><a target="other" rel="nofollow" href="http://www.wingsoft.com/wingguard.html">WingGuard</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial (disappeared?)</td> +</tr> + +<tr class="disappeared"> +<td><a target="other" rel="nofollow" href="http://www.sbktech.org/">HashJava</a></td> +<td><a target="other" rel="nofollow" href="http://www.sbktech.org/">HashJava</a></td> +<td align="center"><br></td> +<td align="center"><br></td> +<td align="center"><img src="checkmark.gif" width="11" height="11" alt="x"></td> +<td align="center"><br></td> +<td>Commercial (disappeared?)</td> +</tr> + +</table> +<p> +All trademarks are property of their respective holders. + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> + +</body> +</html> diff --git a/docs/checkmark.gif b/docs/checkmark.gif Binary files differnew file mode 100644 index 0000000..8afa677 --- /dev/null +++ b/docs/checkmark.gif diff --git a/docs/downloads.html b/docs/downloads.html new file mode 100644 index 0000000..ebd1b28 --- /dev/null +++ b/docs/downloads.html @@ -0,0 +1,521 @@ + +<!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 Downloads</title> +</head> +<body> + +<h2>Downloads</h2> + +<b>ProGuard</b> is distributed under the terms of the GNU General Public +License. Please consult the <a href="license.html">license page</a> for more +details. +<p> +<b>ProGuard</b> is written in Java, so it requires a Java Runtime Environment + (JRE 1.4 or higher). +<p> +You can download the latest release (containing the program jar, the +documentation you're reading now, examples, and the source code) from this +location: +<p> +<center><a href="http://sourceforge.net/project/showfiles.php?group_id=54750" +target="other">Download section</a> (at <a +href="http://sourceforge.net/projects/proguard/" +target="other">SourceForge</a>)</center> +<p> + +If you're still working with an older version of <b>ProGuard</b>, check out +the summary of changes below, to see if you're missing something essential. +Better look at the up-to-date <a +href="http://proguard.sourceforge.net/downloads.html">on-line version</a> if +you're reading a local copy of this page. +<p> +The download section may also contain updates with sub-minor version numbers. +These versions are typically released shortly after their parent versions, for +applying emergency fixes. Please make sure to look at those if you are +encountering any problems with recent releases. +<p> +Finally, there may be beta versions of upcoming releases. They may be of +interest too, because they typically contain any less urgent bug fixes +collected since the previous release. +<p> + +<h3><div>Jul 2009</div> Version 4.4</h3> +<ul> +<li>Added new peephole optimizations. +<li>Added option <code>-optimizations</code> for fine-grained configuration of + optimizations. +<li>Added option <code>-adaptclassstrings</code> for adapting string constants + that correspond to obfuscated classes. +<li>Added option <code>-keeppackagenames</code> for keeping specified package + names from being obfuscated. +<li>Added option <code>-keepdirectories</code> for keeping specified directory + entries in output jars. +<li>Extended options <code>-dontnote</code> and <code>-dontwarn</code> for + fine-grained configuration of notes and warnings. +<li>Added option <code>-regex</code> in ReTrace, for specifying alternative + regular expressions to parse stack traces. +<li>Extended renaming of resource files based on obfuscation. +<li>Improved inlining of constant parameters and removal of unused parameters. +<li>Avoiding bug in IBM's JVM for JSE, in optimization step. +<li>Avoiding ArrayIndexOutOfBoundsException in optimization step. +<li>Fixed configuration with annotations that are not preserved themselves. +<li>Fixed preverification of invocations of super constructors with arguments + containing ternary operators. +<li>Fixed processing of unreachable exception handlers. +<li>Fixed merging of exception classes. +<li>Fixed repeated method inlining. +<li>Fixed inlining of finally blocks surrounded by large try blocks, compiled + with JDK 1.4 or earlier. +<li>Fixed optimization of complex finally blocks, compiled with JDK 1.4 or + earlier. +<li>Fixed obfuscation of anonymous class names, if <code>EnclosingMethod</code> + attributes are being kept. +<li>Fixed obfuscation of inner class names in generic types. +<li>Fixed decoding of UTF-8 strings containing special characters. +<li>Fixed copying of debug information and annotations when merging classes. +<li>Fixed writing out of unknown attributes. +<li>Fixed updating manifest files with split lines. +<li>Updated documentation and examples. +</ul> + +<h3><div>Dec 2008</div> Version 4.3</h3> +<ul> +<li>Added class merging. +<li>Added static single assignment analysis. +<li>Added support for annotation and enumeration class types in configuration. +<li>Refined shrinking of fields in case of unusual + <code>-keepclassmembers</code> options. +<li>Added simplification of tail recursion calls. +<li>Added new peephole optimizations. +<li>Fixed optimization of unused variable initializations causing negative + stack sizes. +<li>Fixed optimization of unusual initialization code causing + NullPointerExceptions. +<li>Fixed optimization of half-used long and double parameters. +<li>Fixed processing of complex generics signatures. +<li>Working around suspected java compiler bug with parameter annotations on + constructors of non-static inner classes. +<li>Fixed obfuscation of classes with inner classes whose names are preserved. +<li>Fixed access of protected methods in repackaged classes. +<li>Added options <code>-classobfuscationdictionary</code> and + <code>-packageobfuscationdictionary</code>. +<li>Adapting more types of resource file names based on obfuscation. +<li>Extended warnings about incorrect dependencies. +<li>Added start-up scripts and build scripts. +<li>Updated documentation and examples. +</ul> + +<h3><div>Mar 2008</div> Version 4.2</h3> +<ul> +<li>Refined data flow analysis in optimization step. +<li>Fixed handling of exceptions when inlining subroutines. +<li>Fixed inlining of incompatible code constructs between different java + versions. +<li>Fixed computation of local variable frame size. +<li>Fixed optimization of infinite loops. +<li>Fixed optimization of subroutine invocations. +<li>Fixed optimization of floating point remainder computations. +<li>Fixed removal of unused parameters in method descriptors containing arrays + of longs or doubles. +<li>Added undocumented java system properties + <code>maximum.inlined.code.length</code> (default is 8) and + <code>maximum.resulting.code.length</code> (defaults are 8000 for JSE and + 2000 for JME), for expert users who read release notes. +<li>Fixed processing of generic types in Signature attributes in shrinking and + optimization steps. +<li>Fixed processing of inner class names in Signature attributes in obfuscation + step. +<li>Improved adapting resource file names following obfuscated class names. +<li>Fixed interpretation of package names in GUI. +<li>Fixed default settings for Xlets in GUI. +<li>Updated documentation and examples. +</ul> + +<h3><div>Dec 2007</div> Version 4.1</h3> +<ul> +<li>Fixed shrinking of default annotation element values. +<li>Fixed optimization of invocations of methods in same class that are + accessed through extensions. +<li>Fixed optimization of invocations of synchronized methods without other + side-effects. +<li>Fixed optimization of some non-returning subroutines. +<li>Fixed handling of local variable debug information when inlining methods. +<li>Avoiding StackOverflowErrors during optimization of complex methods. +<li>Fixed obfuscation of potentially ambiguous non-primitive constants in + interfaces. +<li>Fixed preverification of some code constructs involving String, Class, and + exception types. +<li>The Ant task now allows empty <code><injars></code> and + <code><libraryjars></code> elements. +<li>Updated documentation and examples. +</ul> + +<h3><div>Sep 2007</div> Version 4.0</h3> +<ul> +<li>Added preverifier for Java 6 and Java Micro Edition, with new options + <code>-microedition</code> and <code>-dontpreverify</code>. +<li>Added new option <code>-target</code> to modify java version of processed + class files. +<li>Made <code>-keep</code> options more orthogonal and flexible, with option + modifiers <code>allowshrinking</code>, <code>allowoptimization</code>, and + <code>allowobfuscation</code>. +<li>Added new wildcards for class member descriptors: "<code>***</code>", + matching any type, and "<code>...</code>", matching any number of + arguments. +<li>Added support for configuration by means of annotations. +<li>Improved shrinking of unused annotations. +<li>Added check on modification times of input and output, to avoid unnecessary + processing, with new option <code>-forceprocessing</code>. +<li>Added new options <code>-flattenpackagehierarchy</code> and + <code>-repackageclasses</code> (replacing <code>-defaultpackage</code>) to + control obfuscation of package names. +<li>Added new options <code>-adaptresourcefilenames</code> and + <code>-adaptresourcefilecontents</code>, with file filters, to update + resource files corresponding to obfuscated class names. +<li>Added detection of dynamically accessed fields and methods. +<li>Now treating <code>Exceptions</code> attributes as optional. +<li>Now respecting naming rule for nested class names + (<code>EnclosingClass$InnerClass</code>) in obfuscation step, if + <code>InnerClasses</code> attributes or <code>EnclosingMethod</code> + attributes are being kept. +<li>Added new inter-procedural optimizations: method inlining and propagation + of constant fields, constant arguments, and constant return values. +<li>Added optimized local variable allocation. +<li>Added more than 250 new peephole optimizations. +<li>Improved making classes and class members public or protected. +<li>Now printing notes on suspiciously unkept classes in parameters of + specified methods. +<li>Now printing notes for class names that don't seem to be fully qualified. +<li>Added support for uppercase filename extensions. +<li>Added tool tips to the GUI. +<li>Rewritten class file I/O code. +<li>Updated documentation and examples. +</ul> +Upgrade considerations: +<ul> + +<li>Since ProGuard now treats the <code>Exceptions</code> attribute as + optional, you may have to specify <code>-keepattributes Exceptions</code>, + notably when processing code that is to be used as a library. + +<li>ProGuard now preverifies code for Java Micro Edition, if you specify the + option <code>-microedition</code>. You then no longer need to process the + code with an external preverifier. + +<li>You should preferably specify <code>-repackageclasses</code> instead of the + old option name <code>-defaultpackage</code>. +</ul> + +<h3><div>Dec 2007</div> Version 3.11</h3> +<ul> +<li>Fixed optimization of invocations of methods in same class that are + accessed through extensions. +<li>Fixed optimization of invocations of synchronized methods without other + side-effects. +<li>Updated documentation and examples. +</ul> + +<h3><div>Aug 2007</div> Version 3.10</h3> +<ul> +<li>Now handling mixed-case input class names when + <code>-dontusemixedcaseclassnames</code> is specified. +<li>Fixed optimization of synchronization on classes, as compiled by Eclipse + and Jikes. +<li>Fixed optimization of switch statements with unreachable cases. +<li>Avoiding merging subsequent identically named files. +<li>Updated documentation and examples. +</ul> + +<h3><div>Jun 2007</div> Version 3.9</h3> +<ul> +<li>Fixed processing of .class constructs in Java 6. +<li>Fixed repeated processing of .class constructs. +<li>Fixed possible division by 0 in optimization step. +<li>Fixed handling of variable instructions with variable indices larger than + 255. +<li>Updated documentation and examples. +</ul> + +<h3><div>Mar 2007</div> Version 3.8</h3> +<ul> +<li>Fixed optimization of parameters used as local variables. +<li>Fixed obfuscation with conflicting class member names. +<li>Fixed incremental obfuscation with incomplete mapping file for library jars. +<li>Updated documentation and examples. +</ul> + +<h3><div>Dec 2006</div> Version 3.7</h3> +<ul> +<li>Now accepting Java 6 class files. +<li>Fixed shrinking of partially used annotations. +<li>Improved incremental obfuscation, with new option + <code>-useuniqueclassmembernames</code>. +<li>Printing more information in case of conflicting configuration and input. +<li>Fixed optimization of repeated array length instruction. +<li>Fixed optimization of subsequent try/catch/finally blocks with return + statements. +<li>Fixed optimization of complex stack operations. +<li>Fixed optimization of simple infinite loops. +<li>Fixed optimization of expressions with constant doubles. +<li>Tuned optimization to improve size reduction after preverification. +<li>Fixed overflows of offsets in long code blocks. +<li>Now allowing class names containing dashes. +<li>Updated documentation and examples. +</ul> + +<h3><div>May 2006</div> Version 3.6</h3> +<ul> +<li>No longer automatically keeping classes in parameters of specified methods + from obfuscation and optimization (introduced in version 3.4). +<li>Fixed inlining of interfaces that are used in .class constructs. +<li>Fixed removal of busy-waiting loops reading volatile fields. +<li>Fixed optimization of comparisons of known integers. +<li>Fixed optimization of known branches. +<li>Fixed optimization of method calls on arrays of interfaces. +<li>Fixed optimization of method calls without side-effects. +<li>Fixed optimization of nested try/catch/finally blocks with return + statements. +<li>Fixed initialization of library classes that only appear in descriptors. +<li>Fixed matching of primitive type wildcards in configuration. +<li>Fixed the boilerplate specification for enumerations in the GUI. +<li>Updated documentation and examples. +</ul> + +<h3><div>Jan 2006</div> Version 3.5</h3> +<ul> +<li>Fixed obfuscation of class members with complex visibility. +<li>Fixed optimization bugs causing stack verification errors. +<li>Fixed optimization bug causing overridden methods to be finalized. +<li>Fixed optimization bug causing abstract method errors for retro-fitted + library methods. +<li>Fixed optimization bug evaluating code with constant long values. +<li>Fixed bug in updating of optional local variable table attributes and local + variable type table attributes after optimization. +<li>Fixed interpretation of comma-separated class names without wildcards. +<li>Updated documentation and examples. +</ul> + +<h3><div>Oct 2005</div> Version 3.4</h3> +<ul> +<li>Extended optimizations: removing duplicate code within methods. +<li>Extended regular expressions for class names to comma-separated lists. +<li>Now automatically keeping classes in descriptors of kept class members. +<li>Added verbose statistics for optimizations. +<li>Added boilerplate Number optimizations in GUI. +<li>Fixed <code>Class.forName</code> detection. +<li>Fixed incremental obfuscation bug. +<li>Fixed optimization bug causing stack verification errors. +<li>Fixed optimization bugs related to removal of unused parameters. +<li>Fixed exception when optimizing code with many local variables. +<li>Fixed exception when saving configuration with initializers in GUI. +<li>Updated documentation and examples. +</ul> + +<h3><div>Jun 2005</div> Version 3.3</h3> +<ul> +<li>Extended optimizations: making methods private and static when possible, + making classes static when possible, removing unused parameters. +<li>Made file names relative to the configuration files in which they are + specified. Added <code>-basedirectory</code> option. +<li>Added <code>-whyareyoukeeping</code> option to get details on why given + classes and class members are being kept. +<li>Added warnings for misplaced class files. +<li>Improved printing of notes for <code>Class.forName</code> constructs. +<li>Implemented '<code>assumenosideeffects</code>' nested element in Ant task. +<li>Improved processing of annotations. +<li>Fixed reading and writing of parameter annotations. +<li>Fixed various optimization bugs. +<li>Fixed wildcards not matching '-' character. +<li>Fixed wildcard bug and checkbox bugs in GUI. +<li>Setting file chooser defaults in GUI. +<li>Leaving room for growBox in GUI on Mac OS X. +<li>Properly closing configuration files. +<li>Updated documentation and examples. +</ul> + +<h3><div>Dec 2004</div> Version 3.2</h3> +<ul> +<li>Fixed JDK5.0 processing bugs. +<li>Fixed optimization bugs. +<li>Fixed relative paths in Ant task. +<li>Improved speed of shrinking step. +<li>Updated documentation and examples. +</ul> + +<h3><div>Nov 2004</div> Version 3.1</h3> +<ul> +<li>Improved obfuscation and shrinking of private class members. +<li>Added inlining of interfaces with single implementations. +<li>Added option to specify obfuscation dictionary. +<li>Added option to read package visible library class members. +<li>Extended support for JDK5.0 attributes. +<li>Fixed various optimization bugs. +<li>Modified Ant task to accept paths instead of filesets. +<li>Fixed two Ant task bugs. +<li>Updated documentation and examples. +</ul> + +<h3><div>Aug 2004</div> Version 3.0</h3> +<ul> +<li>Added bytecode optimization step, between shrinking step and obfuscation + step. +<li>Generalized filtered recursive reading and writing of jars, wars, ears, + zips, and directories. +<li>Added support for grouping input and output jars, wars, ears, zips, and + directories. +<li>Added support for applying mapping files to library classes. +<li>Removed <code>-resourcejars</code> option. Resources should now be read + using regular <code>-injars</code> options, using filters if necessary. +<li>Rewrote Ant task. Input and output modification dates are not checked at + the moment. Minor changes in XML schema: + <ul> + <li>Filters now specified using attributes. + <li>'<code>outjars</code>' now nested element instead of attribute. + <li>'<code>type</code>' attribute of <code><method></code> element no + longer defaults to '<code>void</code>'. + <li><code><</code> and <code>></code> characters now have to be + encoded in embedded configurations. + <li><code><proguardconfiguration></code> task no longer accepts + attributes. + </ul> +<li>Updated J2ME WTK plugin, now customizable through configuration file. +<li>Updated GUI. +<li>Fixed various processing bugs. +<li>Fixed ReTrace parsing bugs. +<li>Improved jar compression. +<li>Updated documentation and examples. +</ul> + +<h3><div>Mar 2004</div> Version 2.1</h3> +<ul> +<li>Added support for JDK1.5 classes. +<li>Added additional wildcard for matching primitive types. +<li>Added possibility to switch off notes about duplicate class definitions. +<li>Fixed use of multiple filters on output jars. +<li>Fixed option to keep all attributes. +<li>Fixed various Ant task bugs. +<li>Updated documentation and examples. +</ul> + +<h3><div>Dec 2003</div> Version 2.0</h3> +<ul> +<li>Added a graphical user interface for ProGuard and ReTrace. +<li>Added <code>-applymapping</code> option for incremental obfuscation. +<li>Added support for filtering input and output files. +<li>Added support for the J++ <code>SourceDir</code> attribute. +<li>Improved detection of <code>.class</code> constructs. +<li>Improved handling of misplaced manifest files. +<li>Improved implementation of ReTrace. +<li>Worked around String UTF-8 encoding bug affecting foreign characters. +<li>Fixed exception when ignoring warnings. +<li>Fixed various Ant task bugs. +<li>Updated documentation and examples. +</ul> + +<h3><div>Aug 2003</div> Version 1.7</h3> +<ul> +<li>Fixed various Ant task bugs. +<li>Fixed ClassCastException due to explicitly used abstract classes with + implicitly used interfaces targeted at JRE1.2 (the default in JDK1.4). +<li>Fixed <code>-defaultpackage</code> bug for protected classes and class + members. +<li>Fixed ReTrace bug when retracing without line number tables. +<li>Worked around zip package problems with duplicate out entries and rogue + manifest files. +<li>Added work-around for handling malformed legacy interface class files. +<li>Updated documentation and examples. +</ul> + +<h3><div>May 2003</div> Version 1.6</h3> +<ul> +<li>Added support for Ant. +<li>Added support for the J2ME Wireless Toolkit. +<li>Added support for reading and writing directory hierarchies. +<li>Added option for specifying resource jars and directories. +<li>Added support for wildcards in class member specifications. +<li>Improved handling of the <code>-defaultpackage</code> option. +<li>Improved stack trace parsing in ReTrace tool. +<li>Fixed processing of libraries containing public as well as non-public + extensions of non-public classes. +<li>Fixed examples for processing libraries, midlets, and serializable code. +<li>Updated documentation and examples. +</ul> + +<h3><div>Jan 2003</div> Version 1.5</h3> +<ul> +<li>Fixed processing of retrofitted library interfaces. +<li>Fixed processing of <code>.class</code> constructs in internal classes + targeted at JRE1.2 (the default in JDK1.4). +<li>Fixed <code>-dump</code> option when <code>-outjar</code> option is not + present. +<li>Updated documentation and examples. +</ul> + +<h3><div>Nov 2002</div> Version 1.4</h3> +<ul> +<li>Now copying resource files over from the input jars to the output jar. +<li>Added option to obfuscate using lower-case class names only. +<li>Added better option for obfuscating native methods. +<li>Added option not to ignore non-public library classes. +<li>Added automatic <code>.class</code> detection for classes compiled with + Jikes. +<li>Updated documentation and examples. +</ul> + +<h3><div>Sep 2002</div> Version 1.3</h3> +<ul> +<li>Added support for wildcards in class names. +<li>Added tool to de-obfuscate stack traces. +<li>Added options to print processing information to files. +<li>Added option to rename source file attributes. +<li>Fixed processing of implicitly used interfaces targeted at JRE1.2 (the + default in JDK1.4) +<li>Fixed processing of configurations with negated access modifiers. +<li>Fixed duplicate class entry bug. +<li>Updated documentation and examples. +</ul> + +<h3><div>Aug 2002</div> Version 1.2</h3> +<ul> +<li>Improved speed. +<li>Fixed processing of classes targeted at JRE1.2 (the default in JDK1.4) + with references to their own subclasses. +<li>Fixed processing of static initializers in J2ME MIDP applications. +<li>Fixed processing of retrofitted interfaces (again). +<li>Added more flexible handling of white space in configuration. +<li>Updated documentation. +</ul> + +<h3><div>Jul 2002</div> Version 1.1</h3> +<ul> +<li>Added automatic detection of <code>Class.forName("MyClass")</code>, + <code>MyClass.class</code>, and + <code>(MyClass)Class.forName(variable).newInstance()</code> constructs. + This greatly simplifies configuration. +<li>Added options to keep class names and class member names without affecting + any shrinking. They are mostly useful for native methods and serializable + classes. +<li>Fixed processing of retrofitted interfaces. +<li>Added handling of missing/invalid manifest file in input jar. +<li>Updated documentation and examples. +</ul> + +<h3><div>Jun 2002</div> Version 1.0</h3> +<ul> +<li>First public release, based on class parsing code from Mark Welsh's + <b>RetroGuard</b>. +</ul> + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> + +</body> +</html> diff --git a/docs/drop1.gif b/docs/drop1.gif Binary files differnew file mode 100644 index 0000000..426d856 --- /dev/null +++ b/docs/drop1.gif diff --git a/docs/drop2.gif b/docs/drop2.gif Binary files differnew file mode 100644 index 0000000..b607542 --- /dev/null +++ b/docs/drop2.gif diff --git a/docs/drop3.gif b/docs/drop3.gif Binary files differnew file mode 100644 index 0000000..11ce424 --- /dev/null +++ b/docs/drop3.gif diff --git a/docs/favicon.ico b/docs/favicon.ico Binary files differnew file mode 100644 index 0000000..3923ec1 --- /dev/null +++ b/docs/favicon.ico diff --git a/docs/feedback.html b/docs/feedback.html new file mode 100644 index 0000000..a7e770b --- /dev/null +++ b/docs/feedback.html @@ -0,0 +1,106 @@ +<!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-script-type" content="text/javascript"> +<meta http-equiv="content-style-type" content="text/css"> +<link rel="stylesheet" type="text/css" href="style.css"> +<title>ProGuard Feedback</title> +</head> +<body> + +<h2>Feedback</h2> + +By now, I've invested a fair amount of time in <b>ProGuard</b>. You can help +by providing feedback! If you have problems, bugs, bug fixes, ideas, +encouragements, etc., please let me know: +<p> +<ul> +<li>The <a href="http://sourceforge.net/forum/forum.php?forum_id=182456" + target="other">help forum</a> (at SourceForge) is the right place to ask + questions about any problems you might have configuring and running + <b>ProGuard</b>. + <p> + +<li>The <a href="http://sourceforge.net/forum/forum.php?forum_id=182455" + target="other">open discussion forum</a> (at SourceForge) offers a place + to share your thoughts and discuss new ideas. + <p> + +<li>The <a + + href="http://sourceforge.net/tracker/?atid=474704&group_id=54750&func=browse" + target="other">bug tracking page</a> (at SourceForge) allows you to submit + and consult bug reports. Please make sure the reports are complete and + concise. If I can't reproduce the problem, I most likely can't fix it + either. + <p> + +<li>The <a + + href="http://sourceforge.net/tracker/?atid=474707&group_id=54750&func=browse" + target="other">feature request page</a> (at SourceForge) allows you to + submit and consult feature requests. I generally have my own road map in + mind, but this is the place express your interest in new and existing + ideas. + <p> + +<li>The <a href="http://sourceforge.net/project/showfiles.php?group_id=54750" + target="other">download section</a> at SourceForge and the <a + href="http://software.freshmeat.net/projects/proguard/" + target="other">project page</a> at FreshMeat offer the possibility to + subscribe to the announcements of new releases. They are the most + efficient way to stay abreast of the latest developments. + <p> + +<li>For anything that doesn't fall in the above categories, you can mail me + directly at + +<script type="text/javascript" language="JavaScript"> +<!-- +document.write("<a href=\"ma"); +document.write("ilto:"); +document.write("lafortune"); +document.write("@"); +document.write("users.sourceforge.net\">"); +document.write("lafortune"); +document.write("@"); +document.write("users.sourceforge.net"); +document.write("</a>"); +document.write(" <em>or</em> at "); +document.write("<a href=\"ma"); +document.write("ilto:"); +document.write("eric"); +document.write("@"); +document.write("graphics.cornell.edu\">"); +document.write("eric"); +document.write("@"); +document.write("graphics.cornell.edu"); +document.write("</a>"); +//--> +</script> +<noscript> +< lafortune @ users . sourceforge . net > +<em>or</em> at +< eric @ graphics . cornell . edu > (please remove the spaces) +</noscript> +. +</ul> +<p> +I can't promise a swift answer, or any answer at all, for that matter, but I +like seeing any constructive comments. +<p> + +<b>ProGuard</b> isn't a typical open source project, in the sense that I am +<em>not</em> looking for code contributions. Developing on my own allows me to +do things my way, without the overhead and compromises associated with larger +projects. + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> + +</body> +</html> diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..771bb6a --- /dev/null +++ b/docs/index.html @@ -0,0 +1,72 @@ +<!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-script-type" content="text/javascript"> +<meta http-equiv="content-style-type" content="text/css"> +<meta name="author" content="Eric Lafortune"> +<meta name="description" content="ProGuard: java shrinker, optimizer, obfuscator, and preverifier"> +<meta name="keywords" content="java obfuscator, optimizer, shrinker, preverfier"> +<link rel="stylesheet" type="text/css" href="style.css"> +<link rel="shortcut icon" type="image/x-icon" href="favicon.ico"> +<title>ProGuard</title> +</head> +<frameset + rows="50,*" + framespacing="0" + frameborder="no"> + +<frame + name="title" + src="title.html" + scrolling="no" + marginwidth="0" + marginheight="0" + noresize> + +<frameset + cols="120,*" + framespacing="0" + frameborder="no"> + +<frame + name="sections" + src="sections.html" + scrolling="no" + marginwidth="0" + marginheight="0" + noresize> + +<frame + name="main" + src="main.html" + scrolling="auto" + marginwidth="10" + marginheight="10" + noresize> + +</frameset> +</frameset> + +<noframes> +<body> +<p class="intro"> +<b>ProGuard</b> is a free Java class file shrinker, optimizer, and obfuscator. +It can detect and remove unused classes, fields, methods, and attributes. It +can then optimize bytecode and remove unused instructions. Finally, it can +rename the remaining classes, fields, and methods using short meaningless +names. The resulting jars are smaller and harder to reverse-engineer. +</p> +<p> +Your browser doesn't support frames, but that's cool. +<p> +You can go straight to the <a href="main.html">main page</a>. + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</noframes> +</html> diff --git a/docs/license.html b/docs/license.html new file mode 100644 index 0000000..b4654fd --- /dev/null +++ b/docs/license.html @@ -0,0 +1,47 @@ +<!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 License</title> +</head> +<body> + +<h2>License</h2> + +<b>ProGuard</b> is free. You can use it freely for processing your +applications, commercial or not. Your code obviously remains yours after +having been processed, and its license can remain the same. +<p> + +<b>ProGuard</b> itself is copyrighted, but its distribution license provides +you with some rights for modifying and redistributing its code and its +documentation. More specifically, <b>ProGuard</b> is distributed under the +terms of the <a href="GPL.html">GNU General Public License</a> (GPL), version +2, as published by the <a href="http://www.fsf.org/" target="other">Free +Software Foundation</a> (FSF). In short, this means that you may freely +redistribute the program, modified or as is, on the condition that you make +the complete source code available as well. If you develop a program that is +linked with +<b>ProGuard</b>, the program as a whole has to be distributed at no charge +under the GPL. I am granting a <a href="GPL_exception.html">special +exception</a> to the latter clause (in wording suggested by +the <a href="http://www.gnu.org/copyleft/gpl-faq.html#GPLIncompatibleLibs" +target="other">FSF</a>), for combinations with the following stand-alone +applications: Apache Ant, Apache Maven, the Eclipse ProGuardDT GUI, the +EclipseME JME IDE, the Sun NetBeans Java IDE, the Sun JME Wireless Toolkit, +and the Javaground Tools. + +<p> +The <b>ProGuard user documentation</b> represents an important part of this +work. It may only be redistributed without changes, along with the unmodified +version of the code. + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</html> diff --git a/docs/luciadlogo.png b/docs/luciadlogo.png Binary files differnew file mode 100644 index 0000000..0147ce3 --- /dev/null +++ b/docs/luciadlogo.png diff --git a/docs/main.html b/docs/main.html new file mode 100644 index 0000000..e988c79 --- /dev/null +++ b/docs/main.html @@ -0,0 +1,92 @@ +<!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"> +<meta name="author" content="Eric Lafortune"> +<meta name="description" content="ProGuard: java shrinker, optimizer, obfuscator, and preverifier"> +<meta name="keywords" content="java obfuscator, optimizer, shrinker, preverfier"> +<link rel="stylesheet" type="text/css" href="style.css"> +<title>ProGuard Main</title> +</head> +<body> + +<h2>Main</h2> + +<p class="intro"> +<b>ProGuard</b> is a free Java class file shrinker, optimizer, obfuscator, and +preverifier. It detects and removes unused classes, fields, methods, and +attributes. It optimizes bytecode and removes unused instructions. It renames +the remaining classes, fields, and methods using short meaningless names. +Finally, it preverifies the processed code for Java 6 or for Java Micro +Edition. +</p> +Some uses of <b>ProGuard</b> are: +<ul> + +<li>Creating more compact code, for smaller code archives, faster transfer + across networks, faster loading, and smaller memory footprints. + +<li>Making programs and libraries harder to reverse-engineer. + +<li>Listing dead code, so it can be removed from the source code. + +<li>Retargeting and preverifying existing class files for Java 6, to take full + advantage of Java 6's faster class loading. + +</ul> +<p> +<b>ProGuard</b>'s main advantage compared to other Java obfuscators is +probably its compact template-based configuration. A few intuitive command +line options or a simple configuration file are usually sufficient. For +instance, the following configuration option preserves all applets in a jar: +<pre> + -keep public class * extends java.applet.Applet +</pre> +The user manual explains all available options and shows more examples of this +powerful configuration style. +<p> +<b>ProGuard</b> is fast. It only takes seconds to process programs and +libraries of several megabytes. The results section presents actual figures +for a number of applications. +<p> +<b>ProGuard</b> is a command-line tool with an optional graphical user +interface. It also comes with plugins for Ant and for the JME Wireless +Toolkit. +<p> +<p class="intro"> +Version 4.0 introduced preverification and more bytecode optimizations. Please +report any problems, so they can be fixed soon. +</p> +The following sections provide more detailed information: +<ul> +<li><a href="main.html">Main</a>: this overview page. +<li><a href="results.html">Results</a>: some results obtained with + <b>ProGuard</b>, including timings and memory usage. +<li><a href="FAQ.html">FAQ</a>: answers to some Frequently Asked Questions. +<li><a href="manual/index.html">Manual</a>: the complete <b>ProGuard</b> user + manual, with examples and troubleshooting tips. +<li><a href="quality.html">Quality</a>: a discussion of the (excellent) quality + of <b>ProGuard</b>'s code. +<li><a href="screenshots.html">Screenshots</a>: some impressions of what <b>ProGuard</b> looks like. +<li><a href="testimonials.html">Testimonials</a>: what users think of + <b>ProGuard</b>. +<li><a href="license.html">License</a>: <b>ProGuard</b> is free, under a GPL + license. +<li><a href="downloads.html">Downloads</a>: download the <b>ProGuard</b> + package yourself. +<li><a href="feedback.html">Feedback</a>: tell me about your experiences, or + learn from others on our forums. +<li><a href="acknowledgements.html">Acknowledgements</a>: people who have been + helpful. +<li><a href="alternatives.html">Alternatives</a>: other Java obfuscators, + optimizers, and shrinkers. +</ul> + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</html> diff --git a/docs/manual/ant.html b/docs/manual/ant.html new file mode 100644 index 0000000..bc3a3b4 --- /dev/null +++ b/docs/manual/ant.html @@ -0,0 +1,610 @@ +<!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>Ant Task</title> +</head> +<body> + +<h2>Ant Task</h2> + +<b>ProGuard</b> can be run as a task in the Java-based build tool Ant (version +1.6.0 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: using an external +configuration file, using embedded ProGuard configuration options, or using +the equivalent XML configuration tags. 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 are now +enclosed by an opening <code>${</code> and a closing <code>}</code>. This +syntax also allows you to use Ant properties within the ProGuard +configuration. Other occurrences of <code><</code> and <code>></code> +have to be encoded as <code>&lt;</code> and <code>&gt;</code>. +<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> + +<a name="proguard"> </a> +<h2>Task Attributes and Nested Elements</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 XML-style configurations, use the <a + href="#configuration_element"><code>configuration</code></a> + <i>element</i>.</dd> + +<dt><a href="usage.html#dontskipnonpubliclibraryclasses"><code><b>skipnonpubliclibraryclasses</b></code></a> + = "<i>boolean</i>" + (default = true)</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#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>Targets 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 wars, ears, zips, 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 name of the output jars (or wars, ears, zips, 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 wars, ears, zips, 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 wars, ears, zips, 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></dt> +<dd>Includes the configuration specified in the + <code><proguardconfiguration></code> task (or + <code><proguard></code> task) with the attribute <code>id</code> = + "<i>ref_id</i>". Note that only the nested elements of this configuration + are considered, not the attributes. Also note: for reading ProGuard-style + configuration files, use the <a + href="#configuration_attribute"><code>configuration</code></a> + <i>attribute</i>.</dd> + +</dl> + +<a name="classpath"> </a> +<h2>Class Path Attributes and Nested Elements</h2> + +The jar tags are path tags, so they can have any of the path attributes (or +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 wars, ears, zips, 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 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 tags 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>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>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> + +<a name="keepmodifier"> </a> +<h2>Keep Modifier Attributes</h2> + +The keep tags can have the following <i>modifier</i> attributes: + +<dl> + +<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> + +<a name="classspecification"> </a> +<h2>Class Specification Attributes and Nested Elements</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>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>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> + +<a name="classmemberspecification"> </a> +<h2>Class Member Specification Attributes</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>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-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</html> diff --git a/docs/manual/attention.gif b/docs/manual/attention.gif Binary files differnew file mode 100644 index 0000000..1a0c712 --- /dev/null +++ b/docs/manual/attention.gif diff --git a/docs/manual/examples.html b/docs/manual/examples.html new file mode 100644 index 0000000..3f47fca --- /dev/null +++ b/docs/manual/examples.html @@ -0,0 +1,1302 @@ +<!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 Examples</title> +</head> +<body> + +<h2>Examples</h2> + +Some typical useful configurations: +<ol> +<li><a href="#application">A typical application</a> +<li><a href="#applet">A typical applet</a> +<li><a href="#midlet">A typical midlet</a> +<li><a href="#jcapplet">A typical Java Card applet</a> +<li><a href="#xlet">A typical xlet</a> +<li><a href="#androidapplication">A typical Android application</a> +<li><a href="#library">A typical library</a> +<li><a href="#applications">All possible applications in the input jars</a> +<li><a href="#applets">All possible applets in the input jars</a> +<li><a href="#midlets">All possible midlets in the input jars</a> +<li><a href="#jcapplets">All possible Java Card applets in the input jars</a> +<li><a href="#xlets">All possible xlets in the input jars</a> +<li><a href="#androidapplications">All possible Android applications in the input jars</a> +<li><a href="#servlets">All possible servlets in the input jars</a> +<li><a href="#native">Processing native methods</a> +<li><a href="#callback">Processing callback methods</a> +<li><a href="#enumerations">Processing enumeration classes</a> +<li><a href="#serializable">Processing serializable classes</a> +<li><a href="#beans">Processing bean classes</a> +<li><a href="#annotations">Processing annotations</a> +<li><a href="#database">Processing database drivers</a> +<li><a href="#componentui">Processing ComponentUI classes</a> +<li><a href="#rmi">Processing RMI code</a> +<li><a href="#resourcefiles">Processing resource files</a> +<li><a href="#stacktrace">Producing useful obfuscated stack traces</a> +<li><a href="#repackaging">Obfuscating package names</a> +<li><a href="#restructuring">Restructuring the output archives</a> +<li><a href="#filtering">Filtering the input and the output</a> +<li><a href="#multiple">Processing multiple applications at once</a> +<li><a href="#incremental">Incremental obfuscation</a> +<li><a href="#microedition">Preverifying class files for Java Micro Edition</a> +<li><a href="#upgrade">Upgrading class files to Java 6</a> +<li><a href="#deadcode">Finding dead code</a> +<li><a href="#structure">Printing out the internal structure of class files</a> +<li><a href="#annotated">Using annotations to configure ProGuard</a> +</ol> + +You can find some sample configuration files in the <code>examples</code> +directory of the ProGuard distribution. + +<a name="application"> </a> +<h3>A typical application</h3> +To shrink, optimize, and obfuscate the ProGuard application itself, one would +typically create a configuration file <code>proguard.pro</code> and then type: +<pre> +java -jar proguard.jar @proguard.pro +</pre> +<p> +The configuration file would contain the following options: +<pre> +-injars proguard.jar +-outjars proguard_out.jar +-libraryjars <java.home>/lib/rt.jar +-printmapping proguard.map + +-keep public class proguard.ProGuard { + public static void main(java.lang.String[]); +} +</pre> +<p> +Note the use of the <code><java.home></code> system property; it is +replaced automatically. +<p> +Also note that all type names are fully specified: +<code>proguard.ProGuard</code> and <code>java.lang.String[]</code>. +<p> +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> +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>. For processing 'simple' applications like ProGuard, that is not +required. + +<a name="applet"> </a> +<h3>A typical applet</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>. + +<a name="midlet"> </a> +<h3>A typical midlet</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.1/lib/midpapi20.jar +-libraryjars /usr/local/java/wtk2.1/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. + +<a name="jcapplet"> </a> +<h3>A typical Java Card applet</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. + +<a name="xlet"> </a> +<h3>A typical xlet</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. + +<a name="androidapplication"> </a> +<h3>A typical Android application</h3> +These options shrink, optimize, and obfuscate the simple Android application +based on a single activity <code>mypackage.MyActivity</code>: +<pre> +-injars in.jar +-outjars out.jar +-libraryjars /usr/local/java/android-1.5_r1/platforms/android-1.5/android.jar +-overloadaggressively +-repackageclasses '' +-allowaccessmodification +-optimizations !code/simplification/arithmetic + +-keep public class mypackage.MyActivity +</pre> +<p> +The configuration is very similar to the configuration for midlets, except that +it now targets the Android run-time environment. +<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. +<p> +If applicable, you should add options for processing <a href="#native">native +methods</a>, <a href="#callback">callback methods</a>, and <a +href="#resourcefiles">resource files</a>. + +<a name="library"> </a> +<h3>A typical library</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: +<pre> +-injars in.jar +-outjars out.jar +-libraryjars <java.home>/lib/rt.jar +-printmapping out.map + +-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 class * { + native <methods>; +} + +-keepclassmembers enum * { + public static **[] values(); + public static ** valueOf(java.lang.String); +} + +-keepclassmembers class * implements java.io.Serializable { + static final long serialVersionUID; + 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, to implement the <code>.class</code> +construct. ProGuard will automatically detect them and deal with them, even +when their names have been obfuscated. However, older versions of ProGuard and +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> +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. + +<a name="applications"> </a> +<h3>All possible applications in the input jars</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>. + +<a name="applets"> </a> +<h3>All possible applets in the input jars</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>. + +<a name="midlets"> </a> +<h3>All possible midlets in the input jars</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.1/lib/midpapi20.jar +-libraryjars /usr/local/java/wtk2.1/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. + +<a name="jcapplets"> </a> +<h3>All possible Java Card applets in the input jars</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. + +<a name="xlets"> </a> +<h3>All possible xlets in the input jars</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. + +<a name="androidapplications"> </a> +<h3>All possible Android applications in the input jars</h3> +These options shrink, optimize, and obfuscate all public activities, services, +broadcast receivers, and content providers in <code>in.jar</code>: +<pre> +-injars in.jar +-outjars out.jar +-libraryjars /usr/local/java/android-1.5_r1/platforms/android-1.5/android.jar +-overloadaggressively +-repackageclasses '' +-allowaccessmodification +-optimizations !code/simplification/arithmetic +-printseeds + +-keep public class * extends android.app.Activity +-keep public class * extends android.app.Service +-keep public class * extends android.content.BroadcastReceiver +-keep public class * extends android.content.ContentProvider +</pre> +<p> +We're keeping all classes that extend the base classes that may be referenced +by the <code>AndroidManifest.xml</code> file of the application. +<p> +The <a href="usage.html#printseeds"><code>-printseeds</code></a> option prints +out which implementations 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>, and <a +href="#resourcefiles">resource files</a>. + +<a name="servlets"> </a> +<h3>All possible servlets in the input jars</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>. + +<a name="native"> </a> +<h3>Processing native methods</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 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. +<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. + +<a name="callback"> </a> +<h3>Processing callback methods</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. + +<a name="enumerations"> </a> +<h3>Processing enumeration classes</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 enum * { + public static **[] values(); + public static ** valueOf(java.lang.String); +} +</pre> + +<a name="serializable"> </a> +<h3>Processing serializable classes</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 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. + <p> + +<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; + 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>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://java.sun.com/javase/6/docs/platform/serialization/spec/class.html#4100">Stream + Unique Identifiers</a> of Sun's <a + href="http://java.sun.com/javase/6/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; + 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>". + +</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. + +<a name="beans"> </a> +<h3>Processing bean classes</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 should encompasses 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. + +<a name="annotations"> </a> +<h3>Processing annotations</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> + +<a name="database"> </a> +<h3>Processing database drivers</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). + +<a name="componentui"> </a> +<h3>Processing ComponentUI classes</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. + +<a name="rmi"> </a> +<h3>Processing RMI code</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. + +<a name="resourcefiles"> </a> +<h3>Processing resource files</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. + +<a name="stacktrace"> </a> +<h3>Producing useful obfuscated stack traces</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. + +<a name="repackaging"> </a> +<h3>Obfuscating package names</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. + +<a name="restructuring"> </a> +<h3>Restructuring the output archives</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. + +<a name="filtering"> </a> +<h3>Filtering the input and the output</h3> + +If you want even greater control, you can add filters 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 +the grouping of input and output. + +<a name="multiple"> </a> +<h3>Processing multiple applications at once</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 the processed application jars, with their original names. + +<a name="incremental"> </a> +<h3>Incremental obfuscation</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> + +<a name="microedition"> </a> +<h3>Preverifying class files for Java Micro Edition</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 compared to the traditional external +preverifier. +<pre> +-injars in.jar +-outjars out.jar +-libraryjars /usr/local/java/wtk2.1/lib/midpapi20.jar +-libraryjars /usr/local/java/wtk2.1/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. + +<a name="upgrade"> </a> +<h3>Upgrading class files to Java 6</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. + +<a name="deadcode"> </a> +<h3>Finding dead code</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> + +<a name="structure"> </a> +<h3>Printing out the internal structure of class files</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. + +<a name="annotated"> </a> +<h3>Using annotations to configure ProGuard</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. +<p> + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</html> diff --git a/docs/manual/gui.html b/docs/manual/gui.html new file mode 100644 index 0000000..37684a6 --- /dev/null +++ b/docs/manual/gui.html @@ -0,0 +1,474 @@ +<!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 GUI</title> +</head> +<body> + +<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> +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> + +<a name="proguard"> </a> +<h2>The ProGuard Tab</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> + +<a name="inputoutput"> </a> +<h2>The Input/Output Tab</h2> + +The <i>Input/Output</i> tab contains two lists, respectively to specify the +program jars (or wars, ears, zips, or directories), and the library jars (or +wars, ears, zips, 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>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. +</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. One can specify filters +for class file names and resource file names, for jar file names, for war file +names, for ear file names, and for zip 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>-<a href="usage.html#outjars">outjars</a> +<li>-<a href="usage.html#libraryjars">libraryjars</a> +<li><a href="usage.html#classpath"><i>class_path</i></a> +<li><a href="usage.html#filters"><i>filters</i></a> +</ul> +<p> + +<a name="shrinking"> </a> +<h2>The Shrinking Tab</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>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>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>The <b>Access</b> selections allows to specify constraints on the class or + classes, based on their access modifiers. + +<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>The <b>Class</b> text field takes the fully-qualified name of the class or + classes. The class name can contain wildcards. + +<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>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>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. +</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>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>The <b>Return type</b> text field takes the fully-qualified type of the + field or fields. The type can contain wildcards. + +<li>The <b>Name</b> text field takes the name of the field or fields. The field + name can contain wildcards. +</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>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>The <b>Return type</b> text field takes the fully-qualified type of the method or methods. The type can contain wildcards. + +<li>The <b>Name</b> text field takes the name of the method or methods. The + method name can contain wildcards. + +<li>The <b>Arguments</b> text field takes the comma-separated list of + fully-qualified method arguments. Each of these arguments can contain + wildcards. +</ul> +<p> + +Corresponding configuration options: +<ul type="none"> +<li>-<a href="usage.html#dontshrink">dontshrink</a> +<li>-<a href="usage.html#printusage">printusage</a> +<li>-<a href="usage.html#keep">keep</a> +<li>-<a href="usage.html#keepclassmembers">keepclassmembers</a> +<li>-<a href="usage.html#keepclasseswithmembers">keepclasseswithmembers</a> +</ul> +<p> + +<a name="obfuscation"> </a> +<h2>The Obfuscation Tab</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>-<a href="usage.html#printmapping">printmapping</a> +<li>-<a href="usage.html#applymapping">applymapping</a> +<li>-<a href="usage.html#obfuscationdictionary">obfuscationdictionary</a> +<li>-<a href="usage.html#classobfuscationdictionary">classobfuscationdictionary</a> +<li>-<a href="usage.html#packageobfuscationdictionary">packageobfuscationdictionary</a> +<li>-<a href="usage.html#overloadaggressively">overloadaggressively</a> +<li>-<a href="usage.html#useuniqueclassmembernames">useuniqueclassmembernames</a> +<li>-<a href="usage.html#dontusemixedcaseclassnames">dontusemixedcaseclassnames</a> +<li>-<a href="usage.html#keeppackagenames">keeppackagenames</a> +<li>-<a href="usage.html#flattenpackagehierarchy">flattenpackagehierarchy</a> +<li>-<a href="usage.html#repackageclasses">repackageclasses</a> +<li>-<a href="usage.html#keepattributes">keepattributes</a> +<li>-<a href="usage.html#renamesourcefileattribute">renamesourcefileattribute</a> +<li>-<a href="usage.html#adaptclassstrings">adaptclassstrings</a> +<li>-<a href="usage.html#adaptresourcefilenames">adaptresourcefilenames</a> +<li>-<a href="usage.html#adaptresourcefilecontents">adaptresourcefilecontents</a> +<li>-<a href="usage.html#keepnames">keepnames</a> +<li>-<a href="usage.html#keepclassmembernames">keepclassmembernames</a> +<li>-<a href="usage.html#keepclasseswithmembernames">keepclasseswithmembernames</a> +<li><a href="usage.html#classspecification"><i>class_specification</i></a> +</ul> +<p> + +<a name="optimization"> </a> +<h2>The Optimization Tab</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>-<a href="usage.html#optimizations">optimizations</a> +<li>-<a href="usage.html#optimizationpasses">optimizationpasses</a> +<li>-<a href="usage.html#allowaccessmodification">allowaccessmodification</a> +<li>-<a href="usage.html#mergeinterfacesaggressively">mergeinterfacesaggressively</a> +<li>-<a href="usage.html#assumenosideeffects">assumenosideeffects</a> +<li><a href="usage.html#classspecification"><i>class_specification</i></a> +</ul> +<p> + +<a name="information"> </a> +<h2>The Information Tab</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>-<a href="usage.html#microedition">microedition</a> +<li>-<a href="usage.html#target">target</a> +<li>-<a href="usage.html#verbose">verbose</a> +<li>-<a href="usage.html#dontnote">dontnote</a> +<li>-<a href="usage.html#dontwarn">dontwarn</a> +<li>-<a href="usage.html#ignorewarnings">ignorewarnings</a> +<li>-<a href="usage.html#dontskipnonpubliclibraryclasses">dontskipnonpubliclibraryclasses</a> +<li>-<a href="usage.html#dontskipnonpubliclibraryclassmembers">dontskipnonpubliclibraryclassmembers</a> +<li>-<a href="usage.html#keepdirectories">keepdirectories</a> +<li>-<a href="usage.html#forceprocessing">forceprocessing</a> +<li>-<a href="usage.html#printseeds">printseeds</a> +<li>-<a href="usage.html#printconfiguration">printconfiguration</a> +<li>-<a href="usage.html#dump">dump</a> +<li>-<a href="usage.html#whyareyoukeeping">whyareyoukeeping</a> +</ul> +<p> + +<a name="process"> </a> +<h2>The Process Tab</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> + +<a name="retrace"> </a> +<h2>The ReTrace Tab</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>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>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. +</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> +<p> + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</html> diff --git a/docs/manual/index.html b/docs/manual/index.html new file mode 100644 index 0000000..397b910 --- /dev/null +++ b/docs/manual/index.html @@ -0,0 +1,39 @@ +<!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 Manual</title> +</head> +<body> + +<h2>ProGuard</h2> + +<ol> +<li><a href="introduction.html">Introduction</a> +<li><a href="usage.html">Usage</a> +<li><a href="limitations.html">Limitations</a> +<li><a href="examples.html">Examples</a> +<li><a href="troubleshooting.html">Troubleshooting</a> +<li><a href="refcard.html">Reference Card</a> +<li><a href="gui.html">Graphical User Interface</a> +<li><a href="ant.html">Ant Task</a> +<li><a href="wtk.html">JME Wireless Toolkit Integration</a> +</ol> + +<h2>ReTrace</h2> + +<ol> +<li><a href="retrace/introduction.html">Introduction</a> +<li><a href="retrace/usage.html">Usage</a> +<li><a href="retrace/examples.html">Examples</a> +</ol> + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</html> 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> diff --git a/docs/manual/limitations.html b/docs/manual/limitations.html new file mode 100644 index 0000000..cfe0ff5 --- /dev/null +++ b/docs/manual/limitations.html @@ -0,0 +1,64 @@ +<!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 Limitations</title> +</head> +<body> + +<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> + +<li>For efficiency, ProGuard always ignores any <b>private or package visible + library classes</b> while reading library jars. If any of them are + extended by public library classes, and then extended again by input + classes, ProGuard will complain it can't find them. In that case, you'll + have to use the <code>-dontskipnonpubliclibraryclasses</code> option, and + maybe even the <code>-dontskipnonpubliclibraryclassmembers</code> option. + The graphical user interface has checkboxes for these settings. + <p> + +<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. + <p> + +<li>If an input jar and a library jar contain classes in the <b>same + package</b>, the obfuscated output jar may contain class names that + overlap with class names in the library jar. This is most likely if the + library jar has been obfuscated before, as it will then probably contain + classes named 'a', 'b', etc. Packages should therefore never be split + across input jars and library jars. + <p> + +<li>When obfuscating, ProGuard will write out class files named + "<code>a.class</code>", "<code>b.class</code>", etc. If there is a large + numbers of classes in the same package, it may also write out + <b>"<code>aux.class</code>"</b>. Windows doesn't allow creating files with + this reserved name (among a few other names), so it's generally better to + write the output to a jar, in order to avoid such problems. + <p> + +</ul> +<p> + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</html> diff --git a/docs/manual/optimizations.html b/docs/manual/optimizations.html new file mode 100644 index 0000000..9c20571 --- /dev/null +++ b/docs/manual/optimizations.html @@ -0,0 +1,158 @@ +<!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>Optimizations</title> +</head> +<body> + +<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/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><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 catch blocks.</dd> + +<dt><code><b>code/allocation/variable</b></code></dt> +<dd>Optimizes variable allocation on the local variable frame.</dd> +</dl> +<p> + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</html> diff --git a/docs/manual/refcard.html b/docs/manual/refcard.html new file mode 100644 index 0000000..236f049 --- /dev/null +++ b/docs/manual/refcard.html @@ -0,0 +1,465 @@ +<!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 Reference Card</title> +</head> +<body> + +<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 name 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#dontskipnonpubliclibraryclasses"><code><b>-dontskipnonpubliclibraryclasses</b></code></a></td> +<td>Don't ignore non-public library classes.</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#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 internal structure of the processed class files, 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 entire configuration in traditional ProGuard style, 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><i>filename</i> can contain Java system properties delimited by + '<b><</b>' and '<b>></b>'. +<li>If <i>filename</i> contains special characters, the entire name + should be quoted with single or double quotes. +</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#allowshrinking"><code><b>allowshrinking</b></code></a></td> +<td>The entry points specified in the keep tag may be shrunk.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#allowoptimization"><code><b>allowoptimization</b></code></a></td> +<td>The entry points specified in the keep tag may be optimized.</td> +</tr> + +<tr> +<td valign="top"><a href="usage.html#allowobfuscation"><code><b>allowobfuscation</b></code></a></td> +<td>The entry points specified in the keep tag may be obfuscated.</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>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><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. +</ul> +<p> + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</html> diff --git a/docs/manual/retrace/examples.html b/docs/manual/retrace/examples.html new file mode 100644 index 0000000..211017b --- /dev/null +++ b/docs/manual/retrace/examples.html @@ -0,0 +1,336 @@ +<!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>ReTrace Examples</title> +</head> +<body> + +<h2>Examples</h2> + +Some typical example uses: +<ol> +<li><a href="#with">Restoring a stack trace with line numbers</a> +<li><a href="#withverbose">Restoring a stack trace with line numbers (verbose)</a> +<li><a href="#without">Restoring a stack trace without line numbers</a> +</ol> + +<a name="with"> </a> +<h3>Restoring a stack trace with line numbers</h3> + +Assume for instance ProGuard itself has been obfuscated using the following +extra options: +<pre> +-printmapping proguard.map + +-renamesourcefileattribute ProGuard +-keepattributes SourceFile,LineNumberTable +</pre> +<p> + +Now assume the processed application throws an exception, and we have saved the +stack trace in <code>proguard.trace</code>, shown below. Of course, in real +life ProGuard rarely throws exceptions, so this is a purposely generated +exception. :) + +<pre> +Exception in thread "main" java.lang.Error: Random exception + at pro.bY.a(ProGuard:576) + at pro.bO.a(ProGuard:431) + at pro.bj.a(ProGuard:145) + at pro.bY.a(ProGuard:522) + at pro.bj.a(ProGuard:129) + at pro.bN.a(ProGuard:125) + at pro.bY.a(ProGuard:251) + at pro.bY.a(ProGuard:229) + at pro.l.a(ProGuard:55) + at pro.bo.b(ProGuard:405) + at pro.ci.a(ProGuard:51) + at pro.bo.a(ProGuard:356) + at pro.be.a(ProGuard:109) + at pro.bo.a(ProGuard:356) + at pro.be.a(ProGuard:186) + at pro.bg.a(ProGuard:369) + at pro.bY.a(ProGuard:286) + at pro.bh.a(ProGuard:55) + at pro.bg.b(ProGuard:408) + at pro.bY.a(ProGuard:190) + at pro.bg.a(ProGuard:369) + at pro.M.a(ProGuard:110) + at pro.bY.a(ProGuard:449) + at pro.M.a(ProGuard:99) + at pro.bo.a(ProGuard:372) + at pro.bY.a(ProGuard:649) + at pro.bY.a(ProGuard:112) + at pro.P.a(ProGuard:66) + at pro.p.a(ProGuard:83) + at pro.bU.a(ProGuard:69) + at pro.bo.a(ProGuard:356) + at pro.J.a(ProGuard:149) + at pro.I.a(ProGuard:49) + at pro.J.a(ProGuard:105) + at pro.cf.c(ProGuard:370) + at pro.cf.a(ProGuard:317) + at pro.bc.a(ProGuard:55) + at proguard.ProGuard.a(ProGuard:363) + at proguard.ProGuard.c(ProGuard:187) + at proguard.ProGuard.b(ProGuard:385) + at proguard.ProGuard.main(ProGuard:429) +</pre> +<p> + +We can then use the following command to recover the stack trace: +<pre> +<b>java -jar retrace.jar proguard.map proguard.trace</b> +</pre> +<p> + +The output will look as follows: +<pre> +Exception in thread "main" java.lang.Error: Random exception + at proguard.shrink.UsageMarker.visitInstruction(ProGuard:576) + at proguard.classfile.instruction.GenericInstruction.accept(ProGuard:431) + at proguard.classfile.CodeAttrInfo.instructionsAccept(ProGuard:145) + at proguard.shrink.UsageMarker.visitCodeAttrInfo(ProGuard:522) + at proguard.classfile.CodeAttrInfo.accept(ProGuard:129) + at proguard.classfile.ProgramMemberInfo.attributesAccept(ProGuard:125) + at proguard.shrink.UsageMarker.visitMemberInfo(ProGuard:251) + at proguard.shrink.UsageMarker.visitProgramMethodInfo(ProGuard:229) + at proguard.classfile.ProgramMethodInfo.accept(ProGuard:55) + at proguard.classfile.ProgramClassFile.methodAccept(ProGuard:405) + at proguard.classfile.visitor.NamedMethodVisitor.visitProgramClassFile(ProGuard:51) + at proguard.classfile.ProgramClassFile.accept(ProGuard:356) + at proguard.classfile.visitor.ClassFileUpDownTraveler.visitProgramClassFile(ProGuard:109) + at proguard.classfile.ProgramClassFile.accept(ProGuard:356) + at proguard.classfile.visitor.ClassFileUpDownTraveler.visitLibraryClassFile(ProGuard:186) + at proguard.classfile.LibraryClassFile.accept(ProGuard:369) + at proguard.shrink.UsageMarker.visitLibraryMethodInfo(ProGuard:286) + at proguard.classfile.LibraryMethodInfo.accept(ProGuard:55) + at proguard.classfile.LibraryClassFile.methodsAccept(ProGuard:408) + at proguard.shrink.UsageMarker.visitLibraryClassFile(ProGuard:190) + at proguard.classfile.LibraryClassFile.accept(ProGuard:369) + at proguard.classfile.ClassCpInfo.referencedClassAccept(ProGuard:110) + at proguard.shrink.UsageMarker.visitClassCpInfo(ProGuard:449) + at proguard.classfile.ClassCpInfo.accept(ProGuard:99) + at proguard.classfile.ProgramClassFile.constantPoolEntryAccept(ProGuard:372) + at proguard.shrink.UsageMarker.markCpEntry(ProGuard:649) + at proguard.shrink.UsageMarker.visitProgramClassFile(ProGuard:112) + at proguard.classfile.visitor.VariableClassFileVisitor.visitProgramClassFile(ProGuard:66) + at proguard.classfile.visitor.MultiClassFileVisitor.visitProgramClassFile(ProGuard:83) + at proguard.classfile.visitor.FilteredClassFileVisitor.visitProgramClassFile(ProGuard:69) + at proguard.classfile.ProgramClassFile.accept(ProGuard:356) + at proguard.classfile.ClassPool.classFileAccept(ProGuard:149) + at proguard.classfile.visitor.NamedClassFileVisitor.visitClassPool(ProGuard:49) + at proguard.classfile.ClassPool.accept(ProGuard:105) + at proguard.KeepCommand.executeShrinkingPhase(ProGuard:370) + at proguard.KeepCommand.execute(ProGuard:317) + at proguard.CompoundCommand.execute(ProGuard:55) + at proguard.ProGuard.executeCommands(ProGuard:363) + at proguard.ProGuard.shrink(ProGuard:187) + at proguard.ProGuard.execute(ProGuard:385) + at proguard.ProGuard.main(ProGuard:429) +</pre> + +<a name="withverbose"> </a> +<h3>Restoring a stack trace with line numbers (verbose)</h3> + +In the previous example, we could also use the verbose flag: +<pre> +<b>java -jar retrace.jar -verbose proguard.map proguard.trace</b> +</pre> +<p> + +The output will then look as follows: +<pre> +Exception in thread "main" java.lang.Error: Random exception + at proguard.shrink.UsageMarker.void visitInstruction(proguard.classfile.ClassFile,proguard.classfile.instruction.Instruction)(ProGuard:576) + at proguard.classfile.instruction.GenericInstruction.void accept(proguard.classfile.ClassFile,proguard.classfile.instruction.InstructionVisitor)(ProGuard:431) + at proguard.classfile.CodeAttrInfo.void instructionsAccept(proguard.classfile.ClassFile,proguard.classfile.instruction.InstructionVisitor)(ProGuard:145) + at proguard.shrink.UsageMarker.void visitCodeAttrInfo(proguard.classfile.ClassFile,proguard.classfile.CodeAttrInfo)(ProGuard:522) + at proguard.classfile.CodeAttrInfo.void accept(proguard.classfile.ClassFile,proguard.classfile.visitor.AttrInfoVisitor)(ProGuard:129) + at proguard.classfile.ProgramMemberInfo.void attributesAccept(proguard.classfile.ProgramClassFile,proguard.classfile.visitor.AttrInfoVisitor)(ProGuard:125) + at proguard.shrink.UsageMarker.void visitMemberInfo(proguard.classfile.ProgramClassFile,proguard.classfile.ProgramMemberInfo)(ProGuard:251) + at proguard.shrink.UsageMarker.void visitProgramMethodInfo(proguard.classfile.ProgramClassFile,proguard.classfile.ProgramMethodInfo)(ProGuard:229) + at proguard.classfile.ProgramMethodInfo.void accept(proguard.classfile.ProgramClassFile,proguard.classfile.visitor.MemberInfoVisitor)(ProGuard:55) + at proguard.classfile.ProgramClassFile.void methodAccept(proguard.classfile.visitor.MemberInfoVisitor,java.lang.String,java.lang.String)(ProGuard:405) + at proguard.classfile.visitor.NamedMethodVisitor.void visitProgramClassFile(proguard.classfile.ProgramClassFile)(ProGuard:51) + at proguard.classfile.ProgramClassFile.void accept(proguard.classfile.visitor.ClassFileVisitor)(ProGuard:356) + at proguard.classfile.visitor.ClassFileUpDownTraveler.void visitProgramClassFile(proguard.classfile.ProgramClassFile)(ProGuard:109) + at proguard.classfile.ProgramClassFile.void accept(proguard.classfile.visitor.ClassFileVisitor)(ProGuard:356) + at proguard.classfile.visitor.ClassFileUpDownTraveler.void visitLibraryClassFile(proguard.classfile.LibraryClassFile)(ProGuard:186) + at proguard.classfile.LibraryClassFile.void accept(proguard.classfile.visitor.ClassFileVisitor)(ProGuard:369) + at proguard.shrink.UsageMarker.void visitLibraryMethodInfo(proguard.classfile.LibraryClassFile,proguard.classfile.LibraryMethodInfo)(ProGuard:286) + at proguard.classfile.LibraryMethodInfo.void accept(proguard.classfile.LibraryClassFile,proguard.classfile.visitor.MemberInfoVisitor)(ProGuard:55) + at proguard.classfile.LibraryClassFile.void methodsAccept(proguard.classfile.visitor.MemberInfoVisitor)(ProGuard:408) + at proguard.shrink.UsageMarker.void visitLibraryClassFile(proguard.classfile.LibraryClassFile)(ProGuard:190) + at proguard.classfile.LibraryClassFile.void accept(proguard.classfile.visitor.ClassFileVisitor)(ProGuard:369) + at proguard.classfile.ClassCpInfo.void referencedClassAccept(proguard.classfile.visitor.ClassFileVisitor)(ProGuard:110) + at proguard.shrink.UsageMarker.void visitClassCpInfo(proguard.classfile.ClassFile,proguard.classfile.ClassCpInfo)(ProGuard:449) + at proguard.classfile.ClassCpInfo.void accept(proguard.classfile.ClassFile,proguard.classfile.visitor.CpInfoVisitor)(ProGuard:99) + at proguard.classfile.ProgramClassFile.void constantPoolEntryAccept(proguard.classfile.visitor.CpInfoVisitor,int)(ProGuard:372) + at proguard.shrink.UsageMarker.void markCpEntry(proguard.classfile.ClassFile,int)(ProGuard:649) + at proguard.shrink.UsageMarker.void visitProgramClassFile(proguard.classfile.ProgramClassFile)(ProGuard:112) + at proguard.classfile.visitor.VariableClassFileVisitor.void visitProgramClassFile(proguard.classfile.ProgramClassFile)(ProGuard:66) + at proguard.classfile.visitor.MultiClassFileVisitor.void visitProgramClassFile(proguard.classfile.ProgramClassFile)(ProGuard:83) + at proguard.classfile.visitor.FilteredClassFileVisitor.void visitProgramClassFile(proguard.classfile.ProgramClassFile)(ProGuard:69) + at proguard.classfile.ProgramClassFile.void accept(proguard.classfile.visitor.ClassFileVisitor)(ProGuard:356) + at proguard.classfile.ClassPool.void classFileAccept(proguard.classfile.visitor.ClassFileVisitor,java.lang.String)(ProGuard:149) + at proguard.classfile.visitor.NamedClassFileVisitor.void visitClassPool(proguard.classfile.ClassPool)(ProGuard:49) + at proguard.classfile.ClassPool.void accept(proguard.classfile.visitor.ClassPoolVisitor)(ProGuard:105) + at proguard.KeepCommand.void executeShrinkingPhase(proguard.classfile.ClassPool,proguard.classfile.ClassPool)(ProGuard:370) + at proguard.KeepCommand.void execute(int,proguard.classfile.ClassPool,proguard.classfile.ClassPool)(ProGuard:317) + at proguard.CompoundCommand.void execute(int,proguard.classfile.ClassPool,proguard.classfile.ClassPool)(ProGuard:55) + at proguard.ProGuard.void executeCommands(int)(ProGuard:363) + at proguard.ProGuard.void shrink()(ProGuard:187) + at proguard.ProGuard.void execute(java.lang.String[])(ProGuard:385) + at proguard.ProGuard.void main(java.lang.String[])(ProGuard:429) +</pre> + + +<a name="without"> </a> +<h3>Restoring a stack trace without line numbers</h3> + +Assume for instance ProGuard itself has been obfuscated using the following +extra options, this time without preserving the line number tables: +<pre> +-printmapping proguard.map +</pre> +<p> + +A stack trace <code>proguard.trace</code> will then lack line number +information: +<pre> +Exception in thread "main" java.lang.Error: Random exception + at pro.bY.a(Unknown Source) + at pro.bO.a(Unknown Source) + at pro.bj.a(Unknown Source) + at pro.bY.a(Unknown Source) + at pro.bj.a(Unknown Source) + at pro.bN.a(Unknown Source) + at pro.bY.a(Unknown Source) + at pro.bY.a(Unknown Source) + at pro.l.a(Unknown Source) + at pro.bo.b(Unknown Source) + at pro.ci.a(Unknown Source) + at pro.bo.a(Unknown Source) + at pro.be.a(Unknown Source) + at pro.bo.a(Unknown Source) + at pro.be.a(Unknown Source) + at pro.bg.a(Unknown Source) + at pro.bY.a(Unknown Source) + at pro.bh.a(Unknown Source) + at pro.bg.b(Unknown Source) + at pro.bY.a(Unknown Source) + at pro.bg.a(Unknown Source) + at pro.M.a(Unknown Source) + at pro.bY.a(Unknown Source) + at pro.M.a(Unknown Source) + at pro.bo.a(Unknown Source) + at pro.bY.a(Unknown Source) + at pro.bY.a(Unknown Source) + at pro.P.a(Unknown Source) + at pro.p.a(Unknown Source) + at pro.bU.a(Unknown Source) + at pro.bo.a(Unknown Source) + at pro.J.a(Unknown Source) + at pro.I.a(Unknown Source) + at pro.J.a(Unknown Source) + at pro.cf.c(Unknown Source) + at pro.cf.a(Unknown Source) + at pro.bc.a(Unknown Source) + at proguard.ProGuard.a(Unknown Source) + at proguard.ProGuard.c(Unknown Source) + at proguard.ProGuard.b(Unknown Source) + at proguard.ProGuard.main(Unknown Source) +</pre> +<p> + +We can still use the same command to recover the stack trace: +<pre> +<b>java -jar retrace.jar proguard.map proguard.trace</b> +</pre> +<p> + +The output will now give a list of alternative original method names for each +ambiguous obfuscated method name: +<pre> +Exception in thread "main" java.lang.Error: Random exception + at proguard.shrink.UsageMarker.visitProgramClassFile(Unknown Source) + visitLibraryClassFile + visitProgramFieldInfo + visitProgramMethodInfo + visitMemberInfo + visitLibraryFieldInfo + visitLibraryMethodInfo + visitIntegerCpInfo + visitLongCpInfo + visitFloatCpInfo + visitDoubleCpInfo + visitStringCpInfo + visitUtf8CpInfo + visitFieldrefCpInfo + visitInterfaceMethodrefCpInfo + visitMethodrefCpInfo + visitClassCpInfo + visitNameAndTypeCpInfo + visitUnknownAttrInfo + visitInnerClassesAttrInfo + visitConstantValueAttrInfo + visitExceptionsAttrInfo + visitCodeAttrInfo + visitLineNumberTableAttrInfo + visitLocalVariableTableAttrInfo + visitSourceFileAttrInfo + visitDeprecatedAttrInfo + visitSyntheticAttrInfo + visitInstruction + visitCpInstruction + visitExceptionInfo + visitInnerClassesInfo + visitLocalVariableInfo + markCpEntry + markAsUnused + isUsed + at proguard.classfile.instruction.GenericInstruction.create(Unknown Source) + isWide + getLength + accept + at proguard.classfile.CodeAttrInfo.getAttribute(Unknown Source) + getAttrInfoLength + readInfo + accept + instructionsAccept + exceptionsAccept + [...] + at proguard.KeepCommand.executeShrinkingPhase(Unknown Source) + access$100 + at proguard.KeepCommand.keepField(Unknown Source) + ensureMultiClassFileVisitorForMembers + execute + executeObfuscationPhase + access$002 + access$000 + access$102 + access$108 + at proguard.CompoundCommand.addCommand(Unknown Source) + execute + at proguard.ProGuard.readCommands(Unknown Source) + obfuscate + executeCommands + at proguard.ProGuard.shrink(Unknown Source) + at proguard.ProGuard.check(Unknown Source) + execute + at proguard.ProGuard.main(Unknown Source) +</pre> +<p> + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</html> + diff --git a/docs/manual/retrace/index.html b/docs/manual/retrace/index.html new file mode 100644 index 0000000..ebb23ac --- /dev/null +++ b/docs/manual/retrace/index.html @@ -0,0 +1,25 @@ +<!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>ReTrace Manual</title> +</head> +<body> + +<h2>ReTrace</h2> + +<ol> +<li><a href="introduction.html">Introduction</a> +<li><a href="usage.html">Usage</a> +<li><a href="examples.html">Examples</a> +</ol> + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</html> diff --git a/docs/manual/retrace/introduction.html b/docs/manual/retrace/introduction.html new file mode 100644 index 0000000..19f9471 --- /dev/null +++ b/docs/manual/retrace/introduction.html @@ -0,0 +1,68 @@ +<!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>ReTrace Introduction</title> +</head> +<body> + +<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. +<p> + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</html> + diff --git a/docs/manual/retrace/usage.html b/docs/manual/retrace/usage.html new file mode 100644 index 0000000..88587ff --- /dev/null +++ b/docs/manual/retrace/usage.html @@ -0,0 +1,117 @@ +<!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>ReTrace Usage</title> +</head> +<body> + +<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> +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> + (?:\s*%c:.*)|(?:\s*at\s+%c.%m\s*\(.*?(?::%l)?\)\s*) + </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>%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> + </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. + <p> + +<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. + +</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> + +Unobfuscated elements and obfuscated elements for which no mapping is available +will be left unchanged. +<p> + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</html> + diff --git a/docs/manual/sections.html b/docs/manual/sections.html new file mode 100644 index 0000000..62df9c3 --- /dev/null +++ b/docs/manual/sections.html @@ -0,0 +1,64 @@ +<!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-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="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>With support of</small> +<p> + +<a href="http://sourceforge.net/projects/proguard/" target="other"> + +<script type="text/javascript" language="JavaScript"> +<!-- +document.write("<img src=\""); +document.write(document.location.hostname == "proguard.sourceforge.net" ? + "http://sourceforge.net/sflogo.php?group_id=54750&type=1" : + "../sflogo.png"); +document.write("\" width=\"88\" height=\"31\" alt=\"SourceForge\">"); +//--> +</script> +<noscript> +<img src="../sflogo.png" width="88" height="31" alt="SourceForge"> +</noscript> + +</a> + +<p> +<a href="http://www.luciad.com/" target="other"> +<img src="../luciadlogo.png" width="88" height="24" alt="Luciad"></a> + +<p> +<a href="http://www.javadocking.com/" target="other"> +<img src="../sanawarelogo.png" width="88" height="24" alt="Luciad"></a> +</center> + +</body> +</html> diff --git a/docs/manual/style.css b/docs/manual/style.css new file mode 100644 index 0000000..28fc112 --- /dev/null +++ b/docs/manual/style.css @@ -0,0 +1,92 @@ +@charset "iso-8859-1"; + +/* Global settings. */ + +body { + background: #FFFFFF; +} + +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; +} + +a +{ + text-decoration: none; +} + +/* 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: solid #C0C0C0 1px; + background: #E0E0E0; + padding: 10px 0px; +} + +td.lightblock { + width: 100px; + text-align: center; + border: solid #8888FF 1px; + 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: outset #FFFFFF 1px; + font-weight: bold; +} diff --git a/docs/manual/troubleshooting.html b/docs/manual/troubleshooting.html new file mode 100644 index 0000000..d3ed14e --- /dev/null +++ b/docs/manual/troubleshooting.html @@ -0,0 +1,592 @@ +<!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 Troubleshooting</title> +</head> +<body> + +<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="#descriptorclass">Note: the configuration keeps the entry point '...', but not the descriptor class '...'</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="#unresolvedclassmember">Warning: can't find referenced field/method</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="#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="#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="#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="#nosuchmethodexception">NoSuchMethodException</a></li> +<li><a href="#missingresourceexception">MissingResourceException or NullPointerException</a></li> +<li><a href="#invalidjarfile">Invalid or corrupt jarfile</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="#compilererror">CompilerError: duplicate addition</a></li> +<li><a href="#classformaterror">ClassFormatError: repetitive field name/signature</a></li> +<li><a href="#nosuchmethoderror">NoSuchMethodError or AbstractMethodError</a></li> +<li><a href="#verifyerror">VerifyError</a></li> +</ul> + + +<a name="processing"> </a> +<h2>Problems while processing</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 check if you want to add the jar that + contains this class.</dd> + +<dt><a name="dynamicalclasscast"><b>Note: ... calls '(...)Class.forName(variable).newInstance()'</b></a></dt> + +<dd>ProGuard lists all class casts of dynamically created class instances, + 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>ProGuard lists a number of constructs 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="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 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.</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.</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>If there are unresolved references to classes or interfaces, you most + likely forgot to specify an essential library. For proper processing, all + libraries that are referenced by your code must be specified, including + the Java run-time library. For specifying libraries, use + the <a href="usage.html#libraryjars"><code>-libraryjars</code></a> option. + <p> + If the class that is reported as missing is a non-public library class, + you should specify the <a + href="usage.html#dontskipnonpubliclibraryclasses"><code>-dontskipnonpubliclibraryclasses</code></a> + option. Common examples are the classes + <code>javax.swing.TransferHandler$HasGetTransferHandler</code> and + <code>java.util.zip.ZipConstants</code>, which are used as interfaces in + some public classes, even though they are only package visible. This + option is not set by default for reasons of efficiency. Setting it increases + the processing time a bit, but it won't hurt the output in any way. + <p> + If you're missing a library and you're absolutely sure it isn't used + anyway, 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.</dd> + +<dt><a name="unresolvedclassmember"><b>Warning: can't find referenced field/method</b></a></dt> + +<dd>If there are unresolved references to class members in input classes, your + 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 class files, recompiling them, + zipping them up, and running ProGuard again. + <p> + If the class member that is reported as missing is actually implemented in + a non-public library class, you should specify the + <a href="usage.html#dontskipnonpubliclibraryclasses"><code>-dontskipnonpubliclibraryclasses</code></a> option. A common example is + the method <code>setLength(int)</code> in the public class + <code>java.lang.StringBuilder</code>. This method is actually defined in + the package visible superclass + <code>java.lang.AbstractStringBuilder</code>, which ProGuard ignores by + default. + <p> + If your program classes reside in the same packages as library classes, + and refer to their package visible class members, then you should 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 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 class files, recompiling them, zipping them up, and running + ProGuard again.</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 and library code, and try again.</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="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> + +</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>-Xms</code> and <code>-Xmx</code> options). 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. Remember that only classes or interfaces that are + extended or implemented by classes in your input jars are required.</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/bugdatabase/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> + +<a name="afterprocessing"> </a> +<h2>Unexpected observations after processing</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.</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> + +<a name="preverifying"> </a> +<h2>Problems while preverifying for Java Micro Edition</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> + +<a name="runtime"> </a> +<h2>Problems at run-time</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="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 isn't detecting this (yet), you have to keep the missing + method in using the appropriate <a + href="usage.html#keep"><code>-keep</code></a> option, e.g. "<code>-keep + class mypackage.MyClass { void myMethod(); }</code>".</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>.</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="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="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="classformaterror"><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="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-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</html> diff --git a/docs/manual/usage.html b/docs/manual/usage.html new file mode 100644 index 0000000..8be8d60 --- /dev/null +++ b/docs/manual/usage.html @@ -0,0 +1,1231 @@ +<!doctype html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<html> +<head> +<meta http-equiv="content-type" content="text/html; charset=iso-8859-1"> +<meta http-equiv="content-style-type" content="text/css"> +<link rel="stylesheet" type="text/css" href="style.css"> +<title>ProGuard Usage</title> +</head> +<body> + +<h2>Usage</h2> + +To run ProGuard, just type: +<p class="code"> +<code><b>java -jar proguard.jar </b></code><i>options</i> ... +</p> +You can find the ProGuard jar in the <code>lib</code> directory of the +ProGuard distribution. Options can also be put in one or more configuration +files. Typically, you'll put most options in a configuration file (say, +<code>myconfig.pro</code>), and just call: +<p class="code"> +<code><b>java -jar proguard.jar @myconfig.pro</b></code> +</p> +You can 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> +In a configuration file, a <code><b>#</b></code> sign and all remaining +characters on that line are ignored, allowing you to add comments. +<p> +Extra whitespace between words and delimiters is ignored. To specify file +names with spaces or special characters, words can be quoted with single or +double quotes. Note that the quotes may need to be escaped when used on the +command line, to avoid them being gobbled by the shell. +<p> +Options can be grouped arbitrarily in arguments on the command line and in +lines in configuration files. This means that you can quote any arbitrary +section of command line options, to avoid shell expansion of special +characters, for instance. +<p> +The order of the options is generally irrelevant. They can be abbreviated to +their first unique characters. +<p> + +The sections below provide more details: +<ul> +<li><a href="#iooptions">Input/Output Options</a> +<li><a href="#keepoptions">Keep Options</a> +<li><a href="#shrinkingoptions">Shrinking Options</a> +<li><a href="#optimizationoptions">Optimization Options</a> +<li><a href="#obfuscationoptions">Obfuscation Options</a> +<li><a href="#preverificationoptions">Preverification Options</a> +<li><a href="#generaloptions">General Options</a> +<li><a href="#classpath">Class Paths</a> +<li><a href="#filename">File Names</a> +<li><a href="#filefilters">File Filters</a> +<li><a href="#filters">Filters</a> +<li><a href="#keepoverview">Overview of <code>Keep</code> Options</a> +<li><a href="#keepoptionmodifiers">Keep Option Modifiers</a> +<li><a href="#classspecification">Class Specifications</a> +</ul> + +<a name="iooptions"> </a> +<h2>Input/Output Options</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 wars, ears, zips, or directories) of the + application to be processed. The class files in these jars will be + processed and written to the output jars. 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 wars, ears, zips, or + directories). The processed input of the preceding <code>-injars</code> + options will be written to the named jars. This allows you to collect the + contents of groups of input jars into corresponding groups of output jars. + In addition, the output entries can be filtered, as explained in + the <a href="#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 wars, ears, zips, or directories) of the + application to be processed. The files in these jars will not be included + in the output jars. The specified library jars should at least contain the + class files that are <i>extended</i> by application class files. Library + class files that are only <i>called</i> needn't be present, although their + presence can improve the results of the optimization step. The entries in + the class path can be filtered, as explained in the <a + href="#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>, just by specifying the + appropriate run-time jar.</dd> + +<dt><a name="dontskipnonpubliclibraryclasses"><code><b>-dontskipnonpubliclibraryclasses</b></code></a></dt> + +<dd>Specifies not to ignore non-public library classes. By default, non-public + library classes are skipped while parsing library jars. The classes are + typically not relevant during processing, since they don't affect the + actual program code in the input jars. Ignoring them reduces memory usage + and processing time. Occasionally, a badly designed library may contain a + non-public library class that is extended/implemented by a public library + class. If the latter library class in turn is extended/implemented by a + program class, ProGuard will complain that it can't find the non-public + library class, which it had ignored during parsing. This option will + overcome that problem, at the cost of greater memory usage and longer + processing time.</dd> + +<dt><a name="dontskipnonpubliclibraryclassmembers"><code><b>-dontskipnonpubliclibraryclassmembers</b></code></a></dt> + +<dd>Specifies not to ignore package visible library class members (fields and + methods). By default, these class members are skipped while parsing + library classes, as program classes will generally not refer to them. + Sometimes however, program classes reside in the same packages as library + classes, and they do refer to their package visible class members. In + those cases, it can be useful to actually read the class members, in order + to make sure the processed code remains consistent.</dd> + +<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 wars, ears, or + directories). By default, directory entries are removed. This reduces the + jar size, but it may be undesirable if the program code tries to find them + with constructs like "<code>MyClass.class.getResource("")</code>". If the + option is specified without a filter, all directories are kept. With a + filter, only matching directories are kept.</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>), or <code>1.6</code> (or just <code>6</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.</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> + +<a name="keepoptions"> </a> +<h2>Keep Options</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>, 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> + +<a name="shrinkingoptions"> </a> +<h2>Shrinking Options</h2> + +<dl> +<dt><a name="dontshrink"><code><b>-dontshrink</b></code></a></dt> + +<dd>Specifies not to shrink the input class files. By default, shrinking is + applied; all classes and class members are removed, except for the ones + listed by the various <code>-keep</code> options, and the ones on which + they depend, directly or indirectly. 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> + +<a name="optimizationoptions"> </a> +<h2>Optimization Options</h2> + +<dl> +<dt><a name="dontoptimize"><code><b>-dontoptimize</b></code></a></dt> + +<dd>Specifies not to optimize the input class files. By default, optimization + is enabled; all methods are optimized at a bytecode level.</dd> + +<dt><a name="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. Note that ProGuard will analyze your program code to find such + methods automatically. It will not analyze library code, for which this + option can thus be useful. For example, you could specify the method + <code>System.currentTimeMillis()</code>, so that any idle calls to it will + be removed. 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://java.sun.com/docs/books/jls/second_edition/html/j.title.doc.html" + >The Java Language Specification, Second Edition</a>, <a href= + "http://java.sun.com/docs/books/jls/second_edition/html/binaryComp.doc.html#47259" + >Section 13.4.6</a>), 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://java.sun.com/docs/books/jls/second_edition/html/j.title.doc.html" + >The Java Language Specification, Second Edition</a>, <a href= + "http://java.sun.com/docs/books/jls/second_edition/html/binaryComp.doc.html#45347" + >Section 13.5.3</a>), even if they are not allowed in the Java language + (cfr. <a href= + "http://java.sun.com/docs/books/jls/second_edition/html/j.title.doc.html" + >The Java Language Specification, Second Edition</a>, <a href= + "http://java.sun.com/docs/books/jls/second_edition/html/classes.doc.html#34031" + >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. + </ul></dd> + +</dl> +<p> + +<a name="obfuscationoptions"> </a> +<h2>Obfuscation Options</h2> + +<dl> +<dt><a name="dontobfuscate"><code><b>-dontobfuscate</b></code></a></dt> + +<dd>Specifies not to obfuscate the input class files. By default, obfuscation + is applied; classes and class members receive new short random names, + except for the ones listed by the various <code>-keep</code> options. + Internal attributes that are useful for debugging, such as source files + names, variable names, and line numbers are removed.</dd> + +<dt><a name="printmapping"><code><b>-printmapping</b></code></a> + [<a href="#filename"><i>filename</i></a>]</dt> + +<dd>Specifies to print the mapping from old names to new names for classes and + class members that have been renamed. The mapping is printed to the + standard output or to the given file. 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. In such cases, you should consider whether you also need + the option <a + href="#useuniqueclassmembernames"><code>-useuniqueclassmembernames</code></a>. + 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 (not just their arguments). 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://java.sun.com/docs/books/vmspec/2nd-edition/html/VMSpecTOC.doc.html" + >The Java Virtual Machine Specification, Second Edition</a>, first + paragraphs of <a href= + "http://java.sun.com/docs/books/vmspec/2nd-edition/html/ClassFile.doc.html#2877" + >Section 4.5</a> and <a href= + "http://java.sun.com/docs/books/vmspec/2nd-edition/html/ClassFile.doc.html#1513" + >Section 4.6</a>), even though this kind of overloading is not allowed in + the Java language (cfr. <a href= + "http://java.sun.com/docs/books/jls/second_edition/html/j.title.doc.html" + >The Java Language Specification, Second Edition</a>, <a href= + "http://java.sun.com/docs/books/jls/second_edition/html/classes.doc.html#40898" + >Section 8.3</a> and <a href= + "http://java.sun.com/docs/books/jls/second_edition/html/classes.doc.html#227768" + >Section 8.4.7</a>). Still, some tools have problems with it. Notably: + <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/bugdatabase/view_bug.do?bug_id=4216736">Bug + #4216736</a>). You probably shouldn't use this option for processing + libraries. + <li>Sun's JRE 1.4 and later fail to serialize objects with overloaded + primitive fields. + <li>Sun's JRE 1.5 <code>pack200</code> tool reportedly has problems with + overloaded class members. + </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. Note that the obfuscated jars + will become 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 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 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="#filters">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 attribute names. Attribute + names can contain <b>?</b>, <b>*</b>, and <b>**</b> wildcards, and they + can be preceded by the <b>!</b> negator. Typical optional attributes are + <code>Exceptions</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>, <code>RuntimeVisibleAnnotations</code>, + <code>RuntimeInvisibleAnnotations</code>, + <code>RuntimeVisibleParameterAnnotations</code>, + <code>RuntimeInvisibleParameterAnnotations</code>, and + <code>AnnotationDefault</code>. The <code>InnerClasses</code> attribute + name can be specified as well, referring to the source name part of this + attribute. For example, you 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>. As another example, + you should keep the <code>SourceFile</code> and + <code>LineNumberTable</code> attributes for <a + href="examples.html#stacktrace">producing useful obfuscated stack + traces</a>. Only applicable when obfuscating.</dd> + +<dt><a name="renamesourcefileattribute"><code><b>-renamesourcefileattribute</b></code></a> + [<i>string</i>]</dt> + +<dd>Specifies a constant string to be put in the <code>SourceFile</code> + attributes (and <code>SourceDir</code> attributes) of the class files. + Note that the attribute has to be present to start with, so it also has to + be preserved explicitly using the <code>-keepattributes</code> directive. + For example, you may want to have your processed libraries and + applications produce <a href="examples.html#stacktrace">useful obfuscated + stack traces</a>. Only applicable when obfuscating.</dd> + +<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.</dd> + +</dl> +<p> + +<a name="preverificationoptions"> </a> +<h2>Preverification Options</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 not required (yet), + but it improves the efficiency of the class loading in the Java Virtual + Machine.</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> + +<a name="generaloptions"> </a> +<h2>General Options</h2> + +<dl> +<dt><a name="verbose"><code><b>-verbose</b></code></a></dt> + +<dd>Specifies to write out some more information during processing. If the + program terminates with an exception, this option will print out the entire + stack trace, instead of just the exception message.</dd> + +<dt><a name="dontnote"><code><b>-dontnote</b></code></a> + [<i><a href="#filters">class_filter</a></i>]</dt> + +<dd>Specifies not to print notes about potential mistakes or omissions in the + configuration, like typos in class names, or like 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> + +<a name="classpath"> </a> +<h2>Class Paths</h2> + +ProGuard accepts a generalization of class paths to specify input files and +output files. A class path consists of entries, separated by the 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>A jar file, containing any of the above, +<li>A war file, containing any of the above, +<li>An ear file, containing any of the above, +<li>A zip file, containing any of the above, +<li>A directory (structure), containing any of the above. +</ul> +<p> +The paths of directly specified class files and resource files is ignored, so +class files should generally be part of a jar file, a war file, an ear file, a +zip file, or a directory. In addition, the paths of class files should not have +any additional directory prefixes inside the archives or directories. + +<p> +Each output entry can be: +<ul> +<li>A jar file, in which all processed class files and resource files will be + collected. +<li>A war file, in which any and all of the above will be collected, +<li>An ear file, in which any and all of the above will be collected, +<li>A zip file, in which any and all of the above will be collected, +<li>A directory, in which any and all of the above will be collected. +</ul> +<p> +When writing output entries, ProGuard will generally package the results in a +sensible way, reconstructing the input entries as much as required. Writing +everything to an output directory is the most straightforward option: the +output directory will contain a complete reconstruction of the input entries. +The packaging can be almost arbitrarily complex though: you could process an +entire application, packaged in a zip file along with its documentation, +writing it out as a zip file again. 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 5 types of <a +href="#filefilters">file filters</a> between parentheses, separated by +semi-colons: +<ul> +<li>A filter for all zip names that are encountered, +<li>A filter for all ear names that are encountered, +<li>A filter for all war names that are encountered, +<li>A filter for all jar names that are encountered, +<li>A filter for all class file names and resource file names that are + encountered. +</ul> +<p> +If fewer than 5 filters are specified, they are assumed to be the latter +filters. Any empty filters are ignored. More formally, a filtered class path +entry looks like this: +<pre> +<i>classpathentry</i><b>(</b>[[[[<i>zipfilter</i><b>;</b>]<i>earfilter</i><b>;</b>]<i>warfilter</i><b>;</b>]<i>jarfilter</i><b>;</b>]<i>filefilter</i><b>)</b> +</pre> +<p> +Square brackets "[]" mean that their contents are optional. +<p> +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> +Note that the different filters are applied to all corresponding file types, +irrespective of their nesting levels in the input; they are orthogonal. +<p> +For example, +"<code>input.war(lib/**.jar,support/**.jar;**.class,**.gif)</code>" only +considers jar files in the <code>lib</code> and <code>support</code> +directories in the <code>input</code> war, not any other jar files. It then +matches all class files and gif files that are encountered. +<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> + +<a name="filename"> </a> +<h2>File Names</h2> + +ProGuard accepts absolute paths and relative paths for the various file names +and directory names. A relative path is interpreted as follows: +<ul> +<li>relative to the base directory, if set, or otherwise +<li>relative to the configuration file in which it is specified, if any, or + otherwise +<li>relative to the working directory. +</ul> +<p> +The names can contain Java system properties delimited by '<b><</b>' and +'<b>></b>'. The system properties +are automatically replaced by their respective values. +<p> +For example, <code><java.home>/lib/rt.jar</code> will automatically be +expanded to something like <code>/usr/local/java/jdk/jre/lib/rt.jar</code>. +Similarly, <code><user.home></code> will be expanded to the user's home +directory, and <code><user.dir></code> will be expanded to the current +working directory. +<p> +Names with special characters like spaces and parentheses must be quoted with +single or double quotes. Note that each file name in a list of names has to be +quoted individually. Also note that the quotes themselves may need to be +escaped when used on the command line, to avoid them being gobbled by the +shell. +<p> +For example, on the command line, you could use an option like <code>'-injars +"my program.jar":"/your directory/your program.jar"'</code>. +<p> + +<a name="filefilters"> </a> +<h2>File Filters</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>. + +<a name="filters"> </a> +<h2>Filters</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> + +<a name="keepoverview"> </a> +<h2>Overview of <code>Keep</code> Options</h2> + +The various <code>-keep</code> options for shrinking and obfuscation may seem +a bit confusing at first, but there's actually a pattern behind them. The +following table summarizes how they are related: +<p> + +<table cellpadding="5"> + +<tr> +<th>Keep</th> +<td>From being removed or renamed</td> +<td>From being renamed</td> +</tr> + +<tr> +<td>Classes and class members</td> +<td bgcolor="#E0E0E0"><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> +<table> +<tr><td valign="top"> +<img src="attention.gif" width="64" height="64"alt="attention"> +</td><td> +Always remember: +<ul> +<li>Specifying a class without class members only preserves the class as an + entry point — any class members may then still be removed, optimized, + or obfuscated.</li> +<li>Specifying a class member only preserves the class member as an entry + point — any associated code may still be optimized and adapted.</li> +</ul> +</td></tr> +</table> +<p> + +<a name="keepoptionmodifiers"> </a> +<h2>Keep Option Modifiers</h2> + +<dl> +<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> + +<a name="classspecification"> </a> +<h2>Class Specifications</h2> + +A class specification is a template of classes and class members (fields and +methods). It is used in the various <code>-keep</code> options and in the +<code>-assumenosideeffects</code> option. The corresponding option is only +applied to classes and class members that match the template. +<p> +The template was designed to look very Java-like, with some extensions for +wildcards. To get a feel for the syntax, you should probably look at the <a +href="examples.html">examples</a>, but this is an attempt at a complete formal +definition: +<p> + +<pre> +[<b>@</b><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> + +<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. + <p> + +<li>Every <i>classname</i> must be fully qualified, e.g. + <code>java.lang.String</code>. Class names may be specified as regular + expressions containing the following wildcards: + +<table cellspacing="10"> + +<tr><td valign="top"><code><b>?</b></code></td> + +<td>matches any single character in a class name, but not the package + separator. For example, "<code>mypackage.Test?</code>" matches + "<code>mypackage.Test1</code>" and "<code>mypackage.Test2</code>", but not + "<code>mypackage.Test12</code>".</td></tr> + +<tr><td valign="top"><code><b>*</b></code></td> + +<td>matches any part of a class name not containing the package separator. For + example, "<code>mypackage.*Test*</code>" matches + "<code>mypackage.Test</code>" and + "<code>mypackage.YourTestApplication</code>", but not + "<code>mypackage.mysubpackage.MyTest</code>". Or, more generally, + "<code>mypackage.*</code>" matches all classes in + "<code>mypackage</code>", but not in its subpackages.</td></tr> + +<tr><td valign="top"><code><b>**</b></code></td> + +<td>matches any part of a class name, possibly containing any number of + package separators. For example, "<code>**.Test</code>" matches all + <code>Test</code> classes in all packages except the root package. Or, + "<code>mypackage.**</code>" matches all classes in + "<code>mypackage</code>" and in its subpackages.</td></tr> + +</table> + + For additional flexibility, class names can actually be comma-separated + lists of class names, with optional <code><b>!</b></code> negators, just + like file name filters. This notation doesn't look very Java-like, so it + should be used with moderation. + <p> + For convenience and for backward compatibility, the class name + <code><b>*</b></code> refers to any class, irrespective of its package. + <p> + +<li>The <code><b>extends</b></code> and <code><b>implements</b></code> + specifications are typically used to restrict classes with wildcards. They + are currently equivalent, specifying that only classes extending or + implementing the given class qualify. Note that the given class itself is + not included in this set. If required, it should be specified in a + separate option. + <p> + +<li>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>. + <p> + +<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>". + <p> + +<li>Constructors can also be specified using their short class names (without + package) or using their full class names. As in the Java language, the + constructor specification has an argument list, but no return type. + <p> + +<li>The class access modifiers and class member access modifiers are typically + used to restrict wildcarded classes and class members. They specify that + the corresponding access flags have to be set for the member to match. A + preceding <code><b>!</b></code> specifies that the corresponding access + flag should be unset. + <p> + Combining multiple flags is allowed (e.g. <code>public static</code>). It + means that both access flags have to be set (e.g. <code>public</code> + <i>and</i> <code>static</code>), except when they are conflicting, in + which case at least one of them has to be set (e.g. at least + <code>public</code> + <i>or</i> <code>protected</code>). + +</ul> +<p> + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</html> diff --git a/docs/manual/wtk.html b/docs/manual/wtk.html new file mode 100644 index 0000000..b8c70b5 --- /dev/null +++ b/docs/manual/wtk.html @@ -0,0 +1,58 @@ +<!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 JME Wireless Toolkit Integration</title> +</head> +<body> + +<h2>JME Wireless Toolkit Integration</h2> + +<b>ProGuard</b> can be seamlessly integrated in Sun'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-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</html> diff --git a/docs/quality.html b/docs/quality.html new file mode 100644 index 0000000..29889e3 --- /dev/null +++ b/docs/quality.html @@ -0,0 +1,44 @@ +<!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 Quality</title> +</head> +<body> + +<h2>Quality</h2> + +In order to get a feel for the quality of the <b>ProGuard</b> code, it is run +through a regular automatic build process. This process produces numerous +statistics on the source code, Java lint comments, Java documentation +comments, the Java documentation itself, html lint comments on the Java +documentation, spell checks, compilation results, an output jar, dead code +analysis, a shrunk and obfuscated jar (using ProGuard itself!), test runs with +memory and performance analyses, etc. Most analyses are produced using freely +available tools. The results are poured into a convenient set of web pages +using bash/sed/awk scripts. You're welcome to have a look at an uploaded +snapshot of one of these runs: +<p> +<center><a href="http://proguard.sourceforge.net/quality/" +target="other">Automated Code Analysis and Testing Pages</a> (at <a +href="http://sourceforge.net/projects/proguard/" +target="other">SourceForge</a>)</center> +<p> +The pages will appear in a new window, which you probably want to view at +full-screen size. +<p> + +In addition, <b>ProGuard</b> is tested against a constantly growing test suite +(more than 500 tests at this time of writing). These small programs contain a +wide range of common and uncommon constructs, in order to detect any regression +problems as soon as possible. + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</html> diff --git a/docs/results.html b/docs/results.html new file mode 100644 index 0000000..480cd4f --- /dev/null +++ b/docs/results.html @@ -0,0 +1,155 @@ +<!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 Results</title> +</head> +<body> + +<h2>Results</h2> + +<b>ProGuard</b> successfully processes any Java bytecode, ranging from small +midlets to entire run-time libraries. It primarily reduces the size of the +processed code, with some potential increase in efficiency as an added bonus. +The improvements obviously depend on the original code. The table below +presents some typical results: +<p> + +<table> + +<tr> +<th width="28%">Input Program</th> +<th width="12%">Original size</th> +<th width="12%">After shrinking</th> +<th width="12%">After optim.</th> +<th width="12%">After obfusc.</th> +<th width="12%">Total reduction</th> +<th width="12%">Time</th> +<th width="12%">Memory usage</th> +</tr> + +<tr> +<td><a target="other" href="http://java.sun.com/j2me/">Worm</a>, a sample midlet from Sun's JME</td> +<td align="center">10.3 K</td> +<td align="center">9.8 K</td> +<td align="center">9.6 K</td> +<td align="center">8.5 K</td> +<td align="center">18 %</td> +<td align="center">2 s</td> +<td align="center">19 M</td> +</tr> + +<tr> +<td><a target="other" href="http://www.javadocking.com/">Javadocking</a>, a docking library</td> +<td align="center">290 K</td> +<td align="center">281 K</td> +<td align="center">270 K</td> +<td align="center">201 K</td> +<td align="center">30 %</td> +<td align="center">12 s</td> +<td align="center">32 M</td> +</tr> + +<tr> +<td><b>ProGuard</b> itself</td> +<td align="center">648 K</td> +<td align="center">579 K</td> +<td align="center">557 K</td> +<td align="center">348 K</td> +<td align="center">46 %</td> +<td align="center">28 s</td> +<td align="center">66 M</td> +</tr> + +<tr> +<td><a target="other" href="http://www.clarkware.com/software/JDepend.html">JDepend</a>, a Java quality metrics tool</td> +<td align="center">57 K</td> +<td align="center">36 K</td> +<td align="center">33 K</td> +<td align="center">28 K</td> +<td align="center">51 %</td> +<td align="center">6 s</td> +<td align="center">24 M</td> +</tr> + +<tr> +<td><a target="other" href="http://java.sun.com/javase/6/">the run-time classes</a> from Sun's Java 6</td> +<td align="center">53 M</td> +<td align="center">23 M</td> +<td align="center">22 M</td> +<td align="center">18 M</td> +<td align="center">66 %</td> +<td align="center">16 min</td> +<td align="center">270 M</td> +</tr> + +<tr> +<td><a target="other" href="http://jakarta.apache.org/tomcat/index.html">Tomcat</a>, the Apache servlet container</td> +<td align="center">1.1 M</td> +<td align="center">466 K</td> +<td align="center">426 K</td> +<td align="center">295 K</td> +<td align="center">74 %</td> +<td align="center">17 s</td> +<td align="center">44 M</td> +</tr> + +<tr> +<td><a target="other" href="http://www.kclee.com/clemens/java/javancss/">JavaNCSS</a>, a Java source metrics tool</td> +<td align="center">632 K</td> +<td align="center">242 K</td> +<td align="center">212 K</td> +<td align="center">152 K</td> +<td align="center">75 %</td> +<td align="center">20 s</td> +<td align="center">36 M</td> +</tr> + +<tr> +<td><a target="other" href="http://ant.apache.org/">Ant</a>, the Apache build tool</td> +<td align="center">2.4 M</td> +<td align="center">401 K</td> +<td align="center">325 K</td> +<td align="center">242 K</td> +<td align="center">90 %</td> +<td align="center">23 s</td> +<td align="center">61 M</td> +</tr> + +</table> +<p> +Results were measured with ProGuard 4.0 on a 2.6 GHz Pentium 4 with 512 MB +of memory, using Sun JDK 1.5.0 in Fedora Core 3 Linux. +<p> +The program sizes include companion libraries. The shrinking step produces the +best results for programs that use only small parts of their libraries. The +obfuscation step can significantly shrink large programs even further, since +the identifiers of their many internal references can be replaced by short +identifiers. +<p> +The Java 6 run-time classes are the most complex example. The classes perform +a lot of introspection, interacting with the native code of the virtual +machine. The 1500+ lines of configuration were largely composed by automated +analysis, complemented by a great deal of trial and error. The configuration +is probably not complete, but the resulting library successfully serves as a +run-time environment for running applications like ProGuard and the ProGuard +GUI. +<p> +For small inputs, timings are governed by the reading and parsing of the jars. +For large inputs, the optimization step becomes more important. For instance, +processing the Java 6 run-time classes without optimization only takes 2 +minutes. +<p> +Memory usage (the amount of physical memory used by ProGuard while processing) +is governed by the basic java virtual machine and by the total size of the +library jars and program jars. +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> + +</body> +</html> diff --git a/docs/sanawarelogo.png b/docs/sanawarelogo.png Binary files differnew file mode 100644 index 0000000..bf7218b --- /dev/null +++ b/docs/sanawarelogo.png diff --git a/docs/screenshot_console.gif b/docs/screenshot_console.gif Binary files differnew file mode 100644 index 0000000..8aea61e --- /dev/null +++ b/docs/screenshot_console.gif diff --git a/docs/screenshot_console_small.gif b/docs/screenshot_console_small.gif Binary files differnew file mode 100644 index 0000000..3f55f5b --- /dev/null +++ b/docs/screenshot_console_small.gif diff --git a/docs/screenshot_gui1.gif b/docs/screenshot_gui1.gif Binary files differnew file mode 100644 index 0000000..233e180 --- /dev/null +++ b/docs/screenshot_gui1.gif diff --git a/docs/screenshot_gui2.gif b/docs/screenshot_gui2.gif Binary files differnew file mode 100644 index 0000000..aecdb35 --- /dev/null +++ b/docs/screenshot_gui2.gif diff --git a/docs/screenshot_gui3.gif b/docs/screenshot_gui3.gif Binary files differnew file mode 100644 index 0000000..17950ee --- /dev/null +++ b/docs/screenshot_gui3.gif diff --git a/docs/screenshot_gui4.gif b/docs/screenshot_gui4.gif Binary files differnew file mode 100644 index 0000000..31e60fa --- /dev/null +++ b/docs/screenshot_gui4.gif diff --git a/docs/screenshot_gui5.gif b/docs/screenshot_gui5.gif Binary files differnew file mode 100644 index 0000000..1313db2 --- /dev/null +++ b/docs/screenshot_gui5.gif diff --git a/docs/screenshot_gui6.gif b/docs/screenshot_gui6.gif Binary files differnew file mode 100644 index 0000000..c200b97 --- /dev/null +++ b/docs/screenshot_gui6.gif diff --git a/docs/screenshot_gui7.gif b/docs/screenshot_gui7.gif Binary files differnew file mode 100644 index 0000000..bc5d6ed --- /dev/null +++ b/docs/screenshot_gui7.gif diff --git a/docs/screenshot_gui8.gif b/docs/screenshot_gui8.gif Binary files differnew file mode 100644 index 0000000..95a1a30 --- /dev/null +++ b/docs/screenshot_gui8.gif diff --git a/docs/screenshots.html b/docs/screenshots.html new file mode 100644 index 0000000..8718839 --- /dev/null +++ b/docs/screenshots.html @@ -0,0 +1,56 @@ +<!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 Screenshots</title> +</head> +<body> + +<h2>Screenshots</h2> + +<table><tr><td> +<a href="screenshot_gui1.gif" target="other"> +<img src="screenshots_gui_small.gif" width="320" height="223" align="right" + alt="GUI screenshot" usemap="#guimap"></a> + +<map id="guimap" name="guimap"> +<area shape="rect" coords="2,7,46,16" alt="ProGuard" href="screenshot_gui1.gif" target="other"> +<area shape="rect" coords="2,17,46,27" alt="Input/Output" href="screenshot_gui2.gif" target="other"> +<area shape="rect" coords="2,28,46,37" alt="Shrinking" href="screenshot_gui3.gif" target="other"> +<area shape="rect" coords="2,38,46,48" alt="Optimization" href="screenshot_gui4.gif" target="other"> +<area shape="rect" coords="2,49,46,58" alt="Obfuscation" href="screenshot_gui5.gif" target="other"> +<area shape="rect" coords="2,59,46,69" alt="Information" href="screenshot_gui6.gif" target="other"> +<area shape="rect" coords="2,70,46,79" alt="Process" href="screenshot_gui7.gif" target="other"> +<area shape="rect" coords="2,80,46,90" alt="ReTrace" href="screenshot_gui8.gif" target="other"> +</map> + +The graphical user interface to <b>ProGuard</b> works like a wizard. It allows +you to browse through the presented tabs and fill them out. +<p> +You can click on the small tab buttons to see the full-size versions of the +tabs. + +</td></tr> +<tr><td> +<a href="screenshot_console.gif" target="other"> +<img src="screenshot_console_small.gif" width="320" height="268" align="left" + alt="Console screenshot"></a> + +Of course, real developers don't need all this point-and-click fluff. They +write a short configuration file using their favorite text editor and invoke +<b>ProGuard</b> from the command-line. +<p> +You can click on the image to see the full-size version. + +</td></tr></table> +<p> + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> +</body> +</html> diff --git a/docs/screenshots_gui_small.gif b/docs/screenshots_gui_small.gif Binary files differnew file mode 100644 index 0000000..bc32ccb --- /dev/null +++ b/docs/screenshots_gui_small.gif diff --git a/docs/sections.html b/docs/sections.html new file mode 100644 index 0000000..d955d33 --- /dev/null +++ b/docs/sections.html @@ -0,0 +1,62 @@ +<!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-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 target="main" href="main.html">Main</a></li> +<li><a target="main" href="results.html">Results</a></li> +<li><a target="main" href="FAQ.html">FAQ</a></li> +<li><a href="manual/sections.html">Manual</a></li> +<li><a target="main" href="quality.html">Quality</a></li> +<li><a target="main" href="screenshots.html">Screenshots</a></li> +<li><a target="main" href="testimonials.html">Testimonials</a></li> +<li><a target="main" href="license.html">License</a></li> +<li><a target="main" href="downloads.html">Downloads</a></li> +<li><a target="main" href="feedback.html">Feedback</a></li> +<li><a target="main" href="acknowledgements.html">Ack'ments</a></li> +<li><a target="main" href="alternatives.html">Alternatives</a></li> +</ul> + +<p> +<center> +<small>With support of</small> +<p> + +<a href="http://sourceforge.net/projects/proguard/" target="other"> + +<script type="text/javascript" language="JavaScript"> +<!-- +document.write("<img src=\""); +document.write(document.location.hostname == "proguard.sourceforge.net" ? + "http://sourceforge.net/sflogo.php?group_id=54750&type=1" : + "sflogo.png"); +document.write("\" width=\"88\" height=\"31\" alt=\"SourceForge\">"); +if (document.location.hostname == "proguard.sourceforge.net") { + document.write("<script type=\"text/javascript\" src=\"http://sourceforge.net/apps/piwik/proguard/piwik.js\"></scri"+"pt>"); + document.write("<script type=\"text/javascript\">piwik_log(\"\", 1, \"http://sourceforge.net/apps/piwik/proguard/piwik.php\");</scri"+"pt>"); +} +//--> +</script> +<noscript> +<img src="sflogo.png" width="88" height="31" alt="SourceForge"> +</noscript> + +</a> + +<p> +<a href="http://www.luciad.com/" target="other"> +<img src="luciadlogo.png" width="88" height="24" alt="Luciad"></a> +<p> +<a href="http://www.javadocking.com/" target="other"> +<img src="sanawarelogo.png" width="88" height="24" alt="Sanaware"></a> +</center> + +</body> +</html> diff --git a/docs/sflogo.png b/docs/sflogo.png Binary files differnew file mode 100644 index 0000000..142a6f9 --- /dev/null +++ b/docs/sflogo.png diff --git a/docs/steel.gif b/docs/steel.gif Binary files differnew file mode 100644 index 0000000..307b57a --- /dev/null +++ b/docs/steel.gif diff --git a/docs/style.css b/docs/style.css new file mode 100644 index 0000000..c9798db --- /dev/null +++ b/docs/style.css @@ -0,0 +1,210 @@ + +@charset "iso-8859-1"; + +/* Global settings. */ + +body +{ + background: #FFFFFF; +} + +h1 +{ + text-align: center; +} + +h2 +{ + text-align: center; +} + +h3 +{ + background: #EEEEFF; + padding: 10px; +} + +h3 div +{ + font-weight: normal; + font-size: 80%; + float: right; +} + +table +{ + width: 100%; +} + +th +{ + padding: 4px; +} + +tr.disappeared td +{ + background: #EEEEEE; +} + +td +{ + background: #EEEEFF; + padding: 8px; +} + +a +{ + text-decoration: none; +} + +img +{ + border: none; +} + +/* Settings for the introductory paragraph. */ + +p.intro +{ + background: #EEEEFF; + padding: 10px; + border: solid #000000 1px +} + +/* Settings for the title frame. */ + +body.title +{ + margin: 0px; + padding: 0px; + background: #C0C0C0; +} + +div.title +{ + height: 48px; + margin: 0px; + padding: 0px; + border-width: 1px; + border-style: solid; + border-color: #FFFFFF #808080 #808080 #FFFFFF; + background: url("steel.gif"); +} + +div.title h1 +{ + margin: 0px; + padding: 0px; + padding-top: 8px; + padding-left: 40%; + float: left; +} + +div.title div +{ + margin: 0px; + padding: 0px; + padding-top: 12px; + padding-right: 20px; + float: right; +} + +/* Settings for the section frames. */ + +body.navigation +{ + margin: 0px; + padding: 0px; +} + +ul.navigation +{ + margin: 0px; + padding: 0px; + list-style: none; + text-align: center; + background: url("steel.gif"); +} + +ul.navigation li +{ + margin: 0px; + padding: 0px; + border-width: 1px; + border-style: solid; + border-color: #FFFFFF #808080 #808080 #FFFFFF; + color: #000000; + font-weight: bold; +} + +ul.navigation li.title +{ + margin: 0px; + padding: 4px 10px; + background: #E0E0E0; +} + +ul.navigation li a +{ + margin: 0px; + padding: 6px 0px; + background: transparent; + color: #000000; + text-decoration: none; + display: block; +} + +ul.navigation li a:hover, +ul.navigation li a:focus +{ + background: #FFFFFF; +} + +/* Settings for the yellow note tables. */ + +table.note +{ + width: 408px; + border: none; + border-spacing: 0px; +} + +td.shadow8 +{ + width: 8px; + padding: 0px; + margin: 0px; + vertical-align: bottom; + background: transparent; +} + +td.shadow400 +{ + width: 400px; + padding: 0px; + margin: 0px; + text-align: right; + background: transparent; +} + +td.note +{ + width: 380px; + background: #FFFFC0; + padding: 0px; + margin: 0px; +} + +p.note +{ + padding: 0px; + margin: 0px 10px; + text-align: center; +} + +p.author +{ + padding: 0px; + margin: 0px 10px; + text-align: right; +} diff --git a/docs/testimonials.html b/docs/testimonials.html new file mode 100644 index 0000000..6971617 --- /dev/null +++ b/docs/testimonials.html @@ -0,0 +1,122 @@ +<!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 Testimonials</title> +</head> +<body> + +<h2>Testimonials</h2> + +And now for some shameless self-glorification and name-dropping... +<p> +<b>ProGuard</b> is probably the most popular java shrinker, optimizer, and +obfuscator world-wide. It is being used by developers at companies and +organizations like Sun, IBM, HP, Siemens, Nokia, Google, and NATO. It is the +default tool in many development environments like Sun's Wireless Toolkit, +Netbeans, EclipseME, and more. Although the quotes below probably don't +represent official views of any kind, encouragements like these do keep me +happy. +<p> + +<center><table class="note"> +<tr><td class="note"><p class="note"><cite> +ProGuard is <b>the</b> ultimate java obfuscator! +</cite></p> +<p class="author">P.S, IBM</p></td> +<td class="shadow8"><img src="drop2.gif" width="8" height="100"></td></tr><tr> +<td class="shadow400"><img src="drop1.gif" width="400" height="8"></td> +<td class="shadow8"><img src="drop3.gif" width="8" height="8"></td> +</tr></table></center> +<p> + +Also: +<center><table class="note"> +<tr><td class="note"><p class="note"><cite> +ProGuard is pure quality - powerful and trouble-free. +</cite></p> +<p class="author">M.B., Statestep</p></td> +<td class="shadow8"><img src="drop2.gif" width="8" height="100"></td></tr><tr> +<td class="shadow400"><img src="drop1.gif" width="400" height="8"></td> +<td class="shadow8"><img src="drop3.gif" width="8" height="8"></td> +</tr></table></center> +<p> + +And: +<center><table class="note"> +<tr><td class="note"><p class="note"><cite> +It is the simplest and most robust obfuscator we have ever used. +</cite></p> +<p class="author">I.I., Hewlett-Packard</p></td> +<td class="shadow8"><img src="drop2.gif" width="8" height="100"></td></tr><tr> +<td class="shadow400"><img src="drop1.gif" width="400" height="8"></td> +<td class="shadow8"><img src="drop3.gif" width="8" height="8"></td> +</tr></table></center> +<p> + +And indeed: +<center><table class="note"> +<tr><td class="note"><p class="note"><cite> +ProGuard rules. Much easier to use than the commercial alternatives. +</cite></p> +<p class="author">B.G., Quiotix Corp.</p></td> +<td class="shadow8"><img src="drop2.gif" width="8" height="100"></td></tr><tr> +<td class="shadow400"><img src="drop1.gif" width="400" height="8"></td> +<td class="shadow8"><img src="drop3.gif" width="8" height="8"></td> +</tr></table></center> +<p> + +Straight from <b>ProGuard</b>'s open discussion forum: +<p> +<center><table class="note"> +<tr><td class="note"><p class="note"><cite> +After searching for, trying to trial, and futzing with numerous other +obfuscators and shrinkers, ProGuard stands out as the simplest, most robust, +and accurate shrinker of them all. +</cite></p> +<p class="author">D.J., Joot</p></td> +<td class="shadow8"><img src="drop2.gif" width="8" height="100"></td></tr><tr> +<td class="shadow400"><img src="drop1.gif" width="400" height="8"></td> +<td class="shadow8"><img src="drop3.gif" width="8" height="8"></td> +</tr></table></center> +<p> + +From the article "Obfuscating MIDlet Suites with ProGuard" at <a +target="other" href="http://developers.sun.com/">developers.sun.com</a>: +<p> +<center><table class="note"> +<tr><td class="note"><p class="note"><cite> +Its friendly license, attractive price tag, compelling performance, and +powerful configuration options make it an excellent addition to your MIDlet +development toolbox. +</cite></p> +<p class="author">J.K., Sun</p></td> +<td class="shadow8"><img src="drop2.gif" width="8" height="100"></td></tr><tr> +<td class="shadow400"><img src="drop1.gif" width="400" height="8"></td> +<td class="shadow8"><img src="drop3.gif" width="8" height="8"></td> +</tr></table></center> +<p> + +And, of course, the price is stunning: +<p> +<center><table class="note"> +<tr><td class="note"><p class="note"><cite> +You could've been rich. +</cite></p> +<p class="author">My mother</p></td> +<td class="shadow8"><img src="drop2.gif" width="8" height="100"></td></tr><tr> +<td class="shadow400"><img src="drop1.gif" width="400" height="8"></td> +<td class="shadow8"><img src="drop3.gif" width="8" height="8"></td> +</tr></table></center> +<p> + +<hr> +<address> +Copyright © 2002-2009 +<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>. +</address> + +</body> +</html> diff --git a/docs/title.gif b/docs/title.gif Binary files differnew file mode 100644 index 0000000..5e6ca26 --- /dev/null +++ b/docs/title.gif diff --git a/docs/title.html b/docs/title.html new file mode 100644 index 0000000..33171b5 --- /dev/null +++ b/docs/title.html @@ -0,0 +1,17 @@ +<!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</title> +</head> +<body class="title"> + +<div class="title"> +<h1><img src="title.gif" width="154" height="29" alt="ProGuard"></h1> +<div>Version 4.4</div> +</div> + +</body> +</html> |
