]> git.proxmox.com Git - rustc.git/blob - src/llvm/docs/CommandGuide/bugpoint.rst
Imported Upstream version 1.0.0+dfsg1
[rustc.git] / src / llvm / docs / CommandGuide / bugpoint.rst
1 bugpoint - automatic test case reduction tool
2 =============================================
3
4 SYNOPSIS
5 --------
6
7 **bugpoint** [*options*] [*input LLVM ll/bc files*] [*LLVM passes*] **--args**
8 *program arguments*
9
10 DESCRIPTION
11 -----------
12
13 **bugpoint** narrows down the source of problems in LLVM tools and passes. It
14 can be used to debug three types of failures: optimizer crashes, miscompilations
15 by optimizers, or bad native code generation (including problems in the static
16 and JIT compilers). It aims to reduce large test cases to small, useful ones.
17 For more information on the design and inner workings of **bugpoint**, as well as
18 advice for using bugpoint, see *llvm/docs/Bugpoint.html* in the LLVM
19 distribution.
20
21 OPTIONS
22 -------
23
24 **--additional-so** *library*
25
26 Load the dynamic shared object *library* into the test program whenever it is
27 run. This is useful if you are debugging programs which depend on non-LLVM
28 libraries (such as the X or curses libraries) to run.
29
30 **--append-exit-code**\ =\ *{true,false}*
31
32 Append the test programs exit code to the output file so that a change in exit
33 code is considered a test failure. Defaults to false.
34
35 **--args** *program args*
36
37 Pass all arguments specified after **--args** to the test program whenever it runs.
38 Note that if any of the *program args* start with a "``-``", you should use:
39
40 .. code-block:: bash
41
42 bugpoint [bugpoint args] --args -- [program args]
43
44 The "``--``" right after the **--args** option tells **bugpoint** to consider
45 any options starting with "``-``" to be part of the **--args** option, not as
46 options to **bugpoint** itself.
47
48 **--tool-args** *tool args*
49
50 Pass all arguments specified after **--tool-args** to the LLVM tool under test
51 (**llc**, **lli**, etc.) whenever it runs. You should use this option in the
52 following way:
53
54 .. code-block:: bash
55
56 bugpoint [bugpoint args] --tool-args -- [tool args]
57
58 The "``--``" right after the **--tool-args** option tells **bugpoint** to
59 consider any options starting with "``-``" to be part of the **--tool-args**
60 option, not as options to **bugpoint** itself. (See **--args**, above.)
61
62 **--safe-tool-args** *tool args*
63
64 Pass all arguments specified after **--safe-tool-args** to the "safe" execution
65 tool.
66
67 **--gcc-tool-args** *gcc tool args*
68
69 Pass all arguments specified after **--gcc-tool-args** to the invocation of
70 **gcc**.
71
72 **--opt-args** *opt args*
73
74 Pass all arguments specified after **--opt-args** to the invocation of **opt**.
75
76 **--disable-{dce,simplifycfg}**
77
78 Do not run the specified passes to clean up and reduce the size of the test
79 program. By default, **bugpoint** uses these passes internally when attempting to
80 reduce test programs. If you're trying to find a bug in one of these passes,
81 **bugpoint** may crash.
82
83 **--enable-valgrind**
84
85 Use valgrind to find faults in the optimization phase. This will allow
86 bugpoint to find otherwise asymptomatic problems caused by memory
87 mis-management.
88
89 **-find-bugs**
90
91 Continually randomize the specified passes and run them on the test program
92 until a bug is found or the user kills **bugpoint**.
93
94 **-help**
95
96 Print a summary of command line options.
97
98 **--input** *filename*
99
100 Open *filename* and redirect the standard input of the test program, whenever
101 it runs, to come from that file.
102
103 **--load** *plugin*
104
105 Load the dynamic object *plugin* into **bugpoint** itself. This object should
106 register new optimization passes. Once loaded, the object will add new command
107 line options to enable various optimizations. To see the new complete list of
108 optimizations, use the **-help** and **--load** options together; for example:
109
110
111 .. code-block:: bash
112
113 bugpoint --load myNewPass.so -help
114
115 **--mlimit** *megabytes*
116
117 Specifies an upper limit on memory usage of the optimization and codegen. Set
118 to zero to disable the limit.
119
120 **--output** *filename*
121
122 Whenever the test program produces output on its standard output stream, it
123 should match the contents of *filename* (the "reference output"). If you
124 do not use this option, **bugpoint** will attempt to generate a reference output
125 by compiling the program with the "safe" backend and running it.
126
127 **--run-{int,jit,llc,custom}**
128
129 Whenever the test program is compiled, **bugpoint** should generate code for it
130 using the specified code generator. These options allow you to choose the
131 interpreter, the JIT compiler, the static native code compiler, or a
132 custom command (see **--exec-command**) respectively.
133
134 **--safe-{llc,custom}**
135
136 When debugging a code generator, **bugpoint** should use the specified code
137 generator as the "safe" code generator. This is a known-good code generator
138 used to generate the "reference output" if it has not been provided, and to
139 compile portions of the program that as they are excluded from the testcase.
140 These options allow you to choose the
141 static native code compiler, or a custom command, (see **--exec-command**)
142 respectively. The interpreter and the JIT backends cannot currently
143 be used as the "safe" backends.
144
145 **--exec-command** *command*
146
147 This option defines the command to use with the **--run-custom** and
148 **--safe-custom** options to execute the bitcode testcase. This can
149 be useful for cross-compilation.
150
151 **--compile-command** *command*
152
153 This option defines the command to use with the **--compile-custom**
154 option to compile the bitcode testcase. This can be useful for
155 testing compiler output without running any link or execute stages. To
156 generate a reduced unit test, you may add CHECK directives to the
157 testcase and pass the name of an executable compile-command script in this form:
158
159 .. code-block:: sh
160
161 #!/bin/sh
162 llc "$@"
163 not FileCheck [bugpoint input file].ll < bugpoint-test-program.s
164
165 This script will "fail" as long as FileCheck passes. So the result
166 will be the minimum bitcode that passes FileCheck.
167
168 **--safe-path** *path*
169
170 This option defines the path to the command to execute with the
171 **--safe-{int,jit,llc,custom}**
172 option.
173
174 EXIT STATUS
175 -----------
176
177 If **bugpoint** succeeds in finding a problem, it will exit with 0. Otherwise,
178 if an error occurs, it will exit with a non-zero value.
179
180 SEE ALSO
181 --------
182
183 opt|opt