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