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