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 <https://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=<standard> 102 103 Specify the language standard to compile for. 104 105 Supported values for the C language are: 106 107 | ``c89`` 108 | ``c90`` 109 | ``iso9899:1990`` 110 111 ISO C 1990 112 113 | ``iso9899:199409`` 114 115 ISO C 1990 with amendment 1 116 117 | ``gnu89`` 118 | ``gnu90`` 119 120 ISO C 1990 with GNU extensions 121 122 | ``c99`` 123 | ``iso9899:1999`` 124 125 ISO C 1999 126 127 | ``gnu99`` 128 129 ISO C 1999 with GNU extensions 130 131 | ``c11`` 132 | ``iso9899:2011`` 133 134 ISO C 2011 135 136 | ``gnu11`` 137 138 ISO C 2011 with GNU extensions 139 140 | ``c17`` 141 | ``iso9899:2017`` 142 143 ISO C 2017 144 145 | ``gnu17`` 146 147 ISO C 2017 with GNU extensions 148 149 The default C language standard is ``gnu17``, except on PS4, where it is 150 ``gnu99``. 151 152 Supported values for the C++ language are: 153 154 | ``c++98`` 155 | ``c++03`` 156 157 ISO C++ 1998 with amendments 158 159 | ``gnu++98`` 160 | ``gnu++03`` 161 162 ISO C++ 1998 with amendments and GNU extensions 163 164 | ``c++11`` 165 166 ISO C++ 2011 with amendments 167 168 | ``gnu++11`` 169 170 ISO C++ 2011 with amendments and GNU extensions 171 172 | ``c++14`` 173 174 ISO C++ 2014 with amendments 175 176 | ``gnu++14`` 177 178 ISO C++ 2014 with amendments and GNU extensions 179 180 | ``c++17`` 181 182 ISO C++ 2017 with amendments 183 184 | ``gnu++17`` 185 186 ISO C++ 2017 with amendments and GNU extensions 187 188 | ``c++2a`` 189 190 Working draft for ISO C++ 2020 191 192 | ``gnu++2a`` 193 194 Working draft for ISO C++ 2020 with GNU extensions 195 196 The default C++ language standard is ``gnu++14``. 197 198 Supported values for the OpenCL language are: 199 200 | ``cl1.0`` 201 202 OpenCL 1.0 203 204 | ``cl1.1`` 205 206 OpenCL 1.1 207 208 | ``cl1.2`` 209 210 OpenCL 1.2 211 212 | ``cl2.0`` 213 214 OpenCL 2.0 215 216 The default OpenCL language standard is ``cl1.0``. 217 218 Supported values for the CUDA language are: 219 220 | ``cuda`` 221 222 NVIDIA CUDA(tm) 223 224.. option:: -stdlib=<library> 225 226 Specify the C++ standard library to use; supported options are libstdc++ and 227 libc++. If not specified, platform default will be used. 228 229.. option:: -rtlib=<library> 230 231 Specify the compiler runtime library to use; supported options are libgcc and 232 compiler-rt. If not specified, platform default will be used. 233 234.. option:: -ansi 235 236 Same as -std=c89. 237 238.. option:: -ObjC, -ObjC++ 239 240 Treat source input files as Objective-C and Object-C++ inputs respectively. 241 242.. option:: -trigraphs 243 244 Enable trigraphs. 245 246.. option:: -ffreestanding 247 248 Indicate that the file should be compiled for a freestanding, not a hosted, 249 environment. Note that it is assumed that a freestanding environment will 250 additionally provide `memcpy`, `memmove`, `memset` and `memcmp` 251 implementations, as these are needed for efficient codegen for many programs. 252 253.. option:: -fno-builtin 254 255 Disable special handling and optimizations of builtin functions like 256 :c:func:`strlen` and :c:func:`malloc`. 257 258.. option:: -fmath-errno 259 260 Indicate that math functions should be treated as updating :c:data:`errno`. 261 262.. option:: -fpascal-strings 263 264 Enable support for Pascal-style strings with "\\pfoo". 265 266.. option:: -fms-extensions 267 268 Enable support for Microsoft extensions. 269 270.. option:: -fmsc-version= 271 272 Set _MSC_VER. Defaults to 1300 on Windows. Not set otherwise. 273 274.. option:: -fborland-extensions 275 276 Enable support for Borland extensions. 277 278.. option:: -fwritable-strings 279 280 Make all string literals default to writable. This disables uniquing of 281 strings and other optimizations. 282 283.. option:: -flax-vector-conversions, -flax-vector-conversions=<kind>, -fno-lax-vector-conversions 284 285 Allow loose type checking rules for implicit vector conversions. 286 Possible values of <kind>: 287 288 - ``none``: allow no implicit conversions between vectors 289 - ``integer``: allow implicit bitcasts between integer vectors of the same 290 overall bit-width 291 - ``all``: allow implicit bitcasts between any vectors of the same 292 overall bit-width 293 294 <kind> defaults to ``integer`` if unspecified. 295 296.. option:: -fblocks 297 298 Enable the "Blocks" language feature. 299 300.. option:: -fobjc-abi-version=version 301 302 Select the Objective-C ABI version to use. Available versions are 1 (legacy 303 "fragile" ABI), 2 (non-fragile ABI 1), and 3 (non-fragile ABI 2). 304 305.. option:: -fobjc-nonfragile-abi-version=<version> 306 307 Select the Objective-C non-fragile ABI version to use by default. This will 308 only be used as the Objective-C ABI when the non-fragile ABI is enabled 309 (either via :option:`-fobjc-nonfragile-abi`, or because it is the platform 310 default). 311 312.. option:: -fobjc-nonfragile-abi, -fno-objc-nonfragile-abi 313 314 Enable use of the Objective-C non-fragile ABI. On platforms for which this is 315 the default ABI, it can be disabled with :option:`-fno-objc-nonfragile-abi`. 316 317Target Selection Options 318~~~~~~~~~~~~~~~~~~~~~~~~ 319 320Clang fully supports cross compilation as an inherent part of its design. 321Depending on how your version of Clang is configured, it may have support for a 322number of cross compilers, or may only support a native target. 323 324.. option:: -arch <architecture> 325 326 Specify the architecture to build for. 327 328.. option:: -mmacosx-version-min=<version> 329 330 When building for macOS, specify the minimum version supported by your 331 application. 332 333.. option:: -miphoneos-version-min 334 335 When building for iPhone OS, specify the minimum version supported by your 336 application. 337 338.. option:: --print-supported-cpus 339 340 Print out a list of supported processors for the given target (specified 341 through ``--target=<architecture>`` or :option:`-arch` ``<architecture>``). If no 342 target is specified, the system default target will be used. 343 344.. option:: -mcpu=?, -mtune=? 345 346 Acts as an alias for :option:`--print-supported-cpus`. 347 348.. option:: -march=<cpu> 349 350 Specify that Clang should generate code for a specific processor family 351 member and later. For example, if you specify -march=i486, the compiler is 352 allowed to generate instructions that are valid on i486 and later processors, 353 but which may not exist on earlier ones. 354 355 356Code Generation Options 357~~~~~~~~~~~~~~~~~~~~~~~ 358 359.. option:: -O0, -O1, -O2, -O3, -Ofast, -Os, -Oz, -Og, -O, -O4 360 361 Specify which optimization level to use: 362 363 :option:`-O0` Means "no optimization": this level compiles the fastest and 364 generates the most debuggable code. 365 366 :option:`-O1` Somewhere between :option:`-O0` and :option:`-O2`. 367 368 :option:`-O2` Moderate level of optimization which enables most 369 optimizations. 370 371 :option:`-O3` Like :option:`-O2`, except that it enables optimizations that 372 take longer to perform or that may generate larger code (in an attempt to 373 make the program run faster). 374 375 :option:`-Ofast` Enables all the optimizations from :option:`-O3` along 376 with other aggressive optimizations that may violate strict compliance with 377 language standards. 378 379 :option:`-Os` Like :option:`-O2` with extra optimizations to reduce code 380 size. 381 382 :option:`-Oz` Like :option:`-Os` (and thus :option:`-O2`), but reduces code 383 size further. 384 385 :option:`-Og` Like :option:`-O1`. In future versions, this option might 386 disable different optimizations in order to improve debuggability. 387 388 :option:`-O` Equivalent to :option:`-O1`. 389 390 :option:`-O4` and higher 391 392 Currently equivalent to :option:`-O3` 393 394.. option:: -g, -gline-tables-only, -gmodules 395 396 Control debug information output. Note that Clang debug information works 397 best at :option:`-O0`. When more than one option starting with `-g` is 398 specified, the last one wins: 399 400 :option:`-g` Generate debug information. 401 402 :option:`-gline-tables-only` Generate only line table debug information. This 403 allows for symbolicated backtraces with inlining information, but does not 404 include any information about variables, their locations or types. 405 406 :option:`-gmodules` Generate debug information that contains external 407 references to types defined in Clang modules or precompiled headers instead 408 of emitting redundant debug type information into every object file. This 409 option transparently switches the Clang module format to object file 410 containers that hold the Clang module together with the debug information. 411 When compiling a program that uses Clang modules or precompiled headers, 412 this option produces complete debug information with faster compile 413 times and much smaller object files. 414 415 This option should not be used when building static libraries for 416 distribution to other machines because the debug info will contain 417 references to the module cache on the machine the object files in the 418 library were built on. 419 420.. option:: -fstandalone-debug -fno-standalone-debug 421 422 Clang supports a number of optimizations to reduce the size of debug 423 information in the binary. They work based on the assumption that the 424 debug type information can be spread out over multiple compilation units. 425 For instance, Clang will not emit type definitions for types that are not 426 needed by a module and could be replaced with a forward declaration. 427 Further, Clang will only emit type info for a dynamic C++ class in the 428 module that contains the vtable for the class. 429 430 The :option:`-fstandalone-debug` option turns off these optimizations. 431 This is useful when working with 3rd-party libraries that don't come with 432 debug information. This is the default on Darwin. Note that Clang will 433 never emit type information for types that are not referenced at all by the 434 program. 435 436.. option:: -feliminate-unused-debug-types 437 438 By default, Clang does not emit type information for types that are defined 439 but not used in a program. To retain the debug info for these unused types, 440 the negation **-fno-eliminate-unused-debug-types** can be used. 441 442.. option:: -fexceptions 443 444 Enable generation of unwind information. This allows exceptions to be thrown 445 through Clang compiled stack frames. This is on by default in x86-64. 446 447.. option:: -ftrapv 448 449 Generate code to catch integer overflow errors. Signed integer overflow is 450 undefined in C. With this flag, extra code is generated to detect this and 451 abort when it happens. 452 453.. option:: -fvisibility 454 455 This flag sets the default visibility level. 456 457.. option:: -fcommon, -fno-common 458 459 This flag specifies that variables without initializers get common linkage. 460 It can be disabled with :option:`-fno-common`. 461 462.. option:: -ftls-model=<model> 463 464 Set the default thread-local storage (TLS) model to use for thread-local 465 variables. Valid values are: "global-dynamic", "local-dynamic", 466 "initial-exec" and "local-exec". The default is "global-dynamic". The default 467 model can be overridden with the tls_model attribute. The compiler will try 468 to choose a more efficient model if possible. 469 470.. option:: -flto, -flto=full, -flto=thin, -emit-llvm 471 472 Generate output files in LLVM formats, suitable for link time optimization. 473 When used with :option:`-S` this generates LLVM intermediate language 474 assembly files, otherwise this generates LLVM bitcode format object files 475 (which may be passed to the linker depending on the stage selection options). 476 477 The default for :option:`-flto` is "full", in which the 478 LLVM bitcode is suitable for monolithic Link Time Optimization (LTO), where 479 the linker merges all such modules into a single combined module for 480 optimization. With "thin", :doc:`ThinLTO <../ThinLTO>` 481 compilation is invoked instead. 482 483 .. note:: 484 485 On Darwin, when using :option:`-flto` along with :option:`-g` and 486 compiling and linking in separate steps, you also need to pass 487 ``-Wl,-object_path_lto,<lto-filename>.o`` at the linking step to instruct the 488 ld64 linker not to delete the temporary object file generated during Link 489 Time Optimization (this flag is automatically passed to the linker by Clang 490 if compilation and linking are done in a single step). This allows debugging 491 the executable as well as generating the ``.dSYM`` bundle using :manpage:`dsymutil(1)`. 492 493Driver Options 494~~~~~~~~~~~~~~ 495 496.. option:: -### 497 498 Print (but do not run) the commands to run for this compilation. 499 500.. option:: --help 501 502 Display available options. 503 504.. option:: -Qunused-arguments 505 506 Do not emit any warnings for unused driver arguments. 507 508.. option:: -Wa,<args> 509 510 Pass the comma separated arguments in args to the assembler. 511 512.. option:: -Wl,<args> 513 514 Pass the comma separated arguments in args to the linker. 515 516.. option:: -Wp,<args> 517 518 Pass the comma separated arguments in args to the preprocessor. 519 520.. option:: -Xanalyzer <arg> 521 522 Pass arg to the static analyzer. 523 524.. option:: -Xassembler <arg> 525 526 Pass arg to the assembler. 527 528.. option:: -Xlinker <arg> 529 530 Pass arg to the linker. 531 532.. option:: -Xpreprocessor <arg> 533 534 Pass arg to the preprocessor. 535 536.. option:: -o <file> 537 538 Write output to file. 539 540.. option:: -print-file-name=<file> 541 542 Print the full library path of file. 543 544.. option:: -print-libgcc-file-name 545 546 Print the library path for the currently used compiler runtime library 547 ("libgcc.a" or "libclang_rt.builtins.*.a"). 548 549.. option:: -print-prog-name=<name> 550 551 Print the full program path of name. 552 553.. option:: -print-search-dirs 554 555 Print the paths used for finding libraries and programs. 556 557.. option:: -save-temps 558 559 Save intermediate compilation results. 560 561.. option:: -save-stats, -save-stats=cwd, -save-stats=obj 562 563 Save internal code generation (LLVM) statistics to a file in the current 564 directory (:option:`-save-stats`/"-save-stats=cwd") or the directory 565 of the output file ("-save-state=obj"). 566 567.. option:: -integrated-as, -no-integrated-as 568 569 Used to enable and disable, respectively, the use of the integrated 570 assembler. Whether the integrated assembler is on by default is target 571 dependent. 572 573.. option:: -time 574 575 Time individual commands. 576 577.. option:: -ftime-report 578 579 Print timing summary of each stage of compilation. 580 581.. option:: -v 582 583 Show commands to run and use verbose output. 584 585 586Diagnostics Options 587~~~~~~~~~~~~~~~~~~~ 588 589.. 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 590 591 These options control how Clang prints out information about diagnostics 592 (errors and warnings). Please see the Clang User's Manual for more information. 593 594Preprocessor Options 595~~~~~~~~~~~~~~~~~~~~ 596 597.. option:: -D<macroname>=<value> 598 599 Adds an implicit #define into the predefines buffer which is read before the 600 source file is preprocessed. 601 602.. option:: -U<macroname> 603 604 Adds an implicit #undef into the predefines buffer which is read before the 605 source file is preprocessed. 606 607.. option:: -include <filename> 608 609 Adds an implicit #include into the predefines buffer which is read before the 610 source file is preprocessed. 611 612.. option:: -I<directory> 613 614 Add the specified directory to the search path for include files. 615 616.. option:: -F<directory> 617 618 Add the specified directory to the search path for framework include files. 619 620.. option:: -nostdinc 621 622 Do not search the standard system directories or compiler builtin directories 623 for include files. 624 625.. option:: -nostdlibinc 626 627 Do not search the standard system directories for include files, but do 628 search compiler builtin include directories. 629 630.. option:: -nobuiltininc 631 632 Do not search clang's builtin directory for include files. 633 634 635ENVIRONMENT 636----------- 637 638.. envvar:: TMPDIR, TEMP, TMP 639 640 These environment variables are checked, in order, for the location to write 641 temporary files used during the compilation process. 642 643.. envvar:: CPATH 644 645 If this environment variable is present, it is treated as a delimited list of 646 paths to be added to the default system include path list. The delimiter is 647 the platform dependent delimiter, as used in the PATH environment variable. 648 649 Empty components in the environment variable are ignored. 650 651.. envvar:: C_INCLUDE_PATH, OBJC_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJCPLUS_INCLUDE_PATH 652 653 These environment variables specify additional paths, as for :envvar:`CPATH`, which are 654 only used when processing the appropriate language. 655 656.. envvar:: MACOSX_DEPLOYMENT_TARGET 657 658 If :option:`-mmacosx-version-min` is unspecified, the default deployment 659 target is read from this environment variable. This option only affects 660 Darwin targets. 661 662BUGS 663---- 664 665To report bugs, please visit <https://bugs.llvm.org/>. Most bug reports should 666include preprocessed source files (use the :option:`-E` option) and the full 667output of the compiler, along with information to reproduce. 668 669SEE ALSO 670-------- 671 672:manpage:`as(1)`, :manpage:`ld(1)` 673