usr.bin/clang/clang/clang.1

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