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