=head1 SYNOPSIS
-bugpoint [options] [input LLVM ll/bc files] [LLVM passes] --args
-I<program arguments> ...
+B<bugpoint> [I<options>] [I<input LLVM ll/bc files>] [I<LLVM passes>] B<--args>
+I<program arguments>
=head1 DESCRIPTION
-The B<bugpoint> 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<gccas> 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<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 stupid things or miss obvious simplifications. B<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. Note
-that B<bugpoint> 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<bugpoint> 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<bugpoint> starts the crash debugger.
-
-Otherwise, if the B<-output> option was not specified, B<bugpoint> runs the test
-program with the C backend (which is assumed to generate good code) to generate
-a reference output. Once B<bugpoint> has a reference output for the test
-program, it tries executing it with the selected code generator. If the
-selected code generator crashes, B<bugpoint> starts the L</Crash debugger> 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</Code generator debugger>.
-
-Finally, if the output of the selected code generator matches the reference
-output, B<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 B<bugpoint> can debug.
-
-=head2 Crash debugger
-
-If an optimizer or code generator crashes, B<bugpoint> 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<bugpoint> figures out which combination of optimizer
-passes triggers the bug. This is useful when debugging a problem exposed by
-B<gccas>, for example, because it runs over 38 passes.
-
-Next, B<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, B<bugpoint>
-deletes any individual LLVM instructions whose absence does not eliminate the
-failure. At the end, B<bugpoint> should tell you what passes crash, give you a
-bytecode file, and give you instructions on how to reproduce the failure with
-B<opt>, B<analyze>, or B<llc>.
-
-=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<llc>). 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<bugpoint> 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<bugpoint> only
-works with programs that have deterministic output. Thus, if the program
-outputs C<argv[0]>, the date, time, or any other "random" data, B<bugpoint> 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<bugpoint> is extremely useful when working on a new optimization: it helps
-track down regressions quickly. To avoid having to relink B<bugpoint> every
-time you change your optimization, make B<bugpoint> dynamically load
-your optimization by using the B<-load> option.
-
-=item *
-
-B<bugpoint> 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<bugpoint>'s output in the file F<bugpoint.log>, as well as on
-your terminal.
-
-=item *
-
-B<bugpoint> cannot debug problems with the LLVM linker. If B<bugpoint> crashes
-before you see its C<All input ok> message, you might try running C<llvm-link
--v> 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<bugpoint> will be confused. One way to
-deal with this is to cause B<bugpoint> to ignore the exit code from your
-program, by giving it the B<-check-exit-code=false> option.
-
-=back
+B<bugpoint> 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 B<bugpoint>, as well as
+advice for using bugpoint, see F<llvm/docs/Bugpoint.html> in the LLVM
+distribution.
=head1 OPTIONS
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<--append-exit-code>=I<{true,false}>
+
+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.
+
=item B<--args> I<program args>
Pass all arguments specified after -args to the test program whenever it runs.
options starting with C<-> to be part of the B<--tool-args> option, not as
options to B<bugpoint> itself. (See B<--args>, above.)
-=item B<--check-exit-code>=I<{true,false}>
+=item B<--safe-tool-args> I<tool args>
+
+Pass all arguments specified after B<--safe-tool-args> to the "safe" execution
+tool.
+
+=item B<--gcc-tool-args> I<gcc tool args>
-Assume a non-zero exit code or core dump from the test program is a failure.
-Defaults to true.
+Pass all arguments specified after B<--gcc-tool-args> to the invocation of
+B<gcc>.
+
+=item B<--opt-args> I<opt args>
+
+Pass all arguments specified after B<--opt-args> to the invocation of B<opt>.
=item B<--disable-{dce,simplifycfg}>
reduce test programs. If you're trying to find a bug in one of these passes,
B<bugpoint> may crash.
-=item B<--help>
+=item B<--enable-valgrind>
+
+Use valgrind to find faults in the optimization phase. This will allow
+bugpoint to find otherwise asymptomatic problems caused by memory
+mis-management.
+
+=item B<-find-bugs>
+
+Continually randomize the specified passes and run them on the test program
+until a bug is found or the user kills B<bugpoint>.
+
+=item B<-help>
Print a summary of command line options.
Load the dynamic object F<plugin> into B<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 B<--help> and B<--load> options together; for example:
+optimizations, use the B<-help> and B<--load> options together; for example:
- bugpoint --load myNewPass.so --help
+ bugpoint --load myNewPass.so -help
+
+=item B<--mlimit> F<megabytes>
+
+Specifies an upper limit on memory usage of the optimization and codegen. Set
+to zero to disable the limit.
=item B<--output> F<filename>
Whenever the test program produces output on its standard output stream, it
should match the contents of F<filename> (the "reference output"). If you
do not use this option, B<bugpoint> will attempt to generate a reference output
-by compiling the program with the C backend and running it.
+by compiling the program with the "safe" backend and running it.
=item B<--profile-info-file> F<filename>
Profile file loaded by B<--profile-loader>.
-=item B<--run-{int,jit,llc,cbe}>
+=item B<--run-{int,jit,llc,cbe,custom}>
Whenever the test program is compiled, B<bugpoint> 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.
+interpreter, the JIT compiler, the static native code compiler, the C
+backend, or a custom command (see B<--exec-command>) respectively.
+
+=item B<--safe-{llc,cbe,custom}>
+
+When debugging a code generator, B<bugpoint> 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, the C backend, or a custom command,
+(see B<--exec-command>) respectively. The interpreter and the JIT backends
+cannot currently be used as the "safe" backends.
+
+=item B<--exec-command> I<command>
+
+This option defines the command to use with the B<--run-custom> and
+B<--safe-custom> options to execute the bitcode testcase. This can
+be useful for cross-compilation.
+
+=item B<--safe-path> I<path>
+
+This option defines the path to the command to execute with the
+B<--safe-{int,jit,llc,cbe,custom}>
+option.
=back
=head1 SEE ALSO
-L<opt>, L<analyze>
+L<opt|opt>
=head1 AUTHOR
-Maintained by the LLVM Team (L<http://llvm.cs.uiuc.edu>).
+Maintained by the LLVM Team (L<http://llvm.org>).
=cut
-
projects / oota-llvm.git / blobdiff