Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / llvm / f4ad013a0e72866e747303911fc39fdd8bddd26a / . / docs / CommandGuide / bugpoint.html
blob: 519e02d5277580b42d97eaa8f4de926685eeb97d [file] [log] [blame]
Chris Lattner1213bc72003-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 Gaekeb9b3c332003-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 Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]14
Chris Lattnerf4ad0132004-05-28 16:49:54 +0000[diff] [blame^]15<img src="../img/Debugging.gif" width=444 height=314 align=right>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]16<h3>DESCRIPTION</h3>
17
Brian Gaeke237b3662003-10-19 17:20:15 +0000[diff] [blame]18The <tt>bugpoint</tt> tool narrows down the source of
Chris Lattnerd1eb6f72003-10-18 20:36:15 +0000[diff] [blame]19problems in LLVM tools and passes. It can be used to debug three types of
Chris Lattner1c623552004-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 Lattnerd1eb6f72003-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 Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]26
Brian Gaeke237b3662003-10-19 17:20:15 +0000[diff] [blame]27<a name="designphilosophy">
28<h4>Design Philosophy</h4>
29
Chris Lattner129e7a82003-10-19 17:27:12 +0000[diff] [blame]30<tt>bugpoint</tt> is designed to be a useful tool without requiring any
Brian Gaekeb9b3c332003-10-19 17:03:59 +0000[diff] [blame]31hooks into the LLVM infrastructure at all. It works with any and all LLVM
Chris Lattner5cd840c2003-10-18 20:54:37 +0000[diff] [blame]32passes and code generators, and does not need to "know" how they work. Because
Chris Lattner1c623552004-04-06 15:22:35 +0000[diff] [blame]33of this, it may appear to do stupid things or miss obvious
Brian Gaeke237b3662003-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 Lattner1c623552004-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 Lattner5cd840c2003-10-18 20:54:37 +0000[diff] [blame]40
Brian Gaeke6ff33102003-10-19 17:30:36 +0000[diff] [blame]41<a name="automaticdebuggerselection">
42<h4>Automatic Debugger Selection</h4>
Chris Lattner5cd840c2003-10-18 20:54:37 +0000[diff] [blame]43
Brian Gaeke237b3662003-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 Lattner1c623552004-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 Gaeke6ff33102003-10-19 17:30:36 +0000[diff] [blame]50<tt>bugpoint</tt> starts the <a href="#crashdebug">crash debugger</a>.<p>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]51
Chris Lattnerd1eb6f72003-10-18 20:36:15 +0000[diff] [blame]52Otherwise, if the <a href="#opt_output"><tt>-output</tt></a> option was not
Chris Lattnereb373aa2004-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 Gaeke237b3662003-10-19 17:20:15 +0000[diff] [blame]55<tt>bugpoint</tt> has a reference output for the test program, it tries
Chris Lattnereb373aa2004-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 Lattnerd1eb6f72003-10-18 20:36:15 +0000[diff] [blame]62
Chris Lattnereb373aa2004-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 Lattnerd1eb6f72003-10-18 20:36:15 +0000[diff] [blame]69
70<a name="crashdebug">
Brian Gaeke6ff33102003-10-19 17:30:36 +0000[diff] [blame]71<h4>Crash debugger</h4>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]72
Chris Lattnereb373aa2004-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 Lattner1c623552004-04-06 15:22:35 +0000[diff] [blame]77exposed by <tt>gccas</tt>, for example, because it runs over 38 passes.<p>
Misha Brukman3f717222003-10-16 18:14:43 +0000[diff] [blame]78
Brian Gaeke6ff33102003-10-19 17:30:36 +0000[diff] [blame]79Next, <tt>bugpoint</tt> tries removing functions from the test program, to
Chris Lattnereb373aa2004-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 Lattnerd1eb6f72003-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 Gaekeb9b3c332003-10-19 17:03:59 +0000[diff] [blame]84<tt>bugpoint</tt> deletes any individual LLVM instructions whose absence does
Chris Lattnerd1eb6f72003-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 Lattnereb373aa2004-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 Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]89
Chris Lattnerd1eb6f72003-10-18 20:36:15 +0000[diff] [blame]90<a name="codegendebug">
Brian Gaeke6ff33102003-10-19 17:30:36 +0000[diff] [blame]91<h4>Code generator debugger</h4>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]92
Misha Brukmanf6f7ec12004-04-19 03:28:39 +0000[diff] [blame]93<p>The code generator debugger attempts to narrow down the amount of code that
94is being miscompiled by the <a href="#opt_run-">selected</a> code generator. To
95do this, it takes the test program and partitions it into two pieces: one piece
Chris Lattner5cd840c2003-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 Gaeke6ff33102003-10-19 17:30:36 +0000[diff] [blame]100two bytecode files (called "test" [to be compiled with the code generator] and
Misha Brukmanf6f7ec12004-04-19 03:28:39 +0000[diff] [blame]101"safe" [to be compiled with the C backend], respectively), and instructions for
102reproducing the problem. The code generator debugger assumes that the C backend
103produces good code.</p>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]104
Chris Lattnerd1eb6f72003-10-18 20:36:15 +0000[diff] [blame]105<a name="miscompilationdebug">
Brian Gaeke6ff33102003-10-19 17:30:36 +0000[diff] [blame]106<h4>Miscompilation debugger</h4>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]107
Brian Gaeke6ff33102003-10-19 17:30:36 +0000[diff] [blame]108The miscompilation debugger works similarly to the code generator
109debugger. It works by splitting the test program into two pieces, running the
110optimizations specified on one piece, linking the two pieces back together,
111and then executing the result.
Chris Lattner5cd840c2003-10-18 20:54:37 +0000[diff] [blame]112It attempts to narrow down the list of passes to the one (or few) which are
Brian Gaeke6ff33102003-10-19 17:30:36 +0000[diff] [blame]113causing the miscompilation, then reduce the portion of the test program which is
114being miscompiled. The miscompilation debugger assumes that the selected
115code generator is working properly.<p>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]116
Chris Lattner634ec562003-10-18 21:34:15 +0000[diff] [blame]117<a name="bugpoint notes">
118<h4>Advice for using <tt>bugpoint</tt></h4>
119
120<tt>bugpoint</tt> can be a remarkably useful tool, but it sometimes works in
121non-obvious ways. Here are some hints and tips:<p>
122
123<ol>
Brian Gaeke6ff33102003-10-19 17:30:36 +0000[diff] [blame]124<li>In the code generator and miscompilation debuggers, <tt>bugpoint</tt> only
Chris Lattner634ec562003-10-18 21:34:15 +0000[diff] [blame]125 works with programs that have deterministic output. Thus, if the program
Chris Lattner1c623552004-04-06 15:22:35 +0000[diff] [blame]126 outputs <tt>argv[0]</tt>, the date, time, or any other "random" data, <tt>bugpoint</tt> may
Brian Gaekeb9b3c332003-10-19 17:03:59 +0000[diff] [blame]127 misinterpret differences in these data, when output, as the result of a
128 miscompilation. Programs should be temporarily modified to disable
129 outputs that are likely to vary from run to run.
Chris Lattner634ec562003-10-18 21:34:15 +0000[diff] [blame]130
Brian Gaeke6ff33102003-10-19 17:30:36 +0000[diff] [blame]131<li>In the code generator and miscompilation debuggers, debugging will go
Chris Lattner634ec562003-10-18 21:34:15 +0000[diff] [blame]132 faster if you manually modify the program or its inputs to reduce the
133 runtime, but still exhibit the problem.
134
135<li><tt>bugpoint</tt> is extremely useful when working on a new optimization:
136 it helps track down regressions quickly. To avoid having to relink
Brian Gaekeb9b3c332003-10-19 17:03:59 +0000[diff] [blame]137 <tt>bugpoint</tt> every time you change your optimization however, have
Chris Lattner634ec562003-10-18 21:34:15 +0000[diff] [blame]138 <tt>bugpoint</tt> dynamically load your optimization with the <a
139 href="#opt_load"><tt>-load</tt></a> option.
140
141<li><tt>bugpoint</tt> can generate a lot of output and run for a long period of
142 time. It is often useful to capture the output of the program to file. For
Brian Gaekeb9b3c332003-10-19 17:03:59 +0000[diff] [blame]143 example, in the C shell, you can type:<br>
Chris Lattnere99e7342003-10-19 17:37:33 +0000[diff] [blame]144 <tt>bugpoint ..... |&amp; tee bugpoint.log</tt>
Brian Gaekeb9b3c332003-10-19 17:03:59 +0000[diff] [blame]145 <br>to get a copy of <tt>bugpoint</tt>'s output in the file
Brian Gaeke768a3182003-10-19 17:37:12 +0000[diff] [blame]146 <tt>bugpoint.log</tt>, as well as on your terminal.
Chris Lattner634ec562003-10-18 21:34:15 +0000[diff] [blame]147
Chris Lattner1c623552004-04-06 15:22:35 +0000[diff] [blame]148<li><tt>bugpoint</tt> cannot debug problems with the LLVM linker. If
Brian Gaeke6ff33102003-10-19 17:30:36 +0000[diff] [blame]149 <tt>bugpoint</tt> crashes before you see its "All input ok" message,
150 you might try <tt>llvm-link -v</tt> on the same set of input files. If
151 that also crashes, you may be experiencing a linker bug.
Brian Gaeke421f3172004-02-11 18:44:55 +0000[diff] [blame]152
153<li>If your program is <b>supposed</b> to crash, <tt>bugpoint</tt> will be
154 confused. One way to deal with this is to cause bugpoint to ignore the exit
155 code from your program, by giving it the <tt>-check-exit-code=false</tt>
156 option.
Brian Gaeke6ff33102003-10-19 17:30:36 +0000[diff] [blame]157
Chris Lattner634ec562003-10-18 21:34:15 +0000[diff] [blame]158</ol>
159
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]160<h3>OPTIONS</h3>
161
162<ul>
John Criswellf9c78652004-01-26 21:26:54 +0000[diff] [blame]163 <li><tt>-additional-so &lt;library&gt;</tt><br>
164 Load <tt>&lt;library&gt;</tt> into the test program whenever it is run.
Brian Gaekeb9b3c332003-10-19 17:03:59 +0000[diff] [blame]165 This is useful if you are debugging programs which depend on non-LLVM
166 libraries (such as the X or curses libraries) to run.<p>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]167
Brian Gaekeb9b3c332003-10-19 17:03:59 +0000[diff] [blame]168 <li><tt>-args &lt;program args&gt;</tt><br>
169 Pass all arguments specified after <tt>-args</tt> to the
170 test program whenever it runs. Note that if any of
171 the <tt>&lt;program args&gt;</tt> start with a '-', you should use:
Chris Lattner0b4ffea2003-10-18 20:57:23 +0000[diff] [blame]172 <p>
Brian Gaekeb9b3c332003-10-19 17:03:59 +0000[diff] [blame]173 <tt>bugpoint &lt;bugpoint args&gt; -args -- &lt;program args&gt;</tt>
Chris Lattner0b4ffea2003-10-18 20:57:23 +0000[diff] [blame]174 <p>
175 The "<tt>--</tt>" right after the <tt>-args</tt> option tells
176 <tt>bugpoint</tt> to consider any options starting with <tt>-</tt> to be
177 part of the <tt>-args</tt> option, not as options to <tt>bugpoint</tt>
178 itself.<p>
Chris Lattner5cd840c2003-10-18 20:54:37 +0000[diff] [blame]179
Brian Gaekecbc796e2004-05-04 21:13:35 +0000[diff] [blame]180 <li><tt>-tool-args &lt;tool args&gt;</tt><br>
181 Pass all arguments specified after <tt>-tool-args</tt> to the
182 LLVM tool under test (llc, lli, etc.) whenever it runs.
183 You should use this option in the following way:
184 <p>
185 <tt>bugpoint &lt;bugpoint args&gt; -tool-args -- &lt;tool args&gt;</tt>
186 <p>
187 The "<tt>--</tt>" right after the <tt>-tool-args</tt> option tells
188 <tt>bugpoint</tt> to consider any options starting with <tt>-</tt> to be
189 part of the <tt>-tool-args</tt> option, not as options to
190 <tt>bugpoint</tt> itself. (See <tt>-args</tt>, above.)<p>
191
Brian Gaeke4fda7762004-02-11 18:40:04 +0000[diff] [blame]192 <li><tt>-check-exit-code={true,false}</tt><br>
193 Assume a non-zero exit code or core dump from the test program is
194 a failure. Defaults to true.<p>
195
Chris Lattner6a6d2a22004-03-13 19:36:30 +0000[diff] [blame]196 <li><tt>-disable-{dce,simplifycfg}</tt><br>
Brian Gaekeb9b3c332003-10-19 17:03:59 +0000[diff] [blame]197 Do not run the specified passes to clean up and reduce the size of the
198 test program. By default, <tt>bugpoint</tt> uses these passes internally
199 when attempting to reduce test programs. If you're trying to find
200 a bug in one of these passes, <tt>bugpoint</tt> may crash.<p>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]201
Chris Lattner5cd840c2003-10-18 20:54:37 +0000[diff] [blame]202 <li> <tt>-help</tt><br>
203 Print a summary of command line options.<p>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]204
Chris Lattner5cd840c2003-10-18 20:54:37 +0000[diff] [blame]205 <a name="opt_input"><li><tt>-input &lt;filename&gt;</tt><br>
Brian Gaekeb9b3c332003-10-19 17:03:59 +0000[diff] [blame]206 Open <tt>&lt;filename&gt;</tt> and redirect the standard input of the
207 test program, whenever it runs, to come from that file.
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]208 <p>
209
John Criswellf9c78652004-01-26 21:26:54 +0000[diff] [blame]210 <a name="opt_load"><li> <tt>-load &lt;plugin&gt;</tt><br>
211 Load the dynamic object <tt>&lt;plugin&gt;</tt> into <tt>bugpoint</tt>
Brian Gaekeb9b3c332003-10-19 17:03:59 +0000[diff] [blame]212 itself. This object should register new
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]213 optimization passes. Once loaded, the object will add new command line
214 options to enable various optimizations. To see the new complete list
215 of optimizations, use the -help and -load options together:
216 <p>
John Criswellf9c78652004-01-26 21:26:54 +0000[diff] [blame]217 <tt>bugpoint -load &lt;plugin&gt; -help</tt>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]218 <p>
219
Chris Lattner5cd840c2003-10-18 20:54:37 +0000[diff] [blame]220 <a name="opt_output"><li><tt>-output &lt;filename&gt;</tt><br>
Brian Gaekeb9b3c332003-10-19 17:03:59 +0000[diff] [blame]221 Whenever the test program produces output on its standard output
222 stream, it should match the contents of <tt>&lt;filename&gt;</tt>
223 (the "reference output"). If you do not use this option,
224 <tt>bugpoint</tt> will attempt to generate a reference output by
225 compiling the program with the C backend and running it.<p>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]226
John Criswelld1799612004-03-29 20:23:11 +0000[diff] [blame]227 <li><tt>-profile-info-file &lt;filename&gt;</tt><br>
228 Profile file loaded by -profile-loader.<p>
229
Brian Gaeke28dbfce2003-10-19 17:35:35 +0000[diff] [blame]230 <a name="opt_run-"><li><tt>-run-{int,jit,llc,cbe}</tt><br>
Brian Gaekeb9b3c332003-10-19 17:03:59 +0000[diff] [blame]231 Whenever the test program is compiled, <tt>bugpoint</tt> should generate
232 code for it using the specified code generator. These options allow
233 you to choose the interpreter, the JIT compiler, the static native
234 code compiler, or the C backend, respectively.<p>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]235</ul>
236
237<h3>EXIT STATUS</h3>
238
239If <tt>bugpoint</tt> succeeds in finding a problem, it will exit with 0.
240Otherwise, if an error occurs, it will exit with a non-zero value.
241
242<h3>SEE ALSO</h3>
John Criswell589d91f2003-10-16 20:15:17 +0000[diff] [blame]243<a href="opt.html"><tt>opt</tt></a>,
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]244<a href="analyze.html"><tt>analyze</tt></a>
245
246<HR>
247Maintained by the <a href="http://llvm.cs.uiuc.edu">LLVM Team</a>.
248</body>
249</html>