| <!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> |
| |
