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_fsigned-zeros: 1390 1391**-f[no-]signed-zeros** 1392 1393 Allow optimizations that ignore the sign of floating point zeros. 1394 Defaults to ``-fno-signed-zeros``. 1395 1396.. _opt_fassociative-math: 1397 1398**-f[no-]associative-math** 1399 1400 Allow floating point operations to be reassociated. 1401 Defaults to ``-fno-associative-math``. 1402 1403.. _opt_freciprocal-math: 1404 1405**-f[no-]reciprocal-math** 1406 1407 Allow division operations to be transformed into multiplication by a 1408 reciprocal. This can be significantly faster than an ordinary division 1409 but can also have significantly less precision. Defaults to 1410 ``-fno-reciprocal-math``. 1411 1412.. _opt_funsafe-math-optimizations: 1413 1414**-f[no-]unsafe-math-optimizations** 1415 1416 Allow unsafe floating-point optimizations. Also implies: 1417 1418 * ``-fassociative-math`` 1419 * ``-freciprocal-math`` 1420 * ``-fno-signed-zeroes`` 1421 * ``-fno-trapping-math``. 1422 1423 Defaults to ``-fno-unsafe-math-optimizations``. 1424 1425.. _opt_ffinite-math-only: 1426 1427**-f[no-]finite-math-only** 1428 1429 Allow floating-point optimizations that assume arguments and results are 1430 not NaNs or +-Inf. This defines the ``__FINITE_MATH_ONLY__`` preprocessor macro. 1431 Also implies: 1432 1433 * ``-fno-honor-infinities`` 1434 * ``-fno-honor-nans`` 1435 1436 Defaults to ``-fno-finite-math-only``. 1437 1438.. _opt_frounding-math: 1439 1440**-f[no-]rounding-math** 1441 1442Force floating-point operations to honor the dynamically-set rounding mode by default. 1443 1444The 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. 1445 1446Note 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``. 1447 1448- The option ``-fno-rounding-math`` allows the compiler to assume that the rounding mode is set to ``FE_TONEAREST``. This is the default. 1449- 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. 1450 1451.. option:: -ffp-model=<value> 1452 1453 Specify floating point behavior. ``-ffp-model`` is an umbrella 1454 option that encompasses functionality provided by other, single 1455 purpose, floating point options. Valid values are: ``precise``, ``strict``, 1456 and ``fast``. 1457 Details: 1458 1459 * ``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. 1460 * ``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. 1461 * ``fast`` Behaves identically to specifying both ``-ffast-math`` and ``ffp-contract=fast`` 1462 1463 Note: If your command line specifies multiple instances 1464 of the ``-ffp-model`` option, or if your command line option specifies 1465 ``-ffp-model`` and later on the command line selects a floating point 1466 option that has the effect of negating part of the ``ffp-model`` that 1467 has been selected, then the compiler will issue a diagnostic warning 1468 that the override has occurred. 1469 1470.. option:: -ffp-exception-behavior=<value> 1471 1472 Specify the floating-point exception behavior. 1473 1474 Valid values are: ``ignore``, ``maytrap``, and ``strict``. 1475 The default value is ``ignore``. Details: 1476 1477 * ``ignore`` The compiler assumes that the exception status flags will not be read and that floating point exceptions will be masked. 1478 * ``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. 1479 * ``strict`` The compiler ensures that all transformations strictly preserve the floating point exception semantics of the original code. 1480 1481.. option:: -f[no-]protect-parens: 1482 1483 This option pertains to floating-point types, complex types with 1484 floating-point components, and vectors of these types. Some arithmetic 1485 expression transformations that are mathematically correct and permissible 1486 according to the C and C++ language standards may be incorrect when dealing 1487 with floating-point types, such as reassociation and distribution. Further, 1488 the optimizer may ignore parentheses when computing arithmetic expressions 1489 in circumstances where the parenthesized and unparenthesized expression 1490 express the same mathematical value. For example (a+b)+c is the same 1491 mathematical value as a+(b+c), but the optimizer is free to evaluate the 1492 additions in any order regardless of the parentheses. When enabled, this 1493 option forces the optimizer to honor the order of operations with respect 1494 to parentheses in all circumstances. 1495 1496 Note that floating-point contraction (option `-ffp-contract=`) is disabled 1497 when `-fprotect-parens` is enabled. Also note that in safe floating-point 1498 modes, such as `-ffp-model=precise` or `-ffp-model=strict`, this option 1499 has no effect because the optimizer is prohibited from making unsafe 1500 transformations. 1501 1502.. _fp-constant-eval: 1503 1504A note about Floating Point Constant Evaluation 1505^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1506 1507In C, the only place floating point operations are guaranteed to be evaluated 1508during translation is in the initializers of variables of static storage 1509duration, which are all notionally initialized before the program begins 1510executing (and thus before a non-default floating point environment can be 1511entered). But C++ has many more contexts where floating point constant 1512evaluation occurs. Specifically: for static/thread-local variables, 1513first try evaluating the initializer in a constant context, including in the 1514constant floating point environment (just like in C), and then, if that fails, 1515fall back to emitting runtime code to perform the initialization (which might 1516in general be in a different floating point environment). 1517 1518Consider this example when compiled with ``-frounding-math`` 1519 1520 .. code-block:: console 1521 1522 constexpr float func_01(float x, float y) { 1523 return x + y; 1524 } 1525 float V1 = func_01(1.0F, 0x0.000001p0F); 1526 1527The C++ rule is that initializers for static storage duration variables are 1528first evaluated during translation (therefore, in the default rounding mode), 1529and only evaluated at runtime (and therefore in the runtime rounding mode) if 1530the compile-time evaluation fails. This is in line with the C rules; 1531C11 F.8.5 says: *All computation for automatic initialization is done (as if) 1532at execution time; thus, it is affected by any operative modes and raises 1533floating-point exceptions as required by IEC 60559 (provided the state for the 1534FENV_ACCESS pragma is ‘‘on’’). All computation for initialization of objects 1535that have static or thread storage duration is done (as if) at translation 1536time.* C++ generalizes this by adding another phase of initialization 1537(at runtime) if the translation-time initialization fails, but the 1538translation-time evaluation of the initializer of succeeds, it will be 1539treated as a constant initializer. 1540 1541 1542.. _controlling-code-generation: 1543 1544Controlling Code Generation 1545--------------------------- 1546 1547Clang provides a number of ways to control code generation. The options 1548are listed below. 1549 1550**-f[no-]sanitize=check1,check2,...** 1551 Turn on runtime checks for various forms of undefined or suspicious 1552 behavior. 1553 1554 This option controls whether Clang adds runtime checks for various 1555 forms of undefined or suspicious behavior, and is disabled by 1556 default. If a check fails, a diagnostic message is produced at 1557 runtime explaining the problem. The main checks are: 1558 1559 - .. _opt_fsanitize_address: 1560 1561 ``-fsanitize=address``: 1562 :doc:`AddressSanitizer`, a memory error 1563 detector. 1564 - .. _opt_fsanitize_thread: 1565 1566 ``-fsanitize=thread``: :doc:`ThreadSanitizer`, a data race detector. 1567 - .. _opt_fsanitize_memory: 1568 1569 ``-fsanitize=memory``: :doc:`MemorySanitizer`, 1570 a detector of uninitialized reads. Requires instrumentation of all 1571 program code. 1572 - .. _opt_fsanitize_undefined: 1573 1574 ``-fsanitize=undefined``: :doc:`UndefinedBehaviorSanitizer`, 1575 a fast and compatible undefined behavior checker. 1576 1577 - ``-fsanitize=dataflow``: :doc:`DataFlowSanitizer`, a general data 1578 flow analysis. 1579 - ``-fsanitize=cfi``: :doc:`control flow integrity <ControlFlowIntegrity>` 1580 checks. Requires ``-flto``. 1581 - ``-fsanitize=safe-stack``: :doc:`safe stack <SafeStack>` 1582 protection against stack-based memory corruption errors. 1583 1584 There are more fine-grained checks available: see 1585 the :ref:`list <ubsan-checks>` of specific kinds of 1586 undefined behavior that can be detected and the :ref:`list <cfi-schemes>` 1587 of control flow integrity schemes. 1588 1589 The ``-fsanitize=`` argument must also be provided when linking, in 1590 order to link to the appropriate runtime library. 1591 1592 It is not possible to combine more than one of the ``-fsanitize=address``, 1593 ``-fsanitize=thread``, and ``-fsanitize=memory`` checkers in the same 1594 program. 1595 1596**-f[no-]sanitize-recover=check1,check2,...** 1597 1598**-f[no-]sanitize-recover[=all]** 1599 1600 Controls which checks enabled by ``-fsanitize=`` flag are non-fatal. 1601 If the check is fatal, program will halt after the first error 1602 of this kind is detected and error report is printed. 1603 1604 By default, non-fatal checks are those enabled by 1605 :doc:`UndefinedBehaviorSanitizer`, 1606 except for ``-fsanitize=return`` and ``-fsanitize=unreachable``. Some 1607 sanitizers may not support recovery (or not support it by default 1608 e.g. :doc:`AddressSanitizer`), and always crash the program after the issue 1609 is detected. 1610 1611 Note that the ``-fsanitize-trap`` flag has precedence over this flag. 1612 This means that if a check has been configured to trap elsewhere on the 1613 command line, or if the check traps by default, this flag will not have 1614 any effect unless that sanitizer's trapping behavior is disabled with 1615 ``-fno-sanitize-trap``. 1616 1617 For example, if a command line contains the flags ``-fsanitize=undefined 1618 -fsanitize-trap=undefined``, the flag ``-fsanitize-recover=alignment`` 1619 will have no effect on its own; it will need to be accompanied by 1620 ``-fno-sanitize-trap=alignment``. 1621 1622**-f[no-]sanitize-trap=check1,check2,...** 1623 1624**-f[no-]sanitize-trap[=all]** 1625 1626 Controls which checks enabled by the ``-fsanitize=`` flag trap. This 1627 option is intended for use in cases where the sanitizer runtime cannot 1628 be used (for instance, when building libc or a kernel module), or where 1629 the binary size increase caused by the sanitizer runtime is a concern. 1630 1631 This flag is only compatible with :doc:`control flow integrity 1632 <ControlFlowIntegrity>` schemes and :doc:`UndefinedBehaviorSanitizer` 1633 checks other than ``vptr``. 1634 1635 This flag is enabled by default for sanitizers in the ``cfi`` group. 1636 1637.. option:: -fsanitize-ignorelist=/path/to/ignorelist/file 1638 1639 Disable or modify sanitizer checks for objects (source files, functions, 1640 variables, types) listed in the file. See 1641 :doc:`SanitizerSpecialCaseList` for file format description. 1642 1643.. option:: -fno-sanitize-ignorelist 1644 1645 Don't use ignorelist file, if it was specified earlier in the command line. 1646 1647**-f[no-]sanitize-coverage=[type,features,...]** 1648 1649 Enable simple code coverage in addition to certain sanitizers. 1650 See :doc:`SanitizerCoverage` for more details. 1651 1652**-f[no-]sanitize-address-outline-instrumentation** 1653 1654 Controls how address sanitizer code is generated. If enabled will always use 1655 a function call instead of inlining the code. Turning this option on could 1656 reduce the binary size, but might result in a worse run-time performance. 1657 1658 See :doc: `AddressSanitizer` for more details. 1659 1660**-f[no-]sanitize-stats** 1661 1662 Enable simple statistics gathering for the enabled sanitizers. 1663 See :doc:`SanitizerStats` for more details. 1664 1665.. option:: -fsanitize-undefined-trap-on-error 1666 1667 Deprecated alias for ``-fsanitize-trap=undefined``. 1668 1669.. option:: -fsanitize-cfi-cross-dso 1670 1671 Enable cross-DSO control flow integrity checks. This flag modifies 1672 the behavior of sanitizers in the ``cfi`` group to allow checking 1673 of cross-DSO virtual and indirect calls. 1674 1675.. option:: -fsanitize-cfi-icall-generalize-pointers 1676 1677 Generalize pointers in return and argument types in function type signatures 1678 checked by Control Flow Integrity indirect call checking. See 1679 :doc:`ControlFlowIntegrity` for more details. 1680 1681.. option:: -fstrict-vtable-pointers 1682 1683 Enable optimizations based on the strict rules for overwriting polymorphic 1684 C++ objects, i.e. the vptr is invariant during an object's lifetime. 1685 This enables better devirtualization. Turned off by default, because it is 1686 still experimental. 1687 1688.. option:: -fwhole-program-vtables 1689 1690 Enable whole-program vtable optimizations, such as single-implementation 1691 devirtualization and virtual constant propagation, for classes with 1692 :doc:`hidden LTO visibility <LTOVisibility>`. Requires ``-flto``. 1693 1694.. option:: -fforce-emit-vtables 1695 1696 In order to improve devirtualization, forces emitting of vtables even in 1697 modules where it isn't necessary. It causes more inline virtual functions 1698 to be emitted. 1699 1700.. option:: -fno-assume-sane-operator-new 1701 1702 Don't assume that the C++'s new operator is sane. 1703 1704 This option tells the compiler to do not assume that C++'s global 1705 new operator will always return a pointer that does not alias any 1706 other pointer when the function returns. 1707 1708.. option:: -ftrap-function=[name] 1709 1710 Instruct code generator to emit a function call to the specified 1711 function name for ``__builtin_trap()``. 1712 1713 LLVM code generator translates ``__builtin_trap()`` to a trap 1714 instruction if it is supported by the target ISA. Otherwise, the 1715 builtin is translated into a call to ``abort``. If this option is 1716 set, then the code generator will always lower the builtin to a call 1717 to the specified function regardless of whether the target ISA has a 1718 trap instruction. This option is useful for environments (e.g. 1719 deeply embedded) where a trap cannot be properly handled, or when 1720 some custom behavior is desired. 1721 1722.. option:: -ftls-model=[model] 1723 1724 Select which TLS model to use. 1725 1726 Valid values are: ``global-dynamic``, ``local-dynamic``, 1727 ``initial-exec`` and ``local-exec``. The default value is 1728 ``global-dynamic``. The compiler may use a different model if the 1729 selected model is not supported by the target, or if a more 1730 efficient model can be used. The TLS model can be overridden per 1731 variable using the ``tls_model`` attribute. 1732 1733.. option:: -femulated-tls 1734 1735 Select emulated TLS model, which overrides all -ftls-model choices. 1736 1737 In emulated TLS mode, all access to TLS variables are converted to 1738 calls to __emutls_get_address in the runtime library. 1739 1740.. option:: -mhwdiv=[values] 1741 1742 Select the ARM modes (arm or thumb) that support hardware division 1743 instructions. 1744 1745 Valid values are: ``arm``, ``thumb`` and ``arm,thumb``. 1746 This option is used to indicate which mode (arm or thumb) supports 1747 hardware division instructions. This only applies to the ARM 1748 architecture. 1749 1750.. option:: -m[no-]crc 1751 1752 Enable or disable CRC instructions. 1753 1754 This option is used to indicate whether CRC instructions are to 1755 be generated. This only applies to the ARM architecture. 1756 1757 CRC instructions are enabled by default on ARMv8. 1758 1759.. option:: -mgeneral-regs-only 1760 1761 Generate code which only uses the general purpose registers. 1762 1763 This option restricts the generated code to use general registers 1764 only. This only applies to the AArch64 architecture. 1765 1766.. option:: -mcompact-branches=[values] 1767 1768 Control the usage of compact branches for MIPSR6. 1769 1770 Valid values are: ``never``, ``optimal`` and ``always``. 1771 The default value is ``optimal`` which generates compact branches 1772 when a delay slot cannot be filled. ``never`` disables the usage of 1773 compact branches and ``always`` generates compact branches whenever 1774 possible. 1775 1776**-f[no-]max-type-align=[number]** 1777 Instruct the code generator to not enforce a higher alignment than the given 1778 number (of bytes) when accessing memory via an opaque pointer or reference. 1779 This cap is ignored when directly accessing a variable or when the pointee 1780 type has an explicit “aligned” attribute. 1781 1782 The value should usually be determined by the properties of the system allocator. 1783 Some builtin types, especially vector types, have very high natural alignments; 1784 when working with values of those types, Clang usually wants to use instructions 1785 that take advantage of that alignment. However, many system allocators do 1786 not promise to return memory that is more than 8-byte or 16-byte-aligned. Use 1787 this option to limit the alignment that the compiler can assume for an arbitrary 1788 pointer, which may point onto the heap. 1789 1790 This option does not affect the ABI alignment of types; the layout of structs and 1791 unions and the value returned by the alignof operator remain the same. 1792 1793 This option can be overridden on a case-by-case basis by putting an explicit 1794 “aligned” alignment on a struct, union, or typedef. For example: 1795 1796 .. code-block:: console 1797 1798 #include <immintrin.h> 1799 // Make an aligned typedef of the AVX-512 16-int vector type. 1800 typedef __v16si __aligned_v16si __attribute__((aligned(64))); 1801 1802 void initialize_vector(__aligned_v16si *v) { 1803 // The compiler may assume that ‘v’ is 64-byte aligned, regardless of the 1804 // value of -fmax-type-align. 1805 } 1806 1807.. option:: -faddrsig, -fno-addrsig 1808 1809 Controls whether Clang emits an address-significance table into the object 1810 file. Address-significance tables allow linkers to implement `safe ICF 1811 <https://research.google.com/pubs/archive/36912.pdf>`_ without the false 1812 positives that can result from other implementation techniques such as 1813 relocation scanning. Address-significance tables are enabled by default 1814 on ELF targets when using the integrated assembler. This flag currently 1815 only has an effect on ELF targets. 1816 1817**-f[no]-unique-internal-linkage-names** 1818 1819 Controls whether Clang emits a unique (best-effort) symbol name for internal 1820 linkage symbols. When this option is set, compiler hashes the main source 1821 file path from the command line and appends it to all internal symbols. If a 1822 program contains multiple objects compiled with the same command-line source 1823 file path, the symbols are not guaranteed to be unique. This option is 1824 particularly useful in attributing profile information to the correct 1825 function when multiple functions with the same private linkage name exist 1826 in the binary. 1827 1828 It should be noted that this option cannot guarantee uniqueness and the 1829 following is an example where it is not unique when two modules contain 1830 symbols with the same private linkage name: 1831 1832 .. code-block:: console 1833 1834 $ cd $P/foo && clang -c -funique-internal-linkage-names name_conflict.c 1835 $ cd $P/bar && clang -c -funique-internal-linkage-names name_conflict.c 1836 $ cd $P && clang foo/name_conflict.o && bar/name_conflict.o 1837 1838**-fbasic-block-sections=[labels, all, list=<arg>, none]** 1839 1840 Controls how Clang emits text sections for basic blocks. With values ``all`` 1841 and ``list=<arg>``, each basic block or a subset of basic blocks can be placed 1842 in its own unique section. With the "labels" value, normal text sections are 1843 emitted, but a ``.bb_addr_map`` section is emitted which includes address 1844 offsets for each basic block in the program, relative to the parent function 1845 address. 1846 1847 With the ``list=<arg>`` option, a file containing the subset of basic blocks 1848 that need to placed in unique sections can be specified. The format of the 1849 file is as follows. For example, ``list=spec.txt`` where ``spec.txt`` is the 1850 following: 1851 1852 :: 1853 1854 !foo 1855 !!2 1856 !_Z3barv 1857 1858 will place the machine basic block with ``id 2`` in function ``foo`` in a 1859 unique section. It will also place all basic blocks of functions ``bar`` 1860 in unique sections. 1861 1862 Further, section clusters can also be specified using the ``list=<arg>`` 1863 option. For example, ``list=spec.txt`` where ``spec.txt`` contains: 1864 1865 :: 1866 1867 !foo 1868 !!1 !!3 !!5 1869 !!2 !!4 !!6 1870 1871 will create two unique sections for function ``foo`` with the first 1872 containing the odd numbered basic blocks and the second containing the 1873 even numbered basic blocks. 1874 1875 Basic block sections allow the linker to reorder basic blocks and enables 1876 link-time optimizations like whole program inter-procedural basic block 1877 reordering. 1878 1879Profile Guided Optimization 1880--------------------------- 1881 1882Profile information enables better optimization. For example, knowing that a 1883branch is taken very frequently helps the compiler make better decisions when 1884ordering basic blocks. Knowing that a function ``foo`` is called more 1885frequently than another function ``bar`` helps the inliner. Optimization 1886levels ``-O2`` and above are recommended for use of profile guided optimization. 1887 1888Clang supports profile guided optimization with two different kinds of 1889profiling. A sampling profiler can generate a profile with very low runtime 1890overhead, or you can build an instrumented version of the code that collects 1891more detailed profile information. Both kinds of profiles can provide execution 1892counts for instructions in the code and information on branches taken and 1893function invocation. 1894 1895Regardless of which kind of profiling you use, be careful to collect profiles 1896by running your code with inputs that are representative of the typical 1897behavior. Code that is not exercised in the profile will be optimized as if it 1898is unimportant, and the compiler may make poor optimization choices for code 1899that is disproportionately used while profiling. 1900 1901Differences Between Sampling and Instrumentation 1902^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1903 1904Although both techniques are used for similar purposes, there are important 1905differences between the two: 1906 19071. Profile data generated with one cannot be used by the other, and there is no 1908 conversion tool that can convert one to the other. So, a profile generated 1909 via ``-fprofile-instr-generate`` must be used with ``-fprofile-instr-use``. 1910 Similarly, sampling profiles generated by external profilers must be 1911 converted and used with ``-fprofile-sample-use``. 1912 19132. Instrumentation profile data can be used for code coverage analysis and 1914 optimization. 1915 19163. Sampling profiles can only be used for optimization. They cannot be used for 1917 code coverage analysis. Although it would be technically possible to use 1918 sampling profiles for code coverage, sample-based profiles are too 1919 coarse-grained for code coverage purposes; it would yield poor results. 1920 19214. Sampling profiles must be generated by an external tool. The profile 1922 generated by that tool must then be converted into a format that can be read 1923 by LLVM. The section on sampling profilers describes one of the supported 1924 sampling profile formats. 1925 1926 1927Using Sampling Profilers 1928^^^^^^^^^^^^^^^^^^^^^^^^ 1929 1930Sampling profilers are used to collect runtime information, such as 1931hardware counters, while your application executes. They are typically 1932very efficient and do not incur a large runtime overhead. The 1933sample data collected by the profiler can be used during compilation 1934to determine what the most executed areas of the code are. 1935 1936Using the data from a sample profiler requires some changes in the way 1937a program is built. Before the compiler can use profiling information, 1938the code needs to execute under the profiler. The following is the 1939usual build cycle when using sample profilers for optimization: 1940 19411. Build the code with source line table information. You can use all the 1942 usual build flags that you always build your application with. The only 1943 requirement is that you add ``-gline-tables-only`` or ``-g`` to the 1944 command line. This is important for the profiler to be able to map 1945 instructions back to source line locations. 1946 1947 .. code-block:: console 1948 1949 $ clang++ -O2 -gline-tables-only code.cc -o code 1950 19512. Run the executable under a sampling profiler. The specific profiler 1952 you use does not really matter, as long as its output can be converted 1953 into the format that the LLVM optimizer understands. Currently, there 1954 exists a conversion tool for the Linux Perf profiler 1955 (https://perf.wiki.kernel.org/), so these examples assume that you 1956 are using Linux Perf to profile your code. 1957 1958 .. code-block:: console 1959 1960 $ perf record -b ./code 1961 1962 Note the use of the ``-b`` flag. This tells Perf to use the Last Branch 1963 Record (LBR) to record call chains. While this is not strictly required, 1964 it provides better call information, which improves the accuracy of 1965 the profile data. 1966 19673. Convert the collected profile data to LLVM's sample profile format. 1968 This is currently supported via the AutoFDO converter ``create_llvm_prof``. 1969 It is available at https://github.com/google/autofdo. Once built and 1970 installed, you can convert the ``perf.data`` file to LLVM using 1971 the command: 1972 1973 .. code-block:: console 1974 1975 $ create_llvm_prof --binary=./code --out=code.prof 1976 1977 This will read ``perf.data`` and the binary file ``./code`` and emit 1978 the profile data in ``code.prof``. Note that if you ran ``perf`` 1979 without the ``-b`` flag, you need to use ``--use_lbr=false`` when 1980 calling ``create_llvm_prof``. 1981 19824. Build the code again using the collected profile. This step feeds 1983 the profile back to the optimizers. This should result in a binary 1984 that executes faster than the original one. Note that you are not 1985 required to build the code with the exact same arguments that you 1986 used in the first step. The only requirement is that you build the code 1987 with ``-gline-tables-only`` and ``-fprofile-sample-use``. 1988 1989 .. code-block:: console 1990 1991 $ clang++ -O2 -gline-tables-only -fprofile-sample-use=code.prof code.cc -o code 1992 1993 1994Sample Profile Formats 1995"""""""""""""""""""""" 1996 1997Since external profilers generate profile data in a variety of custom formats, 1998the data generated by the profiler must be converted into a format that can be 1999read by the backend. LLVM supports three different sample profile formats: 2000 20011. ASCII text. This is the easiest one to generate. The file is divided into 2002 sections, which correspond to each of the functions with profile 2003 information. The format is described below. It can also be generated from 2004 the binary or gcov formats using the ``llvm-profdata`` tool. 2005 20062. Binary encoding. This uses a more efficient encoding that yields smaller 2007 profile files. This is the format generated by the ``create_llvm_prof`` tool 2008 in https://github.com/google/autofdo. 2009 20103. GCC encoding. This is based on the gcov format, which is accepted by GCC. It 2011 is only interesting in environments where GCC and Clang co-exist. This 2012 encoding is only generated by the ``create_gcov`` tool in 2013 https://github.com/google/autofdo. It can be read by LLVM and 2014 ``llvm-profdata``, but it cannot be generated by either. 2015 2016If you are using Linux Perf to generate sampling profiles, you can use the 2017conversion tool ``create_llvm_prof`` described in the previous section. 2018Otherwise, you will need to write a conversion tool that converts your 2019profiler's native format into one of these three. 2020 2021 2022Sample Profile Text Format 2023"""""""""""""""""""""""""" 2024 2025This section describes the ASCII text format for sampling profiles. It is, 2026arguably, the easiest one to generate. If you are interested in generating any 2027of the other two, consult the ``ProfileData`` library in LLVM's source tree 2028(specifically, ``include/llvm/ProfileData/SampleProfReader.h``). 2029 2030.. code-block:: console 2031 2032 function1:total_samples:total_head_samples 2033 offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ] 2034 offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ] 2035 ... 2036 offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ] 2037 offsetA[.discriminator]: fnA:num_of_total_samples 2038 offsetA1[.discriminator]: number_of_samples [fn7:num fn8:num ... ] 2039 offsetA1[.discriminator]: number_of_samples [fn9:num fn10:num ... ] 2040 offsetB[.discriminator]: fnB:num_of_total_samples 2041 offsetB1[.discriminator]: number_of_samples [fn11:num fn12:num ... ] 2042 2043This is a nested tree in which the indentation represents the nesting level 2044of the inline stack. There are no blank lines in the file. And the spacing 2045within a single line is fixed. Additional spaces will result in an error 2046while reading the file. 2047 2048Any line starting with the '#' character is completely ignored. 2049 2050Inlined calls are represented with indentation. The Inline stack is a 2051stack of source locations in which the top of the stack represents the 2052leaf function, and the bottom of the stack represents the actual 2053symbol to which the instruction belongs. 2054 2055Function names must be mangled in order for the profile loader to 2056match them in the current translation unit. The two numbers in the 2057function header specify how many total samples were accumulated in the 2058function (first number), and the total number of samples accumulated 2059in the prologue of the function (second number). This head sample 2060count provides an indicator of how frequently the function is invoked. 2061 2062There are two types of lines in the function body. 2063 2064- Sampled line represents the profile information of a source location. 2065 ``offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]`` 2066 2067- Callsite line represents the profile information of an inlined callsite. 2068 ``offsetA[.discriminator]: fnA:num_of_total_samples`` 2069 2070Each sampled line may contain several items. Some are optional (marked 2071below): 2072 2073a. Source line offset. This number represents the line number 2074 in the function where the sample was collected. The line number is 2075 always relative to the line where symbol of the function is 2076 defined. So, if the function has its header at line 280, the offset 2077 13 is at line 293 in the file. 2078 2079 Note that this offset should never be a negative number. This could 2080 happen in cases like macros. The debug machinery will register the 2081 line number at the point of macro expansion. So, if the macro was 2082 expanded in a line before the start of the function, the profile 2083 converter should emit a 0 as the offset (this means that the optimizers 2084 will not be able to associate a meaningful weight to the instructions 2085 in the macro). 2086 2087b. [OPTIONAL] Discriminator. This is used if the sampled program 2088 was compiled with DWARF discriminator support 2089 (http://wiki.dwarfstd.org/index.php?title=Path_Discriminators). 2090 DWARF discriminators are unsigned integer values that allow the 2091 compiler to distinguish between multiple execution paths on the 2092 same source line location. 2093 2094 For example, consider the line of code ``if (cond) foo(); else bar();``. 2095 If the predicate ``cond`` is true 80% of the time, then the edge 2096 into function ``foo`` should be considered to be taken most of the 2097 time. But both calls to ``foo`` and ``bar`` are at the same source 2098 line, so a sample count at that line is not sufficient. The 2099 compiler needs to know which part of that line is taken more 2100 frequently. 2101 2102 This is what discriminators provide. In this case, the calls to 2103 ``foo`` and ``bar`` will be at the same line, but will have 2104 different discriminator values. This allows the compiler to correctly 2105 set edge weights into ``foo`` and ``bar``. 2106 2107c. Number of samples. This is an integer quantity representing the 2108 number of samples collected by the profiler at this source 2109 location. 2110 2111d. [OPTIONAL] Potential call targets and samples. If present, this 2112 line contains a call instruction. This models both direct and 2113 number of samples. For example, 2114 2115 .. code-block:: console 2116 2117 130: 7 foo:3 bar:2 baz:7 2118 2119 The above means that at relative line offset 130 there is a call 2120 instruction that calls one of ``foo()``, ``bar()`` and ``baz()``, 2121 with ``baz()`` being the relatively more frequently called target. 2122 2123As an example, consider a program with the call chain ``main -> foo -> bar``. 2124When built with optimizations enabled, the compiler may inline the 2125calls to ``bar`` and ``foo`` inside ``main``. The generated profile 2126could then be something like this: 2127 2128.. code-block:: console 2129 2130 main:35504:0 2131 1: _Z3foov:35504 2132 2: _Z32bari:31977 2133 1.1: 31977 2134 2: 0 2135 2136This profile indicates that there were a total of 35,504 samples 2137collected in main. All of those were at line 1 (the call to ``foo``). 2138Of those, 31,977 were spent inside the body of ``bar``. The last line 2139of the profile (``2: 0``) corresponds to line 2 inside ``main``. No 2140samples were collected there. 2141 2142Profiling with Instrumentation 2143^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2144 2145Clang also supports profiling via instrumentation. This requires building a 2146special instrumented version of the code and has some runtime 2147overhead during the profiling, but it provides more detailed results than a 2148sampling profiler. It also provides reproducible results, at least to the 2149extent that the code behaves consistently across runs. 2150 2151Here are the steps for using profile guided optimization with 2152instrumentation: 2153 21541. Build an instrumented version of the code by compiling and linking with the 2155 ``-fprofile-instr-generate`` option. 2156 2157 .. code-block:: console 2158 2159 $ clang++ -O2 -fprofile-instr-generate code.cc -o code 2160 21612. Run the instrumented executable with inputs that reflect the typical usage. 2162 By default, the profile data will be written to a ``default.profraw`` file 2163 in the current directory. You can override that default by using option 2164 ``-fprofile-instr-generate=`` or by setting the ``LLVM_PROFILE_FILE`` 2165 environment variable to specify an alternate file. If non-default file name 2166 is specified by both the environment variable and the command line option, 2167 the environment variable takes precedence. The file name pattern specified 2168 can include different modifiers: ``%p``, ``%h``, and ``%m``. 2169 2170 Any instance of ``%p`` in that file name will be replaced by the process 2171 ID, so that you can easily distinguish the profile output from multiple 2172 runs. 2173 2174 .. code-block:: console 2175 2176 $ LLVM_PROFILE_FILE="code-%p.profraw" ./code 2177 2178 The modifier ``%h`` can be used in scenarios where the same instrumented 2179 binary is run in multiple different host machines dumping profile data 2180 to a shared network based storage. The ``%h`` specifier will be substituted 2181 with the hostname so that profiles collected from different hosts do not 2182 clobber each other. 2183 2184 While the use of ``%p`` specifier can reduce the likelihood for the profiles 2185 dumped from different processes to clobber each other, such clobbering can still 2186 happen because of the ``pid`` re-use by the OS. Another side-effect of using 2187 ``%p`` is that the storage requirement for raw profile data files is greatly 2188 increased. To avoid issues like this, the ``%m`` specifier can used in the profile 2189 name. When this specifier is used, the profiler runtime will substitute ``%m`` 2190 with a unique integer identifier associated with the instrumented binary. Additionally, 2191 multiple raw profiles dumped from different processes that share a file system (can be 2192 on different hosts) will be automatically merged by the profiler runtime during the 2193 dumping. If the program links in multiple instrumented shared libraries, each library 2194 will dump the profile data into its own profile data file (with its unique integer 2195 id embedded in the profile name). Note that the merging enabled by ``%m`` is for raw 2196 profile data generated by profiler runtime. The resulting merged "raw" profile data 2197 file still needs to be converted to a different format expected by the compiler ( 2198 see step 3 below). 2199 2200 .. code-block:: console 2201 2202 $ LLVM_PROFILE_FILE="code-%m.profraw" ./code 2203 2204 22053. Combine profiles from multiple runs and convert the "raw" profile format to 2206 the input expected by clang. Use the ``merge`` command of the 2207 ``llvm-profdata`` tool to do this. 2208 2209 .. code-block:: console 2210 2211 $ llvm-profdata merge -output=code.profdata code-*.profraw 2212 2213 Note that this step is necessary even when there is only one "raw" profile, 2214 since the merge operation also changes the file format. 2215 22164. Build the code again using the ``-fprofile-instr-use`` option to specify the 2217 collected profile data. 2218 2219 .. code-block:: console 2220 2221 $ clang++ -O2 -fprofile-instr-use=code.profdata code.cc -o code 2222 2223 You can repeat step 4 as often as you like without regenerating the 2224 profile. As you make changes to your code, clang may no longer be able to 2225 use the profile data. It will warn you when this happens. 2226 2227Profile generation using an alternative instrumentation method can be 2228controlled by the GCC-compatible flags ``-fprofile-generate`` and 2229``-fprofile-use``. Although these flags are semantically equivalent to 2230their GCC counterparts, they *do not* handle GCC-compatible profiles. 2231They are only meant to implement GCC's semantics with respect to 2232profile creation and use. Flag ``-fcs-profile-generate`` also instruments 2233programs using the same instrumentation method as ``-fprofile-generate``. 2234 2235.. option:: -fprofile-generate[=<dirname>] 2236 2237 The ``-fprofile-generate`` and ``-fprofile-generate=`` flags will use 2238 an alternative instrumentation method for profile generation. When 2239 given a directory name, it generates the profile file 2240 ``default_%m.profraw`` in the directory named ``dirname`` if specified. 2241 If ``dirname`` does not exist, it will be created at runtime. ``%m`` specifier 2242 will be substituted with a unique id documented in step 2 above. In other words, 2243 with ``-fprofile-generate[=<dirname>]`` option, the "raw" profile data automatic 2244 merging is turned on by default, so there will no longer any risk of profile 2245 clobbering from different running processes. For example, 2246 2247 .. code-block:: console 2248 2249 $ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code 2250 2251 When ``code`` is executed, the profile will be written to the file 2252 ``yyy/zzz/default_xxxx.profraw``. 2253 2254 To generate the profile data file with the compiler readable format, the 2255 ``llvm-profdata`` tool can be used with the profile directory as the input: 2256 2257 .. code-block:: console 2258 2259 $ llvm-profdata merge -output=code.profdata yyy/zzz/ 2260 2261 If the user wants to turn off the auto-merging feature, or simply override the 2262 the profile dumping path specified at command line, the environment variable 2263 ``LLVM_PROFILE_FILE`` can still be used to override 2264 the directory and filename for the profile file at runtime. 2265 2266.. option:: -fcs-profile-generate[=<dirname>] 2267 2268 The ``-fcs-profile-generate`` and ``-fcs-profile-generate=`` flags will use 2269 the same instrumentation method, and generate the same profile as in the 2270 ``-fprofile-generate`` and ``-fprofile-generate=`` flags. The difference is 2271 that the instrumentation is performed after inlining so that the resulted 2272 profile has a better context sensitive information. They cannot be used 2273 together with ``-fprofile-generate`` and ``-fprofile-generate=`` flags. 2274 They are typically used in conjunction with ``-fprofile-use`` flag. 2275 The profile generated by ``-fcs-profile-generate`` and ``-fprofile-generate`` 2276 can be merged by llvm-profdata. A use example: 2277 2278 .. code-block:: console 2279 2280 $ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code 2281 $ ./code 2282 $ llvm-profdata merge -output=code.profdata yyy/zzz/ 2283 2284 The first few steps are the same as that in ``-fprofile-generate`` 2285 compilation. Then perform a second round of instrumentation. 2286 2287 .. code-block:: console 2288 2289 $ clang++ -O2 -fprofile-use=code.profdata -fcs-profile-generate=sss/ttt \ 2290 -o cs_code 2291 $ ./cs_code 2292 $ llvm-profdata merge -output=cs_code.profdata sss/ttt code.profdata 2293 2294 The resulted ``cs_code.prodata`` combines ``code.profdata`` and the profile 2295 generated from binary ``cs_code``. Profile ``cs_code.profata`` can be used by 2296 ``-fprofile-use`` compilation. 2297 2298 .. code-block:: console 2299 2300 $ clang++ -O2 -fprofile-use=cs_code.profdata 2301 2302 The above command will read both profiles to the compiler at the identical 2303 point of instrumentations. 2304 2305.. option:: -fprofile-use[=<pathname>] 2306 2307 Without any other arguments, ``-fprofile-use`` behaves identically to 2308 ``-fprofile-instr-use``. Otherwise, if ``pathname`` is the full path to a 2309 profile file, it reads from that file. If ``pathname`` is a directory name, 2310 it reads from ``pathname/default.profdata``. 2311 2312.. option:: -fprofile-update[=<method>] 2313 2314 Unless ``-fsanitize=thread`` is specified, the default is ``single``, which 2315 uses non-atomic increments. The counters can be inaccurate under thread 2316 contention. ``atomic`` uses atomic increments which is accurate but has 2317 overhead. ``prefer-atomic`` will be transformed to ``atomic`` when supported 2318 by the target, or ``single`` otherwise. 2319 2320 This option currently works with ``-fprofile-arcs`` and ``-fprofile-instr-generate``, 2321 but not with ``-fprofile-generate``. 2322 2323Disabling Instrumentation 2324^^^^^^^^^^^^^^^^^^^^^^^^^ 2325 2326In certain situations, it may be useful to disable profile generation or use 2327for specific files in a build, without affecting the main compilation flags 2328used for the other files in the project. 2329 2330In these cases, you can use the flag ``-fno-profile-instr-generate`` (or 2331``-fno-profile-generate``) to disable profile generation, and 2332``-fno-profile-instr-use`` (or ``-fno-profile-use``) to disable profile use. 2333 2334Note that these flags should appear after the corresponding profile 2335flags to have an effect. 2336 2337Instrumenting only selected files or functions 2338^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2339 2340Sometimes it's useful to only instrument certain files or functions. For 2341example in automated testing infrastructure, it may be desirable to only 2342instrument files or functions that were modified by a patch to reduce the 2343overhead of instrumenting a full system. 2344 2345This can be done using the ``-fprofile-list`` option. 2346 2347.. option:: -fprofile-list=<pathname> 2348 2349 This option can be used to apply profile instrumentation only to selected 2350 files or functions. ``pathname`` should point to a file in the 2351 :doc:`SanitizerSpecialCaseList` format which selects which files and 2352 functions to instrument. 2353 2354 .. code-block:: console 2355 2356 $ echo "fun:test" > fun.list 2357 $ clang++ -O2 -fprofile-instr-generate -fprofile-list=fun.list code.cc -o code 2358 2359The option can be specified multiple times to pass multiple files. 2360 2361.. code-block:: console 2362 2363 $ echo "!fun:*test*" > fun.list 2364 $ echo "src:code.cc" > src.list 2365 % clang++ -O2 -fprofile-instr-generate -fcoverage-mapping -fprofile-list=fun.list -fprofile-list=code.list code.cc -o code 2366 2367To filter individual functions or entire source files using ``fun:<name>`` or 2368``src:<file>`` respectively. To exclude a function or a source file, use 2369``!fun:<name>`` or ``!src:<file>`` respectively. The format also supports 2370wildcard expansion. The compiler generated functions are assumed to be located 2371in the main source file. It is also possible to restrict the filter to a 2372particular instrumentation type by using a named section. 2373 2374.. code-block:: none 2375 2376 # all functions whose name starts with foo will be instrumented. 2377 fun:foo* 2378 2379 # except for foo1 which will be excluded from instrumentation. 2380 !fun:foo1 2381 2382 # every function in path/to/foo.cc will be instrumented. 2383 src:path/to/foo.cc 2384 2385 # bar will be instrumented only when using backend instrumentation. 2386 # Recognized section names are clang, llvm and csllvm. 2387 [llvm] 2388 fun:bar 2389 2390When the file contains only excludes, all files and functions except for the 2391excluded ones will be instrumented. Otherwise, only the files and functions 2392specified will be instrumented. 2393 2394Profile remapping 2395^^^^^^^^^^^^^^^^^ 2396 2397When the program is compiled after a change that affects many symbol names, 2398pre-existing profile data may no longer match the program. For example: 2399 2400 * switching from libstdc++ to libc++ will result in the mangled names of all 2401 functions taking standard library types to change 2402 * renaming a widely-used type in C++ will result in the mangled names of all 2403 functions that have parameters involving that type to change 2404 * moving from a 32-bit compilation to a 64-bit compilation may change the 2405 underlying type of ``size_t`` and similar types, resulting in changes to 2406 manglings 2407 2408Clang allows use of a profile remapping file to specify that such differences 2409in mangled names should be ignored when matching the profile data against the 2410program. 2411 2412.. option:: -fprofile-remapping-file=<file> 2413 2414 Specifies a file containing profile remapping information, that will be 2415 used to match mangled names in the profile data to mangled names in the 2416 program. 2417 2418The profile remapping file is a text file containing lines of the form 2419 2420.. code-block:: text 2421 2422 fragmentkind fragment1 fragment2 2423 2424where ``fragmentkind`` is one of ``name``, ``type``, or ``encoding``, 2425indicating whether the following mangled name fragments are 2426<`name <https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.name>`_>s, 2427<`type <https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.type>`_>s, or 2428<`encoding <https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.encoding>`_>s, 2429respectively. 2430Blank lines and lines starting with ``#`` are ignored. 2431 2432For convenience, built-in <substitution>s such as ``St`` and ``Ss`` 2433are accepted as <name>s (even though they technically are not <name>s). 2434 2435For example, to specify that ``absl::string_view`` and ``std::string_view`` 2436should be treated as equivalent when matching profile data, the following 2437remapping file could be used: 2438 2439.. code-block:: text 2440 2441 # absl::string_view is considered equivalent to std::string_view 2442 type N4absl11string_viewE St17basic_string_viewIcSt11char_traitsIcEE 2443 2444 # std:: might be std::__1:: in libc++ or std::__cxx11:: in libstdc++ 2445 name 3std St3__1 2446 name 3std St7__cxx11 2447 2448Matching profile data using a profile remapping file is supported on a 2449best-effort basis. For example, information regarding indirect call targets is 2450currently not remapped. For best results, you are encouraged to generate new 2451profile data matching the updated program, or to remap the profile data 2452using the ``llvm-cxxmap`` and ``llvm-profdata merge`` tools. 2453 2454.. note:: 2455 2456 Profile data remapping support is currently only implemented for LLVM's 2457 new pass manager, which can be enabled with 2458 ``-fexperimental-new-pass-manager``. 2459 2460.. note:: 2461 2462 Profile data remapping is currently only supported for C++ mangled names 2463 following the Itanium C++ ABI mangling scheme. This covers all C++ targets 2464 supported by Clang other than Windows. 2465 2466GCOV-based Profiling 2467-------------------- 2468 2469GCOV is a test coverage program, it helps to know how often a line of code 2470is executed. When instrumenting the code with ``--coverage`` option, some 2471counters are added for each edge linking basic blocks. 2472 2473At compile time, gcno files are generated containing information about 2474blocks and edges between them. At runtime the counters are incremented and at 2475exit the counters are dumped in gcda files. 2476 2477The tool ``llvm-cov gcov`` will parse gcno, gcda and source files to generate 2478a report ``.c.gcov``. 2479 2480.. option:: -fprofile-filter-files=[regexes] 2481 2482 Define a list of regexes separated by a semi-colon. 2483 If a file name matches any of the regexes then the file is instrumented. 2484 2485 .. code-block:: console 2486 2487 $ clang --coverage -fprofile-filter-files=".*\.c$" foo.c 2488 2489 For example, this will only instrument files finishing with ``.c``, skipping ``.h`` files. 2490 2491.. option:: -fprofile-exclude-files=[regexes] 2492 2493 Define a list of regexes separated by a semi-colon. 2494 If a file name doesn't match all the regexes then the file is instrumented. 2495 2496 .. code-block:: console 2497 2498 $ clang --coverage -fprofile-exclude-files="^/usr/include/.*$" foo.c 2499 2500 For example, this will instrument all the files except the ones in ``/usr/include``. 2501 2502If both options are used then a file is instrumented if its name matches any 2503of the regexes from ``-fprofile-filter-list`` and doesn't match all the regexes 2504from ``-fprofile-exclude-list``. 2505 2506.. code-block:: console 2507 2508 $ clang --coverage -fprofile-exclude-files="^/usr/include/.*$" \ 2509 -fprofile-filter-files="^/usr/.*$" 2510 2511In that case ``/usr/foo/oof.h`` is instrumented since it matches the filter regex and 2512doesn't match the exclude regex, but ``/usr/include/foo.h`` doesn't since it matches 2513the exclude regex. 2514 2515Controlling Debug Information 2516----------------------------- 2517 2518Controlling Size of Debug Information 2519^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2520 2521Debug info kind generated by Clang can be set by one of the flags listed 2522below. If multiple flags are present, the last one is used. 2523 2524.. option:: -g0 2525 2526 Don't generate any debug info (default). 2527 2528.. option:: -gline-tables-only 2529 2530 Generate line number tables only. 2531 2532 This kind of debug info allows to obtain stack traces with function names, 2533 file names and line numbers (by such tools as ``gdb`` or ``addr2line``). It 2534 doesn't contain any other data (e.g. description of local variables or 2535 function parameters). 2536 2537.. option:: -fstandalone-debug 2538 2539 Clang supports a number of optimizations to reduce the size of debug 2540 information in the binary. They work based on the assumption that 2541 the debug type information can be spread out over multiple 2542 compilation units. For instance, Clang will not emit type 2543 definitions for types that are not needed by a module and could be 2544 replaced with a forward declaration. Further, Clang will only emit 2545 type info for a dynamic C++ class in the module that contains the 2546 vtable for the class. 2547 2548 The **-fstandalone-debug** option turns off these optimizations. 2549 This is useful when working with 3rd-party libraries that don't come 2550 with debug information. Note that Clang will never emit type 2551 information for types that are not referenced at all by the program. 2552 2553.. option:: -fno-standalone-debug 2554 2555 On Darwin **-fstandalone-debug** is enabled by default. The 2556 **-fno-standalone-debug** option can be used to get to turn on the 2557 vtable-based optimization described above. 2558 2559.. option:: -fuse-ctor-homing 2560 2561 This optimization is similar to the optimizations that are enabled as part 2562 of -fno-standalone-debug. Here, Clang only emits type info for a 2563 non-trivial, non-aggregate C++ class in the modules that contain a 2564 definition of one of its constructors. This relies on the additional 2565 assumption that all classes that are not trivially constructible have a 2566 non-trivial constructor that is used somewhere. The negation, 2567 -fno-use-ctor-homing, ensures that constructor homing is not used. 2568 2569 This flag is not enabled by default, and needs to be used with -cc1 or 2570 -Xclang. 2571 2572.. option:: -g 2573 2574 Generate complete debug info. 2575 2576.. option:: -feliminate-unused-debug-types 2577 2578 By default, Clang does not emit type information for types that are defined 2579 but not used in a program. To retain the debug info for these unused types, 2580 the negation **-fno-eliminate-unused-debug-types** can be used. 2581 2582Controlling Macro Debug Info Generation 2583^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2584 2585Debug info for C preprocessor macros increases the size of debug information in 2586the binary. Macro debug info generated by Clang can be controlled by the flags 2587listed below. 2588 2589.. option:: -fdebug-macro 2590 2591 Generate debug info for preprocessor macros. This flag is discarded when 2592 **-g0** is enabled. 2593 2594.. option:: -fno-debug-macro 2595 2596 Do not generate debug info for preprocessor macros (default). 2597 2598Controlling Debugger "Tuning" 2599^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2600 2601While Clang generally emits standard DWARF debug info (http://dwarfstd.org), 2602different debuggers may know how to take advantage of different specific DWARF 2603features. You can "tune" the debug info for one of several different debuggers. 2604 2605.. option:: -ggdb, -glldb, -gsce, -gdbx 2606 2607 Tune the debug info for the ``gdb``, ``lldb``, Sony PlayStation\ |reg| 2608 debugger, or ``dbx``, respectively. Each of these options implies **-g**. 2609 (Therefore, if you want both **-gline-tables-only** and debugger tuning, the 2610 tuning option must come first.) 2611 2612Controlling LLVM IR Output 2613-------------------------- 2614 2615Controlling Value Names in LLVM IR 2616^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2617 2618Emitting value names in LLVM IR increases the size and verbosity of the IR. 2619By default, value names are only emitted in assertion-enabled builds of Clang. 2620However, when reading IR it can be useful to re-enable the emission of value 2621names to improve readability. 2622 2623.. option:: -fdiscard-value-names 2624 2625 Discard value names when generating LLVM IR. 2626 2627.. option:: -fno-discard-value-names 2628 2629 Do not discard value names when generating LLVM IR. This option can be used 2630 to re-enable names for release builds of Clang. 2631 2632 2633Comment Parsing Options 2634----------------------- 2635 2636Clang parses Doxygen and non-Doxygen style documentation comments and attaches 2637them to the appropriate declaration nodes. By default, it only parses 2638Doxygen-style comments and ignores ordinary comments starting with ``//`` and 2639``/*``. 2640 2641.. option:: -Wdocumentation 2642 2643 Emit warnings about use of documentation comments. This warning group is off 2644 by default. 2645 2646 This includes checking that ``\param`` commands name parameters that actually 2647 present in the function signature, checking that ``\returns`` is used only on 2648 functions that actually return a value etc. 2649 2650.. option:: -Wno-documentation-unknown-command 2651 2652 Don't warn when encountering an unknown Doxygen command. 2653 2654.. option:: -fparse-all-comments 2655 2656 Parse all comments as documentation comments (including ordinary comments 2657 starting with ``//`` and ``/*``). 2658 2659.. option:: -fcomment-block-commands=[commands] 2660 2661 Define custom documentation commands as block commands. This allows Clang to 2662 construct the correct AST for these custom commands, and silences warnings 2663 about unknown commands. Several commands must be separated by a comma 2664 *without trailing space*; e.g. ``-fcomment-block-commands=foo,bar`` defines 2665 custom commands ``\foo`` and ``\bar``. 2666 2667 It is also possible to use ``-fcomment-block-commands`` several times; e.g. 2668 ``-fcomment-block-commands=foo -fcomment-block-commands=bar`` does the same 2669 as above. 2670 2671.. _c: 2672 2673C Language Features 2674=================== 2675 2676The support for standard C in clang is feature-complete except for the 2677C99 floating-point pragmas. 2678 2679Extensions supported by clang 2680----------------------------- 2681 2682See :doc:`LanguageExtensions`. 2683 2684Differences between various standard modes 2685------------------------------------------ 2686 2687clang supports the -std option, which changes what language mode clang uses. 2688The supported modes for C are c89, gnu89, c94, c99, gnu99, c11, gnu11, c17, 2689gnu17, c2x, gnu2x, and various aliases for those modes. If no -std option is 2690specified, clang defaults to gnu17 mode. Many C99 and C11 features are 2691supported in earlier modes as a conforming extension, with a warning. Use 2692``-pedantic-errors`` to request an error if a feature from a later standard 2693revision is used in an earlier mode. 2694 2695Differences between all ``c*`` and ``gnu*`` modes: 2696 2697- ``c*`` modes define "``__STRICT_ANSI__``". 2698- Target-specific defines not prefixed by underscores, like ``linux``, 2699 are defined in ``gnu*`` modes. 2700- Trigraphs default to being off in ``gnu*`` modes; they can be enabled 2701 by the ``-trigraphs`` option. 2702- The parser recognizes ``asm`` and ``typeof`` as keywords in ``gnu*`` modes; 2703 the variants ``__asm__`` and ``__typeof__`` are recognized in all modes. 2704- The parser recognizes ``inline`` as a keyword in ``gnu*`` mode, in 2705 addition to recognizing it in the ``*99`` and later modes for which it is 2706 part of the ISO C standard. The variant ``__inline__`` is recognized in all 2707 modes. 2708- The Apple "blocks" extension is recognized by default in ``gnu*`` modes 2709 on some platforms; it can be enabled in any mode with the ``-fblocks`` 2710 option. 2711 2712Differences between ``*89`` and ``*94`` modes: 2713 2714- Digraphs are not recognized in c89 mode. 2715 2716Differences between ``*94`` and ``*99`` modes: 2717 2718- The ``*99`` modes default to implementing ``inline`` / ``__inline__`` 2719 as specified in C99, while the ``*89`` modes implement the GNU version. 2720 This can be overridden for individual functions with the ``__gnu_inline__`` 2721 attribute. 2722- The scope of names defined inside a ``for``, ``if``, ``switch``, ``while``, 2723 or ``do`` statement is different. (example: ``if ((struct x {int x;}*)0) {}``.) 2724- ``__STDC_VERSION__`` is not defined in ``*89`` modes. 2725- ``inline`` is not recognized as a keyword in ``c89`` mode. 2726- ``restrict`` is not recognized as a keyword in ``*89`` modes. 2727- Commas are allowed in integer constant expressions in ``*99`` modes. 2728- Arrays which are not lvalues are not implicitly promoted to pointers 2729 in ``*89`` modes. 2730- Some warnings are different. 2731 2732Differences between ``*99`` and ``*11`` modes: 2733 2734- Warnings for use of C11 features are disabled. 2735- ``__STDC_VERSION__`` is defined to ``201112L`` rather than ``199901L``. 2736 2737Differences between ``*11`` and ``*17`` modes: 2738 2739- ``__STDC_VERSION__`` is defined to ``201710L`` rather than ``201112L``. 2740 2741GCC extensions not implemented yet 2742---------------------------------- 2743 2744clang tries to be compatible with gcc as much as possible, but some gcc 2745extensions are not implemented yet: 2746 2747- clang does not support decimal floating point types (``_Decimal32`` and 2748 friends) yet. 2749- clang does not support nested functions; this is a complex feature 2750 which is infrequently used, so it is unlikely to be implemented 2751 anytime soon. In C++11 it can be emulated by assigning lambda 2752 functions to local variables, e.g: 2753 2754 .. code-block:: cpp 2755 2756 auto const local_function = [&](int parameter) { 2757 // Do something 2758 }; 2759 ... 2760 local_function(1); 2761 2762- clang only supports global register variables when the register specified 2763 is non-allocatable (e.g. the stack pointer). Support for general global 2764 register variables is unlikely to be implemented soon because it requires 2765 additional LLVM backend support. 2766- clang does not support static initialization of flexible array 2767 members. This appears to be a rarely used extension, but could be 2768 implemented pending user demand. 2769- clang does not support 2770 ``__builtin_va_arg_pack``/``__builtin_va_arg_pack_len``. This is 2771 used rarely, but in some potentially interesting places, like the 2772 glibc headers, so it may be implemented pending user demand. Note 2773 that because clang pretends to be like GCC 4.2, and this extension 2774 was introduced in 4.3, the glibc headers will not try to use this 2775 extension with clang at the moment. 2776- clang does not support the gcc extension for forward-declaring 2777 function parameters; this has not shown up in any real-world code 2778 yet, though, so it might never be implemented. 2779 2780This is not a complete list; if you find an unsupported extension 2781missing from this list, please send an e-mail to cfe-dev. This list 2782currently excludes C++; see :ref:`C++ Language Features <cxx>`. Also, this 2783list does not include bugs in mostly-implemented features; please see 2784the `bug 2785tracker <https://bugs.llvm.org/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer>`_ 2786for known existing bugs (FIXME: Is there a section for bug-reporting 2787guidelines somewhere?). 2788 2789Intentionally unsupported GCC extensions 2790---------------------------------------- 2791 2792- clang does not support the gcc extension that allows variable-length 2793 arrays in structures. This is for a few reasons: one, it is tricky to 2794 implement, two, the extension is completely undocumented, and three, 2795 the extension appears to be rarely used. Note that clang *does* 2796 support flexible array members (arrays with a zero or unspecified 2797 size at the end of a structure). 2798- GCC accepts many expression forms that are not valid integer constant 2799 expressions in bit-field widths, enumerator constants, case labels, 2800 and in array bounds at global scope. Clang also accepts additional 2801 expression forms in these contexts, but constructs that GCC accepts due to 2802 simplifications GCC performs while parsing, such as ``x - x`` (where ``x`` is a 2803 variable) will likely never be accepted by Clang. 2804- clang does not support ``__builtin_apply`` and friends; this extension 2805 is extremely obscure and difficult to implement reliably. 2806 2807.. _c_ms: 2808 2809Microsoft extensions 2810-------------------- 2811 2812clang has support for many extensions from Microsoft Visual C++. To enable these 2813extensions, use the ``-fms-extensions`` command-line option. This is the default 2814for Windows targets. Clang does not implement every pragma or declspec provided 2815by MSVC, but the popular ones, such as ``__declspec(dllexport)`` and ``#pragma 2816comment(lib)`` are well supported. 2817 2818clang has a ``-fms-compatibility`` flag that makes clang accept enough 2819invalid C++ to be able to parse most Microsoft headers. For example, it 2820allows `unqualified lookup of dependent base class members 2821<https://clang.llvm.org/compatibility.html#dep_lookup_bases>`_, which is 2822a common compatibility issue with clang. This flag is enabled by default 2823for Windows targets. 2824 2825``-fdelayed-template-parsing`` lets clang delay parsing of function template 2826definitions until the end of a translation unit. This flag is enabled by 2827default for Windows targets. 2828 2829For compatibility with existing code that compiles with MSVC, clang defines the 2830``_MSC_VER`` and ``_MSC_FULL_VER`` macros. These default to the values of 1800 2831and 180000000 respectively, making clang look like an early release of Visual 2832C++ 2013. The ``-fms-compatibility-version=`` flag overrides these values. It 2833accepts a dotted version tuple, such as 19.00.23506. Changing the MSVC 2834compatibility version makes clang behave more like that version of MSVC. For 2835example, ``-fms-compatibility-version=19`` will enable C++14 features and define 2836``char16_t`` and ``char32_t`` as builtin types. 2837 2838.. _cxx: 2839 2840C++ Language Features 2841===================== 2842 2843clang fully implements all of standard C++98 except for exported 2844templates (which were removed in C++11), all of standard C++11, 2845C++14, and C++17, and most of C++20. 2846 2847See the `C++ support in Clang <https://clang.llvm.org/cxx_status.html>` page 2848for detailed information on C++ feature support across Clang versions. 2849 2850Controlling implementation limits 2851--------------------------------- 2852 2853.. option:: -fbracket-depth=N 2854 2855 Sets the limit for nested parentheses, brackets, and braces to N. The 2856 default is 256. 2857 2858.. option:: -fconstexpr-depth=N 2859 2860 Sets the limit for recursive constexpr function invocations to N. The 2861 default is 512. 2862 2863.. option:: -fconstexpr-steps=N 2864 2865 Sets the limit for the number of full-expressions evaluated in a single 2866 constant expression evaluation. The default is 1048576. 2867 2868.. option:: -ftemplate-depth=N 2869 2870 Sets the limit for recursively nested template instantiations to N. The 2871 default is 1024. 2872 2873.. option:: -foperator-arrow-depth=N 2874 2875 Sets the limit for iterative calls to 'operator->' functions to N. The 2876 default is 256. 2877 2878.. _objc: 2879 2880Objective-C Language Features 2881============================= 2882 2883.. _objcxx: 2884 2885Objective-C++ Language Features 2886=============================== 2887 2888.. _openmp: 2889 2890OpenMP Features 2891=============== 2892 2893Clang supports all OpenMP 4.5 directives and clauses. See :doc:`OpenMPSupport` 2894for additional details. 2895 2896Use `-fopenmp` to enable OpenMP. Support for OpenMP can be disabled with 2897`-fno-openmp`. 2898 2899Use `-fopenmp-simd` to enable OpenMP simd features only, without linking 2900the runtime library; for combined constructs 2901(e.g. ``#pragma omp parallel for simd``) the non-simd directives and clauses 2902will be ignored. This can be disabled with `-fno-openmp-simd`. 2903 2904Controlling implementation limits 2905--------------------------------- 2906 2907.. option:: -fopenmp-use-tls 2908 2909 Controls code generation for OpenMP threadprivate variables. In presence of 2910 this option all threadprivate variables are generated the same way as thread 2911 local variables, using TLS support. If `-fno-openmp-use-tls` 2912 is provided or target does not support TLS, code generation for threadprivate 2913 variables relies on OpenMP runtime library. 2914 2915.. _opencl: 2916 2917OpenCL Features 2918=============== 2919 2920Clang can be used to compile OpenCL kernels for execution on a device 2921(e.g. GPU). It is possible to compile the kernel into a binary (e.g. for AMDGPU) 2922that can be uploaded to run directly on a device (e.g. using 2923`clCreateProgramWithBinary 2924<https://www.khronos.org/registry/OpenCL/specs/opencl-1.1.pdf#111>`_) or 2925into generic bitcode files loadable into other toolchains. 2926 2927Compiling to a binary using the default target from the installation can be done 2928as follows: 2929 2930 .. code-block:: console 2931 2932 $ echo "kernel void k(){}" > test.cl 2933 $ clang test.cl 2934 2935Compiling for a specific target can be done by specifying the triple corresponding 2936to the target, for example: 2937 2938 .. code-block:: console 2939 2940 $ clang -target nvptx64-unknown-unknown test.cl 2941 $ clang -target amdgcn-amd-amdhsa -mcpu=gfx900 test.cl 2942 2943Compiling to bitcode can be done as follows: 2944 2945 .. code-block:: console 2946 2947 $ clang -c -emit-llvm test.cl 2948 2949This will produce a file `test.bc` that can be used in vendor toolchains 2950to perform machine code generation. 2951 2952Note that if compiled to bitcode for generic targets such as SPIR, 2953portable IR is produced that can be used with various vendor 2954tools as well as open source tools such as `SPIRV-LLVM Translator 2955<https://github.com/KhronosGroup/SPIRV-LLVM-Translator>`_ 2956to produce SPIR-V binary. More details are provided in `the offline 2957compilation from OpenCL kernel sources into SPIR-V using open source 2958tools 2959<https://github.com/KhronosGroup/OpenCL-Guide/blob/main/chapters/os_tooling.md>`_. 2960 2961Clang currently supports OpenCL C language standards up to v2.0. Clang mainly 2962supports full profile. There is only very limited support of the embedded 2963profile. 2964Starting from clang 9 a C++ mode is available for OpenCL (see 2965:ref:`C++ for OpenCL <cxx_for_opencl>`). 2966 2967There is ongoing support for OpenCL v3.0 that is documented along with other 2968experimental functionality and features in development on :doc:`OpenCLSupport` 2969page. 2970 2971OpenCL Specific Options 2972----------------------- 2973 2974Most of the OpenCL build options from `the specification v2.0 section 5.8.4 2975<https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf#200>`_ are available. 2976 2977Examples: 2978 2979 .. code-block:: console 2980 2981 $ clang -cl-std=CL2.0 -cl-single-precision-constant test.cl 2982 2983 2984Many flags used for the compilation for C sources can also be passed while 2985compiling for OpenCL, examples: ``-c``, ``-O<1-4|s>``, ``-o``, ``-emit-llvm``, etc. 2986 2987Some extra options are available to support special OpenCL features. 2988 2989.. _opencl_cl_no_stdinc: 2990 2991.. option:: -cl-no-stdinc 2992 2993Allows to disable all extra types and functions that are not native to the compiler. 2994This might reduce the compilation speed marginally but many declarations from the 2995OpenCL standard will not be accessible. For example, the following will fail to 2996compile. 2997 2998 .. code-block:: console 2999 3000 $ echo "bool is_wg_uniform(int i){return get_enqueued_local_size(i)==get_local_size(i);}" > test.cl 3001 $ clang -cl-std=CL2.0 -cl-no-stdinc test.cl 3002 error: use of undeclared identifier 'get_enqueued_local_size' 3003 error: use of undeclared identifier 'get_local_size' 3004 3005More information about the standard types and functions is provided in :ref:`the 3006section on the OpenCL Header <opencl_header>`. 3007 3008OpenCL Targets 3009-------------- 3010 3011OpenCL targets are derived from the regular Clang target classes. The OpenCL 3012specific parts of the target representation provide address space mapping as 3013well as a set of supported extensions. 3014 3015Specific Targets 3016^^^^^^^^^^^^^^^^ 3017 3018There is a set of concrete HW architectures that OpenCL can be compiled for. 3019 3020- For AMD target: 3021 3022 .. code-block:: console 3023 3024 $ clang -target amdgcn-amd-amdhsa -mcpu=gfx900 test.cl 3025 3026- For Nvidia architectures: 3027 3028 .. code-block:: console 3029 3030 $ clang -target nvptx64-unknown-unknown test.cl 3031 3032 3033Generic Targets 3034^^^^^^^^^^^^^^^ 3035 3036- SPIR is available as a generic target to allow portable bitcode to be produced 3037 that can be used across GPU toolchains. The implementation follows `the SPIR 3038 specification <https://www.khronos.org/spir>`_. There are two flavors 3039 available for 32 and 64 bits. 3040 3041 .. code-block:: console 3042 3043 $ clang -target spir test.cl -emit-llvm -c 3044 $ clang -target spir64 test.cl -emit-llvm -c 3045 3046 All known OpenCL extensions are supported in the SPIR targets. Clang will 3047 generate SPIR v1.2 compatible IR for OpenCL versions up to 2.0 and SPIR v2.0 3048 for OpenCL v2.0 or C++ for OpenCL. 3049 3050- x86 is used by some implementations that are x86 compatible and currently 3051 remains for backwards compatibility (with older implementations prior to 3052 SPIR target support). For "non-SPMD" targets which cannot spawn multiple 3053 work-items on the fly using hardware, which covers practically all non-GPU 3054 devices such as CPUs and DSPs, additional processing is needed for the kernels 3055 to support multiple work-item execution. For this, a 3rd party toolchain, 3056 such as for example `POCL <http://portablecl.org/>`_, can be used. 3057 3058 This target does not support multiple memory segments and, therefore, the fake 3059 address space map can be added using the :ref:`-ffake-address-space-map 3060 <opencl_fake_address_space_map>` flag. 3061 3062.. _opencl_header: 3063 3064OpenCL Header 3065------------- 3066 3067By default Clang will include standard headers and therefore most of OpenCL 3068builtin functions and types are available during compilation. The 3069default declarations of non-native compiler types and functions can be disabled 3070by using flag :ref:`-cl-no-stdinc <opencl_cl_no_stdinc>`. 3071 3072The following example demonstrates that OpenCL kernel sources with various 3073standard builtin functions can be compiled without the need for an explicit 3074includes or compiler flags. 3075 3076 .. code-block:: console 3077 3078 $ echo "bool is_wg_uniform(int i){return get_enqueued_local_size(i)==get_local_size(i);}" > test.cl 3079 $ clang -cl-std=CL2.0 test.cl 3080 3081More information about the default headers is provided in :doc:`OpenCLSupport`. 3082 3083OpenCL Extensions 3084----------------- 3085 3086Most of the ``cl_khr_*`` extensions to OpenCL C from `the official OpenCL 3087registry <https://www.khronos.org/registry/OpenCL/>`_ are available and 3088configured per target depending on the support available in the specific 3089architecture. 3090 3091It is possible to alter the default extensions setting per target using 3092``-cl-ext`` flag. (See :ref:`flags description <opencl_cl_ext>` for more details). 3093 3094Vendor extensions can be added flexibly by declaring the list of types and 3095functions associated with each extensions enclosed within the following 3096compiler pragma directives: 3097 3098 .. code-block:: c 3099 3100 #pragma OPENCL EXTENSION the_new_extension_name : begin 3101 // declare types and functions associated with the extension here 3102 #pragma OPENCL EXTENSION the_new_extension_name : end 3103 3104For example, parsing the following code adds ``my_t`` type and ``my_func`` 3105function to the custom ``my_ext`` extension. 3106 3107 .. code-block:: c 3108 3109 #pragma OPENCL EXTENSION my_ext : begin 3110 typedef struct{ 3111 int a; 3112 }my_t; 3113 void my_func(my_t); 3114 #pragma OPENCL EXTENSION my_ext : end 3115 3116There is no conflict resolution for identifier clashes among extensions. 3117It is therefore recommended that the identifiers are prefixed with a 3118double underscore to avoid clashing with user space identifiers. Vendor 3119extension should use reserved identifier prefix e.g. amd, arm, intel. 3120 3121Clang also supports language extensions documented in `The OpenCL C Language 3122Extensions Documentation 3123<https://github.com/KhronosGroup/Khronosdotorg/blob/master/api/opencl/assets/OpenCL_LangExt.pdf>`_. 3124 3125OpenCL-Specific Attributes 3126-------------------------- 3127 3128OpenCL support in Clang contains a set of attribute taken directly from the 3129specification as well as additional attributes. 3130 3131See also :doc:`AttributeReference`. 3132 3133nosvm 3134^^^^^ 3135 3136Clang supports this attribute to comply to OpenCL v2.0 conformance, but it 3137does not have any effect on the IR. For more details reffer to the specification 3138`section 6.7.2 3139<https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#49>`_ 3140 3141 3142opencl_unroll_hint 3143^^^^^^^^^^^^^^^^^^ 3144 3145The implementation of this feature mirrors the unroll hint for C. 3146More details on the syntax can be found in the specification 3147`section 6.11.5 3148<https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#61>`_ 3149 3150convergent 3151^^^^^^^^^^ 3152 3153To make sure no invalid optimizations occur for single program multiple data 3154(SPMD) / single instruction multiple thread (SIMT) Clang provides attributes that 3155can be used for special functions that have cross work item semantics. 3156An example is the subgroup operations such as `intel_sub_group_shuffle 3157<https://www.khronos.org/registry/cl/extensions/intel/cl_intel_subgroups.txt>`_ 3158 3159 .. code-block:: c 3160 3161 // Define custom my_sub_group_shuffle(data, c) 3162 // that makes use of intel_sub_group_shuffle 3163 r1 = ... 3164 if (r0) r1 = computeA(); 3165 // Shuffle data from r1 into r3 3166 // of threads id r2. 3167 r3 = my_sub_group_shuffle(r1, r2); 3168 if (r0) r3 = computeB(); 3169 3170with non-SPMD semantics this is optimized to the following equivalent code: 3171 3172 .. code-block:: c 3173 3174 r1 = ... 3175 if (!r0) 3176 // Incorrect functionality! The data in r1 3177 // have not been computed by all threads yet. 3178 r3 = my_sub_group_shuffle(r1, r2); 3179 else { 3180 r1 = computeA(); 3181 r3 = my_sub_group_shuffle(r1, r2); 3182 r3 = computeB(); 3183 } 3184 3185Declaring the function ``my_sub_group_shuffle`` with the convergent attribute 3186would prevent this: 3187 3188 .. code-block:: c 3189 3190 my_sub_group_shuffle() __attribute__((convergent)); 3191 3192Using ``convergent`` guarantees correct execution by keeping CFG equivalence 3193wrt operations marked as ``convergent``. CFG ``G´`` is equivalent to ``G`` wrt 3194node ``Ni`` : ``iff ∀ Nj (i≠j)`` domination and post-domination relations with 3195respect to ``Ni`` remain the same in both ``G`` and ``G´``. 3196 3197noduplicate 3198^^^^^^^^^^^ 3199 3200``noduplicate`` is more restrictive with respect to optimizations than 3201``convergent`` because a convergent function only preserves CFG equivalence. 3202This allows some optimizations to happen as long as the control flow remains 3203unmodified. 3204 3205 .. code-block:: c 3206 3207 for (int i=0; i<4; i++) 3208 my_sub_group_shuffle() 3209 3210can be modified to: 3211 3212 .. code-block:: c 3213 3214 my_sub_group_shuffle(); 3215 my_sub_group_shuffle(); 3216 my_sub_group_shuffle(); 3217 my_sub_group_shuffle(); 3218 3219while using ``noduplicate`` would disallow this. Also ``noduplicate`` doesn't 3220have the same safe semantics of CFG as ``convergent`` and can cause changes in 3221CFG that modify semantics of the original program. 3222 3223``noduplicate`` is kept for backwards compatibility only and it considered to be 3224deprecated for future uses. 3225 3226.. _cxx_for_opencl: 3227 3228C++ for OpenCL 3229-------------- 3230 3231Starting from clang 9 kernel code can contain C++17 features: classes, templates, 3232function overloading, type deduction, etc. Please note that this is not an 3233implementation of `OpenCL C++ 3234<https://www.khronos.org/registry/OpenCL/specs/2.2/pdf/OpenCL_Cxx.pdf>`_ and 3235there is no plan to support it in clang in any new releases in the near future. 3236 3237 3238Clang currently supports C++ for OpenCL v1.0. 3239For detailed information about this language refer to the C++ for OpenCL 3240Programming Language Documentation available 3241in `the latest build 3242<https://www.khronos.org/opencl/assets/CXX_for_OpenCL.html>`_ 3243or in `the official release 3244<https://github.com/KhronosGroup/OpenCL-Docs/releases/tag/cxxforopencl-v1.0-r2>`_. 3245 3246To enable the C++ for OpenCL mode, pass one of following command line options when 3247compiling ``.cl`` file ``-cl-std=clc++``, ``-cl-std=CLC++``, ``-std=clc++`` or 3248``-std=CLC++``. 3249 3250 .. code-block:: c++ 3251 3252 template<class T> T add( T x, T y ) 3253 { 3254 return x + y; 3255 } 3256 3257 __kernel void test( __global float* a, __global float* b) 3258 { 3259 auto index = get_global_id(0); 3260 a[index] = add(b[index], b[index+1]); 3261 } 3262 3263 3264 .. code-block:: console 3265 3266 clang -cl-std=clc++ test.cl 3267 3268Alternatively, files with ``.clcpp`` extension are compiled with the C++ for OpenCL 3269mode. 3270 3271 .. code-block:: console 3272 3273 clang test.clcpp 3274 3275C++ for OpenCL kernel sources can also be compiled online in drivers supporting 3276`cl_ext_cxx_for_opencl 3277<https://www.khronos.org/registry/OpenCL/extensions/ext/cl_ext_cxx_for_opencl.html>`_ 3278extension. 3279 3280Constructing and destroying global objects 3281^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3282 3283Global objects with non-trivial constructors require the constructors to be run 3284before the first kernel using the global objects is executed. Similarly global 3285objects with non-trivial destructors require destructor invocation just after 3286the last kernel using the program objects is executed. 3287In OpenCL versions earlier than v2.2 there is no support for invoking global 3288constructors. However, an easy workaround is to manually enqueue the 3289constructor initialization kernel that has the following name scheme 3290``_GLOBAL__sub_I_<compiled file name>``. 3291This kernel is only present if there are global objects with non-trivial 3292constructors present in the compiled binary. One way to check this is by 3293passing ``CL_PROGRAM_KERNEL_NAMES`` to ``clGetProgramInfo`` (OpenCL v2.0 3294s5.8.7) and then checking whether any kernel name matches the naming scheme of 3295global constructor initialization kernel above. 3296 3297Note that if multiple files are compiled and linked into libraries, multiple 3298kernels that initialize global objects for multiple modules would have to be 3299invoked. 3300 3301Applications are currently required to run initialization of global objects 3302manually before running any kernels in which the objects are used. 3303 3304 .. code-block:: console 3305 3306 clang -cl-std=clc++ test.cl 3307 3308If there are any global objects to be initialized, the final binary will 3309contain the ``_GLOBAL__sub_I_test.cl`` kernel to be enqueued. 3310 3311Note that the manual workaround only applies to objects declared at the 3312program scope. There is no manual workaround for the construction of static 3313objects with non-trivial constructors inside functions. 3314 3315Global destructors can not be invoked manually in the OpenCL v2.0 drivers. 3316However, all memory used for program scope objects should be released on 3317``clReleaseProgram``. 3318 3319Libraries 3320^^^^^^^^^ 3321Limited experimental support of C++ standard libraries for OpenCL is 3322described in :doc:`OpenCLSupport` page. 3323 3324.. _target_features: 3325 3326Target-Specific Features and Limitations 3327======================================== 3328 3329CPU Architectures Features and Limitations 3330------------------------------------------ 3331 3332X86 3333^^^ 3334 3335The support for X86 (both 32-bit and 64-bit) is considered stable on 3336Darwin (macOS), Linux, FreeBSD, and Dragonfly BSD: it has been tested 3337to correctly compile many large C, C++, Objective-C, and Objective-C++ 3338codebases. 3339 3340On ``x86_64-mingw32``, passing i128(by value) is incompatible with the 3341Microsoft x64 calling convention. You might need to tweak 3342``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp. 3343 3344For the X86 target, clang supports the `-m16` command line 3345argument which enables 16-bit code output. This is broadly similar to 3346using ``asm(".code16gcc")`` with the GNU toolchain. The generated code 3347and the ABI remains 32-bit but the assembler emits instructions 3348appropriate for a CPU running in 16-bit mode, with address-size and 3349operand-size prefixes to enable 32-bit addressing and operations. 3350 3351Several micro-architecture levels as specified by the x86-64 psABI are defined. 3352They are cumulative in the sense that features from previous levels are 3353implicitly included in later levels. 3354 3355- ``-march=x86-64``: CMOV, CMPXCHG8B, FPU, FXSR, MMX, FXSR, SCE, SSE, SSE2 3356- ``-march=x86-64-v2``: (close to Nehalem) CMPXCHG16B, LAHF-SAHF, POPCNT, SSE3, SSE4.1, SSE4.2, SSSE3 3357- ``-march=x86-64-v3``: (close to Haswell) AVX, AVX2, BMI1, BMI2, F16C, FMA, LZCNT, MOVBE, XSAVE 3358- ``-march=x86-64-v4``: AVX512F, AVX512BW, AVX512CD, AVX512DQ, AVX512VL 3359 3360ARM 3361^^^ 3362 3363The support for ARM (specifically ARMv6 and ARMv7) is considered stable 3364on Darwin (iOS): it has been tested to correctly compile many large C, 3365C++, Objective-C, and Objective-C++ codebases. Clang only supports a 3366limited number of ARM architectures. It does not yet fully support 3367ARMv5, for example. 3368 3369PowerPC 3370^^^^^^^ 3371 3372The support for PowerPC (especially PowerPC64) is considered stable 3373on Linux and FreeBSD: it has been tested to correctly compile many 3374large C and C++ codebases. PowerPC (32bit) is still missing certain 3375features (e.g. PIC code on ELF platforms). 3376 3377Other platforms 3378^^^^^^^^^^^^^^^ 3379 3380clang currently contains some support for other architectures (e.g. Sparc); 3381however, significant pieces of code generation are still missing, and they 3382haven't undergone significant testing. 3383 3384clang contains limited support for the MSP430 embedded processor, but 3385both the clang support and the LLVM backend support are highly 3386experimental. 3387 3388Other platforms are completely unsupported at the moment. Adding the 3389minimal support needed for parsing and semantic analysis on a new 3390platform is quite easy; see ``lib/Basic/Targets.cpp`` in the clang source 3391tree. This level of support is also sufficient for conversion to LLVM IR 3392for simple programs. Proper support for conversion to LLVM IR requires 3393adding code to ``lib/CodeGen/CGCall.cpp`` at the moment; this is likely to 3394change soon, though. Generating assembly requires a suitable LLVM 3395backend. 3396 3397Operating System Features and Limitations 3398----------------------------------------- 3399 3400Windows 3401^^^^^^^ 3402 3403Clang has experimental support for targeting "Cygming" (Cygwin / MinGW) 3404platforms. 3405 3406See also :ref:`Microsoft Extensions <c_ms>`. 3407 3408Cygwin 3409"""""" 3410 3411Clang works on Cygwin-1.7. 3412 3413MinGW32 3414""""""" 3415 3416Clang works on some mingw32 distributions. Clang assumes directories as 3417below; 3418 3419- ``C:/mingw/include`` 3420- ``C:/mingw/lib`` 3421- ``C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++`` 3422 3423On MSYS, a few tests might fail. 3424 3425MinGW-w64 3426""""""""" 3427 3428For 32-bit (i686-w64-mingw32), and 64-bit (x86\_64-w64-mingw32), Clang 3429assumes as below; 3430 3431- ``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)`` 3432- ``some_directory/bin/gcc.exe`` 3433- ``some_directory/bin/clang.exe`` 3434- ``some_directory/bin/clang++.exe`` 3435- ``some_directory/bin/../include/c++/GCC_version`` 3436- ``some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32`` 3437- ``some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32`` 3438- ``some_directory/bin/../include/c++/GCC_version/backward`` 3439- ``some_directory/bin/../x86_64-w64-mingw32/include`` 3440- ``some_directory/bin/../i686-w64-mingw32/include`` 3441- ``some_directory/bin/../include`` 3442 3443This directory layout is standard for any toolchain you will find on the 3444official `MinGW-w64 website <http://mingw-w64.sourceforge.net>`_. 3445 3446Clang expects the GCC executable "gcc.exe" compiled for 3447``i686-w64-mingw32`` (or ``x86_64-w64-mingw32``) to be present on PATH. 3448 3449`Some tests might fail <https://bugs.llvm.org/show_bug.cgi?id=9072>`_ on 3450``x86_64-w64-mingw32``. 3451 3452.. _clang-cl: 3453 3454clang-cl 3455======== 3456 3457clang-cl is an alternative command-line interface to Clang, designed for 3458compatibility with the Visual C++ compiler, cl.exe. 3459 3460To enable clang-cl to find system headers, libraries, and the linker when run 3461from the command-line, it should be executed inside a Visual Studio Native Tools 3462Command Prompt or a regular Command Prompt where the environment has been set 3463up using e.g. `vcvarsall.bat <https://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_. 3464 3465clang-cl can also be used from inside Visual Studio by selecting the LLVM 3466Platform Toolset. The toolset is not part of the installer, but may be installed 3467separately from the 3468`Visual Studio Marketplace <https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.llvm-toolchain>`_. 3469To use the toolset, select a project in Solution Explorer, open its Property 3470Page (Alt+F7), and in the "General" section of "Configuration Properties" 3471change "Platform Toolset" to LLVM. Doing so enables an additional Property 3472Page for selecting the clang-cl executable to use for builds. 3473 3474To use the toolset with MSBuild directly, invoke it with e.g. 3475``/p:PlatformToolset=LLVM``. This allows trying out the clang-cl toolchain 3476without modifying your project files. 3477 3478It's also possible to point MSBuild at clang-cl without changing toolset by 3479passing ``/p:CLToolPath=c:\llvm\bin /p:CLToolExe=clang-cl.exe``. 3480 3481When using CMake and the Visual Studio generators, the toolset can be set with the ``-T`` flag: 3482 3483 :: 3484 3485 cmake -G"Visual Studio 15 2017" -T LLVM .. 3486 3487When using CMake with the Ninja generator, set the ``CMAKE_C_COMPILER`` and 3488``CMAKE_CXX_COMPILER`` variables to clang-cl: 3489 3490 :: 3491 3492 cmake -GNinja -DCMAKE_C_COMPILER="c:/Program Files (x86)/LLVM/bin/clang-cl.exe" 3493 -DCMAKE_CXX_COMPILER="c:/Program Files (x86)/LLVM/bin/clang-cl.exe" .. 3494 3495 3496Command-Line Options 3497-------------------- 3498 3499To be compatible with cl.exe, clang-cl supports most of the same command-line 3500options. Those options can start with either ``/`` or ``-``. It also supports 3501some of Clang's core options, such as the ``-W`` options. 3502 3503Options that are known to clang-cl, but not currently supported, are ignored 3504with a warning. For example: 3505 3506 :: 3507 3508 clang-cl.exe: warning: argument unused during compilation: '/AI' 3509 3510To suppress warnings about unused arguments, use the ``-Qunused-arguments`` option. 3511 3512Options that are not known to clang-cl will be ignored by default. Use the 3513``-Werror=unknown-argument`` option in order to treat them as errors. If these 3514options are spelled with a leading ``/``, they will be mistaken for a filename: 3515 3516 :: 3517 3518 clang-cl.exe: error: no such file or directory: '/foobar' 3519 3520Please `file a bug <https://bugs.llvm.org/enter_bug.cgi?product=clang&component=Driver>`_ 3521for any valid cl.exe flags that clang-cl does not understand. 3522 3523Execute ``clang-cl /?`` to see a list of supported options: 3524 3525 :: 3526 3527 CL.EXE COMPATIBILITY OPTIONS: 3528 /? Display available options 3529 /arch:<value> Set architecture for code generation 3530 /Brepro- Emit an object file which cannot be reproduced over time 3531 /Brepro Emit an object file which can be reproduced over time 3532 /clang:<arg> Pass <arg> to the clang driver 3533 /C Don't discard comments when preprocessing 3534 /c Compile only 3535 /d1PP Retain macro definitions in /E mode 3536 /d1reportAllClassLayout Dump record layout information 3537 /diagnostics:caret Enable caret and column diagnostics (on by default) 3538 /diagnostics:classic Disable column and caret diagnostics 3539 /diagnostics:column Disable caret diagnostics but keep column info 3540 /D <macro[=value]> Define macro 3541 /EH<value> Exception handling model 3542 /EP Disable linemarker output and preprocess to stdout 3543 /execution-charset:<value> 3544 Runtime encoding, supports only UTF-8 3545 /E Preprocess to stdout 3546 /FA Output assembly code file during compilation 3547 /Fa<file or directory> Output assembly code to this file during compilation (with /FA) 3548 /Fe<file or directory> Set output executable file or directory (ends in / or \) 3549 /FI <value> Include file before parsing 3550 /Fi<file> Set preprocess output file name (with /P) 3551 /Fo<file or directory> Set output object file, or directory (ends in / or \) (with /c) 3552 /fp:except- 3553 /fp:except 3554 /fp:fast 3555 /fp:precise 3556 /fp:strict 3557 /Fp<filename> Set pch filename (with /Yc and /Yu) 3558 /GA Assume thread-local variables are defined in the executable 3559 /Gd Set __cdecl as a default calling convention 3560 /GF- Disable string pooling 3561 /GF Enable string pooling (default) 3562 /GR- Disable emission of RTTI data 3563 /Gregcall Set __regcall as a default calling convention 3564 /GR Enable emission of RTTI data 3565 /Gr Set __fastcall as a default calling convention 3566 /GS- Disable buffer security check 3567 /GS Enable buffer security check (default) 3568 /Gs Use stack probes (default) 3569 /Gs<value> Set stack probe size (default 4096) 3570 /guard:<value> Enable Control Flow Guard with /guard:cf, 3571 or only the table with /guard:cf,nochecks. 3572 Enable EH Continuation Guard with /guard:ehcont 3573 /Gv Set __vectorcall as a default calling convention 3574 /Gw- Don't put each data item in its own section 3575 /Gw Put each data item in its own section 3576 /GX- Disable exception handling 3577 /GX Enable exception handling 3578 /Gy- Don't put each function in its own section (default) 3579 /Gy Put each function in its own section 3580 /Gz Set __stdcall as a default calling convention 3581 /help Display available options 3582 /imsvc <dir> Add directory to system include search path, as if part of %INCLUDE% 3583 /I <dir> Add directory to include search path 3584 /J Make char type unsigned 3585 /LDd Create debug DLL 3586 /LD Create DLL 3587 /link <options> Forward options to the linker 3588 /MDd Use DLL debug run-time 3589 /MD Use DLL run-time 3590 /MTd Use static debug run-time 3591 /MT Use static run-time 3592 /O0 Disable optimization 3593 /O1 Optimize for size (same as /Og /Os /Oy /Ob2 /GF /Gy) 3594 /O2 Optimize for speed (same as /Og /Oi /Ot /Oy /Ob2 /GF /Gy) 3595 /Ob0 Disable function inlining 3596 /Ob1 Only inline functions which are (explicitly or implicitly) marked inline 3597 /Ob2 Inline functions as deemed beneficial by the compiler 3598 /Od Disable optimization 3599 /Og No effect 3600 /Oi- Disable use of builtin functions 3601 /Oi Enable use of builtin functions 3602 /Os Optimize for size 3603 /Ot Optimize for speed 3604 /Ox Deprecated (same as /Og /Oi /Ot /Oy /Ob2); use /O2 instead 3605 /Oy- Disable frame pointer omission (x86 only, default) 3606 /Oy Enable frame pointer omission (x86 only) 3607 /O<flags> Set multiple /O flags at once; e.g. '/O2y-' for '/O2 /Oy-' 3608 /o <file or directory> Set output file or directory (ends in / or \) 3609 /P Preprocess to file 3610 /Qvec- Disable the loop vectorization passes 3611 /Qvec Enable the loop vectorization passes 3612 /showFilenames- Don't print the name of each compiled file (default) 3613 /showFilenames Print the name of each compiled file 3614 /showIncludes Print info about included files to stderr 3615 /source-charset:<value> Source encoding, supports only UTF-8 3616 /std:<value> Language standard to compile for 3617 /TC Treat all source files as C 3618 /Tc <filename> Specify a C source file 3619 /TP Treat all source files as C++ 3620 /Tp <filename> Specify a C++ source file 3621 /utf-8 Set source and runtime encoding to UTF-8 (default) 3622 /U <macro> Undefine macro 3623 /vd<value> Control vtordisp placement 3624 /vmb Use a best-case representation method for member pointers 3625 /vmg Use a most-general representation for member pointers 3626 /vmm Set the default most-general representation to multiple inheritance 3627 /vms Set the default most-general representation to single inheritance 3628 /vmv Set the default most-general representation to virtual inheritance 3629 /volatile:iso Volatile loads and stores have standard semantics 3630 /volatile:ms Volatile loads and stores have acquire and release semantics 3631 /W0 Disable all warnings 3632 /W1 Enable -Wall 3633 /W2 Enable -Wall 3634 /W3 Enable -Wall 3635 /W4 Enable -Wall and -Wextra 3636 /Wall Enable -Weverything 3637 /WX- Do not treat warnings as errors 3638 /WX Treat warnings as errors 3639 /w Disable all warnings 3640 /X Don't add %INCLUDE% to the include search path 3641 /Y- Disable precompiled headers, overrides /Yc and /Yu 3642 /Yc<filename> Generate a pch file for all code up to and including <filename> 3643 /Yu<filename> Load a pch file and use it instead of all code up to and including <filename> 3644 /Z7 Enable CodeView debug information in object files 3645 /Zc:char8_t Enable C++2a char8_t type 3646 /Zc:char8_t- Disable C++2a char8_t type 3647 /Zc:dllexportInlines- Don't dllexport/dllimport inline member functions of dllexport/import classes 3648 /Zc:dllexportInlines dllexport/dllimport inline member functions of dllexport/import classes (default) 3649 /Zc:sizedDealloc- Disable C++14 sized global deallocation functions 3650 /Zc:sizedDealloc Enable C++14 sized global deallocation functions 3651 /Zc:strictStrings Treat string literals as const 3652 /Zc:threadSafeInit- Disable thread-safe initialization of static variables 3653 /Zc:threadSafeInit Enable thread-safe initialization of static variables 3654 /Zc:trigraphs- Disable trigraphs (default) 3655 /Zc:trigraphs Enable trigraphs 3656 /Zc:twoPhase- Disable two-phase name lookup in templates 3657 /Zc:twoPhase Enable two-phase name lookup in templates 3658 /Zd Emit debug line number tables only 3659 /Zi Alias for /Z7. Does not produce PDBs. 3660 /Zl Don't mention any default libraries in the object file 3661 /Zp Set the default maximum struct packing alignment to 1 3662 /Zp<value> Specify the default maximum struct packing alignment 3663 /Zs Syntax-check only 3664 3665 OPTIONS: 3666 -### Print (but do not run) the commands to run for this compilation 3667 --analyze Run the static analyzer 3668 -faddrsig Emit an address-significance table 3669 -fansi-escape-codes Use ANSI escape codes for diagnostics 3670 -fblocks Enable the 'blocks' language feature 3671 -fcf-protection=<value> Instrument control-flow architecture protection. Options: return, branch, full, none. 3672 -fcf-protection Enable cf-protection in 'full' mode 3673 -fcolor-diagnostics Use colors in diagnostics 3674 -fcomplete-member-pointers 3675 Require member pointer base types to be complete if they would be significant under the Microsoft ABI 3676 -fcoverage-mapping Generate coverage mapping to enable code coverage analysis 3677 -fcrash-diagnostics-dir=<dir> 3678 Put crash-report files in <dir> 3679 -fdebug-macro Emit macro debug information 3680 -fdelayed-template-parsing 3681 Parse templated function definitions at the end of the translation unit 3682 -fdiagnostics-absolute-paths 3683 Print absolute paths in diagnostics 3684 -fdiagnostics-parseable-fixits 3685 Print fix-its in machine parseable form 3686 -flto=<value> Set LTO mode to either 'full' or 'thin' 3687 -flto Enable LTO in 'full' mode 3688 -fmerge-all-constants Allow merging of constants 3689 -fms-compatibility-version=<value> 3690 Dot-separated value representing the Microsoft compiler version 3691 number to report in _MSC_VER (0 = don't define it (default)) 3692 -fms-compatibility Enable full Microsoft Visual C++ compatibility 3693 -fms-extensions Accept some non-standard constructs supported by the Microsoft compiler 3694 -fmsc-version=<value> Microsoft compiler version number to report in _MSC_VER 3695 (0 = don't define it (default)) 3696 -fno-addrsig Don't emit an address-significance table 3697 -fno-builtin-<value> Disable implicit builtin knowledge of a specific function 3698 -fno-builtin Disable implicit builtin knowledge of functions 3699 -fno-complete-member-pointers 3700 Do not require member pointer base types to be complete if they would be significant under the Microsoft ABI 3701 -fno-coverage-mapping Disable code coverage analysis 3702 -fno-crash-diagnostics Disable auto-generation of preprocessed source files and a script for reproduction during a clang crash 3703 -fno-debug-macro Do not emit macro debug information 3704 -fno-delayed-template-parsing 3705 Disable delayed template parsing 3706 -fno-sanitize-address-poison-custom-array-cookie 3707 Disable poisoning array cookies when using custom operator new[] in AddressSanitizer 3708 -fno-sanitize-address-use-after-scope 3709 Disable use-after-scope detection in AddressSanitizer 3710 -fno-sanitize-address-use-odr-indicator 3711 Disable ODR indicator globals 3712 -fno-sanitize-ignorelist Don't use ignorelist file for sanitizers 3713 -fno-sanitize-cfi-cross-dso 3714 Disable control flow integrity (CFI) checks for cross-DSO calls. 3715 -fno-sanitize-coverage=<value> 3716 Disable specified features of coverage instrumentation for Sanitizers 3717 -fno-sanitize-memory-track-origins 3718 Disable origins tracking in MemorySanitizer 3719 -fno-sanitize-memory-use-after-dtor 3720 Disable use-after-destroy detection in MemorySanitizer 3721 -fno-sanitize-recover=<value> 3722 Disable recovery for specified sanitizers 3723 -fno-sanitize-stats Disable sanitizer statistics gathering. 3724 -fno-sanitize-thread-atomics 3725 Disable atomic operations instrumentation in ThreadSanitizer 3726 -fno-sanitize-thread-func-entry-exit 3727 Disable function entry/exit instrumentation in ThreadSanitizer 3728 -fno-sanitize-thread-memory-access 3729 Disable memory access instrumentation in ThreadSanitizer 3730 -fno-sanitize-trap=<value> 3731 Disable trapping for specified sanitizers 3732 -fno-standalone-debug Limit debug information produced to reduce size of debug binary 3733 -fobjc-runtime=<value> Specify the target Objective-C runtime kind and version 3734 -fprofile-exclude-files=<value> 3735 Instrument only functions from files where names don't match all the regexes separated by a semi-colon 3736 -fprofile-filter-files=<value> 3737 Instrument only functions from files where names match any regex separated by a semi-colon 3738 -fprofile-instr-generate=<file> 3739 Generate instrumented code to collect execution counts into <file> 3740 (overridden by LLVM_PROFILE_FILE env var) 3741 -fprofile-instr-generate 3742 Generate instrumented code to collect execution counts into default.profraw file 3743 (overridden by '=' form of option or LLVM_PROFILE_FILE env var) 3744 -fprofile-instr-use=<value> 3745 Use instrumentation data for profile-guided optimization 3746 -fprofile-remapping-file=<file> 3747 Use the remappings described in <file> to match the profile data against names in the program 3748 -fprofile-list=<file> 3749 Filename defining the list of functions/files to instrument 3750 -fsanitize-address-field-padding=<value> 3751 Level of field padding for AddressSanitizer 3752 -fsanitize-address-globals-dead-stripping 3753 Enable linker dead stripping of globals in AddressSanitizer 3754 -fsanitize-address-poison-custom-array-cookie 3755 Enable poisoning array cookies when using custom operator new[] in AddressSanitizer 3756 -fsanitize-address-use-after-return=<mode> 3757 Select the mode of detecting stack use-after-return in AddressSanitizer: never | runtime (default) | always 3758 -fsanitize-address-use-after-scope 3759 Enable use-after-scope detection in AddressSanitizer 3760 -fsanitize-address-use-odr-indicator 3761 Enable ODR indicator globals to avoid false ODR violation reports in partially sanitized programs at the cost of an increase in binary size 3762 -fsanitize-ignorelist=<value> 3763 Path to ignorelist file for sanitizers 3764 -fsanitize-cfi-cross-dso 3765 Enable control flow integrity (CFI) checks for cross-DSO calls. 3766 -fsanitize-cfi-icall-generalize-pointers 3767 Generalize pointers in CFI indirect call type signature checks 3768 -fsanitize-coverage=<value> 3769 Specify the type of coverage instrumentation for Sanitizers 3770 -fsanitize-hwaddress-abi=<value> 3771 Select the HWAddressSanitizer ABI to target (interceptor or platform, default interceptor) 3772 -fsanitize-memory-track-origins=<value> 3773 Enable origins tracking in MemorySanitizer 3774 -fsanitize-memory-track-origins 3775 Enable origins tracking in MemorySanitizer 3776 -fsanitize-memory-use-after-dtor 3777 Enable use-after-destroy detection in MemorySanitizer 3778 -fsanitize-recover=<value> 3779 Enable recovery for specified sanitizers 3780 -fsanitize-stats Enable sanitizer statistics gathering. 3781 -fsanitize-thread-atomics 3782 Enable atomic operations instrumentation in ThreadSanitizer (default) 3783 -fsanitize-thread-func-entry-exit 3784 Enable function entry/exit instrumentation in ThreadSanitizer (default) 3785 -fsanitize-thread-memory-access 3786 Enable memory access instrumentation in ThreadSanitizer (default) 3787 -fsanitize-trap=<value> Enable trapping for specified sanitizers 3788 -fsanitize-undefined-strip-path-components=<number> 3789 Strip (or keep only, if negative) a given number of path components when emitting check metadata. 3790 -fsanitize=<check> Turn on runtime checks for various forms of undefined or suspicious 3791 behavior. See user manual for available checks 3792 -fsplit-lto-unit Enables splitting of the LTO unit. 3793 -fstandalone-debug Emit full debug info for all types used by the program 3794 -fwhole-program-vtables Enables whole-program vtable optimization. Requires -flto 3795 -gcodeview-ghash Emit type record hashes in a .debug$H section 3796 -gcodeview Generate CodeView debug information 3797 -gline-directives-only Emit debug line info directives only 3798 -gline-tables-only Emit debug line number tables only 3799 -miamcu Use Intel MCU ABI 3800 -mllvm <value> Additional arguments to forward to LLVM's option processing 3801 -nobuiltininc Disable builtin #include directories 3802 -Qunused-arguments Don't emit warning for unused driver arguments 3803 -R<remark> Enable the specified remark 3804 --target=<value> Generate code for the given target 3805 --version Print version information 3806 -v Show commands to run and use verbose output 3807 -W<warning> Enable the specified warning 3808 -Xclang <arg> Pass <arg> to the clang compiler 3809 3810The /clang: Option 3811^^^^^^^^^^^^^^^^^^ 3812 3813When clang-cl is run with a set of ``/clang:<arg>`` options, it will gather all 3814of the ``<arg>`` arguments and process them as if they were passed to the clang 3815driver. This mechanism allows you to pass flags that are not exposed in the 3816clang-cl options or flags that have a different meaning when passed to the clang 3817driver. Regardless of where they appear in the command line, the ``/clang:`` 3818arguments are treated as if they were passed at the end of the clang-cl command 3819line. 3820 3821The /Zc:dllexportInlines- Option 3822^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3823 3824This causes the class-level `dllexport` and `dllimport` attributes to not apply 3825to inline member functions, as they otherwise would. For example, in the code 3826below `S::foo()` would normally be defined and exported by the DLL, but when 3827using the ``/Zc:dllexportInlines-`` flag it is not: 3828 3829.. code-block:: c 3830 3831 struct __declspec(dllexport) S { 3832 void foo() {} 3833 } 3834 3835This has the benefit that the compiler doesn't need to emit a definition of 3836`S::foo()` in every translation unit where the declaration is included, as it 3837would otherwise do to ensure there's a definition in the DLL even if it's not 3838used there. If the declaration occurs in a header file that's widely used, this 3839can save significant compilation time and output size. It also reduces the 3840number of functions exported by the DLL similarly to what 3841``-fvisibility-inlines-hidden`` does for shared objects on ELF and Mach-O. 3842Since the function declaration comes with an inline definition, users of the 3843library can use that definition directly instead of importing it from the DLL. 3844 3845Note that the Microsoft Visual C++ compiler does not support this option, and 3846if code in a DLL is compiled with ``/Zc:dllexportInlines-``, the code using the 3847DLL must be compiled in the same way so that it doesn't attempt to dllimport 3848the inline member functions. The reverse scenario should generally work though: 3849a DLL compiled without this flag (such as a system library compiled with Visual 3850C++) can be referenced from code compiled using the flag, meaning that the 3851referencing code will use the inline definitions instead of importing them from 3852the DLL. 3853 3854Also note that like when using ``-fvisibility-inlines-hidden``, the address of 3855`S::foo()` will be different inside and outside the DLL, breaking the C/C++ 3856standard requirement that functions have a unique address. 3857 3858The flag does not apply to explicit class template instantiation definitions or 3859declarations, as those are typically used to explicitly provide a single 3860definition in a DLL, (dllexported instantiation definition) or to signal that 3861the definition is available elsewhere (dllimport instantiation declaration). It 3862also doesn't apply to inline members with static local variables, to ensure 3863that the same instance of the variable is used inside and outside the DLL. 3864 3865Using this flag can cause problems when inline functions that would otherwise 3866be dllexported refer to internal symbols of a DLL. For example: 3867 3868.. code-block:: c 3869 3870 void internal(); 3871 3872 struct __declspec(dllimport) S { 3873 void foo() { internal(); } 3874 } 3875 3876Normally, references to `S::foo()` would use the definition in the DLL from 3877which it was exported, and which presumably also has the definition of 3878`internal()`. However, when using ``/Zc:dllexportInlines-``, the inline 3879definition of `S::foo()` is used directly, resulting in a link error since 3880`internal()` is not available. Even worse, if there is an inline definition of 3881`internal()` containing a static local variable, we will now refer to a 3882different instance of that variable than in the DLL: 3883 3884.. code-block:: c 3885 3886 inline int internal() { static int x; return x++; } 3887 3888 struct __declspec(dllimport) S { 3889 int foo() { return internal(); } 3890 } 3891 3892This could lead to very subtle bugs. Using ``-fvisibility-inlines-hidden`` can 3893lead to the same issue. To avoid it in this case, make `S::foo()` or 3894`internal()` non-inline, or mark them `dllimport/dllexport` explicitly. 3895 3896Finding Clang runtime libraries 3897^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3898 3899clang-cl supports several features that require runtime library support: 3900 3901- Address Sanitizer (ASan): ``-fsanitize=address`` 3902- Undefined Behavior Sanitizer (UBSan): ``-fsanitize=undefined`` 3903- Code coverage: ``-fprofile-instr-generate -fcoverage-mapping`` 3904- Profile Guided Optimization (PGO): ``-fprofile-instr-generate`` 3905- Certain math operations (int128 division) require the builtins library 3906 3907In order to use these features, the user must link the right runtime libraries 3908into their program. These libraries are distributed alongside Clang in the 3909library resource directory. Clang searches for the resource directory by 3910searching relative to the Clang executable. For example, if LLVM is installed 3911in ``C:\Program Files\LLVM``, then the profile runtime library will be located 3912at the path 3913``C:\Program Files\LLVM\lib\clang\11.0.0\lib\windows\clang_rt.profile-x86_64.lib``. 3914 3915For UBSan, PGO, and coverage, Clang will emit object files that auto-link the 3916appropriate runtime library, but the user generally needs to help the linker 3917(whether it is ``lld-link.exe`` or MSVC ``link.exe``) find the library resource 3918directory. Using the example installation above, this would mean passing 3919``/LIBPATH:C:\Program Files\LLVM\lib\clang\11.0.0\lib\windows`` to the linker. 3920If the user links the program with the ``clang`` or ``clang-cl`` drivers, the 3921driver will pass this flag for them. 3922 3923If the linker cannot find the appropriate library, it will emit an error like 3924this:: 3925 3926 $ clang-cl -c -fsanitize=undefined t.cpp 3927 3928 $ lld-link t.obj -dll 3929 lld-link: error: could not open 'clang_rt.ubsan_standalone-x86_64.lib': no such file or directory 3930 lld-link: error: could not open 'clang_rt.ubsan_standalone_cxx-x86_64.lib': no such file or directory 3931 3932 $ link t.obj -dll -nologo 3933 LINK : fatal error LNK1104: cannot open file 'clang_rt.ubsan_standalone-x86_64.lib' 3934 3935To fix the error, add the appropriate ``/libpath:`` flag to the link line. 3936 3937For ASan, as of this writing, the user is also responsible for linking against 3938the correct ASan libraries. 3939 3940If the user is using the dynamic CRT (``/MD``), then they should add 3941``clang_rt.asan_dynamic-x86_64.lib`` to the link line as a regular input. For 3942other architectures, replace x86_64 with the appropriate name here and below. 3943 3944If the user is using the static CRT (``/MT``), then different runtimes are used 3945to produce DLLs and EXEs. To link a DLL, pass 3946``clang_rt.asan_dll_thunk-x86_64.lib``. To link an EXE, pass 3947``-wholearchive:clang_rt.asan-x86_64.lib``. 3948