diff --git a/llvm/docs/CommandGuide/bugpoint.pod b/llvm/docs/CommandGuide/bugpoint.pod new file mode 100644 index 000000000000..d3102c7f406a --- /dev/null +++ b/llvm/docs/CommandGuide/bugpoint.pod @@ -0,0 +1,250 @@ +=pod + +=head1 NAME + +bugpoint - automatic test case reduction tool + +=head1 SYNOPSIS + +bugpoint [options] [input LLVM ll/bc files] [LLVM passes] --args +I ... + +=head1 DESCRIPTION + +The B tool 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 example, if B crashes while optimizing a file, it will +identify the optimization (or combination of optimizations) that causes the +crash, and reduce the file down to a small example which triggers the crash. + +=head2 Design Philosophy + +B 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 stupid things or miss obvious simplifications. B 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. Note +that B is generally very quick unless debugging a miscompilation where +each test of the program (which requires executing it) takes a long time. + +=head2 Automatic Debugger Selection + +B reads each F<.bc> or F<.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 (which +causes the verifier to abort), B starts the crash debugger. + +Otherwise, if the B<-output> option was not specified, B runs the test +program with the C backend (which is assumed to generate good code) to generate +a reference output. Once B has a reference output for the test +program, it tries executing it with the selected code generator. If the +selected code generator crashes, B starts the L on +the code generator. Otherwise, if the resulting output differs from the +reference output, it assumes the difference resulted from a code generator +failure, and starts the L. + +Finally, if the output of the selected code generator matches the reference +output, B 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 B can debug. + +=head2 Crash debugger + +If an optimizer or code generator crashes, B will try as hard as it +can to reduce the list of passes (for optimizer crashes) and the size of the +test program. First, B figures out which combination of optimizer +passes triggers the bug. This is useful when debugging a problem exposed by +B, for example, because it runs over 38 passes. + +Next, B 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, B +deletes any individual LLVM instructions whose absence does not eliminate the +failure. At the end, B should tell you what passes crash, give you a +bytecode file, and give you instructions on how to reproduce the failure with +B, B, or B. + +=head2 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 compiler (B). 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. + +=head2 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. + +=head2 Advice for using bugpoint + +B can be a remarkably useful tool, but it sometimes works in +non-obvious ways. Here are some hints and tips: + +=over + +=item * + +In the code generator and miscompilation debuggers, B only +works with programs that have deterministic output. Thus, if the program +outputs C, the date, time, or any other "random" data, B may +misinterpret differences in these data, when output, as the result of a +miscompilation. Programs should be temporarily modified to disable outputs that +are likely to vary from run to run. + +=item * + +In the code generator and miscompilation debuggers, debugging will go faster if +you manually modify the program or its inputs to reduce the runtime, but still +exhibit the problem. + +=item * + +B is extremely useful when working on a new optimization: it helps +track down regressions quickly. To avoid having to relink B every +time you change your optimization, make B dynamically load +your optimization by using the B<-load> option. + +=item * + +B can generate a lot of output and run for a long period of time. It +is often useful to capture the output of the program to file. For example, in +the C shell, you can type: + + bugpoint ... |& tee bugpoint.log + +to get a copy of B's output in the file F, as well as on +your terminal. + +=item * + +B cannot debug problems with the LLVM linker. If B crashes +before you see its C message, you might try running C on the same set of input files. If that also crashes, you may be +experiencing a linker bug. + +=item * + +If your program is supposed to crash, B will be confused. One way to +deal with this is to cause B to ignore the exit code from your +program, by giving it the B<-check-exit-code=false> option. + +=back + +=head1 OPTIONS + +=over + +=item B<--additional-so> F + +Load the dynamic shared object F 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. + +=item B<--args> I + +Pass all arguments specified after -args to the test program whenever it runs. +Note that if any of the I start with a '-', you should use: + + bugpoint [bugpoint args] --args -- [program args] + +The "--" right after the B<--args> option tells B to consider any +options starting with C<-> to be part of the B<--args> option, not as options to +B itself. + +=item B<--tool-args> I + +Pass all arguments specified after --tool-args to the LLVM tool under test +(B, B, etc.) whenever it runs. You should use this option in the +following way: + + bugpoint [bugpoint args] --tool-args -- [tool args] + +The "--" right after the B<--tool-args> option tells B to consider any +options starting with C<-> to be part of the B<--tool-args> option, not as +options to B itself. (See B<--args>, above.) + +=item B<--check-exit-code>=I<{true,false}> + +Assume a non-zero exit code or core dump from the test program is a failure. +Defaults to true. + +=item B<--disable-{dce,simplifycfg}> + +Do not run the specified passes to clean up and reduce the size of the test +program. By default, B uses these passes internally when attempting to +reduce test programs. If you're trying to find a bug in one of these passes, +B may crash. + +=item B<--help> + +Print a summary of command line options. + +=item B<--input> F + +Open F and redirect the standard input of the test program, whenever +it runs, to come from that file. + +=item B<--load> F + +Load the dynamic object F into B 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 B<--help> and B<--load> options together; for example: + + bugpoint --load myNewPass.so --help + +=item B<--output> F + +Whenever the test program produces output on its standard output stream, it +should match the contents of F (the "reference output"). If you +do not use this option, B will attempt to generate a reference output +by compiling the program with the C backend and running it. + +=item B<--profile-info-file> F + +Profile file loaded by B<--profile-loader>. + +=item B<--run-{int,jit,llc,cbe}> + +Whenever the test program is compiled, B 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 the C +backend, respectively. + +=back + +=head1 EXIT STATUS + +If B succeeds in finding a problem, it will exit with 0. Otherwise, +if an error occurs, it will exit with a non-zero value. + +=head1 SEE ALSO + +L, L + +=head1 AUTHOR + +Maintained by the LLVM Team (L). + +=cut +