jode/jode/README

JODE (Java Obfuscator/DEcompiler)

This is a decompiler and optimizer for java I have written in my spare
time.  It takes class files as input and produces something similar to
the original java file.  Of course this can't be perfect: There is no
way to produce the comments or the names of local variables (except
when the java files were compiled with `-g') and there are often more
ways to write the same thing.  But jode does its job quite well.

Please note that most software licenses forbid to decompile class
files.  Use this decompiler only, if you have legal rights to
decompile the class (e.g. on your own code).

The features of the decompilers are:

 * Systematic flow analysis, that can decompile every java code
   without the need of goto (which doesn't exists in java).
 * Type deduction, that can guess the type of local variables, even if 
   it is an interface type that doesn't occur in the bytecode.
 * Handling of inner and anonymous classes.
 * Different indentation styles available.
 * It can decompile itself (194 classes) without a single error.
 * It can decrypt strings on the fly, that were encrypted by an obfuscator.

Known bugs of the decompiler:

 - If not all dependent classes can be found, the verifier (which is 
   run before decompilation starts) may exit with a type error.  You
   can decompile it with --verify=off, but take the warning serious,
   that the types may be incorrect.  There's sometimes no way to guess
   the right type, if you don't have access the full class hierarchie.

   But if you don't have the dependent classes, you can't compile the
   code again, anyway, so why do you want to decompile it?

 - There may be situations, where jode doesn't understand complex
   expressions. In this case many ugly temporary variables are used,
   but the code should still be compileable.  This does especially
   happen when you compile with `-O' flag and javac has inlined some
   methods.

 - Sometimes this program may exit with an Exception or produce
   incorrect code.  If it produced incorrect code the code probably
   can't be compiled, so that the error can be easily spotted.  If you
   have one of these problems (they are very rare now), I would be
   very interested in a bug report (including the .class file, if
   possible).

 - Sometimes it generates some GOTO expression and labels.  This
   shouldn't happen any more with code produced by javac or jikes.
   But some flow obfuscator likes Zelix Klassmaster may provoke this.
   In that case you can run the Obfuscator first (to optimize away the
   flow obfuscation ;-).

The features of the obfuscator are:
 * Modular design, you can plug the obfuscation transformation you need
   together via the script file.
 * Strong analysis, that optimizes away fields, expressions that are
   known to be constant (and reverts the flow obfuscation of Zelix
   Klassmaster)
 * Can also be used as Optimizer, without any obfuscation at all,  it
   will preserve the local variable table and line number table.
 * Many different renaming options, you can also simply add your own.


PRELIMINARIES:

You need java jdk1.2 or above, and the gnu getopt package.

You should also have the jode-x.x.xx.jar file.  Read INSTALL how to
compile it yourself.

Jode also works with jdk1.1, you need the sun collection classes and
swing in that case and you have to compile the jar-file yourself.

Here are some URLs for the tools and packages you may need:

 CYGWIN (unix tools for win95/NT):
   http://sourceware.cygnus.com/cygwin/

 JDK 1.1:
   http://java.sun.com/products/jdk/1.1/index.htm

 Collection classes and Swing for JDK 1.1:
   http://java.sun.com/beans/infobus/#DOWNLOAD_COLLECTIONS
   http://java.sun.com/products/jfc/index.html#download-swing

 JDK 1.2:
   http://java.sun.com/products/jdk/1.2/index.html

 Getopt:
   http://www.urbanophile.com/arenn/hacking/download.html#getopt

USAGE:

First set the classpath.  It should contain the jar file
jode-x.x.xx.jar, the gnu getopt package and the sun collection package
for 1.1.  For the swingui program you also need swing in you classpath.

You can then decompile a class file with:
  java jode.Decompiler --classpath jarfile1.jar,jarfile2.jar org.package.Class

For a graphical user interface based on swing try:
  java jode.swingui.Main --classpath jarfile1.jar

The obfuscator/deobfuscator can be run with:
  java jode.obfuscator.Main --script obfuscation.script

See XXXX for more information about the script syntax.

HISTORY:

Someday I found guavad, a disassembler for java byte code (it does
similar things like `javap -c').  I used it on a class file, and found
that it was possible to reconstruct the original java code.  First I
did it by hand on some small routines, but I soon realized that it was
a rather stupid task, and that I could write a perl script, that does
the same.  At the end of the next day I had the first working
decompiler.

Now while it was working, it was not easy to use.  You had to
decompile the code first with a disassembler, cut the method, you
wanted to decompile and then run the perl script on it.  So I decided
to get some information of the class files and do this all
automatically.  I decided to write it in java now, because it suited
best.