1============================ 2Clang Compiler User's Manual 3============================ 4 5.. include:: <isonum.txt> 6 7.. contents:: 8 :local: 9 10Introduction 11============ 12 13The Clang Compiler is an open-source compiler for the C family of 14programming languages, aiming to be the best in class implementation of 15these languages. Clang builds on the LLVM optimizer and code generator, 16allowing it to provide high-quality optimization and code generation 17support for many targets. For more general information, please see the 18`Clang Web Site <https://clang.llvm.org>`_ or the `LLVM Web 19Site <https://llvm.org>`_. 20 21This document describes important notes about using Clang as a compiler 22for an end-user, documenting the supported features, command line 23options, etc. If you are interested in using Clang to build a tool that 24processes code, please see :doc:`InternalsManual`. If you are interested in the 25`Clang Static Analyzer <https://clang-analyzer.llvm.org>`_, please see its web 26page. 27 28Clang is one component in a complete toolchain for C family languages. 29A separate document describes the other pieces necessary to 30:doc:`assemble a complete toolchain <Toolchain>`. 31 32Clang is designed to support the C family of programming languages, 33which includes :ref:`C <c>`, :ref:`Objective-C <objc>`, :ref:`C++ <cxx>`, and 34:ref:`Objective-C++ <objcxx>` as well as many dialects of those. For 35language-specific information, please see the corresponding language 36specific section: 37 38- :ref:`C Language <c>`: K&R C, ANSI C89, ISO C90, ISO C94 (C89+AMD1), ISO 39 C99 (+TC1, TC2, TC3). 40- :ref:`Objective-C Language <objc>`: ObjC 1, ObjC 2, ObjC 2.1, plus 41 variants depending on base language. 42- :ref:`C++ Language <cxx>` 43- :ref:`Objective C++ Language <objcxx>` 44- :ref:`OpenCL Kernel Language <opencl>`: OpenCL C v1.0, v1.1, v1.2, v2.0, 45 plus C++ for OpenCL. 46 47In addition to these base languages and their dialects, Clang supports a 48broad variety of language extensions, which are documented in the 49corresponding language section. These extensions are provided to be 50compatible with the GCC, Microsoft, and other popular compilers as well 51as to improve functionality through Clang-specific features. The Clang 52driver and language features are intentionally designed to be as 53compatible with the GNU GCC compiler as reasonably possible, easing 54migration from GCC to Clang. In most cases, code "just works". 55Clang also provides an alternative driver, :ref:`clang-cl`, that is designed 56to be compatible with the Visual C++ compiler, cl.exe. 57 58In addition to language specific features, Clang has a variety of 59features that depend on what CPU architecture or operating system is 60being compiled for. Please see the :ref:`Target-Specific Features and 61Limitations <target_features>` section for more details. 62 63The rest of the introduction introduces some basic :ref:`compiler 64terminology <terminology>` that is used throughout this manual and 65contains a basic :ref:`introduction to using Clang <basicusage>` as a 66command line compiler. 67 68.. _terminology: 69 70Terminology 71----------- 72 73Front end, parser, backend, preprocessor, undefined behavior, 74diagnostic, optimizer 75 76.. _basicusage: 77 78Basic Usage 79----------- 80 81Intro to how to use a C compiler for newbies. 82 83compile + link compile then link debug info enabling optimizations 84picking a language to use, defaults to C17 by default. Autosenses based 85on extension. using a makefile 86 87Command Line Options 88==================== 89 90This section is generally an index into other sections. It does not go 91into depth on the ones that are covered by other sections. However, the 92first part introduces the language selection and other high level 93options like :option:`-c`, :option:`-g`, etc. 94 95Options to Control Error and Warning Messages 96--------------------------------------------- 97 98.. option:: -Werror 99 100 Turn warnings into errors. 101 102.. This is in plain monospaced font because it generates the same label as 103.. -Werror, and Sphinx complains. 104 105``-Werror=foo`` 106 107 Turn warning "foo" into an error. 108 109.. option:: -Wno-error=foo 110 111 Turn warning "foo" into a warning even if :option:`-Werror` is specified. 112 113.. option:: -Wfoo 114 115 Enable warning "foo". 116 See the :doc:`diagnostics reference <DiagnosticsReference>` for a complete 117 list of the warning flags that can be specified in this way. 118 119.. option:: -Wno-foo 120 121 Disable warning "foo". 122 123.. option:: -w 124 125 Disable all diagnostics. 126 127.. option:: -Weverything 128 129 :ref:`Enable all diagnostics. <diagnostics_enable_everything>` 130 131.. option:: -pedantic 132 133 Warn on language extensions. 134 135.. option:: -pedantic-errors 136 137 Error on language extensions. 138 139.. option:: -Wsystem-headers 140 141 Enable warnings from system headers. 142 143.. option:: -ferror-limit=123 144 145 Stop emitting diagnostics after 123 errors have been produced. The default is 146 20, and the error limit can be disabled with `-ferror-limit=0`. 147 148.. option:: -ftemplate-backtrace-limit=123 149 150 Only emit up to 123 template instantiation notes within the template 151 instantiation backtrace for a single warning or error. The default is 10, and 152 the limit can be disabled with `-ftemplate-backtrace-limit=0`. 153 154.. _cl_diag_formatting: 155 156Formatting of Diagnostics 157^^^^^^^^^^^^^^^^^^^^^^^^^ 158 159Clang aims to produce beautiful diagnostics by default, particularly for 160new users that first come to Clang. However, different people have 161different preferences, and sometimes Clang is driven not by a human, 162but by a program that wants consistent and easily parsable output. For 163these cases, Clang provides a wide range of options to control the exact 164output format of the diagnostics that it generates. 165 166.. _opt_fshow-column: 167 168**-f[no-]show-column** 169 Print column number in diagnostic. 170 171 This option, which defaults to on, controls whether or not Clang 172 prints the column number of a diagnostic. For example, when this is 173 enabled, Clang will print something like: 174 175 :: 176 177 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] 178 #endif bad 179 ^ 180 // 181 182 When this is disabled, Clang will print "test.c:28: warning..." with 183 no column number. 184 185 The printed column numbers count bytes from the beginning of the 186 line; take care if your source contains multibyte characters. 187 188.. _opt_fshow-source-location: 189 190**-f[no-]show-source-location** 191 Print source file/line/column information in diagnostic. 192 193 This option, which defaults to on, controls whether or not Clang 194 prints the filename, line number and column number of a diagnostic. 195 For example, when this is enabled, Clang will print something like: 196 197 :: 198 199 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] 200 #endif bad 201 ^ 202 // 203 204 When this is disabled, Clang will not print the "test.c:28:8: " 205 part. 206 207.. _opt_fcaret-diagnostics: 208 209**-f[no-]caret-diagnostics** 210 Print source line and ranges from source code in diagnostic. 211 This option, which defaults to on, controls whether or not Clang 212 prints the source line, source ranges, and caret when emitting a 213 diagnostic. For example, when this is enabled, Clang will print 214 something like: 215 216 :: 217 218 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] 219 #endif bad 220 ^ 221 // 222 223**-f[no-]color-diagnostics** 224 This option, which defaults to on when a color-capable terminal is 225 detected, controls whether or not Clang prints diagnostics in color. 226 227 When this option is enabled, Clang will use colors to highlight 228 specific parts of the diagnostic, e.g., 229 230 .. nasty hack to not lose our dignity 231 232 .. raw:: html 233 234 <pre> 235 <b><span style="color:black">test.c:28:8: <span style="color:magenta">warning</span>: extra tokens at end of #endif directive [-Wextra-tokens]</span></b> 236 #endif bad 237 <span style="color:green">^</span> 238 <span style="color:green">//</span> 239 </pre> 240 241 When this is disabled, Clang will just print: 242 243 :: 244 245 test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] 246 #endif bad 247 ^ 248 // 249 250**-fansi-escape-codes** 251 Controls whether ANSI escape codes are used instead of the Windows Console 252 API to output colored diagnostics. This option is only used on Windows and 253 defaults to off. 254 255.. option:: -fdiagnostics-format=clang/msvc/vi 256 257 Changes diagnostic output format to better match IDEs and command line tools. 258 259 This option controls the output format of the filename, line number, 260 and column printed in diagnostic messages. The options, and their 261 affect on formatting a simple conversion diagnostic, follow: 262 263 **clang** (default) 264 :: 265 266 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' 267 268 **msvc** 269 :: 270 271 t.c(3,11) : warning: conversion specifies type 'char *' but the argument has type 'int' 272 273 **vi** 274 :: 275 276 t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int' 277 278.. _opt_fdiagnostics-show-option: 279 280**-f[no-]diagnostics-show-option** 281 Enable ``[-Woption]`` information in diagnostic line. 282 283 This option, which defaults to on, controls whether or not Clang 284 prints the associated :ref:`warning group <cl_diag_warning_groups>` 285 option name when outputting a warning diagnostic. For example, in 286 this output: 287 288 :: 289 290 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] 291 #endif bad 292 ^ 293 // 294 295 Passing **-fno-diagnostics-show-option** will prevent Clang from 296 printing the [:ref:`-Wextra-tokens <opt_Wextra-tokens>`] information in 297 the diagnostic. This information tells you the flag needed to enable 298 or disable the diagnostic, either from the command line or through 299 :ref:`#pragma GCC diagnostic <pragma_GCC_diagnostic>`. 300 301.. _opt_fdiagnostics-show-category: 302 303.. option:: -fdiagnostics-show-category=none/id/name 304 305 Enable printing category information in diagnostic line. 306 307 This option, which defaults to "none", controls whether or not Clang 308 prints the category associated with a diagnostic when emitting it. 309 Each diagnostic may or many not have an associated category, if it 310 has one, it is listed in the diagnostic categorization field of the 311 diagnostic line (in the []'s). 312 313 For example, a format string warning will produce these three 314 renditions based on the setting of this option: 315 316 :: 317 318 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat] 319 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1] 320 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String] 321 322 This category can be used by clients that want to group diagnostics 323 by category, so it should be a high level category. We want dozens 324 of these, not hundreds or thousands of them. 325 326.. _opt_fsave-optimization-record: 327 328.. option:: -f[no-]save-optimization-record[=<format>] 329 330 Enable optimization remarks during compilation and write them to a separate 331 file. 332 333 This option, which defaults to off, controls whether Clang writes 334 optimization reports to a separate file. By recording diagnostics in a file, 335 users can parse or sort the remarks in a convenient way. 336 337 By default, the serialization format is YAML. 338 339 The supported serialization formats are: 340 341 - .. _opt_fsave_optimization_record_yaml: 342 343 ``-fsave-optimization-record=yaml``: A structured YAML format. 344 345 - .. _opt_fsave_optimization_record_bitstream: 346 347 ``-fsave-optimization-record=bitstream``: A binary format based on LLVM 348 Bitstream. 349 350 The output file is controlled by :ref:`-foptimization-record-file <opt_foptimization-record-file>`. 351 352 In the absence of an explicit output file, the file is chosen using the 353 following scheme: 354 355 ``<base>.opt.<format>`` 356 357 where ``<base>`` is based on the output file of the compilation (whether 358 it's explicitly specified through `-o` or not) when used with `-c` or `-S`. 359 For example: 360 361 * ``clang -fsave-optimization-record -c in.c -o out.o`` will generate 362 ``out.opt.yaml`` 363 364 * ``clang -fsave-optimization-record -c in.c `` will generate 365 ``in.opt.yaml`` 366 367 When targeting (Thin)LTO, the base is derived from the output filename, and 368 the extension is not dropped. 369 370 When targeting ThinLTO, the following scheme is used: 371 372 ``<base>.opt.<format>.thin.<num>.<format>`` 373 374 Darwin-only: when used for generating a linked binary from a source file 375 (through an intermediate object file), the driver will invoke `cc1` to 376 generate a temporary object file. The temporary remark file will be emitted 377 next to the object file, which will then be picked up by `dsymutil` and 378 emitted in the .dSYM bundle. This is available for all formats except YAML. 379 380 For example: 381 382 ``clang -fsave-optimization-record=bitstream in.c -o out`` will generate 383 384 * ``/var/folders/43/9y164hh52tv_2nrdxrj31nyw0000gn/T/a-9be59b.o`` 385 386 * ``/var/folders/43/9y164hh52tv_2nrdxrj31nyw0000gn/T/a-9be59b.opt.bitstream`` 387 388 * ``out`` 389 390 * ``out.dSYM/Contents/Resources/Remarks/out`` 391 392 Darwin-only: compiling for multiple architectures will use the following 393 scheme: 394 395 ``<base>-<arch>.opt.<format>`` 396 397 Note that this is incompatible with passing the 398 :ref:`-foptimization-record-file <opt_foptimization-record-file>` option. 399 400.. _opt_foptimization-record-file: 401 402**-foptimization-record-file** 403 Control the file to which optimization reports are written. This implies 404 :ref:`-fsave-optimization-record <opt_fsave-optimization-record>`. 405 406 On Darwin platforms, this is incompatible with passing multiple 407 ``-arch <arch>`` options. 408 409.. _opt_foptimization-record-passes: 410 411**-foptimization-record-passes** 412 Only include passes which match a specified regular expression. 413 414 When optimization reports are being output (see 415 :ref:`-fsave-optimization-record <opt_fsave-optimization-record>`), this 416 option controls the passes that will be included in the final report. 417 418 If this option is not used, all the passes are included in the optimization 419 record. 420 421.. _opt_fdiagnostics-show-hotness: 422 423**-f[no-]diagnostics-show-hotness** 424 Enable profile hotness information in diagnostic line. 425 426 This option controls whether Clang prints the profile hotness associated 427 with diagnostics in the presence of profile-guided optimization information. 428 This is currently supported with optimization remarks (see 429 :ref:`Options to Emit Optimization Reports <rpass>`). The hotness information 430 allows users to focus on the hot optimization remarks that are likely to be 431 more relevant for run-time performance. 432 433 For example, in this output, the block containing the callsite of `foo` was 434 executed 3000 times according to the profile data: 435 436 :: 437 438 s.c:7:10: remark: foo inlined into bar (hotness: 3000) [-Rpass-analysis=inline] 439 sum += foo(x, x - 2); 440 ^ 441 442 This option is implied when 443 :ref:`-fsave-optimization-record <opt_fsave-optimization-record>` is used. 444 Otherwise, it defaults to off. 445 446.. _opt_fdiagnostics-hotness-threshold: 447 448**-fdiagnostics-hotness-threshold** 449 Prevent optimization remarks from being output if they do not have at least 450 this hotness value. 451 452 This option, which defaults to zero, controls the minimum hotness an 453 optimization remark would need in order to be output by Clang. This is 454 currently supported with optimization remarks (see :ref:`Options to Emit 455 Optimization Reports <rpass>`) when profile hotness information in 456 diagnostics is enabled (see 457 :ref:`-fdiagnostics-show-hotness <opt_fdiagnostics-show-hotness>`). 458 459.. _opt_fdiagnostics-fixit-info: 460 461**-f[no-]diagnostics-fixit-info** 462 Enable "FixIt" information in the diagnostics output. 463 464 This option, which defaults to on, controls whether or not Clang 465 prints the information on how to fix a specific diagnostic 466 underneath it when it knows. For example, in this output: 467 468 :: 469 470 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] 471 #endif bad 472 ^ 473 // 474 475 Passing **-fno-diagnostics-fixit-info** will prevent Clang from 476 printing the "//" line at the end of the message. This information 477 is useful for users who may not understand what is wrong, but can be 478 confusing for machine parsing. 479 480.. _opt_fdiagnostics-print-source-range-info: 481 482**-fdiagnostics-print-source-range-info** 483 Print machine parsable information about source ranges. 484 This option makes Clang print information about source ranges in a machine 485 parsable format after the file/line/column number information. The 486 information is a simple sequence of brace enclosed ranges, where each range 487 lists the start and end line/column locations. For example, in this output: 488 489 :: 490 491 exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float') 492 P = (P-42) + Gamma*4; 493 ~~~~~~ ^ ~~~~~~~ 494 495 The {}'s are generated by -fdiagnostics-print-source-range-info. 496 497 The printed column numbers count bytes from the beginning of the 498 line; take care if your source contains multibyte characters. 499 500.. option:: -fdiagnostics-parseable-fixits 501 502 Print Fix-Its in a machine parseable form. 503 504 This option makes Clang print available Fix-Its in a machine 505 parseable format at the end of diagnostics. The following example 506 illustrates the format: 507 508 :: 509 510 fix-it:"t.cpp":{7:25-7:29}:"Gamma" 511 512 The range printed is a half-open range, so in this example the 513 characters at column 25 up to but not including column 29 on line 7 514 in t.cpp should be replaced with the string "Gamma". Either the 515 range or the replacement string may be empty (representing strict 516 insertions and strict erasures, respectively). Both the file name 517 and the insertion string escape backslash (as "\\\\"), tabs (as 518 "\\t"), newlines (as "\\n"), double quotes(as "\\"") and 519 non-printable characters (as octal "\\xxx"). 520 521 The printed column numbers count bytes from the beginning of the 522 line; take care if your source contains multibyte characters. 523 524.. option:: -fno-elide-type 525 526 Turns off elision in template type printing. 527 528 The default for template type printing is to elide as many template 529 arguments as possible, removing those which are the same in both 530 template types, leaving only the differences. Adding this flag will 531 print all the template arguments. If supported by the terminal, 532 highlighting will still appear on differing arguments. 533 534 Default: 535 536 :: 537 538 t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument; 539 540 -fno-elide-type: 541 542 :: 543 544 t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<int, map<float, int>>>' to 'vector<map<int, map<double, int>>>' for 1st argument; 545 546.. option:: -fdiagnostics-show-template-tree 547 548 Template type diffing prints a text tree. 549 550 For diffing large templated types, this option will cause Clang to 551 display the templates as an indented text tree, one argument per 552 line, with differences marked inline. This is compatible with 553 -fno-elide-type. 554 555 Default: 556 557 :: 558 559 t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument; 560 561 With :option:`-fdiagnostics-show-template-tree`: 562 563 :: 564 565 t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument; 566 vector< 567 map< 568 [...], 569 map< 570 [float != double], 571 [...]>>> 572 573.. _cl_diag_warning_groups: 574 575Individual Warning Groups 576^^^^^^^^^^^^^^^^^^^^^^^^^ 577 578TODO: Generate this from tblgen. Define one anchor per warning group. 579 580.. _opt_wextra-tokens: 581 582.. option:: -Wextra-tokens 583 584 Warn about excess tokens at the end of a preprocessor directive. 585 586 This option, which defaults to on, enables warnings about extra 587 tokens at the end of preprocessor directives. For example: 588 589 :: 590 591 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] 592 #endif bad 593 ^ 594 595 These extra tokens are not strictly conforming, and are usually best 596 handled by commenting them out. 597 598.. option:: -Wambiguous-member-template 599 600 Warn about unqualified uses of a member template whose name resolves to 601 another template at the location of the use. 602 603 This option, which defaults to on, enables a warning in the 604 following code: 605 606 :: 607 608 template<typename T> struct set{}; 609 template<typename T> struct trait { typedef const T& type; }; 610 struct Value { 611 template<typename T> void set(typename trait<T>::type value) {} 612 }; 613 void foo() { 614 Value v; 615 v.set<double>(3.2); 616 } 617 618 C++ [basic.lookup.classref] requires this to be an error, but, 619 because it's hard to work around, Clang downgrades it to a warning 620 as an extension. 621 622.. option:: -Wbind-to-temporary-copy 623 624 Warn about an unusable copy constructor when binding a reference to a 625 temporary. 626 627 This option enables warnings about binding a 628 reference to a temporary when the temporary doesn't have a usable 629 copy constructor. For example: 630 631 :: 632 633 struct NonCopyable { 634 NonCopyable(); 635 private: 636 NonCopyable(const NonCopyable&); 637 }; 638 void foo(const NonCopyable&); 639 void bar() { 640 foo(NonCopyable()); // Disallowed in C++98; allowed in C++11. 641 } 642 643 :: 644 645 struct NonCopyable2 { 646 NonCopyable2(); 647 NonCopyable2(NonCopyable2&); 648 }; 649 void foo(const NonCopyable2&); 650 void bar() { 651 foo(NonCopyable2()); // Disallowed in C++98; allowed in C++11. 652 } 653 654 Note that if ``NonCopyable2::NonCopyable2()`` has a default argument 655 whose instantiation produces a compile error, that error will still 656 be a hard error in C++98 mode even if this warning is turned off. 657 658Options to Control Clang Crash Diagnostics 659------------------------------------------ 660 661As unbelievable as it may sound, Clang does crash from time to time. 662Generally, this only occurs to those living on the `bleeding 663edge <https://llvm.org/releases/download.html#svn>`_. Clang goes to great 664lengths to assist you in filing a bug report. Specifically, Clang 665generates preprocessed source file(s) and associated run script(s) upon 666a crash. These files should be attached to a bug report to ease 667reproducibility of the failure. Below are the command line options to 668control the crash diagnostics. 669 670.. option:: -fno-crash-diagnostics 671 672 Disable auto-generation of preprocessed source files during a clang crash. 673 674The -fno-crash-diagnostics flag can be helpful for speeding the process 675of generating a delta reduced test case. 676 677.. option:: -fcrash-diagnostics-dir=<dir> 678 679 Specify where to write the crash diagnostics files; defaults to the 680 usual location for temporary files. 681 682Clang is also capable of generating preprocessed source file(s) and associated 683run script(s) even without a crash. This is specially useful when trying to 684generate a reproducer for warnings or errors while using modules. 685 686.. option:: -gen-reproducer 687 688 Generates preprocessed source files, a reproducer script and if relevant, a 689 cache containing: built module pcm's and all headers needed to rebuild the 690 same modules. 691 692.. _rpass: 693 694Options to Emit Optimization Reports 695------------------------------------ 696 697Optimization reports trace, at a high-level, all the major decisions 698done by compiler transformations. For instance, when the inliner 699decides to inline function ``foo()`` into ``bar()``, or the loop unroller 700decides to unroll a loop N times, or the vectorizer decides to 701vectorize a loop body. 702 703Clang offers a family of flags which the optimizers can use to emit 704a diagnostic in three cases: 705 7061. When the pass makes a transformation (`-Rpass`). 707 7082. When the pass fails to make a transformation (`-Rpass-missed`). 709 7103. When the pass determines whether or not to make a transformation 711 (`-Rpass-analysis`). 712 713NOTE: Although the discussion below focuses on `-Rpass`, the exact 714same options apply to `-Rpass-missed` and `-Rpass-analysis`. 715 716Since there are dozens of passes inside the compiler, each of these flags 717take a regular expression that identifies the name of the pass which should 718emit the associated diagnostic. For example, to get a report from the inliner, 719compile the code with: 720 721.. code-block:: console 722 723 $ clang -O2 -Rpass=inline code.cc -o code 724 code.cc:4:25: remark: foo inlined into bar [-Rpass=inline] 725 int bar(int j) { return foo(j, j - 2); } 726 ^ 727 728Note that remarks from the inliner are identified with `[-Rpass=inline]`. 729To request a report from every optimization pass, you should use 730`-Rpass=.*` (in fact, you can use any valid POSIX regular 731expression). However, do not expect a report from every transformation 732made by the compiler. Optimization remarks do not really make sense 733outside of the major transformations (e.g., inlining, vectorization, 734loop optimizations) and not every optimization pass supports this 735feature. 736 737Note that when using profile-guided optimization information, profile hotness 738information can be included in the remarks (see 739:ref:`-fdiagnostics-show-hotness <opt_fdiagnostics-show-hotness>`). 740 741Current limitations 742^^^^^^^^^^^^^^^^^^^ 743 7441. Optimization remarks that refer to function names will display the 745 mangled name of the function. Since these remarks are emitted by the 746 back end of the compiler, it does not know anything about the input 747 language, nor its mangling rules. 748 7492. Some source locations are not displayed correctly. The front end has 750 a more detailed source location tracking than the locations included 751 in the debug info (e.g., the front end can locate code inside macro 752 expansions). However, the locations used by `-Rpass` are 753 translated from debug annotations. That translation can be lossy, 754 which results in some remarks having no location information. 755 756Options to Emit Resource Consumption Reports 757-------------------------------------------- 758 759These are options that report execution time and consumed memory of different 760compilations steps. 761 762.. option:: -fproc-stat-report= 763 764 This option requests driver to print used memory and execution time of each 765 compilation step. The ``clang`` driver during execution calls different tools, 766 like compiler, assembler, linker etc. With this option the driver reports 767 total execution time, the execution time spent in user mode and peak memory 768 usage of each the called tool. Value of the option specifies where the report 769 is sent to. If it specifies a regular file, the data are saved to this file in 770 CSV format: 771 772 .. code-block:: console 773 774 $ clang -fproc-stat-report=abc foo.c 775 $ cat abc 776 clang-11,"/tmp/foo-123456.o",92000,84000,87536 777 ld,"a.out",900,8000,53568 778 779 The data on each row represent: 780 781 * file name of the tool executable, 782 * output file name in quotes, 783 * total execution time in microseconds, 784 * execution time in user mode in microseconds, 785 * peak memory usage in Kb. 786 787 It is possible to specify this option without any value. In this case statistics 788 are printed on standard output in human readable format: 789 790 .. code-block:: console 791 792 $ clang -fproc-stat-report foo.c 793 clang-11: output=/tmp/foo-855a8e.o, total=68.000 ms, user=60.000 ms, mem=86920 Kb 794 ld: output=a.out, total=8.000 ms, user=4.000 ms, mem=52320 Kb 795 796 The report file specified in the option is locked for write, so this option 797 can be used to collect statistics in parallel builds. The report file is not 798 cleared, new data is appended to it, thus making posible to accumulate build 799 statistics. 800 801 You can also use environment variables to control the process statistics reporting. 802 Setting ``CC_PRINT_PROC_STAT`` to ``1`` enables the feature, the report goes to 803 stdout in human readable format. 804 Setting ``CC_PRINT_PROC_STAT_FILE`` to a fully qualified file path makes it report 805 process statistics to the given file in the CSV format. Specifying a relative 806 path will likely lead to multiple files with the same name created in different 807 directories, since the path is relative to a changing working directory. 808 809 These environment variables are handy when you need to request the statistics 810 report without changing your build scripts or alter the existing set of compiler 811 options. Note that ``-fproc-stat-report`` take precedence over ``CC_PRINT_PROC_STAT`` 812 and ``CC_PRINT_PROC_STAT_FILE``. 813 814 .. code-block:: console 815 816 $ export CC_PRINT_PROC_STAT=1 817 $ export CC_PRINT_PROC_STAT_FILE=~/project-build-proc-stat.csv 818 $ make 819 820Other Options 821------------- 822Clang options that don't fit neatly into other categories. 823 824.. option:: -fgnuc-version= 825 826 This flag controls the value of ``__GNUC__`` and related macros. This flag 827 does not enable or disable any GCC extensions implemented in Clang. Setting 828 the version to zero causes Clang to leave ``__GNUC__`` and other 829 GNU-namespaced macros, such as ``__GXX_WEAK__``, undefined. 830 831.. option:: -MV 832 833 When emitting a dependency file, use formatting conventions appropriate 834 for NMake or Jom. Ignored unless another option causes Clang to emit a 835 dependency file. 836 837When Clang emits a dependency file (e.g., you supplied the -M option) 838most filenames can be written to the file without any special formatting. 839Different Make tools will treat different sets of characters as "special" 840and use different conventions for telling the Make tool that the character 841is actually part of the filename. Normally Clang uses backslash to "escape" 842a special character, which is the convention used by GNU Make. The -MV 843option tells Clang to put double-quotes around the entire filename, which 844is the convention used by NMake and Jom. 845 846Configuration files 847------------------- 848 849Configuration files group command-line options and allow all of them to be 850specified just by referencing the configuration file. They may be used, for 851example, to collect options required to tune compilation for particular 852target, such as -L, -I, -l, --sysroot, codegen options, etc. 853 854The command line option `--config` can be used to specify configuration 855file in a Clang invocation. For example: 856 857:: 858 859 clang --config /home/user/cfgs/testing.txt 860 clang --config debug.cfg 861 862If the provided argument contains a directory separator, it is considered as 863a file path, and options are read from that file. Otherwise the argument is 864treated as a file name and is searched for sequentially in the directories: 865 866 - user directory, 867 - system directory, 868 - the directory where Clang executable resides. 869 870Both user and system directories for configuration files are specified during 871clang build using CMake parameters, CLANG_CONFIG_FILE_USER_DIR and 872CLANG_CONFIG_FILE_SYSTEM_DIR respectively. The first file found is used. It is 873an error if the required file cannot be found. 874 875Another way to specify a configuration file is to encode it in executable name. 876For example, if the Clang executable is named `armv7l-clang` (it may be a 877symbolic link to `clang`), then Clang will search for file `armv7l.cfg` in the 878directory where Clang resides. 879 880If a driver mode is specified in invocation, Clang tries to find a file specific 881for the specified mode. For example, if the executable file is named 882`x86_64-clang-cl`, Clang first looks for `x86_64-cl.cfg` and if it is not found, 883looks for `x86_64.cfg`. 884 885If the command line contains options that effectively change target architecture 886(these are -m32, -EL, and some others) and the configuration file starts with an 887architecture name, Clang tries to load the configuration file for the effective 888architecture. For example, invocation: 889 890:: 891 892 x86_64-clang -m32 abc.c 893 894causes Clang search for a file `i368.cfg` first, and if no such file is found, 895Clang looks for the file `x86_64.cfg`. 896 897The configuration file consists of command-line options specified on one or 898more lines. Lines composed of whitespace characters only are ignored as well as 899lines in which the first non-blank character is `#`. Long options may be split 900between several lines by a trailing backslash. Here is example of a 901configuration file: 902 903:: 904 905 # Several options on line 906 -c --target=x86_64-unknown-linux-gnu 907 908 # Long option split between lines 909 -I/usr/lib/gcc/x86_64-linux-gnu/5.4.0/../../../../\ 910 include/c++/5.4.0 911 912 # other config files may be included 913 @linux.options 914 915Files included by `@file` directives in configuration files are resolved 916relative to the including file. For example, if a configuration file 917`~/.llvm/target.cfg` contains the directive `@os/linux.opts`, the file 918`linux.opts` is searched for in the directory `~/.llvm/os`. 919 920Language and Target-Independent Features 921======================================== 922 923Controlling Errors and Warnings 924------------------------------- 925 926Clang provides a number of ways to control which code constructs cause 927it to emit errors and warning messages, and how they are displayed to 928the console. 929 930Controlling How Clang Displays Diagnostics 931^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 932 933When Clang emits a diagnostic, it includes rich information in the 934output, and gives you fine-grain control over which information is 935printed. Clang has the ability to print this information, and these are 936the options that control it: 937 938#. A file/line/column indicator that shows exactly where the diagnostic 939 occurs in your code [:ref:`-fshow-column <opt_fshow-column>`, 940 :ref:`-fshow-source-location <opt_fshow-source-location>`]. 941#. A categorization of the diagnostic as a note, warning, error, or 942 fatal error. 943#. A text string that describes what the problem is. 944#. An option that indicates how to control the diagnostic (for 945 diagnostics that support it) 946 [:ref:`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`]. 947#. A :ref:`high-level category <diagnostics_categories>` for the diagnostic 948 for clients that want to group diagnostics by class (for diagnostics 949 that support it) 950 [:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>`]. 951#. The line of source code that the issue occurs on, along with a caret 952 and ranges that indicate the important locations 953 [:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`]. 954#. "FixIt" information, which is a concise explanation of how to fix the 955 problem (when Clang is certain it knows) 956 [:ref:`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`]. 957#. A machine-parsable representation of the ranges involved (off by 958 default) 959 [:ref:`-fdiagnostics-print-source-range-info <opt_fdiagnostics-print-source-range-info>`]. 960 961For more information please see :ref:`Formatting of 962Diagnostics <cl_diag_formatting>`. 963 964Diagnostic Mappings 965^^^^^^^^^^^^^^^^^^^ 966 967All diagnostics are mapped into one of these 6 classes: 968 969- Ignored 970- Note 971- Remark 972- Warning 973- Error 974- Fatal 975 976.. _diagnostics_categories: 977 978Diagnostic Categories 979^^^^^^^^^^^^^^^^^^^^^ 980 981Though not shown by default, diagnostics may each be associated with a 982high-level category. This category is intended to make it possible to 983triage builds that produce a large number of errors or warnings in a 984grouped way. 985 986Categories are not shown by default, but they can be turned on with the 987:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>` option. 988When set to "``name``", the category is printed textually in the 989diagnostic output. When it is set to "``id``", a category number is 990printed. The mapping of category names to category id's can be obtained 991by running '``clang --print-diagnostic-categories``'. 992 993Controlling Diagnostics via Command Line Flags 994^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 995 996TODO: -W flags, -pedantic, etc 997 998.. _pragma_gcc_diagnostic: 999 1000Controlling Diagnostics via Pragmas 1001^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1002 1003Clang can also control what diagnostics are enabled through the use of 1004pragmas in the source code. This is useful for turning off specific 1005warnings in a section of source code. Clang supports GCC's pragma for 1006compatibility with existing source code, as well as several extensions. 1007 1008The pragma may control any warning that can be used from the command 1009line. Warnings may be set to ignored, warning, error, or fatal. The 1010following example code will tell Clang or GCC to ignore the -Wall 1011warnings: 1012 1013.. code-block:: c 1014 1015 #pragma GCC diagnostic ignored "-Wall" 1016 1017In addition to all of the functionality provided by GCC's pragma, Clang 1018also allows you to push and pop the current warning state. This is 1019particularly useful when writing a header file that will be compiled by 1020other people, because you don't know what warning flags they build with. 1021 1022In the below example :option:`-Wextra-tokens` is ignored for only a single line 1023of code, after which the diagnostics return to whatever state had previously 1024existed. 1025 1026.. code-block:: c 1027 1028 #if foo 1029 #endif foo // warning: extra tokens at end of #endif directive 1030 1031 #pragma clang diagnostic push 1032 #pragma clang diagnostic ignored "-Wextra-tokens" 1033 1034 #if foo 1035 #endif foo // no warning 1036 1037 #pragma clang diagnostic pop 1038 1039The push and pop pragmas will save and restore the full diagnostic state 1040of the compiler, regardless of how it was set. That means that it is 1041possible to use push and pop around GCC compatible diagnostics and Clang 1042will push and pop them appropriately, while GCC will ignore the pushes 1043and pops as unknown pragmas. It should be noted that while Clang 1044supports the GCC pragma, Clang and GCC do not support the exact same set 1045of warnings, so even when using GCC compatible #pragmas there is no 1046guarantee that they will have identical behaviour on both compilers. 1047 1048In addition to controlling warnings and errors generated by the compiler, it is 1049possible to generate custom warning and error messages through the following 1050pragmas: 1051 1052.. code-block:: c 1053 1054 // The following will produce warning messages 1055 #pragma message "some diagnostic message" 1056 #pragma GCC warning "TODO: replace deprecated feature" 1057 1058 // The following will produce an error message 1059 #pragma GCC error "Not supported" 1060 1061These pragmas operate similarly to the ``#warning`` and ``#error`` preprocessor 1062directives, except that they may also be embedded into preprocessor macros via 1063the C99 ``_Pragma`` operator, for example: 1064 1065.. code-block:: c 1066 1067 #define STR(X) #X 1068 #define DEFER(M,...) M(__VA_ARGS__) 1069 #define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__)))) 1070 1071 CUSTOM_ERROR("Feature not available"); 1072 1073Controlling Diagnostics in System Headers 1074^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1075 1076Warnings are suppressed when they occur in system headers. By default, 1077an included file is treated as a system header if it is found in an 1078include path specified by ``-isystem``, but this can be overridden in 1079several ways. 1080 1081The ``system_header`` pragma can be used to mark the current file as 1082being a system header. No warnings will be produced from the location of 1083the pragma onwards within the same file. 1084 1085.. code-block:: c 1086 1087 #if foo 1088 #endif foo // warning: extra tokens at end of #endif directive 1089 1090 #pragma clang system_header 1091 1092 #if foo 1093 #endif foo // no warning 1094 1095The `--system-header-prefix=` and `--no-system-header-prefix=` 1096command-line arguments can be used to override whether subsets of an include 1097path are treated as system headers. When the name in a ``#include`` directive 1098is found within a header search path and starts with a system prefix, the 1099header is treated as a system header. The last prefix on the 1100command-line which matches the specified header name takes precedence. 1101For instance: 1102 1103.. code-block:: console 1104 1105 $ clang -Ifoo -isystem bar --system-header-prefix=x/ \ 1106 --no-system-header-prefix=x/y/ 1107 1108Here, ``#include "x/a.h"`` is treated as including a system header, even 1109if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated 1110as not including a system header, even if the header is found in 1111``bar``. 1112 1113A ``#include`` directive which finds a file relative to the current 1114directory is treated as including a system header if the including file 1115is treated as a system header. 1116 1117.. _diagnostics_enable_everything: 1118 1119Enabling All Diagnostics 1120^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1121 1122In addition to the traditional ``-W`` flags, one can enable **all** diagnostics 1123by passing :option:`-Weverything`. This works as expected with 1124:option:`-Werror`, and also includes the warnings from :option:`-pedantic`. Some 1125diagnostics contradict each other, therefore, users of :option:`-Weverything` 1126often disable many diagnostics such as `-Wno-c++98-compat` and `-Wno-c++-compat` 1127because they contradict recent C++ standards. 1128 1129Since :option:`-Weverything` enables every diagnostic, we generally don't 1130recommend using it. `-Wall` `-Wextra` are a better choice for most projects. 1131Using :option:`-Weverything` means that updating your compiler is more difficult 1132because you're exposed to experimental diagnostics which might be of lower 1133quality than the default ones. If you do use :option:`-Weverything` then we 1134advise that you address all new compiler diagnostics as they get added to Clang, 1135either by fixing everything they find or explicitly disabling that diagnostic 1136with its corresponding `Wno-` option. 1137 1138Note that when combined with :option:`-w` (which disables all warnings), 1139disabling all warnings wins. 1140 1141Controlling Static Analyzer Diagnostics 1142^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1143 1144While not strictly part of the compiler, the diagnostics from Clang's 1145`static analyzer <https://clang-analyzer.llvm.org>`_ can also be 1146influenced by the user via changes to the source code. See the available 1147`annotations <https://clang-analyzer.llvm.org/annotations.html>`_ and the 1148analyzer's `FAQ 1149page <https://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more 1150information. 1151 1152.. _usersmanual-precompiled-headers: 1153 1154Precompiled Headers 1155------------------- 1156 1157`Precompiled headers <https://en.wikipedia.org/wiki/Precompiled_header>`_ 1158are a general approach employed by many compilers to reduce compilation 1159time. The underlying motivation of the approach is that it is common for 1160the same (and often large) header files to be included by multiple 1161source files. Consequently, compile times can often be greatly improved 1162by caching some of the (redundant) work done by a compiler to process 1163headers. Precompiled header files, which represent one of many ways to 1164implement this optimization, are literally files that represent an 1165on-disk cache that contains the vital information necessary to reduce 1166some of the work needed to process a corresponding header file. While 1167details of precompiled headers vary between compilers, precompiled 1168headers have been shown to be highly effective at speeding up program 1169compilation on systems with very large system headers (e.g., macOS). 1170 1171Generating a PCH File 1172^^^^^^^^^^^^^^^^^^^^^ 1173 1174To generate a PCH file using Clang, one invokes Clang with the 1175`-x <language>-header` option. This mirrors the interface in GCC 1176for generating PCH files: 1177 1178.. code-block:: console 1179 1180 $ gcc -x c-header test.h -o test.h.gch 1181 $ clang -x c-header test.h -o test.h.pch 1182 1183Using a PCH File 1184^^^^^^^^^^^^^^^^ 1185 1186A PCH file can then be used as a prefix header when a :option:`-include` 1187option is passed to ``clang``: 1188 1189.. code-block:: console 1190 1191 $ clang -include test.h test.c -o test 1192 1193The ``clang`` driver will first check if a PCH file for ``test.h`` is 1194available; if so, the contents of ``test.h`` (and the files it includes) 1195will be processed from the PCH file. Otherwise, Clang falls back to 1196directly processing the content of ``test.h``. This mirrors the behavior 1197of GCC. 1198 1199.. note:: 1200 1201 Clang does *not* automatically use PCH files for headers that are directly 1202 included within a source file. For example: 1203 1204 .. code-block:: console 1205 1206 $ clang -x c-header test.h -o test.h.pch 1207 $ cat test.c 1208 #include "test.h" 1209 $ clang test.c -o test 1210 1211 In this example, ``clang`` will not automatically use the PCH file for 1212 ``test.h`` since ``test.h`` was included directly in the source file and not 1213 specified on the command line using :option:`-include`. 1214 1215Relocatable PCH Files 1216^^^^^^^^^^^^^^^^^^^^^ 1217 1218It is sometimes necessary to build a precompiled header from headers 1219that are not yet in their final, installed locations. For example, one 1220might build a precompiled header within the build tree that is then 1221meant to be installed alongside the headers. Clang permits the creation 1222of "relocatable" precompiled headers, which are built with a given path 1223(into the build directory) and can later be used from an installed 1224location. 1225 1226To build a relocatable precompiled header, place your headers into a 1227subdirectory whose structure mimics the installed location. For example, 1228if you want to build a precompiled header for the header ``mylib.h`` 1229that will be installed into ``/usr/include``, create a subdirectory 1230``build/usr/include`` and place the header ``mylib.h`` into that 1231subdirectory. If ``mylib.h`` depends on other headers, then they can be 1232stored within ``build/usr/include`` in a way that mimics the installed 1233location. 1234 1235Building a relocatable precompiled header requires two additional 1236arguments. First, pass the ``--relocatable-pch`` flag to indicate that 1237the resulting PCH file should be relocatable. Second, pass 1238``-isysroot /path/to/build``, which makes all includes for your library 1239relative to the build directory. For example: 1240 1241.. code-block:: console 1242 1243 # clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch 1244 1245When loading the relocatable PCH file, the various headers used in the 1246PCH file are found from the system header root. For example, ``mylib.h`` 1247can be found in ``/usr/include/mylib.h``. If the headers are installed 1248in some other system root, the ``-isysroot`` option can be used provide 1249a different system root from which the headers will be based. For 1250example, ``-isysroot /Developer/SDKs/MacOSX10.4u.sdk`` will look for 1251``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``. 1252 1253Relocatable precompiled headers are intended to be used in a limited 1254number of cases where the compilation environment is tightly controlled 1255and the precompiled header cannot be generated after headers have been 1256installed. 1257 1258.. _controlling-fp-behavior: 1259 1260Controlling Floating Point Behavior 1261----------------------------------- 1262 1263Clang provides a number of ways to control floating point behavior. The options 1264are listed below. 1265 1266.. option:: -ffast-math 1267 1268 Enable fast-math mode. This option lets the 1269 compiler make aggressive, potentially-lossy assumptions about 1270 floating-point math. These include: 1271 1272 * Floating-point math obeys regular algebraic rules for real numbers (e.g. 1273 ``+`` and ``*`` are associative, ``x/y == x * (1/y)``, and 1274 ``(a + b) * c == a * c + b * c``), 1275 * Operands to floating-point operations are not equal to ``NaN`` and 1276 ``Inf``, and 1277 * ``+0`` and ``-0`` are interchangeable. 1278 1279 ``-ffast-math`` also defines the ``__FAST_MATH__`` preprocessor 1280 macro. Some math libraries recognize this macro and change their behavior. 1281 With the exception of ``-ffp-contract=fast``, using any of the options 1282 below to disable any of the individual optimizations in ``-ffast-math`` 1283 will cause ``__FAST_MATH__`` to no longer be set. 1284 1285 This option implies: 1286 1287 * ``-fno-honor-infinities`` 1288 1289 * ``-fno-honor-nans`` 1290 1291 * ``-fno-math-errno`` 1292 1293 * ``-ffinite-math-only`` 1294 1295 * ``-fassociative-math`` 1296 1297 * ``-freciprocal-math`` 1298 1299 * ``-fno-signed-zeros`` 1300 1301 * ``-fno-trapping-math`` 1302 1303 * ``-ffp-contract=fast`` 1304 1305.. option:: -fdenormal-fp-math=<value> 1306 1307 Select which denormal numbers the code is permitted to require. 1308 1309 Valid values are: 1310 1311 * ``ieee`` - IEEE 754 denormal numbers 1312 * ``preserve-sign`` - the sign of a flushed-to-zero number is preserved in the sign of 0 1313 * ``positive-zero`` - denormals are flushed to positive zero 1314 1315 Defaults to ``ieee``. 1316 1317.. _opt_fstrict-float-cast-overflow: 1318 1319**-f[no-]strict-float-cast-overflow** 1320 1321 When a floating-point value is not representable in a destination integer 1322 type, the code has undefined behavior according to the language standard. 1323 By default, Clang will not guarantee any particular result in that case. 1324 With the 'no-strict' option, Clang attempts to match the overflowing behavior 1325 of the target's native float-to-int conversion instructions. 1326 1327.. _opt_fmath-errno: 1328 1329**-f[no-]math-errno** 1330 1331 Require math functions to indicate errors by setting errno. 1332 The default varies by ToolChain. ``-fno-math-errno`` allows optimizations 1333 that might cause standard C math functions to not set ``errno``. 1334 For example, on some systems, the math function ``sqrt`` is specified 1335 as setting ``errno`` to ``EDOM`` when the input is negative. On these 1336 systems, the compiler cannot normally optimize a call to ``sqrt`` to use 1337 inline code (e.g. the x86 ``sqrtsd`` instruction) without additional 1338 checking to ensure that ``errno`` is set appropriately. 1339 ``-fno-math-errno`` permits these transformations. 1340 1341 On some targets, math library functions never set ``errno``, and so 1342 ``-fno-math-errno`` is the default. This includes most BSD-derived 1343 systems, including Darwin. 1344 1345.. _opt_ftrapping-math: 1346 1347**-f[no-]trapping-math** 1348 1349 Control floating point exception behavior. ``-fno-trapping-math`` allows optimizations that assume that floating point operations cannot generate traps such as divide-by-zero, overflow and underflow. 1350 1351- The option ``-ftrapping-math`` behaves identically to ``-ffp-exception-behavior=strict``. 1352- The option ``-fno-trapping-math`` behaves identically to ``-ffp-exception-behavior=ignore``. This is the default. 1353 1354.. option:: -ffp-contract=<value> 1355 1356 Specify when the compiler is permitted to form fused floating-point 1357 operations, such as fused multiply-add (FMA). Fused operations are 1358 permitted to produce more precise results than performing the same 1359 operations separately. 1360 1361 The C standard permits intermediate floating-point results within an 1362 expression to be computed with more precision than their type would 1363 normally allow. This permits operation fusing, and Clang takes advantage 1364 of this by default. This behavior can be controlled with the ``FP_CONTRACT`` 1365 and ``clang fp contract`` pragmas. Please refer to the pragma documentation 1366 for a description of how the pragmas interact with this option. 1367 1368 Valid values are: 1369 1370 * ``fast`` (fuse across statements disregarding pragmas, default for CUDA) 1371 * ``on`` (fuse in the same statement unless dictated by pragmas, default for languages other than CUDA/HIP) 1372 * ``off`` (never fuse) 1373 * ``fast-honor-pragmas`` (fuse across statements unless dictated by pragmas, default for HIP) 1374 1375.. _opt_fhonor-infinities: 1376 1377**-f[no-]honor-infinities** 1378 1379 If both ``-fno-honor-infinities`` and ``-fno-honor-nans`` are used, 1380 has the same effect as specifying ``-ffinite-math-only``. 1381 1382.. _opt_fhonor-nans: 1383 1384**-f[no-]honor-nans** 1385 1386 If both ``-fno-honor-infinities`` and ``-fno-honor-nans`` are used, 1387 has the same effect as specifying ``-ffinite-math-only``. 1388 1389.. _opt_fapprox-func: 1390 1391**-f[no-]approx-func** 1392 1393 Allow certain math function calls (such as ``log``, ``sqrt``, ``pow``, etc) 1394 to be replaced with an approximately equivalent set of instructions 1395 or alternative math function calls. For example, a ``pow(x, 0.25)`` 1396 may be replaced with ``sqrt(sqrt(x))``, despite being an inexact result 1397 in cases where ``x`` is ``-0.0`` or ``-inf``. 1398 Defaults to ``-fno-approx-func``. 1399 1400.. _opt_fsigned-zeros: 1401 1402**-f[no-]signed-zeros** 1403 1404 Allow optimizations that ignore the sign of floating point zeros. 1405 Defaults to ``-fno-signed-zeros``. 1406 1407.. _opt_fassociative-math: 1408 1409**-f[no-]associative-math** 1410 1411 Allow floating point operations to be reassociated. 1412 Defaults to ``-fno-associative-math``. 1413 1414.. _opt_freciprocal-math: 1415 1416**-f[no-]reciprocal-math** 1417 1418 Allow division operations to be transformed into multiplication by a 1419 reciprocal. This can be significantly faster than an ordinary division 1420 but can also have significantly less precision. Defaults to 1421 ``-fno-reciprocal-math``. 1422 1423.. _opt_funsafe-math-optimizations: 1424 1425**-f[no-]unsafe-math-optimizations** 1426 1427 Allow unsafe floating-point optimizations. Also implies: 1428 1429 * ``-fassociative-math`` 1430 * ``-freciprocal-math`` 1431 * ``-fno-signed-zeroes`` 1432 * ``-fno-trapping-math``. 1433 1434 Defaults to ``-fno-unsafe-math-optimizations``. 1435 1436.. _opt_ffinite-math-only: 1437 1438**-f[no-]finite-math-only** 1439 1440 Allow floating-point optimizations that assume arguments and results are 1441 not NaNs or +-Inf. This defines the ``__FINITE_MATH_ONLY__`` preprocessor macro. 1442 Also implies: 1443 1444 * ``-fno-honor-infinities`` 1445 * ``-fno-honor-nans`` 1446 1447 Defaults to ``-fno-finite-math-only``. 1448 1449.. _opt_frounding-math: 1450 1451**-f[no-]rounding-math** 1452 1453Force floating-point operations to honor the dynamically-set rounding mode by default. 1454 1455The result of a floating-point operation often cannot be exactly represented in the result type and therefore must be rounded. IEEE 754 describes different rounding modes that control how to perform this rounding, not all of which are supported by all implementations. C provides interfaces (``fesetround`` and ``fesetenv``) for dynamically controlling the rounding mode, and while it also recommends certain conventions for changing the rounding mode, these conventions are not typically enforced in the ABI. Since the rounding mode changes the numerical result of operations, the compiler must understand something about it in order to optimize floating point operations. 1456 1457Note that floating-point operations performed as part of constant initialization are formally performed prior to the start of the program and are therefore not subject to the current rounding mode. This includes the initialization of global variables and local ``static`` variables. Floating-point operations in these contexts will be rounded using ``FE_TONEAREST``. 1458 1459- The option ``-fno-rounding-math`` allows the compiler to assume that the rounding mode is set to ``FE_TONEAREST``. This is the default. 1460- The option ``-frounding-math`` forces the compiler to honor the dynamically-set rounding mode. This prevents optimizations which might affect results if the rounding mode changes or is different from the default; for example, it prevents floating-point operations from being reordered across most calls and prevents constant-folding when the result is not exactly representable. 1461 1462.. option:: -ffp-model=<value> 1463 1464 Specify floating point behavior. ``-ffp-model`` is an umbrella 1465 option that encompasses functionality provided by other, single 1466 purpose, floating point options. Valid values are: ``precise``, ``strict``, 1467 and ``fast``. 1468 Details: 1469 1470 * ``precise`` Disables optimizations that are not value-safe on floating-point data, although FP contraction (FMA) is enabled (``-ffp-contract=fast``). This is the default behavior. 1471 * ``strict`` Enables ``-frounding-math`` and ``-ffp-exception-behavior=strict``, and disables contractions (FMA). All of the ``-ffast-math`` enablements are disabled. Enables ``STDC FENV_ACCESS``: by default ``FENV_ACCESS`` is disabled. This option setting behaves as though ``#pragma STDC FENV_ACESS ON`` appeared at the top of the source file. 1472 * ``fast`` Behaves identically to specifying both ``-ffast-math`` and ``ffp-contract=fast`` 1473 1474 Note: If your command line specifies multiple instances 1475 of the ``-ffp-model`` option, or if your command line option specifies 1476 ``-ffp-model`` and later on the command line selects a floating point 1477 option that has the effect of negating part of the ``ffp-model`` that 1478 has been selected, then the compiler will issue a diagnostic warning 1479 that the override has occurred. 1480 1481.. option:: -ffp-exception-behavior=<value> 1482 1483 Specify the floating-point exception behavior. 1484 1485 Valid values are: ``ignore``, ``maytrap``, and ``strict``. 1486 The default value is ``ignore``. Details: 1487 1488 * ``ignore`` The compiler assumes that the exception status flags will not be read and that floating point exceptions will be masked. 1489 * ``maytrap`` The compiler avoids transformations that may raise exceptions that would not have been raised by the original code. Constant folding performed by the compiler is exempt from this option. 1490 * ``strict`` The compiler ensures that all transformations strictly preserve the floating point exception semantics of the original code. 1491 1492.. option:: -f[no-]protect-parens: 1493 1494 This option pertains to floating-point types, complex types with 1495 floating-point components, and vectors of these types. Some arithmetic 1496 expression transformations that are mathematically correct and permissible 1497 according to the C and C++ language standards may be incorrect when dealing 1498 with floating-point types, such as reassociation and distribution. Further, 1499 the optimizer may ignore parentheses when computing arithmetic expressions 1500 in circumstances where the parenthesized and unparenthesized expression 1501 express the same mathematical value. For example (a+b)+c is the same 1502 mathematical value as a+(b+c), but the optimizer is free to evaluate the 1503 additions in any order regardless of the parentheses. When enabled, this 1504 option forces the optimizer to honor the order of operations with respect 1505 to parentheses in all circumstances. 1506 1507 Note that floating-point contraction (option `-ffp-contract=`) is disabled 1508 when `-fprotect-parens` is enabled. Also note that in safe floating-point 1509 modes, such as `-ffp-model=precise` or `-ffp-model=strict`, this option 1510 has no effect because the optimizer is prohibited from making unsafe 1511 transformations. 1512 1513.. _fp-constant-eval: 1514 1515A note about Floating Point Constant Evaluation 1516^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1517 1518In C, the only place floating point operations are guaranteed to be evaluated 1519during translation is in the initializers of variables of static storage 1520duration, which are all notionally initialized before the program begins 1521executing (and thus before a non-default floating point environment can be 1522entered). But C++ has many more contexts where floating point constant 1523evaluation occurs. Specifically: for static/thread-local variables, 1524first try evaluating the initializer in a constant context, including in the 1525constant floating point environment (just like in C), and then, if that fails, 1526fall back to emitting runtime code to perform the initialization (which might 1527in general be in a different floating point environment). 1528 1529Consider this example when compiled with ``-frounding-math`` 1530 1531 .. code-block:: console 1532 1533 constexpr float func_01(float x, float y) { 1534 return x + y; 1535 } 1536 float V1 = func_01(1.0F, 0x0.000001p0F); 1537 1538The C++ rule is that initializers for static storage duration variables are 1539first evaluated during translation (therefore, in the default rounding mode), 1540and only evaluated at runtime (and therefore in the runtime rounding mode) if 1541the compile-time evaluation fails. This is in line with the C rules; 1542C11 F.8.5 says: *All computation for automatic initialization is done (as if) 1543at execution time; thus, it is affected by any operative modes and raises 1544floating-point exceptions as required by IEC 60559 (provided the state for the 1545FENV_ACCESS pragma is ‘‘on’’). All computation for initialization of objects 1546that have static or thread storage duration is done (as if) at translation 1547time.* C++ generalizes this by adding another phase of initialization 1548(at runtime) if the translation-time initialization fails, but the 1549translation-time evaluation of the initializer of succeeds, it will be 1550treated as a constant initializer. 1551 1552 1553.. _controlling-code-generation: 1554 1555Controlling Code Generation 1556--------------------------- 1557 1558Clang provides a number of ways to control code generation. The options 1559are listed below. 1560 1561**-f[no-]sanitize=check1,check2,...** 1562 Turn on runtime checks for various forms of undefined or suspicious 1563 behavior. 1564 1565 This option controls whether Clang adds runtime checks for various 1566 forms of undefined or suspicious behavior, and is disabled by 1567 default. If a check fails, a diagnostic message is produced at 1568 runtime explaining the problem. The main checks are: 1569 1570 - .. _opt_fsanitize_address: 1571 1572 ``-fsanitize=address``: 1573 :doc:`AddressSanitizer`, a memory error 1574 detector. 1575 - .. _opt_fsanitize_thread: 1576 1577 ``-fsanitize=thread``: :doc:`ThreadSanitizer`, a data race detector. 1578 - .. _opt_fsanitize_memory: 1579 1580 ``-fsanitize=memory``: :doc:`MemorySanitizer`, 1581 a detector of uninitialized reads. Requires instrumentation of all 1582 program code. 1583 - .. _opt_fsanitize_undefined: 1584 1585 ``-fsanitize=undefined``: :doc:`UndefinedBehaviorSanitizer`, 1586 a fast and compatible undefined behavior checker. 1587 1588 - ``-fsanitize=dataflow``: :doc:`DataFlowSanitizer`, a general data 1589 flow analysis. 1590 - ``-fsanitize=cfi``: :doc:`control flow integrity <ControlFlowIntegrity>` 1591 checks. Requires ``-flto``. 1592 - ``-fsanitize=safe-stack``: :doc:`safe stack <SafeStack>` 1593 protection against stack-based memory corruption errors. 1594 1595 There are more fine-grained checks available: see 1596 the :ref:`list <ubsan-checks>` of specific kinds of 1597 undefined behavior that can be detected and the :ref:`list <cfi-schemes>` 1598 of control flow integrity schemes. 1599 1600 The ``-fsanitize=`` argument must also be provided when linking, in 1601 order to link to the appropriate runtime library. 1602 1603 It is not possible to combine more than one of the ``-fsanitize=address``, 1604 ``-fsanitize=thread``, and ``-fsanitize=memory`` checkers in the same 1605 program. 1606 1607**-f[no-]sanitize-recover=check1,check2,...** 1608 1609**-f[no-]sanitize-recover[=all]** 1610 1611 Controls which checks enabled by ``-fsanitize=`` flag are non-fatal. 1612 If the check is fatal, program will halt after the first error 1613 of this kind is detected and error report is printed. 1614 1615 By default, non-fatal checks are those enabled by 1616 :doc:`UndefinedBehaviorSanitizer`, 1617 except for ``-fsanitize=return`` and ``-fsanitize=unreachable``. Some 1618 sanitizers may not support recovery (or not support it by default 1619 e.g. :doc:`AddressSanitizer`), and always crash the program after the issue 1620 is detected. 1621 1622 Note that the ``-fsanitize-trap`` flag has precedence over this flag. 1623 This means that if a check has been configured to trap elsewhere on the 1624 command line, or if the check traps by default, this flag will not have 1625 any effect unless that sanitizer's trapping behavior is disabled with 1626 ``-fno-sanitize-trap``. 1627 1628 For example, if a command line contains the flags ``-fsanitize=undefined 1629 -fsanitize-trap=undefined``, the flag ``-fsanitize-recover=alignment`` 1630 will have no effect on its own; it will need to be accompanied by 1631 ``-fno-sanitize-trap=alignment``. 1632 1633**-f[no-]sanitize-trap=check1,check2,...** 1634 1635**-f[no-]sanitize-trap[=all]** 1636 1637 Controls which checks enabled by the ``-fsanitize=`` flag trap. This 1638 option is intended for use in cases where the sanitizer runtime cannot 1639 be used (for instance, when building libc or a kernel module), or where 1640 the binary size increase caused by the sanitizer runtime is a concern. 1641 1642 This flag is only compatible with :doc:`control flow integrity 1643 <ControlFlowIntegrity>` schemes and :doc:`UndefinedBehaviorSanitizer` 1644 checks other than ``vptr``. 1645 1646 This flag is enabled by default for sanitizers in the ``cfi`` group. 1647 1648.. option:: -fsanitize-ignorelist=/path/to/ignorelist/file 1649 1650 Disable or modify sanitizer checks for objects (source files, functions, 1651 variables, types) listed in the file. See 1652 :doc:`SanitizerSpecialCaseList` for file format description. 1653 1654.. option:: -fno-sanitize-ignorelist 1655 1656 Don't use ignorelist file, if it was specified earlier in the command line. 1657 1658**-f[no-]sanitize-coverage=[type,features,...]** 1659 1660 Enable simple code coverage in addition to certain sanitizers. 1661 See :doc:`SanitizerCoverage` for more details. 1662 1663**-f[no-]sanitize-address-outline-instrumentation** 1664 1665 Controls how address sanitizer code is generated. If enabled will always use 1666 a function call instead of inlining the code. Turning this option on could 1667 reduce the binary size, but might result in a worse run-time performance. 1668 1669 See :doc: `AddressSanitizer` for more details. 1670 1671**-f[no-]sanitize-stats** 1672 1673 Enable simple statistics gathering for the enabled sanitizers. 1674 See :doc:`SanitizerStats` for more details. 1675 1676.. option:: -fsanitize-undefined-trap-on-error 1677 1678 Deprecated alias for ``-fsanitize-trap=undefined``. 1679 1680.. option:: -fsanitize-cfi-cross-dso 1681 1682 Enable cross-DSO control flow integrity checks. This flag modifies 1683 the behavior of sanitizers in the ``cfi`` group to allow checking 1684 of cross-DSO virtual and indirect calls. 1685 1686.. option:: -fsanitize-cfi-icall-generalize-pointers 1687 1688 Generalize pointers in return and argument types in function type signatures 1689 checked by Control Flow Integrity indirect call checking. See 1690 :doc:`ControlFlowIntegrity` for more details. 1691 1692.. option:: -fstrict-vtable-pointers 1693 1694 Enable optimizations based on the strict rules for overwriting polymorphic 1695 C++ objects, i.e. the vptr is invariant during an object's lifetime. 1696 This enables better devirtualization. Turned off by default, because it is 1697 still experimental. 1698 1699.. option:: -fwhole-program-vtables 1700 1701 Enable whole-program vtable optimizations, such as single-implementation 1702 devirtualization and virtual constant propagation, for classes with 1703 :doc:`hidden LTO visibility <LTOVisibility>`. Requires ``-flto``. 1704 1705.. option:: -fforce-emit-vtables 1706 1707 In order to improve devirtualization, forces emitting of vtables even in 1708 modules where it isn't necessary. It causes more inline virtual functions 1709 to be emitted. 1710 1711.. option:: -fno-assume-sane-operator-new 1712 1713 Don't assume that the C++'s new operator is sane. 1714 1715 This option tells the compiler to do not assume that C++'s global 1716 new operator will always return a pointer that does not alias any 1717 other pointer when the function returns. 1718 1719.. option:: -ftrap-function=[name] 1720 1721 Instruct code generator to emit a function call to the specified 1722 function name for ``__builtin_trap()``. 1723 1724 LLVM code generator translates ``__builtin_trap()`` to a trap 1725 instruction if it is supported by the target ISA. Otherwise, the 1726 builtin is translated into a call to ``abort``. If this option is 1727 set, then the code generator will always lower the builtin to a call 1728 to the specified function regardless of whether the target ISA has a 1729 trap instruction. This option is useful for environments (e.g. 1730 deeply embedded) where a trap cannot be properly handled, or when 1731 some custom behavior is desired. 1732 1733.. option:: -ftls-model=[model] 1734 1735 Select which TLS model to use. 1736 1737 Valid values are: ``global-dynamic``, ``local-dynamic``, 1738 ``initial-exec`` and ``local-exec``. The default value is 1739 ``global-dynamic``. The compiler may use a different model if the 1740 selected model is not supported by the target, or if a more 1741 efficient model can be used. The TLS model can be overridden per 1742 variable using the ``tls_model`` attribute. 1743 1744.. option:: -femulated-tls 1745 1746 Select emulated TLS model, which overrides all -ftls-model choices. 1747 1748 In emulated TLS mode, all access to TLS variables are converted to 1749 calls to __emutls_get_address in the runtime library. 1750 1751.. option:: -mhwdiv=[values] 1752 1753 Select the ARM modes (arm or thumb) that support hardware division 1754 instructions. 1755 1756 Valid values are: ``arm``, ``thumb`` and ``arm,thumb``. 1757 This option is used to indicate which mode (arm or thumb) supports 1758 hardware division instructions. This only applies to the ARM 1759 architecture. 1760 1761.. option:: -m[no-]crc 1762 1763 Enable or disable CRC instructions. 1764 1765 This option is used to indicate whether CRC instructions are to 1766 be generated. This only applies to the ARM architecture. 1767 1768 CRC instructions are enabled by default on ARMv8. 1769 1770.. option:: -mgeneral-regs-only 1771 1772 Generate code which only uses the general purpose registers. 1773 1774 This option restricts the generated code to use general registers 1775 only. This only applies to the AArch64 architecture. 1776 1777.. option:: -mcompact-branches=[values] 1778 1779 Control the usage of compact branches for MIPSR6. 1780 1781 Valid values are: ``never``, ``optimal`` and ``always``. 1782 The default value is ``optimal`` which generates compact branches 1783 when a delay slot cannot be filled. ``never`` disables the usage of 1784 compact branches and ``always`` generates compact branches whenever 1785 possible. 1786 1787**-f[no-]max-type-align=[number]** 1788 Instruct the code generator to not enforce a higher alignment than the given 1789 number (of bytes) when accessing memory via an opaque pointer or reference. 1790 This cap is ignored when directly accessing a variable or when the pointee 1791 type has an explicit “aligned” attribute. 1792 1793 The value should usually be determined by the properties of the system allocator. 1794 Some builtin types, especially vector types, have very high natural alignments; 1795 when working with values of those types, Clang usually wants to use instructions 1796 that take advantage of that alignment. However, many system allocators do 1797 not promise to return memory that is more than 8-byte or 16-byte-aligned. Use 1798 this option to limit the alignment that the compiler can assume for an arbitrary 1799 pointer, which may point onto the heap. 1800 1801 This option does not affect the ABI alignment of types; the layout of structs and 1802 unions and the value returned by the alignof operator remain the same. 1803 1804 This option can be overridden on a case-by-case basis by putting an explicit 1805 “aligned” alignment on a struct, union, or typedef. For example: 1806 1807 .. code-block:: console 1808 1809 #include <immintrin.h> 1810 // Make an aligned typedef of the AVX-512 16-int vector type. 1811 typedef __v16si __aligned_v16si __attribute__((aligned(64))); 1812 1813 void initialize_vector(__aligned_v16si *v) { 1814 // The compiler may assume that ‘v’ is 64-byte aligned, regardless of the 1815 // value of -fmax-type-align. 1816 } 1817 1818.. option:: -faddrsig, -fno-addrsig 1819 1820 Controls whether Clang emits an address-significance table into the object 1821 file. Address-significance tables allow linkers to implement `safe ICF 1822 <https://research.google.com/pubs/archive/36912.pdf>`_ without the false 1823 positives that can result from other implementation techniques such as 1824 relocation scanning. Address-significance tables are enabled by default 1825 on ELF targets when using the integrated assembler. This flag currently 1826 only has an effect on ELF targets. 1827 1828**-f[no]-unique-internal-linkage-names** 1829 1830 Controls whether Clang emits a unique (best-effort) symbol name for internal 1831 linkage symbols. When this option is set, compiler hashes the main source 1832 file path from the command line and appends it to all internal symbols. If a 1833 program contains multiple objects compiled with the same command-line source 1834 file path, the symbols are not guaranteed to be unique. This option is 1835 particularly useful in attributing profile information to the correct 1836 function when multiple functions with the same private linkage name exist 1837 in the binary. 1838 1839 It should be noted that this option cannot guarantee uniqueness and the 1840 following is an example where it is not unique when two modules contain 1841 symbols with the same private linkage name: 1842 1843 .. code-block:: console 1844 1845 $ cd $P/foo && clang -c -funique-internal-linkage-names name_conflict.c 1846 $ cd $P/bar && clang -c -funique-internal-linkage-names name_conflict.c 1847 $ cd $P && clang foo/name_conflict.o && bar/name_conflict.o 1848 1849**-fbasic-block-sections=[labels, all, list=<arg>, none]** 1850 1851 Controls how Clang emits text sections for basic blocks. With values ``all`` 1852 and ``list=<arg>``, each basic block or a subset of basic blocks can be placed 1853 in its own unique section. With the "labels" value, normal text sections are 1854 emitted, but a ``.bb_addr_map`` section is emitted which includes address 1855 offsets for each basic block in the program, relative to the parent function 1856 address. 1857 1858 With the ``list=<arg>`` option, a file containing the subset of basic blocks 1859 that need to placed in unique sections can be specified. The format of the 1860 file is as follows. For example, ``list=spec.txt`` where ``spec.txt`` is the 1861 following: 1862 1863 :: 1864 1865 !foo 1866 !!2 1867 !_Z3barv 1868 1869 will place the machine basic block with ``id 2`` in function ``foo`` in a 1870 unique section. It will also place all basic blocks of functions ``bar`` 1871 in unique sections. 1872 1873 Further, section clusters can also be specified using the ``list=<arg>`` 1874 option. For example, ``list=spec.txt`` where ``spec.txt`` contains: 1875 1876 :: 1877 1878 !foo 1879 !!1 !!3 !!5 1880 !!2 !!4 !!6 1881 1882 will create two unique sections for function ``foo`` with the first 1883 containing the odd numbered basic blocks and the second containing the 1884 even numbered basic blocks. 1885 1886 Basic block sections allow the linker to reorder basic blocks and enables 1887 link-time optimizations like whole program inter-procedural basic block 1888 reordering. 1889 1890Profile Guided Optimization 1891--------------------------- 1892 1893Profile information enables better optimization. For example, knowing that a 1894branch is taken very frequently helps the compiler make better decisions when 1895ordering basic blocks. Knowing that a function ``foo`` is called more 1896frequently than another function ``bar`` helps the inliner. Optimization 1897levels ``-O2`` and above are recommended for use of profile guided optimization. 1898 1899Clang supports profile guided optimization with two different kinds of 1900profiling. A sampling profiler can generate a profile with very low runtime 1901overhead, or you can build an instrumented version of the code that collects 1902more detailed profile information. Both kinds of profiles can provide execution 1903counts for instructions in the code and information on branches taken and 1904function invocation. 1905 1906Regardless of which kind of profiling you use, be careful to collect profiles 1907by running your code with inputs that are representative of the typical 1908behavior. Code that is not exercised in the profile will be optimized as if it 1909is unimportant, and the compiler may make poor optimization choices for code 1910that is disproportionately used while profiling. 1911 1912Differences Between Sampling and Instrumentation 1913^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1914 1915Although both techniques are used for similar purposes, there are important 1916differences between the two: 1917 19181. Profile data generated with one cannot be used by the other, and there is no 1919 conversion tool that can convert one to the other. So, a profile generated 1920 via ``-fprofile-instr-generate`` must be used with ``-fprofile-instr-use``. 1921 Similarly, sampling profiles generated by external profilers must be 1922 converted and used with ``-fprofile-sample-use``. 1923 19242. Instrumentation profile data can be used for code coverage analysis and 1925 optimization. 1926 19273. Sampling profiles can only be used for optimization. They cannot be used for 1928 code coverage analysis. Although it would be technically possible to use 1929 sampling profiles for code coverage, sample-based profiles are too 1930 coarse-grained for code coverage purposes; it would yield poor results. 1931 19324. Sampling profiles must be generated by an external tool. The profile 1933 generated by that tool must then be converted into a format that can be read 1934 by LLVM. The section on sampling profilers describes one of the supported 1935 sampling profile formats. 1936 1937 1938Using Sampling Profilers 1939^^^^^^^^^^^^^^^^^^^^^^^^ 1940 1941Sampling profilers are used to collect runtime information, such as 1942hardware counters, while your application executes. They are typically 1943very efficient and do not incur a large runtime overhead. The 1944sample data collected by the profiler can be used during compilation 1945to determine what the most executed areas of the code are. 1946 1947Using the data from a sample profiler requires some changes in the way 1948a program is built. Before the compiler can use profiling information, 1949the code needs to execute under the profiler. The following is the 1950usual build cycle when using sample profilers for optimization: 1951 19521. Build the code with source line table information. You can use all the 1953 usual build flags that you always build your application with. The only 1954 requirement is that you add ``-gline-tables-only`` or ``-g`` to the 1955 command line. This is important for the profiler to be able to map 1956 instructions back to source line locations. 1957 1958 .. code-block:: console 1959 1960 $ clang++ -O2 -gline-tables-only code.cc -o code 1961 19622. Run the executable under a sampling profiler. The specific profiler 1963 you use does not really matter, as long as its output can be converted 1964 into the format that the LLVM optimizer understands. Currently, there 1965 exists a conversion tool for the Linux Perf profiler 1966 (https://perf.wiki.kernel.org/), so these examples assume that you 1967 are using Linux Perf to profile your code. 1968 1969 .. code-block:: console 1970 1971 $ perf record -b ./code 1972 1973 Note the use of the ``-b`` flag. This tells Perf to use the Last Branch 1974 Record (LBR) to record call chains. While this is not strictly required, 1975 it provides better call information, which improves the accuracy of 1976 the profile data. 1977 19783. Convert the collected profile data to LLVM's sample profile format. 1979 This is currently supported via the AutoFDO converter ``create_llvm_prof``. 1980 It is available at https://github.com/google/autofdo. Once built and 1981 installed, you can convert the ``perf.data`` file to LLVM using 1982 the command: 1983 1984 .. code-block:: console 1985 1986 $ create_llvm_prof --binary=./code --out=code.prof 1987 1988 This will read ``perf.data`` and the binary file ``./code`` and emit 1989 the profile data in ``code.prof``. Note that if you ran ``perf`` 1990 without the ``-b`` flag, you need to use ``--use_lbr=false`` when 1991 calling ``create_llvm_prof``. 1992 19934. Build the code again using the collected profile. This step feeds 1994 the profile back to the optimizers. This should result in a binary 1995 that executes faster than the original one. Note that you are not 1996 required to build the code with the exact same arguments that you 1997 used in the first step. The only requirement is that you build the code 1998 with ``-gline-tables-only`` and ``-fprofile-sample-use``. 1999 2000 .. code-block:: console 2001 2002 $ clang++ -O2 -gline-tables-only -fprofile-sample-use=code.prof code.cc -o code 2003 2004 2005Sample Profile Formats 2006"""""""""""""""""""""" 2007 2008Since external profilers generate profile data in a variety of custom formats, 2009the data generated by the profiler must be converted into a format that can be 2010read by the backend. LLVM supports three different sample profile formats: 2011 20121. ASCII text. This is the easiest one to generate. The file is divided into 2013 sections, which correspond to each of the functions with profile 2014 information. The format is described below. It can also be generated from 2015 the binary or gcov formats using the ``llvm-profdata`` tool. 2016 20172. Binary encoding. This uses a more efficient encoding that yields smaller 2018 profile files. This is the format generated by the ``create_llvm_prof`` tool 2019 in https://github.com/google/autofdo. 2020 20213. GCC encoding. This is based on the gcov format, which is accepted by GCC. It 2022 is only interesting in environments where GCC and Clang co-exist. This 2023 encoding is only generated by the ``create_gcov`` tool in 2024 https://github.com/google/autofdo. It can be read by LLVM and 2025 ``llvm-profdata``, but it cannot be generated by either. 2026 2027If you are using Linux Perf to generate sampling profiles, you can use the 2028conversion tool ``create_llvm_prof`` described in the previous section. 2029Otherwise, you will need to write a conversion tool that converts your 2030profiler's native format into one of these three. 2031 2032 2033Sample Profile Text Format 2034"""""""""""""""""""""""""" 2035 2036This section describes the ASCII text format for sampling profiles. It is, 2037arguably, the easiest one to generate. If you are interested in generating any 2038of the other two, consult the ``ProfileData`` library in LLVM's source tree 2039(specifically, ``include/llvm/ProfileData/SampleProfReader.h``). 2040 2041.. code-block:: console 2042 2043 function1:total_samples:total_head_samples 2044 offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ] 2045 offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ] 2046 ... 2047 offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ] 2048 offsetA[.discriminator]: fnA:num_of_total_samples 2049 offsetA1[.discriminator]: number_of_samples [fn7:num fn8:num ... ] 2050 offsetA1[.discriminator]: number_of_samples [fn9:num fn10:num ... ] 2051 offsetB[.discriminator]: fnB:num_of_total_samples 2052 offsetB1[.discriminator]: number_of_samples [fn11:num fn12:num ... ] 2053 2054This is a nested tree in which the indentation represents the nesting level 2055of the inline stack. There are no blank lines in the file. And the spacing 2056within a single line is fixed. Additional spaces will result in an error 2057while reading the file. 2058 2059Any line starting with the '#' character is completely ignored. 2060 2061Inlined calls are represented with indentation. The Inline stack is a 2062stack of source locations in which the top of the stack represents the 2063leaf function, and the bottom of the stack represents the actual 2064symbol to which the instruction belongs. 2065 2066Function names must be mangled in order for the profile loader to 2067match them in the current translation unit. The two numbers in the 2068function header specify how many total samples were accumulated in the 2069function (first number), and the total number of samples accumulated 2070in the prologue of the function (second number). This head sample 2071count provides an indicator of how frequently the function is invoked. 2072 2073There are two types of lines in the function body. 2074 2075- Sampled line represents the profile information of a source location. 2076 ``offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]`` 2077 2078- Callsite line represents the profile information of an inlined callsite. 2079 ``offsetA[.discriminator]: fnA:num_of_total_samples`` 2080 2081Each sampled line may contain several items. Some are optional (marked 2082below): 2083 2084a. Source line offset. This number represents the line number 2085 in the function where the sample was collected. The line number is 2086 always relative to the line where symbol of the function is 2087 defined. So, if the function has its header at line 280, the offset 2088 13 is at line 293 in the file. 2089 2090 Note that this offset should never be a negative number. This could 2091 happen in cases like macros. The debug machinery will register the 2092 line number at the point of macro expansion. So, if the macro was 2093 expanded in a line before the start of the function, the profile 2094 converter should emit a 0 as the offset (this means that the optimizers 2095 will not be able to associate a meaningful weight to the instructions 2096 in the macro). 2097 2098b. [OPTIONAL] Discriminator. This is used if the sampled program 2099 was compiled with DWARF discriminator support 2100 (http://wiki.dwarfstd.org/index.php?title=Path_Discriminators). 2101 DWARF discriminators are unsigned integer values that allow the 2102 compiler to distinguish between multiple execution paths on the 2103 same source line location. 2104 2105 For example, consider the line of code ``if (cond) foo(); else bar();``. 2106 If the predicate ``cond`` is true 80% of the time, then the edge 2107 into function ``foo`` should be considered to be taken most of the 2108 time. But both calls to ``foo`` and ``bar`` are at the same source 2109 line, so a sample count at that line is not sufficient. The 2110 compiler needs to know which part of that line is taken more 2111 frequently. 2112 2113 This is what discriminators provide. In this case, the calls to 2114 ``foo`` and ``bar`` will be at the same line, but will have 2115 different discriminator values. This allows the compiler to correctly 2116 set edge weights into ``foo`` and ``bar``. 2117 2118c. Number of samples. This is an integer quantity representing the 2119 number of samples collected by the profiler at this source 2120 location. 2121 2122d. [OPTIONAL] Potential call targets and samples. If present, this 2123 line contains a call instruction. This models both direct and 2124 number of samples. For example, 2125 2126 .. code-block:: console 2127 2128 130: 7 foo:3 bar:2 baz:7 2129 2130 The above means that at relative line offset 130 there is a call 2131 instruction that calls one of ``foo()``, ``bar()`` and ``baz()``, 2132 with ``baz()`` being the relatively more frequently called target. 2133 2134As an example, consider a program with the call chain ``main -> foo -> bar``. 2135When built with optimizations enabled, the compiler may inline the 2136calls to ``bar`` and ``foo`` inside ``main``. The generated profile 2137could then be something like this: 2138 2139.. code-block:: console 2140 2141 main:35504:0 2142 1: _Z3foov:35504 2143 2: _Z32bari:31977 2144 1.1: 31977 2145 2: 0 2146 2147This profile indicates that there were a total of 35,504 samples 2148collected in main. All of those were at line 1 (the call to ``foo``). 2149Of those, 31,977 were spent inside the body of ``bar``. The last line 2150of the profile (``2: 0``) corresponds to line 2 inside ``main``. No 2151samples were collected there. 2152 2153Profiling with Instrumentation 2154^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2155 2156Clang also supports profiling via instrumentation. This requires building a 2157special instrumented version of the code and has some runtime 2158overhead during the profiling, but it provides more detailed results than a 2159sampling profiler. It also provides reproducible results, at least to the 2160extent that the code behaves consistently across runs. 2161 2162Here are the steps for using profile guided optimization with 2163instrumentation: 2164 21651. Build an instrumented version of the code by compiling and linking with the 2166 ``-fprofile-instr-generate`` option. 2167 2168 .. code-block:: console 2169 2170 $ clang++ -O2 -fprofile-instr-generate code.cc -o code 2171 21722. Run the instrumented executable with inputs that reflect the typical usage. 2173 By default, the profile data will be written to a ``default.profraw`` file 2174 in the current directory. You can override that default by using option 2175 ``-fprofile-instr-generate=`` or by setting the ``LLVM_PROFILE_FILE`` 2176 environment variable to specify an alternate file. If non-default file name 2177 is specified by both the environment variable and the command line option, 2178 the environment variable takes precedence. The file name pattern specified 2179 can include different modifiers: ``%p``, ``%h``, and ``%m``. 2180 2181 Any instance of ``%p`` in that file name will be replaced by the process 2182 ID, so that you can easily distinguish the profile output from multiple 2183 runs. 2184 2185 .. code-block:: console 2186 2187 $ LLVM_PROFILE_FILE="code-%p.profraw" ./code 2188 2189 The modifier ``%h`` can be used in scenarios where the same instrumented 2190 binary is run in multiple different host machines dumping profile data 2191 to a shared network based storage. The ``%h`` specifier will be substituted 2192 with the hostname so that profiles collected from different hosts do not 2193 clobber each other. 2194 2195 While the use of ``%p`` specifier can reduce the likelihood for the profiles 2196 dumped from different processes to clobber each other, such clobbering can still 2197 happen because of the ``pid`` re-use by the OS. Another side-effect of using 2198 ``%p`` is that the storage requirement for raw profile data files is greatly 2199 increased. To avoid issues like this, the ``%m`` specifier can used in the profile 2200 name. When this specifier is used, the profiler runtime will substitute ``%m`` 2201 with a unique integer identifier associated with the instrumented binary. Additionally, 2202 multiple raw profiles dumped from different processes that share a file system (can be 2203 on different hosts) will be automatically merged by the profiler runtime during the 2204 dumping. If the program links in multiple instrumented shared libraries, each library 2205 will dump the profile data into its own profile data file (with its unique integer 2206 id embedded in the profile name). Note that the merging enabled by ``%m`` is for raw 2207 profile data generated by profiler runtime. The resulting merged "raw" profile data 2208 file still needs to be converted to a different format expected by the compiler ( 2209 see step 3 below). 2210 2211 .. code-block:: console 2212 2213 $ LLVM_PROFILE_FILE="code-%m.profraw" ./code 2214 2215 22163. Combine profiles from multiple runs and convert the "raw" profile format to 2217 the input expected by clang. Use the ``merge`` command of the 2218 ``llvm-profdata`` tool to do this. 2219 2220 .. code-block:: console 2221 2222 $ llvm-profdata merge -output=code.profdata code-*.profraw 2223 2224 Note that this step is necessary even when there is only one "raw" profile, 2225 since the merge operation also changes the file format. 2226 22274. Build the code again using the ``-fprofile-instr-use`` option to specify the 2228 collected profile data. 2229 2230 .. code-block:: console 2231 2232 $ clang++ -O2 -fprofile-instr-use=code.profdata code.cc -o code 2233 2234 You can repeat step 4 as often as you like without regenerating the 2235 profile. As you make changes to your code, clang may no longer be able to 2236 use the profile data. It will warn you when this happens. 2237 2238Profile generation using an alternative instrumentation method can be 2239controlled by the GCC-compatible flags ``-fprofile-generate`` and 2240``-fprofile-use``. Although these flags are semantically equivalent to 2241their GCC counterparts, they *do not* handle GCC-compatible profiles. 2242They are only meant to implement GCC's semantics with respect to 2243profile creation and use. Flag ``-fcs-profile-generate`` also instruments 2244programs using the same instrumentation method as ``-fprofile-generate``. 2245 2246.. option:: -fprofile-generate[=<dirname>] 2247 2248 The ``-fprofile-generate`` and ``-fprofile-generate=`` flags will use 2249 an alternative instrumentation method for profile generation. When 2250 given a directory name, it generates the profile file 2251 ``default_%m.profraw`` in the directory named ``dirname`` if specified. 2252 If ``dirname`` does not exist, it will be created at runtime. ``%m`` specifier 2253 will be substituted with a unique id documented in step 2 above. In other words, 2254 with ``-fprofile-generate[=<dirname>]`` option, the "raw" profile data automatic 2255 merging is turned on by default, so there will no longer any risk of profile 2256 clobbering from different running processes. For example, 2257 2258 .. code-block:: console 2259 2260 $ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code 2261 2262 When ``code`` is executed, the profile will be written to the file 2263 ``yyy/zzz/default_xxxx.profraw``. 2264 2265 To generate the profile data file with the compiler readable format, the 2266 ``llvm-profdata`` tool can be used with the profile directory as the input: 2267 2268 .. code-block:: console 2269 2270 $ llvm-profdata merge -output=code.profdata yyy/zzz/ 2271 2272 If the user wants to turn off the auto-merging feature, or simply override the 2273 the profile dumping path specified at command line, the environment variable 2274 ``LLVM_PROFILE_FILE`` can still be used to override 2275 the directory and filename for the profile file at runtime. 2276 2277.. option:: -fcs-profile-generate[=<dirname>] 2278 2279 The ``-fcs-profile-generate`` and ``-fcs-profile-generate=`` flags will use 2280 the same instrumentation method, and generate the same profile as in the 2281 ``-fprofile-generate`` and ``-fprofile-generate=`` flags. The difference is 2282 that the instrumentation is performed after inlining so that the resulted 2283 profile has a better context sensitive information. They cannot be used 2284 together with ``-fprofile-generate`` and ``-fprofile-generate=`` flags. 2285 They are typically used in conjunction with ``-fprofile-use`` flag. 2286 The profile generated by ``-fcs-profile-generate`` and ``-fprofile-generate`` 2287 can be merged by llvm-profdata. A use example: 2288 2289 .. code-block:: console 2290 2291 $ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code 2292 $ ./code 2293 $ llvm-profdata merge -output=code.profdata yyy/zzz/ 2294 2295 The first few steps are the same as that in ``-fprofile-generate`` 2296 compilation. Then perform a second round of instrumentation. 2297 2298 .. code-block:: console 2299 2300 $ clang++ -O2 -fprofile-use=code.profdata -fcs-profile-generate=sss/ttt \ 2301 -o cs_code 2302 $ ./cs_code 2303 $ llvm-profdata merge -output=cs_code.profdata sss/ttt code.profdata 2304 2305 The resulted ``cs_code.prodata`` combines ``code.profdata`` and the profile 2306 generated from binary ``cs_code``. Profile ``cs_code.profata`` can be used by 2307 ``-fprofile-use`` compilation. 2308 2309 .. code-block:: console 2310 2311 $ clang++ -O2 -fprofile-use=cs_code.profdata 2312 2313 The above command will read both profiles to the compiler at the identical 2314 point of instrumentations. 2315 2316.. option:: -fprofile-use[=<pathname>] 2317 2318 Without any other arguments, ``-fprofile-use`` behaves identically to 2319 ``-fprofile-instr-use``. Otherwise, if ``pathname`` is the full path to a 2320 profile file, it reads from that file. If ``pathname`` is a directory name, 2321 it reads from ``pathname/default.profdata``. 2322 2323.. option:: -fprofile-update[=<method>] 2324 2325 Unless ``-fsanitize=thread`` is specified, the default is ``single``, which 2326 uses non-atomic increments. The counters can be inaccurate under thread 2327 contention. ``atomic`` uses atomic increments which is accurate but has 2328 overhead. ``prefer-atomic`` will be transformed to ``atomic`` when supported 2329 by the target, or ``single`` otherwise. 2330 2331 This option currently works with ``-fprofile-arcs`` and ``-fprofile-instr-generate``, 2332 but not with ``-fprofile-generate``. 2333 2334Disabling Instrumentation 2335^^^^^^^^^^^^^^^^^^^^^^^^^ 2336 2337In certain situations, it may be useful to disable profile generation or use 2338for specific files in a build, without affecting the main compilation flags 2339used for the other files in the project. 2340 2341In these cases, you can use the flag ``-fno-profile-instr-generate`` (or 2342``-fno-profile-generate``) to disable profile generation, and 2343``-fno-profile-instr-use`` (or ``-fno-profile-use``) to disable profile use. 2344 2345Note that these flags should appear after the corresponding profile 2346flags to have an effect. 2347 2348.. note:: 2349 2350 When none of the translation units inside a binary is instrumented, in the 2351 case of Fuchsia the profile runtime will not be linked into the binary and 2352 no profile will be produced, while on other platforms the profile runtime 2353 will be linked and profile will be produced but there will not be any 2354 counters. 2355 2356Instrumenting only selected files or functions 2357^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2358 2359Sometimes it's useful to only instrument certain files or functions. For 2360example in automated testing infrastructure, it may be desirable to only 2361instrument files or functions that were modified by a patch to reduce the 2362overhead of instrumenting a full system. 2363 2364This can be done using the ``-fprofile-list`` option. 2365 2366.. option:: -fprofile-list=<pathname> 2367 2368 This option can be used to apply profile instrumentation only to selected 2369 files or functions. ``pathname`` should point to a file in the 2370 :doc:`SanitizerSpecialCaseList` format which selects which files and 2371 functions to instrument. 2372 2373 .. code-block:: console 2374 2375 $ echo "fun:test" > fun.list 2376 $ clang++ -O2 -fprofile-instr-generate -fprofile-list=fun.list code.cc -o code 2377 2378The option can be specified multiple times to pass multiple files. 2379 2380.. code-block:: console 2381 2382 $ echo "!fun:*test*" > fun.list 2383 $ echo "src:code.cc" > src.list 2384 % clang++ -O2 -fprofile-instr-generate -fcoverage-mapping -fprofile-list=fun.list -fprofile-list=code.list code.cc -o code 2385 2386To filter individual functions or entire source files using ``fun:<name>`` or 2387``src:<file>`` respectively. To exclude a function or a source file, use 2388``!fun:<name>`` or ``!src:<file>`` respectively. The format also supports 2389wildcard expansion. The compiler generated functions are assumed to be located 2390in the main source file. It is also possible to restrict the filter to a 2391particular instrumentation type by using a named section. 2392 2393.. code-block:: none 2394 2395 # all functions whose name starts with foo will be instrumented. 2396 fun:foo* 2397 2398 # except for foo1 which will be excluded from instrumentation. 2399 !fun:foo1 2400 2401 # every function in path/to/foo.cc will be instrumented. 2402 src:path/to/foo.cc 2403 2404 # bar will be instrumented only when using backend instrumentation. 2405 # Recognized section names are clang, llvm and csllvm. 2406 [llvm] 2407 fun:bar 2408 2409When the file contains only excludes, all files and functions except for the 2410excluded ones will be instrumented. Otherwise, only the files and functions 2411specified will be instrumented. 2412 2413Profile remapping 2414^^^^^^^^^^^^^^^^^ 2415 2416When the program is compiled after a change that affects many symbol names, 2417pre-existing profile data may no longer match the program. For example: 2418 2419 * switching from libstdc++ to libc++ will result in the mangled names of all 2420 functions taking standard library types to change 2421 * renaming a widely-used type in C++ will result in the mangled names of all 2422 functions that have parameters involving that type to change 2423 * moving from a 32-bit compilation to a 64-bit compilation may change the 2424 underlying type of ``size_t`` and similar types, resulting in changes to 2425 manglings 2426 2427Clang allows use of a profile remapping file to specify that such differences 2428in mangled names should be ignored when matching the profile data against the 2429program. 2430 2431.. option:: -fprofile-remapping-file=<file> 2432 2433 Specifies a file containing profile remapping information, that will be 2434 used to match mangled names in the profile data to mangled names in the 2435 program. 2436 2437The profile remapping file is a text file containing lines of the form 2438 2439.. code-block:: text 2440 2441 fragmentkind fragment1 fragment2 2442 2443where ``fragmentkind`` is one of ``name``, ``type``, or ``encoding``, 2444indicating whether the following mangled name fragments are 2445<`name <https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.name>`_>s, 2446<`type <https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.type>`_>s, or 2447<`encoding <https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.encoding>`_>s, 2448respectively. 2449Blank lines and lines starting with ``#`` are ignored. 2450 2451For convenience, built-in <substitution>s such as ``St`` and ``Ss`` 2452are accepted as <name>s (even though they technically are not <name>s). 2453 2454For example, to specify that ``absl::string_view`` and ``std::string_view`` 2455should be treated as equivalent when matching profile data, the following 2456remapping file could be used: 2457 2458.. code-block:: text 2459 2460 # absl::string_view is considered equivalent to std::string_view 2461 type N4absl11string_viewE St17basic_string_viewIcSt11char_traitsIcEE 2462 2463 # std:: might be std::__1:: in libc++ or std::__cxx11:: in libstdc++ 2464 name 3std St3__1 2465 name 3std St7__cxx11 2466 2467Matching profile data using a profile remapping file is supported on a 2468best-effort basis. For example, information regarding indirect call targets is 2469currently not remapped. For best results, you are encouraged to generate new 2470profile data matching the updated program, or to remap the profile data 2471using the ``llvm-cxxmap`` and ``llvm-profdata merge`` tools. 2472 2473.. note:: 2474 2475 Profile data remapping support is currently only implemented for LLVM's 2476 new pass manager, which can be enabled with 2477 ``-fexperimental-new-pass-manager``. 2478 2479.. note:: 2480 2481 Profile data remapping is currently only supported for C++ mangled names 2482 following the Itanium C++ ABI mangling scheme. This covers all C++ targets 2483 supported by Clang other than Windows. 2484 2485GCOV-based Profiling 2486-------------------- 2487 2488GCOV is a test coverage program, it helps to know how often a line of code 2489is executed. When instrumenting the code with ``--coverage`` option, some 2490counters are added for each edge linking basic blocks. 2491 2492At compile time, gcno files are generated containing information about 2493blocks and edges between them. At runtime the counters are incremented and at 2494exit the counters are dumped in gcda files. 2495 2496The tool ``llvm-cov gcov`` will parse gcno, gcda and source files to generate 2497a report ``.c.gcov``. 2498 2499.. option:: -fprofile-filter-files=[regexes] 2500 2501 Define a list of regexes separated by a semi-colon. 2502 If a file name matches any of the regexes then the file is instrumented. 2503 2504 .. code-block:: console 2505 2506 $ clang --coverage -fprofile-filter-files=".*\.c$" foo.c 2507 2508 For example, this will only instrument files finishing with ``.c``, skipping ``.h`` files. 2509 2510.. option:: -fprofile-exclude-files=[regexes] 2511 2512 Define a list of regexes separated by a semi-colon. 2513 If a file name doesn't match all the regexes then the file is instrumented. 2514 2515 .. code-block:: console 2516 2517 $ clang --coverage -fprofile-exclude-files="^/usr/include/.*$" foo.c 2518 2519 For example, this will instrument all the files except the ones in ``/usr/include``. 2520 2521If both options are used then a file is instrumented if its name matches any 2522of the regexes from ``-fprofile-filter-list`` and doesn't match all the regexes 2523from ``-fprofile-exclude-list``. 2524 2525.. code-block:: console 2526 2527 $ clang --coverage -fprofile-exclude-files="^/usr/include/.*$" \ 2528 -fprofile-filter-files="^/usr/.*$" 2529 2530In that case ``/usr/foo/oof.h`` is instrumented since it matches the filter regex and 2531doesn't match the exclude regex, but ``/usr/include/foo.h`` doesn't since it matches 2532the exclude regex. 2533 2534Controlling Debug Information 2535----------------------------- 2536 2537Controlling Size of Debug Information 2538^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2539 2540Debug info kind generated by Clang can be set by one of the flags listed 2541below. If multiple flags are present, the last one is used. 2542 2543.. option:: -g0 2544 2545 Don't generate any debug info (default). 2546 2547.. option:: -gline-tables-only 2548 2549 Generate line number tables only. 2550 2551 This kind of debug info allows to obtain stack traces with function names, 2552 file names and line numbers (by such tools as ``gdb`` or ``addr2line``). It 2553 doesn't contain any other data (e.g. description of local variables or 2554 function parameters). 2555 2556.. option:: -fstandalone-debug 2557 2558 Clang supports a number of optimizations to reduce the size of debug 2559 information in the binary. They work based on the assumption that 2560 the debug type information can be spread out over multiple 2561 compilation units. For instance, Clang will not emit type 2562 definitions for types that are not needed by a module and could be 2563 replaced with a forward declaration. Further, Clang will only emit 2564 type info for a dynamic C++ class in the module that contains the 2565 vtable for the class. 2566 2567 The **-fstandalone-debug** option turns off these optimizations. 2568 This is useful when working with 3rd-party libraries that don't come 2569 with debug information. Note that Clang will never emit type 2570 information for types that are not referenced at all by the program. 2571 2572.. option:: -fno-standalone-debug 2573 2574 On Darwin **-fstandalone-debug** is enabled by default. The 2575 **-fno-standalone-debug** option can be used to get to turn on the 2576 vtable-based optimization described above. 2577 2578.. option:: -fuse-ctor-homing 2579 2580 This optimization is similar to the optimizations that are enabled as part 2581 of -fno-standalone-debug. Here, Clang only emits type info for a 2582 non-trivial, non-aggregate C++ class in the modules that contain a 2583 definition of one of its constructors. This relies on the additional 2584 assumption that all classes that are not trivially constructible have a 2585 non-trivial constructor that is used somewhere. The negation, 2586 -fno-use-ctor-homing, ensures that constructor homing is not used. 2587 2588 This flag is not enabled by default, and needs to be used with -cc1 or 2589 -Xclang. 2590 2591.. option:: -g 2592 2593 Generate complete debug info. 2594 2595.. option:: -feliminate-unused-debug-types 2596 2597 By default, Clang does not emit type information for types that are defined 2598 but not used in a program. To retain the debug info for these unused types, 2599 the negation **-fno-eliminate-unused-debug-types** can be used. 2600 2601Controlling Macro Debug Info Generation 2602^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2603 2604Debug info for C preprocessor macros increases the size of debug information in 2605the binary. Macro debug info generated by Clang can be controlled by the flags 2606listed below. 2607 2608.. option:: -fdebug-macro 2609 2610 Generate debug info for preprocessor macros. This flag is discarded when 2611 **-g0** is enabled. 2612 2613.. option:: -fno-debug-macro 2614 2615 Do not generate debug info for preprocessor macros (default). 2616 2617Controlling Debugger "Tuning" 2618^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2619 2620While Clang generally emits standard DWARF debug info (http://dwarfstd.org), 2621different debuggers may know how to take advantage of different specific DWARF 2622features. You can "tune" the debug info for one of several different debuggers. 2623 2624.. option:: -ggdb, -glldb, -gsce, -gdbx 2625 2626 Tune the debug info for the ``gdb``, ``lldb``, Sony PlayStation\ |reg| 2627 debugger, or ``dbx``, respectively. Each of these options implies **-g**. 2628 (Therefore, if you want both **-gline-tables-only** and debugger tuning, the 2629 tuning option must come first.) 2630 2631Controlling LLVM IR Output 2632-------------------------- 2633 2634Controlling Value Names in LLVM IR 2635^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2636 2637Emitting value names in LLVM IR increases the size and verbosity of the IR. 2638By default, value names are only emitted in assertion-enabled builds of Clang. 2639However, when reading IR it can be useful to re-enable the emission of value 2640names to improve readability. 2641 2642.. option:: -fdiscard-value-names 2643 2644 Discard value names when generating LLVM IR. 2645 2646.. option:: -fno-discard-value-names 2647 2648 Do not discard value names when generating LLVM IR. This option can be used 2649 to re-enable names for release builds of Clang. 2650 2651 2652Comment Parsing Options 2653----------------------- 2654 2655Clang parses Doxygen and non-Doxygen style documentation comments and attaches 2656them to the appropriate declaration nodes. By default, it only parses 2657Doxygen-style comments and ignores ordinary comments starting with ``//`` and 2658``/*``. 2659 2660.. option:: -Wdocumentation 2661 2662 Emit warnings about use of documentation comments. This warning group is off 2663 by default. 2664 2665 This includes checking that ``\param`` commands name parameters that actually 2666 present in the function signature, checking that ``\returns`` is used only on 2667 functions that actually return a value etc. 2668 2669.. option:: -Wno-documentation-unknown-command 2670 2671 Don't warn when encountering an unknown Doxygen command. 2672 2673.. option:: -fparse-all-comments 2674 2675 Parse all comments as documentation comments (including ordinary comments 2676 starting with ``//`` and ``/*``). 2677 2678.. option:: -fcomment-block-commands=[commands] 2679 2680 Define custom documentation commands as block commands. This allows Clang to 2681 construct the correct AST for these custom commands, and silences warnings 2682 about unknown commands. Several commands must be separated by a comma 2683 *without trailing space*; e.g. ``-fcomment-block-commands=foo,bar`` defines 2684 custom commands ``\foo`` and ``\bar``. 2685 2686 It is also possible to use ``-fcomment-block-commands`` several times; e.g. 2687 ``-fcomment-block-commands=foo -fcomment-block-commands=bar`` does the same 2688 as above. 2689 2690.. _c: 2691 2692C Language Features 2693=================== 2694 2695The support for standard C in clang is feature-complete except for the 2696C99 floating-point pragmas. 2697 2698Extensions supported by clang 2699----------------------------- 2700 2701See :doc:`LanguageExtensions`. 2702 2703Differences between various standard modes 2704------------------------------------------ 2705 2706clang supports the -std option, which changes what language mode clang uses. 2707The supported modes for C are c89, gnu89, c94, c99, gnu99, c11, gnu11, c17, 2708gnu17, c2x, gnu2x, and various aliases for those modes. If no -std option is 2709specified, clang defaults to gnu17 mode. Many C99 and C11 features are 2710supported in earlier modes as a conforming extension, with a warning. Use 2711``-pedantic-errors`` to request an error if a feature from a later standard 2712revision is used in an earlier mode. 2713 2714Differences between all ``c*`` and ``gnu*`` modes: 2715 2716- ``c*`` modes define "``__STRICT_ANSI__``". 2717- Target-specific defines not prefixed by underscores, like ``linux``, 2718 are defined in ``gnu*`` modes. 2719- Trigraphs default to being off in ``gnu*`` modes; they can be enabled 2720 by the ``-trigraphs`` option. 2721- The parser recognizes ``asm`` and ``typeof`` as keywords in ``gnu*`` modes; 2722 the variants ``__asm__`` and ``__typeof__`` are recognized in all modes. 2723- The parser recognizes ``inline`` as a keyword in ``gnu*`` mode, in 2724 addition to recognizing it in the ``*99`` and later modes for which it is 2725 part of the ISO C standard. The variant ``__inline__`` is recognized in all 2726 modes. 2727- The Apple "blocks" extension is recognized by default in ``gnu*`` modes 2728 on some platforms; it can be enabled in any mode with the ``-fblocks`` 2729 option. 2730 2731Differences between ``*89`` and ``*94`` modes: 2732 2733- Digraphs are not recognized in c89 mode. 2734 2735Differences between ``*94`` and ``*99`` modes: 2736 2737- The ``*99`` modes default to implementing ``inline`` / ``__inline__`` 2738 as specified in C99, while the ``*89`` modes implement the GNU version. 2739 This can be overridden for individual functions with the ``__gnu_inline__`` 2740 attribute. 2741- The scope of names defined inside a ``for``, ``if``, ``switch``, ``while``, 2742 or ``do`` statement is different. (example: ``if ((struct x {int x;}*)0) {}``.) 2743- ``__STDC_VERSION__`` is not defined in ``*89`` modes. 2744- ``inline`` is not recognized as a keyword in ``c89`` mode. 2745- ``restrict`` is not recognized as a keyword in ``*89`` modes. 2746- Commas are allowed in integer constant expressions in ``*99`` modes. 2747- Arrays which are not lvalues are not implicitly promoted to pointers 2748 in ``*89`` modes. 2749- Some warnings are different. 2750 2751Differences between ``*99`` and ``*11`` modes: 2752 2753- Warnings for use of C11 features are disabled. 2754- ``__STDC_VERSION__`` is defined to ``201112L`` rather than ``199901L``. 2755 2756Differences between ``*11`` and ``*17`` modes: 2757 2758- ``__STDC_VERSION__`` is defined to ``201710L`` rather than ``201112L``. 2759 2760GCC extensions not implemented yet 2761---------------------------------- 2762 2763clang tries to be compatible with gcc as much as possible, but some gcc 2764extensions are not implemented yet: 2765 2766- clang does not support decimal floating point types (``_Decimal32`` and 2767 friends) yet. 2768- clang does not support nested functions; this is a complex feature 2769 which is infrequently used, so it is unlikely to be implemented 2770 anytime soon. In C++11 it can be emulated by assigning lambda 2771 functions to local variables, e.g: 2772 2773 .. code-block:: cpp 2774 2775 auto const local_function = [&](int parameter) { 2776 // Do something 2777 }; 2778 ... 2779 local_function(1); 2780 2781- clang only supports global register variables when the register specified 2782 is non-allocatable (e.g. the stack pointer). Support for general global 2783 register variables is unlikely to be implemented soon because it requires 2784 additional LLVM backend support. 2785- clang does not support static initialization of flexible array 2786 members. This appears to be a rarely used extension, but could be 2787 implemented pending user demand. 2788- clang does not support 2789 ``__builtin_va_arg_pack``/``__builtin_va_arg_pack_len``. This is 2790 used rarely, but in some potentially interesting places, like the 2791 glibc headers, so it may be implemented pending user demand. Note 2792 that because clang pretends to be like GCC 4.2, and this extension 2793 was introduced in 4.3, the glibc headers will not try to use this 2794 extension with clang at the moment. 2795- clang does not support the gcc extension for forward-declaring 2796 function parameters; this has not shown up in any real-world code 2797 yet, though, so it might never be implemented. 2798 2799This is not a complete list; if you find an unsupported extension 2800missing from this list, please send an e-mail to cfe-dev. This list 2801currently excludes C++; see :ref:`C++ Language Features <cxx>`. Also, this 2802list does not include bugs in mostly-implemented features; please see 2803the `bug 2804tracker <https://bugs.llvm.org/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer>`_ 2805for known existing bugs (FIXME: Is there a section for bug-reporting 2806guidelines somewhere?). 2807 2808Intentionally unsupported GCC extensions 2809---------------------------------------- 2810 2811- clang does not support the gcc extension that allows variable-length 2812 arrays in structures. This is for a few reasons: one, it is tricky to 2813 implement, two, the extension is completely undocumented, and three, 2814 the extension appears to be rarely used. Note that clang *does* 2815 support flexible array members (arrays with a zero or unspecified 2816 size at the end of a structure). 2817- GCC accepts many expression forms that are not valid integer constant 2818 expressions in bit-field widths, enumerator constants, case labels, 2819 and in array bounds at global scope. Clang also accepts additional 2820 expression forms in these contexts, but constructs that GCC accepts due to 2821 simplifications GCC performs while parsing, such as ``x - x`` (where ``x`` is a 2822 variable) will likely never be accepted by Clang. 2823- clang does not support ``__builtin_apply`` and friends; this extension 2824 is extremely obscure and difficult to implement reliably. 2825 2826.. _c_ms: 2827 2828Microsoft extensions 2829-------------------- 2830 2831clang has support for many extensions from Microsoft Visual C++. To enable these 2832extensions, use the ``-fms-extensions`` command-line option. This is the default 2833for Windows targets. Clang does not implement every pragma or declspec provided 2834by MSVC, but the popular ones, such as ``__declspec(dllexport)`` and ``#pragma 2835comment(lib)`` are well supported. 2836 2837clang has a ``-fms-compatibility`` flag that makes clang accept enough 2838invalid C++ to be able to parse most Microsoft headers. For example, it 2839allows `unqualified lookup of dependent base class members 2840<https://clang.llvm.org/compatibility.html#dep_lookup_bases>`_, which is 2841a common compatibility issue with clang. This flag is enabled by default 2842for Windows targets. 2843 2844``-fdelayed-template-parsing`` lets clang delay parsing of function template 2845definitions until the end of a translation unit. This flag is enabled by 2846default for Windows targets. 2847 2848For compatibility with existing code that compiles with MSVC, clang defines the 2849``_MSC_VER`` and ``_MSC_FULL_VER`` macros. These default to the values of 1800 2850and 180000000 respectively, making clang look like an early release of Visual 2851C++ 2013. The ``-fms-compatibility-version=`` flag overrides these values. It 2852accepts a dotted version tuple, such as 19.00.23506. Changing the MSVC 2853compatibility version makes clang behave more like that version of MSVC. For 2854example, ``-fms-compatibility-version=19`` will enable C++14 features and define 2855``char16_t`` and ``char32_t`` as builtin types. 2856 2857.. _cxx: 2858 2859C++ Language Features 2860===================== 2861 2862clang fully implements all of standard C++98 except for exported 2863templates (which were removed in C++11), all of standard C++11, 2864C++14, and C++17, and most of C++20. 2865 2866See the `C++ support in Clang <https://clang.llvm.org/cxx_status.html>` page 2867for detailed information on C++ feature support across Clang versions. 2868 2869Controlling implementation limits 2870--------------------------------- 2871 2872.. option:: -fbracket-depth=N 2873 2874 Sets the limit for nested parentheses, brackets, and braces to N. The 2875 default is 256. 2876 2877.. option:: -fconstexpr-depth=N 2878 2879 Sets the limit for recursive constexpr function invocations to N. The 2880 default is 512. 2881 2882.. option:: -fconstexpr-steps=N 2883 2884 Sets the limit for the number of full-expressions evaluated in a single 2885 constant expression evaluation. The default is 1048576. 2886 2887.. option:: -ftemplate-depth=N 2888 2889 Sets the limit for recursively nested template instantiations to N. The 2890 default is 1024. 2891 2892.. option:: -foperator-arrow-depth=N 2893 2894 Sets the limit for iterative calls to 'operator->' functions to N. The 2895 default is 256. 2896 2897.. _objc: 2898 2899Objective-C Language Features 2900============================= 2901 2902.. _objcxx: 2903 2904Objective-C++ Language Features 2905=============================== 2906 2907.. _openmp: 2908 2909OpenMP Features 2910=============== 2911 2912Clang supports all OpenMP 4.5 directives and clauses. See :doc:`OpenMPSupport` 2913for additional details. 2914 2915Use `-fopenmp` to enable OpenMP. Support for OpenMP can be disabled with 2916`-fno-openmp`. 2917 2918Use `-fopenmp-simd` to enable OpenMP simd features only, without linking 2919the runtime library; for combined constructs 2920(e.g. ``#pragma omp parallel for simd``) the non-simd directives and clauses 2921will be ignored. This can be disabled with `-fno-openmp-simd`. 2922 2923Controlling implementation limits 2924--------------------------------- 2925 2926.. option:: -fopenmp-use-tls 2927 2928 Controls code generation for OpenMP threadprivate variables. In presence of 2929 this option all threadprivate variables are generated the same way as thread 2930 local variables, using TLS support. If `-fno-openmp-use-tls` 2931 is provided or target does not support TLS, code generation for threadprivate 2932 variables relies on OpenMP runtime library. 2933 2934.. _opencl: 2935 2936OpenCL Features 2937=============== 2938 2939Clang can be used to compile OpenCL kernels for execution on a device 2940(e.g. GPU). It is possible to compile the kernel into a binary (e.g. for AMDGPU) 2941that can be uploaded to run directly on a device (e.g. using 2942`clCreateProgramWithBinary 2943<https://www.khronos.org/registry/OpenCL/specs/opencl-1.1.pdf#111>`_) or 2944into generic bitcode files loadable into other toolchains. 2945 2946Compiling to a binary using the default target from the installation can be done 2947as follows: 2948 2949 .. code-block:: console 2950 2951 $ echo "kernel void k(){}" > test.cl 2952 $ clang test.cl 2953 2954Compiling for a specific target can be done by specifying the triple corresponding 2955to the target, for example: 2956 2957 .. code-block:: console 2958 2959 $ clang -target nvptx64-unknown-unknown test.cl 2960 $ clang -target amdgcn-amd-amdhsa -mcpu=gfx900 test.cl 2961 2962Compiling to bitcode can be done as follows: 2963 2964 .. code-block:: console 2965 2966 $ clang -c -emit-llvm test.cl 2967 2968This will produce a file `test.bc` that can be used in vendor toolchains 2969to perform machine code generation. 2970 2971Note that if compiled to bitcode for generic targets such as SPIR, 2972portable IR is produced that can be used with various vendor 2973tools as well as open source tools such as `SPIRV-LLVM Translator 2974<https://github.com/KhronosGroup/SPIRV-LLVM-Translator>`_ 2975to produce SPIR-V binary. More details are provided in `the offline 2976compilation from OpenCL kernel sources into SPIR-V using open source 2977tools 2978<https://github.com/KhronosGroup/OpenCL-Guide/blob/main/chapters/os_tooling.md>`_. 2979 2980Clang currently supports OpenCL C language standards up to v2.0. Clang mainly 2981supports full profile. There is only very limited support of the embedded 2982profile. 2983Starting from clang 9 a C++ mode is available for OpenCL (see 2984:ref:`C++ for OpenCL <cxx_for_opencl>`). 2985 2986There is ongoing support for OpenCL v3.0 that is documented along with other 2987experimental functionality and features in development on :doc:`OpenCLSupport` 2988page. 2989 2990OpenCL Specific Options 2991----------------------- 2992 2993Most of the OpenCL build options from `the specification v2.0 section 5.8.4 2994<https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf#200>`_ are available. 2995 2996Examples: 2997 2998 .. code-block:: console 2999 3000 $ clang -cl-std=CL2.0 -cl-single-precision-constant test.cl 3001 3002 3003Many flags used for the compilation for C sources can also be passed while 3004compiling for OpenCL, examples: ``-c``, ``-O<1-4|s>``, ``-o``, ``-emit-llvm``, etc. 3005 3006Some extra options are available to support special OpenCL features. 3007 3008.. _opencl_cl_no_stdinc: 3009 3010.. option:: -cl-no-stdinc 3011 3012Allows to disable all extra types and functions that are not native to the compiler. 3013This might reduce the compilation speed marginally but many declarations from the 3014OpenCL standard will not be accessible. For example, the following will fail to 3015compile. 3016 3017 .. code-block:: console 3018 3019 $ echo "bool is_wg_uniform(int i){return get_enqueued_local_size(i)==get_local_size(i);}" > test.cl 3020 $ clang -cl-std=CL2.0 -cl-no-stdinc test.cl 3021 error: use of undeclared identifier 'get_enqueued_local_size' 3022 error: use of undeclared identifier 'get_local_size' 3023 3024More information about the standard types and functions is provided in :ref:`the 3025section on the OpenCL Header <opencl_header>`. 3026 3027OpenCL Targets 3028-------------- 3029 3030OpenCL targets are derived from the regular Clang target classes. The OpenCL 3031specific parts of the target representation provide address space mapping as 3032well as a set of supported extensions. 3033 3034Specific Targets 3035^^^^^^^^^^^^^^^^ 3036 3037There is a set of concrete HW architectures that OpenCL can be compiled for. 3038 3039- For AMD target: 3040 3041 .. code-block:: console 3042 3043 $ clang -target amdgcn-amd-amdhsa -mcpu=gfx900 test.cl 3044 3045- For Nvidia architectures: 3046 3047 .. code-block:: console 3048 3049 $ clang -target nvptx64-unknown-unknown test.cl 3050 3051 3052Generic Targets 3053^^^^^^^^^^^^^^^ 3054 3055- SPIR is available as a generic target to allow portable bitcode to be produced 3056 that can be used across GPU toolchains. The implementation follows `the SPIR 3057 specification <https://www.khronos.org/spir>`_. There are two flavors 3058 available for 32 and 64 bits. 3059 3060 .. code-block:: console 3061 3062 $ clang -target spir test.cl -emit-llvm -c 3063 $ clang -target spir64 test.cl -emit-llvm -c 3064 3065 All known OpenCL extensions are supported in the SPIR targets. Clang will 3066 generate SPIR v1.2 compatible IR for OpenCL versions up to 2.0 and SPIR v2.0 3067 for OpenCL v2.0 or C++ for OpenCL. 3068 3069- x86 is used by some implementations that are x86 compatible and currently 3070 remains for backwards compatibility (with older implementations prior to 3071 SPIR target support). For "non-SPMD" targets which cannot spawn multiple 3072 work-items on the fly using hardware, which covers practically all non-GPU 3073 devices such as CPUs and DSPs, additional processing is needed for the kernels 3074 to support multiple work-item execution. For this, a 3rd party toolchain, 3075 such as for example `POCL <http://portablecl.org/>`_, can be used. 3076 3077 This target does not support multiple memory segments and, therefore, the fake 3078 address space map can be added using the :ref:`-ffake-address-space-map 3079 <opencl_fake_address_space_map>` flag. 3080 3081.. _opencl_header: 3082 3083OpenCL Header 3084------------- 3085 3086By default Clang will include standard headers and therefore most of OpenCL 3087builtin functions and types are available during compilation. The 3088default declarations of non-native compiler types and functions can be disabled 3089by using flag :ref:`-cl-no-stdinc <opencl_cl_no_stdinc>`. 3090 3091The following example demonstrates that OpenCL kernel sources with various 3092standard builtin functions can be compiled without the need for an explicit 3093includes or compiler flags. 3094 3095 .. code-block:: console 3096 3097 $ echo "bool is_wg_uniform(int i){return get_enqueued_local_size(i)==get_local_size(i);}" > test.cl 3098 $ clang -cl-std=CL2.0 test.cl 3099 3100More information about the default headers is provided in :doc:`OpenCLSupport`. 3101 3102OpenCL Extensions 3103----------------- 3104 3105Most of the ``cl_khr_*`` extensions to OpenCL C from `the official OpenCL 3106registry <https://www.khronos.org/registry/OpenCL/>`_ are available and 3107configured per target depending on the support available in the specific 3108architecture. 3109 3110It is possible to alter the default extensions setting per target using 3111``-cl-ext`` flag. (See :ref:`flags description <opencl_cl_ext>` for more details). 3112 3113Vendor extensions can be added flexibly by declaring the list of types and 3114functions associated with each extensions enclosed within the following 3115compiler pragma directives: 3116 3117 .. code-block:: c 3118 3119 #pragma OPENCL EXTENSION the_new_extension_name : begin 3120 // declare types and functions associated with the extension here 3121 #pragma OPENCL EXTENSION the_new_extension_name : end 3122 3123For example, parsing the following code adds ``my_t`` type and ``my_func`` 3124function to the custom ``my_ext`` extension. 3125 3126 .. code-block:: c 3127 3128 #pragma OPENCL EXTENSION my_ext : begin 3129 typedef struct{ 3130 int a; 3131 }my_t; 3132 void my_func(my_t); 3133 #pragma OPENCL EXTENSION my_ext : end 3134 3135There is no conflict resolution for identifier clashes among extensions. 3136It is therefore recommended that the identifiers are prefixed with a 3137double underscore to avoid clashing with user space identifiers. Vendor 3138extension should use reserved identifier prefix e.g. amd, arm, intel. 3139 3140Clang also supports language extensions documented in `The OpenCL C Language 3141Extensions Documentation 3142<https://github.com/KhronosGroup/Khronosdotorg/blob/master/api/opencl/assets/OpenCL_LangExt.pdf>`_. 3143 3144OpenCL-Specific Attributes 3145-------------------------- 3146 3147OpenCL support in Clang contains a set of attribute taken directly from the 3148specification as well as additional attributes. 3149 3150See also :doc:`AttributeReference`. 3151 3152nosvm 3153^^^^^ 3154 3155Clang supports this attribute to comply to OpenCL v2.0 conformance, but it 3156does not have any effect on the IR. For more details reffer to the specification 3157`section 6.7.2 3158<https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#49>`_ 3159 3160 3161opencl_unroll_hint 3162^^^^^^^^^^^^^^^^^^ 3163 3164The implementation of this feature mirrors the unroll hint for C. 3165More details on the syntax can be found in the specification 3166`section 6.11.5 3167<https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#61>`_ 3168 3169convergent 3170^^^^^^^^^^ 3171 3172To make sure no invalid optimizations occur for single program multiple data 3173(SPMD) / single instruction multiple thread (SIMT) Clang provides attributes that 3174can be used for special functions that have cross work item semantics. 3175An example is the subgroup operations such as `intel_sub_group_shuffle 3176<https://www.khronos.org/registry/cl/extensions/intel/cl_intel_subgroups.txt>`_ 3177 3178 .. code-block:: c 3179 3180 // Define custom my_sub_group_shuffle(data, c) 3181 // that makes use of intel_sub_group_shuffle 3182 r1 = ... 3183 if (r0) r1 = computeA(); 3184 // Shuffle data from r1 into r3 3185 // of threads id r2. 3186 r3 = my_sub_group_shuffle(r1, r2); 3187 if (r0) r3 = computeB(); 3188 3189with non-SPMD semantics this is optimized to the following equivalent code: 3190 3191 .. code-block:: c 3192 3193 r1 = ... 3194 if (!r0) 3195 // Incorrect functionality! The data in r1 3196 // have not been computed by all threads yet. 3197 r3 = my_sub_group_shuffle(r1, r2); 3198 else { 3199 r1 = computeA(); 3200 r3 = my_sub_group_shuffle(r1, r2); 3201 r3 = computeB(); 3202 } 3203 3204Declaring the function ``my_sub_group_shuffle`` with the convergent attribute 3205would prevent this: 3206 3207 .. code-block:: c 3208 3209 my_sub_group_shuffle() __attribute__((convergent)); 3210 3211Using ``convergent`` guarantees correct execution by keeping CFG equivalence 3212wrt operations marked as ``convergent``. CFG ``G´`` is equivalent to ``G`` wrt 3213node ``Ni`` : ``iff ∀ Nj (i≠j)`` domination and post-domination relations with 3214respect to ``Ni`` remain the same in both ``G`` and ``G´``. 3215 3216noduplicate 3217^^^^^^^^^^^ 3218 3219``noduplicate`` is more restrictive with respect to optimizations than 3220``convergent`` because a convergent function only preserves CFG equivalence. 3221This allows some optimizations to happen as long as the control flow remains 3222unmodified. 3223 3224 .. code-block:: c 3225 3226 for (int i=0; i<4; i++) 3227 my_sub_group_shuffle() 3228 3229can be modified to: 3230 3231 .. code-block:: c 3232 3233 my_sub_group_shuffle(); 3234 my_sub_group_shuffle(); 3235 my_sub_group_shuffle(); 3236 my_sub_group_shuffle(); 3237 3238while using ``noduplicate`` would disallow this. Also ``noduplicate`` doesn't 3239have the same safe semantics of CFG as ``convergent`` and can cause changes in 3240CFG that modify semantics of the original program. 3241 3242``noduplicate`` is kept for backwards compatibility only and it considered to be 3243deprecated for future uses. 3244 3245.. _cxx_for_opencl: 3246 3247C++ for OpenCL 3248-------------- 3249 3250Starting from clang 9 kernel code can contain C++17 features: classes, templates, 3251function overloading, type deduction, etc. Please note that this is not an 3252implementation of `OpenCL C++ 3253<https://www.khronos.org/registry/OpenCL/specs/2.2/pdf/OpenCL_Cxx.pdf>`_ and 3254there is no plan to support it in clang in any new releases in the near future. 3255 3256 3257Clang currently supports C++ for OpenCL v1.0. 3258For detailed information about this language refer to the C++ for OpenCL 3259Programming Language Documentation available 3260in `the latest build 3261<https://www.khronos.org/opencl/assets/CXX_for_OpenCL.html>`_ 3262or in `the official release 3263<https://github.com/KhronosGroup/OpenCL-Docs/releases/tag/cxxforopencl-v1.0-r2>`_. 3264 3265To enable the C++ for OpenCL mode, pass one of following command line options when 3266compiling ``.cl`` file ``-cl-std=clc++``, ``-cl-std=CLC++``, ``-cl-std=clc++1.0``, 3267``-cl-std=CLC++1.0``, ``-std=clc++``, ``-std=CLC++``, ``-std=clc++1.0`` or 3268``-std=CLC++1.0``. 3269 3270 .. code-block:: c++ 3271 3272 template<class T> T add( T x, T y ) 3273 { 3274 return x + y; 3275 } 3276 3277 __kernel void test( __global float* a, __global float* b) 3278 { 3279 auto index = get_global_id(0); 3280 a[index] = add(b[index], b[index+1]); 3281 } 3282 3283 3284 .. code-block:: console 3285 3286 clang -cl-std=clc++ test.cl 3287 3288Alternatively, files with ``.clcpp`` extension are compiled with the C++ for OpenCL 3289mode. 3290 3291 .. code-block:: console 3292 3293 clang test.clcpp 3294 3295C++ for OpenCL kernel sources can also be compiled online in drivers supporting 3296`cl_ext_cxx_for_opencl 3297<https://www.khronos.org/registry/OpenCL/extensions/ext/cl_ext_cxx_for_opencl.html>`_ 3298extension. 3299 3300Constructing and destroying global objects 3301^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3302 3303Global objects with non-trivial constructors require the constructors to be run 3304before the first kernel using the global objects is executed. Similarly global 3305objects with non-trivial destructors require destructor invocation just after 3306the last kernel using the program objects is executed. 3307In OpenCL versions earlier than v2.2 there is no support for invoking global 3308constructors. However, an easy workaround is to manually enqueue the 3309constructor initialization kernel that has the following name scheme 3310``_GLOBAL__sub_I_<compiled file name>``. 3311This kernel is only present if there are global objects with non-trivial 3312constructors present in the compiled binary. One way to check this is by 3313passing ``CL_PROGRAM_KERNEL_NAMES`` to ``clGetProgramInfo`` (OpenCL v2.0 3314s5.8.7) and then checking whether any kernel name matches the naming scheme of 3315global constructor initialization kernel above. 3316 3317Note that if multiple files are compiled and linked into libraries, multiple 3318kernels that initialize global objects for multiple modules would have to be 3319invoked. 3320 3321Applications are currently required to run initialization of global objects 3322manually before running any kernels in which the objects are used. 3323 3324 .. code-block:: console 3325 3326 clang -cl-std=clc++ test.cl 3327 3328If there are any global objects to be initialized, the final binary will 3329contain the ``_GLOBAL__sub_I_test.cl`` kernel to be enqueued. 3330 3331Note that the manual workaround only applies to objects declared at the 3332program scope. There is no manual workaround for the construction of static 3333objects with non-trivial constructors inside functions. 3334 3335Global destructors can not be invoked manually in the OpenCL v2.0 drivers. 3336However, all memory used for program scope objects should be released on 3337``clReleaseProgram``. 3338 3339Libraries 3340^^^^^^^^^ 3341Limited experimental support of C++ standard libraries for OpenCL is 3342described in :doc:`OpenCLSupport` page. 3343 3344.. _target_features: 3345 3346Target-Specific Features and Limitations 3347======================================== 3348 3349CPU Architectures Features and Limitations 3350------------------------------------------ 3351 3352X86 3353^^^ 3354 3355The support for X86 (both 32-bit and 64-bit) is considered stable on 3356Darwin (macOS), Linux, FreeBSD, and Dragonfly BSD: it has been tested 3357to correctly compile many large C, C++, Objective-C, and Objective-C++ 3358codebases. 3359 3360On ``x86_64-mingw32``, passing i128(by value) is incompatible with the 3361Microsoft x64 calling convention. You might need to tweak 3362``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp. 3363 3364For the X86 target, clang supports the `-m16` command line 3365argument which enables 16-bit code output. This is broadly similar to 3366using ``asm(".code16gcc")`` with the GNU toolchain. The generated code 3367and the ABI remains 32-bit but the assembler emits instructions 3368appropriate for a CPU running in 16-bit mode, with address-size and 3369operand-size prefixes to enable 32-bit addressing and operations. 3370 3371Several micro-architecture levels as specified by the x86-64 psABI are defined. 3372They are cumulative in the sense that features from previous levels are 3373implicitly included in later levels. 3374 3375- ``-march=x86-64``: CMOV, CMPXCHG8B, FPU, FXSR, MMX, FXSR, SCE, SSE, SSE2 3376- ``-march=x86-64-v2``: (close to Nehalem) CMPXCHG16B, LAHF-SAHF, POPCNT, SSE3, SSE4.1, SSE4.2, SSSE3 3377- ``-march=x86-64-v3``: (close to Haswell) AVX, AVX2, BMI1, BMI2, F16C, FMA, LZCNT, MOVBE, XSAVE 3378- ``-march=x86-64-v4``: AVX512F, AVX512BW, AVX512CD, AVX512DQ, AVX512VL 3379 3380ARM 3381^^^ 3382 3383The support for ARM (specifically ARMv6 and ARMv7) is considered stable 3384on Darwin (iOS): it has been tested to correctly compile many large C, 3385C++, Objective-C, and Objective-C++ codebases. Clang only supports a 3386limited number of ARM architectures. It does not yet fully support 3387ARMv5, for example. 3388 3389PowerPC 3390^^^^^^^ 3391 3392The support for PowerPC (especially PowerPC64) is considered stable 3393on Linux and FreeBSD: it has been tested to correctly compile many 3394large C and C++ codebases. PowerPC (32bit) is still missing certain 3395features (e.g. PIC code on ELF platforms). 3396 3397Other platforms 3398^^^^^^^^^^^^^^^ 3399 3400clang currently contains some support for other architectures (e.g. Sparc); 3401however, significant pieces of code generation are still missing, and they 3402haven't undergone significant testing. 3403 3404clang contains limited support for the MSP430 embedded processor, but 3405both the clang support and the LLVM backend support are highly 3406experimental. 3407 3408Other platforms are completely unsupported at the moment. Adding the 3409minimal support needed for parsing and semantic analysis on a new 3410platform is quite easy; see ``lib/Basic/Targets.cpp`` in the clang source 3411tree. This level of support is also sufficient for conversion to LLVM IR 3412for simple programs. Proper support for conversion to LLVM IR requires 3413adding code to ``lib/CodeGen/CGCall.cpp`` at the moment; this is likely to 3414change soon, though. Generating assembly requires a suitable LLVM 3415backend. 3416 3417Operating System Features and Limitations 3418----------------------------------------- 3419 3420Windows 3421^^^^^^^ 3422 3423Clang has experimental support for targeting "Cygming" (Cygwin / MinGW) 3424platforms. 3425 3426See also :ref:`Microsoft Extensions <c_ms>`. 3427 3428Cygwin 3429"""""" 3430 3431Clang works on Cygwin-1.7. 3432 3433MinGW32 3434""""""" 3435 3436Clang works on some mingw32 distributions. Clang assumes directories as 3437below; 3438 3439- ``C:/mingw/include`` 3440- ``C:/mingw/lib`` 3441- ``C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++`` 3442 3443On MSYS, a few tests might fail. 3444 3445MinGW-w64 3446""""""""" 3447 3448For 32-bit (i686-w64-mingw32), and 64-bit (x86\_64-w64-mingw32), Clang 3449assumes as below; 3450 3451- ``GCC versions 4.5.0 to 4.5.3, 4.6.0 to 4.6.2, or 4.7.0 (for the C++ header search path)`` 3452- ``some_directory/bin/gcc.exe`` 3453- ``some_directory/bin/clang.exe`` 3454- ``some_directory/bin/clang++.exe`` 3455- ``some_directory/bin/../include/c++/GCC_version`` 3456- ``some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32`` 3457- ``some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32`` 3458- ``some_directory/bin/../include/c++/GCC_version/backward`` 3459- ``some_directory/bin/../x86_64-w64-mingw32/include`` 3460- ``some_directory/bin/../i686-w64-mingw32/include`` 3461- ``some_directory/bin/../include`` 3462 3463This directory layout is standard for any toolchain you will find on the 3464official `MinGW-w64 website <http://mingw-w64.sourceforge.net>`_. 3465 3466Clang expects the GCC executable "gcc.exe" compiled for 3467``i686-w64-mingw32`` (or ``x86_64-w64-mingw32``) to be present on PATH. 3468 3469`Some tests might fail <https://bugs.llvm.org/show_bug.cgi?id=9072>`_ on 3470``x86_64-w64-mingw32``. 3471 3472.. _clang-cl: 3473 3474clang-cl 3475======== 3476 3477clang-cl is an alternative command-line interface to Clang, designed for 3478compatibility with the Visual C++ compiler, cl.exe. 3479 3480To enable clang-cl to find system headers, libraries, and the linker when run 3481from the command-line, it should be executed inside a Visual Studio Native Tools 3482Command Prompt or a regular Command Prompt where the environment has been set 3483up using e.g. `vcvarsall.bat <https://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_. 3484 3485clang-cl can also be used from inside Visual Studio by selecting the LLVM 3486Platform Toolset. The toolset is not part of the installer, but may be installed 3487separately from the 3488`Visual Studio Marketplace <https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.llvm-toolchain>`_. 3489To use the toolset, select a project in Solution Explorer, open its Property 3490Page (Alt+F7), and in the "General" section of "Configuration Properties" 3491change "Platform Toolset" to LLVM. Doing so enables an additional Property 3492Page for selecting the clang-cl executable to use for builds. 3493 3494To use the toolset with MSBuild directly, invoke it with e.g. 3495``/p:PlatformToolset=LLVM``. This allows trying out the clang-cl toolchain 3496without modifying your project files. 3497 3498It's also possible to point MSBuild at clang-cl without changing toolset by 3499passing ``/p:CLToolPath=c:\llvm\bin /p:CLToolExe=clang-cl.exe``. 3500 3501When using CMake and the Visual Studio generators, the toolset can be set with the ``-T`` flag: 3502 3503 :: 3504 3505 cmake -G"Visual Studio 15 2017" -T LLVM .. 3506 3507When using CMake with the Ninja generator, set the ``CMAKE_C_COMPILER`` and 3508``CMAKE_CXX_COMPILER`` variables to clang-cl: 3509 3510 :: 3511 3512 cmake -GNinja -DCMAKE_C_COMPILER="c:/Program Files (x86)/LLVM/bin/clang-cl.exe" 3513 -DCMAKE_CXX_COMPILER="c:/Program Files (x86)/LLVM/bin/clang-cl.exe" .. 3514 3515 3516Command-Line Options 3517-------------------- 3518 3519To be compatible with cl.exe, clang-cl supports most of the same command-line 3520options. Those options can start with either ``/`` or ``-``. It also supports 3521some of Clang's core options, such as the ``-W`` options. 3522 3523Options that are known to clang-cl, but not currently supported, are ignored 3524with a warning. For example: 3525 3526 :: 3527 3528 clang-cl.exe: warning: argument unused during compilation: '/AI' 3529 3530To suppress warnings about unused arguments, use the ``-Qunused-arguments`` option. 3531 3532Options that are not known to clang-cl will be ignored by default. Use the 3533``-Werror=unknown-argument`` option in order to treat them as errors. If these 3534options are spelled with a leading ``/``, they will be mistaken for a filename: 3535 3536 :: 3537 3538 clang-cl.exe: error: no such file or directory: '/foobar' 3539 3540Please `file a bug <https://bugs.llvm.org/enter_bug.cgi?product=clang&component=Driver>`_ 3541for any valid cl.exe flags that clang-cl does not understand. 3542 3543Execute ``clang-cl /?`` to see a list of supported options: 3544 3545 :: 3546 3547 CL.EXE COMPATIBILITY OPTIONS: 3548 /? Display available options 3549 /arch:<value> Set architecture for code generation 3550 /Brepro- Emit an object file which cannot be reproduced over time 3551 /Brepro Emit an object file which can be reproduced over time 3552 /clang:<arg> Pass <arg> to the clang driver 3553 /C Don't discard comments when preprocessing 3554 /c Compile only 3555 /d1PP Retain macro definitions in /E mode 3556 /d1reportAllClassLayout Dump record layout information 3557 /diagnostics:caret Enable caret and column diagnostics (on by default) 3558 /diagnostics:classic Disable column and caret diagnostics 3559 /diagnostics:column Disable caret diagnostics but keep column info 3560 /D <macro[=value]> Define macro 3561 /EH<value> Exception handling model 3562 /EP Disable linemarker output and preprocess to stdout 3563 /execution-charset:<value> 3564 Runtime encoding, supports only UTF-8 3565 /E Preprocess to stdout 3566 /FA Output assembly code file during compilation 3567 /Fa<file or directory> Output assembly code to this file during compilation (with /FA) 3568 /Fe<file or directory> Set output executable file or directory (ends in / or \) 3569 /FI <value> Include file before parsing 3570 /Fi<file> Set preprocess output file name (with /P) 3571 /Fo<file or directory> Set output object file, or directory (ends in / or \) (with /c) 3572 /fp:except- 3573 /fp:except 3574 /fp:fast 3575 /fp:precise 3576 /fp:strict 3577 /Fp<filename> Set pch filename (with /Yc and /Yu) 3578 /GA Assume thread-local variables are defined in the executable 3579 /Gd Set __cdecl as a default calling convention 3580 /GF- Disable string pooling 3581 /GF Enable string pooling (default) 3582 /GR- Disable emission of RTTI data 3583 /Gregcall Set __regcall as a default calling convention 3584 /GR Enable emission of RTTI data 3585 /Gr Set __fastcall as a default calling convention 3586 /GS- Disable buffer security check 3587 /GS Enable buffer security check (default) 3588 /Gs Use stack probes (default) 3589 /Gs<value> Set stack probe size (default 4096) 3590 /guard:<value> Enable Control Flow Guard with /guard:cf, 3591 or only the table with /guard:cf,nochecks. 3592 Enable EH Continuation Guard with /guard:ehcont 3593 /Gv Set __vectorcall as a default calling convention 3594 /Gw- Don't put each data item in its own section 3595 /Gw Put each data item in its own section 3596 /GX- Disable exception handling 3597 /GX Enable exception handling 3598 /Gy- Don't put each function in its own section (default) 3599 /Gy Put each function in its own section 3600 /Gz Set __stdcall as a default calling convention 3601 /help Display available options 3602 /imsvc <dir> Add directory to system include search path, as if part of %INCLUDE% 3603 /I <dir> Add directory to include search path 3604 /J Make char type unsigned 3605 /LDd Create debug DLL 3606 /LD Create DLL 3607 /link <options> Forward options to the linker 3608 /MDd Use DLL debug run-time 3609 /MD Use DLL run-time 3610 /MTd Use static debug run-time 3611 /MT Use static run-time 3612 /O0 Disable optimization 3613 /O1 Optimize for size (same as /Og /Os /Oy /Ob2 /GF /Gy) 3614 /O2 Optimize for speed (same as /Og /Oi /Ot /Oy /Ob2 /GF /Gy) 3615 /Ob0 Disable function inlining 3616 /Ob1 Only inline functions which are (explicitly or implicitly) marked inline 3617 /Ob2 Inline functions as deemed beneficial by the compiler 3618 /Od Disable optimization 3619 /Og No effect 3620 /Oi- Disable use of builtin functions 3621 /Oi Enable use of builtin functions 3622 /Os Optimize for size 3623 /Ot Optimize for speed 3624 /Ox Deprecated (same as /Og /Oi /Ot /Oy /Ob2); use /O2 instead 3625 /Oy- Disable frame pointer omission (x86 only, default) 3626 /Oy Enable frame pointer omission (x86 only) 3627 /O<flags> Set multiple /O flags at once; e.g. '/O2y-' for '/O2 /Oy-' 3628 /o <file or directory> Set output file or directory (ends in / or \) 3629 /P Preprocess to file 3630 /Qvec- Disable the loop vectorization passes 3631 /Qvec Enable the loop vectorization passes 3632 /showFilenames- Don't print the name of each compiled file (default) 3633 /showFilenames Print the name of each compiled file 3634 /showIncludes Print info about included files to stderr 3635 /source-charset:<value> Source encoding, supports only UTF-8 3636 /std:<value> Language standard to compile for 3637 /TC Treat all source files as C 3638 /Tc <filename> Specify a C source file 3639 /TP Treat all source files as C++ 3640 /Tp <filename> Specify a C++ source file 3641 /utf-8 Set source and runtime encoding to UTF-8 (default) 3642 /U <macro> Undefine macro 3643 /vd<value> Control vtordisp placement 3644 /vmb Use a best-case representation method for member pointers 3645 /vmg Use a most-general representation for member pointers 3646 /vmm Set the default most-general representation to multiple inheritance 3647 /vms Set the default most-general representation to single inheritance 3648 /vmv Set the default most-general representation to virtual inheritance 3649 /volatile:iso Volatile loads and stores have standard semantics 3650 /volatile:ms Volatile loads and stores have acquire and release semantics 3651 /W0 Disable all warnings 3652 /W1 Enable -Wall 3653 /W2 Enable -Wall 3654 /W3 Enable -Wall 3655 /W4 Enable -Wall and -Wextra 3656 /Wall Enable -Weverything 3657 /WX- Do not treat warnings as errors 3658 /WX Treat warnings as errors 3659 /w Disable all warnings 3660 /X Don't add %INCLUDE% to the include search path 3661 /Y- Disable precompiled headers, overrides /Yc and /Yu 3662 /Yc<filename> Generate a pch file for all code up to and including <filename> 3663 /Yu<filename> Load a pch file and use it instead of all code up to and including <filename> 3664 /Z7 Enable CodeView debug information in object files 3665 /Zc:char8_t Enable C++2a char8_t type 3666 /Zc:char8_t- Disable C++2a char8_t type 3667 /Zc:dllexportInlines- Don't dllexport/dllimport inline member functions of dllexport/import classes 3668 /Zc:dllexportInlines dllexport/dllimport inline member functions of dllexport/import classes (default) 3669 /Zc:sizedDealloc- Disable C++14 sized global deallocation functions 3670 /Zc:sizedDealloc Enable C++14 sized global deallocation functions 3671 /Zc:strictStrings Treat string literals as const 3672 /Zc:threadSafeInit- Disable thread-safe initialization of static variables 3673 /Zc:threadSafeInit Enable thread-safe initialization of static variables 3674 /Zc:trigraphs- Disable trigraphs (default) 3675 /Zc:trigraphs Enable trigraphs 3676 /Zc:twoPhase- Disable two-phase name lookup in templates 3677 /Zc:twoPhase Enable two-phase name lookup in templates 3678 /Zd Emit debug line number tables only 3679 /Zi Alias for /Z7. Does not produce PDBs. 3680 /Zl Don't mention any default libraries in the object file 3681 /Zp Set the default maximum struct packing alignment to 1 3682 /Zp<value> Specify the default maximum struct packing alignment 3683 /Zs Syntax-check only 3684 3685 OPTIONS: 3686 -### Print (but do not run) the commands to run for this compilation 3687 --analyze Run the static analyzer 3688 -faddrsig Emit an address-significance table 3689 -fansi-escape-codes Use ANSI escape codes for diagnostics 3690 -fblocks Enable the 'blocks' language feature 3691 -fcf-protection=<value> Instrument control-flow architecture protection. Options: return, branch, full, none. 3692 -fcf-protection Enable cf-protection in 'full' mode 3693 -fcolor-diagnostics Use colors in diagnostics 3694 -fcomplete-member-pointers 3695 Require member pointer base types to be complete if they would be significant under the Microsoft ABI 3696 -fcoverage-mapping Generate coverage mapping to enable code coverage analysis 3697 -fcrash-diagnostics-dir=<dir> 3698 Put crash-report files in <dir> 3699 -fdebug-macro Emit macro debug information 3700 -fdelayed-template-parsing 3701 Parse templated function definitions at the end of the translation unit 3702 -fdiagnostics-absolute-paths 3703 Print absolute paths in diagnostics 3704 -fdiagnostics-parseable-fixits 3705 Print fix-its in machine parseable form 3706 -flto=<value> Set LTO mode to either 'full' or 'thin' 3707 -flto Enable LTO in 'full' mode 3708 -fmerge-all-constants Allow merging of constants 3709 -fms-compatibility-version=<value> 3710 Dot-separated value representing the Microsoft compiler version 3711 number to report in _MSC_VER (0 = don't define it (default)) 3712 -fms-compatibility Enable full Microsoft Visual C++ compatibility 3713 -fms-extensions Accept some non-standard constructs supported by the Microsoft compiler 3714 -fmsc-version=<value> Microsoft compiler version number to report in _MSC_VER 3715 (0 = don't define it (default)) 3716 -fno-addrsig Don't emit an address-significance table 3717 -fno-builtin-<value> Disable implicit builtin knowledge of a specific function 3718 -fno-builtin Disable implicit builtin knowledge of functions 3719 -fno-complete-member-pointers 3720 Do not require member pointer base types to be complete if they would be significant under the Microsoft ABI 3721 -fno-coverage-mapping Disable code coverage analysis 3722 -fno-crash-diagnostics Disable auto-generation of preprocessed source files and a script for reproduction during a clang crash 3723 -fno-debug-macro Do not emit macro debug information 3724 -fno-delayed-template-parsing 3725 Disable delayed template parsing 3726 -fno-sanitize-address-poison-custom-array-cookie 3727 Disable poisoning array cookies when using custom operator new[] in AddressSanitizer 3728 -fno-sanitize-address-use-after-scope 3729 Disable use-after-scope detection in AddressSanitizer 3730 -fno-sanitize-address-use-odr-indicator 3731 Disable ODR indicator globals 3732 -fno-sanitize-ignorelist Don't use ignorelist file for sanitizers 3733 -fno-sanitize-cfi-cross-dso 3734 Disable control flow integrity (CFI) checks for cross-DSO calls. 3735 -fno-sanitize-coverage=<value> 3736 Disable specified features of coverage instrumentation for Sanitizers 3737 -fno-sanitize-memory-track-origins 3738 Disable origins tracking in MemorySanitizer 3739 -fno-sanitize-memory-use-after-dtor 3740 Disable use-after-destroy detection in MemorySanitizer 3741 -fno-sanitize-recover=<value> 3742 Disable recovery for specified sanitizers 3743 -fno-sanitize-stats Disable sanitizer statistics gathering. 3744 -fno-sanitize-thread-atomics 3745 Disable atomic operations instrumentation in ThreadSanitizer 3746 -fno-sanitize-thread-func-entry-exit 3747 Disable function entry/exit instrumentation in ThreadSanitizer 3748 -fno-sanitize-thread-memory-access 3749 Disable memory access instrumentation in ThreadSanitizer 3750 -fno-sanitize-trap=<value> 3751 Disable trapping for specified sanitizers 3752 -fno-standalone-debug Limit debug information produced to reduce size of debug binary 3753 -fobjc-runtime=<value> Specify the target Objective-C runtime kind and version 3754 -fprofile-exclude-files=<value> 3755 Instrument only functions from files where names don't match all the regexes separated by a semi-colon 3756 -fprofile-filter-files=<value> 3757 Instrument only functions from files where names match any regex separated by a semi-colon 3758 -fprofile-instr-generate=<file> 3759 Generate instrumented code to collect execution counts into <file> 3760 (overridden by LLVM_PROFILE_FILE env var) 3761 -fprofile-instr-generate 3762 Generate instrumented code to collect execution counts into default.profraw file 3763 (overridden by '=' form of option or LLVM_PROFILE_FILE env var) 3764 -fprofile-instr-use=<value> 3765 Use instrumentation data for profile-guided optimization 3766 -fprofile-remapping-file=<file> 3767 Use the remappings described in <file> to match the profile data against names in the program 3768 -fprofile-list=<file> 3769 Filename defining the list of functions/files to instrument 3770 -fsanitize-address-field-padding=<value> 3771 Level of field padding for AddressSanitizer 3772 -fsanitize-address-globals-dead-stripping 3773 Enable linker dead stripping of globals in AddressSanitizer 3774 -fsanitize-address-poison-custom-array-cookie 3775 Enable poisoning array cookies when using custom operator new[] in AddressSanitizer 3776 -fsanitize-address-use-after-return=<mode> 3777 Select the mode of detecting stack use-after-return in AddressSanitizer: never | runtime (default) | always 3778 -fsanitize-address-use-after-scope 3779 Enable use-after-scope detection in AddressSanitizer 3780 -fsanitize-address-use-odr-indicator 3781 Enable ODR indicator globals to avoid false ODR violation reports in partially sanitized programs at the cost of an increase in binary size 3782 -fsanitize-ignorelist=<value> 3783 Path to ignorelist file for sanitizers 3784 -fsanitize-cfi-cross-dso 3785 Enable control flow integrity (CFI) checks for cross-DSO calls. 3786 -fsanitize-cfi-icall-generalize-pointers 3787 Generalize pointers in CFI indirect call type signature checks 3788 -fsanitize-coverage=<value> 3789 Specify the type of coverage instrumentation for Sanitizers 3790 -fsanitize-hwaddress-abi=<value> 3791 Select the HWAddressSanitizer ABI to target (interceptor or platform, default interceptor) 3792 -fsanitize-memory-track-origins=<value> 3793 Enable origins tracking in MemorySanitizer 3794 -fsanitize-memory-track-origins 3795 Enable origins tracking in MemorySanitizer 3796 -fsanitize-memory-use-after-dtor 3797 Enable use-after-destroy detection in MemorySanitizer 3798 -fsanitize-recover=<value> 3799 Enable recovery for specified sanitizers 3800 -fsanitize-stats Enable sanitizer statistics gathering. 3801 -fsanitize-thread-atomics 3802 Enable atomic operations instrumentation in ThreadSanitizer (default) 3803 -fsanitize-thread-func-entry-exit 3804 Enable function entry/exit instrumentation in ThreadSanitizer (default) 3805 -fsanitize-thread-memory-access 3806 Enable memory access instrumentation in ThreadSanitizer (default) 3807 -fsanitize-trap=<value> Enable trapping for specified sanitizers 3808 -fsanitize-undefined-strip-path-components=<number> 3809 Strip (or keep only, if negative) a given number of path components when emitting check metadata. 3810 -fsanitize=<check> Turn on runtime checks for various forms of undefined or suspicious 3811 behavior. See user manual for available checks 3812 -fsplit-lto-unit Enables splitting of the LTO unit. 3813 -fstandalone-debug Emit full debug info for all types used by the program 3814 -fwhole-program-vtables Enables whole-program vtable optimization. Requires -flto 3815 -gcodeview-ghash Emit type record hashes in a .debug$H section 3816 -gcodeview Generate CodeView debug information 3817 -gline-directives-only Emit debug line info directives only 3818 -gline-tables-only Emit debug line number tables only 3819 -miamcu Use Intel MCU ABI 3820 -mllvm <value> Additional arguments to forward to LLVM's option processing 3821 -nobuiltininc Disable builtin #include directories 3822 -Qunused-arguments Don't emit warning for unused driver arguments 3823 -R<remark> Enable the specified remark 3824 --target=<value> Generate code for the given target 3825 --version Print version information 3826 -v Show commands to run and use verbose output 3827 -W<warning> Enable the specified warning 3828 -Xclang <arg> Pass <arg> to the clang compiler 3829 3830The /clang: Option 3831^^^^^^^^^^^^^^^^^^ 3832 3833When clang-cl is run with a set of ``/clang:<arg>`` options, it will gather all 3834of the ``<arg>`` arguments and process them as if they were passed to the clang 3835driver. This mechanism allows you to pass flags that are not exposed in the 3836clang-cl options or flags that have a different meaning when passed to the clang 3837driver. Regardless of where they appear in the command line, the ``/clang:`` 3838arguments are treated as if they were passed at the end of the clang-cl command 3839line. 3840 3841The /Zc:dllexportInlines- Option 3842^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3843 3844This causes the class-level `dllexport` and `dllimport` attributes to not apply 3845to inline member functions, as they otherwise would. For example, in the code 3846below `S::foo()` would normally be defined and exported by the DLL, but when 3847using the ``/Zc:dllexportInlines-`` flag it is not: 3848 3849.. code-block:: c 3850 3851 struct __declspec(dllexport) S { 3852 void foo() {} 3853 } 3854 3855This has the benefit that the compiler doesn't need to emit a definition of 3856`S::foo()` in every translation unit where the declaration is included, as it 3857would otherwise do to ensure there's a definition in the DLL even if it's not 3858used there. If the declaration occurs in a header file that's widely used, this 3859can save significant compilation time and output size. It also reduces the 3860number of functions exported by the DLL similarly to what 3861``-fvisibility-inlines-hidden`` does for shared objects on ELF and Mach-O. 3862Since the function declaration comes with an inline definition, users of the 3863library can use that definition directly instead of importing it from the DLL. 3864 3865Note that the Microsoft Visual C++ compiler does not support this option, and 3866if code in a DLL is compiled with ``/Zc:dllexportInlines-``, the code using the 3867DLL must be compiled in the same way so that it doesn't attempt to dllimport 3868the inline member functions. The reverse scenario should generally work though: 3869a DLL compiled without this flag (such as a system library compiled with Visual 3870C++) can be referenced from code compiled using the flag, meaning that the 3871referencing code will use the inline definitions instead of importing them from 3872the DLL. 3873 3874Also note that like when using ``-fvisibility-inlines-hidden``, the address of 3875`S::foo()` will be different inside and outside the DLL, breaking the C/C++ 3876standard requirement that functions have a unique address. 3877 3878The flag does not apply to explicit class template instantiation definitions or 3879declarations, as those are typically used to explicitly provide a single 3880definition in a DLL, (dllexported instantiation definition) or to signal that 3881the definition is available elsewhere (dllimport instantiation declaration). It 3882also doesn't apply to inline members with static local variables, to ensure 3883that the same instance of the variable is used inside and outside the DLL. 3884 3885Using this flag can cause problems when inline functions that would otherwise 3886be dllexported refer to internal symbols of a DLL. For example: 3887 3888.. code-block:: c 3889 3890 void internal(); 3891 3892 struct __declspec(dllimport) S { 3893 void foo() { internal(); } 3894 } 3895 3896Normally, references to `S::foo()` would use the definition in the DLL from 3897which it was exported, and which presumably also has the definition of 3898`internal()`. However, when using ``/Zc:dllexportInlines-``, the inline 3899definition of `S::foo()` is used directly, resulting in a link error since 3900`internal()` is not available. Even worse, if there is an inline definition of 3901`internal()` containing a static local variable, we will now refer to a 3902different instance of that variable than in the DLL: 3903 3904.. code-block:: c 3905 3906 inline int internal() { static int x; return x++; } 3907 3908 struct __declspec(dllimport) S { 3909 int foo() { return internal(); } 3910 } 3911 3912This could lead to very subtle bugs. Using ``-fvisibility-inlines-hidden`` can 3913lead to the same issue. To avoid it in this case, make `S::foo()` or 3914`internal()` non-inline, or mark them `dllimport/dllexport` explicitly. 3915 3916Finding Clang runtime libraries 3917^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3918 3919clang-cl supports several features that require runtime library support: 3920 3921- Address Sanitizer (ASan): ``-fsanitize=address`` 3922- Undefined Behavior Sanitizer (UBSan): ``-fsanitize=undefined`` 3923- Code coverage: ``-fprofile-instr-generate -fcoverage-mapping`` 3924- Profile Guided Optimization (PGO): ``-fprofile-instr-generate`` 3925- Certain math operations (int128 division) require the builtins library 3926 3927In order to use these features, the user must link the right runtime libraries 3928into their program. These libraries are distributed alongside Clang in the 3929library resource directory. Clang searches for the resource directory by 3930searching relative to the Clang executable. For example, if LLVM is installed 3931in ``C:\Program Files\LLVM``, then the profile runtime library will be located 3932at the path 3933``C:\Program Files\LLVM\lib\clang\11.0.0\lib\windows\clang_rt.profile-x86_64.lib``. 3934 3935For UBSan, PGO, and coverage, Clang will emit object files that auto-link the 3936appropriate runtime library, but the user generally needs to help the linker 3937(whether it is ``lld-link.exe`` or MSVC ``link.exe``) find the library resource 3938directory. Using the example installation above, this would mean passing 3939``/LIBPATH:C:\Program Files\LLVM\lib\clang\11.0.0\lib\windows`` to the linker. 3940If the user links the program with the ``clang`` or ``clang-cl`` drivers, the 3941driver will pass this flag for them. 3942 3943If the linker cannot find the appropriate library, it will emit an error like 3944this:: 3945 3946 $ clang-cl -c -fsanitize=undefined t.cpp 3947 3948 $ lld-link t.obj -dll 3949 lld-link: error: could not open 'clang_rt.ubsan_standalone-x86_64.lib': no such file or directory 3950 lld-link: error: could not open 'clang_rt.ubsan_standalone_cxx-x86_64.lib': no such file or directory 3951 3952 $ link t.obj -dll -nologo 3953 LINK : fatal error LNK1104: cannot open file 'clang_rt.ubsan_standalone-x86_64.lib' 3954 3955To fix the error, add the appropriate ``/libpath:`` flag to the link line. 3956 3957For ASan, as of this writing, the user is also responsible for linking against 3958the correct ASan libraries. 3959 3960If the user is using the dynamic CRT (``/MD``), then they should add 3961``clang_rt.asan_dynamic-x86_64.lib`` to the link line as a regular input. For 3962other architectures, replace x86_64 with the appropriate name here and below. 3963 3964If the user is using the static CRT (``/MT``), then different runtimes are used 3965to produce DLLs and EXEs. To link a DLL, pass 3966``clang_rt.asan_dll_thunk-x86_64.lib``. To link an EXE, pass 3967``-wholearchive:clang_rt.asan-x86_64.lib``. 3968