Remove awareness of isDummyClass
[oota-llvm.git] / docs / HowToSubmitABug.html
index 84d7b8ba1081cd140b400e80b28e1a624521a9f1..6449f29dcd99c5b7b1fcae6c8ae76f8f02186b02 100644 (file)
 
 </ol>
 
-<div class="doc_text">
-  <p><b>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a> and
-                   <a href="http://misha.brukman.net">Misha Brukman</a></b></p>
+<div class="doc_author">
+  <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a> and
+                <a href="http://misha.brukman.net">Misha Brukman</a></p>
 </div>
 
 </td>
 <td align="right">
-  <img src="Debugging.gif" alt="Debugging" width="444" height="314">
+  <img src="img/Debugging.gif" alt="Debugging" width="444" height="314">
 </td>
 </tr>
 </table>
@@ -147,9 +147,9 @@ along with a brief description of the error it caused.</p>
 compilation, compile your test-case to a <tt>.s</tt> file with the
 <tt>-save-temps</tt> option to <tt><b>llvm-gcc</b></tt>. Then run:</p>
 
-<pre>
-  <b>gccas</b> -debug-pass=Arguments &lt; /dev/null -o - &gt; /dev/null
-</pre>
+<div class="doc_code">
+<p><tt><b>gccas</b> -debug-pass=Arguments &lt; /dev/null -o - &gt; /dev/null</tt></p>
+</div>
 
 <p>... which will print a list of arguments, indicating the list of passes that
 <tt><b>gccas</b></tt> runs.  Once you have the input file and the list of
@@ -170,10 +170,11 @@ compilation, gather all of the <tt>.o</tt> bytecode files and libraries that are
 being linked together (the "<tt><b>llvm-gcc</b> -v</tt>" output should include
 the full list of objects linked).  Then run:</p>
 
-<pre>
-  <b>llvm-as</b> &lt; /dev/null &gt; null.bc
-  <b>gccld</b> -debug-pass=Arguments null.bc
-</pre><p>
+<div class="doc_code">
+<p><tt><b>llvm-as</b> &lt; /dev/null &gt; null.bc<br>
+<b>gccld</b> -debug-pass=Arguments null.bc</tt>
+</p>
+</div>
 
 <p>... which will print a list of arguments, indicating the list of passes that
 <tt><b>gccld</b></tt> runs.  Once you have the input files and the list of
@@ -194,19 +195,21 @@ files and a list of passes which crash when run on the specified input.  In
 order to reduce the list of passes (which is probably large) and the input to
 something tractable, use the <tt><b>bugpoint</b></tt> tool as follows:</p>
 
-<pre>
-  <b>bugpoint</b> &lt;input files&gt; &lt;list of passes&gt;
-</pre><p>
+<div class="doc_code">
+<p><tt><b>bugpoint</b> &lt;input files&gt; &lt;list of passes&gt;</tt></p>
+</div>
 
 <p><tt><b>bugpoint</b></tt> will print a bunch of output as it reduces the
 test-case, but it should eventually print something like this:</p>
 
-<pre>
-  ...
-  Emitted bytecode to 'bugpoint-reduced-simplified.bc'
-
-  *** You can reproduce the problem with: opt bugpoint-reduced-simplified.bc -licm
-</pre>
+<div class="doc_code">
+<p><tt>
+...<br>
+Emitted bytecode to 'bugpoint-reduced-simplified.bc'<br>
+<br>
+*** You can reproduce the problem with: opt bugpoint-reduced-simplified.bc -licm<br>
+</tt></p>
+</div>
 
 <p>Once you complete this, please send the LLVM bytecode file and the command
 line to reproduce the problem to the llvmbugs mailing list.</p>
@@ -227,13 +230,21 @@ from producing invalid LLVM code (i.e., code not in SSA form, using values
 before defining them, etc.) which the verifier will check for after a pass
 finishes its run.</p>
 
-<p>To debug a miscompilation, you should choose which program you wish to run
-the output through, e.g. C backend, the JIT, or LLC, and a selection of passes,
-one of which may be causing the error, and run, for example:</p>
+<p>If it looks like the LLVM compiler is miscompiling a program, the very first
+thing to check is to make sure it is not using undefined behavior.  In
+particular, check to see if the program <a
+href="http://valgrind.kde.org/">valgrind</a>s clean, passes purify, or some
+other memory checker tool.  Many of the "LLVM bugs" that we have chased down
+ended up being bugs in the program being compiled, not LLVM.</p>
 
