Gitiles
Code Review Sign In
gerrit-public.fairphone.software / toolchain / llvm-project / 8a32c6d91b859c1d2a7f72a68db18d550b5340b6 / . / llvm / docs / CommandGuide / bugpoint.html
blob: e73bd0986882a671673a4613f2c9407d6a96103a [file] [log] [blame]
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]1<html>
2<title>LLVM: bugpoint tool</title>
3
4<body bgcolor=white>
5
6<center><h1>LLVM: <tt>bugpoint</tt> tool</h1></center>
7<HR>
8
9<h3>NAME</h3>
10<tt>bugpoint</tt>
11
12<h3>SYNOPSIS</h3>
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]13<tt>bugpoint [options] [input LLVM ll/bc files] [LLVM passes] --args &lt;program arguments&gt;...</tt>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]14
15<img src="../Debugging.gif" width=444 height=314 align=right>
16<h3>DESCRIPTION</h3>
17
Brian Gaekeabe08a62003-10-19 17:20:15 +0000[diff] [blame]18The <tt>bugpoint</tt> tool narrows down the source of
Chris Lattnerb0ce7e22003-10-18 20:36:15 +0000[diff] [blame]19problems in LLVM tools and passes. It can be used to debug three types of
Chris Lattner3ef249c02004-04-06 15:22:35 +0000[diff] [blame]20failures: optimizer crashes, miscompilations by optimizers, or bad native
21code generation (including problems in the static and JIT compilers). It aims
22to reduce large test cases to small, useful ones. For example,
Chris Lattnerb0ce7e22003-10-18 20:36:15 +0000[diff] [blame]23if <tt><a href="gccas.html">gccas</a></tt> crashes while optimizing a file, it
24will identify the optimization (or combination of optimizations) that causes the
25crash, and reduce the file down to a small example which triggers the crash.<p>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]26
Brian Gaekeabe08a62003-10-19 17:20:15 +0000[diff] [blame]27<a name="designphilosophy">
28<h4>Design Philosophy</h4>
29
Chris Lattner90f86a72003-10-19 17:27:12 +0000[diff] [blame]30<tt>bugpoint</tt> is designed to be a useful tool without requiring any
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]31hooks into the LLVM infrastructure at all. It works with any and all LLVM
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]32passes and code generators, and does not need to "know" how they work. Because
Chris Lattner3ef249c02004-04-06 15:22:35 +0000[diff] [blame]33of this, it may appear to do stupid things or miss obvious
Brian Gaekeabe08a62003-10-19 17:20:15 +0000[diff] [blame]34simplifications. <tt>bugpoint</tt> is also designed to trade off programmer
35time for computer time in the compiler-debugging process; consequently, it may
36take a long period of (unattended) time to reduce a test case, but we feel it
Chris Lattner3ef249c02004-04-06 15:22:35 +0000[diff] [blame]37is still worth it. Note that <tt>bugpoint</tt> is generally very quick unless
38debugging a miscompilation where each test of the program (which requires
39executing it) takes a long time.<p>
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]40
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]41<a name="automaticdebuggerselection">
42<h4>Automatic Debugger Selection</h4>
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]43
Brian Gaekeabe08a62003-10-19 17:20:15 +0000[diff] [blame]44<tt>bugpoint</tt> reads each <tt>.bc</tt> or <tt>.ll</tt> file
45specified on the command line and links them together into a single module,
46called the test program. If any LLVM passes are
47specified on the command line, it runs these passes on the test program. If
Chris Lattner3ef249c02004-04-06 15:22:35 +0000[diff] [blame]48any of the passes crash, or if they produce malformed output (which causes the
49verifier to abort),
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]50<tt>bugpoint</tt> starts the <a href="#crashdebug">crash debugger</a>.<p>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]51
Chris Lattnerb0ce7e22003-10-18 20:36:15 +0000[diff] [blame]52Otherwise, if the <a href="#opt_output"><tt>-output</tt></a> option was not
Chris Lattner5f015c72004-02-18 23:30:21 +0000[diff] [blame]53specified, <tt>bugpoint</tt> runs the test program with the C backend (which is
54assumed to generate good code) to generate a reference output. Once
Brian Gaekeabe08a62003-10-19 17:20:15 +0000[diff] [blame]55<tt>bugpoint</tt> has a reference output for the test program, it tries
Chris Lattner5f015c72004-02-18 23:30:21 +0000[diff] [blame]56executing it with the <a href="#opt_run-">selected</a> code generator. If the
57selected code generator crashes, <tt>bugpoint</tt> starts the <a
58href="#crashdebug">crash debugger</a> on the code generator. Otherwise, if the
59resulting output differs from the reference output, it assumes the difference
60resulted from a code generator failure, and starts the <a
61href="#codegendebug">code generator debugger</a>.<p>
Chris Lattnerb0ce7e22003-10-18 20:36:15 +0000[diff] [blame]62
Chris Lattner5f015c72004-02-18 23:30:21 +0000[diff] [blame]63Finally, if the output of the selected code generator matches the reference
64output, <tt>bugpoint</tt> runs the test program after all of the LLVM passes
65have been applied to it. If its output differs from the reference output, it
66assumes the difference resulted from a failure in one of the LLVM passes, and
67enters the <a href="#miscompilationdebug">miscompilation
68debugger</a>. Otherwise, there is no problem <tt>bugpoint</tt> can debug.<p>
Chris Lattnerb0ce7e22003-10-18 20:36:15 +0000[diff] [blame]69
70<a name="crashdebug">
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]71<h4>Crash debugger</h4>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]72
Chris Lattner5f015c72004-02-18 23:30:21 +0000[diff] [blame]73If an optimizer or code generator crashes, <tt>bugpoint</tt> will try as hard as
74it can to reduce the list of passes (for optimizer crashes) and the size of the
75test program. First, <tt>bugpoint</tt> figures out which combination of
76optimizer passes triggers the bug. This is useful when debugging a problem
Chris Lattner3ef249c02004-04-06 15:22:35 +0000[diff] [blame]77exposed by <tt>gccas</tt>, for example, because it runs over 38 passes.<p>
Misha Brukman488ccea2003-10-16 18:14:43 +0000[diff] [blame]78
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]79Next, <tt>bugpoint</tt> tries removing functions from the test program, to
Chris Lattner5f015c72004-02-18 23:30:21 +0000[diff] [blame]80reduce its size. Usually it is able to reduce a test program to a single
81function, when debugging intraprocedural optimizations. Once the number of
Chris Lattnerb0ce7e22003-10-18 20:36:15 +0000[diff] [blame]82functions has been reduced, it attempts to delete various edges in the control
83flow graph, to reduce the size of the function as much as possible. Finally,
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]84<tt>bugpoint</tt> deletes any individual LLVM instructions whose absence does
Chris Lattnerb0ce7e22003-10-18 20:36:15 +0000[diff] [blame]85not eliminate the failure. At the end, <tt>bugpoint</tt> should tell you what
86passes crash, give you a bytecode file, and give you instructions on how to
Chris Lattner5f015c72004-02-18 23:30:21 +0000[diff] [blame]87reproduce the failure with <tt><a href="opt.html">opt</a></tt>, <tt><a
88href="analyze.html">analyze</a></tt>, or <tt><a href="llc.html">llc</a></tt>.<p>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]89
Chris Lattnerb0ce7e22003-10-18 20:36:15 +0000[diff] [blame]90<a name="codegendebug">
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]91<h4>Code generator debugger</h4>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]92
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]93The code generator debugger attempts to narrow down the amount of code that is
94being miscompiled by the <a href="#opt_run-">selected</a> code generator. To do
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]95this, it takes the test program and partitions it into two pieces: one piece
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]96which it compiles with the C backend (into a shared object), and one piece which
97it runs with either the JIT or the static LLC compiler. It uses several
98techniques to reduce the amount of code pushed through the LLVM code generator,
99to reduce the potential scope of the problem. After it is finished, it emits
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]100two bytecode files (called "test" [to be compiled with the code generator] and
101"safe" [to be compiled with the C backend] respectively), and instructions for
102reproducing the problem. The code generator debugger assumes that the C
103backend produces good code.<p>
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]104
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]105If you are using the code generator debugger and get an error message that
Misha Brukman774b94a2003-10-20 19:47:25 +0000[diff] [blame]106says "UNSUPPORTED: external function used as a global initializer!", try using
107the <tt>-run-llc</tt> option instead of the <tt>-run-jit</tt> option. This is
108due to an unimplemented feature in the code generator debugger.<p>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]109
Chris Lattnerb0ce7e22003-10-18 20:36:15 +0000[diff] [blame]110<a name="miscompilationdebug">
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]111<h4>Miscompilation debugger</h4>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]112
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]113The miscompilation debugger works similarly to the code generator
114debugger. It works by splitting the test program into two pieces, running the
115optimizations specified on one piece, linking the two pieces back together,
116and then executing the result.
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]117It attempts to narrow down the list of passes to the one (or few) which are
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]118causing the miscompilation, then reduce the portion of the test program which is
119being miscompiled. The miscompilation debugger assumes that the selected
120code generator is working properly.<p>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]121
Chris Lattnerf0219402003-10-18 21:34:15 +0000[diff] [blame]122<a name="bugpoint notes">
123<h4>Advice for using <tt>bugpoint</tt></h4>
124
125<tt>bugpoint</tt> can be a remarkably useful tool, but it sometimes works in
126non-obvious ways. Here are some hints and tips:<p>
127
128<ol>
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]129<li>In the code generator and miscompilation debuggers, <tt>bugpoint</tt> only
Chris Lattnerf0219402003-10-18 21:34:15 +0000[diff] [blame]130 works with programs that have deterministic output. Thus, if the program
Chris Lattner3ef249c02004-04-06 15:22:35 +0000[diff] [blame]131 outputs <tt>argv[0]</tt>, the date, time, or any other "random" data, <tt>bugpoint</tt> may
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]132 misinterpret differences in these data, when output, as the result of a
133 miscompilation. Programs should be temporarily modified to disable
134 outputs that are likely to vary from run to run.
Chris Lattnerf0219402003-10-18 21:34:15 +0000[diff] [blame]135
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]136<li>In the code generator and miscompilation debuggers, debugging will go
Chris Lattnerf0219402003-10-18 21:34:15 +0000[diff] [blame]137 faster if you manually modify the program or its inputs to reduce the
138 runtime, but still exhibit the problem.
139
140<li><tt>bugpoint</tt> is extremely useful when working on a new optimization:
141 it helps track down regressions quickly. To avoid having to relink
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]142 <tt>bugpoint</tt> every time you change your optimization however, have
Chris Lattnerf0219402003-10-18 21:34:15 +0000[diff] [blame]143 <tt>bugpoint</tt> dynamically load your optimization with the <a
144 href="#opt_load"><tt>-load</tt></a> option.
145
146<li><tt>bugpoint</tt> can generate a lot of output and run for a long period of
147 time. It is often useful to capture the output of the program to file. For
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]148 example, in the C shell, you can type:<br>
Chris Lattnerd46f9452003-10-19 17:37:33 +0000[diff] [blame]149 <tt>bugpoint ..... |&amp; tee bugpoint.log</tt>
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]150 <br>to get a copy of <tt>bugpoint</tt>'s output in the file
Brian Gaekec8521942003-10-19 17:37:12 +0000[diff] [blame]151 <tt>bugpoint.log</tt>, as well as on your terminal.
Chris Lattnerf0219402003-10-18 21:34:15 +0000[diff] [blame]152
Chris Lattner3ef249c02004-04-06 15:22:35 +0000[diff] [blame]153<li><tt>bugpoint</tt> cannot debug problems with the LLVM linker. If
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]154 <tt>bugpoint</tt> crashes before you see its "All input ok" message,
155 you might try <tt>llvm-link -v</tt> on the same set of input files. If
156 that also crashes, you may be experiencing a linker bug.
Brian Gaekebc67d592004-02-11 18:44:55 +0000[diff] [blame]157
158<li>If your program is <b>supposed</b> to crash, <tt>bugpoint</tt> will be
159 confused. One way to deal with this is to cause bugpoint to ignore the exit
160 code from your program, by giving it the <tt>-check-exit-code=false</tt>
161 option.
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]162
Chris Lattnerf0219402003-10-18 21:34:15 +0000[diff] [blame]163</ol>
164
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]165<h3>OPTIONS</h3>
166
167<ul>
John Criswell2edea842004-01-26 21:26:54 +0000[diff] [blame]168 <li><tt>-additional-so &lt;library&gt;</tt><br>
169 Load <tt>&lt;library&gt;</tt> into the test program whenever it is run.
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]170 This is useful if you are debugging programs which depend on non-LLVM
171 libraries (such as the X or curses libraries) to run.<p>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]172
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]173 <li><tt>-args &lt;program args&gt;</tt><br>
174 Pass all arguments specified after <tt>-args</tt> to the
175 test program whenever it runs. Note that if any of
176 the <tt>&lt;program args&gt;</tt> start with a '-', you should use:
Chris Lattner9d7eeb62003-10-18 20:57:23 +0000[diff] [blame]177 <p>
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]178 <tt>bugpoint &lt;bugpoint args&gt; -args -- &lt;program args&gt;</tt>
Chris Lattner9d7eeb62003-10-18 20:57:23 +0000[diff] [blame]179 <p>
180 The "<tt>--</tt>" right after the <tt>-args</tt> option tells
181 <tt>bugpoint</tt> to consider any options starting with <tt>-</tt> to be
182 part of the <tt>-args</tt> option, not as options to <tt>bugpoint</tt>
183 itself.<p>
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]184
Brian Gaeke228a29b2004-02-11 18:40:04 +0000[diff] [blame]185 <li><tt>-check-exit-code={true,false}</tt><br>
186 Assume a non-zero exit code or core dump from the test program is
187 a failure. Defaults to true.<p>
188
Chris Lattner84d0f632004-03-13 19:36:30 +0000[diff] [blame]189 <li><tt>-disable-{dce,simplifycfg}</tt><br>
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]190 Do not run the specified passes to clean up and reduce the size of the
191 test program. By default, <tt>bugpoint</tt> uses these passes internally
192 when attempting to reduce test programs. If you're trying to find
193 a bug in one of these passes, <tt>bugpoint</tt> may crash.<p>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]194
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]195 <li> <tt>-help</tt><br>
196 Print a summary of command line options.<p>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]197
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]198 <a name="opt_input"><li><tt>-input &lt;filename&gt;</tt><br>
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]199 Open <tt>&lt;filename&gt;</tt> and redirect the standard input of the
200 test program, whenever it runs, to come from that file.
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]201 <p>
202
John Criswell2edea842004-01-26 21:26:54 +0000[diff] [blame]203 <a name="opt_load"><li> <tt>-load &lt;plugin&gt;</tt><br>
204 Load the dynamic object <tt>&lt;plugin&gt;</tt> into <tt>bugpoint</tt>
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]205 itself. This object should register new
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]206 optimization passes. Once loaded, the object will add new command line
207 options to enable various optimizations. To see the new complete list
208 of optimizations, use the -help and -load options together:
209 <p>
John Criswell2edea842004-01-26 21:26:54 +0000[diff] [blame]210 <tt>bugpoint -load &lt;plugin&gt; -help</tt>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]211 <p>
212
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]213 <a name="opt_output"><li><tt>-output &lt;filename&gt;</tt><br>
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]214 Whenever the test program produces output on its standard output
215 stream, it should match the contents of <tt>&lt;filename&gt;</tt>
216 (the "reference output"). If you do not use this option,
217 <tt>bugpoint</tt> will attempt to generate a reference output by
218 compiling the program with the C backend and running it.<p>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]219
John Criswellfa2f3682004-03-29 20:23:11 +0000[diff] [blame]220 <li><tt>-profile-info-file &lt;filename&gt;</tt><br>
221 Profile file loaded by -profile-loader.<p>
222
Brian Gaeke8ef235e2003-10-19 17:35:35 +0000[diff] [blame]223 <a name="opt_run-"><li><tt>-run-{int,jit,llc,cbe}</tt><br>
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]224 Whenever the test program is compiled, <tt>bugpoint</tt> should generate
225 code for it using the specified code generator. These options allow
226 you to choose the interpreter, the JIT compiler, the static native
227 code compiler, or the C backend, respectively.<p>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]228</ul>
229
230<h3>EXIT STATUS</h3>
231
232If <tt>bugpoint</tt> succeeds in finding a problem, it will exit with 0.
233Otherwise, if an error occurs, it will exit with a non-zero value.
234
235<h3>SEE ALSO</h3>
John Criswell38458952003-10-16 20:15:17 +0000[diff] [blame]236<a href="opt.html"><tt>opt</tt></a>,
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]237<a href="analyze.html"><tt>analyze</tt></a>
238
239<HR>
240Maintained by the <a href="http://llvm.cs.uiuc.edu">LLVM Team</a>.
241</body>
242</html>