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 C99 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 warnings. 116 117.. option:: -Weverything 118 119 :ref:`Enable all warnings. <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 :option:`-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 :option:`-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 by another program 152that wants to parse simple and consistent output, not a person. 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**-f[no-]diagnostics-show-name** 269 Enable the display of the diagnostic name. 270 This option, which defaults to off, controls whether or not Clang 271 prints the associated name. 272 273.. _opt_fdiagnostics-show-option: 274 275**-f[no-]diagnostics-show-option** 276 Enable ``[-Woption]`` information in diagnostic line. 277 278 This option, which defaults to on, controls whether or not Clang 279 prints the associated :ref:`warning group <cl_diag_warning_groups>` 280 option name when outputting a warning diagnostic. For example, in 281 this output: 282 283 :: 284 285 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] 286 #endif bad 287 ^ 288 // 289 290 Passing **-fno-diagnostics-show-option** will prevent Clang from 291 printing the [:ref:`-Wextra-tokens <opt_Wextra-tokens>`] information in 292 the diagnostic. This information tells you the flag needed to enable 293 or disable the diagnostic, either from the command line or through 294 :ref:`#pragma GCC diagnostic <pragma_GCC_diagnostic>`. 295 296.. _opt_fdiagnostics-show-category: 297 298.. option:: -fdiagnostics-show-category=none/id/name 299 300 Enable printing category information in diagnostic line. 301 302 This option, which defaults to "none", controls whether or not Clang 303 prints the category associated with a diagnostic when emitting it. 304 Each diagnostic may or many not have an associated category, if it 305 has one, it is listed in the diagnostic categorization field of the 306 diagnostic line (in the []'s). 307 308 For example, a format string warning will produce these three 309 renditions based on the setting of this option: 310 311 :: 312 313 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat] 314 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1] 315 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String] 316 317 This category can be used by clients that want to group diagnostics 318 by category, so it should be a high level category. We want dozens 319 of these, not hundreds or thousands of them. 320 321.. _opt_fdiagnostics-fixit-info: 322 323**-f[no-]diagnostics-fixit-info** 324 Enable "FixIt" information in the diagnostics output. 325 326 This option, which defaults to on, controls whether or not Clang 327 prints the information on how to fix a specific diagnostic 328 underneath it when it knows. For example, in this output: 329 330 :: 331 332 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] 333 #endif bad 334 ^ 335 // 336 337 Passing **-fno-diagnostics-fixit-info** will prevent Clang from 338 printing the "//" line at the end of the message. This information 339 is useful for users who may not understand what is wrong, but can be 340 confusing for machine parsing. 341 342.. _opt_fdiagnostics-print-source-range-info: 343 344**-fdiagnostics-print-source-range-info** 345 Print machine parsable information about source ranges. 346 This option makes Clang print information about source ranges in a machine 347 parsable format after the file/line/column number information. The 348 information is a simple sequence of brace enclosed ranges, where each range 349 lists the start and end line/column locations. For example, in this output: 350 351 :: 352 353 exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float') 354 P = (P-42) + Gamma*4; 355 ~~~~~~ ^ ~~~~~~~ 356 357 The {}'s are generated by -fdiagnostics-print-source-range-info. 358 359 The printed column numbers count bytes from the beginning of the 360 line; take care if your source contains multibyte characters. 361 362.. option:: -fdiagnostics-parseable-fixits 363 364 Print Fix-Its in a machine parseable form. 365 366 This option makes Clang print available Fix-Its in a machine 367 parseable format at the end of diagnostics. The following example 368 illustrates the format: 369 370 :: 371 372 fix-it:"t.cpp":{7:25-7:29}:"Gamma" 373 374 The range printed is a half-open range, so in this example the 375 characters at column 25 up to but not including column 29 on line 7 376 in t.cpp should be replaced with the string "Gamma". Either the 377 range or the replacement string may be empty (representing strict 378 insertions and strict erasures, respectively). Both the file name 379 and the insertion string escape backslash (as "\\\\"), tabs (as 380 "\\t"), newlines (as "\\n"), double quotes(as "\\"") and 381 non-printable characters (as octal "\\xxx"). 382 383 The printed column numbers count bytes from the beginning of the 384 line; take care if your source contains multibyte characters. 385 386.. option:: -fno-elide-type 387 388 Turns off elision in template type printing. 389 390 The default for template type printing is to elide as many template 391 arguments as possible, removing those which are the same in both 392 template types, leaving only the differences. Adding this flag will 393 print all the template arguments. If supported by the terminal, 394 highlighting will still appear on differing arguments. 395 396 Default: 397 398 :: 399 400 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; 401 402 -fno-elide-type: 403 404 :: 405 406 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; 407 408.. option:: -fdiagnostics-show-template-tree 409 410 Template type diffing prints a text tree. 411 412 For diffing large templated types, this option will cause Clang to 413 display the templates as an indented text tree, one argument per 414 line, with differences marked inline. This is compatible with 415 -fno-elide-type. 416 417 Default: 418 419 :: 420 421 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; 422 423 With :option:`-fdiagnostics-show-template-tree`: 424 425 :: 426 427 t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument; 428 vector< 429 map< 430 [...], 431 map< 432 [float != double], 433 [...]>>> 434 435.. _cl_diag_warning_groups: 436 437Individual Warning Groups 438^^^^^^^^^^^^^^^^^^^^^^^^^ 439 440TODO: Generate this from tblgen. Define one anchor per warning group. 441 442.. _opt_wextra-tokens: 443 444.. option:: -Wextra-tokens 445 446 Warn about excess tokens at the end of a preprocessor directive. 447 448 This option, which defaults to on, enables warnings about extra 449 tokens at the end of preprocessor directives. For example: 450 451 :: 452 453 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] 454 #endif bad 455 ^ 456 457 These extra tokens are not strictly conforming, and are usually best 458 handled by commenting them out. 459 460.. option:: -Wambiguous-member-template 461 462 Warn about unqualified uses of a member template whose name resolves to 463 another template at the location of the use. 464 465 This option, which defaults to on, enables a warning in the 466 following code: 467 468 :: 469 470 template<typename T> struct set{}; 471 template<typename T> struct trait { typedef const T& type; }; 472 struct Value { 473 template<typename T> void set(typename trait<T>::type value) {} 474 }; 475 void foo() { 476 Value v; 477 v.set<double>(3.2); 478 } 479 480 C++ [basic.lookup.classref] requires this to be an error, but, 481 because it's hard to work around, Clang downgrades it to a warning 482 as an extension. 483 484.. option:: -Wbind-to-temporary-copy 485 486 Warn about an unusable copy constructor when binding a reference to a 487 temporary. 488 489 This option, which defaults to on, enables warnings about binding a 490 reference to a temporary when the temporary doesn't have a usable 491 copy constructor. For example: 492 493 :: 494 495 struct NonCopyable { 496 NonCopyable(); 497 private: 498 NonCopyable(const NonCopyable&); 499 }; 500 void foo(const NonCopyable&); 501 void bar() { 502 foo(NonCopyable()); // Disallowed in C++98; allowed in C++11. 503 } 504 505 :: 506 507 struct NonCopyable2 { 508 NonCopyable2(); 509 NonCopyable2(NonCopyable2&); 510 }; 511 void foo(const NonCopyable2&); 512 void bar() { 513 foo(NonCopyable2()); // Disallowed in C++98; allowed in C++11. 514 } 515 516 Note that if ``NonCopyable2::NonCopyable2()`` has a default argument 517 whose instantiation produces a compile error, that error will still 518 be a hard error in C++98 mode even if this warning is turned off. 519 520Options to Control Clang Crash Diagnostics 521------------------------------------------ 522 523As unbelievable as it may sound, Clang does crash from time to time. 524Generally, this only occurs to those living on the `bleeding 525edge <http://llvm.org/releases/download.html#svn>`_. Clang goes to great 526lengths to assist you in filing a bug report. Specifically, Clang 527generates preprocessed source file(s) and associated run script(s) upon 528a crash. These files should be attached to a bug report to ease 529reproducibility of the failure. Below are the command line options to 530control the crash diagnostics. 531 532.. option:: -fno-crash-diagnostics 533 534 Disable auto-generation of preprocessed source files during a clang crash. 535 536The -fno-crash-diagnostics flag can be helpful for speeding the process 537of generating a delta reduced test case. 538 539Language and Target-Independent Features 540======================================== 541 542Controlling Errors and Warnings 543------------------------------- 544 545Clang provides a number of ways to control which code constructs cause 546it to emit errors and warning messages, and how they are displayed to 547the console. 548 549Controlling How Clang Displays Diagnostics 550^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 551 552When Clang emits a diagnostic, it includes rich information in the 553output, and gives you fine-grain control over which information is 554printed. Clang has the ability to print this information, and these are 555the options that control it: 556 557#. A file/line/column indicator that shows exactly where the diagnostic 558 occurs in your code [:ref:`-fshow-column <opt_fshow-column>`, 559 :ref:`-fshow-source-location <opt_fshow-source-location>`]. 560#. A categorization of the diagnostic as a note, warning, error, or 561 fatal error. 562#. A text string that describes what the problem is. 563#. An option that indicates how to control the diagnostic (for 564 diagnostics that support it) 565 [:ref:`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`]. 566#. A :ref:`high-level category <diagnostics_categories>` for the diagnostic 567 for clients that want to group diagnostics by class (for diagnostics 568 that support it) 569 [:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>`]. 570#. The line of source code that the issue occurs on, along with a caret 571 and ranges that indicate the important locations 572 [:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`]. 573#. "FixIt" information, which is a concise explanation of how to fix the 574 problem (when Clang is certain it knows) 575 [:ref:`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`]. 576#. A machine-parsable representation of the ranges involved (off by 577 default) 578 [:ref:`-fdiagnostics-print-source-range-info <opt_fdiagnostics-print-source-range-info>`]. 579 580For more information please see :ref:`Formatting of 581Diagnostics <cl_diag_formatting>`. 582 583Diagnostic Mappings 584^^^^^^^^^^^^^^^^^^^ 585 586All diagnostics are mapped into one of these 5 classes: 587 588- Ignored 589- Note 590- Warning 591- Error 592- Fatal 593 594.. _diagnostics_categories: 595 596Diagnostic Categories 597^^^^^^^^^^^^^^^^^^^^^ 598 599Though not shown by default, diagnostics may each be associated with a 600high-level category. This category is intended to make it possible to 601triage builds that produce a large number of errors or warnings in a 602grouped way. 603 604Categories are not shown by default, but they can be turned on with the 605:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>` option. 606When set to "``name``", the category is printed textually in the 607diagnostic output. When it is set to "``id``", a category number is 608printed. The mapping of category names to category id's can be obtained 609by running '``clang --print-diagnostic-categories``'. 610 611Controlling Diagnostics via Command Line Flags 612^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 613 614TODO: -W flags, -pedantic, etc 615 616.. _pragma_gcc_diagnostic: 617 618Controlling Diagnostics via Pragmas 619^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 620 621Clang can also control what diagnostics are enabled through the use of 622pragmas in the source code. This is useful for turning off specific 623warnings in a section of source code. Clang supports GCC's pragma for 624compatibility with existing source code, as well as several extensions. 625 626The pragma may control any warning that can be used from the command 627line. Warnings may be set to ignored, warning, error, or fatal. The 628following example code will tell Clang or GCC to ignore the -Wall 629warnings: 630 631.. code-block:: c 632 633 #pragma GCC diagnostic ignored "-Wall" 634 635In addition to all of the functionality provided by GCC's pragma, Clang 636also allows you to push and pop the current warning state. This is 637particularly useful when writing a header file that will be compiled by 638other people, because you don't know what warning flags they build with. 639 640In the below example :option:`-Wmultichar` is ignored for only a single line of 641code, after which the diagnostics return to whatever state had previously 642existed. 643 644.. code-block:: c 645 646 #pragma clang diagnostic push 647 #pragma clang diagnostic ignored "-Wmultichar" 648 649 char b = 'df'; // no warning. 650 651 #pragma clang diagnostic pop 652 653The push and pop pragmas will save and restore the full diagnostic state 654of the compiler, regardless of how it was set. That means that it is 655possible to use push and pop around GCC compatible diagnostics and Clang 656will push and pop them appropriately, while GCC will ignore the pushes 657and pops as unknown pragmas. It should be noted that while Clang 658supports the GCC pragma, Clang and GCC do not support the exact same set 659of warnings, so even when using GCC compatible #pragmas there is no 660guarantee that they will have identical behaviour on both compilers. 661 662In addition to controlling warnings and errors generated by the compiler, it is 663possible to generate custom warning and error messages through the following 664pragmas: 665 666.. code-block:: c 667 668 // The following will produce warning messages 669 #pragma message "some diagnostic message" 670 #pragma GCC warning "TODO: replace deprecated feature" 671 672 // The following will produce an error message 673 #pragma GCC error "Not supported" 674 675These pragmas operate similarly to the ``#warning`` and ``#error`` preprocessor 676directives, except that they may also be embedded into preprocessor macros via 677the C99 ``_Pragma`` operator, for example: 678 679.. code-block:: c 680 681 #define STR(X) #X 682 #define DEFER(M,...) M(__VA_ARGS__) 683 #define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__)))) 684 685 CUSTOM_ERROR("Feature not available"); 686 687Controlling Diagnostics in System Headers 688^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 689 690Warnings are suppressed when they occur in system headers. By default, 691an included file is treated as a system header if it is found in an 692include path specified by ``-isystem``, but this can be overridden in 693several ways. 694 695The ``system_header`` pragma can be used to mark the current file as 696being a system header. No warnings will be produced from the location of 697the pragma onwards within the same file. 698 699.. code-block:: c 700 701 char a = 'xy'; // warning 702 703 #pragma clang system_header 704 705 char b = 'ab'; // no warning 706 707The :option:`-isystem-prefix` and :option:`-ino-system-prefix` command-line 708arguments can be used to override whether subsets of an include path are 709treated as system headers. When the name in a ``#include`` directive is 710found within a header search path and starts with a system prefix, the 711header is treated as a system header. The last prefix on the 712command-line which matches the specified header name takes precedence. 713For instance: 714 715.. code-block:: console 716 717 $ clang -Ifoo -isystem bar -isystem-prefix x/ -ino-system-prefix x/y/ 718 719Here, ``#include "x/a.h"`` is treated as including a system header, even 720if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated 721as not including a system header, even if the header is found in 722``bar``. 723 724A ``#include`` directive which finds a file relative to the current 725directory is treated as including a system header if the including file 726is treated as a system header. 727 728.. _diagnostics_enable_everything: 729 730Enabling All Warnings 731^^^^^^^^^^^^^^^^^^^^^ 732 733In addition to the traditional ``-W`` flags, one can enable **all** 734warnings by passing :option:`-Weverything`. This works as expected with 735:option:`-Werror`, and also includes the warnings from :option:`-pedantic`. 736 737Note that when combined with :option:`-w` (which disables all warnings), that 738flag wins. 739 740Controlling Static Analyzer Diagnostics 741^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 742 743While not strictly part of the compiler, the diagnostics from Clang's 744`static analyzer <http://clang-analyzer.llvm.org>`_ can also be 745influenced by the user via changes to the source code. See the available 746`annotations <http://clang-analyzer.llvm.org/annotations.html>`_ and the 747analyzer's `FAQ 748page <http://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more 749information. 750 751.. _usersmanual-precompiled-headers: 752 753Precompiled Headers 754------------------- 755 756`Precompiled headers <http://en.wikipedia.org/wiki/Precompiled_header>`__ 757are a general approach employed by many compilers to reduce compilation 758time. The underlying motivation of the approach is that it is common for 759the same (and often large) header files to be included by multiple 760source files. Consequently, compile times can often be greatly improved 761by caching some of the (redundant) work done by a compiler to process 762headers. Precompiled header files, which represent one of many ways to 763implement this optimization, are literally files that represent an 764on-disk cache that contains the vital information necessary to reduce 765some of the work needed to process a corresponding header file. While 766details of precompiled headers vary between compilers, precompiled 767headers have been shown to be highly effective at speeding up program 768compilation on systems with very large system headers (e.g., Mac OS/X). 769 770Generating a PCH File 771^^^^^^^^^^^^^^^^^^^^^ 772 773To generate a PCH file using Clang, one invokes Clang with the 774:option:`-x <language>-header` option. This mirrors the interface in GCC 775for generating PCH files: 776 777.. code-block:: console 778 779 $ gcc -x c-header test.h -o test.h.gch 780 $ clang -x c-header test.h -o test.h.pch 781 782Using a PCH File 783^^^^^^^^^^^^^^^^ 784 785A PCH file can then be used as a prefix header when a :option:`-include` 786option is passed to ``clang``: 787 788.. code-block:: console 789 790 $ clang -include test.h test.c -o test 791 792The ``clang`` driver will first check if a PCH file for ``test.h`` is 793available; if so, the contents of ``test.h`` (and the files it includes) 794will be processed from the PCH file. Otherwise, Clang falls back to 795directly processing the content of ``test.h``. This mirrors the behavior 796of GCC. 797 798.. note:: 799 800 Clang does *not* automatically use PCH files for headers that are directly 801 included within a source file. For example: 802 803 .. code-block:: console 804 805 $ clang -x c-header test.h -o test.h.pch 806 $ cat test.c 807 #include "test.h" 808 $ clang test.c -o test 809 810 In this example, ``clang`` will not automatically use the PCH file for 811 ``test.h`` since ``test.h`` was included directly in the source file and not 812 specified on the command line using :option:`-include`. 813 814Relocatable PCH Files 815^^^^^^^^^^^^^^^^^^^^^ 816 817It is sometimes necessary to build a precompiled header from headers 818that are not yet in their final, installed locations. For example, one 819might build a precompiled header within the build tree that is then 820meant to be installed alongside the headers. Clang permits the creation 821of "relocatable" precompiled headers, which are built with a given path 822(into the build directory) and can later be used from an installed 823location. 824 825To build a relocatable precompiled header, place your headers into a 826subdirectory whose structure mimics the installed location. For example, 827if you want to build a precompiled header for the header ``mylib.h`` 828that will be installed into ``/usr/include``, create a subdirectory 829``build/usr/include`` and place the header ``mylib.h`` into that 830subdirectory. If ``mylib.h`` depends on other headers, then they can be 831stored within ``build/usr/include`` in a way that mimics the installed 832location. 833 834Building a relocatable precompiled header requires two additional 835arguments. First, pass the ``--relocatable-pch`` flag to indicate that 836the resulting PCH file should be relocatable. Second, pass 837:option:`-isysroot /path/to/build`, which makes all includes for your library 838relative to the build directory. For example: 839 840.. code-block:: console 841 842 # clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch 843 844When loading the relocatable PCH file, the various headers used in the 845PCH file are found from the system header root. For example, ``mylib.h`` 846can be found in ``/usr/include/mylib.h``. If the headers are installed 847in some other system root, the :option:`-isysroot` option can be used provide 848a different system root from which the headers will be based. For 849example, :option:`-isysroot /Developer/SDKs/MacOSX10.4u.sdk` will look for 850``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``. 851 852Relocatable precompiled headers are intended to be used in a limited 853number of cases where the compilation environment is tightly controlled 854and the precompiled header cannot be generated after headers have been 855installed. 856 857Controlling Code Generation 858--------------------------- 859 860Clang provides a number of ways to control code generation. The options 861are listed below. 862 863**-f[no-]sanitize=check1,check2,...** 864 Turn on runtime checks for various forms of undefined or suspicious 865 behavior. 866 867 This option controls whether Clang adds runtime checks for various 868 forms of undefined or suspicious behavior, and is disabled by 869 default. If a check fails, a diagnostic message is produced at 870 runtime explaining the problem. The main checks are: 871 872 - .. _opt_fsanitize_address: 873 874 ``-fsanitize=address``: 875 :doc:`AddressSanitizer`, a memory error 876 detector. 877 - ``-fsanitize=init-order``: Make AddressSanitizer check for 878 dynamic initialization order problems. Implied by ``-fsanitize=address``. 879 - ``-fsanitize=address-full``: AddressSanitizer with all the 880 experimental features listed below. 881 - ``-fsanitize=integer``: Enables checks for undefined or 882 suspicious integer behavior. 883 - .. _opt_fsanitize_thread: 884 885 ``-fsanitize=thread``: :doc:`ThreadSanitizer`, a data race detector. 886 - .. _opt_fsanitize_memory: 887 888 ``-fsanitize=memory``: :doc:`MemorySanitizer`, 889 an *experimental* detector of uninitialized reads. Not ready for 890 widespread use. 891 - .. _opt_fsanitize_undefined: 892 893 ``-fsanitize=undefined``: Fast and compatible undefined behavior 894 checker. Enables the undefined behavior checks that have small 895 runtime cost and no impact on address space layout or ABI. This 896 includes all of the checks listed below other than 897 ``unsigned-integer-overflow``. 898 899 - ``-fsanitize=undefined-trap``: This includes all sanitizers 900 included by ``-fsanitize=undefined``, except those that require 901 runtime support. This group of sanitizers is intended to be 902 used in conjunction with the ``-fsanitize-undefined-trap-on-error`` 903 flag. This includes all of the checks listed below other than 904 ``unsigned-integer-overflow`` and ``vptr``. 905 - ``-fsanitize=dataflow``: :doc:`DataFlowSanitizer`, a general data 906 flow analysis. 907 908 The following more fine-grained checks are also available: 909 910 - ``-fsanitize=alignment``: Use of a misaligned pointer or creation 911 of a misaligned reference. 912 - ``-fsanitize=bool``: Load of a ``bool`` value which is neither 913 ``true`` nor ``false``. 914 - ``-fsanitize=bounds``: Out of bounds array indexing, in cases 915 where the array bound can be statically determined. 916 - ``-fsanitize=enum``: Load of a value of an enumerated type which 917 is not in the range of representable values for that enumerated 918 type. 919 - ``-fsanitize=float-cast-overflow``: Conversion to, from, or 920 between floating-point types which would overflow the 921 destination. 922 - ``-fsanitize=float-divide-by-zero``: Floating point division by 923 zero. 924 - ``-fsanitize=function``: Indirect call of a function through a 925 function pointer of the wrong type (Linux, C++ and x86/x86_64 only). 926 - ``-fsanitize=integer-divide-by-zero``: Integer division by zero. 927 - ``-fsanitize=null``: Use of a null pointer or creation of a null 928 reference. 929 - ``-fsanitize=object-size``: An attempt to use bytes which the 930 optimizer can determine are not part of the object being 931 accessed. The sizes of objects are determined using 932 ``__builtin_object_size``, and consequently may be able to detect 933 more problems at higher optimization levels. 934 - ``-fsanitize=return``: In C++, reaching the end of a 935 value-returning function without returning a value. 936 - ``-fsanitize=shift``: Shift operators where the amount shifted is 937 greater or equal to the promoted bit-width of the left hand side 938 or less than zero, or where the left hand side is negative. For a 939 signed left shift, also checks for signed overflow in C, and for 940 unsigned overflow in C++. 941 - ``-fsanitize=signed-integer-overflow``: Signed integer overflow, 942 including all the checks added by ``-ftrapv``, and checking for 943 overflow in signed division (``INT_MIN / -1``). 944 - ``-fsanitize=unreachable``: If control flow reaches 945 ``__builtin_unreachable``. 946 - ``-fsanitize=unsigned-integer-overflow``: Unsigned integer 947 overflows. 948 - ``-fsanitize=vla-bound``: A variable-length array whose bound 949 does not evaluate to a positive value. 950 - ``-fsanitize=vptr``: Use of an object whose vptr indicates that 951 it is of the wrong dynamic type, or that its lifetime has not 952 begun or has ended. Incompatible with ``-fno-rtti``. 953 954 You can turn off or modify checks for certain source files, functions 955 or even variables by providing a special file: 956 957 - ``-fsanitize-blacklist=/path/to/blacklist/file``: disable or modify 958 sanitizer checks for objects listed in the file. See 959 :doc:`SanitizerSpecialCaseList` for file format description. 960 - ``-fno-sanitize-blacklist``: don't use blacklist file, if it was 961 specified earlier in the command line. 962 963 Experimental features of AddressSanitizer (not ready for widespread 964 use, require explicit ``-fsanitize=address``): 965 966 - ``-fsanitize=use-after-return``: Check for use-after-return 967 errors (accessing local variable after the function exit). 968 - ``-fsanitize=use-after-scope``: Check for use-after-scope errors 969 (accesing local variable after it went out of scope). 970 971 Extra features of MemorySanitizer (require explicit 972 ``-fsanitize=memory``): 973 974 - ``-fsanitize-memory-track-origins``: Enables origin tracking in 975 MemorySanitizer. Adds a second section to MemorySanitizer 976 reports pointing to the heap or stack allocation the 977 uninitialized bits came from. Slows down execution by additional 978 1.5x-2x. 979 980 Extra features of UndefinedBehaviorSanitizer: 981 982 - ``-fno-sanitize-recover``: By default, after a sanitizer diagnoses 983 an issue, it will attempt to continue executing the program if there 984 is a reasonable behavior it can give to the faulting operation. This 985 option causes the program to abort instead. 986 - ``-fsanitize-undefined-trap-on-error``: Causes traps to be emitted 987 rather than calls to runtime libraries when a problem is detected. 988 This option is intended for use in cases where the sanitizer runtime 989 cannot be used (for instance, when building libc or a kernel module). 990 This is only compatible with the sanitizers in the ``undefined-trap`` 991 group. 992 993 The ``-fsanitize=`` argument must also be provided when linking, in 994 order to link to the appropriate runtime library. When using 995 ``-fsanitize=vptr`` (or a group that includes it, such as 996 ``-fsanitize=undefined``) with a C++ program, the link must be 997 performed by ``clang++``, not ``clang``, in order to link against the 998 C++-specific parts of the runtime library. 999 1000 It is not possible to combine more than one of the ``-fsanitize=address``, 1001 ``-fsanitize=thread``, and ``-fsanitize=memory`` checkers in the same 1002 program. The ``-fsanitize=undefined`` checks can be combined with other 1003 sanitizers. 1004 1005**-f[no-]address-sanitizer** 1006 Deprecated synonym for :ref:`-f[no-]sanitize=address 1007 <opt_fsanitize_address>`. 1008**-f[no-]thread-sanitizer** 1009 Deprecated synonym for :ref:`-f[no-]sanitize=thread 1010 <opt_fsanitize_thread>`. 1011 1012.. option:: -fcatch-undefined-behavior 1013 1014 Deprecated synonym for :ref:`-fsanitize=undefined 1015 <opt_fsanitize_undefined>`. 1016 1017.. option:: -fno-assume-sane-operator-new 1018 1019 Don't assume that the C++'s new operator is sane. 1020 1021 This option tells the compiler to do not assume that C++'s global 1022 new operator will always return a pointer that does not alias any 1023 other pointer when the function returns. 1024 1025.. option:: -ftrap-function=[name] 1026 1027 Instruct code generator to emit a function call to the specified 1028 function name for ``__builtin_trap()``. 1029 1030 LLVM code generator translates ``__builtin_trap()`` to a trap 1031 instruction if it is supported by the target ISA. Otherwise, the 1032 builtin is translated into a call to ``abort``. If this option is 1033 set, then the code generator will always lower the builtin to a call 1034 to the specified function regardless of whether the target ISA has a 1035 trap instruction. This option is useful for environments (e.g. 1036 deeply embedded) where a trap cannot be properly handled, or when 1037 some custom behavior is desired. 1038 1039.. option:: -ftls-model=[model] 1040 1041 Select which TLS model to use. 1042 1043 Valid values are: ``global-dynamic``, ``local-dynamic``, 1044 ``initial-exec`` and ``local-exec``. The default value is 1045 ``global-dynamic``. The compiler may use a different model if the 1046 selected model is not supported by the target, or if a more 1047 efficient model can be used. The TLS model can be overridden per 1048 variable using the ``tls_model`` attribute. 1049 1050.. option:: -mhwdiv=[values] 1051 1052 Select the ARM modes (arm or thumb) that support hardware division 1053 instructions. 1054 1055 Valid values are: ``arm``, ``thumb`` and ``arm,thumb``. 1056 This option is used to indicate which mode (arm or thumb) supports 1057 hardware division instructions. This only applies to the ARM 1058 architecture. 1059 1060.. option:: -m[no-]crc 1061 1062 Enable or disable CRC instructions. 1063 1064 This option is used to indicate whether CRC instructions are to 1065 be generated. This only applies to the ARM architecture. 1066 1067 CRC instructions are enabled by default on ARMv8. 1068 1069 1070Controlling Size of Debug Information 1071------------------------------------- 1072 1073Debug info kind generated by Clang can be set by one of the flags listed 1074below. If multiple flags are present, the last one is used. 1075 1076.. option:: -g0 1077 1078 Don't generate any debug info (default). 1079 1080.. option:: -gline-tables-only 1081 1082 Generate line number tables only. 1083 1084 This kind of debug info allows to obtain stack traces with function names, 1085 file names and line numbers (by such tools as ``gdb`` or ``addr2line``). It 1086 doesn't contain any other data (e.g. description of local variables or 1087 function parameters). 1088 1089.. option:: -g 1090 1091 Generate complete debug info. 1092 1093Comment Parsing Options 1094-------------------------- 1095 1096Clang parses Doxygen and non-Doxygen style documentation comments and attaches 1097them to the appropriate declaration nodes. By default, it only parses 1098Doxygen-style comments and ignores ordinary comments starting with ``//`` and 1099``/*``. 1100 1101.. option:: -fparse-all-comments 1102 1103 Parse all comments as documentation comments (including ordinary comments 1104 starting with ``//`` and ``/*``). 1105 1106.. _c: 1107 1108C Language Features 1109=================== 1110 1111The support for standard C in clang is feature-complete except for the 1112C99 floating-point pragmas. 1113 1114Extensions supported by clang 1115----------------------------- 1116 1117See :doc:`LanguageExtensions`. 1118 1119Differences between various standard modes 1120------------------------------------------ 1121 1122clang supports the -std option, which changes what language mode clang 1123uses. The supported modes for C are c89, gnu89, c94, c99, gnu99 and 1124various aliases for those modes. If no -std option is specified, clang 1125defaults to gnu99 mode. 1126 1127Differences between all ``c*`` and ``gnu*`` modes: 1128 1129- ``c*`` modes define "``__STRICT_ANSI__``". 1130- Target-specific defines not prefixed by underscores, like "linux", 1131 are defined in ``gnu*`` modes. 1132- Trigraphs default to being off in ``gnu*`` modes; they can be enabled by 1133 the -trigraphs option. 1134- The parser recognizes "asm" and "typeof" as keywords in ``gnu*`` modes; 1135 the variants "``__asm__``" and "``__typeof__``" are recognized in all 1136 modes. 1137- The Apple "blocks" extension is recognized by default in ``gnu*`` modes 1138 on some platforms; it can be enabled in any mode with the "-fblocks" 1139 option. 1140- Arrays that are VLA's according to the standard, but which can be 1141 constant folded by the frontend are treated as fixed size arrays. 1142 This occurs for things like "int X[(1, 2)];", which is technically a 1143 VLA. ``c*`` modes are strictly compliant and treat these as VLAs. 1144 1145Differences between ``*89`` and ``*99`` modes: 1146 1147- The ``*99`` modes default to implementing "inline" as specified in C99, 1148 while the ``*89`` modes implement the GNU version. This can be 1149 overridden for individual functions with the ``__gnu_inline__`` 1150 attribute. 1151- Digraphs are not recognized in c89 mode. 1152- The scope of names defined inside a "for", "if", "switch", "while", 1153 or "do" statement is different. (example: "``if ((struct x {int 1154 x;}*)0) {}``".) 1155- ``__STDC_VERSION__`` is not defined in ``*89`` modes. 1156- "inline" is not recognized as a keyword in c89 mode. 1157- "restrict" is not recognized as a keyword in ``*89`` modes. 1158- Commas are allowed in integer constant expressions in ``*99`` modes. 1159- Arrays which are not lvalues are not implicitly promoted to pointers 1160 in ``*89`` modes. 1161- Some warnings are different. 1162 1163c94 mode is identical to c89 mode except that digraphs are enabled in 1164c94 mode (FIXME: And ``__STDC_VERSION__`` should be defined!). 1165 1166GCC extensions not implemented yet 1167---------------------------------- 1168 1169clang tries to be compatible with gcc as much as possible, but some gcc 1170extensions are not implemented yet: 1171 1172- clang does not support #pragma weak (`bug 1173 3679 <http://llvm.org/bugs/show_bug.cgi?id=3679>`_). Due to the uses 1174 described in the bug, this is likely to be implemented at some point, 1175 at least partially. 1176- clang does not support decimal floating point types (``_Decimal32`` and 1177 friends) or fixed-point types (``_Fract`` and friends); nobody has 1178 expressed interest in these features yet, so it's hard to say when 1179 they will be implemented. 1180- clang does not support nested functions; this is a complex feature 1181 which is infrequently used, so it is unlikely to be implemented 1182 anytime soon. In C++11 it can be emulated by assigning lambda 1183 functions to local variables, e.g: 1184 1185 .. code-block:: cpp 1186 1187 auto const local_function = [&](int parameter) { 1188 // Do something 1189 }; 1190 ... 1191 local_function(1); 1192 1193- clang does not support global register variables; this is unlikely to 1194 be implemented soon because it requires additional LLVM backend 1195 support. 1196- clang does not support static initialization of flexible array 1197 members. This appears to be a rarely used extension, but could be 1198 implemented pending user demand. 1199- clang does not support 1200 ``__builtin_va_arg_pack``/``__builtin_va_arg_pack_len``. This is 1201 used rarely, but in some potentially interesting places, like the 1202 glibc headers, so it may be implemented pending user demand. Note 1203 that because clang pretends to be like GCC 4.2, and this extension 1204 was introduced in 4.3, the glibc headers will not try to use this 1205 extension with clang at the moment. 1206- clang does not support the gcc extension for forward-declaring 1207 function parameters; this has not shown up in any real-world code 1208 yet, though, so it might never be implemented. 1209 1210This is not a complete list; if you find an unsupported extension 1211missing from this list, please send an e-mail to cfe-dev. This list 1212currently excludes C++; see :ref:`C++ Language Features <cxx>`. Also, this 1213list does not include bugs in mostly-implemented features; please see 1214the `bug 1215tracker <http://llvm.org/bugs/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer>`_ 1216for known existing bugs (FIXME: Is there a section for bug-reporting 1217guidelines somewhere?). 1218 1219Intentionally unsupported GCC extensions 1220---------------------------------------- 1221 1222- clang does not support the gcc extension that allows variable-length 1223 arrays in structures. This is for a few reasons: one, it is tricky to 1224 implement, two, the extension is completely undocumented, and three, 1225 the extension appears to be rarely used. Note that clang *does* 1226 support flexible array members (arrays with a zero or unspecified 1227 size at the end of a structure). 1228- clang does not have an equivalent to gcc's "fold"; this means that 1229 clang doesn't accept some constructs gcc might accept in contexts 1230 where a constant expression is required, like "x-x" where x is a 1231 variable. 1232- clang does not support ``__builtin_apply`` and friends; this extension 1233 is extremely obscure and difficult to implement reliably. 1234 1235.. _c_ms: 1236 1237Microsoft extensions 1238-------------------- 1239 1240clang has some experimental support for extensions from Microsoft Visual 1241C++; to enable it, use the -fms-extensions command-line option. This is 1242the default for Windows targets. Note that the support is incomplete. 1243Some constructs such as dllexport on classes are ignored with a warning, 1244and others such as `Microsoft IDL annotations 1245<http://msdn.microsoft.com/en-us/library/8tesw2eh.aspx>`_ are silently 1246ignored. 1247 1248clang has a -fms-compatibility flag that makes clang accept enough 1249invalid C++ to be able to parse most Microsoft headers. For example, it 1250allows `unqualified lookup of dependent base class members 1251<http://clang.llvm.org/compatibility.html#dep_lookup_bases>`_, which is 1252a common compatibility issue with clang. This flag is enabled by default 1253for Windows targets. 1254 1255-fdelayed-template-parsing lets clang delay all template instantiation 1256until the end of a translation unit. This flag is enabled by default for 1257Windows targets. 1258 1259- clang allows setting ``_MSC_VER`` with ``-fmsc-version=``. It defaults to 1260 1700 which is the same as Visual C/C++ 2012. Any number is supported 1261 and can greatly affect what Windows SDK and c++stdlib headers clang 1262 can compile. 1263- clang does not support the Microsoft extension where anonymous record 1264 members can be declared using user defined typedefs. 1265- clang supports the Microsoft ``#pragma pack`` feature for controlling 1266 record layout. GCC also contains support for this feature, however 1267 where MSVC and GCC are incompatible clang follows the MSVC 1268 definition. 1269- clang supports the Microsoft ``#pragma comment(lib, "foo.lib")`` feature for 1270 automatically linking against the specified library. Currently this feature 1271 only works with the Visual C++ linker. 1272- clang supports the Microsoft ``#pragma comment(linker, "/flag:foo")`` feature 1273 for adding linker flags to COFF object files. The user is responsible for 1274 ensuring that the linker understands the flags. 1275- clang defaults to C++11 for Windows targets. 1276 1277.. _cxx: 1278 1279C++ Language Features 1280===================== 1281 1282clang fully implements all of standard C++98 except for exported 1283templates (which were removed in C++11), and `many C++11 1284features <http://clang.llvm.org/cxx_status.html>`_ are also implemented. 1285 1286Controlling implementation limits 1287--------------------------------- 1288 1289.. option:: -fbracket-depth=N 1290 1291 Sets the limit for nested parentheses, brackets, and braces to N. The 1292 default is 256. 1293 1294.. option:: -fconstexpr-depth=N 1295 1296 Sets the limit for recursive constexpr function invocations to N. The 1297 default is 512. 1298 1299.. option:: -ftemplate-depth=N 1300 1301 Sets the limit for recursively nested template instantiations to N. The 1302 default is 256. 1303 1304.. option:: -foperator-arrow-depth=N 1305 1306 Sets the limit for iterative calls to 'operator->' functions to N. The 1307 default is 256. 1308 1309.. _objc: 1310 1311Objective-C Language Features 1312============================= 1313 1314.. _objcxx: 1315 1316Objective-C++ Language Features 1317=============================== 1318 1319 1320.. _target_features: 1321 1322Target-Specific Features and Limitations 1323======================================== 1324 1325CPU Architectures Features and Limitations 1326------------------------------------------ 1327 1328X86 1329^^^ 1330 1331The support for X86 (both 32-bit and 64-bit) is considered stable on 1332Darwin (Mac OS/X), Linux, FreeBSD, and Dragonfly BSD: it has been tested 1333to correctly compile many large C, C++, Objective-C, and Objective-C++ 1334codebases. 1335 1336On ``x86_64-mingw32``, passing i128(by value) is incompatible to Microsoft 1337x64 calling conversion. You might need to tweak 1338``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp. 1339 1340ARM 1341^^^ 1342 1343The support for ARM (specifically ARMv6 and ARMv7) is considered stable 1344on Darwin (iOS): it has been tested to correctly compile many large C, 1345C++, Objective-C, and Objective-C++ codebases. Clang only supports a 1346limited number of ARM architectures. It does not yet fully support 1347ARMv5, for example. 1348 1349PowerPC 1350^^^^^^^ 1351 1352The support for PowerPC (especially PowerPC64) is considered stable 1353on Linux and FreeBSD: it has been tested to correctly compile many 1354large C and C++ codebases. PowerPC (32bit) is still missing certain 1355features (e.g. PIC code on ELF platforms). 1356 1357Other platforms 1358^^^^^^^^^^^^^^^ 1359 1360clang currently contains some support for other architectures (e.g. Sparc); 1361however, significant pieces of code generation are still missing, and they 1362haven't undergone significant testing. 1363 1364clang contains limited support for the MSP430 embedded processor, but 1365both the clang support and the LLVM backend support are highly 1366experimental. 1367 1368Other platforms are completely unsupported at the moment. Adding the 1369minimal support needed for parsing and semantic analysis on a new 1370platform is quite easy; see ``lib/Basic/Targets.cpp`` in the clang source 1371tree. This level of support is also sufficient for conversion to LLVM IR 1372for simple programs. Proper support for conversion to LLVM IR requires 1373adding code to ``lib/CodeGen/CGCall.cpp`` at the moment; this is likely to 1374change soon, though. Generating assembly requires a suitable LLVM 1375backend. 1376 1377Operating System Features and Limitations 1378----------------------------------------- 1379 1380Darwin (Mac OS/X) 1381^^^^^^^^^^^^^^^^^ 1382 1383None 1384 1385Windows 1386^^^^^^^ 1387 1388Experimental supports are on Cygming. 1389 1390See also :ref:`Microsoft Extensions <c_ms>`. 1391 1392Cygwin 1393"""""" 1394 1395Clang works on Cygwin-1.7. 1396 1397MinGW32 1398""""""" 1399 1400Clang works on some mingw32 distributions. Clang assumes directories as 1401below; 1402 1403- ``C:/mingw/include`` 1404- ``C:/mingw/lib`` 1405- ``C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++`` 1406 1407On MSYS, a few tests might fail. 1408 1409MinGW-w64 1410""""""""" 1411 1412For 32-bit (i686-w64-mingw32), and 64-bit (x86\_64-w64-mingw32), Clang 1413assumes as below; 1414 1415- ``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)`` 1416- ``some_directory/bin/gcc.exe`` 1417- ``some_directory/bin/clang.exe`` 1418- ``some_directory/bin/clang++.exe`` 1419- ``some_directory/bin/../include/c++/GCC_version`` 1420- ``some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32`` 1421- ``some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32`` 1422- ``some_directory/bin/../include/c++/GCC_version/backward`` 1423- ``some_directory/bin/../x86_64-w64-mingw32/include`` 1424- ``some_directory/bin/../i686-w64-mingw32/include`` 1425- ``some_directory/bin/../include`` 1426 1427This directory layout is standard for any toolchain you will find on the 1428official `MinGW-w64 website <http://mingw-w64.sourceforge.net>`_. 1429 1430Clang expects the GCC executable "gcc.exe" compiled for 1431``i686-w64-mingw32`` (or ``x86_64-w64-mingw32``) to be present on PATH. 1432 1433`Some tests might fail <http://llvm.org/bugs/show_bug.cgi?id=9072>`_ on 1434``x86_64-w64-mingw32``. 1435 1436.. _clang-cl: 1437 1438clang-cl 1439======== 1440 1441clang-cl is an alternative command-line interface to Clang driver, designed for 1442compatibility with the Visual C++ compiler, cl.exe. 1443 1444To enable clang-cl to find system headers, libraries, and the linker when run 1445from the command-line, it should be executed inside a Visual Studio Native Tools 1446Command Prompt or a regular Command Prompt where the environment has been set 1447up using e.g. `vcvars32.bat <http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_. 1448 1449clang-cl can also be used from inside Visual Studio by using an LLVM Platform 1450Toolset. 1451 1452Command-Line Options 1453-------------------- 1454 1455To be compatible with cl.exe, clang-cl supports most of the same command-line 1456options. Those options can start with either ``/`` or ``-``. It also supports 1457some of Clang's core options, such as the ``-W`` options. 1458 1459Options that are known to clang-cl, but not currently supported, are ignored 1460with a warning. For example: 1461 1462 :: 1463 1464 clang-cl.exe: warning: argument unused during compilation: '/Zi' 1465 1466To suppress warnings about unused arguments, use the ``-Qunused-arguments`` option. 1467 1468Options that are not known to clang-cl will cause errors. If they are spelled with a 1469leading ``/``, they will be mistaken for a filename: 1470 1471 :: 1472 1473 clang-cl.exe: error: no such file or directory: '/foobar' 1474 1475Please `file a bug <http://llvm.org/bugs/enter_bug.cgi?product=clang&component=Driver>`_ 1476for any valid cl.exe flags that clang-cl does not understand. 1477 1478Execute ``clang-cl /?`` to see a list of supported options: 1479 1480 :: 1481 1482 /? Display available options 1483 /c Compile only 1484 /D <macro[=value]> Define macro 1485 /fallback Fall back to cl.exe if clang-cl fails to compile 1486 /FA Output assembly code file during compilation 1487 /Fa<file or directory> Output assembly code to this file during compilation 1488 /Fe<file or directory> Set output executable file or directory (ends in / or \) 1489 /FI<value> Include file before parsing 1490 /Fo<file or directory> Set output object file, or directory (ends in / or \) 1491 /GF- Disable string pooling 1492 /GR- Disable RTTI 1493 /GR Enable RTTI 1494 /help Display available options 1495 /I <dir> Add directory to include search path 1496 /J Make char type unsigned 1497 /LDd Create debug DLL 1498 /LD Create DLL 1499 /link <options> Forward options to the linker 1500 /MDd Use DLL debug run-time 1501 /MD Use DLL run-time 1502 /MTd Use static debug run-time 1503 /MT Use static run-time 1504 /Ob0 Disable inlining 1505 /Od Disable optimization 1506 /Oi- Disable use of builtin functions 1507 /Oi Enable use of builtin functions 1508 /Os Optimize for size 1509 /Ot Optimize for speed 1510 /Ox Maximum optimization 1511 /Oy- Disable frame pointer omission 1512 /Oy Enable frame pointer omission 1513 /O<n> Optimization level 1514 /P Only run the preprocessor 1515 /showIncludes Print info about included files to stderr 1516 /TC Treat all source files as C 1517 /Tc <filename> Specify a C source file 1518 /TP Treat all source files as C++ 1519 /Tp <filename> Specify a C++ source file 1520 /U <macro> Undefine macro 1521 /W0 Disable all warnings 1522 /W1 Enable -Wall 1523 /W2 Enable -Wall 1524 /W3 Enable -Wall 1525 /W4 Enable -Wall 1526 /Wall Enable -Wall 1527 /WX- Do not treat warnings as errors 1528 /WX Treat warnings as errors 1529 /w Disable all warnings 1530 /Zs Syntax-check only 1531 1532The /fallback Option 1533^^^^^^^^^^^^^^^^^^^^ 1534 1535When clang-cl is run with the ``/fallback`` option, it will first try to 1536compile files itself. For any file that it fails to compile, it will fall back 1537and try to compile the file by invoking cl.exe. 1538 1539This option is intended to be used as a temporary means to build projects where 1540clang-cl cannot successfully compile all the files. clang-cl may fail to compile 1541a file either because it cannot generate code for some C++ feature, or because 1542it cannot parse some Microsoft language extension. 1543