1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>bugpoint - automatic test case reduction tool — LLVM 13 documentation</title>
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="llvm-extract - extract a function from an LLVM module" href="llvm-extract.html" />
<link rel="prev" title="llvm-strip - object stripping tool" href="llvm-strip.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head><body>
<div class="logo">
<a href="../index.html">
<img src="../_static/logo.png"
alt="LLVM Logo" width="250" height="88"/></a>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="llvm-extract.html" title="llvm-extract - extract a function from an LLVM module"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="llvm-strip.html" title="llvm-strip - object stripping tool"
accesskey="P">previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="../index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="../Reference.html" >Reference</a> »</li>
<li class="nav-item nav-item-2"><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
<li class="nav-item nav-item-this"><a href="">bugpoint - automatic test case reduction tool</a></li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3>Documentation</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/GettingStartedTutorials.html">Getting Started/Tutorials</a></li>
<li><a href="https://llvm.org/docs/UserGuides.html">User Guides</a></li>
<li><a href="https://llvm.org/docs/Reference.html">Reference</a></li>
</ul>
<h3>Getting Involved</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/Contributing.html">Contributing to LLVM</a></li>
<li><a href="https://llvm.org/docs/HowToSubmitABug.html">Submitting Bug Reports</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#mailing-lists">Mailing Lists</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#irc">IRC</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#meetups-and-social-events">Meetups and Social Events</a></li>
</ul>
<h3>Additional Links</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/FAQ.html">FAQ</a></li>
<li><a href="https://llvm.org/docs/Lexicon.html">Glossary</a></li>
<li><a href="https://llvm.org/pubs">Publications</a></li>
<li><a href="https://github.com/llvm/llvm-project//">Github Repository</a></li>
</ul>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/CommandGuide/bugpoint.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="bugpoint-automatic-test-case-reduction-tool">
<h1>bugpoint - automatic test case reduction tool<a class="headerlink" href="#bugpoint-automatic-test-case-reduction-tool" title="Permalink to this headline">¶</a></h1>
<div class="section" id="synopsis">
<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
<p><strong>bugpoint</strong> [<em>options</em>] [<em>input LLVM ll/bc files</em>] [<em>LLVM passes</em>] <strong>–args</strong>
<em>program arguments</em></p>
</div>
<div class="section" id="description">
<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p><strong>bugpoint</strong> 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 bad native code generation (including problems in the static
and JIT compilers). It aims to reduce large test cases to small, useful ones.
For more information on the design and inner workings of <strong>bugpoint</strong>, as well as
advice for using bugpoint, see <a class="reference internal" href="../Bugpoint.html"><span class="doc">LLVM bugpoint tool: design and usage</span></a> in the LLVM
distribution.</p>
</div>
<div class="section" id="options">
<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
<p><strong>–additional-so</strong> <em>library</em></p>
<blockquote>
<div><p>Load the dynamic shared object <em>library</em> into the test program whenever it is
run. This is useful if you are debugging programs which depend on non-LLVM
libraries (such as the X or curses libraries) to run.</p>
</div></blockquote>
<p><strong>–append-exit-code</strong>=<em>{true,false}</em></p>
<blockquote>
<div><p>Append the test programs exit code to the output file so that a change in exit
code is considered a test failure. Defaults to false.</p>
</div></blockquote>
<p><strong>–args</strong> <em>program args</em></p>
<blockquote>
<div><p>Pass all arguments specified after <strong>–args</strong> to the test program whenever it runs.
Note that if any of the <em>program args</em> start with a “<code class="docutils literal notranslate"><span class="pre">-</span></code>“, you should use:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>bugpoint <span class="o">[</span>bugpoint args<span class="o">]</span> --args -- <span class="o">[</span>program args<span class="o">]</span>
</pre></div>
</div>
<p>The “<code class="docutils literal notranslate"><span class="pre">--</span></code>” right after the <strong>–args</strong> option tells <strong>bugpoint</strong> to consider
any options starting with “<code class="docutils literal notranslate"><span class="pre">-</span></code>” to be part of the <strong>–args</strong> option, not as
options to <strong>bugpoint</strong> itself.</p>
</div></blockquote>
<p><strong>–tool-args</strong> <em>tool args</em></p>
<blockquote>
<div><p>Pass all arguments specified after <strong>–tool-args</strong> to the LLVM tool under test
(<strong>llc</strong>, <strong>lli</strong>, etc.) whenever it runs. You should use this option in the
following way:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>bugpoint <span class="o">[</span>bugpoint args<span class="o">]</span> --tool-args -- <span class="o">[</span>tool args<span class="o">]</span>
</pre></div>
</div>
<p>The “<code class="docutils literal notranslate"><span class="pre">--</span></code>” right after the <strong>–tool-args</strong> option tells <strong>bugpoint</strong> to
consider any options starting with “<code class="docutils literal notranslate"><span class="pre">-</span></code>” to be part of the <strong>–tool-args</strong>
option, not as options to <strong>bugpoint</strong> itself. (See <strong>–args</strong>, above.)</p>
</div></blockquote>
<p><strong>–safe-tool-args</strong> <em>tool args</em></p>
<blockquote>
<div><p>Pass all arguments specified after <strong>–safe-tool-args</strong> to the “safe” execution
tool.</p>
</div></blockquote>
<p><strong>–gcc-tool-args</strong> <em>gcc tool args</em></p>
<blockquote>
<div><p>Pass all arguments specified after <strong>–gcc-tool-args</strong> to the invocation of
<strong>gcc</strong>.</p>
</div></blockquote>
<p><strong>–opt-args</strong> <em>opt args</em></p>
<blockquote>
<div><p>Pass all arguments specified after <strong>–opt-args</strong> to the invocation of <strong>opt</strong>.</p>
</div></blockquote>
<p><strong>–disable-{dce,simplifycfg}</strong></p>
<blockquote>
<div><p>Do not run the specified passes to clean up and reduce the size of the test
program. By default, <strong>bugpoint</strong> uses these passes internally when attempting to
reduce test programs. If you’re trying to find a bug in one of these passes,
<strong>bugpoint</strong> may crash.</p>
</div></blockquote>
<p><strong>–enable-valgrind</strong></p>
<blockquote>
<div><p>Use valgrind to find faults in the optimization phase. This will allow
bugpoint to find otherwise asymptomatic problems caused by memory
mis-management.</p>
</div></blockquote>
<p><strong>-find-bugs</strong></p>
<blockquote>
<div><p>Continually randomize the specified passes and run them on the test program
until a bug is found or the user kills <strong>bugpoint</strong>.</p>
</div></blockquote>
<p><strong>-help</strong></p>
<blockquote>
<div><p>Print a summary of command line options.</p>
</div></blockquote>
<p><strong>–input</strong> <em>filename</em></p>
<blockquote>
<div><p>Open <em>filename</em> and redirect the standard input of the test program, whenever
it runs, to come from that file.</p>
</div></blockquote>
<p><strong>–load</strong> <em>plugin</em></p>
<blockquote>
<div><p>Load the dynamic object <em>plugin</em> into <strong>bugpoint</strong> itself. This object should
register new optimization passes. Once loaded, the object will add new command
line options to enable various optimizations. To see the new complete list of
optimizations, use the <strong>-help</strong> and <strong>–load</strong> options together; for example:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>bugpoint --load myNewPass.so -help
</pre></div>
</div>
</div></blockquote>
<p><strong>–mlimit</strong> <em>megabytes</em></p>
<blockquote>
<div><p>Specifies an upper limit on memory usage of the optimization and codegen. Set
to zero to disable the limit.</p>
</div></blockquote>
<p><strong>–output</strong> <em>filename</em></p>
<blockquote>
<div><p>Whenever the test program produces output on its standard output stream, it
should match the contents of <em>filename</em> (the “reference output”). If you
do not use this option, <strong>bugpoint</strong> will attempt to generate a reference output
by compiling the program with the “safe” backend and running it.</p>
</div></blockquote>
<p><strong>–run-{int,jit,llc,custom}</strong></p>
<blockquote>
<div><p>Whenever the test program is compiled, <strong>bugpoint</strong> should generate code for it
using the specified code generator. These options allow you to choose the
interpreter, the JIT compiler, the static native code compiler, or a
custom command (see <strong>–exec-command</strong>) respectively.</p>
</div></blockquote>
<p><strong>–safe-{llc,custom}</strong></p>
<blockquote>
<div><p>When debugging a code generator, <strong>bugpoint</strong> should use the specified code
generator as the “safe” code generator. This is a known-good code generator
used to generate the “reference output” if it has not been provided, and to
compile portions of the program that as they are excluded from the testcase.
These options allow you to choose the
static native code compiler, or a custom command, (see <strong>–exec-command</strong>)
respectively. The interpreter and the JIT backends cannot currently
be used as the “safe” backends.</p>
</div></blockquote>
<p><strong>–exec-command</strong> <em>command</em></p>
<blockquote>
<div><p>This option defines the command to use with the <strong>–run-custom</strong> and
<strong>–safe-custom</strong> options to execute the bitcode testcase. This can
be useful for cross-compilation.</p>
</div></blockquote>
<p><strong>–compile-command</strong> <em>command</em></p>
<blockquote>
<div><p>This option defines the command to use with the <strong>–compile-custom</strong>
option to compile the bitcode testcase. The command should exit with a
failure exit code if the file is “interesting” and should exit with a
success exit code (i.e. 0) otherwise (this is the same as if it crashed on
“interesting” inputs).</p>
<p>This can be useful for
testing compiler output without running any link or execute stages. To
generate a reduced unit test, you may add CHECK directives to the
testcase and pass the name of an executable compile-command script in this form:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/bin/sh</span>
llc <span class="s2">"</span><span class="nv">$@</span><span class="s2">"</span>
not FileCheck <span class="o">[</span>bugpoint input file<span class="o">]</span>.ll < bugpoint-test-program.s
</pre></div>
</div>
<p>This script will “fail” as long as FileCheck passes. So the result
will be the minimum bitcode that passes FileCheck.</p>
</div></blockquote>
<p><strong>–safe-path</strong> <em>path</em></p>
<blockquote>
<div><p>This option defines the path to the command to execute with the
<strong>–safe-{int,jit,llc,custom}</strong>
option.</p>
</div></blockquote>
<p><strong>–verbose-errors</strong>=<em>{true,false}</em></p>
<blockquote>
<div><p>The default behavior of bugpoint is to print “<crash>” when it finds a reduced
test that crashes compilation. This flag prints the output of the crashing
program to stderr. This is useful to make sure it is the same error being
tracked down and not a different error that happens to crash the compiler as
well. Defaults to false.</p>
</div></blockquote>
</div>
<div class="section" id="exit-status">
<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
<p>If <strong>bugpoint</strong> succeeds in finding a problem, it will exit with 0. Otherwise,
if an error occurs, it will exit with a non-zero value.</p>
</div>
<div class="section" id="see-also">
<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
<p><em class="manpage"><a class="manpage reference external" href="https://llvm.org/docs/CommandGuide/opt.html">opt(1)</a></em></p>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="llvm-extract.html" title="llvm-extract - extract a function from an LLVM module"
>next</a> |</li>
<li class="right" >
<a href="llvm-strip.html" title="llvm-strip - object stripping tool"
>previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="../index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="../Reference.html" >Reference</a> »</li>
<li class="nav-item nav-item-2"><a href="index.html" >LLVM Command Guide</a> »</li>
<li class="nav-item nav-item-this"><a href="">bugpoint - automatic test case reduction tool</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2003-2021, LLVM Project.
Last updated on 2021-09-18.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.5.4.
</div>
</body>
</html>
|
