usage.html revision b72c5c2e5482cf10117b2b25f642f7616b2326c3 
1<!doctype html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2<html>
3<head>
4<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
5<meta http-equiv="content-style-type" content="text/css">
6<link rel="stylesheet" type="text/css" href="/style.css">
7<title>ReTrace Usage</title>
8</head>
9<body>
10
11<h2>Usage</h2>
12
13You can find the ReTrace jar in the <code>lib</code> directory of the
14ProGuard distribution. To run ReTrace, just type:
15<p>
16<p class="code">
17<code><b>java -jar retrace.jar </b></code>[<i>options...</i>]
18         <i>mapping_file</i> [<i>stacktrace_file</i>]
19</p>
20These are the arguments:
21
22<dl>
23<dt><i>mapping_file</i></dt>
24
25<dd>Specifies the name of the mapping file, produced by ProGuard with the
26    option
27    "<a href="/usage.html#printmapping"><code>-printmapping</code></a> <i>mapping_file</i>",
28    while obfuscating the application that produced the stack trace.</dd>
29
30<dt><i>stacktrace_file</i></dt>
31
32<dd>Optionally specifies the name of the file containing the stack trace. If
33    no file is specified, a stack trace is read from the standard input. Blank
34    lines and unrecognized lines are ignored, as far as possible.</dd>
35</dl>
36
37The following options are supported:
38<dl>
39<dt><code><b>-verbose</b></code></dt>
40
41<dd>Specifies to print out more informative stack traces that include not only
42    method names, but also method return types and arguments.</dd>
43
44<dt><code><b>-regex</b></code> <i>regular_expression</i></dt>
45
46<dd>Specifies the regular expression that is used to parse the lines in the
47    stack trace. Specifying a different regular expression allows to
48    de-obfuscate more general types of input than just stack traces. The
49    default is suitable for stack traces produced by most JVMs:
50    <pre>
51    (?:\s*%c:.*)|(?:\s*at\s+%c.%m\s*\(.*?(?::%l)?\)\s*)
52    </pre>
53    The regular expression is a Java regular expression (cfr. the documentation
54    of <code>java.util.regex.Pattern</code>), with a few additional wildcards:
55    <table cellspacing="10">
56    <tr><td valign="top"><code><b>%c</b></code></td>
57        <td>matches a class name (e.g.
58            "<code>myapplication.MyClass</code>").</td></tr>
59    <tr><td valign="top"><code><b>%C</b></code></td>
60        <td>matches a class name with slashes (e.g.
61            "<code>myapplication/MyClass</code>").</td></tr>
62    <tr><td valign="top"><code><b>%t</b></code></td>
63        <td>matches a field type or method return type (e.g.
64            "<code>myapplication.MyClass[]</code>").</td></tr>
65    <tr><td valign="top"><code><b>%f</b></code></td>
66        <td>matches a field name (e.g.
67            "<code>myField</code>").</td></tr>
68    <tr><td valign="top"><code><b>%m</b></code></td>
69        <td>matches a method name (e.g.
70            "<code>myMethod</code>").</td></tr>
71    <tr><td valign="top"><code><b>%a</b></code></td>
72        <td>matches a list of method arguments (e.g.
73            "<code>boolean,int</code>").</td></tr>
74    <tr><td valign="top"><code><b>%l</b></code></td>
75        <td>matches a line number inside a method (e.g.
76            "<code>123</code>").</td></tr>
77    </table>
78    Elements that match these wildcards are de-obfuscated, when possible. Note
79    that regular expressions must not contain any capturing groups. Use
80    non-capturing groups instead: <code>(?:</code>...<code>)</code>
81    </dd>
82</dl>
83
84The restored stack trace is printed to the standard output. The completeness
85of the restored stack trace depends on the presence of line number tables in
86the obfuscated class files:
87
88<ul>
89<li>If all line numbers have been preserved while obfuscating the application,
90    ReTrace will be able to restore the stack trace completely.
91    <p>
92
93<li>If the line numbers have been removed, mapping obfuscated method names
94    back to their original names has become ambiguous. Retrace will list all
95    possible original method names for each line in the stack trace. The user
96    can then try to deduce the actual stack trace manually, based on the logic
97    of the program.
98
99</ul>
100<p>
101
102Preserving line number tables is explained in detail in this <a
103href="/examples.html#stacktrace">example</a> in the ProGuard User Manual.
104<p>
105
106Unobfuscated elements and obfuscated elements for which no mapping is available
107will be left unchanged.
108<p>
109
110<hr>
111<address>
112Copyright &copy; 2002-2009
113<a href="http://www.graphics.cornell.edu/~eric/">Eric Lafortune</a>.
114</address>
115</body>
116</html>
117
118