-<pre>
-  <b>bugpoint</b> -run-cbe [... optimization passes ...] file-to-test.bc
-</pre>
+<p>Once you determine that the program itself is not buggy, you should choose 
+which code generator you wish to compile the program with (e.g. C backend, the 
+JIT, or LLC) and optionally a series of LLVM passes to run.  For example:</p>
+
+<div class="doc_code">
+<p><tt>
+<b>bugpoint</b> -run-cbe [... optzn passes ...] file-to-test.bc --args -- [program arguments]</tt></p>
+</div>
 
 <p><tt>bugpoint</tt> will try to narrow down your list of passes to the one pass
 that causes an error, and simplify the bytecode file as much as it can to assist
@@ -260,15 +271,35 @@ Backend, and then link in the shared object it generates.</p>
 
 <p>To debug the JIT:</p>
 
+<div class="doc_code">
 <pre>
-  <b>bugpoint</b> -run-jit -output=[correct output file] [bytecodefile]
+bugpoint -run-jit -output=[correct output file] [bytecode file]  \
+         --tool-args -- [arguments to pass to lli]               \
+         --args -- [program arguments]
 </pre>
+</div>
 
 <p>Similarly, to debug the LLC, one would run:</p>
 
+<div class="doc_code">
 <pre>
-  <b>bugpoint</b> -run-llc -output=[correct output file] [bytecodefile]
+bugpoint -run-llc -output=[correct output file] [bytecode file]  \
+         --tool-args -- [arguments to pass to llc]               \
+         --args -- [program arguments]
 </pre>
+</div>
+
+<p><b>Special note:</b> if you are debugging MultiSource or SPEC tests that
+already exist in the <tt>llvm/test</tt> hierarchy, there is an easier way to
+debug the JIT, LLC, and CBE, using the pre-written Makefile targets, which
+will pass the program options specified in the Makefiles:</p>
+
+<div class="doc_code">
+<p><tt>
+cd llvm/test/../../program<br>
+make bugpoint-jit
+</tt></p>
+</div>
 
 <p>At the end of a successful <tt>bugpoint</tt> run, you will be presented
 with two bytecode files: a <em>safe</em> file which can be compiled with the C
@@ -280,27 +311,32 @@ the following:</p>
 
 <ol>
 
-  <li>Regenerate the shared object from the safe bytecode file:<br>
-
-<pre>
-  <b>llc</b> -march=c safe.bc -o safe.c<br>
-  <b>gcc</b> -shared safe.c -o safe.so
-</pre></li>
-
-  <li>If debugging LLC, compile test bytecode native and link with the shared object:<br>
-
-<pre>
-  <b>llc</b> test.bc -o test.s -f<br>
-  gcc test.s safe.so -o test.llc<br>
-  ./test.llc [program options]
-</pre></li>
-      
-  <li>If debugging the JIT, load the shared object and supply the test
-bytecode:
-
-<pre>
-  <b>lli</b> -load=safe.so test.bc [program options]
-</pre></li>  
+<li><p>Regenerate the shared object from the safe bytecode file:</p>
+
+<div class="doc_code">
+<p><tt>
+<b>llc</b> -march=c safe.bc -o safe.c<br>
+<b>gcc</b> -shared safe.c -o safe.so
+</tt></p>
+</div></li>
+
+<li><p>If debugging LLC, compile test bytecode native and link with the shared
+    object:</p>
+
+<div class="doc_code">
+<p><tt>
+<b>llc</b> test.bc -o test.s -f<br>
+<b>gcc</b> test.s safe.so -o test.llc<br>
+./test.llc [program options]
+</tt></p>
+</div></li>
+    
+<li><p>If debugging the JIT, load the shared object and supply the test
+    bytecode:</p>
+
+<div class="doc_code">
+<p><tt><b>lli</b> -load=safe.so test.bc [program options]</tt></p>
+</div></li>  
 
 </ol>