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