| bugpoint - automatic test case reduction tool |
| ============================================= |
| |
| SYNOPSIS |
| -------- |
| |
| **bugpoint** [*options*] [*input LLVM ll/bc files*] [*LLVM passes*] **--args** |
| *program arguments* |
| |
| DESCRIPTION |
| ----------- |
| |
| **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 **bugpoint**, as well as |
| advice for using bugpoint, see :doc:`/Bugpoint` in the LLVM |
| distribution. |
| |
| OPTIONS |
| ------- |
| |
| **--additional-so** *library* |
| |
| Load the dynamic shared object *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. |
| |
| **--append-exit-code**\ =\ *{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. |
| |
| **--args** *program args* |
| |
| 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: |
| |
| .. code-block:: bash |
| |
| 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. |
| |
| **--tool-args** *tool args* |
| |
| Pass all arguments specified after **--tool-args** to the LLVM tool under test |
| (**llc**, **lli**, etc.) whenever it runs. You should use this option in the |
| following way: |
| |
| .. code-block:: bash |
| |
| bugpoint [bugpoint args] --tool-args -- [tool args] |
| |
| The "``--``" right after the **--tool-args** option tells **bugpoint** to |
| consider any options starting with "``-``" to be part of the **--tool-args** |
| option, not as options to **bugpoint** itself. (See **--args**, above.) |
| |
| **--safe-tool-args** *tool args* |
| |
| Pass all arguments specified after **--safe-tool-args** to the "safe" execution |
| tool. |
| |
| **--gcc-tool-args** *gcc tool args* |
| |
| Pass all arguments specified after **--gcc-tool-args** to the invocation of |
| **gcc**. |
| |
| **--opt-args** *opt args* |
| |
| Pass all arguments specified after **--opt-args** to the invocation of **opt**. |
| |
| **--disable-{dce,simplifycfg}** |
| |
| 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. |
| |
| **--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. |
| |
| **-find-bugs** |
| |
| Continually randomize the specified passes and run them on the test program |
| until a bug is found or the user kills **bugpoint**. |
| |
| **-help** |
| |
| Print a summary of command line options. |
| |
| **--input** *filename* |
| |
| Open *filename* and redirect the standard input of the test program, whenever |
| it runs, to come from that file. |
| |
| **--load** *plugin* |
| |
| 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; for example: |
| |
| |
| .. code-block:: bash |
| |
| bugpoint --load myNewPass.so -help |
| |
| **--mlimit** *megabytes* |
| |
| Specifies an upper limit on memory usage of the optimization and codegen. Set |
| to zero to disable the limit. |
| |
| **--output** *filename* |
| |
| Whenever the test program produces output on its standard output stream, it |
| should match the contents of *filename* (the "reference output"). If you |
| do not use this option, **bugpoint** will attempt to generate a reference output |
| by compiling the program with the "safe" backend and running it. |
| |
| **--run-{int,jit,llc,custom}** |
| |
| Whenever the test program is compiled, **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 a |
| custom command (see **--exec-command**) respectively. |
| |
| **--safe-{llc,custom}** |
| |
| When debugging a code generator, **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, or a custom command, (see **--exec-command**) |
| respectively. The interpreter and the JIT backends cannot currently |
| be used as the "safe" backends. |
| |
| **--exec-command** *command* |
| |
| This option defines the command to use with the **--run-custom** and |
| **--safe-custom** options to execute the bitcode testcase. This can |
| be useful for cross-compilation. |
| |
| **--compile-command** *command* |
| |
| This option defines the command to use with the **--compile-custom** |
| option to compile the bitcode testcase. The command should exit with a |
| failure exit code if the file is "interesting" and should exit with a |
| success exit code (i.e. 0) otherwise (this is the same as if it crashed on |
| "interesting" inputs). |
| |
| This can be useful for |
| testing compiler output without running any link or execute stages. To |
| generate a reduced unit test, you may add CHECK directives to the |
| testcase and pass the name of an executable compile-command script in this form: |
| |
| .. code-block:: sh |
| |
| #!/bin/sh |
| llc "$@" |
| not FileCheck [bugpoint input file].ll < bugpoint-test-program.s |
| |
| This script will "fail" as long as FileCheck passes. So the result |
| will be the minimum bitcode that passes FileCheck. |
| |
| **--safe-path** *path* |
| |
| This option defines the path to the command to execute with the |
| **--safe-{int,jit,llc,custom}** |
| option. |
| |
| **--verbose-errors**\ =\ *{true,false}* |
| |
| The default behavior of bugpoint is to print "<crash>" when it finds a reduced |
| test that crashes compilation. This flag prints the output of the crashing |
| program to stderr. This is useful to make sure it is the same error being |
| tracked down and not a different error that happens to crash the compiler as |
| well. Defaults to false. |
| |
| 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|opt |
