docs/CommandGuide/bugpoint.rst

   1 bugpoint - automatic test case reduction tool
   2 =============================================
   3
   4
   5 SYNOPSIS
   6 --------
   7
   8
   9 **bugpoint** [*options*] [*input LLVM ll/bc files*] [*LLVM passes*] **--args**
  10 *program arguments*
  11
  12
  13 DESCRIPTION
  14 -----------
  15
  16
  17 **bugpoint** narrows down the source of problems in LLVM tools and passes.  It
  18 can be used to debug three types of failures: optimizer crashes, miscompilations
  19 by optimizers, or bad native code generation (including problems in the static
  20 and JIT compilers).  It aims to reduce large test cases to small, useful ones.
  21 For more information on the design and inner workings of **bugpoint**, as well as
  22 advice for using bugpoint, see *llvm/docs/Bugpoint.html* in the LLVM
  23 distribution.
  24
  25
  26 OPTIONS
  27 -------
  28
  29
  30
  31 **--additional-so** *library*
  32
  33  Load the dynamic shared object *library* into the test program whenever it is
  34  run.  This is useful if you are debugging programs which depend on non-LLVM
  35  libraries (such as the X or curses libraries) to run.
  36
  37
  38
  39 **--append-exit-code**\ =\ *{true,false}*
  40
  41  Append the test programs exit code to the output file so that a change in exit
  42  code is considered a test failure. Defaults to false.
  43
  44
  45
  46 **--args** *program args*
  47
  48  Pass all arguments specified after -args to the test program whenever it runs.
  49  Note that if any of the *program args* start with a '-', you should use:
  50
  51
  52  .. code-block:: perl
  53
  54       bugpoint [bugpoint args] --args -- [program args]
  55
  56
  57  The "--" right after the **--args** option tells **bugpoint** to consider any
  58  options starting with ``-`` to be part of the **--args** option, not as options to
  59  **bugpoint** itself.
  60
  61
  62
  63 **--tool-args** *tool args*
  64
  65  Pass all arguments specified after --tool-args to the LLVM tool under test
  66  (**llc**, **lli**, etc.) whenever it runs.  You should use this option in the
  67  following way:
  68
  69
  70  .. code-block:: perl
  71
  72       bugpoint [bugpoint args] --tool-args -- [tool args]
  73
  74
  75  The "--" right after the **--tool-args** option tells **bugpoint** to consider any
  76  options starting with ``-`` to be part of the **--tool-args** option, not as
  77  options to **bugpoint** itself. (See **--args**, above.)
  78
  79
  80
  81 **--safe-tool-args** *tool args*
  82
  83  Pass all arguments specified after **--safe-tool-args** to the "safe" execution
  84  tool.
  85
  86
  87
  88 **--gcc-tool-args** *gcc tool args*
  89
  90  Pass all arguments specified after **--gcc-tool-args** to the invocation of
  91  **gcc**.
  92
  93
  94
  95 **--opt-args** *opt args*
  96
  97  Pass all arguments specified after **--opt-args** to the invocation of **opt**.
  98
  99
 100
 101 **--disable-{dce,simplifycfg}**
 102
 103  Do not run the specified passes to clean up and reduce the size of the test
 104  program. By default, **bugpoint** uses these passes internally when attempting to
 105  reduce test programs.  If you're trying to find a bug in one of these passes,
 106  **bugpoint** may crash.
 107
 108
 109
 110 **--enable-valgrind**
 111
 112  Use valgrind to find faults in the optimization phase. This will allow
 113  bugpoint to find otherwise asymptomatic problems caused by memory
 114  mis-management.
 115
 116
 117
 118 **-find-bugs**
 119
 120  Continually randomize the specified passes and run them on the test program
 121  until a bug is found or the user kills **bugpoint**.
 122
 123
 124
 125 **-help**
 126
 127  Print a summary of command line options.
 128
 129
 130
 131 **--input** *filename*
 132
 133  Open *filename* and redirect the standard input of the test program, whenever
 134  it runs, to come from that file.
 135
 136
 137
 138 **--load** *plugin*
 139
 140  Load the dynamic object *plugin* into **bugpoint** itself.  This object should
 141  register new optimization passes.  Once loaded, the object will add new command
 142  line options to enable various optimizations.  To see the new complete list of
 143  optimizations, use the **-help** and **--load** options together; for example:
 144
 145
 146  .. code-block:: perl
 147
 148       bugpoint --load myNewPass.so -help
 149
 150
 151
 152
 153 **--mlimit** *megabytes*
 154
 155  Specifies an upper limit on memory usage of the optimization and codegen. Set
 156  to zero to disable the limit.
 157
 158
 159
 160 **--output** *filename*
 161
 162  Whenever the test program produces output on its standard output stream, it
 163  should match the contents of *filename* (the "reference output"). If you
 164  do not use this option, **bugpoint** will attempt to generate a reference output
 165  by compiling the program with the "safe" backend and running it.
 166
 167
 168
 169 **--profile-info-file** *filename*
 170
 171  Profile file loaded by **--profile-loader**.
 172
 173
 174
 175 **--run-{int,jit,llc,custom}**
 176
 177  Whenever the test program is compiled, **bugpoint** should generate code for it
 178  using the specified code generator.  These options allow you to choose the
 179  interpreter, the JIT compiler, the static native code compiler, or a
 180  custom command (see **--exec-command**) respectively.
 181
 182
 183
 184 **--safe-{llc,custom}**
 185
 186  When debugging a code generator, **bugpoint** should use the specified code
 187  generator as the "safe" code generator. This is a known-good code generator
 188  used to generate the "reference output" if it has not been provided, and to
 189  compile portions of the program that as they are excluded from the testcase.
 190  These options allow you to choose the
 191  static native code compiler, or a custom command, (see **--exec-command**)
 192  respectively. The interpreter and the JIT backends cannot currently
 193  be used as the "safe" backends.
 194
 195
 196
 197 **--exec-command** *command*
 198
 199  This option defines the command to use with the **--run-custom** and
 200  **--safe-custom** options to execute the bitcode testcase. This can
 201  be useful for cross-compilation.
 202
 203
 204
 205 **--compile-command** *command*
 206
 207  This option defines the command to use with the **--compile-custom**
 208  option to compile the bitcode testcase. This can be useful for
 209  testing compiler output without running any link or execute stages. To
 210  generate a reduced unit test, you may add CHECK directives to the
 211  testcase and pass the name of an executable compile-command script in this form:
 212
 213
 214  .. code-block:: sh
 215
 216       #!/bin/sh
 217       llc "$@"
 218       not FileCheck [bugpoint input file].ll < bugpoint-test-program.s
 219
 220
 221  This script will "fail" as long as FileCheck passes. So the result
 222  will be the minimum bitcode that passes FileCheck.
 223
 224
 225
 226 **--safe-path** *path*
 227
 228  This option defines the path to the command to execute with the
 229  **--safe-{int,jit,llc,custom}**
 230  option.
 231
 232
 233
 234
 235 EXIT STATUS
 236 -----------
 237
 238
 239 If **bugpoint** succeeds in finding a problem, it will exit with 0.  Otherwise,
 240 if an error occurs, it will exit with a non-zero value.
 241
 242
 243 SEE ALSO
 244 --------
 245
 246
 247 opt|opt