]>
Commit | Line | Data |
---|---|---|
223e47cc LB |
1 | bugpoint - automatic test case reduction tool |
2 | ============================================= | |
3 | ||
223e47cc LB |
4 | SYNOPSIS |
5 | -------- | |
6 | ||
223e47cc LB |
7 | **bugpoint** [*options*] [*input LLVM ll/bc files*] [*LLVM passes*] **--args** |
8 | *program arguments* | |
9 | ||
223e47cc LB |
10 | DESCRIPTION |
11 | ----------- | |
12 | ||
223e47cc LB |
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 | ||
223e47cc LB |
21 | OPTIONS |
22 | ------- | |
23 | ||
223e47cc LB |
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 | ||
223e47cc LB |
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 | ||
223e47cc LB |
35 | **--args** *program args* |
36 | ||
970d7e83 LB |
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: | |
223e47cc | 39 | |
970d7e83 | 40 | .. code-block:: bash |
223e47cc LB |
41 | |
42 | bugpoint [bugpoint args] --args -- [program args] | |
43 | ||
970d7e83 LB |
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. | |
223e47cc LB |
47 | |
48 | **--tool-args** *tool args* | |
49 | ||
970d7e83 | 50 | Pass all arguments specified after **--tool-args** to the LLVM tool under test |
223e47cc LB |
51 | (**llc**, **lli**, etc.) whenever it runs. You should use this option in the |
52 | following way: | |
53 | ||
970d7e83 | 54 | .. code-block:: bash |
223e47cc LB |
55 | |
56 | bugpoint [bugpoint args] --tool-args -- [tool args] | |
57 | ||
970d7e83 LB |
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.) | |
223e47cc LB |
61 | |
62 | **--safe-tool-args** *tool args* | |
63 | ||
64 | Pass all arguments specified after **--safe-tool-args** to the "safe" execution | |
65 | tool. | |
66 | ||
223e47cc LB |
67 | **--gcc-tool-args** *gcc tool args* |
68 | ||
69 | Pass all arguments specified after **--gcc-tool-args** to the invocation of | |
70 | **gcc**. | |
71 | ||
223e47cc LB |
72 | **--opt-args** *opt args* |
73 | ||
74 | Pass all arguments specified after **--opt-args** to the invocation of **opt**. | |
75 | ||
223e47cc LB |
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 | ||
223e47cc LB |
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 | ||
223e47cc LB |
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 | ||
223e47cc LB |
94 | **-help** |
95 | ||
96 | Print a summary of command line options. | |
97 | ||
223e47cc LB |
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 | ||
223e47cc LB |
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 | ||
970d7e83 | 111 | .. code-block:: bash |
223e47cc LB |
112 | |
113 | bugpoint --load myNewPass.so -help | |
114 | ||
223e47cc LB |
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 | ||
223e47cc LB |
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 | ||
223e47cc LB |
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 | ||
223e47cc LB |
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 | ||
223e47cc LB |
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 | ||
223e47cc LB |
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 | ||
223e47cc LB |
159 | .. code-block:: sh |
160 | ||
161 | #!/bin/sh | |
162 | llc "$@" | |
163 | not FileCheck [bugpoint input file].ll < bugpoint-test-program.s | |
164 | ||
223e47cc LB |
165 | This script will "fail" as long as FileCheck passes. So the result |
166 | will be the minimum bitcode that passes FileCheck. | |
167 | ||
223e47cc LB |
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 | ||
223e47cc LB |
174 | EXIT STATUS |
175 | ----------- | |
176 | ||
223e47cc LB |
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 | ||
223e47cc LB |
180 | SEE ALSO |
181 | -------- | |
182 | ||
223e47cc | 183 | opt|opt |