Otherwise, if the -output option was not
specified, bugpoint runs the test program with the C backend (which
is assumed to generate good code) to generate a reference output. Once
bugpoint has a reference output for the test program, it tries
executing it
with the selected code generator. If
the resulting output differs from the reference output, it assumes the
difference resulted from a code generator failure, and starts the
code generator debugger.
Otherwise, bugpoint runs the test program after all of the LLVM passes
have been applied to it. If its output differs from the reference output,
it assumes the difference resulted from a failure in one of the LLVM passes,
and enters the
miscompilation debugger. Otherwise,
there is no problem bugpoint can debug.
Next, bugpoint tries removing functions from the test program, to
reduce its
size. Usually it is able to reduce a test program
to a single function, when debugging intraprocedural optimizations. Once the
number of
functions has been reduced, it attempts to delete various edges in the control
flow graph, to reduce the size of the function as much as possible. Finally,
bugpoint deletes any individual LLVM instructions whose absence does
not eliminate the failure. At the end, bugpoint should tell you what
passes crash, give you a bytecode file, and give you instructions on how to
reproduce the failure with opt or
analyze.
If you are using the code generator debugger and get an error message that
says "UNSUPPORTED: external function used as a global initializer!", try using
the -run-llc option instead of the -run-jit option. This is
due to an unimplemented feature in the code generator debugger.
bugpoint <bugpoint args> -args -- <program args>
The "--" right after the -args option tells
bugpoint to consider any options starting with - to be
part of the -args option, not as options to bugpoint
itself.
bugpoint -load <plugin> -help
Design Philosophy
bugpoint is designed to be a useful tool without requiring any
hooks into the LLVM infrastructure at all. It works with any and all LLVM
passes and code generators, and does not need to "know" how they work. Because
of this, it may appear to do a lot of stupid things or miss obvious
simplifications. bugpoint is also designed to trade off programmer
time for computer time in the compiler-debugging process; consequently, it may
take a long period of (unattended) time to reduce a test case, but we feel it
is still worth it. :-) Automatic Debugger Selection
bugpoint reads each .bc or .ll file
specified on the command line and links them together into a single module,
called the test program. If any LLVM passes are
specified on the command line, it runs these passes on the test program. If
any of the passes crash, or if they produce malformed output,
bugpoint starts the crash debugger.Crash debugger
If an optimizer crashes, bugpoint will try as hard as it can to
reduce the list of passes and the size of the test program. First,
bugpoint figures out which combination of passes triggers the bug. This
is useful when debugging a problem exposed by gccas, for example,
because it runs over 25 optimizations.Code generator debugger
The code generator debugger attempts to narrow down the amount of code that is
being miscompiled by the selected code generator. To do
this, it takes the test program and partitions it into two pieces: one piece
which it compiles with the C backend (into a shared object), and one piece which
it runs with either the JIT or the static LLC compiler. It uses several
techniques to reduce the amount of code pushed through the LLVM code generator,
to reduce the potential scope of the problem. After it is finished, it emits
two bytecode files (called "test" [to be compiled with the code generator] and
"safe" [to be compiled with the C backend] respectively), and instructions for
reproducing the problem. The code generator debugger assumes that the C
backend produces good code.Miscompilation debugger
The miscompilation debugger works similarly to the code generator
debugger. It works by splitting the test program into two pieces, running the
optimizations specified on one piece, linking the two pieces back together,
and then executing the result.
It attempts to narrow down the list of passes to the one (or few) which are
causing the miscompilation, then reduce the portion of the test program which is
being miscompiled. The miscompilation debugger assumes that the selected
code generator is working properly.Advice for using bugpoint
bugpoint can be a remarkably useful tool, but it sometimes works in
non-obvious ways. Here are some hints and tips:
bugpoint ..... |& tee bugpoint.log
to get a copy of bugpoint's output in the file
bugpoint.log, as well as on your terminal.
OPTIONS
Load <library> 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.
Pass all arguments specified after -args to the
test program whenever it runs. Note that if any of
the <program args> start with a '-', you should use:
Do not run the specified passes to clean up and reduce the size of the
test program. By default, bugpoint uses these passes internally
when attempting to reduce test programs. If you're trying to find
a bug in one of these passes, bugpoint may crash.
Print a summary of command line options.
Open <filename> and redirect the standard input of the
test program, whenever it runs, to come from that file.
Load the dynamic object <plugin> into bugpoint
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 -help and -load options together:
EXIT STATUS
If bugpoint succeeds in finding a problem, it will exit with 0.
Otherwise, if an error occurs, it will exit with a non-zero value.
SEE ALSO
opt,
analyze
Maintained by the LLVM Team.