usr.bin/clang/bugpoint/bugpoint.1

   1 .\" $FreeBSD$
   2 .\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
   3 .\"
   4 .\" Standard preamble:
   5 .\" ========================================================================
   6 .de Sp \" Vertical space (when we can't use .PP)
   7 .if t .sp .5v
   8 .if n .sp
   9 ..
  10 .de Vb \" Begin verbatim text
  11 .ft CW
  12 .nf
  13 .ne \\$1
  14 ..
  15 .de Ve \" End verbatim text
  16 .ft R
  17 .fi
  18 ..
  19 .\" Set up some character translations and predefined strings.  \*(-- will
  20 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  21 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  22 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  23 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  24 .\" nothing in troff, for use with C<>.
  25 .tr \(*W-
  26 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  27 .ie n \{\
  28 .    ds -- \(*W-
  29 .    ds PI pi
  30 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  31 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  32 .    ds L" ""
  33 .    ds R" ""
  34 .    ds C` ""
  35 .    ds C' ""
  36 'br\}
  37 .el\{\
  38 .    ds -- \|\(em\|
  39 .    ds PI \(*p
  40 .    ds L" ``
  41 .    ds R" ''
  42 'br\}
  43 .\"
  44 .\" Escape single quotes in literal strings from groff's Unicode transform.
  45 .ie \n(.g .ds Aq \(aq
  46 .el       .ds Aq '
  47 .\"
  48 .\" If the F register is turned on, we'll generate index entries on stderr for
  49 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  50 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  51 .\" output yourself in some meaningful fashion.
  52 .ie \nF \{\
  53 .    de IX
  54 .    tm Index:\\$1\t\\n%\t"\\$2"
  55 ..
  56 .    nr % 0
  57 .    rr F
  58 .\}
  59 .el \{\
  60 .    de IX
  61 ..
  62 .\}
  63 .\"
  64 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  65 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  66 .    \" fudge factors for nroff and troff
  67 .if n \{\
  68 .    ds #H 0
  69 .    ds #V .8m
  70 .    ds #F .3m
  71 .    ds #[ \f1
  72 .    ds #] \fP
  73 .\}
  74 .if t \{\
  75 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  76 .    ds #V .6m
  77 .    ds #F 0
  78 .    ds #[ \&
  79 .    ds #] \&
  80 .\}
  81 .    \" simple accents for nroff and troff
  82 .if n \{\
  83 .    ds ' \&
  84 .    ds ` \&
  85 .    ds ^ \&
  86 .    ds , \&
  87 .    ds ~ ~
  88 .    ds /
  89 .\}
  90 .if t \{\
  91 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  92 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  93 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  94 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  95 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  96 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  97 .\}
  98 .    \" troff and (daisy-wheel) nroff accents
  99 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 100 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 101 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 102 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 103 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 104 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 105 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 106 .ds ae a\h'-(\w'a'u*4/10)'e
 107 .ds Ae A\h'-(\w'A'u*4/10)'E
 108 .    \" corrections for vroff
 109 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 110 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 111 .    \" for low resolution devices (crt and lpr)
 112 .if \n(.H>23 .if \n(.V>19 \
 113 \{\
 114 .    ds : e
 115 .    ds 8 ss
 116 .    ds o a
 117 .    ds d- d\h'-1'\(ga
 118 .    ds D- D\h'-1'\(hy
 119 .    ds th \o'bp'
 120 .    ds Th \o'LP'
 121 .    ds ae ae
 122 .    ds Ae AE
 123 .\}
 124 .rm #[ #] #H #V #F C
 125 .\" ========================================================================
 126 .\"
 127 .IX Title "BUGPOINT 1"
 128 .TH BUGPOINT 1 "2012-04-05" "LLVM 3.1" "LLVM Command Guide"
 129 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 130 .\" way too many mistakes in technical documents.
 131 .if n .ad l
 132 .nh
 133 .SH "NAME"
 134 bugpoint \- automatic test case reduction tool
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 \&\fBbugpoint\fR [\fIoptions\fR] [\fIinput \s-1LLVM\s0 ll/bc files\fR] [\fI\s-1LLVM\s0 passes\fR] \fB\-\-args\fR
 138 \&\fIprogram arguments\fR
 139 .SH "DESCRIPTION"
 140 .IX Header "DESCRIPTION"
 141 \&\fBbugpoint\fR narrows down the source of problems in \s-1LLVM\s0 tools and passes.  It
 142 can be used to debug three types of failures: optimizer crashes, miscompilations
 143 by optimizers, or bad native code generation (including problems in the static
 144 and \s-1JIT\s0 compilers).  It aims to reduce large test cases to small, useful ones.
 145 For more information on the design and inner workings of \fBbugpoint\fR, as well as
 146 advice for using bugpoint, see \fIllvm/docs/Bugpoint.html\fR in the \s-1LLVM\s0
 147 distribution.
 148 .SH "OPTIONS"
 149 .IX Header "OPTIONS"
 150 .IP "\fB\-\-additional\-so\fR \fIlibrary\fR" 4
 151 .IX Item "--additional-so library"
 152 Load the dynamic shared object \fIlibrary\fR into the test program whenever it is
 153 run.  This is useful if you are debugging programs which depend on non-LLVM
 154 libraries (such as the X or curses libraries) to run.
 155 .IP "\fB\-\-append\-exit\-code\fR=\fI{true,false}\fR" 4
 156 .IX Item "--append-exit-code={true,false}"
 157 Append the test programs exit code to the output file so that a change in exit
 158 code is considered a test failure. Defaults to false.
 159 .IP "\fB\-\-args\fR \fIprogram args\fR" 4
 160 .IX Item "--args program args"
 161 Pass all arguments specified after \-args to the test program whenever it runs.
 162 Note that if any of the \fIprogram args\fR start with a '\-', you should use:
 163 .Sp
 164 .Vb 1
 165 \&    bugpoint [bugpoint args] \-\-args \-\- [program args]
 166 .Ve
 167 .Sp
 168 The \*(L"\-\-\*(R" right after the \fB\-\-args\fR option tells \fBbugpoint\fR to consider any
 169 options starting with \f(CW\*(C`\-\*(C'\fR to be part of the \fB\-\-args\fR option, not as options to
 170 \&\fBbugpoint\fR itself.
 171 .IP "\fB\-\-tool\-args\fR \fItool args\fR" 4
 172 .IX Item "--tool-args tool args"
 173 Pass all arguments specified after \-\-tool\-args to the \s-1LLVM\s0 tool under test
 174 (\fBllc\fR, \fBlli\fR, etc.) whenever it runs.  You should use this option in the
 175 following way:
 176 .Sp
 177 .Vb 1
 178 \&    bugpoint [bugpoint args] \-\-tool\-args \-\- [tool args]
 179 .Ve
 180 .Sp
 181 The \*(L"\-\-\*(R" right after the \fB\-\-tool\-args\fR option tells \fBbugpoint\fR to consider any
 182 options starting with \f(CW\*(C`\-\*(C'\fR to be part of the \fB\-\-tool\-args\fR option, not as
 183 options to \fBbugpoint\fR itself. (See \fB\-\-args\fR, above.)
 184 .IP "\fB\-\-safe\-tool\-args\fR \fItool args\fR" 4
 185 .IX Item "--safe-tool-args tool args"
 186 Pass all arguments specified after \fB\-\-safe\-tool\-args\fR to the \*(L"safe\*(R" execution
 187 tool.
 188 .IP "\fB\-\-gcc\-tool\-args\fR \fIgcc tool args\fR" 4
 189 .IX Item "--gcc-tool-args gcc tool args"
 190 Pass all arguments specified after \fB\-\-gcc\-tool\-args\fR to the invocation of
 191 \&\fBgcc\fR.
 192 .IP "\fB\-\-opt\-args\fR \fIopt args\fR" 4
 193 .IX Item "--opt-args opt args"
 194 Pass all arguments specified after \fB\-\-opt\-args\fR to the invocation of \fBopt\fR.
 195 .IP "\fB\-\-disable\-{dce,simplifycfg}\fR" 4
 196 .IX Item "--disable-{dce,simplifycfg}"
 197 Do not run the specified passes to clean up and reduce the size of the test
 198 program. By default, \fBbugpoint\fR uses these passes internally when attempting to
 199 reduce test programs.  If you're trying to find a bug in one of these passes,
 200 \&\fBbugpoint\fR may crash.
 201 .IP "\fB\-\-enable\-valgrind\fR" 4
 202 .IX Item "--enable-valgrind"
 203 Use valgrind to find faults in the optimization phase. This will allow
 204 bugpoint to find otherwise asymptomatic problems caused by memory
 205 mis-management.
 206 .IP "\fB\-find\-bugs\fR" 4
 207 .IX Item "-find-bugs"
 208 Continually randomize the specified passes and run them on the test program
 209 until a bug is found or the user kills \fBbugpoint\fR.
 210 .IP "\fB\-help\fR" 4
 211 .IX Item "-help"
 212 Print a summary of command line options.
 213 .IP "\fB\-\-input\fR \fIfilename\fR" 4
 214 .IX Item "--input filename"
 215 Open \fIfilename\fR and redirect the standard input of the test program, whenever
 216 it runs, to come from that file.
 217 .IP "\fB\-\-load\fR \fIplugin\fR" 4
 218 .IX Item "--load plugin"
 219 Load the dynamic object \fIplugin\fR into \fBbugpoint\fR itself.  This object should
 220 register new optimization passes.  Once loaded, the object will add new command
 221 line options to enable various optimizations.  To see the new complete list of
 222 optimizations, use the \fB\-help\fR and \fB\-\-load\fR options together; for example:
 223 .Sp
 224 .Vb 1
 225 \&    bugpoint \-\-load myNewPass.so \-help
 226 .Ve
 227 .IP "\fB\-\-mlimit\fR \fImegabytes\fR" 4
 228 .IX Item "--mlimit megabytes"
 229 Specifies an upper limit on memory usage of the optimization and codegen. Set
 230 to zero to disable the limit.
 231 .IP "\fB\-\-output\fR \fIfilename\fR" 4
 232 .IX Item "--output filename"
 233 Whenever the test program produces output on its standard output stream, it
 234 should match the contents of \fIfilename\fR (the \*(L"reference output\*(R"). If you
 235 do not use this option, \fBbugpoint\fR will attempt to generate a reference output
 236 by compiling the program with the \*(L"safe\*(R" backend and running it.
 237 .IP "\fB\-\-profile\-info\-file\fR \fIfilename\fR" 4
 238 .IX Item "--profile-info-file filename"
 239 Profile file loaded by \fB\-\-profile\-loader\fR.
 240 .IP "\fB\-\-run\-{int,jit,llc,cbe,custom}\fR" 4
 241 .IX Item "--run-{int,jit,llc,cbe,custom}"
 242 Whenever the test program is compiled, \fBbugpoint\fR should generate code for it
 243 using the specified code generator.  These options allow you to choose the
 244 interpreter, the \s-1JIT\s0 compiler, the static native code compiler, the C
 245 backend, or a custom command (see \fB\-\-exec\-command\fR) respectively.
 246 .IP "\fB\-\-safe\-{llc,cbe,custom}\fR" 4
 247 .IX Item "--safe-{llc,cbe,custom}"
 248 When debugging a code generator, \fBbugpoint\fR should use the specified code
 249 generator as the \*(L"safe\*(R" code generator. This is a known-good code generator
 250 used to generate the \*(L"reference output\*(R" if it has not been provided, and to
 251 compile portions of the program that as they are excluded from the testcase.
 252 These options allow you to choose the
 253 static native code compiler, the C backend, or a custom command,
 254 (see \fB\-\-exec\-command\fR) respectively. The interpreter and the \s-1JIT\s0 backends
 255 cannot currently be used as the \*(L"safe\*(R" backends.
 256 .IP "\fB\-\-exec\-command\fR \fIcommand\fR" 4
 257 .IX Item "--exec-command command"
 258 This option defines the command to use with the \fB\-\-run\-custom\fR and
 259 \&\fB\-\-safe\-custom\fR options to execute the bitcode testcase. This can
 260 be useful for cross-compilation.
 261 .IP "\fB\-\-compile\-command\fR \fIcommand\fR" 4
 262 .IX Item "--compile-command command"
 263 This option defines the command to use with the \fB\-\-compile\-custom\fR
 264 option to compile the bitcode testcase. This can be useful for
 265 testing compiler output without running any link or execute stages. To
 266 generate a reduced unit test, you may add \s-1CHECK\s0 directives to the
 267 testcase and pass the name of an executable compile-command script in this form:
 268 .Sp
 269 .Vb 3
 270 \&    #!/bin/sh
 271 \&    llc "$@"
 272 \&    not FileCheck [bugpoint input file].ll < bugpoint\-test\-program.s
 273 .Ve
 274 .Sp
 275 This script will \*(L"fail\*(R" as long as FileCheck passes. So the result
 276 will be the minimum bitcode that passes FileCheck.
 277 .IP "\fB\-\-safe\-path\fR \fIpath\fR" 4
 278 .IX Item "--safe-path path"
 279 This option defines the path to the command to execute with the
 280 \&\fB\-\-safe\-{int,jit,llc,cbe,custom}\fR
 281 option.
 282 .SH "EXIT STATUS"
 283 .IX Header "EXIT STATUS"
 284 If \fBbugpoint\fR succeeds in finding a problem, it will exit with 0.  Otherwise,
 285 if an error occurs, it will exit with a non-zero value.
 286 .SH "SEE ALSO"
 287 .IX Header "SEE ALSO"
 288 opt
 289 .SH "AUTHOR"
 290 .IX Header "AUTHOR"
 291 Maintained by the \s-1LLVM\s0 Team (<http://llvm.org/>).