788 lines · plain
1clang - the Clang C, C++, and Objective-C compiler2==================================================3 4SYNOPSIS5--------6 7:program:`clang` [*options*] *filename ...*8 9DESCRIPTION10-----------11 12:program:`clang` is a C, C++, and Objective-C compiler which encompasses13preprocessing, parsing, optimization, code generation, assembly, and linking.14Depending on which high-level mode setting is passed, Clang will stop before15doing a full link. While Clang is highly integrated, it is important to16understand the stages of compilation, to understand how to invoke it. These17stages are:18 19Driver20 The clang executable is actually a small driver which controls the overall21 execution of other tools such as the compiler, assembler and linker.22 Typically you do not need to interact with the driver, but you23 transparently use it to run the other tools.24 25Preprocessing26 This stage handles tokenization of the input source file, macro expansion,27 #include expansion and handling of other preprocessor directives. The28 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 Analysis32 This stage parses the input file, translating preprocessor tokens into a33 parse tree. Once in the form of a parse tree, it applies semantic34 analysis to compute types for expressions as well and determine whether35 the code is well formed. This stage is responsible for generating most of36 the compiler warnings as well as parse errors. The output of this stage is37 an "Abstract Syntax Tree" (AST).38 39Code Generation and Optimization40 This stage translates an AST into low-level intermediate code (known as41 "LLVM IR") and ultimately to machine code. This phase is responsible for42 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 code46 generator produces object files directly. This avoids the overhead of47 generating the ".s" file and of calling the target assembler.48 49Assembler50 This stage runs the target assembler to translate the output of the51 compiler into a target object file. The output of this stage is typically52 called a ".o" file or "object" file.53 54Linker55 This stage runs the target linker to merge multiple object files into an56 executable or dynamic library. The output of this stage is typically called57 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 bugs62through code analysis. This tool uses many parts of Clang and is built into63the same driver. Please see <https://clang-analyzer.llvm.org> for more details64on how to use the static analyzer.65 66OPTIONS67-------68 69Stage Selection Options70~~~~~~~~~~~~~~~~~~~~~~~71 72.. option:: -E73 74 Run the preprocessor stage.75 76.. option:: -fsyntax-only77 78 Run the preprocessor, parser and semantic analysis stages.79 80.. option:: -S81 82 Run the previous stages as well as LLVM generation and optimization stages83 and target-specific code generation, producing an assembly file.84 85.. option:: -c86 87 Run all of the above, plus the assembler, generating a target ".o" object file.88 89.. option:: no stage selection option90 91 If no stage selection option is specified, all stages above are run, and the92 linker is run to combine the results into an executable or shared library.93 94Language Selection and Mode Options95~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~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 1990112 113 | ``iso9899:199409``114 115 ISO C 1990 with amendment 1116 117 | ``gnu89``118 | ``gnu90``119 120 ISO C 1990 with GNU extensions121 122 | ``c99``123 | ``iso9899:1999``124 125 ISO C 1999126 127 | ``gnu99``128 129 ISO C 1999 with GNU extensions130 131 | ``c11``132 | ``iso9899:2011``133 134 ISO C 2011135 136 | ``gnu11``137 138 ISO C 2011 with GNU extensions139 140 | ``c17``141 | ``iso9899:2017``142 143 ISO C 2017144 145 | ``gnu17``146 147 ISO C 2017 with GNU extensions148 149 | ``c23``150 | ``iso9899:2024``151 152 ISO C 2023153 154 | ``gnu23``155 156 ISO C 2023 with GNU extensions157 158 | ``c2y``159 160 ISO C 202y161 162 | ``gnu2y``163 164 ISO C 202y with GNU extensions165 166 The default C language standard is ``gnu17``, except on PS4, where it is167 ``gnu99``.168 169 Supported values for the C++ language are:170 171 | ``c++98``172 | ``c++03``173 174 ISO C++ 1998 with amendments175 176 | ``gnu++98``177 | ``gnu++03``178 179 ISO C++ 1998 with amendments and GNU extensions180 181 | ``c++11``182 183 ISO C++ 2011 with amendments184 185 | ``gnu++11``186 187 ISO C++ 2011 with amendments and GNU extensions188 189 | ``c++14``190 191 ISO C++ 2014 with amendments192 193 | ``gnu++14``194 195 ISO C++ 2014 with amendments and GNU extensions196 197 | ``c++17``198 199 ISO C++ 2017 with amendments200 201 | ``gnu++17``202 203 ISO C++ 2017 with amendments and GNU extensions204 205 | ``c++20``206 207 ISO C++ 2020 with amendments208 209 | ``gnu++20``210 211 ISO C++ 2020 with amendments and GNU extensions212 213 | ``c++23``214 215 ISO C++ 2023 with amendments216 217 | ``gnu++23``218 219 ISO C++ 2023 with amendments and GNU extensions220 221 | ``c++2c``222 223 Working draft for C++2c224 225 | ``gnu++2c``226 227 Working draft for C++2c with GNU extensions228 229 The default C++ language standard is ``gnu++17``.230 231 Supported values for the OpenCL language are:232 233 | ``cl1.0``234 235 OpenCL 1.0236 237 | ``cl1.1``238 239 OpenCL 1.1240 241 | ``cl1.2``242 243 OpenCL 1.2244 245 | ``cl2.0``246 247 OpenCL 2.0248 249 The default OpenCL language standard is ``cl1.0``.250 251 Supported values for the CUDA language are:252 253 | ``cuda``254 255 NVIDIA CUDA(tm)256 257.. option:: -stdlib=<library>258 259 Specify the C++ standard library to use; supported options are libstdc++ and260 libc++. If not specified, platform default will be used.261 262.. option:: -rtlib=<library>263 264 Specify the compiler runtime library to use; supported options are libgcc and265 compiler-rt. If not specified, platform default will be used.266 267.. option:: -ansi268 269 Same as -std=c89.270 271.. option:: -ObjC, -ObjC++272 273 Treat source input files as Objective-C and Object-C++ inputs respectively.274 275.. option:: -trigraphs276 277 Enable trigraphs.278 279.. option:: -ffreestanding280 281 Indicate that the file should be compiled for a freestanding, not a hosted,282 environment. Note that a freestanding build still requires linking against a C283 Standard Library which supports the freestanding interfaces for the specified284 language mode and target environment. This includes functions like `memcpy`,285 `memmove`, and `memset`.286 287.. option:: -fno-builtin288 289 Disable special handling and optimizations of well-known library functions,290 like :c:func:`strlen` and :c:func:`malloc`.291 292.. option:: -fno-builtin-<function>293 294 Disable special handling and optimizations for the specific library function.295 For example, ``-fno-builtin-strlen`` removes any special handling for the296 :c:func:`strlen` library function.297 298.. option:: -fno-builtin-std-<function>299 300 Disable special handling and optimizations for the specific C++ standard301 library function in namespace ``std``. For example,302 ``-fno-builtin-std-move_if_noexcept`` removes any special handling for the303 :cpp:func:`std::move_if_noexcept` library function.304 305 For C standard library functions that the C++ standard library also provides306 in namespace ``std``, use :option:`-fno-builtin-\<function\>` instead.307 308.. option:: -fmath-errno309 310 Indicate that math functions should be treated as updating :c:data:`errno`.311 312.. option:: -fpascal-strings313 314 Enable support for Pascal-style strings with "\\pfoo".315 316.. option:: -fms-extensions317 318 Enable support for Microsoft extensions.319 320.. option:: -fmsc-version=321 322 Set ``_MSC_VER``. When on Windows, this defaults to either the same value as323 the currently installed version of cl.exe, or ``1933``. Not set otherwise.324 325.. option:: -fborland-extensions326 327 Enable support for Borland extensions.328 329.. option:: -fwritable-strings330 331 Make all string literals default to writable. This disables uniquing of332 strings and other optimizations.333 334.. option:: -flax-vector-conversions, -flax-vector-conversions=<kind>, -fno-lax-vector-conversions335 336 Allow loose type checking rules for implicit vector conversions.337 Possible values of <kind>:338 339 - ``none``: allow no implicit conversions between vectors340 - ``integer``: allow implicit bitcasts between integer vectors of the same341 overall bit-width342 - ``all``: allow implicit bitcasts between any vectors of the same343 overall bit-width344 345 <kind> defaults to ``integer`` if unspecified.346 347.. option:: -fblocks348 349 Enable the "Blocks" language feature.350 351.. option:: -fobjc-abi-version=version352 353 Select the Objective-C ABI version to use. Available versions are 1 (legacy354 "fragile" ABI), 2 (non-fragile ABI 1), and 3 (non-fragile ABI 2).355 356.. option:: -fobjc-nonfragile-abi-version=<version>357 358 Select the Objective-C non-fragile ABI version to use by default. This will359 only be used as the Objective-C ABI when the non-fragile ABI is enabled360 (either via :option:`-fobjc-nonfragile-abi`, or because it is the platform361 default).362 363.. option:: -fobjc-nonfragile-abi, -fno-objc-nonfragile-abi364 365 Enable use of the Objective-C non-fragile ABI. On platforms for which this is366 the default ABI, it can be disabled with :option:`-fno-objc-nonfragile-abi`.367 368Target Selection Options369~~~~~~~~~~~~~~~~~~~~~~~~370 371Clang fully supports cross compilation as an inherent part of its design.372Depending on how your version of Clang is configured, it may have support for a373number of cross compilers, or may only support a native target.374 375.. option:: -arch <architecture>376 377 Specify the architecture to build for (Mac OS X specific).378 379.. option:: -target <architecture>380 381 Specify the architecture to build for (all platforms).382 383.. option:: -mmacos-version-min=<version>384 385 When building for macOS, specify the minimum version supported by your386 application.387 388.. option:: -miphoneos-version-min389 390 When building for iPhone OS, specify the minimum version supported by your391 application.392 393.. option:: --print-supported-cpus394 395 Print out a list of supported processors for the given target (specified396 through ``--target=<architecture>`` or :option:`-arch` ``<architecture>``). If no397 target is specified, the system default target will be used.398 399.. option:: -mcpu=?, -mtune=?400 401 Acts as an alias for :option:`--print-supported-cpus`.402 403.. option:: -mcpu=help, -mtune=help404 405 Acts as an alias for :option:`--print-supported-cpus`.406 407.. option:: -march=<cpu>408 409 Specify that Clang should generate code for a specific processor family410 member and later. For example, if you specify -march=i486, the compiler is411 allowed to generate instructions that are valid on i486 and later processors,412 but which may not exist on earlier ones.413 414.. option:: --print-enabled-extensions415 416 Prints the list of extensions that are enabled for the target specified by the417 combination of `--target`, `-march`, and `-mcpu` values. Currently, this418 option is only supported on AArch64 and RISC-V. On RISC-V, this option also419 prints out the ISA string of enabled extensions.420 421.. option:: --print-supported-extensions422 423 Prints the list of all extensions that are supported for every CPU target424 for an architecture (specified through ``--target=<architecture>`` or425 :option:`-arch` ``<architecture>``). If no target is specified, the system426 default target will be used. Currently, this option is only supported on427 AArch64 and RISC-V.428 429Code Generation Options430~~~~~~~~~~~~~~~~~~~~~~~431 432.. option:: -O0, -O1, -O2, -O3, -Ofast, -Os, -Oz, -Og, -O, -O4433 434 Specify which optimization level to use:435 436 :option:`-O0` Means "no optimization": this level compiles the fastest and437 generates the most debuggable code.438 439 :option:`-O1` Somewhere between :option:`-O0` and :option:`-O2`.440 441 :option:`-O2` Moderate level of optimization which enables most442 optimizations.443 444 :option:`-O3` Like :option:`-O2`, except that it enables optimizations that445 take longer to perform or that may generate larger code (in an attempt to446 make the program run faster).447 448 :option:`-Ofast` Enables all the optimizations from :option:`-O3` along449 with other aggressive optimizations that may violate strict compliance with450 language standards. This is deprecated in Clang 19 and a warning is emitted451 that :option:`-O3` in combination with :option:`-ffast-math` should be used452 instead if the request for non-standard math behavior is intended. There453 is no timeline yet for removal; the aim is to discourage use of454 :option:`-Ofast` due to the surprising behavior of an optimization flag455 changing the observable behavior of correct code.456 457 :option:`-Os` Like :option:`-O2` with extra optimizations to reduce code458 size.459 460 :option:`-Oz` Like :option:`-Os` (and thus :option:`-O2`), but reduces code461 size further.462 463 :option:`-Og` Similar to :option:`-O1`, but with slightly reduced464 optimization and better variable visibility. The same optimizations are run465 as at :option:`-O1`, but the ``-fextend-variable-liveness`` flag is466 also set, which tries to prevent optimizations from reducing the liveness of467 user variables, improving their availability when debugging.468 469 :option:`-O` Equivalent to :option:`-O1`.470 471 :option:`-O4` and higher472 473 Currently equivalent to :option:`-O3`474 475.. option:: -g, -gline-tables-only, -gmodules476 477 Control debug information output. Note that Clang debug information works478 best at :option:`-O0`. When more than one option starting with `-g` is479 specified, the last one wins:480 481 :option:`-g` Generate debug information.482 483 :option:`-gline-tables-only` Generate only line table debug information. This484 allows for symbolicated backtraces with inlining information, but does not485 include any information about variables, their locations or types.486 487 :option:`-gmodules` Generate debug information that contains external488 references to types defined in Clang modules or precompiled headers instead489 of emitting redundant debug type information into every object file. This490 option transparently switches the Clang module format to object file491 containers that hold the Clang module together with the debug information.492 When compiling a program that uses Clang modules or precompiled headers,493 this option produces complete debug information with faster compile494 times and much smaller object files.495 496 This option should not be used when building static libraries for497 distribution to other machines because the debug info will contain498 references to the module cache on the machine the object files in the499 library were built on.500 501.. option:: -fstandalone-debug -fno-standalone-debug502 503 Clang supports a number of optimizations to reduce the size of debug504 information in the binary. They work based on the assumption that the505 debug type information can be spread out over multiple compilation units.506 For instance, Clang will not emit type definitions for types that are not507 needed by a module and could be replaced with a forward declaration.508 Further, Clang will only emit type info for a dynamic C++ class in the509 module that contains the vtable for the class.510 511 The :option:`-fstandalone-debug` option turns off these optimizations.512 This is useful when working with 3rd-party libraries that don't come with513 debug information. This is the default on Darwin. Note that Clang will514 never emit type information for types that are not referenced at all by the515 program.516 517.. option:: -feliminate-unused-debug-types518 519 By default, Clang does not emit type information for types that are defined520 but not used in a program. To retain the debug info for these unused types,521 the negation **-fno-eliminate-unused-debug-types** can be used.522 523.. option:: -fexceptions524 525 Allow exceptions to be thrown through Clang compiled stack frames (on many526 targets, this will enable unwind information for functions that might have527 an exception thrown through them). For most targets, this is enabled by528 default for C++.529 530.. option:: -ftrapv531 532 Generate code to catch integer overflow errors. Signed integer overflow is533 undefined in C. With this flag, extra code is generated to detect this and534 abort when it happens.535 536.. option:: -fvisibility537 538 This flag sets the default visibility level.539 540.. option:: -fcommon, -fno-common541 542 This flag specifies that variables without initializers get common linkage.543 It can be disabled with :option:`-fno-common`.544 545.. option:: -ftls-model=<model>546 547 Set the default thread-local storage (TLS) model to use for thread-local548 variables. Valid values are: "global-dynamic", "local-dynamic",549 "initial-exec" and "local-exec". The default is "global-dynamic". The default550 model can be overridden with the tls_model attribute. The compiler will try551 to choose a more efficient model if possible.552 553.. option:: -flto, -flto=full, -flto=thin, -emit-llvm554 555 Generate output files in LLVM formats, suitable for link time optimization.556 When used with :option:`-S` this generates LLVM intermediate language557 assembly files, otherwise this generates LLVM bitcode format object files558 (which may be passed to the linker depending on the stage selection options).559 560 The default for :option:`-flto` is "full", in which the561 LLVM bitcode is suitable for monolithic Link Time Optimization (LTO), where562 the linker merges all such modules into a single combined module for563 optimization. With "thin", :doc:`ThinLTO <../ThinLTO>`564 compilation is invoked instead.565 566 .. note::567 568 On Darwin, when using :option:`-flto` along with :option:`-g` and569 compiling and linking in separate steps, you also need to pass570 ``-Wl,-object_path_lto,<lto-filename>.o`` at the linking step to instruct the571 ld64 linker not to delete the temporary object file generated during Link572 Time Optimization (this flag is automatically passed to the linker by Clang573 if compilation and linking are done in a single step). This allows debugging574 the executable as well as generating the ``.dSYM`` bundle using :manpage:`dsymutil(1)`.575 576Driver Options577~~~~~~~~~~~~~~578 579.. option:: -###580 581 Print (but do not run) the commands to run for this compilation.582 583.. option:: --help584 585 Display available options.586 587.. option:: -Qunused-arguments588 589 Do not emit any warnings for unused driver arguments.590 591.. option:: -Wa,<args>592 593 Pass the comma separated arguments in args to the assembler.594 595.. option:: -Wl,<args>596 597 Pass the comma separated arguments in args to the linker.598 599.. option:: -Wp,<args>600 601 Pass the comma separated arguments in args to the preprocessor.602 603.. option:: -Xanalyzer <arg>604 605 Pass arg to the static analyzer.606 607.. option:: -Xassembler <arg>608 609 Pass arg to the assembler.610 611.. option:: -Xlinker <arg>612 613 Pass arg to the linker.614 615.. option:: -Xpreprocessor <arg>616 617 Pass arg to the preprocessor.618 619.. option:: -o <file>620 621 Write output to file.622 623.. option:: -print-file-name=<file>624 625 Print the full library path of file.626 627.. option:: -print-libgcc-file-name628 629 Print the library path for the currently used compiler runtime library630 ("libgcc.a" or "libclang_rt.builtins.*.a").631 632.. option:: -print-prog-name=<name>633 634 Print the full program path of name.635 636.. option:: -print-search-dirs637 638 Print the paths used for finding libraries and programs.639 640.. option:: -save-temps641 642 Save intermediate compilation results.643 644.. option:: -save-stats, -save-stats=cwd, -save-stats=obj645 646 Save internal code generation (LLVM) statistics to a file in the current647 directory (:option:`-save-stats`/"-save-stats=cwd") or the directory648 of the output file ("-save-stats=obj").649 650 You can also use environment variables to control the statistics reporting.651 Setting ``CC_PRINT_INTERNAL_STAT`` to ``1`` enables the feature, the report652 goes to stdout in JSON format.653 654 Setting ``CC_PRINT_INTERNAL_STAT_FILE`` to a file path makes it report655 statistics to the given file in the JSON format.656 657 Note that ``-save-stats`` take precedence over ``CC_PRINT_INTERNAL_STAT``658 and ``CC_PRINT_INTERNAL_STAT_FILE``.659 660.. option:: -integrated-as, -no-integrated-as661 662 Used to enable and disable, respectively, the use of the integrated663 assembler. Whether the integrated assembler is on by default is target664 dependent.665 666.. option:: -time667 668 Time individual commands.669 670.. option:: -ftime-report671 672 Print timing summary of each stage of compilation.673 674.. option:: -v675 676 Show commands to run and use verbose output.677 678 679Diagnostics Options680~~~~~~~~~~~~~~~~~~~681 682.. 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-length683 684 These options control how Clang prints out information about diagnostics685 (errors and warnings). Please see the Clang User's Manual for more information.686 687Preprocessor Options688~~~~~~~~~~~~~~~~~~~~689 690.. option:: -D<macroname>=<value>691 692 Adds an implicit #define into the predefines buffer which is read before the693 source file is preprocessed.694 695.. option:: -U<macroname>696 697 Adds an implicit #undef into the predefines buffer which is read before the698 source file is preprocessed.699 700.. option:: -include <filename>701 702 Adds an implicit #include into the predefines buffer which is read before the703 source file is preprocessed.704 705.. option:: -I<directory>706 707 Add the specified directory to the search path for include files.708 709.. option:: -F<directory>710 711 Add the specified directory to the search path for framework include files.712 713.. option:: -nostdinc714 715 Do not search the standard system directories or compiler builtin directories716 for include files.717 718.. option:: -nostdlibinc719 720 Do not search the standard system directories for include files, but do721 search compiler builtin include directories.722 723.. option:: -nobuiltininc724 725 Do not search clang's builtin directory for include files.726 727.. option:: -nostdinc++728 729 Do not search the system C++ standard library directory for include files.730 731.. option:: -fkeep-system-includes732 733 Usable only with :option:`-E`. Do not copy the preprocessed content of734 "system" headers to the output; instead, preserve the #include directive.735 This can greatly reduce the volume of text produced by :option:`-E` which736 can be helpful when trying to produce a "small" reproduceable test case.737 738 This option does not guarantee reproduceability, however. If the including739 source defines preprocessor symbols that influence the behavior of system740 headers (for example, ``_XOPEN_SOURCE``) the operation of :option:`-E` will741 remove that definition and thus can change the semantics of the included742 header. Also, using a different version of the system headers (especially a743 different version of the STL) may result in different behavior. Always verify744 the preprocessed file by compiling it separately.745 746 747ENVIRONMENT748-----------749 750.. envvar:: TMPDIR, TEMP, TMP751 752 These environment variables are checked, in order, for the location to write753 temporary files used during the compilation process.754 755.. envvar:: CPATH756 757 This environment variable specifies additional (non-system) header search758 paths to be used to find included header files. These paths are searched after759 paths specified with the :option:`-I\<directory\>` option, but before any760 system header search paths. Paths are delimited by the platform dependent761 delimiter as used in the ``PATH`` environment variable. Empty entries in the762 delimited path list, including those at the beginning or end of the list, are763 treated as specifying the compiler's current working directory.764 765.. envvar:: C_INCLUDE_PATH, OBJC_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJCPLUS_INCLUDE_PATH766 767 These environment variables specify additional system header file search768 paths to be used when processing the corresponding language. Search paths are769 delimited as for the :envvar:`CPATH` environment variable.770 771.. envvar:: MACOSX_DEPLOYMENT_TARGET772 773 If :option:`-mmacos-version-min` is unspecified, the default deployment774 target is read from this environment variable. This option only affects775 Darwin targets.776 777BUGS778----779 780To report bugs, please visit <https://github.com/llvm/llvm-project/issues/>. Most bug reports should781include preprocessed source files (use the :option:`-E` option) and the full782output of the compiler, along with information to reproduce.783 784SEE ALSO785--------786 787:manpage:`as(1)`, :manpage:`ld(1)`788