1============================ 2Clang Compiler User's Manual 3============================ 4 5.. contents:: 6 :local: 7 8Introduction 9============ 10 11The Clang Compiler is an open-source compiler for the C family of 12programming languages, aiming to be the best in class implementation of 13these languages. Clang builds on the LLVM optimizer and code generator, 14allowing it to provide high-quality optimization and code generation 15support for many targets. For more general information, please see the 16`Clang Web Site <http://clang.llvm.org>`_ or the `LLVM Web 17Site <http://llvm.org>`_. 18 19This document describes important notes about using Clang as a compiler 20for an end-user, documenting the supported features, command line 21options, etc. If you are interested in using Clang to build a tool that 22processes code, please see :doc:`InternalsManual`. If you are interested in the 23`Clang Static Analyzer <http://clang-analyzer.llvm.org>`_, please see its web 24page. 25 26Clang is designed to support the C family of programming languages, 27which includes :ref:`C <c>`, :ref:`Objective-C <objc>`, :ref:`C++ <cxx>`, and 28:ref:`Objective-C++ <objcxx>` as well as many dialects of those. For 29language-specific information, please see the corresponding language 30specific section: 31 32- :ref:`C Language <c>`: K&R C, ANSI C89, ISO C90, ISO C94 (C89+AMD1), ISO 33 C99 (+TC1, TC2, TC3). 34- :ref:`Objective-C Language <objc>`: ObjC 1, ObjC 2, ObjC 2.1, plus 35 variants depending on base language. 36- :ref:`C++ Language <cxx>` 37- :ref:`Objective C++ Language <objcxx>` 38 39In addition to these base languages and their dialects, Clang supports a 40broad variety of language extensions, which are documented in the 41corresponding language section. These extensions are provided to be 42compatible with the GCC, Microsoft, and other popular compilers as well 43as to improve functionality through Clang-specific features. The Clang 44driver and language features are intentionally designed to be as 45compatible with the GNU GCC compiler as reasonably possible, easing 46migration from GCC to Clang. In most cases, code "just works". 47Clang also provides an alternative driver, :ref:`clang-cl`, that is designed 48to be compatible with the Visual C++ compiler, cl.exe. 49 50In addition to language specific features, Clang has a variety of 51features that depend on what CPU architecture or operating system is 52being compiled for. Please see the :ref:`Target-Specific Features and 53Limitations <target_features>` section for more details. 54 55The rest of the introduction introduces some basic :ref:`compiler 56terminology <terminology>` that is used throughout this manual and 57contains a basic :ref:`introduction to using Clang <basicusage>` as a 58command line compiler. 59 60.. _terminology: 61 62Terminology 63----------- 64 65Front end, parser, backend, preprocessor, undefined behavior, 66diagnostic, optimizer 67 68.. _basicusage: 69 70Basic Usage 71----------- 72 73Intro to how to use a C compiler for newbies. 74 75compile + link compile then link debug info enabling optimizations 76picking a language to use, defaults to C11 by default. Autosenses based 77on extension. using a makefile 78 79Command Line Options 80==================== 81 82This section is generally an index into other sections. It does not go 83into depth on the ones that are covered by other sections. However, the 84first part introduces the language selection and other high level 85options like :option:`-c`, :option:`-g`, etc. 86 87Options to Control Error and Warning Messages 88--------------------------------------------- 89 90.. option:: -Werror 91 92 Turn warnings into errors. 93 94.. This is in plain monospaced font because it generates the same label as 95.. -Werror, and Sphinx complains. 96 97``-Werror=foo`` 98 99 Turn warning "foo" into an error. 100 101.. option:: -Wno-error=foo 102 103 Turn warning "foo" into an warning even if :option:`-Werror` is specified. 104 105.. option:: -Wfoo 106 107 Enable warning "foo". 108 109.. option:: -Wno-foo 110 111 Disable warning "foo". 112 113.. option:: -w 114 115 Disable all diagnostics. 116 117.. option:: -Weverything 118 119 :ref:`Enable all diagnostics. <diagnostics_enable_everything>` 120 121.. option:: -pedantic 122 123 Warn on language extensions. 124 125.. option:: -pedantic-errors 126 127 Error on language extensions. 128 129.. option:: -Wsystem-headers 130 131 Enable warnings from system headers. 132 133.. option:: -ferror-limit=123 134 135 Stop emitting diagnostics after 123 errors have been produced. The default is 136 20, and the error limit can be disabled with `-ferror-limit=0`. 137 138.. option:: -ftemplate-backtrace-limit=123 139 140 Only emit up to 123 template instantiation notes within the template 141 instantiation backtrace for a single warning or error. The default is 10, and 142 the limit can be disabled with `-ftemplate-backtrace-limit=0`. 143 144.. _cl_diag_formatting: 145 146Formatting of Diagnostics 147^^^^^^^^^^^^^^^^^^^^^^^^^ 148 149Clang aims to produce beautiful diagnostics by default, particularly for 150new users that first come to Clang. However, different people have 151different preferences, and sometimes Clang is driven not by a human, 152but by a program that wants consistent and easily parsable output. For 153these cases, Clang provides a wide range of options to control the exact 154output format of the diagnostics that it generates. 155 156.. _opt_fshow-column: 157 158**-f[no-]show-column** 159 Print column number in diagnostic. 160 161 This option, which defaults to on, controls whether or not Clang 162 prints the column number of a diagnostic. For example, when this is 163 enabled, Clang will print something like: 164 165 :: 166 167 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] 168 #endif bad 169 ^ 170 // 171 172 When this is disabled, Clang will print "test.c:28: warning..." with 173 no column number. 174 175 The printed column numbers count bytes from the beginning of the 176 line; take care if your source contains multibyte characters. 177 178.. _opt_fshow-source-location: 179 180**-f[no-]show-source-location** 181 Print source file/line/column information in diagnostic. 182 183 This option, which defaults to on, controls whether or not Clang 184 prints the filename, line number and column number of a diagnostic. 185 For example, when this is enabled, Clang will print something like: 186 187 :: 188 189 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] 190 #endif bad 191 ^ 192 // 193 194 When this is disabled, Clang will not print the "test.c:28:8: " 195 part. 196 197.. _opt_fcaret-diagnostics: 198 199**-f[no-]caret-diagnostics** 200 Print source line and ranges from source code in diagnostic. 201 This option, which defaults to on, controls whether or not Clang 202 prints the source line, source ranges, and caret when emitting a 203 diagnostic. For example, when this is enabled, Clang will print 204 something like: 205 206 :: 207 208 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] 209 #endif bad 210 ^ 211 // 212 213**-f[no-]color-diagnostics** 214 This option, which defaults to on when a color-capable terminal is 215 detected, controls whether or not Clang prints diagnostics in color. 216 217 When this option is enabled, Clang will use colors to highlight 218 specific parts of the diagnostic, e.g., 219 220 .. nasty hack to not lose our dignity 221 222 .. raw:: html 223 224 <pre> 225 <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> 226 #endif bad 227 <span style="color:green">^</span> 228 <span style="color:green">//</span> 229 </pre> 230 231 When this is disabled, Clang will just print: 232 233 :: 234 235 test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] 236 #endif bad 237 ^ 238 // 239 240**-fansi-escape-codes** 241 Controls whether ANSI escape codes are used instead of the Windows Console 242 API to output colored diagnostics. This option is only used on Windows and 243 defaults to off. 244 245.. option:: -fdiagnostics-format=clang/msvc/vi 246 247 Changes diagnostic output format to better match IDEs and command line tools. 248 249 This option controls the output format of the filename, line number, 250 and column printed in diagnostic messages. The options, and their 251 affect on formatting a simple conversion diagnostic, follow: 252 253 **clang** (default) 254 :: 255 256 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' 257 258 **msvc** 259 :: 260 261 t.c(3,11) : warning: conversion specifies type 'char *' but the argument has type 'int' 262 263 **vi** 264 :: 265 266 t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int' 267 268.. _opt_fdiagnostics-show-option: 269 270**-f[no-]diagnostics-show-option** 271 Enable ``[-Woption]`` information in diagnostic line. 272 273 This option, which defaults to on, controls whether or not Clang 274 prints the associated :ref:`warning group <cl_diag_warning_groups>` 275 option name when outputting a warning diagnostic. For example, in 276 this output: 277 278 :: 279 280 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] 281 #endif bad 282 ^ 283 // 284 285 Passing **-fno-diagnostics-show-option** will prevent Clang from 286 printing the [:ref:`-Wextra-tokens <opt_Wextra-tokens>`] information in 287 the diagnostic. This information tells you the flag needed to enable 288 or disable the diagnostic, either from the command line or through 289 :ref:`#pragma GCC diagnostic <pragma_GCC_diagnostic>`. 290 291.. _opt_fdiagnostics-show-category: 292 293.. option:: -fdiagnostics-show-category=none/id/name 294 295 Enable printing category information in diagnostic line. 296 297 This option, which defaults to "none", controls whether or not Clang 298 prints the category associated with a diagnostic when emitting it. 299 Each diagnostic may or many not have an associated category, if it 300 has one, it is listed in the diagnostic categorization field of the 301 diagnostic line (in the []'s). 302 303 For example, a format string warning will produce these three 304 renditions based on the setting of this option: 305 306 :: 307 308 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat] 309 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1] 310 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String] 311 312 This category can be used by clients that want to group diagnostics 313 by category, so it should be a high level category. We want dozens 314 of these, not hundreds or thousands of them. 315 316.. _opt_fdiagnostics-fixit-info: 317 318**-f[no-]diagnostics-fixit-info** 319 Enable "FixIt" information in the diagnostics output. 320 321 This option, which defaults to on, controls whether or not Clang 322 prints the information on how to fix a specific diagnostic 323 underneath it when it knows. For example, in this output: 324 325 :: 326 327 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] 328 #endif bad 329 ^ 330 // 331 332 Passing **-fno-diagnostics-fixit-info** will prevent Clang from 333 printing the "//" line at the end of the message. This information 334 is useful for users who may not understand what is wrong, but can be 335 confusing for machine parsing. 336 337.. _opt_fdiagnostics-print-source-range-info: 338 339**-fdiagnostics-print-source-range-info** 340 Print machine parsable information about source ranges. 341 This option makes Clang print information about source ranges in a machine 342 parsable format after the file/line/column number information. The 343 information is a simple sequence of brace enclosed ranges, where each range 344 lists the start and end line/column locations. For example, in this output: 345 346 :: 347 348 exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float') 349 P = (P-42) + Gamma*4; 350 ~~~~~~ ^ ~~~~~~~ 351 352 The {}'s are generated by -fdiagnostics-print-source-range-info. 353 354 The printed column numbers count bytes from the beginning of the 355 line; take care if your source contains multibyte characters. 356 357.. option:: -fdiagnostics-parseable-fixits 358 359 Print Fix-Its in a machine parseable form. 360 361 This option makes Clang print available Fix-Its in a machine 362 parseable format at the end of diagnostics. The following example 363 illustrates the format: 364 365 :: 366 367 fix-it:"t.cpp":{7:25-7:29}:"Gamma" 368 369 The range printed is a half-open range, so in this example the 370 characters at column 25 up to but not including column 29 on line 7 371 in t.cpp should be replaced with the string "Gamma". Either the 372 range or the replacement string may be empty (representing strict 373 insertions and strict erasures, respectively). Both the file name 374 and the insertion string escape backslash (as "\\\\"), tabs (as 375 "\\t"), newlines (as "\\n"), double quotes(as "\\"") and 376 non-printable characters (as octal "\\xxx"). 377 378 The printed column numbers count bytes from the beginning of the 379 line; take care if your source contains multibyte characters. 380 381.. option:: -fno-elide-type 382 383 Turns off elision in template type printing. 384 385 The default for template type printing is to elide as many template 386 arguments as possible, removing those which are the same in both 387 template types, leaving only the differences. Adding this flag will 388 print all the template arguments. If supported by the terminal, 389 highlighting will still appear on differing arguments. 390 391 Default: 392 393 :: 394 395 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; 396 397 -fno-elide-type: 398 399 :: 400 401 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; 402 403.. option:: -fdiagnostics-show-template-tree 404 405 Template type diffing prints a text tree. 406 407 For diffing large templated types, this option will cause Clang to 408 display the templates as an indented text tree, one argument per 409 line, with differences marked inline. This is compatible with 410 -fno-elide-type. 411 412 Default: 413 414 :: 415 416 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; 417 418 With :option:`-fdiagnostics-show-template-tree`: 419 420 :: 421 422 t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument; 423 vector< 424 map< 425 [...], 426 map< 427 [float != double], 428 [...]>>> 429 430.. _cl_diag_warning_groups: 431 432Individual Warning Groups 433^^^^^^^^^^^^^^^^^^^^^^^^^ 434 435TODO: Generate this from tblgen. Define one anchor per warning group. 436 437.. _opt_wextra-tokens: 438 439.. option:: -Wextra-tokens 440 441 Warn about excess tokens at the end of a preprocessor directive. 442 443 This option, which defaults to on, enables warnings about extra 444 tokens at the end of preprocessor directives. For example: 445 446 :: 447 448 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] 449 #endif bad 450 ^ 451 452 These extra tokens are not strictly conforming, and are usually best 453 handled by commenting them out. 454 455.. option:: -Wambiguous-member-template 456 457 Warn about unqualified uses of a member template whose name resolves to 458 another template at the location of the use. 459 460 This option, which defaults to on, enables a warning in the 461 following code: 462 463 :: 464 465 template<typename T> struct set{}; 466 template<typename T> struct trait { typedef const T& type; }; 467 struct Value { 468 template<typename T> void set(typename trait<T>::type value) {} 469 }; 470 void foo() { 471 Value v; 472 v.set<double>(3.2); 473 } 474 475 C++ [basic.lookup.classref] requires this to be an error, but, 476 because it's hard to work around, Clang downgrades it to a warning 477 as an extension. 478 479.. option:: -Wbind-to-temporary-copy 480 481 Warn about an unusable copy constructor when binding a reference to a 482 temporary. 483 484 This option enables warnings about binding a 485 reference to a temporary when the temporary doesn't have a usable 486 copy constructor. For example: 487 488 :: 489 490 struct NonCopyable { 491 NonCopyable(); 492 private: 493 NonCopyable(const NonCopyable&); 494 }; 495 void foo(const NonCopyable&); 496 void bar() { 497 foo(NonCopyable()); // Disallowed in C++98; allowed in C++11. 498 } 499 500 :: 501 502 struct NonCopyable2 { 503 NonCopyable2(); 504 NonCopyable2(NonCopyable2&); 505 }; 506 void foo(const NonCopyable2&); 507 void bar() { 508 foo(NonCopyable2()); // Disallowed in C++98; allowed in C++11. 509 } 510 511 Note that if ``NonCopyable2::NonCopyable2()`` has a default argument 512 whose instantiation produces a compile error, that error will still 513 be a hard error in C++98 mode even if this warning is turned off. 514 515Options to Control Clang Crash Diagnostics 516------------------------------------------ 517 518As unbelievable as it may sound, Clang does crash from time to time. 519Generally, this only occurs to those living on the `bleeding 520edge <http://llvm.org/releases/download.html#svn>`_. Clang goes to great 521lengths to assist you in filing a bug report. Specifically, Clang 522generates preprocessed source file(s) and associated run script(s) upon 523a crash. These files should be attached to a bug report to ease 524reproducibility of the failure. Below are the command line options to 525control the crash diagnostics. 526 527.. option:: -fno-crash-diagnostics 528 529 Disable auto-generation of preprocessed source files during a clang crash. 530 531The -fno-crash-diagnostics flag can be helpful for speeding the process 532of generating a delta reduced test case. 533 534Options to Emit Optimization Reports 535------------------------------------ 536 537Optimization reports trace, at a high-level, all the major decisions 538done by compiler transformations. For instance, when the inliner 539decides to inline function ``foo()`` into ``bar()``, or the loop unroller 540decides to unroll a loop N times, or the vectorizer decides to 541vectorize a loop body. 542 543Clang offers a family of flags which the optimizers can use to emit 544a diagnostic in three cases: 545 5461. When the pass makes a transformation (:option:`-Rpass`). 547 5482. When the pass fails to make a transformation (:option:`-Rpass-missed`). 549 5503. When the pass determines whether or not to make a transformation 551 (:option:`-Rpass-analysis`). 552 553NOTE: Although the discussion below focuses on :option:`-Rpass`, the exact 554same options apply to :option:`-Rpass-missed` and :option:`-Rpass-analysis`. 555 556Since there are dozens of passes inside the compiler, each of these flags 557take a regular expression that identifies the name of the pass which should 558emit the associated diagnostic. For example, to get a report from the inliner, 559compile the code with: 560 561.. code-block:: console 562 563 $ clang -O2 -Rpass=inline code.cc -o code 564 code.cc:4:25: remark: foo inlined into bar [-Rpass=inline] 565 int bar(int j) { return foo(j, j - 2); } 566 ^ 567 568Note that remarks from the inliner are identified with `[-Rpass=inline]`. 569To request a report from every optimization pass, you should use 570:option:`-Rpass=.*` (in fact, you can use any valid POSIX regular 571expression). However, do not expect a report from every transformation 572made by the compiler. Optimization remarks do not really make sense 573outside of the major transformations (e.g., inlining, vectorization, 574loop optimizations) and not every optimization pass supports this 575feature. 576 577Current limitations 578^^^^^^^^^^^^^^^^^^^ 579 5801. Optimization remarks that refer to function names will display the 581 mangled name of the function. Since these remarks are emitted by the 582 back end of the compiler, it does not know anything about the input 583 language, nor its mangling rules. 584 5852. Some source locations are not displayed correctly. The front end has 586 a more detailed source location tracking than the locations included 587 in the debug info (e.g., the front end can locate code inside macro 588 expansions). However, the locations used by :option:`-Rpass` are 589 translated from debug annotations. That translation can be lossy, 590 which results in some remarks having no location information. 591 592Other Options 593------------- 594Clang options that that don't fit neatly into other categories. 595 596.. option:: -MV 597 598 When emitting a dependency file, use formatting conventions appropriate 599 for NMake or Jom. Ignored unless another option causes Clang to emit a 600 dependency file. 601 602When Clang emits a dependency file (e.g., you supplied the -M option) 603most filenames can be written to the file without any special formatting. 604Different Make tools will treat different sets of characters as "special" 605and use different conventions for telling the Make tool that the character 606is actually part of the filename. Normally Clang uses backslash to "escape" 607a special character, which is the convention used by GNU Make. The -MV 608option tells Clang to put double-quotes around the entire filename, which 609is the convention used by NMake and Jom. 610 611 612Language and Target-Independent Features 613======================================== 614 615Controlling Errors and Warnings 616------------------------------- 617 618Clang provides a number of ways to control which code constructs cause 619it to emit errors and warning messages, and how they are displayed to 620the console. 621 622Controlling How Clang Displays Diagnostics 623^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 624 625When Clang emits a diagnostic, it includes rich information in the 626output, and gives you fine-grain control over which information is 627printed. Clang has the ability to print this information, and these are 628the options that control it: 629 630#. A file/line/column indicator that shows exactly where the diagnostic 631 occurs in your code [:ref:`-fshow-column <opt_fshow-column>`, 632 :ref:`-fshow-source-location <opt_fshow-source-location>`]. 633#. A categorization of the diagnostic as a note, warning, error, or 634 fatal error. 635#. A text string that describes what the problem is. 636#. An option that indicates how to control the diagnostic (for 637 diagnostics that support it) 638 [:ref:`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`]. 639#. A :ref:`high-level category <diagnostics_categories>` for the diagnostic 640 for clients that want to group diagnostics by class (for diagnostics 641 that support it) 642 [:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>`]. 643#. The line of source code that the issue occurs on, along with a caret 644 and ranges that indicate the important locations 645 [:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`]. 646#. "FixIt" information, which is a concise explanation of how to fix the 647 problem (when Clang is certain it knows) 648 [:ref:`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`]. 649#. A machine-parsable representation of the ranges involved (off by 650 default) 651 [:ref:`-fdiagnostics-print-source-range-info <opt_fdiagnostics-print-source-range-info>`]. 652 653For more information please see :ref:`Formatting of 654Diagnostics <cl_diag_formatting>`. 655 656Diagnostic Mappings 657^^^^^^^^^^^^^^^^^^^ 658 659All diagnostics are mapped into one of these 6 classes: 660 661- Ignored 662- Note 663- Remark 664- Warning 665- Error 666- Fatal 667 668.. _diagnostics_categories: 669 670Diagnostic Categories 671^^^^^^^^^^^^^^^^^^^^^ 672 673Though not shown by default, diagnostics may each be associated with a 674high-level category. This category is intended to make it possible to 675triage builds that produce a large number of errors or warnings in a 676grouped way. 677 678Categories are not shown by default, but they can be turned on with the 679:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>` option. 680When set to "``name``", the category is printed textually in the 681diagnostic output. When it is set to "``id``", a category number is 682printed. The mapping of category names to category id's can be obtained 683by running '``clang --print-diagnostic-categories``'. 684 685Controlling Diagnostics via Command Line Flags 686^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 687 688TODO: -W flags, -pedantic, etc 689 690.. _pragma_gcc_diagnostic: 691 692Controlling Diagnostics via Pragmas 693^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 694 695Clang can also control what diagnostics are enabled through the use of 696pragmas in the source code. This is useful for turning off specific 697warnings in a section of source code. Clang supports GCC's pragma for 698compatibility with existing source code, as well as several extensions. 699 700The pragma may control any warning that can be used from the command 701line. Warnings may be set to ignored, warning, error, or fatal. The 702following example code will tell Clang or GCC to ignore the -Wall 703warnings: 704 705.. code-block:: c 706 707 #pragma GCC diagnostic ignored "-Wall" 708 709In addition to all of the functionality provided by GCC's pragma, Clang 710also allows you to push and pop the current warning state. This is 711particularly useful when writing a header file that will be compiled by 712other people, because you don't know what warning flags they build with. 713 714In the below example :option:`-Wextra-tokens` is ignored for only a single line 715of code, after which the diagnostics return to whatever state had previously 716existed. 717 718.. code-block:: c 719 720 #if foo 721 #endif foo // warning: extra tokens at end of #endif directive 722 723 #pragma clang diagnostic ignored "-Wextra-tokens" 724 725 #if foo 726 #endif foo // no warning 727 728 #pragma clang diagnostic pop 729 730The push and pop pragmas will save and restore the full diagnostic state 731of the compiler, regardless of how it was set. That means that it is 732possible to use push and pop around GCC compatible diagnostics and Clang 733will push and pop them appropriately, while GCC will ignore the pushes 734and pops as unknown pragmas. It should be noted that while Clang 735supports the GCC pragma, Clang and GCC do not support the exact same set 736of warnings, so even when using GCC compatible #pragmas there is no 737guarantee that they will have identical behaviour on both compilers. 738 739In addition to controlling warnings and errors generated by the compiler, it is 740possible to generate custom warning and error messages through the following 741pragmas: 742 743.. code-block:: c 744 745 // The following will produce warning messages 746 #pragma message "some diagnostic message" 747 #pragma GCC warning "TODO: replace deprecated feature" 748 749 // The following will produce an error message 750 #pragma GCC error "Not supported" 751 752These pragmas operate similarly to the ``#warning`` and ``#error`` preprocessor 753directives, except that they may also be embedded into preprocessor macros via 754the C99 ``_Pragma`` operator, for example: 755 756.. code-block:: c 757 758 #define STR(X) #X 759 #define DEFER(M,...) M(__VA_ARGS__) 760 #define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__)))) 761 762 CUSTOM_ERROR("Feature not available"); 763 764Controlling Diagnostics in System Headers 765^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 766 767Warnings are suppressed when they occur in system headers. By default, 768an included file is treated as a system header if it is found in an 769include path specified by ``-isystem``, but this can be overridden in 770several ways. 771 772The ``system_header`` pragma can be used to mark the current file as 773being a system header. No warnings will be produced from the location of 774the pragma onwards within the same file. 775 776.. code-block:: c 777 778 #if foo 779 #endif foo // warning: extra tokens at end of #endif directive 780 781 #pragma clang system_header 782 783 #if foo 784 #endif foo // no warning 785 786The :option:`--system-header-prefix=` and :option:`--no-system-header-prefix=` 787command-line arguments can be used to override whether subsets of an include 788path are treated as system headers. When the name in a ``#include`` directive 789is found within a header search path and starts with a system prefix, the 790header is treated as a system header. The last prefix on the 791command-line which matches the specified header name takes precedence. 792For instance: 793 794.. code-block:: console 795 796 $ clang -Ifoo -isystem bar --system-header-prefix=x/ \ 797 --no-system-header-prefix=x/y/ 798 799Here, ``#include "x/a.h"`` is treated as including a system header, even 800if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated 801as not including a system header, even if the header is found in 802``bar``. 803 804A ``#include`` directive which finds a file relative to the current 805directory is treated as including a system header if the including file 806is treated as a system header. 807 808.. _diagnostics_enable_everything: 809 810Enabling All Diagnostics 811^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 812 813In addition to the traditional ``-W`` flags, one can enable **all** 814diagnostics by passing :option:`-Weverything`. This works as expected 815with 816:option:`-Werror`, and also includes the warnings from :option:`-pedantic`. 817 818Note that when combined with :option:`-w` (which disables all warnings), that 819flag wins. 820 821Controlling Static Analyzer Diagnostics 822^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 823 824While not strictly part of the compiler, the diagnostics from Clang's 825`static analyzer <http://clang-analyzer.llvm.org>`_ can also be 826influenced by the user via changes to the source code. See the available 827`annotations <http://clang-analyzer.llvm.org/annotations.html>`_ and the 828analyzer's `FAQ 829page <http://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more 830information. 831 832.. _usersmanual-precompiled-headers: 833 834Precompiled Headers 835------------------- 836 837`Precompiled headers <http://en.wikipedia.org/wiki/Precompiled_header>`__ 838are a general approach employed by many compilers to reduce compilation 839time. The underlying motivation of the approach is that it is common for 840the same (and often large) header files to be included by multiple 841source files. Consequently, compile times can often be greatly improved 842by caching some of the (redundant) work done by a compiler to process 843headers. Precompiled header files, which represent one of many ways to 844implement this optimization, are literally files that represent an 845on-disk cache that contains the vital information necessary to reduce 846some of the work needed to process a corresponding header file. While 847details of precompiled headers vary between compilers, precompiled 848headers have been shown to be highly effective at speeding up program 849compilation on systems with very large system headers (e.g., Mac OS X). 850 851Generating a PCH File 852^^^^^^^^^^^^^^^^^^^^^ 853 854To generate a PCH file using Clang, one invokes Clang with the 855:option:`-x <language>-header` option. This mirrors the interface in GCC 856for generating PCH files: 857 858.. code-block:: console 859 860 $ gcc -x c-header test.h -o test.h.gch 861 $ clang -x c-header test.h -o test.h.pch 862 863Using a PCH File 864^^^^^^^^^^^^^^^^ 865 866A PCH file can then be used as a prefix header when a :option:`-include` 867option is passed to ``clang``: 868 869.. code-block:: console 870 871 $ clang -include test.h test.c -o test 872 873The ``clang`` driver will first check if a PCH file for ``test.h`` is 874available; if so, the contents of ``test.h`` (and the files it includes) 875will be processed from the PCH file. Otherwise, Clang falls back to 876directly processing the content of ``test.h``. This mirrors the behavior 877of GCC. 878 879.. note:: 880 881 Clang does *not* automatically use PCH files for headers that are directly 882 included within a source file. For example: 883 884 .. code-block:: console 885 886 $ clang -x c-header test.h -o test.h.pch 887 $ cat test.c 888 #include "test.h" 889 $ clang test.c -o test 890 891 In this example, ``clang`` will not automatically use the PCH file for 892 ``test.h`` since ``test.h`` was included directly in the source file and not 893 specified on the command line using :option:`-include`. 894 895Relocatable PCH Files 896^^^^^^^^^^^^^^^^^^^^^ 897 898It is sometimes necessary to build a precompiled header from headers 899that are not yet in their final, installed locations. For example, one 900might build a precompiled header within the build tree that is then 901meant to be installed alongside the headers. Clang permits the creation 902of "relocatable" precompiled headers, which are built with a given path 903(into the build directory) and can later be used from an installed 904location. 905 906To build a relocatable precompiled header, place your headers into a 907subdirectory whose structure mimics the installed location. For example, 908if you want to build a precompiled header for the header ``mylib.h`` 909that will be installed into ``/usr/include``, create a subdirectory 910``build/usr/include`` and place the header ``mylib.h`` into that 911subdirectory. If ``mylib.h`` depends on other headers, then they can be 912stored within ``build/usr/include`` in a way that mimics the installed 913location. 914 915Building a relocatable precompiled header requires two additional 916arguments. First, pass the ``--relocatable-pch`` flag to indicate that 917the resulting PCH file should be relocatable. Second, pass 918:option:`-isysroot /path/to/build`, which makes all includes for your library 919relative to the build directory. For example: 920 921.. code-block:: console 922 923 # clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch 924 925When loading the relocatable PCH file, the various headers used in the 926PCH file are found from the system header root. For example, ``mylib.h`` 927can be found in ``/usr/include/mylib.h``. If the headers are installed 928in some other system root, the :option:`-isysroot` option can be used provide 929a different system root from which the headers will be based. For 930example, :option:`-isysroot /Developer/SDKs/MacOSX10.4u.sdk` will look for 931``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``. 932 933Relocatable precompiled headers are intended to be used in a limited 934number of cases where the compilation environment is tightly controlled 935and the precompiled header cannot be generated after headers have been 936installed. 937 938.. _controlling-code-generation: 939 940Controlling Code Generation 941--------------------------- 942 943Clang provides a number of ways to control code generation. The options 944are listed below. 945 946**-f[no-]sanitize=check1,check2,...** 947 Turn on runtime checks for various forms of undefined or suspicious 948 behavior. 949 950 This option controls whether Clang adds runtime checks for various 951 forms of undefined or suspicious behavior, and is disabled by 952 default. If a check fails, a diagnostic message is produced at 953 runtime explaining the problem. The main checks are: 954 955 - .. _opt_fsanitize_address: 956 957 ``-fsanitize=address``: 958 :doc:`AddressSanitizer`, a memory error 959 detector. 960 - .. _opt_fsanitize_thread: 961 962 ``-fsanitize=thread``: :doc:`ThreadSanitizer`, a data race detector. 963 - .. _opt_fsanitize_memory: 964 965 ``-fsanitize=memory``: :doc:`MemorySanitizer`, 966 a detector of uninitialized reads. Requires instrumentation of all 967 program code. 968 - .. _opt_fsanitize_undefined: 969 970 ``-fsanitize=undefined``: :doc:`UndefinedBehaviorSanitizer`, 971 a fast and compatible undefined behavior checker. 972 973 - ``-fsanitize=dataflow``: :doc:`DataFlowSanitizer`, a general data 974 flow analysis. 975 - ``-fsanitize=cfi``: :doc:`control flow integrity <ControlFlowIntegrity>` 976 checks. Requires ``-flto``. 977 - ``-fsanitize=safe-stack``: :doc:`safe stack <SafeStack>` 978 protection against stack-based memory corruption errors. 979 980 There are more fine-grained checks available: see 981 the :ref:`list <ubsan-checks>` of specific kinds of 982 undefined behavior that can be detected and the :ref:`list <cfi-schemes>` 983 of control flow integrity schemes. 984 985 The ``-fsanitize=`` argument must also be provided when linking, in 986 order to link to the appropriate runtime library. 987 988 It is not possible to combine more than one of the ``-fsanitize=address``, 989 ``-fsanitize=thread``, and ``-fsanitize=memory`` checkers in the same 990 program. 991 992**-f[no-]sanitize-recover=check1,check2,...** 993 994**-f[no-]sanitize-recover=all** 995 996 Controls which checks enabled by ``-fsanitize=`` flag are non-fatal. 997 If the check is fatal, program will halt after the first error 998 of this kind is detected and error report is printed. 999 1000 By default, non-fatal checks are those enabled by 1001 :doc:`UndefinedBehaviorSanitizer`, 1002 except for ``-fsanitize=return`` and ``-fsanitize=unreachable``. Some 1003 sanitizers may not support recovery (or not support it by default 1004 e.g. :doc:`AddressSanitizer`), and always crash the program after the issue 1005 is detected. 1006 1007 Note that the ``-fsanitize-trap`` flag has precedence over this flag. 1008 This means that if a check has been configured to trap elsewhere on the 1009 command line, or if the check traps by default, this flag will not have 1010 any effect unless that sanitizer's trapping behavior is disabled with 1011 ``-fno-sanitize-trap``. 1012 1013 For example, if a command line contains the flags ``-fsanitize=undefined 1014 -fsanitize-trap=undefined``, the flag ``-fsanitize-recover=alignment`` 1015 will have no effect on its own; it will need to be accompanied by 1016 ``-fno-sanitize-trap=alignment``. 1017 1018**-f[no-]sanitize-trap=check1,check2,...** 1019 1020 Controls which checks enabled by the ``-fsanitize=`` flag trap. This 1021 option is intended for use in cases where the sanitizer runtime cannot 1022 be used (for instance, when building libc or a kernel module), or where 1023 the binary size increase caused by the sanitizer runtime is a concern. 1024 1025 This flag is only compatible with :doc:`control flow integrity 1026 <ControlFlowIntegrity>` schemes and :doc:`UndefinedBehaviorSanitizer` 1027 checks other than ``vptr``. If this flag 1028 is supplied together with ``-fsanitize=undefined``, the ``vptr`` sanitizer 1029 will be implicitly disabled. 1030 1031 This flag is enabled by default for sanitizers in the ``cfi`` group. 1032 1033.. option:: -fsanitize-blacklist=/path/to/blacklist/file 1034 1035 Disable or modify sanitizer checks for objects (source files, functions, 1036 variables, types) listed in the file. See 1037 :doc:`SanitizerSpecialCaseList` for file format description. 1038 1039.. option:: -fno-sanitize-blacklist 1040 1041 Don't use blacklist file, if it was specified earlier in the command line. 1042 1043**-f[no-]sanitize-coverage=[type,features,...]** 1044 1045 Enable simple code coverage in addition to certain sanitizers. 1046 See :doc:`SanitizerCoverage` for more details. 1047 1048**-f[no-]sanitize-stats** 1049 1050 Enable simple statistics gathering for the enabled sanitizers. 1051 See :doc:`SanitizerStats` for more details. 1052 1053.. option:: -fsanitize-undefined-trap-on-error 1054 1055 Deprecated alias for ``-fsanitize-trap=undefined``. 1056 1057.. option:: -fsanitize-cfi-cross-dso 1058 1059 Enable cross-DSO control flow integrity checks. This flag modifies 1060 the behavior of sanitizers in the ``cfi`` group to allow checking 1061 of cross-DSO virtual and indirect calls. 1062 1063.. option:: -ffast-math 1064 1065 Enable fast-math mode. This defines the ``__FAST_MATH__`` preprocessor 1066 macro, and lets the compiler make aggressive, potentially-lossy assumptions 1067 about floating-point math. These include: 1068 1069 * Floating-point math obeys regular algebraic rules for real numbers (e.g. 1070 ``+`` and ``*`` are associative, ``x/y == x * (1/y)``, and 1071 ``(a + b) * c == a * c + b * c``), 1072 * operands to floating-point operations are not equal to ``NaN`` and 1073 ``Inf``, and 1074 * ``+0`` and ``-0`` are interchangeable. 1075 1076.. option:: -fwhole-program-vtables 1077 1078 Enable whole-program vtable optimizations, such as single-implementation 1079 devirtualization and virtual constant propagation, for classes with 1080 :doc:`hidden LTO visibility <LTOVisibility>`. Requires ``-flto``. 1081 1082.. option:: -fno-assume-sane-operator-new 1083 1084 Don't assume that the C++'s new operator is sane. 1085 1086 This option tells the compiler to do not assume that C++'s global 1087 new operator will always return a pointer that does not alias any 1088 other pointer when the function returns. 1089 1090.. option:: -ftrap-function=[name] 1091 1092 Instruct code generator to emit a function call to the specified 1093 function name for ``__builtin_trap()``. 1094 1095 LLVM code generator translates ``__builtin_trap()`` to a trap 1096 instruction if it is supported by the target ISA. Otherwise, the 1097 builtin is translated into a call to ``abort``. If this option is 1098 set, then the code generator will always lower the builtin to a call 1099 to the specified function regardless of whether the target ISA has a 1100 trap instruction. This option is useful for environments (e.g. 1101 deeply embedded) where a trap cannot be properly handled, or when 1102 some custom behavior is desired. 1103 1104.. option:: -ftls-model=[model] 1105 1106 Select which TLS model to use. 1107 1108 Valid values are: ``global-dynamic``, ``local-dynamic``, 1109 ``initial-exec`` and ``local-exec``. The default value is 1110 ``global-dynamic``. The compiler may use a different model if the 1111 selected model is not supported by the target, or if a more 1112 efficient model can be used. The TLS model can be overridden per 1113 variable using the ``tls_model`` attribute. 1114 1115.. option:: -femulated-tls 1116 1117 Select emulated TLS model, which overrides all -ftls-model choices. 1118 1119 In emulated TLS mode, all access to TLS variables are converted to 1120 calls to __emutls_get_address in the runtime library. 1121 1122.. option:: -mhwdiv=[values] 1123 1124 Select the ARM modes (arm or thumb) that support hardware division 1125 instructions. 1126 1127 Valid values are: ``arm``, ``thumb`` and ``arm,thumb``. 1128 This option is used to indicate which mode (arm or thumb) supports 1129 hardware division instructions. This only applies to the ARM 1130 architecture. 1131 1132.. option:: -m[no-]crc 1133 1134 Enable or disable CRC instructions. 1135 1136 This option is used to indicate whether CRC instructions are to 1137 be generated. This only applies to the ARM architecture. 1138 1139 CRC instructions are enabled by default on ARMv8. 1140 1141.. option:: -mgeneral-regs-only 1142 1143 Generate code which only uses the general purpose registers. 1144 1145 This option restricts the generated code to use general registers 1146 only. This only applies to the AArch64 architecture. 1147 1148.. option:: -mcompact-branches=[values] 1149 1150 Control the usage of compact branches for MIPSR6. 1151 1152 Valid values are: ``never``, ``optimal`` and ``always``. 1153 The default value is ``optimal`` which generates compact branches 1154 when a delay slot cannot be filled. ``never`` disables the usage of 1155 compact branches and ``always`` generates compact branches whenever 1156 possible. 1157 1158**-f[no-]max-type-align=[number]** 1159 Instruct the code generator to not enforce a higher alignment than the given 1160 number (of bytes) when accessing memory via an opaque pointer or reference. 1161 This cap is ignored when directly accessing a variable or when the pointee 1162 type has an explicit “aligned” attribute. 1163 1164 The value should usually be determined by the properties of the system allocator. 1165 Some builtin types, especially vector types, have very high natural alignments; 1166 when working with values of those types, Clang usually wants to use instructions 1167 that take advantage of that alignment. However, many system allocators do 1168 not promise to return memory that is more than 8-byte or 16-byte-aligned. Use 1169 this option to limit the alignment that the compiler can assume for an arbitrary 1170 pointer, which may point onto the heap. 1171 1172 This option does not affect the ABI alignment of types; the layout of structs and 1173 unions and the value returned by the alignof operator remain the same. 1174 1175 This option can be overridden on a case-by-case basis by putting an explicit 1176 “aligned” alignment on a struct, union, or typedef. For example: 1177 1178 .. code-block:: console 1179 1180 #include <immintrin.h> 1181 // Make an aligned typedef of the AVX-512 16-int vector type. 1182 typedef __v16si __aligned_v16si __attribute__((aligned(64))); 1183 1184 void initialize_vector(__aligned_v16si *v) { 1185 // The compiler may assume that ‘v’ is 64-byte aligned, regardless of the 1186 // value of -fmax-type-align. 1187 } 1188 1189 1190Profile Guided Optimization 1191--------------------------- 1192 1193Profile information enables better optimization. For example, knowing that a 1194branch is taken very frequently helps the compiler make better decisions when 1195ordering basic blocks. Knowing that a function ``foo`` is called more 1196frequently than another function ``bar`` helps the inliner. 1197 1198Clang supports profile guided optimization with two different kinds of 1199profiling. A sampling profiler can generate a profile with very low runtime 1200overhead, or you can build an instrumented version of the code that collects 1201more detailed profile information. Both kinds of profiles can provide execution 1202counts for instructions in the code and information on branches taken and 1203function invocation. 1204 1205Regardless of which kind of profiling you use, be careful to collect profiles 1206by running your code with inputs that are representative of the typical 1207behavior. Code that is not exercised in the profile will be optimized as if it 1208is unimportant, and the compiler may make poor optimization choices for code 1209that is disproportionately used while profiling. 1210 1211Differences Between Sampling and Instrumentation 1212^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1213 1214Although both techniques are used for similar purposes, there are important 1215differences between the two: 1216 12171. Profile data generated with one cannot be used by the other, and there is no 1218 conversion tool that can convert one to the other. So, a profile generated 1219 via ``-fprofile-instr-generate`` must be used with ``-fprofile-instr-use``. 1220 Similarly, sampling profiles generated by external profilers must be 1221 converted and used with ``-fprofile-sample-use``. 1222 12232. Instrumentation profile data can be used for code coverage analysis and 1224 optimization. 1225 12263. Sampling profiles can only be used for optimization. They cannot be used for 1227 code coverage analysis. Although it would be technically possible to use 1228 sampling profiles for code coverage, sample-based profiles are too 1229 coarse-grained for code coverage purposes; it would yield poor results. 1230 12314. Sampling profiles must be generated by an external tool. The profile 1232 generated by that tool must then be converted into a format that can be read 1233 by LLVM. The section on sampling profilers describes one of the supported 1234 sampling profile formats. 1235 1236 1237Using Sampling Profilers 1238^^^^^^^^^^^^^^^^^^^^^^^^ 1239 1240Sampling profilers are used to collect runtime information, such as 1241hardware counters, while your application executes. They are typically 1242very efficient and do not incur a large runtime overhead. The 1243sample data collected by the profiler can be used during compilation 1244to determine what the most executed areas of the code are. 1245 1246Using the data from a sample profiler requires some changes in the way 1247a program is built. Before the compiler can use profiling information, 1248the code needs to execute under the profiler. The following is the 1249usual build cycle when using sample profilers for optimization: 1250 12511. Build the code with source line table information. You can use all the 1252 usual build flags that you always build your application with. The only 1253 requirement is that you add ``-gline-tables-only`` or ``-g`` to the 1254 command line. This is important for the profiler to be able to map 1255 instructions back to source line locations. 1256 1257 .. code-block:: console 1258 1259 $ clang++ -O2 -gline-tables-only code.cc -o code 1260 12612. Run the executable under a sampling profiler. The specific profiler 1262 you use does not really matter, as long as its output can be converted 1263 into the format that the LLVM optimizer understands. Currently, there 1264 exists a conversion tool for the Linux Perf profiler 1265 (https://perf.wiki.kernel.org/), so these examples assume that you 1266 are using Linux Perf to profile your code. 1267 1268 .. code-block:: console 1269 1270 $ perf record -b ./code 1271 1272 Note the use of the ``-b`` flag. This tells Perf to use the Last Branch 1273 Record (LBR) to record call chains. While this is not strictly required, 1274 it provides better call information, which improves the accuracy of 1275 the profile data. 1276 12773. Convert the collected profile data to LLVM's sample profile format. 1278 This is currently supported via the AutoFDO converter ``create_llvm_prof``. 1279 It is available at http://github.com/google/autofdo. Once built and 1280 installed, you can convert the ``perf.data`` file to LLVM using 1281 the command: 1282 1283 .. code-block:: console 1284 1285 $ create_llvm_prof --binary=./code --out=code.prof 1286 1287 This will read ``perf.data`` and the binary file ``./code`` and emit 1288 the profile data in ``code.prof``. Note that if you ran ``perf`` 1289 without the ``-b`` flag, you need to use ``--use_lbr=false`` when 1290 calling ``create_llvm_prof``. 1291 12924. Build the code again using the collected profile. This step feeds 1293 the profile back to the optimizers. This should result in a binary 1294 that executes faster than the original one. Note that you are not 1295 required to build the code with the exact same arguments that you 1296 used in the first step. The only requirement is that you build the code 1297 with ``-gline-tables-only`` and ``-fprofile-sample-use``. 1298 1299 .. code-block:: console 1300 1301 $ clang++ -O2 -gline-tables-only -fprofile-sample-use=code.prof code.cc -o code 1302 1303 1304Sample Profile Formats 1305"""""""""""""""""""""" 1306 1307Since external profilers generate profile data in a variety of custom formats, 1308the data generated by the profiler must be converted into a format that can be 1309read by the backend. LLVM supports three different sample profile formats: 1310 13111. ASCII text. This is the easiest one to generate. The file is divided into 1312 sections, which correspond to each of the functions with profile 1313 information. The format is described below. It can also be generated from 1314 the binary or gcov formats using the ``llvm-profdata`` tool. 1315 13162. Binary encoding. This uses a more efficient encoding that yields smaller 1317 profile files. This is the format generated by the ``create_llvm_prof`` tool 1318 in http://github.com/google/autofdo. 1319 13203. GCC encoding. This is based on the gcov format, which is accepted by GCC. It 1321 is only interesting in environments where GCC and Clang co-exist. This 1322 encoding is only generated by the ``create_gcov`` tool in 1323 http://github.com/google/autofdo. It can be read by LLVM and 1324 ``llvm-profdata``, but it cannot be generated by either. 1325 1326If you are using Linux Perf to generate sampling profiles, you can use the 1327conversion tool ``create_llvm_prof`` described in the previous section. 1328Otherwise, you will need to write a conversion tool that converts your 1329profiler's native format into one of these three. 1330 1331 1332Sample Profile Text Format 1333"""""""""""""""""""""""""" 1334 1335This section describes the ASCII text format for sampling profiles. It is, 1336arguably, the easiest one to generate. If you are interested in generating any 1337of the other two, consult the ``ProfileData`` library in in LLVM's source tree 1338(specifically, ``include/llvm/ProfileData/SampleProfReader.h``). 1339 1340.. code-block:: console 1341 1342 function1:total_samples:total_head_samples 1343 offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ] 1344 offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ] 1345 ... 1346 offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ] 1347 offsetA[.discriminator]: fnA:num_of_total_samples 1348 offsetA1[.discriminator]: number_of_samples [fn7:num fn8:num ... ] 1349 offsetA1[.discriminator]: number_of_samples [fn9:num fn10:num ... ] 1350 offsetB[.discriminator]: fnB:num_of_total_samples 1351 offsetB1[.discriminator]: number_of_samples [fn11:num fn12:num ... ] 1352 1353This is a nested tree in which the identation represents the nesting level 1354of the inline stack. There are no blank lines in the file. And the spacing 1355within a single line is fixed. Additional spaces will result in an error 1356while reading the file. 1357 1358Any line starting with the '#' character is completely ignored. 1359 1360Inlined calls are represented with indentation. The Inline stack is a 1361stack of source locations in which the top of the stack represents the 1362leaf function, and the bottom of the stack represents the actual 1363symbol to which the instruction belongs. 1364 1365Function names must be mangled in order for the profile loader to 1366match them in the current translation unit. The two numbers in the 1367function header specify how many total samples were accumulated in the 1368function (first number), and the total number of samples accumulated 1369in the prologue of the function (second number). This head sample 1370count provides an indicator of how frequently the function is invoked. 1371 1372There are two types of lines in the function body. 1373 1374- Sampled line represents the profile information of a source location. 1375 ``offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]`` 1376 1377- Callsite line represents the profile information of an inlined callsite. 1378 ``offsetA[.discriminator]: fnA:num_of_total_samples`` 1379 1380Each sampled line may contain several items. Some are optional (marked 1381below): 1382 1383a. Source line offset. This number represents the line number 1384 in the function where the sample was collected. The line number is 1385 always relative to the line where symbol of the function is 1386 defined. So, if the function has its header at line 280, the offset 1387 13 is at line 293 in the file. 1388 1389 Note that this offset should never be a negative number. This could 1390 happen in cases like macros. The debug machinery will register the 1391 line number at the point of macro expansion. So, if the macro was 1392 expanded in a line before the start of the function, the profile 1393 converter should emit a 0 as the offset (this means that the optimizers 1394 will not be able to associate a meaningful weight to the instructions 1395 in the macro). 1396 1397b. [OPTIONAL] Discriminator. This is used if the sampled program 1398 was compiled with DWARF discriminator support 1399 (http://wiki.dwarfstd.org/index.php?title=Path_Discriminators). 1400 DWARF discriminators are unsigned integer values that allow the 1401 compiler to distinguish between multiple execution paths on the 1402 same source line location. 1403 1404 For example, consider the line of code ``if (cond) foo(); else bar();``. 1405 If the predicate ``cond`` is true 80% of the time, then the edge 1406 into function ``foo`` should be considered to be taken most of the 1407 time. But both calls to ``foo`` and ``bar`` are at the same source 1408 line, so a sample count at that line is not sufficient. The 1409 compiler needs to know which part of that line is taken more 1410 frequently. 1411 1412 This is what discriminators provide. In this case, the calls to 1413 ``foo`` and ``bar`` will be at the same line, but will have 1414 different discriminator values. This allows the compiler to correctly 1415 set edge weights into ``foo`` and ``bar``. 1416 1417c. Number of samples. This is an integer quantity representing the 1418 number of samples collected by the profiler at this source 1419 location. 1420 1421d. [OPTIONAL] Potential call targets and samples. If present, this 1422 line contains a call instruction. This models both direct and 1423 number of samples. For example, 1424 1425 .. code-block:: console 1426 1427 130: 7 foo:3 bar:2 baz:7 1428 1429 The above means that at relative line offset 130 there is a call 1430 instruction that calls one of ``foo()``, ``bar()`` and ``baz()``, 1431 with ``baz()`` being the relatively more frequently called target. 1432 1433As an example, consider a program with the call chain ``main -> foo -> bar``. 1434When built with optimizations enabled, the compiler may inline the 1435calls to ``bar`` and ``foo`` inside ``main``. The generated profile 1436could then be something like this: 1437 1438.. code-block:: console 1439 1440 main:35504:0 1441 1: _Z3foov:35504 1442 2: _Z32bari:31977 1443 1.1: 31977 1444 2: 0 1445 1446This profile indicates that there were a total of 35,504 samples 1447collected in main. All of those were at line 1 (the call to ``foo``). 1448Of those, 31,977 were spent inside the body of ``bar``. The last line 1449of the profile (``2: 0``) corresponds to line 2 inside ``main``. No 1450samples were collected there. 1451 1452Profiling with Instrumentation 1453^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1454 1455Clang also supports profiling via instrumentation. This requires building a 1456special instrumented version of the code and has some runtime 1457overhead during the profiling, but it provides more detailed results than a 1458sampling profiler. It also provides reproducible results, at least to the 1459extent that the code behaves consistently across runs. 1460 1461Here are the steps for using profile guided optimization with 1462instrumentation: 1463 14641. Build an instrumented version of the code by compiling and linking with the 1465 ``-fprofile-instr-generate`` option. 1466 1467 .. code-block:: console 1468 1469 $ clang++ -O2 -fprofile-instr-generate code.cc -o code 1470 14712. Run the instrumented executable with inputs that reflect the typical usage. 1472 By default, the profile data will be written to a ``default.profraw`` file 1473 in the current directory. You can override that default by setting the 1474 ``LLVM_PROFILE_FILE`` environment variable to specify an alternate file. 1475 Any instance of ``%p`` in that file name will be replaced by the process 1476 ID, so that you can easily distinguish the profile output from multiple 1477 runs. 1478 1479 .. code-block:: console 1480 1481 $ LLVM_PROFILE_FILE="code-%p.profraw" ./code 1482 14833. Combine profiles from multiple runs and convert the "raw" profile format to 1484 the input expected by clang. Use the ``merge`` command of the 1485 ``llvm-profdata`` tool to do this. 1486 1487 .. code-block:: console 1488 1489 $ llvm-profdata merge -output=code.profdata code-*.profraw 1490 1491 Note that this step is necessary even when there is only one "raw" profile, 1492 since the merge operation also changes the file format. 1493 14944. Build the code again using the ``-fprofile-instr-use`` option to specify the 1495 collected profile data. 1496 1497 .. code-block:: console 1498 1499 $ clang++ -O2 -fprofile-instr-use=code.profdata code.cc -o code 1500 1501 You can repeat step 4 as often as you like without regenerating the 1502 profile. As you make changes to your code, clang may no longer be able to 1503 use the profile data. It will warn you when this happens. 1504 1505Profile generation and use can also be controlled by the GCC-compatible flags 1506``-fprofile-generate`` and ``-fprofile-use``. Although these flags are 1507semantically equivalent to their GCC counterparts, they *do not* handle 1508GCC-compatible profiles. They are only meant to implement GCC's semantics 1509with respect to profile creation and use. 1510 1511.. option:: -fprofile-generate[=<dirname>] 1512 1513 Without any other arguments, ``-fprofile-generate`` behaves identically to 1514 ``-fprofile-instr-generate``. When given a directory name, it generates the 1515 profile file ``default.profraw`` in the directory named ``dirname``. If 1516 ``dirname`` does not exist, it will be created at runtime. The environment 1517 variable ``LLVM_PROFILE_FILE`` can be used to override the directory and 1518 filename for the profile file at runtime. For example, 1519 1520 .. code-block:: console 1521 1522 $ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code 1523 1524 When ``code`` is executed, the profile will be written to the file 1525 ``yyy/zzz/default.profraw``. This can be altered at runtime via the 1526 ``LLVM_PROFILE_FILE`` environment variable: 1527 1528 .. code-block:: console 1529 1530 $ LLVM_PROFILE_FILE=/tmp/myprofile/code.profraw ./code 1531 1532 The above invocation will produce the profile file 1533 ``/tmp/myprofile/code.profraw`` instead of ``yyy/zzz/default.profraw``. 1534 Notice that ``LLVM_PROFILE_FILE`` overrides the directory *and* the file 1535 name for the profile file. 1536 1537.. option:: -fprofile-use[=<pathname>] 1538 1539 Without any other arguments, ``-fprofile-use`` behaves identically to 1540 ``-fprofile-instr-use``. Otherwise, if ``pathname`` is the full path to a 1541 profile file, it reads from that file. If ``pathname`` is a directory name, 1542 it reads from ``pathname/default.profdata``. 1543 1544Disabling Instrumentation 1545^^^^^^^^^^^^^^^^^^^^^^^^^ 1546 1547In certain situations, it may be useful to disable profile generation or use 1548for specific files in a build, without affecting the main compilation flags 1549used for the other files in the project. 1550 1551In these cases, you can use the flag ``-fno-profile-instr-generate`` (or 1552``-fno-profile-generate``) to disable profile generation, and 1553``-fno-profile-instr-use`` (or ``-fno-profile-use``) to disable profile use. 1554 1555Note that these flags should appear after the corresponding profile 1556flags to have an effect. 1557 1558Controlling Debug Information 1559----------------------------- 1560 1561Controlling Size of Debug Information 1562^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1563 1564Debug info kind generated by Clang can be set by one of the flags listed 1565below. If multiple flags are present, the last one is used. 1566 1567.. option:: -g0 1568 1569 Don't generate any debug info (default). 1570 1571.. option:: -gline-tables-only 1572 1573 Generate line number tables only. 1574 1575 This kind of debug info allows to obtain stack traces with function names, 1576 file names and line numbers (by such tools as ``gdb`` or ``addr2line``). It 1577 doesn't contain any other data (e.g. description of local variables or 1578 function parameters). 1579 1580.. option:: -fstandalone-debug 1581 1582 Clang supports a number of optimizations to reduce the size of debug 1583 information in the binary. They work based on the assumption that 1584 the debug type information can be spread out over multiple 1585 compilation units. For instance, Clang will not emit type 1586 definitions for types that are not needed by a module and could be 1587 replaced with a forward declaration. Further, Clang will only emit 1588 type info for a dynamic C++ class in the module that contains the 1589 vtable for the class. 1590 1591 The **-fstandalone-debug** option turns off these optimizations. 1592 This is useful when working with 3rd-party libraries that don't come 1593 with debug information. Note that Clang will never emit type 1594 information for types that are not referenced at all by the program. 1595 1596.. option:: -fno-standalone-debug 1597 1598 On Darwin **-fstandalone-debug** is enabled by default. The 1599 **-fno-standalone-debug** option can be used to get to turn on the 1600 vtable-based optimization described above. 1601 1602.. option:: -g 1603 1604 Generate complete debug info. 1605 1606Controlling Debugger "Tuning" 1607^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1608 1609While Clang generally emits standard DWARF debug info (http://dwarfstd.org), 1610different debuggers may know how to take advantage of different specific DWARF 1611features. You can "tune" the debug info for one of several different debuggers. 1612 1613.. option:: -ggdb, -glldb, -gsce 1614 1615 Tune the debug info for the ``gdb``, ``lldb``, or Sony Computer Entertainment 1616 debugger, respectively. Each of these options implies **-g**. (Therefore, if 1617 you want both **-gline-tables-only** and debugger tuning, the tuning option 1618 must come first.) 1619 1620 1621Comment Parsing Options 1622----------------------- 1623 1624Clang parses Doxygen and non-Doxygen style documentation comments and attaches 1625them to the appropriate declaration nodes. By default, it only parses 1626Doxygen-style comments and ignores ordinary comments starting with ``//`` and 1627``/*``. 1628 1629.. option:: -Wdocumentation 1630 1631 Emit warnings about use of documentation comments. This warning group is off 1632 by default. 1633 1634 This includes checking that ``\param`` commands name parameters that actually 1635 present in the function signature, checking that ``\returns`` is used only on 1636 functions that actually return a value etc. 1637 1638.. option:: -Wno-documentation-unknown-command 1639 1640 Don't warn when encountering an unknown Doxygen command. 1641 1642.. option:: -fparse-all-comments 1643 1644 Parse all comments as documentation comments (including ordinary comments 1645 starting with ``//`` and ``/*``). 1646 1647.. option:: -fcomment-block-commands=[commands] 1648 1649 Define custom documentation commands as block commands. This allows Clang to 1650 construct the correct AST for these custom commands, and silences warnings 1651 about unknown commands. Several commands must be separated by a comma 1652 *without trailing space*; e.g. ``-fcomment-block-commands=foo,bar`` defines 1653 custom commands ``\foo`` and ``\bar``. 1654 1655 It is also possible to use ``-fcomment-block-commands`` several times; e.g. 1656 ``-fcomment-block-commands=foo -fcomment-block-commands=bar`` does the same 1657 as above. 1658 1659.. _c: 1660 1661C Language Features 1662=================== 1663 1664The support for standard C in clang is feature-complete except for the 1665C99 floating-point pragmas. 1666 1667Extensions supported by clang 1668----------------------------- 1669 1670See :doc:`LanguageExtensions`. 1671 1672Differences between various standard modes 1673------------------------------------------ 1674 1675clang supports the -std option, which changes what language mode clang 1676uses. The supported modes for C are c89, gnu89, c94, c99, gnu99, c11, 1677gnu11, and various aliases for those modes. If no -std option is 1678specified, clang defaults to gnu11 mode. Many C99 and C11 features are 1679supported in earlier modes as a conforming extension, with a warning. Use 1680``-pedantic-errors`` to request an error if a feature from a later standard 1681revision is used in an earlier mode. 1682 1683Differences between all ``c*`` and ``gnu*`` modes: 1684 1685- ``c*`` modes define "``__STRICT_ANSI__``". 1686- Target-specific defines not prefixed by underscores, like "linux", 1687 are defined in ``gnu*`` modes. 1688- Trigraphs default to being off in ``gnu*`` modes; they can be enabled by 1689 the -trigraphs option. 1690- The parser recognizes "asm" and "typeof" as keywords in ``gnu*`` modes; 1691 the variants "``__asm__``" and "``__typeof__``" are recognized in all 1692 modes. 1693- The Apple "blocks" extension is recognized by default in ``gnu*`` modes 1694 on some platforms; it can be enabled in any mode with the "-fblocks" 1695 option. 1696- Arrays that are VLA's according to the standard, but which can be 1697 constant folded by the frontend are treated as fixed size arrays. 1698 This occurs for things like "int X[(1, 2)];", which is technically a 1699 VLA. ``c*`` modes are strictly compliant and treat these as VLAs. 1700 1701Differences between ``*89`` and ``*99`` modes: 1702 1703- The ``*99`` modes default to implementing "inline" as specified in C99, 1704 while the ``*89`` modes implement the GNU version. This can be 1705 overridden for individual functions with the ``__gnu_inline__`` 1706 attribute. 1707- Digraphs are not recognized in c89 mode. 1708- The scope of names defined inside a "for", "if", "switch", "while", 1709 or "do" statement is different. (example: "``if ((struct x {int 1710 x;}*)0) {}``".) 1711- ``__STDC_VERSION__`` is not defined in ``*89`` modes. 1712- "inline" is not recognized as a keyword in c89 mode. 1713- "restrict" is not recognized as a keyword in ``*89`` modes. 1714- Commas are allowed in integer constant expressions in ``*99`` modes. 1715- Arrays which are not lvalues are not implicitly promoted to pointers 1716 in ``*89`` modes. 1717- Some warnings are different. 1718 1719Differences between ``*99`` and ``*11`` modes: 1720 1721- Warnings for use of C11 features are disabled. 1722- ``__STDC_VERSION__`` is defined to ``201112L`` rather than ``199901L``. 1723 1724c94 mode is identical to c89 mode except that digraphs are enabled in 1725c94 mode (FIXME: And ``__STDC_VERSION__`` should be defined!). 1726 1727GCC extensions not implemented yet 1728---------------------------------- 1729 1730clang tries to be compatible with gcc as much as possible, but some gcc 1731extensions are not implemented yet: 1732 1733- clang does not support decimal floating point types (``_Decimal32`` and 1734 friends) or fixed-point types (``_Fract`` and friends); nobody has 1735 expressed interest in these features yet, so it's hard to say when 1736 they will be implemented. 1737- clang does not support nested functions; this is a complex feature 1738 which is infrequently used, so it is unlikely to be implemented 1739 anytime soon. In C++11 it can be emulated by assigning lambda 1740 functions to local variables, e.g: 1741 1742 .. code-block:: cpp 1743 1744 auto const local_function = [&](int parameter) { 1745 // Do something 1746 }; 1747 ... 1748 local_function(1); 1749 1750- clang does not support static initialization of flexible array 1751 members. This appears to be a rarely used extension, but could be 1752 implemented pending user demand. 1753- clang does not support 1754 ``__builtin_va_arg_pack``/``__builtin_va_arg_pack_len``. This is 1755 used rarely, but in some potentially interesting places, like the 1756 glibc headers, so it may be implemented pending user demand. Note 1757 that because clang pretends to be like GCC 4.2, and this extension 1758 was introduced in 4.3, the glibc headers will not try to use this 1759 extension with clang at the moment. 1760- clang does not support the gcc extension for forward-declaring 1761 function parameters; this has not shown up in any real-world code 1762 yet, though, so it might never be implemented. 1763 1764This is not a complete list; if you find an unsupported extension 1765missing from this list, please send an e-mail to cfe-dev. This list 1766currently excludes C++; see :ref:`C++ Language Features <cxx>`. Also, this 1767list does not include bugs in mostly-implemented features; please see 1768the `bug 1769tracker <http://llvm.org/bugs/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer>`_ 1770for known existing bugs (FIXME: Is there a section for bug-reporting 1771guidelines somewhere?). 1772 1773Intentionally unsupported GCC extensions 1774---------------------------------------- 1775 1776- clang does not support the gcc extension that allows variable-length 1777 arrays in structures. This is for a few reasons: one, it is tricky to 1778 implement, two, the extension is completely undocumented, and three, 1779 the extension appears to be rarely used. Note that clang *does* 1780 support flexible array members (arrays with a zero or unspecified 1781 size at the end of a structure). 1782- clang does not have an equivalent to gcc's "fold"; this means that 1783 clang doesn't accept some constructs gcc might accept in contexts 1784 where a constant expression is required, like "x-x" where x is a 1785 variable. 1786- clang does not support ``__builtin_apply`` and friends; this extension 1787 is extremely obscure and difficult to implement reliably. 1788 1789.. _c_ms: 1790 1791Microsoft extensions 1792-------------------- 1793 1794clang has support for many extensions from Microsoft Visual C++. To enable these 1795extensions, use the ``-fms-extensions`` command-line option. This is the default 1796for Windows targets. Clang does not implement every pragma or declspec provided 1797by MSVC, but the popular ones, such as ``__declspec(dllexport)`` and ``#pragma 1798comment(lib)`` are well supported. 1799 1800clang has a ``-fms-compatibility`` flag that makes clang accept enough 1801invalid C++ to be able to parse most Microsoft headers. For example, it 1802allows `unqualified lookup of dependent base class members 1803<http://clang.llvm.org/compatibility.html#dep_lookup_bases>`_, which is 1804a common compatibility issue with clang. This flag is enabled by default 1805for Windows targets. 1806 1807``-fdelayed-template-parsing`` lets clang delay parsing of function template 1808definitions until the end of a translation unit. This flag is enabled by 1809default for Windows targets. 1810 1811For compatibility with existing code that compiles with MSVC, clang defines the 1812``_MSC_VER`` and ``_MSC_FULL_VER`` macros. These default to the values of 1800 1813and 180000000 respectively, making clang look like an early release of Visual 1814C++ 2013. The ``-fms-compatibility-version=`` flag overrides these values. It 1815accepts a dotted version tuple, such as 19.00.23506. Changing the MSVC 1816compatibility version makes clang behave more like that version of MSVC. For 1817example, ``-fms-compatibility-version=19`` will enable C++14 features and define 1818``char16_t`` and ``char32_t`` as builtin types. 1819 1820.. _cxx: 1821 1822C++ Language Features 1823===================== 1824 1825clang fully implements all of standard C++98 except for exported 1826templates (which were removed in C++11), and all of standard C++11 1827and the current draft standard for C++1y. 1828 1829Controlling implementation limits 1830--------------------------------- 1831 1832.. option:: -fbracket-depth=N 1833 1834 Sets the limit for nested parentheses, brackets, and braces to N. The 1835 default is 256. 1836 1837.. option:: -fconstexpr-depth=N 1838 1839 Sets the limit for recursive constexpr function invocations to N. The 1840 default is 512. 1841 1842.. option:: -ftemplate-depth=N 1843 1844 Sets the limit for recursively nested template instantiations to N. The 1845 default is 256. 1846 1847.. option:: -foperator-arrow-depth=N 1848 1849 Sets the limit for iterative calls to 'operator->' functions to N. The 1850 default is 256. 1851 1852.. _objc: 1853 1854Objective-C Language Features 1855============================= 1856 1857.. _objcxx: 1858 1859Objective-C++ Language Features 1860=============================== 1861 1862.. _openmp: 1863 1864OpenMP Features 1865=============== 1866 1867Clang supports all OpenMP 3.1 directives and clauses. In addition, some 1868features of OpenMP 4.0 are supported. For example, ``#pragma omp simd``, 1869``#pragma omp for simd``, ``#pragma omp parallel for simd`` directives, extended 1870set of atomic constructs, ``proc_bind`` clause for all parallel-based 1871directives, ``depend`` clause for ``#pragma omp task`` directive (except for 1872array sections), ``#pragma omp cancel`` and ``#pragma omp cancellation point`` 1873directives, and ``#pragma omp taskgroup`` directive. 1874 1875Use :option:`-fopenmp` to enable OpenMP. Support for OpenMP can be disabled with 1876:option:`-fno-openmp`. 1877 1878Controlling implementation limits 1879--------------------------------- 1880 1881.. option:: -fopenmp-use-tls 1882 1883 Controls code generation for OpenMP threadprivate variables. In presence of 1884 this option all threadprivate variables are generated the same way as thread 1885 local variables, using TLS support. If :option:`-fno-openmp-use-tls` 1886 is provided or target does not support TLS, code generation for threadprivate 1887 variables relies on OpenMP runtime library. 1888 1889.. _target_features: 1890 1891Target-Specific Features and Limitations 1892======================================== 1893 1894CPU Architectures Features and Limitations 1895------------------------------------------ 1896 1897X86 1898^^^ 1899 1900The support for X86 (both 32-bit and 64-bit) is considered stable on 1901Darwin (Mac OS X), Linux, FreeBSD, and Dragonfly BSD: it has been tested 1902to correctly compile many large C, C++, Objective-C, and Objective-C++ 1903codebases. 1904 1905On ``x86_64-mingw32``, passing i128(by value) is incompatible with the 1906Microsoft x64 calling convention. You might need to tweak 1907``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp. 1908 1909For the X86 target, clang supports the :option:`-m16` command line 1910argument which enables 16-bit code output. This is broadly similar to 1911using ``asm(".code16gcc")`` with the GNU toolchain. The generated code 1912and the ABI remains 32-bit but the assembler emits instructions 1913appropriate for a CPU running in 16-bit mode, with address-size and 1914operand-size prefixes to enable 32-bit addressing and operations. 1915 1916ARM 1917^^^ 1918 1919The support for ARM (specifically ARMv6 and ARMv7) is considered stable 1920on Darwin (iOS): it has been tested to correctly compile many large C, 1921C++, Objective-C, and Objective-C++ codebases. Clang only supports a 1922limited number of ARM architectures. It does not yet fully support 1923ARMv5, for example. 1924 1925PowerPC 1926^^^^^^^ 1927 1928The support for PowerPC (especially PowerPC64) is considered stable 1929on Linux and FreeBSD: it has been tested to correctly compile many 1930large C and C++ codebases. PowerPC (32bit) is still missing certain 1931features (e.g. PIC code on ELF platforms). 1932 1933Other platforms 1934^^^^^^^^^^^^^^^ 1935 1936clang currently contains some support for other architectures (e.g. Sparc); 1937however, significant pieces of code generation are still missing, and they 1938haven't undergone significant testing. 1939 1940clang contains limited support for the MSP430 embedded processor, but 1941both the clang support and the LLVM backend support are highly 1942experimental. 1943 1944Other platforms are completely unsupported at the moment. Adding the 1945minimal support needed for parsing and semantic analysis on a new 1946platform is quite easy; see ``lib/Basic/Targets.cpp`` in the clang source 1947tree. This level of support is also sufficient for conversion to LLVM IR 1948for simple programs. Proper support for conversion to LLVM IR requires 1949adding code to ``lib/CodeGen/CGCall.cpp`` at the moment; this is likely to 1950change soon, though. Generating assembly requires a suitable LLVM 1951backend. 1952 1953Operating System Features and Limitations 1954----------------------------------------- 1955 1956Darwin (Mac OS X) 1957^^^^^^^^^^^^^^^^^ 1958 1959Thread Sanitizer is not supported. 1960 1961Windows 1962^^^^^^^ 1963 1964Clang has experimental support for targeting "Cygming" (Cygwin / MinGW) 1965platforms. 1966 1967See also :ref:`Microsoft Extensions <c_ms>`. 1968 1969Cygwin 1970"""""" 1971 1972Clang works on Cygwin-1.7. 1973 1974MinGW32 1975""""""" 1976 1977Clang works on some mingw32 distributions. Clang assumes directories as 1978below; 1979 1980- ``C:/mingw/include`` 1981- ``C:/mingw/lib`` 1982- ``C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++`` 1983 1984On MSYS, a few tests might fail. 1985 1986MinGW-w64 1987""""""""" 1988 1989For 32-bit (i686-w64-mingw32), and 64-bit (x86\_64-w64-mingw32), Clang 1990assumes as below; 1991 1992- ``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)`` 1993- ``some_directory/bin/gcc.exe`` 1994- ``some_directory/bin/clang.exe`` 1995- ``some_directory/bin/clang++.exe`` 1996- ``some_directory/bin/../include/c++/GCC_version`` 1997- ``some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32`` 1998- ``some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32`` 1999- ``some_directory/bin/../include/c++/GCC_version/backward`` 2000- ``some_directory/bin/../x86_64-w64-mingw32/include`` 2001- ``some_directory/bin/../i686-w64-mingw32/include`` 2002- ``some_directory/bin/../include`` 2003 2004This directory layout is standard for any toolchain you will find on the 2005official `MinGW-w64 website <http://mingw-w64.sourceforge.net>`_. 2006 2007Clang expects the GCC executable "gcc.exe" compiled for 2008``i686-w64-mingw32`` (or ``x86_64-w64-mingw32``) to be present on PATH. 2009 2010`Some tests might fail <http://llvm.org/bugs/show_bug.cgi?id=9072>`_ on 2011``x86_64-w64-mingw32``. 2012 2013.. _clang-cl: 2014 2015clang-cl 2016======== 2017 2018clang-cl is an alternative command-line interface to Clang driver, designed for 2019compatibility with the Visual C++ compiler, cl.exe. 2020 2021To enable clang-cl to find system headers, libraries, and the linker when run 2022from the command-line, it should be executed inside a Visual Studio Native Tools 2023Command Prompt or a regular Command Prompt where the environment has been set 2024up using e.g. `vcvars32.bat <http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_. 2025 2026clang-cl can also be used from inside Visual Studio by using an LLVM Platform 2027Toolset. 2028 2029Command-Line Options 2030-------------------- 2031 2032To be compatible with cl.exe, clang-cl supports most of the same command-line 2033options. Those options can start with either ``/`` or ``-``. It also supports 2034some of Clang's core options, such as the ``-W`` options. 2035 2036Options that are known to clang-cl, but not currently supported, are ignored 2037with a warning. For example: 2038 2039 :: 2040 2041 clang-cl.exe: warning: argument unused during compilation: '/AI' 2042 2043To suppress warnings about unused arguments, use the ``-Qunused-arguments`` option. 2044 2045Options that are not known to clang-cl will be ignored by default. Use the 2046``-Werror=unknown-argument`` option in order to treat them as errors. If these 2047options are spelled with a leading ``/``, they will be mistaken for a filename: 2048 2049 :: 2050 2051 clang-cl.exe: error: no such file or directory: '/foobar' 2052 2053Please `file a bug <http://llvm.org/bugs/enter_bug.cgi?product=clang&component=Driver>`_ 2054for any valid cl.exe flags that clang-cl does not understand. 2055 2056Execute ``clang-cl /?`` to see a list of supported options: 2057 2058 :: 2059 2060 CL.EXE COMPATIBILITY OPTIONS: 2061 /? Display available options 2062 /arch:<value> Set architecture for code generation 2063 /Brepro- Emit an object file which cannot be reproduced over time 2064 /Brepro Emit an object file which can be reproduced over time 2065 /C Don't discard comments when preprocessing 2066 /c Compile only 2067 /D <macro[=value]> Define macro 2068 /EH<value> Exception handling model 2069 /EP Disable linemarker output and preprocess to stdout 2070 /E Preprocess to stdout 2071 /fallback Fall back to cl.exe if clang-cl fails to compile 2072 /FA Output assembly code file during compilation 2073 /Fa<file or directory> Output assembly code to this file during compilation (with /FA) 2074 /Fe<file or directory> Set output executable file or directory (ends in / or \) 2075 /FI <value> Include file before parsing 2076 /Fi<file> Set preprocess output file name (with /P) 2077 /Fo<file or directory> Set output object file, or directory (ends in / or \) (with /c) 2078 /fp:except- 2079 /fp:except 2080 /fp:fast 2081 /fp:precise 2082 /fp:strict 2083 /GA Assume thread-local variables are defined in the executable 2084 /GF- Disable string pooling 2085 /GR- Disable emission of RTTI data 2086 /GR Enable emission of RTTI data 2087 /Gs<value> Set stack probe size 2088 /Gw- Don't put each data item in its own section 2089 /Gw Put each data item in its own section 2090 /Gy- Don't put each function in its own section 2091 /Gy Put each function in its own section 2092 /help Display available options 2093 /I <dir> Add directory to include search path 2094 /J Make char type unsigned 2095 /LDd Create debug DLL 2096 /LD Create DLL 2097 /link <options> Forward options to the linker 2098 /MDd Use DLL debug run-time 2099 /MD Use DLL run-time 2100 /MTd Use static debug run-time 2101 /MT Use static run-time 2102 /Ob0 Disable inlining 2103 /Od Disable optimization 2104 /Oi- Disable use of builtin functions 2105 /Oi Enable use of builtin functions 2106 /Os Optimize for size 2107 /Ot Optimize for speed 2108 /O<value> Optimization level 2109 /o <file or directory> Set output file or directory (ends in / or \) 2110 /P Preprocess to file 2111 /Qvec- Disable the loop vectorization passes 2112 /Qvec Enable the loop vectorization passes 2113 /showIncludes Print info about included files to stderr 2114 /TC Treat all source files as C 2115 /Tc <filename> Specify a C source file 2116 /TP Treat all source files as C++ 2117 /Tp <filename> Specify a C++ source file 2118 /U <macro> Undefine macro 2119 /vd<value> Control vtordisp placement 2120 /vmb Use a best-case representation method for member pointers 2121 /vmg Use a most-general representation for member pointers 2122 /vmm Set the default most-general representation to multiple inheritance 2123 /vms Set the default most-general representation to single inheritance 2124 /vmv Set the default most-general representation to virtual inheritance 2125 /volatile:iso Volatile loads and stores have standard semantics 2126 /volatile:ms Volatile loads and stores have acquire and release semantics 2127 /W0 Disable all warnings 2128 /W1 Enable -Wall 2129 /W2 Enable -Wall 2130 /W3 Enable -Wall 2131 /W4 Enable -Wall and -Wextra 2132 /Wall Enable -Wall and -Wextra 2133 /WX- Do not treat warnings as errors 2134 /WX Treat warnings as errors 2135 /w Disable all warnings 2136 /Z7 Enable CodeView debug information in object files 2137 /Zc:sizedDealloc- Disable C++14 sized global deallocation functions 2138 /Zc:sizedDealloc Enable C++14 sized global deallocation functions 2139 /Zc:strictStrings Treat string literals as const 2140 /Zc:threadSafeInit- Disable thread-safe initialization of static variables 2141 /Zc:threadSafeInit Enable thread-safe initialization of static variables 2142 /Zc:trigraphs- Disable trigraphs (default) 2143 /Zc:trigraphs Enable trigraphs 2144 /Zi Alias for /Z7. Does not produce PDBs. 2145 /Zl Don't mention any default libraries in the object file 2146 /Zp Set the default maximum struct packing alignment to 1 2147 /Zp<value> Specify the default maximum struct packing alignment 2148 /Zs Syntax-check only 2149 2150 OPTIONS: 2151 -### Print (but do not run) the commands to run for this compilation 2152 --analyze Run the static analyzer 2153 -fansi-escape-codes Use ANSI escape codes for diagnostics 2154 -fcolor-diagnostics Use colors in diagnostics 2155 -fdiagnostics-parseable-fixits 2156 Print fix-its in machine parseable form 2157 -fms-compatibility-version=<value> 2158 Dot-separated value representing the Microsoft compiler version 2159 number to report in _MSC_VER (0 = don't define it (default)) 2160 -fms-compatibility Enable full Microsoft Visual C++ compatibility 2161 -fms-extensions Accept some non-standard constructs supported by the Microsoft compiler 2162 -fmsc-version=<value> Microsoft compiler version number to report in _MSC_VER 2163 (0 = don't define it (default)) 2164 -fno-sanitize-coverage=<value> 2165 Disable specified features of coverage instrumentation for Sanitizers 2166 -fno-sanitize-recover=<value> 2167 Disable recovery for specified sanitizers 2168 -fno-sanitize-trap=<value> 2169 Disable trapping for specified sanitizers 2170 -fsanitize-blacklist=<value> 2171 Path to blacklist file for sanitizers 2172 -fsanitize-coverage=<value> 2173 Specify the type of coverage instrumentation for Sanitizers 2174 -fsanitize-recover=<value> 2175 Enable recovery for specified sanitizers 2176 -fsanitize-trap=<value> Enable trapping for specified sanitizers 2177 -fsanitize=<check> Turn on runtime checks for various forms of undefined or suspicious 2178 behavior. See user manual for available checks 2179 -gcodeview Generate CodeView debug information 2180 -mllvm <value> Additional arguments to forward to LLVM's option processing 2181 -Qunused-arguments Don't emit warning for unused driver arguments 2182 -R<remark> Enable the specified remark 2183 --target=<value> Generate code for the given target 2184 -v Show commands to run and use verbose output 2185 -W<warning> Enable the specified warning 2186 -Xclang <arg> Pass <arg> to the clang compiler 2187 2188The /fallback Option 2189^^^^^^^^^^^^^^^^^^^^ 2190 2191When clang-cl is run with the ``/fallback`` option, it will first try to 2192compile files itself. For any file that it fails to compile, it will fall back 2193and try to compile the file by invoking cl.exe. 2194 2195This option is intended to be used as a temporary means to build projects where 2196clang-cl cannot successfully compile all the files. clang-cl may fail to compile 2197a file either because it cannot generate code for some C++ feature, or because 2198it cannot parse some Microsoft language extension. 2199