IDEA-285172 - [decompiler] - StrongConnectivityHelper refactoring
[idea/community.git] / plugins / java-decompiler / engine / README.md
1 ### About Fernflower
2
3 Fernflower is the first actually working analytical decompiler for Java and 
4 probably for a high-level programming language in general. Naturally it is still 
5 under development, please send your bug reports and improvement suggestions to the
6 [issue tracker](https://youtrack.jetbrains.com/newIssue?project=IDEA&clearDraft=true&c=Subsystem+Decompiler).
7
8 ### Licence
9
10 Fernflower is licenced under the [Apache Licence Version 2.0](http://www.apache.org/licenses/LICENSE-2.0).
11
12 ### Running from command line
13
14 `java -jar fernflower.jar [-<option>=<value>]* [<source>]+ <destination>`
15
16 \* means 0 or more times\
17 \+ means 1 or more times
18
19 \<source>: file or directory with files to be decompiled. Directories are recursively scanned. Allowed file extensions are class, zip and jar.
20           Sources prefixed with -e= mean "library" files that won't be decompiled, but taken into account when analysing relationships between 
21           classes or methods. Especially renaming of identifiers (s. option 'ren') can benefit from information about external classes.          
22
23 \<destination>: destination directory 
24
25 \<option>, \<value>: a command-line option with the corresponding value (see "Command-line options" below).
26
27 ##### Examples:
28
29 `java -jar fernflower.jar -hes=0 -hdc=0 c:\Temp\binary\ -e=c:\Java\rt.jar c:\Temp\source\`
30
31 `java -jar fernflower.jar -dgs=1 c:\Temp\binary\library.jar c:\Temp\binary\Boot.class c:\Temp\source\`
32
33 ### Command-line options
34
35 With the exception of mpm and urc the value of 1 means the option is activated, 0 - deactivated. Default 
36 value, if any, is given between parentheses.
37
38 Typically, the following options will be changed by user, if any: hes, hdc, dgs, mpm, ren, urc 
39 The rest of options can be left as they are: they are aimed at professional reverse engineers.
40
41 - rbr (1): hide bridge methods
42 - rsy (0): hide synthetic class members
43 - din (1): decompile inner classes
44 - dc4 (1): collapse 1.4 class references
45 - das (1): decompile assertions
46 - hes (1): hide empty super invocation
47 - hdc (1): hide empty default constructor
48 - dgs (0): decompile generic signatures
49 - ner (1): assume return not throwing exceptions
50 - den (1): decompile enumerations
51 - rgn (1): remove getClass() invocation, when it is part of a qualified new statement
52 - lit (0): output numeric literals "as-is"
53 - asc (0): encode non-ASCII characters in string and character literals as Unicode escapes
54 - bto (1): interpret int 1 as boolean true (workaround to a compiler bug)
55 - nns (0): allow for not set synthetic attribute (workaround to a compiler bug)
56 - uto (1): consider nameless types as java.lang.Object (workaround to a compiler architecture flaw)
57 - udv (1): reconstruct variable names from debug information, if present
58 - ump (1): reconstruct parameter names from corresponding attributes, if present
59 - rer (1): remove empty exception ranges
60 - fdi (1): de-inline finally structures
61 - mpm (0): maximum allowed processing time per decompiled method, in seconds. 0 means no upper limit
62 - ren (0): rename ambiguous (resp. obfuscated) classes and class elements
63 - urc (-): full name of a user-supplied class implementing IIdentifierRenamer interface. It is used to determine which class identifiers
64            should be renamed and provides new identifier names (see "Renaming identifiers")
65 - inn (1): check for IntelliJ IDEA-specific @NotNull annotation and remove inserted code if found
66 - lac (0): decompile lambda expressions to anonymous classes
67 - nls (0): define new line character to be used for output. 0 - '\r\n' (Windows), 1 - '\n' (Unix), default is OS-dependent
68 - ind: indentation string (default is 3 spaces)
69 - log (INFO): a logging level, possible values are TRACE, INFO, WARN, ERROR
70
71 ### Renaming identifiers
72
73 Some obfuscators give classes and their member elements short, meaningless and above all ambiguous names. Recompiling of such
74 code leads to a great number of conflicts. Therefore it is advisable to let the decompiler rename elements in its turn, 
75 ensuring uniqueness of each identifier.
76
77 Option 'ren' (i.e. -ren=1) activates renaming functionality. Default renaming strategy goes as follows:
78 - rename an element if its name is a reserved word or is shorter than 3 characters
79 - new names are built according to a simple pattern: (class|method|field)_\<consecutive unique number>  
80 You can overwrite this rules by providing your own implementation of the 4 key methods invoked by the decompiler while renaming. Simply 
81 pass a class that implements org.jetbrains.java.decompiler.main.extern.IIdentifierRenamer in the option 'urc'
82 (e.g. -urc=com.example.MyRenamer) to Fernflower. The class must be available on the application classpath.
83
84 The meaning of each method should be clear from naming: toBeRenamed determine whether the element will be renamed, while the other three
85 provide new names for classes, methods and fields respectively.