docs/tools/clang.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 clang - the Clang C and Objective-C compiler
   6
   7 =head1 SYNOPSIS
   8
   9 B<clang> [B<-c>|B<-S>|B<-E>] B<-std=>I<standard> B<-g>
  10   [B<-O0>|B<-O1>|B<-O2>|B<-Os>|B<-O3>|B<-O4>]
  11   B<-W>I<warnings...> B<-pedantic>
  12   B<-I>I<dir...> B<-L>I<dir...>
  13   B<-D>I<macro[=defn]>
  14   B<-f>I<feature-option...>
  15   B<-m>I<machine-option...>
  16   B<-o> I<output-file>
  17   I<input-filenames>
  18
  19 =head1 DESCRIPTION
  20
  21 B<clang> is a C and Objective-C compiler which encompasses preprocessing,
  22 parsing, optimization, code generation, assembly, and linking.  Depending on
  23 which high-level mode setting is passed, Clang will stop before doing a full
  24 link.  While Clang is highly integrated, it is important to understand the
  25 stages of compilation, to understand how to invoke it.  These stages are:
  26
  27 =over
  28
  29 =item B<Driver>
  30
  31 The B<clang> executable is actually a small driver which controls the overall
  32 execution of other tools such as the compiler, assembler and linker.  Typically
  33 you do not need to interact with the driver, but you transparently use it to run
  34 the other tools.
  35
  36 =item B<Preprocessing>
  37
  38 This stage handles tokenization of the input source file, macro expansion,
  39 #include expansion and handling of other preprocessor directives.  The output of
  40 this stage is typically called a ".i" (for C) or ".mi" (for Objective-C) file.
  41
  42 =item B<Parsing and Semantic Analysis>
  43
  44 This stage parses the input file, translating preprocessor tokens into a parse
  45 tree.  Once in the form of a parser tree, it applies semantic analysis to compute
  46 types for expressions as well and determine whether the code is well formed. This
  47 stage is responsible for generating most of the compiler warnings as well as
  48 parse errors.  The output of this stage is an "Abstract Syntax Tree" (AST).
  49
  50 =item B<Code Generation and Optimization>
  51
  52 This stage translates an AST into low-level intermediate code (known as "LLVM
  53 IR") and ultimately to machine code (depending on the optimization level).  This
  54 phase is responsible for optimizing the generated code and handling
  55 target-specfic code generation.  The output of this stage is typically called a
  56 ".s" file or "assembly" file.
  57
  58 =item B<Assembler>
  59
  60 This stage runs the target assembler to translate the output of the compiler
  61 into a target object file.  The output of this stage is typically called a ".o"
  62 file or "object" file.
  63
  64 =item B<Linker>
  65
  66 This stage runs the target linker to merge multiple object files into an
  67 executable or dynamic library.  The output of this stage is typically called an
  68 "a.out", ".dylib" or ".so" file.
  69
  70 =back
  71
  72 The Clang compiler supports a large number of options to control each of these
  73 stages.  In addition to compilation of code, Clang also supports other tools:
  74
  75 B<Clang Static Analyzer>
  76
  77 The Clang Static Analyzer is a tool that scans source code to try to find bugs
  78 though code analysis.  This tool uses many parts of Clang and is built into the
  79 same driver.
  80
  81
  82 =head1 OPTIONS
  83
  84 =head2 Stage Selection Options
  85
  86 =over
  87
  88 =item B<-E>
  89
  90 Run the preprocessor stage.
  91
  92 =item B<-fsyntax-only>
  93
  94 Run the preprocessor, parser and type checking stages.
  95
  96 =item B<-S>
  97
  98 Run the previous stages as well as LLVM generation and optimization stages and
  99 target-specific code generation, producing an assembly file.
 100
 101 =item B<-c>
 102
 103 Run all of the above, plus the assembler, generating a target ".o" object file.
 104
 105 =item B<no stage selection option>
 106
 107 If no stage selection option is specified, all stages above are run, and the
 108 linker is run to combine the results into an executable or shared library.
 109
 110 =item B<--analyze>
 111
 112 Run the Clang Static Analyzer.
 113
 114 =back
 115
 116
 117
 118 =head2 Language Selection and Mode Options
 119
 120 =over
 121
 122 =item B<-x> I<language>
 123
 124 Treat subsequent input files as having type I<language>.
 125
 126 =item B<-std>=I<language>
 127
 128 Specify the language standard to compile for.
 129
 130 =item B<-ansi>
 131
 132 Same as B<-std=c89>.
 133
 134 =item B<-ObjC++>
 135
 136 Treat source input files as Objective-C++ inputs.
 137
 138 =item B<-ObjC>
 139
 140 Treat source input files as Objective-C inputs.
 141
 142 =item B<-trigraphs>
 143
 144 Enable trigraphs.
 145
 146 =item B<-ffreestanding>
 147
 148 Indicate that the file should be compiled for a freestanding, not a hosted,
 149 environment.
 150
 151 =item B<-fno-builtin>
 152
 153 Disable special handling and optimizations of builtin functions like strlen and
 154 malloc.
 155
 156 =item B<-fmath-errno>
 157
 158 Indicate that math functions should be treated as updating errno.
 159
 160 =item B<-fpascal-strings>
 161
 162 Enable support for Pascal-style strings with "\pfoo".
 163
 164 =item B<-fms-extensions>
 165
 166 Enable support for Microsoft extensions.
 167
 168 =item B<-fwritable-strings>
 169
 170 Make all string literals default to writable.  This disables uniquing of
 171 strings and other optimizations.
 172
 173 =item B<-flax-vector-conversions>
 174
 175 Allow loose type checking rules for implicit vector conversions.
 176
 177 =item B<-fblocks>
 178
 179 Enable the "Blocks" language feature.
 180
 181
 182 =item B<-fobjc-gc-only>
 183
 184 Indicate that Objective-C code should be compiled in GC-only mode, which only
 185 works when Objective-C Garbage Collection is enabled.
 186
 187 =item B<-fobjc-gc>
 188
 189 Indicate that Objective-C code should be compiled in hybrid-GC mode, which works
 190 with both GC and non-GC mode.
 191
 192 =back
 193
 194
 195
 196 =head2 Target Selection Options
 197
 198 Clang fully supports cross compilation as an inherent part of its design.
 199 Depending on how your version of Clang is configured, it may have support for
 200 a number of cross compilers, or may only support a native target.
 201
 202 =over
 203
 204 =item B<-arch> I<architecture>
 205
 206 Specify the architecture to build for.
 207
 208 =item B<-mmacosx-version-min>=I<version>
 209
 210 When building for Mac OS/X, specify the minimum version supported by your
 211 application.
 212
 213 =item B<-miphoneos-version-min>
 214
 215 When building for iPhone OS, specify the minimum version supported by your
 216 application.
 217
 218
 219 =item B<-march>=I<cpu>
 220
 221 Specify that Clang should generate code for a specific processor family member
 222 and later.  For example, if you specify -march=i486, the compiler is allowed to
 223 generate instructions that are valid on i486 and later processors, but which
 224 may not exist on earlier ones.
 225
 226 =back
 227
 228
 229 =head2 Code Generation Options
 230
 231 =over
 232
 233 =item B<-O0> B<-O1> B<-O2> B<-Os> B<-O3> B<-O4>
 234
 235 Specify which optimization level to use.  B<-O0> means "no optimization": this
 236 level compiles the fastest and generates the most debuggable code.  B<-O2> is a
 237 moderate level of optimization which enables most optimizations.  B<-Os> is like
 238 B<-O2> with extra optimizations to reduce code size.  B<-O3> is like B<-O2>,
 239 except that it enables optimizations that take longer to perform or that may
 240 generate larger code (in an attempt to make the program run faster).  On
 241 supported platforms, B<-O4> enables link-time optimization; object files are
 242 stored in the LLVM bitcode file format and whole program optimization is done at
 243 link time. B<-O1> is somewhere between B<-O0> and B<-O2>.
 244
 245 =item B<-g>
 246
 247 Generate debug information.  Note that Clang debug information works best at
 248 B<-O0>.  At higher optimization levels, only line number information is
 249 currently available.
 250
 251 =item B<-fexceptions>
 252
 253 Enable generation of unwind information, this allows exceptions to be thrown
 254 through Clang compiled stack frames.  This is on by default in x86-64.
 255
 256 =item B<-ftrapv>
 257
 258 Generate code to catch integer overflow errors.  Signed integer overflow is
 259 undefined in C, with this flag, extra code is generated to detect this and abort
 260 when it happens.
 261
 262
 263 =item B<-fvisibility>
 264
 265 This flag sets the default visibility level.
 266
 267 =item B<-fcommon>
 268
 269 This flag specifies that variables without initializers get common linkage.  It
 270 can be disabled with B<-fno-common>.
 271
 272 =item B<-flto> B<-emit-llvm>
 273
 274 Generate output files in LLVM formats, suitable for link time optimization. When
 275 used with B<-S> this generates LLVM intermediate language assembly files,
 276 otherwise this generates LLVM bitcode format object files (which may be passed
 277 to the linker depending on the stage selection options).
 278
 279 =cut
 280
 281 ##=item B<-fnext-runtime> B<-fobjc-nonfragile-abi> B<-fgnu-runtime>
 282 ##These options specify which Objective-C runtime the code generator should
 283 ##target.  FIXME: we don't want people poking these generally.
 284
 285 =pod
 286
 287 =back
 288
 289
 290 =head2 Driver Options
 291
 292 =over
 293
 294 =item B<-###>
 295
 296 Print the commands to run for this compilation.
 297
 298 =item B<--help>
 299
 300 Display available options.
 301
 302 =item B<-Qunused-arguments>
 303
 304 Don't emit warning for unused driver arguments.
 305
 306 =item B<-Wa,>I<args>
 307
 308 Pass the comma separated arguments in I<args> to the assembler.
 309
 310 =item B<-Wl,>I<args>
 311
 312 Pass the comma separated arguments in I<args> to the linker.
 313
 314 =item B<-Wp,>I<args>
 315
 316 Pass the comma separated arguments in I<args> to the preprocessor.
 317
 318 =item B<-Xanalyzer> I<arg>
 319
 320 Pass I<arg> to the static analyzer.
 321
 322 =item B<-Xassembler> I<arg>
 323
 324 Pass I<arg> to the assembler.
 325
 326 =item B<-Xclang> I<arg>
 327
 328 Pass I<arg> to the clang compiler.
 329
 330 =item B<-Xlinker> I<arg>
 331
 332 Pass I<arg> to the linker.
 333
 334 =item B<-Xpreprocessor> I<arg>
 335
 336 Pass I<arg> to the preprocessor.
 337
 338 =item B<-o> I<file>
 339
 340 Write output to I<file>.
 341
 342 =item B<-print-file-name>=I<file>
 343
 344 Print the full library path of I<file>.
 345
 346 =item B<-print-libgcc-file-name>
 347
 348 Print the library path for "libgcc.a".
 349
 350 =item B<-print-prog-name>=I<name>
 351
 352 Print the full program path of I<name>.
 353
 354 =item B<-print-search-dirs>
 355
 356 Print the paths used for finding libraries and programs.
 357
 358 =item B<-save-temps>
 359
 360 Save intermediate compilation results.
 361
 362 =item B<-time>
 363
 364 Time individual commands.
 365
 366 =item B<-ftime-report>
 367
 368 Print timing summary of each stage of compilation.
 369
 370 =item B<-v>
 371
 372 Show commands to run and use verbose output.
 373
 374 =back
 375
 376
 377 =head2 Diagnostics Options
 378
 379 =over
 380
 381 =item B<-fshow-column>
 382 B<-fshow-source-location>
 383 B<-fcaret-diagnostics>
 384 B<-fdiagnostics-fixit-info>
 385 B<-fdiagnostics-print-source-range-info>
 386 B<-fprint-source-range-info>
 387 B<-fdiagnostics-show-option>
 388 B<-fmessage-length>
 389
 390 These options control how Clang prints out information about diagnostics (errors
 391 and warnings).  Please see the Clang User's Manual for more information.
 392
 393 =back
 394
 395
 396 =head2 Preprocessor Options
 397
 398 =over
 399
 400 =item B<-D>I<macroname=value>
 401
 402 Adds an implicit #define into the predefines buffer which is read before the
 403 source file is preprocessed.
 404
 405 =item B<-U>I<macroname>
 406
 407 Adds an implicit #undef into the predefines buffer which is read before the
 408 source file is preprocessed.
 409
 410 =item B<-include> I<filename>
 411
 412 Adds an implicit #include into the predefines buffer which is read before the
 413 source file is preprocessed.
 414
 415 =item B<-I>I<directory>
 416
 417 Add the specified directory to the search path for include files.
 418
 419 =item B<-F>I<directory>
 420
 421 Add the specified directory to the search path for framework include files.
 422
 423 =item B<-nostdinc>
 424
 425 Do not search the standard system directories for include files.
 426
 427 =item B<-nobuiltininc>
 428
 429 Do not search clang's builtin directory for include files.
 430
 431 =cut
 432
 433 ## TODO, but do we really want people using this stuff?
 434 #=item B<-idirafter>I<directory>
 435 #=item B<-iquote>I<directory>
 436 #=item B<-isystem>I<directory>
 437 #=item B<-iprefix>I<directory>
 438 #=item B<-iwithprefix>I<directory>
 439 #=item B<-iwithprefixbefore>I<directory>
 440 #=item B<-isysroot>
 441
 442 =pod
 443
 444
 445 =back
 446
 447
 448
 449 =cut
 450
 451 ### TODO someday.
 452 #=head2 Warning Control Options
 453 #=over
 454 #=back
 455 #=head2 Code Generation and Optimization Options
 456 #=over
 457 #=back
 458 #=head2 Assembler Options
 459 #=over
 460 #=back
 461 #=head2 Linker Options
 462 #=over
 463 #=back
 464 #=head2 Static Analyzer Options
 465 #=over
 466 #=back
 467
 468 =pod
 469
 470
 471 =head1 ENVIRONMENT
 472
 473 =over
 474
 475 =item B<TMPDIR>, B<TEMP>, B<TMP>
 476
 477 These environment variables are checked, in order, for the location to
 478 write temporary files used during the compilation process.
 479
 480 =item B<CPATH>
 481
 482 If this environment variable is present, it is treated as a delimited
 483 list of paths to be added to the default system include path list. The
 484 delimiter is the platform dependent delimitor, as used in the I<PATH>
 485 environment variable.
 486
 487 Empty components in the environment variable are ignored.
 488
 489 =item B<C_INCLUDE_PATH>, B<OBJC_INCLUDE_PATH>, B<CPLUS_INCLUDE_PATH>,
 490 B<OBJCPLUS_INCLUDE_PATH>
 491
 492 These environment variables specify additional paths, as for CPATH,
 493 which are only used when processing the appropriate language.
 494
 495 =item B<MACOSX_DEPLOYMENT_TARGET>
 496
 497 If -mmacosx-version-min is unspecified, the default deployment target
 498 is read from this environment variable.  This option only affects darwin
 499 targets.
 500
 501 =back
 502
 503 =head1 BUGS
 504
 505 Clang currently does not have C++ support, and this manual page is incomplete.
 506 To report bugs, please visit L<http://llvm.org/bugs/>.  Most bug reports should
 507 include preprocessed source files (use the B<-E> option) and the full output of
 508 the compiler, along with information to reproduce.
 509
 510 =head1 SEE ALSO
 511
 512  as(1), ld(1)
 513
 514 =head1 AUTHOR
 515
 516 Maintained by the Clang / LLVM Team (L<http://clang.llvm.org>).
 517
 518 =cut