1 clang - the Clang C, C++, and Objective-C compiler 2 ================================================== 3 4 SYNOPSIS 5 -------- 6 7 :program:`clang` [*options*] *filename ...* 8 9 DESCRIPTION 10 ----------- 11 12 :program:`clang` is a C, C++, and Objective-C compiler which encompasses 13 preprocessing, parsing, optimization, code generation, assembly, and linking. 14 Depending on which high-level mode setting is passed, Clang will stop before 15 doing a full link. While Clang is highly integrated, it is important to 16 understand the stages of compilation, to understand how to invoke it. These 17 stages are: 18 19 Driver 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 25 Preprocessing 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 31 Parsing 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 39 Code 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 49 Assembler 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 54 Linker 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 61 The Clang Static Analyzer is a tool that scans source code to try to find bugs 62 through code analysis. This tool uses many parts of Clang and is built into 63 the same driver. Please see <http://clang-analyzer.llvm.org> for more details 64 on how to use the static analyzer. 65 66 OPTIONS 67 ------- 68 69 Stage 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 94 Language 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 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 192 Target Selection Options 193 ~~~~~~~~~~~~~~~~~~~~~~~~ 194 195 Clang fully supports cross compilation as an inherent part of its design. 196 Depending on how your version of Clang is configured, it may have support for a 197 number 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 221 Code 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 257 258 Generate debug information. Note that Clang debug information works best at -O0. 259 260 .. option:: -gmodules 261 262 Generate debug information that contains external references to 263 types defined in clang modules or precompiled headers instead of 264 emitting redundant debug type information into every object file. 265 This option implies `-fmodule-format=obj`. 266 267 .. option:: -fstandalone-debug -fno-standalone-debug 268 269 Clang supports a number of optimizations to reduce the size of debug 270 information in the binary. They work based on the assumption that the 271 debug type information can be spread out over multiple compilation units. 272 For instance, Clang will not emit type definitions for types that are not 273 needed by a module and could be replaced with a forward declaration. 274 Further, Clang will only emit type info for a dynamic C++ class in the 275 module that contains the vtable for the class. 276 277 The :option:`-fstandalone-debug` option turns off these optimizations. 278 This is useful when working with 3rd-party libraries that don't come with 279 debug information. This is the default on Darwin. Note that Clang will 280 never emit type information for types that are not referenced at all by the 281 program. 282 283 .. option:: -fexceptions 284 285 Enable generation of unwind information. This allows exceptions to be thrown 286 through Clang compiled stack frames. This is on by default in x86-64. 287 288 .. option:: -ftrapv 289 290 Generate code to catch integer overflow errors. Signed integer overflow is 291 undefined in C. With this flag, extra code is generated to detect this and 292 abort when it happens. 293 294 .. option:: -fvisibility 295 296 This flag sets the default visibility level. 297 298 .. option:: -fcommon 299 300 This flag specifies that variables without initializers get common linkage. 301 It can be disabled with :option:`-fno-common`. 302 303 .. option:: -ftls-model=<model> 304 305 Set the default thread-local storage (TLS) model to use for thread-local 306 variables. Valid values are: "global-dynamic", "local-dynamic", 307 "initial-exec" and "local-exec". The default is "global-dynamic". The default 308 model can be overridden with the tls_model attribute. The compiler will try 309 to choose a more efficient model if possible. 310 311 .. option:: -flto, -emit-llvm 312 313 Generate output files in LLVM formats, suitable for link time optimization. 314 When used with :option:`-S` this generates LLVM intermediate language 315 assembly files, otherwise this generates LLVM bitcode format object files 316 (which may be passed to the linker depending on the stage selection options). 317 318 Driver Options 319 ~~~~~~~~~~~~~~ 320 321 .. option:: -### 322 323 Print (but do not run) the commands to run for this compilation. 324 325 .. option:: --help 326 327 Display available options. 328 329 .. option:: -Qunused-arguments 330 331 Do not emit any warnings for unused driver arguments. 332 333 .. option:: -Wa,<args> 334 335 Pass the comma separated arguments in args to the assembler. 336 337 .. option:: -Wl,<args> 338 339 Pass the comma separated arguments in args to the linker. 340 341 .. option:: -Wp,<args> 342 343 Pass the comma separated arguments in args to the preprocessor. 344 345 .. option:: -Xanalyzer <arg> 346 347 Pass arg to the static analyzer. 348 349 .. option:: -Xassembler <arg> 350 351 Pass arg to the assembler. 352 353 .. option:: -Xlinker <arg> 354 355 Pass arg to the linker. 356 357 .. option:: -Xpreprocessor <arg> 358 359 Pass arg to the preprocessor. 360 361 .. option:: -o <file> 362 363 Write output to file. 364 365 .. option:: -print-file-name=<file> 366 367 Print the full library path of file. 368 369 .. option:: -print-libgcc-file-name 370 371 Print the library path for "libgcc.a". 372 373 .. option:: -print-prog-name=<name> 374 375 Print the full program path of name. 376 377 .. option:: -print-search-dirs 378 379 Print the paths used for finding libraries and programs. 380 381 .. option:: -save-temps 382 383 Save intermediate compilation results. 384 385 .. option:: -integrated-as, -no-integrated-as 386 387 Used to enable and disable, respectively, the use of the integrated 388 assembler. Whether the integrated assembler is on by default is target 389 dependent. 390 391 .. option:: -time 392 393 Time individual commands. 394 395 .. option:: -ftime-report 396 397 Print timing summary of each stage of compilation. 398 399 .. option:: -v 400 401 Show commands to run and use verbose output. 402 403 404 Diagnostics Options 405 ~~~~~~~~~~~~~~~~~~~ 406 407 .. 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 408 409 These options control how Clang prints out information about diagnostics 410 (errors and warnings). Please see the Clang User's Manual for more information. 411 412 Preprocessor Options 413 ~~~~~~~~~~~~~~~~~~~~ 414 415 .. option:: -D<macroname>=<value> 416 417 Adds an implicit #define into the predefines buffer which is read before the 418 source file is preprocessed. 419 420 .. option:: -U<macroname> 421 422 Adds an implicit #undef into the predefines buffer which is read before the 423 source file is preprocessed. 424 425 .. option:: -include <filename> 426 427 Adds an implicit #include into the predefines buffer which is read before the 428 source file is preprocessed. 429 430 .. option:: -I<directory> 431 432 Add the specified directory to the search path for include files. 433 434 .. option:: -F<directory> 435 436 Add the specified directory to the search path for framework include files. 437 438 .. option:: -nostdinc 439 440 Do not search the standard system directories or compiler builtin directories 441 for include files. 442 443 .. option:: -nostdlibinc 444 445 Do not search the standard system directories for include files, but do 446 search compiler builtin include directories. 447 448 .. option:: -nobuiltininc 449 450 Do not search clang's builtin directory for include files. 451 452 453 ENVIRONMENT 454 ----------- 455 456 .. envvar:: TMPDIR, TEMP, TMP 457 458 These environment variables are checked, in order, for the location to write 459 temporary files used during the compilation process. 460 461 .. envvar:: CPATH 462 463 If this environment variable is present, it is treated as a delimited list of 464 paths to be added to the default system include path list. The delimiter is 465 the platform dependent delimiter, as used in the PATH environment variable. 466 467 Empty components in the environment variable are ignored. 468 469 .. envvar:: C_INCLUDE_PATH, OBJC_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJCPLUS_INCLUDE_PATH 470 471 These environment variables specify additional paths, as for :envvar:`CPATH`, which are 472 only used when processing the appropriate language. 473 474 .. envvar:: MACOSX_DEPLOYMENT_TARGET 475 476 If :option:`-mmacosx-version-min` is unspecified, the default deployment 477 target is read from this environment variable. This option only affects 478 Darwin targets. 479 480 BUGS 481 ---- 482 483 To report bugs, please visit <http://llvm.org/bugs/>. Most bug reports should 484 include preprocessed source files (use the :option:`-E` option) and the full 485 output of the compiler, along with information to reproduce. 486 487 SEE ALSO 488 -------- 489 490 :manpage:`as(1)`, :manpage:`ld(1)` 491 492
