llvm_clang/block5/clang/clang.1

   1 .\" Man page generated from reStructuredText.
   2 .
   3 .TH "CLANG" "1" "March 20, 2016" "3.8" "Clang"
   4 .SH NAME
   5 clang \- the Clang C, C++, and Objective-C compiler
   6 .
   7 .nr rst2man-indent-level 0
   8 .
   9 .de1 rstReportMargin
  10 \\$1 \\n[an-margin]
  11 level \\n[rst2man-indent-level]
  12 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
  13 -
  14 \\n[rst2man-indent0]
  15 \\n[rst2man-indent1]
  16 \\n[rst2man-indent2]
  17 ..
  18 .de1 INDENT
  19 .\" .rstReportMargin pre:
  20 . RS \\$1
  21 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
  22 . nr rst2man-indent-level +1
  23 .\" .rstReportMargin post:
  24 ..
  25 .de UNINDENT
  26 . RE
  27 .\" indent \\n[an-margin]
  28 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
  29 .nr rst2man-indent-level -1
  30 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
  31 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
  32 ..
  33 .SH SYNOPSIS
  34 .sp
  35 \fBclang\fP [\fIoptions\fP] \fIfilename ...\fP
  36 .SH DESCRIPTION
  37 .sp
  38 \fBclang\fP is a C, C++, and Objective\-C compiler which encompasses
  39 preprocessing, parsing, optimization, code generation, assembly, and linking.
  40 Depending on which high\-level mode setting is passed, Clang will stop before
  41 doing a full link.  While Clang is highly integrated, it is important to
  42 understand the stages of compilation, to understand how to invoke it.  These
  43 stages are:
  44 .INDENT 0.0
  45 .TP
  46 .B Driver
  47 The clang executable is actually a small driver which controls the overall
  48 execution of other tools such as the compiler, assembler and linker.
  49 Typically you do not need to interact with the driver, but you
  50 transparently use it to run the other tools.
  51 .TP
  52 .B Preprocessing
  53 This stage handles tokenization of the input source file, macro expansion,
  54 #include expansion and handling of other preprocessor directives.  The
  55 output of this stage is typically called a ".i" (for C), ".ii" (for C++),
  56 ".mi" (for Objective\-C), or ".mii" (for Objective\-C++) file.
  57 .TP
  58 .B Parsing and Semantic Analysis
  59 This stage parses the input file, translating preprocessor tokens into a
  60 parse tree.  Once in the form of a parse tree, it applies semantic
  61 analysis to compute types for expressions as well and determine whether
  62 the code is well formed. This stage is responsible for generating most of
  63 the compiler warnings as well as parse errors. The output of this stage is
  64 an "Abstract Syntax Tree" (AST).
  65 .TP
  66 .B Code Generation and Optimization
  67 This stage translates an AST into low\-level intermediate code (known as
  68 "LLVM IR") and ultimately to machine code.  This phase is responsible for
  69 optimizing the generated code and handling target\-specific code generation.
  70 The output of this stage is typically called a ".s" file or "assembly" file.
  71 .sp
  72 Clang also supports the use of an integrated assembler, in which the code
  73 generator produces object files directly. This avoids the overhead of
  74 generating the ".s" file and of calling the target assembler.
  75 .TP
  76 .B Assembler
  77 This stage runs the target assembler to translate the output of the
  78 compiler into a target object file. The output of this stage is typically
  79 called a ".o" file or "object" file.
  80 .TP
  81 .B Linker
  82 This stage runs the target linker to merge multiple object files into an
  83 executable or dynamic library. The output of this stage is typically called
  84 an "a.out", ".dylib" or ".so" file.
  85 .UNINDENT
  86 .sp
  87 \fBClang Static Analyzer\fP
  88 .sp
  89 The Clang Static Analyzer is a tool that scans source code to try to find bugs
  90 through code analysis.  This tool uses many parts of Clang and is built into
  91 the same driver.  Please see <\fI\%http://clang\-analyzer.llvm.org\fP> for more details
  92 on how to use the static analyzer.
  93 .SH OPTIONS
  94 .SS Stage Selection Options
  95 .INDENT 0.0
  96 .TP
  97 .B \-E
  98 Run the preprocessor stage.
  99 .UNINDENT
 100 .INDENT 0.0
 101 .TP
 102 .B \-fsyntax\-only
 103 Run the preprocessor, parser and type checking stages.
 104 .UNINDENT
 105 .INDENT 0.0
 106 .TP
 107 .B \-S
 108 Run the previous stages as well as LLVM generation and optimization stages
 109 and target\-specific code generation, producing an assembly file.
 110 .UNINDENT
 111 .INDENT 0.0
 112 .TP
 113 .B \-c
 114 Run all of the above, plus the assembler, generating a target ".o" object file.
 115 .UNINDENT
 116 .INDENT 0.0
 117 .TP
 118 .B no stage selection option
 119 If no stage selection option is specified, all stages above are run, and the
 120 linker is run to combine the results into an executable or shared library.
 121 .UNINDENT
 122 .SS Language Selection and Mode Options
 123 .INDENT 0.0
 124 .TP
 125 .B \-x <language>
 126 Treat subsequent input files as having type language.
 127 .UNINDENT
 128 .INDENT 0.0
 129 .TP
 130 .B \-std=<language>
 131 Specify the language standard to compile for.
 132 .UNINDENT
 133 .INDENT 0.0
 134 .TP
 135 .B \-stdlib=<library>
 136 Specify the C++ standard library to use; supported options are libstdc++ and
 137 libc++.
 138 .UNINDENT
 139 .INDENT 0.0
 140 .TP
 141 .B \-ansi
 142 Same as \-std=c89.
 143 .UNINDENT
 144 .INDENT 0.0
 145 .TP
 146 .B \-ObjC, \-ObjC++
 147 Treat source input files as Objective\-C and Object\-C++ inputs respectively.
 148 .UNINDENT
 149 .INDENT 0.0
 150 .TP
 151 .B \-trigraphs
 152 Enable trigraphs.
 153 .UNINDENT
 154 .INDENT 0.0
 155 .TP
 156 .B \-ffreestanding
 157 Indicate that the file should be compiled for a freestanding, not a hosted,
 158 environment.
 159 .UNINDENT
 160 .INDENT 0.0
 161 .TP
 162 .B \-fno\-builtin
 163 Disable special handling and optimizations of builtin functions like
 164 \fBstrlen()\fP and \fBmalloc()\fP\&.
 165 .UNINDENT
 166 .INDENT 0.0
 167 .TP
 168 .B \-fmath\-errno
 169 Indicate that math functions should be treated as updating \fBerrno\fP\&.
 170 .UNINDENT
 171 .INDENT 0.0
 172 .TP
 173 .B \-fpascal\-strings
 174 Enable support for Pascal\-style strings with "\epfoo".
 175 .UNINDENT
 176 .INDENT 0.0
 177 .TP
 178 .B \-fms\-extensions
 179 Enable support for Microsoft extensions.
 180 .UNINDENT
 181 .INDENT 0.0
 182 .TP
 183 .B \-fmsc\-version=
 184 Set _MSC_VER. Defaults to 1300 on Windows. Not set otherwise.
 185 .UNINDENT
 186 .INDENT 0.0
 187 .TP
 188 .B \-fborland\-extensions
 189 Enable support for Borland extensions.
 190 .UNINDENT
 191 .INDENT 0.0
 192 .TP
 193 .B \-fwritable\-strings
 194 Make all string literals default to writable.  This disables uniquing of
 195 strings and other optimizations.
 196 .UNINDENT
 197 .INDENT 0.0
 198 .TP
 199 .B \-flax\-vector\-conversions
 200 Allow loose type checking rules for implicit vector conversions.
 201 .UNINDENT
 202 .INDENT 0.0
 203 .TP
 204 .B \-fblocks
 205 Enable the "Blocks" language feature.
 206 .UNINDENT
 207 .INDENT 0.0
 208 .TP
 209 .B \-fobjc\-gc\-only
 210 Indicate that Objective\-C code should be compiled in GC\-only mode, which only
 211 works when Objective\-C Garbage Collection is enabled.
 212 .UNINDENT
 213 .INDENT 0.0
 214 .TP
 215 .B \-fobjc\-gc
 216 Indicate that Objective\-C code should be compiled in hybrid\-GC mode, which
 217 works with both GC and non\-GC mode.
 218 .UNINDENT
 219 .INDENT 0.0
 220 .TP
 221 .B \-fobjc\-abi\-version=version
 222 Select the Objective\-C ABI version to use. Available versions are 1 (legacy
 223 "fragile" ABI), 2 (non\-fragile ABI 1), and 3 (non\-fragile ABI 2).
 224 .UNINDENT
 225 .INDENT 0.0
 226 .TP
 227 .B \-fobjc\-nonfragile\-abi\-version=<version>
 228 Select the Objective\-C non\-fragile ABI version to use by default. This will
 229 only be used as the Objective\-C ABI when the non\-fragile ABI is enabled
 230 (either via \fI\%\-fobjc\-nonfragile\-abi\fP, or because it is the platform
 231 default).
 232 .UNINDENT
 233 .INDENT 0.0
 234 .TP
 235 .B \-fobjc\-nonfragile\-abi
 236 Enable use of the Objective\-C non\-fragile ABI. On platforms for which this is
 237 the default ABI, it can be disabled with \fB\-fno\-objc\-nonfragile\-abi\fP\&.
 238 .UNINDENT
 239 .SS Target Selection Options
 240 .sp
 241 Clang fully supports cross compilation as an inherent part of its design.
 242 Depending on how your version of Clang is configured, it may have support for a
 243 number of cross compilers, or may only support a native target.
 244 .INDENT 0.0
 245 .TP
 246 .B \-arch <architecture>
 247 Specify the architecture to build for.
 248 .UNINDENT
 249 .INDENT 0.0
 250 .TP
 251 .B \-mmacosx\-version\-min=<version>
 252 When building for Mac OS X, specify the minimum version supported by your
 253 application.
 254 .UNINDENT
 255 .INDENT 0.0
 256 .TP
 257 .B \-miphoneos\-version\-min
 258 When building for iPhone OS, specify the minimum version supported by your
 259 application.
 260 .UNINDENT
 261 .INDENT 0.0
 262 .TP
 263 .B \-march=<cpu>
 264 Specify that Clang should generate code for a specific processor family
 265 member and later.  For example, if you specify \-march=i486, the compiler is
 266 allowed to generate instructions that are valid on i486 and later processors,
 267 but which may not exist on earlier ones.
 268 .UNINDENT
 269 .SS Code Generation Options
 270 .INDENT 0.0
 271 .TP
 272 .B \-O0, \-O1, \-O2, \-O3, \-Ofast, \-Os, \-Oz, \-O, \-O4
 273 Specify which optimization level to use:
 274 .INDENT 7.0
 275 .INDENT 3.5
 276 \fI\%\-O0\fP Means "no optimization": this level compiles the fastest and
 277 generates the most debuggable code.
 278 .sp
 279 \fI\%\-O1\fP Somewhere between \fI\%\-O0\fP and \fI\%\-O2\fP\&.
 280 .sp
 281 \fI\%\-O2\fP Moderate level of optimization which enables most
 282 optimizations.
 283 .sp
 284 \fI\%\-O3\fP Like \fI\%\-O2\fP, except that it enables optimizations that
 285 take longer to perform or that may generate larger code (in an attempt to
 286 make the program run faster).
 287 .sp
 288 \fI\%\-Ofast\fP Enables all the optimizations from \fI\%\-O3\fP along
 289 with other aggressive optimizations that may violate strict compliance with
 290 language standards.
 291 .sp
 292 \fI\%\-Os\fP Like \fI\%\-O2\fP with extra optimizations to reduce code
 293 size.
 294 .sp
 295 \fI\%\-Oz\fP Like \fI\%\-Os\fP (and thus \fI\%\-O2\fP), but reduces code
 296 size further.
 297 .sp
 298 \fI\%\-O\fP Equivalent to \fI\%\-O2\fP\&.
 299 .sp
 300 \fI\%\-O4\fP and higher
 301 .INDENT 0.0
 302 .INDENT 3.5
 303 Currently equivalent to \fI\%\-O3\fP
 304 .UNINDENT
 305 .UNINDENT
 306 .UNINDENT
 307 .UNINDENT
 308 .UNINDENT
 309 .INDENT 0.0
 310 .TP
 311 .B \-g
 312 Generate debug information.  Note that Clang debug information works best at \-O0.
 313 .UNINDENT
 314 .INDENT 0.0
 315 .TP
 316 .B \-gmodules
 317 Generate debug information that contains external references to
 318 types defined in clang modules or precompiled headers instead of
 319 emitting redundant debug type information into every object file.
 320 This option implies \fB\-fmodule\-format=obj\fP\&.
 321 .sp
 322 This option should not be used when building static libraries for
 323 distribution to other machines because the debug info will contain
 324 references to the module cache on the machine the object files in
 325 the library were built on.
 326 .UNINDENT
 327 .INDENT 0.0
 328 .TP
 329 .B \-fstandalone\-debug \-fno\-standalone\-debug
 330 Clang supports a number of optimizations to reduce the size of debug
 331 information in the binary. They work based on the assumption that the
 332 debug type information can be spread out over multiple compilation units.
 333 For instance, Clang will not emit type definitions for types that are not
 334 needed by a module and could be replaced with a forward declaration.
 335 Further, Clang will only emit type info for a dynamic C++ class in the
 336 module that contains the vtable for the class.
 337 .sp
 338 The \fB\-fstandalone\-debug\fP option turns off these optimizations.
 339 This is useful when working with 3rd\-party libraries that don\(aqt come with
 340 debug information.  This is the default on Darwin.  Note that Clang will
 341 never emit type information for types that are not referenced at all by the
 342 program.
 343 .UNINDENT
 344 .INDENT 0.0
 345 .TP
 346 .B \-fexceptions
 347 Enable generation of unwind information. This allows exceptions to be thrown
 348 through Clang compiled stack frames.  This is on by default in x86\-64.
 349 .UNINDENT
 350 .INDENT 0.0
 351 .TP
 352 .B \-ftrapv
 353 Generate code to catch integer overflow errors.  Signed integer overflow is
 354 undefined in C. With this flag, extra code is generated to detect this and
 355 abort when it happens.
 356 .UNINDENT
 357 .INDENT 0.0
 358 .TP
 359 .B \-fvisibility
 360 This flag sets the default visibility level.
 361 .UNINDENT
 362 .INDENT 0.0
 363 .TP
 364 .B \-fcommon
 365 This flag specifies that variables without initializers get common linkage.
 366 It can be disabled with \fB\-fno\-common\fP\&.
 367 .UNINDENT
 368 .INDENT 0.0
 369 .TP
 370 .B \-ftls\-model=<model>
 371 Set the default thread\-local storage (TLS) model to use for thread\-local
 372 variables. Valid values are: "global\-dynamic", "local\-dynamic",
 373 "initial\-exec" and "local\-exec". The default is "global\-dynamic". The default
 374 model can be overridden with the tls_model attribute. The compiler will try
 375 to choose a more efficient model if possible.
 376 .UNINDENT
 377 .INDENT 0.0
 378 .TP
 379 .B \-flto, \-emit\-llvm
 380 Generate output files in LLVM formats, suitable for link time optimization.
 381 When used with \fI\%\-S\fP this generates LLVM intermediate language
 382 assembly files, otherwise this generates LLVM bitcode format object files
 383 (which may be passed to the linker depending on the stage selection options).
 384 .UNINDENT
 385 .SS Driver Options
 386 .INDENT 0.0
 387 .TP
 388 .B \-###
 389 Print (but do not run) the commands to run for this compilation.
 390 .UNINDENT
 391 .INDENT 0.0
 392 .TP
 393 .B \-\-help
 394 Display available options.
 395 .UNINDENT
 396 .INDENT 0.0
 397 .TP
 398 .B \-Qunused\-arguments
 399 Do not emit any warnings for unused driver arguments.
 400 .UNINDENT
 401 .INDENT 0.0
 402 .TP
 403 .B \-Wa,<args>
 404 Pass the comma separated arguments in args to the assembler.
 405 .UNINDENT
 406 .INDENT 0.0
 407 .TP
 408 .B \-Wl,<args>
 409 Pass the comma separated arguments in args to the linker.
 410 .UNINDENT
 411 .INDENT 0.0
 412 .TP
 413 .B \-Wp,<args>
 414 Pass the comma separated arguments in args to the preprocessor.
 415 .UNINDENT
 416 .INDENT 0.0
 417 .TP
 418 .B \-Xanalyzer <arg>
 419 Pass arg to the static analyzer.
 420 .UNINDENT
 421 .INDENT 0.0
 422 .TP
 423 .B \-Xassembler <arg>
 424 Pass arg to the assembler.
 425 .UNINDENT
 426 .INDENT 0.0
 427 .TP
 428 .B \-Xlinker <arg>
 429 Pass arg to the linker.
 430 .UNINDENT
 431 .INDENT 0.0
 432 .TP
 433 .B \-Xpreprocessor <arg>
 434 Pass arg to the preprocessor.
 435 .UNINDENT
 436 .INDENT 0.0
 437 .TP
 438 .B \-o <file>
 439 Write output to file.
 440 .UNINDENT
 441 .INDENT 0.0
 442 .TP
 443 .B \-print\-file\-name=<file>
 444 Print the full library path of file.
 445 .UNINDENT
 446 .INDENT 0.0
 447 .TP
 448 .B \-print\-libgcc\-file\-name
 449 Print the library path for "libgcc.a".
 450 .UNINDENT
 451 .INDENT 0.0
 452 .TP
 453 .B \-print\-prog\-name=<name>
 454 Print the full program path of name.
 455 .UNINDENT
 456 .INDENT 0.0
 457 .TP
 458 .B \-print\-search\-dirs
 459 Print the paths used for finding libraries and programs.
 460 .UNINDENT
 461 .INDENT 0.0
 462 .TP
 463 .B \-save\-temps
 464 Save intermediate compilation results.
 465 .UNINDENT
 466 .INDENT 0.0
 467 .TP
 468 .B \-integrated\-as, \-no\-integrated\-as
 469 Used to enable and disable, respectively, the use of the integrated
 470 assembler. Whether the integrated assembler is on by default is target
 471 dependent.
 472 .UNINDENT
 473 .INDENT 0.0
 474 .TP
 475 .B \-time
 476 Time individual commands.
 477 .UNINDENT
 478 .INDENT 0.0
 479 .TP
 480 .B \-ftime\-report
 481 Print timing summary of each stage of compilation.
 482 .UNINDENT
 483 .INDENT 0.0
 484 .TP
 485 .B \-v
 486 Show commands to run and use verbose output.
 487 .UNINDENT
 488 .SS Diagnostics Options
 489 .INDENT 0.0
 490 .TP
 491 .B \-fshow\-column, \-fshow\-source\-location, \-fcaret\-diagnostics, \-fdiagnostics\-fixit\-info, \-fdiagnostics\-parseable\-fixits, \-fdiagnostics\-print\-source\-range\-info, \-fprint\-source\-range\-info, \-fdiagnostics\-show\-option, \-fmessage\-length
 492 These options control how Clang prints out information about diagnostics
 493 (errors and warnings). Please see the Clang User\(aqs Manual for more information.
 494 .UNINDENT
 495 .SS Preprocessor Options
 496 .INDENT 0.0
 497 .TP
 498 .B \-D<macroname>=<value>
 499 Adds an implicit #define into the predefines buffer which is read before the
 500 source file is preprocessed.
 501 .UNINDENT
 502 .INDENT 0.0
 503 .TP
 504 .B \-U<macroname>
 505 Adds an implicit #undef into the predefines buffer which is read before the
 506 source file is preprocessed.
 507 .UNINDENT
 508 .INDENT 0.0
 509 .TP
 510 .B \-include <filename>
 511 Adds an implicit #include into the predefines buffer which is read before the
 512 source file is preprocessed.
 513 .UNINDENT
 514 .INDENT 0.0
 515 .TP
 516 .B \-I<directory>
 517 Add the specified directory to the search path for include files.
 518 .UNINDENT
 519 .INDENT 0.0
 520 .TP
 521 .B \-F<directory>
 522 Add the specified directory to the search path for framework include files.
 523 .UNINDENT
 524 .INDENT 0.0
 525 .TP
 526 .B \-nostdinc
 527 Do not search the standard system directories or compiler builtin directories
 528 for include files.
 529 .UNINDENT
 530 .INDENT 0.0
 531 .TP
 532 .B \-nostdlibinc
 533 Do not search the standard system directories for include files, but do
 534 search compiler builtin include directories.
 535 .UNINDENT
 536 .INDENT 0.0
 537 .TP
 538 .B \-nobuiltininc
 539 Do not search clang\(aqs builtin directory for include files.
 540 .UNINDENT
 541 .SH ENVIRONMENT
 542 .INDENT 0.0
 543 .TP
 544 .B TMPDIR, TEMP, TMP
 545 These environment variables are checked, in order, for the location to write
 546 temporary files used during the compilation process.
 547 .UNINDENT
 548 .INDENT 0.0
 549 .TP
 550 .B CPATH
 551 If this environment variable is present, it is treated as a delimited list of
 552 paths to be added to the default system include path list. The delimiter is
 553 the platform dependent delimiter, as used in the PATH environment variable.
 554 .sp
 555 Empty components in the environment variable are ignored.
 556 .UNINDENT
 557 .INDENT 0.0
 558 .TP
 559 .B C_INCLUDE_PATH, OBJC_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJCPLUS_INCLUDE_PATH
 560 These environment variables specify additional paths, as for \fI\%CPATH\fP, which are
 561 only used when processing the appropriate language.
 562 .UNINDENT
 563 .INDENT 0.0
 564 .TP
 565 .B MACOSX_DEPLOYMENT_TARGET
 566 If \fI\%\-mmacosx\-version\-min\fP is unspecified, the default deployment
 567 target is read from this environment variable. This option only affects
 568 Darwin targets.
 569 .UNINDENT
 570 .SH BUGS
 571 .sp
 572 To report bugs, please visit <\fI\%http://llvm.org/bugs/\fP>.  Most bug reports should
 573 include preprocessed source files (use the \fI\%\-E\fP option) and the full
 574 output of the compiler, along with information to reproduce.
 575 .SH SEE ALSO
 576 .sp
 577 \fIas(1)\fP, \fIld(1)\fP
 578 .SH AUTHOR
 579 Maintained by the Clang / LLVM Team (<http://clang.llvm.org>)
 580 .SH COPYRIGHT
 581 2007-2016, The Clang Team
 582 .\" Generated by docutils manpage writer.
 583 .