[llvm-commits] CVS: llvm/docs/CommandGuide/bugpoint.html

[Brian Gaeke]

Changes in directory llvm/docs/CommandGuide:

bugpoint.html updated: 1.11 -> 1.12

---
Log message:

Minor edits to Description section.
Add Design Philosophy as a separate subsection.  Clarify its last sentence.
Give Automatic Mode Selection a uniquely-named anchor.
Always call the program the "test program", instead of the "initial program",
 the "LLVM program", the "test case", the "resultant module", etc.
Try to explain the assumptions a little more, instead of just describing the
 process.


---
Diffs of the changes:  (+36 -25)

Index: llvm/docs/CommandGuide/bugpoint.html
diff -u llvm/docs/CommandGuide/bugpoint.html:1.11 llvm/docs/CommandGuide/bugpoint.html:1.12
--- llvm/docs/CommandGuide/bugpoint.html:1.11	Sun Oct 19 12:03:59 2003
+++ llvm/docs/CommandGuide/bugpoint.html	Sun Oct 19 12:20:15 2003
@@ -15,56 +15,67 @@
 <img src="../Debugging.gif" width=444 height=314 align=right>
 <h3>DESCRIPTION</h3>
 
-The <tt>bugpoint</tt> tool is a generally useful tool for narrowing down
+The <tt>bugpoint</tt> tool narrows down the source of
 problems in LLVM tools and passes.  It can be used to debug three types of
 failures: optimizer crashes, miscompilations by optimizers, or invalid native
-code generation.  It aims to reduce test cases to something useful.  For example,
+code generation.  It aims to reduce large test cases to small, useful ones. 
+For example,
 if <tt><a href="gccas.html">gccas</a></tt> crashes while optimizing a file, it
 will identify the optimization (or combination of optimizations) that causes the
 crash, and reduce the file down to a small example which triggers the crash.<p>
 
+<a name="designphilosophy">
+<h4>Design Philosophy</h4>
+
 <tt>bugpoint</tt> has been designed to be a useful tool without requiring any
 hooks into the LLVM infrastructure at all.  It works with any and all LLVM
 passes and code generators, and does not need to "know" how they work.  Because
 of this, it may appear to do a lot of stupid things or miss obvious
-simplifications.  Remember, however, that computer time is much cheaper than
-programmer time, so if it takes a long time to reduce a test case it is still
-worth it.  :)<p>
+simplifications.  <tt>bugpoint</tt> is also designed to trade off programmer
+time for computer time in the compiler-debugging process; consequently, it may
+take a long period of (unattended) time to reduce a test case, but we feel it
+is still worth it. :-) <p>
 
-<a name="crashdebug">
+<a name="automaticmodeselection">
 <h4>Automatic Mode Selection</h4>
 
-<tt>bugpoint</tt> reads the specified list of <tt>.bc</tt> or <tt>.ll</tt> files
-specified on the command-line and links them together.  If any LLVM passes are
-specified on the command line, it runs these passes on the resultant module.  If
+<tt>bugpoint</tt> reads each <tt>.bc</tt> or <tt>.ll</tt> file
+specified on the command line and links them together into a single module,
+called the test program.  If any LLVM passes are
+specified on the command line, it runs these passes on the test program.  If
 any of the passes crash, or if they produce a malformed LLVM module,
 <tt>bugpoint</tt> enters <a href="#crashdebug">crash debugging mode</a>.<p>
 
 Otherwise, if the <a href="#opt_output"><tt>-output</tt></a> option was not
-specified, <tt>bugpoint</tt> runs the initial program with the C backend (which
+specified, <tt>bugpoint</tt> runs the test program with the C backend (which
 is assumed to generate good code) to generate a reference output.  Once
-<tt>bugpoint</tt> has a reference output to match, it tries executing the
-original program with the <a href="#opt_run-">selected</a> code generator.  If
-the resultant output is different than the reference output, it enters <a
-href="#codegendebug">code generator debugging mode</a>.<p>
-
-Otherwise, <tt>bugpoint</tt> runs the LLVM program after all of the LLVM passes
-have been applied to it.  If the executed program matches the reference output,
-there is no problem <tt>bugpoint</tt> can debug.  Otherwise, it enters <a
-href="#miscompilationdebug">miscompilation debugging mode</a>.<p>
+<tt>bugpoint</tt> has a reference output for the test program, it tries
+executing it
+with the <a href="#opt_run-">selected</a> code generator.  If
+the resulting output differs from the reference output, it assumes the
+difference resulted from a code generator failure, and enters
+<a href="#codegendebug">code generator debugging mode</a>.<p>
+
+Otherwise, <tt>bugpoint</tt> runs the test program after all of the LLVM passes
+have been applied to it.  If its output differs from the reference output,
+it assumes the difference resulted from a failure in one of the LLVM passes,
+and enters
+<a href="#miscompilationdebug">miscompilation debugging mode</a>. Otherwise,
+there is no problem <tt>bugpoint</tt> can debug.<p>
 
 <a name="crashdebug">
 <h4>Crash debugging mode</h4>
 
-If an optimizer crashes, <tt>bugpoint</tt> will try a variety of techniques to
-narrow down the list of passes and the code to a more manageable amount.  First,
-<tt>bugpoint</tt> figures out which combination of passes trigger the bug.  This
-is useful when debugging a problem exposed by <tt>gccas</tt> for example,
+If an optimizer crashes, <tt>bugpoint</tt> will try as hard as it can to
+reduce the list of passes and the size of the test program.  First,
+<tt>bugpoint</tt> figures out which combination of passes triggers the bug. This
+is useful when debugging a problem exposed by <tt>gccas</tt>, for example,
 because it runs over 30 optimizations.<p>
 
 Next, <tt>bugpoint</tt> tries removing functions from the module, to reduce the
-size of the test case to a reasonable amount.  Usually it is able to get it down
-to a single function for intraprocedural optimizations.  Once the number of
+size of the test program.  Usually it is able to reduce a test program
+to a single function, when debugging intraprocedural optimizations.  Once the
+number of
 functions has been reduced, it attempts to delete various edges in the control
 flow graph, to reduce the size of the function as much as possible.  Finally,
 <tt>bugpoint</tt> deletes any individual LLVM instructions whose absence does