1 ============================
2 Clang Compiler User's Manual
3 ============================
11 The Clang Compiler is an open-source compiler for the C family of
12 programming languages, aiming to be the best in class implementation of
13 these languages. Clang builds on the LLVM optimizer and code generator,
14 allowing it to provide high-quality optimization and code generation
15 support for many targets. For more general information, please see the
16 `Clang Web Site <http://clang.llvm.org>`_ or the `LLVM Web
17 Site <http://llvm.org>`_.
19 This document describes important notes about using Clang as a compiler
20 for an end-user, documenting the supported features, command line
21 options, etc. If you are interested in using Clang to build a tool that
22 processes code, please see :doc:`InternalsManual`. If you are interested in the
23 `Clang Static Analyzer <http://clang-analyzer.llvm.org>`_, please see its web
26 Clang is designed to support the C family of programming languages,
27 which 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
29 language-specific information, please see the corresponding language
32 - :ref:`C Language <c>`: K&R C, ANSI C89, ISO C90, ISO C94 (C89+AMD1), ISO
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>`
39 In addition to these base languages and their dialects, Clang supports a
40 broad variety of language extensions, which are documented in the
41 corresponding language section. These extensions are provided to be
42 compatible with the GCC, Microsoft, and other popular compilers as well
43 as to improve functionality through Clang-specific features. The Clang
44 driver and language features are intentionally designed to be as
45 compatible with the GNU GCC compiler as reasonably possible, easing
46 migration from GCC to Clang. In most cases, code "just works".
47 Clang also provides an alternative driver, :ref:`clang-cl`, that is designed
48 to be compatible with the Visual C++ compiler, cl.exe.
50 In addition to language specific features, Clang has a variety of
51 features that depend on what CPU architecture or operating system is
52 being compiled for. Please see the :ref:`Target-Specific Features and
53 Limitations <target_features>` section for more details.
55 The rest of the introduction introduces some basic :ref:`compiler
56 terminology <terminology>` that is used throughout this manual and
57 contains a basic :ref:`introduction to using Clang <basicusage>` as a
58 command line compiler.
65 Front end, parser, backend, preprocessor, undefined behavior,
73 Intro to how to use a C compiler for newbies.
75 compile + link compile then link debug info enabling optimizations
76 picking a language to use, defaults to C99 by default. Autosenses based
77 on extension. using a makefile
82 This section is generally an index into other sections. It does not go
83 into depth on the ones that are covered by other sections. However, the
84 first part introduces the language selection and other high level
85 options like :option:`-c`, :option:`-g`, etc.
87 Options to Control Error and Warning Messages
88 ---------------------------------------------
92 Turn warnings into errors.
94 .. This is in plain monospaced font because it generates the same label as
95 .. -Werror, and Sphinx complains.
99 Turn warning "foo" into an error.
101 .. option:: -Wno-error=foo
103 Turn warning "foo" into an warning even if :option:`-Werror` is specified.
107 Enable warning "foo".
111 Disable warning "foo".
115 Disable all diagnostics.
117 .. option:: -Weverything
119 :ref:`Enable all diagnostics. <diagnostics_enable_everything>`
121 .. option:: -pedantic
123 Warn on language extensions.
125 .. option:: -pedantic-errors
127 Error on language extensions.
129 .. option:: -Wsystem-headers
131 Enable warnings from system headers.
133 .. option:: -ferror-limit=123
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`.
138 .. option:: -ftemplate-backtrace-limit=123
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`.
144 .. _cl_diag_formatting:
146 Formatting of Diagnostics
147 ^^^^^^^^^^^^^^^^^^^^^^^^^
149 Clang aims to produce beautiful diagnostics by default, particularly for
150 new users that first come to Clang. However, different people have
151 different preferences, and sometimes Clang is driven by another program
152 that wants to parse simple and consistent output, not a person. For
153 these cases, Clang provides a wide range of options to control the exact
154 output format of the diagnostics that it generates.
156 .. _opt_fshow-column:
158 **-f[no-]show-column**
159 Print column number in diagnostic.
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:
167 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
172 When this is disabled, Clang will print "test.c:28: warning..." with
175 The printed column numbers count bytes from the beginning of the
176 line; take care if your source contains multibyte characters.
178 .. _opt_fshow-source-location:
180 **-f[no-]show-source-location**
181 Print source file/line/column information in diagnostic.
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:
189 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
194 When this is disabled, Clang will not print the "test.c:28:8: "
197 .. _opt_fcaret-diagnostics:
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
208 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
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.
217 When this option is enabled, Clang will use colors to highlight
218 specific parts of the diagnostic, e.g.,
220 .. nasty hack to not lose our dignity
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>
227 <span style="color:green">^</span>
228 <span style="color:green">//</span>
231 When this is disabled, Clang will just print:
235 test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
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
245 .. option:: -fdiagnostics-format=clang/msvc/vi
247 Changes diagnostic output format to better match IDEs and command line tools.
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:
256 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
261 t.c(3,11) : warning: conversion specifies type 'char *' but the argument has type 'int'
266 t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
268 .. _opt_fdiagnostics-show-option:
270 **-f[no-]diagnostics-show-option**
271 Enable ``[-Woption]`` information in diagnostic line.
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
280 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
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>`.
291 .. _opt_fdiagnostics-show-category:
293 .. option:: -fdiagnostics-show-category=none/id/name
295 Enable printing category information in diagnostic line.
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).
303 For example, a format string warning will produce these three
304 renditions based on the setting of this option:
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]
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.
316 .. _opt_fdiagnostics-fixit-info:
318 **-f[no-]diagnostics-fixit-info**
319 Enable "FixIt" information in the diagnostics output.
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:
327 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
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.
337 .. _opt_fdiagnostics-print-source-range-info:
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:
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;
352 The {}'s are generated by -fdiagnostics-print-source-range-info.
354 The printed column numbers count bytes from the beginning of the
355 line; take care if your source contains multibyte characters.
357 .. option:: -fdiagnostics-parseable-fixits
359 Print Fix-Its in a machine parseable form.
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:
367 fix-it:"t.cpp":{7:25-7:29}:"Gamma"
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").
378 The printed column numbers count bytes from the beginning of the
379 line; take care if your source contains multibyte characters.
381 .. option:: -fno-elide-type
383 Turns off elision in template type printing.
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.
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;
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;
403 .. option:: -fdiagnostics-show-template-tree
405 Template type diffing prints a text tree.
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
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;
418 With :option:`-fdiagnostics-show-template-tree`:
422 t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument;
430 .. _cl_diag_warning_groups:
432 Individual Warning Groups
433 ^^^^^^^^^^^^^^^^^^^^^^^^^
435 TODO: Generate this from tblgen. Define one anchor per warning group.
437 .. _opt_wextra-tokens:
439 .. option:: -Wextra-tokens
441 Warn about excess tokens at the end of a preprocessor directive.
443 This option, which defaults to on, enables warnings about extra
444 tokens at the end of preprocessor directives. For example:
448 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
452 These extra tokens are not strictly conforming, and are usually best
453 handled by commenting them out.
455 .. option:: -Wambiguous-member-template
457 Warn about unqualified uses of a member template whose name resolves to
458 another template at the location of the use.
460 This option, which defaults to on, enables a warning in the
465 template<typename T> struct set{};
466 template<typename T> struct trait { typedef const T& type; };
468 template<typename T> void set(typename trait<T>::type value) {}
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
479 .. option:: -Wbind-to-temporary-copy
481 Warn about an unusable copy constructor when binding a reference to a
484 This option, which defaults to on, enables warnings about binding a
485 reference to a temporary when the temporary doesn't have a usable
486 copy constructor. For example:
493 NonCopyable(const NonCopyable&);
495 void foo(const NonCopyable&);
497 foo(NonCopyable()); // Disallowed in C++98; allowed in C++11.
502 struct NonCopyable2 {
504 NonCopyable2(NonCopyable2&);
506 void foo(const NonCopyable2&);
508 foo(NonCopyable2()); // Disallowed in C++98; allowed in C++11.
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.
515 Options to Control Clang Crash Diagnostics
516 ------------------------------------------
518 As unbelievable as it may sound, Clang does crash from time to time.
519 Generally, this only occurs to those living on the `bleeding
520 edge <http://llvm.org/releases/download.html#svn>`_. Clang goes to great
521 lengths to assist you in filing a bug report. Specifically, Clang
522 generates preprocessed source file(s) and associated run script(s) upon
523 a crash. These files should be attached to a bug report to ease
524 reproducibility of the failure. Below are the command line options to
525 control the crash diagnostics.
527 .. option:: -fno-crash-diagnostics
529 Disable auto-generation of preprocessed source files during a clang crash.
531 The -fno-crash-diagnostics flag can be helpful for speeding the process
532 of generating a delta reduced test case.
534 Options to Emit Optimization Reports
535 ------------------------------------
537 Optimization reports trace, at a high-level, all the major decisions
538 done by compiler transformations. For instance, when the inliner
539 decides to inline function ``foo()`` into ``bar()``, or the loop unroller
540 decides to unroll a loop N times, or the vectorizer decides to
541 vectorize a loop body.
543 Clang offers a family of flags which the optimizers can use to emit
544 a diagnostic in three cases:
546 1. When the pass makes a transformation (:option:`-Rpass`).
548 2. When the pass fails to make a transformation (:option:`-Rpass-missed`).
550 3. When the pass determines whether or not to make a transformation
551 (:option:`-Rpass-analysis`).
553 NOTE: Although the discussion below focuses on :option:`-Rpass`, the exact
554 same options apply to :option:`-Rpass-missed` and :option:`-Rpass-analysis`.
556 Since there are dozens of passes inside the compiler, each of these flags
557 take a regular expression that identifies the name of the pass which should
558 emit the associated diagnostic. For example, to get a report from the inliner,
559 compile the code with:
561 .. code-block:: console
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); }
568 Note that remarks from the inliner are identified with `[-Rpass=inline]`.
569 To request a report from every optimization pass, you should use
570 :option:`-Rpass=.*` (in fact, you can use any valid POSIX regular
571 expression). However, do not expect a report from every transformation
572 made by the compiler. Optimization remarks do not really make sense
573 outside of the major transformations (e.g., inlining, vectorization,
574 loop optimizations) and not every optimization pass supports this
580 1. For :option:`-Rpass` to provide source location information, you
581 need to enable debug line tables and column information. That is,
582 you need to add :option:`-gmlt` (or any of the debug-generating
583 flags) and :option:`-gcolumn-info`. If you omit these options,
584 every remark will be accompanied by a note stating that line number
585 information is missing.
587 2. Optimization remarks that refer to function names will display the
588 mangled name of the function. Since these remarks are emitted by the
589 back end of the compiler, it does not know anything about the input
590 language, nor its mangling rules.
592 3. Some source locations are not displayed correctly. The front end has
593 a more detailed source location tracking than the locations included
594 in the debug info (e.g., the front end can locate code inside macro
595 expansions). However, the locations used by :option:`-Rpass` are
596 translated from debug annotations. That translation can be lossy,
597 which results in some remarks having no location information.
600 Language and Target-Independent Features
601 ========================================
603 Controlling Errors and Warnings
604 -------------------------------
606 Clang provides a number of ways to control which code constructs cause
607 it to emit errors and warning messages, and how they are displayed to
610 Controlling How Clang Displays Diagnostics
611 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
613 When Clang emits a diagnostic, it includes rich information in the
614 output, and gives you fine-grain control over which information is
615 printed. Clang has the ability to print this information, and these are
616 the options that control it:
618 #. A file/line/column indicator that shows exactly where the diagnostic
619 occurs in your code [:ref:`-fshow-column <opt_fshow-column>`,
620 :ref:`-fshow-source-location <opt_fshow-source-location>`].
621 #. A categorization of the diagnostic as a note, warning, error, or
623 #. A text string that describes what the problem is.
624 #. An option that indicates how to control the diagnostic (for
625 diagnostics that support it)
626 [:ref:`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`].
627 #. A :ref:`high-level category <diagnostics_categories>` for the diagnostic
628 for clients that want to group diagnostics by class (for diagnostics
630 [:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>`].
631 #. The line of source code that the issue occurs on, along with a caret
632 and ranges that indicate the important locations
633 [:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`].
634 #. "FixIt" information, which is a concise explanation of how to fix the
635 problem (when Clang is certain it knows)
636 [:ref:`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`].
637 #. A machine-parsable representation of the ranges involved (off by
639 [:ref:`-fdiagnostics-print-source-range-info <opt_fdiagnostics-print-source-range-info>`].
641 For more information please see :ref:`Formatting of
642 Diagnostics <cl_diag_formatting>`.
647 All diagnostics are mapped into one of these 5 classes:
656 .. _diagnostics_categories:
658 Diagnostic Categories
659 ^^^^^^^^^^^^^^^^^^^^^
661 Though not shown by default, diagnostics may each be associated with a
662 high-level category. This category is intended to make it possible to
663 triage builds that produce a large number of errors or warnings in a
666 Categories are not shown by default, but they can be turned on with the
667 :ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>` option.
668 When set to "``name``", the category is printed textually in the
669 diagnostic output. When it is set to "``id``", a category number is
670 printed. The mapping of category names to category id's can be obtained
671 by running '``clang --print-diagnostic-categories``'.
673 Controlling Diagnostics via Command Line Flags
674 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
676 TODO: -W flags, -pedantic, etc
678 .. _pragma_gcc_diagnostic:
680 Controlling Diagnostics via Pragmas
681 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
683 Clang can also control what diagnostics are enabled through the use of
684 pragmas in the source code. This is useful for turning off specific
685 warnings in a section of source code. Clang supports GCC's pragma for
686 compatibility with existing source code, as well as several extensions.
688 The pragma may control any warning that can be used from the command
689 line. Warnings may be set to ignored, warning, error, or fatal. The
690 following example code will tell Clang or GCC to ignore the -Wall
695 #pragma GCC diagnostic ignored "-Wall"
697 In addition to all of the functionality provided by GCC's pragma, Clang
698 also allows you to push and pop the current warning state. This is
699 particularly useful when writing a header file that will be compiled by
700 other people, because you don't know what warning flags they build with.
702 In the below example :option:`-Wmultichar` is ignored for only a single line of
703 code, after which the diagnostics return to whatever state had previously
708 #pragma clang diagnostic push
709 #pragma clang diagnostic ignored "-Wmultichar"
711 char b = 'df'; // no warning.
713 #pragma clang diagnostic pop
715 The push and pop pragmas will save and restore the full diagnostic state
716 of the compiler, regardless of how it was set. That means that it is
717 possible to use push and pop around GCC compatible diagnostics and Clang
718 will push and pop them appropriately, while GCC will ignore the pushes
719 and pops as unknown pragmas. It should be noted that while Clang
720 supports the GCC pragma, Clang and GCC do not support the exact same set
721 of warnings, so even when using GCC compatible #pragmas there is no
722 guarantee that they will have identical behaviour on both compilers.
724 In addition to controlling warnings and errors generated by the compiler, it is
725 possible to generate custom warning and error messages through the following
730 // The following will produce warning messages
731 #pragma message "some diagnostic message"
732 #pragma GCC warning "TODO: replace deprecated feature"
734 // The following will produce an error message
735 #pragma GCC error "Not supported"
737 These pragmas operate similarly to the ``#warning`` and ``#error`` preprocessor
738 directives, except that they may also be embedded into preprocessor macros via
739 the C99 ``_Pragma`` operator, for example:
744 #define DEFER(M,...) M(__VA_ARGS__)
745 #define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__))))
747 CUSTOM_ERROR("Feature not available");
749 Controlling Diagnostics in System Headers
750 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
752 Warnings are suppressed when they occur in system headers. By default,
753 an included file is treated as a system header if it is found in an
754 include path specified by ``-isystem``, but this can be overridden in
757 The ``system_header`` pragma can be used to mark the current file as
758 being a system header. No warnings will be produced from the location of
759 the pragma onwards within the same file.
763 char a = 'xy'; // warning
765 #pragma clang system_header
767 char b = 'ab'; // no warning
769 The :option:`--system-header-prefix=` and :option:`--no-system-header-prefix=`
770 command-line arguments can be used to override whether subsets of an include
771 path are treated as system headers. When the name in a ``#include`` directive
772 is found within a header search path and starts with a system prefix, the
773 header is treated as a system header. The last prefix on the
774 command-line which matches the specified header name takes precedence.
777 .. code-block:: console
779 $ clang -Ifoo -isystem bar --system-header-prefix=x/ \
780 --no-system-header-prefix=x/y/
782 Here, ``#include "x/a.h"`` is treated as including a system header, even
783 if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated
784 as not including a system header, even if the header is found in
787 A ``#include`` directive which finds a file relative to the current
788 directory is treated as including a system header if the including file
789 is treated as a system header.
791 .. _diagnostics_enable_everything:
793 Enabling All Diagnostics
794 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
796 In addition to the traditional ``-W`` flags, one can enable **all**
797 diagnostics by passing :option:`-Weverything`. This works as expected
799 :option:`-Werror`, and also includes the warnings from :option:`-pedantic`.
801 Note that when combined with :option:`-w` (which disables all warnings), that
804 Controlling Static Analyzer Diagnostics
805 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
807 While not strictly part of the compiler, the diagnostics from Clang's
808 `static analyzer <http://clang-analyzer.llvm.org>`_ can also be
809 influenced by the user via changes to the source code. See the available
810 `annotations <http://clang-analyzer.llvm.org/annotations.html>`_ and the
812 page <http://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more
815 .. _usersmanual-precompiled-headers:
820 `Precompiled headers <http://en.wikipedia.org/wiki/Precompiled_header>`__
821 are a general approach employed by many compilers to reduce compilation
822 time. The underlying motivation of the approach is that it is common for
823 the same (and often large) header files to be included by multiple
824 source files. Consequently, compile times can often be greatly improved
825 by caching some of the (redundant) work done by a compiler to process
826 headers. Precompiled header files, which represent one of many ways to
827 implement this optimization, are literally files that represent an
828 on-disk cache that contains the vital information necessary to reduce
829 some of the work needed to process a corresponding header file. While
830 details of precompiled headers vary between compilers, precompiled
831 headers have been shown to be highly effective at speeding up program
832 compilation on systems with very large system headers (e.g., Mac OS X).
834 Generating a PCH File
835 ^^^^^^^^^^^^^^^^^^^^^
837 To generate a PCH file using Clang, one invokes Clang with the
838 :option:`-x <language>-header` option. This mirrors the interface in GCC
839 for generating PCH files:
841 .. code-block:: console
843 $ gcc -x c-header test.h -o test.h.gch
844 $ clang -x c-header test.h -o test.h.pch
849 A PCH file can then be used as a prefix header when a :option:`-include`
850 option is passed to ``clang``:
852 .. code-block:: console
854 $ clang -include test.h test.c -o test
856 The ``clang`` driver will first check if a PCH file for ``test.h`` is
857 available; if so, the contents of ``test.h`` (and the files it includes)
858 will be processed from the PCH file. Otherwise, Clang falls back to
859 directly processing the content of ``test.h``. This mirrors the behavior
864 Clang does *not* automatically use PCH files for headers that are directly
865 included within a source file. For example:
867 .. code-block:: console
869 $ clang -x c-header test.h -o test.h.pch
872 $ clang test.c -o test
874 In this example, ``clang`` will not automatically use the PCH file for
875 ``test.h`` since ``test.h`` was included directly in the source file and not
876 specified on the command line using :option:`-include`.
878 Relocatable PCH Files
879 ^^^^^^^^^^^^^^^^^^^^^
881 It is sometimes necessary to build a precompiled header from headers
882 that are not yet in their final, installed locations. For example, one
883 might build a precompiled header within the build tree that is then
884 meant to be installed alongside the headers. Clang permits the creation
885 of "relocatable" precompiled headers, which are built with a given path
886 (into the build directory) and can later be used from an installed
889 To build a relocatable precompiled header, place your headers into a
890 subdirectory whose structure mimics the installed location. For example,
891 if you want to build a precompiled header for the header ``mylib.h``
892 that will be installed into ``/usr/include``, create a subdirectory
893 ``build/usr/include`` and place the header ``mylib.h`` into that
894 subdirectory. If ``mylib.h`` depends on other headers, then they can be
895 stored within ``build/usr/include`` in a way that mimics the installed
898 Building a relocatable precompiled header requires two additional
899 arguments. First, pass the ``--relocatable-pch`` flag to indicate that
900 the resulting PCH file should be relocatable. Second, pass
901 :option:`-isysroot /path/to/build`, which makes all includes for your library
902 relative to the build directory. For example:
904 .. code-block:: console
906 # clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
908 When loading the relocatable PCH file, the various headers used in the
909 PCH file are found from the system header root. For example, ``mylib.h``
910 can be found in ``/usr/include/mylib.h``. If the headers are installed
911 in some other system root, the :option:`-isysroot` option can be used provide
912 a different system root from which the headers will be based. For
913 example, :option:`-isysroot /Developer/SDKs/MacOSX10.4u.sdk` will look for
914 ``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``.
916 Relocatable precompiled headers are intended to be used in a limited
917 number of cases where the compilation environment is tightly controlled
918 and the precompiled header cannot be generated after headers have been
921 Controlling Code Generation
922 ---------------------------
924 Clang provides a number of ways to control code generation. The options
927 **-f[no-]sanitize=check1,check2,...**
928 Turn on runtime checks for various forms of undefined or suspicious
931 This option controls whether Clang adds runtime checks for various
932 forms of undefined or suspicious behavior, and is disabled by
933 default. If a check fails, a diagnostic message is produced at
934 runtime explaining the problem. The main checks are:
936 - .. _opt_fsanitize_address:
938 ``-fsanitize=address``:
939 :doc:`AddressSanitizer`, a memory error
941 - ``-fsanitize=integer``: Enables checks for undefined or
942 suspicious integer behavior.
943 - .. _opt_fsanitize_thread:
945 ``-fsanitize=thread``: :doc:`ThreadSanitizer`, a data race detector.
946 - .. _opt_fsanitize_memory:
948 ``-fsanitize=memory``: :doc:`MemorySanitizer`,
949 an *experimental* detector of uninitialized reads. Not ready for
951 - .. _opt_fsanitize_undefined:
953 ``-fsanitize=undefined``: Fast and compatible undefined behavior
954 checker. Enables the undefined behavior checks that have small
955 runtime cost and no impact on address space layout or ABI. This
956 includes all of the checks listed below other than
957 ``unsigned-integer-overflow``.
959 - ``-fsanitize=undefined-trap``: This includes all sanitizers
960 included by ``-fsanitize=undefined``, except those that require
961 runtime support. This group of sanitizers is intended to be
962 used in conjunction with the ``-fsanitize-undefined-trap-on-error``
963 flag. This includes all of the checks listed below other than
964 ``unsigned-integer-overflow`` and ``vptr``.
965 - ``-fsanitize=dataflow``: :doc:`DataFlowSanitizer`, a general data
968 The following more fine-grained checks are also available:
970 - ``-fsanitize=alignment``: Use of a misaligned pointer or creation
971 of a misaligned reference.
972 - ``-fsanitize=bool``: Load of a ``bool`` value which is neither
973 ``true`` nor ``false``.
974 - ``-fsanitize=bounds``: Out of bounds array indexing, in cases
975 where the array bound can be statically determined.
976 - ``-fsanitize=enum``: Load of a value of an enumerated type which
977 is not in the range of representable values for that enumerated
979 - ``-fsanitize=float-cast-overflow``: Conversion to, from, or
980 between floating-point types which would overflow the
982 - ``-fsanitize=float-divide-by-zero``: Floating point division by
984 - ``-fsanitize=function``: Indirect call of a function through a
985 function pointer of the wrong type (Linux, C++ and x86/x86_64 only).
986 - ``-fsanitize=integer-divide-by-zero``: Integer division by zero.
987 - ``-fsanitize=null``: Use of a null pointer or creation of a null
989 - ``-fsanitize=object-size``: An attempt to use bytes which the
990 optimizer can determine are not part of the object being
991 accessed. The sizes of objects are determined using
992 ``__builtin_object_size``, and consequently may be able to detect
993 more problems at higher optimization levels.
994 - ``-fsanitize=return``: In C++, reaching the end of a
995 value-returning function without returning a value.
996 - ``-fsanitize=shift``: Shift operators where the amount shifted is
997 greater or equal to the promoted bit-width of the left hand side
998 or less than zero, or where the left hand side is negative. For a
999 signed left shift, also checks for signed overflow in C, and for
1000 unsigned overflow in C++.
1001 - ``-fsanitize=signed-integer-overflow``: Signed integer overflow,
1002 including all the checks added by ``-ftrapv``, and checking for
1003 overflow in signed division (``INT_MIN / -1``).
1004 - ``-fsanitize=unreachable``: If control flow reaches
1005 ``__builtin_unreachable``.
1006 - ``-fsanitize=unsigned-integer-overflow``: Unsigned integer
1008 - ``-fsanitize=vla-bound``: A variable-length array whose bound
1009 does not evaluate to a positive value.
1010 - ``-fsanitize=vptr``: Use of an object whose vptr indicates that
1011 it is of the wrong dynamic type, or that its lifetime has not
1012 begun or has ended. Incompatible with ``-fno-rtti``.
1014 You can turn off or modify checks for certain source files, functions
1015 or even variables by providing a special file:
1017 - ``-fsanitize-blacklist=/path/to/blacklist/file``: disable or modify
1018 sanitizer checks for objects listed in the file. See
1019 :doc:`SanitizerSpecialCaseList` for file format description.
1020 - ``-fno-sanitize-blacklist``: don't use blacklist file, if it was
1021 specified earlier in the command line.
1023 Extra features of MemorySanitizer (require explicit
1024 ``-fsanitize=memory``):
1026 - ``-fsanitize-memory-track-origins[=level]``: Enables origin tracking in
1027 MemorySanitizer. Adds a second section to MemorySanitizer
1028 reports pointing to the heap or stack allocation the
1029 uninitialized bits came from. Slows down execution by additional
1032 Possible values for level are 0 (off), 1 (default), 2. Level 2 adds more
1033 sections to MemorySanitizer reports describing the order of memory stores
1034 the uninitialized value went through. Beware, this mode may use a lot of
1037 Extra features of UndefinedBehaviorSanitizer:
1039 - ``-fno-sanitize-recover``: By default, after a sanitizer diagnoses
1040 an issue, it will attempt to continue executing the program if there
1041 is a reasonable behavior it can give to the faulting operation. This
1042 option causes the program to abort instead.
1043 - ``-fsanitize-undefined-trap-on-error``: Causes traps to be emitted
1044 rather than calls to runtime libraries when a problem is detected.
1045 This option is intended for use in cases where the sanitizer runtime
1046 cannot be used (for instance, when building libc or a kernel module).
1047 This is only compatible with the sanitizers in the ``undefined-trap``
1050 The ``-fsanitize=`` argument must also be provided when linking, in
1051 order to link to the appropriate runtime library. When using
1052 ``-fsanitize=vptr`` (or a group that includes it, such as
1053 ``-fsanitize=undefined``) with a C++ program, the link must be
1054 performed by ``clang++``, not ``clang``, in order to link against the
1055 C++-specific parts of the runtime library.
1057 It is not possible to combine more than one of the ``-fsanitize=address``,
1058 ``-fsanitize=thread``, and ``-fsanitize=memory`` checkers in the same
1059 program. The ``-fsanitize=undefined`` checks can be combined with other
1062 .. option:: -fno-assume-sane-operator-new
1064 Don't assume that the C++'s new operator is sane.
1066 This option tells the compiler to do not assume that C++'s global
1067 new operator will always return a pointer that does not alias any
1068 other pointer when the function returns.
1070 .. option:: -ftrap-function=[name]
1072 Instruct code generator to emit a function call to the specified
1073 function name for ``__builtin_trap()``.
1075 LLVM code generator translates ``__builtin_trap()`` to a trap
1076 instruction if it is supported by the target ISA. Otherwise, the
1077 builtin is translated into a call to ``abort``. If this option is
1078 set, then the code generator will always lower the builtin to a call
1079 to the specified function regardless of whether the target ISA has a
1080 trap instruction. This option is useful for environments (e.g.
1081 deeply embedded) where a trap cannot be properly handled, or when
1082 some custom behavior is desired.
1084 .. option:: -ftls-model=[model]
1086 Select which TLS model to use.
1088 Valid values are: ``global-dynamic``, ``local-dynamic``,
1089 ``initial-exec`` and ``local-exec``. The default value is
1090 ``global-dynamic``. The compiler may use a different model if the
1091 selected model is not supported by the target, or if a more
1092 efficient model can be used. The TLS model can be overridden per
1093 variable using the ``tls_model`` attribute.
1095 .. option:: -mhwdiv=[values]
1097 Select the ARM modes (arm or thumb) that support hardware division
1100 Valid values are: ``arm``, ``thumb`` and ``arm,thumb``.
1101 This option is used to indicate which mode (arm or thumb) supports
1102 hardware division instructions. This only applies to the ARM
1105 .. option:: -m[no-]crc
1107 Enable or disable CRC instructions.
1109 This option is used to indicate whether CRC instructions are to
1110 be generated. This only applies to the ARM architecture.
1112 CRC instructions are enabled by default on ARMv8.
1114 .. option:: -mgeneral-regs-only
1116 Generate code which only uses the general purpose registers.
1118 This option restricts the generated code to use general registers
1119 only. This only applies to the AArch64 architecture.
1122 Using Sampling Profilers for Optimization
1123 -----------------------------------------
1125 Sampling profilers are used to collect runtime information, such as
1126 hardware counters, while your application executes. They are typically
1127 very efficient and do not incur a large runtime overhead. The
1128 sample data collected by the profiler can be used during compilation
1129 to determine what the most executed areas of the code are.
1131 In particular, sample profilers can provide execution counts for all
1132 instructions in the code and information on branches taken and function
1133 invocation. The compiler can use this information in its optimization
1134 cost models. For example, knowing that a branch is taken very
1135 frequently helps the compiler make better decisions when ordering
1136 basic blocks. Knowing that a function ``foo`` is called more
1137 frequently than another function ``bar`` helps the inliner.
1139 Using the data from a sample profiler requires some changes in the way
1140 a program is built. Before the compiler can use profiling information,
1141 the code needs to execute under the profiler. The following is the
1142 usual build cycle when using sample profilers for optimization:
1144 1. Build the code with source line table information. You can use all the
1145 usual build flags that you always build your application with. The only
1146 requirement is that you add ``-gline-tables-only`` or ``-g`` to the
1147 command line. This is important for the profiler to be able to map
1148 instructions back to source line locations.
1150 .. code-block:: console
1152 $ clang++ -O2 -gline-tables-only code.cc -o code
1154 2. Run the executable under a sampling profiler. The specific profiler
1155 you use does not really matter, as long as its output can be converted
1156 into the format that the LLVM optimizer understands. Currently, there
1157 exists a conversion tool for the Linux Perf profiler
1158 (https://perf.wiki.kernel.org/), so these examples assume that you
1159 are using Linux Perf to profile your code.
1161 .. code-block:: console
1163 $ perf record -b ./code
1165 Note the use of the ``-b`` flag. This tells Perf to use the Last Branch
1166 Record (LBR) to record call chains. While this is not strictly required,
1167 it provides better call information, which improves the accuracy of
1170 3. Convert the collected profile data to LLVM's sample profile format.
1171 This is currently supported via the AutoFDO converter ``create_llvm_prof``.
1172 It is available at http://github.com/google/autofdo. Once built and
1173 installed, you can convert the ``perf.data`` file to LLVM using
1176 .. code-block:: console
1178 $ create_llvm_prof --binary=./code --out=code.prof
1180 This will read ``perf.data`` and the binary file ``./code`` and emit
1181 the profile data in ``code.prof``. Note that if you ran ``perf``
1182 without the ``-b`` flag, you need to use ``--use_lbr=false`` when
1183 calling ``create_llvm_prof``.
1185 4. Build the code again using the collected profile. This step feeds
1186 the profile back to the optimizers. This should result in a binary
1187 that executes faster than the original one. Note that you are not
1188 required to build the code with the exact same arguments that you
1189 used in the first step. The only requirement is that you build the code
1190 with ``-gline-tables-only`` and ``-fprofile-sample-use``.
1192 .. code-block:: console
1194 $ clang++ -O2 -gline-tables-only -fprofile-sample-use=code.prof code.cc -o code
1197 Sample Profile Format
1198 ^^^^^^^^^^^^^^^^^^^^^
1200 If you are not using Linux Perf to collect profiles, you will need to
1201 write a conversion tool from your profiler to LLVM's format. This section
1202 explains the file format expected by the backend.
1204 Sample profiles are written as ASCII text. The file is divided into sections,
1205 which correspond to each of the functions executed at runtime. Each
1206 section has the following format (taken from
1207 https://github.com/google/autofdo/blob/master/profile_writer.h):
1209 .. code-block:: console
1211 function1:total_samples:total_head_samples
1212 offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ]
1213 offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ]
1215 offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]
1217 The file may contain blank lines between sections and within a
1218 section. However, the spacing within a single line is fixed. Additional
1219 spaces will result in an error while reading the file.
1221 Function names must be mangled in order for the profile loader to
1222 match them in the current translation unit. The two numbers in the
1223 function header specify how many total samples were accumulated in the
1224 function (first number), and the total number of samples accumulated
1225 in the prologue of the function (second number). This head sample
1226 count provides an indicator of how frequently the function is invoked.
1228 Each sampled line may contain several items. Some are optional (marked
1231 a. Source line offset. This number represents the line number
1232 in the function where the sample was collected. The line number is
1233 always relative to the line where symbol of the function is
1234 defined. So, if the function has its header at line 280, the offset
1235 13 is at line 293 in the file.
1237 Note that this offset should never be a negative number. This could
1238 happen in cases like macros. The debug machinery will register the
1239 line number at the point of macro expansion. So, if the macro was
1240 expanded in a line before the start of the function, the profile
1241 converter should emit a 0 as the offset (this means that the optimizers
1242 will not be able to associate a meaningful weight to the instructions
1245 b. [OPTIONAL] Discriminator. This is used if the sampled program
1246 was compiled with DWARF discriminator support
1247 (http://wiki.dwarfstd.org/index.php?title=Path_Discriminators).
1248 DWARF discriminators are unsigned integer values that allow the
1249 compiler to distinguish between multiple execution paths on the
1250 same source line location.
1252 For example, consider the line of code ``if (cond) foo(); else bar();``.
1253 If the predicate ``cond`` is true 80% of the time, then the edge
1254 into function ``foo`` should be considered to be taken most of the
1255 time. But both calls to ``foo`` and ``bar`` are at the same source
1256 line, so a sample count at that line is not sufficient. The
1257 compiler needs to know which part of that line is taken more
1260 This is what discriminators provide. In this case, the calls to
1261 ``foo`` and ``bar`` will be at the same line, but will have
1262 different discriminator values. This allows the compiler to correctly
1263 set edge weights into ``foo`` and ``bar``.
1265 c. Number of samples. This is an integer quantity representing the
1266 number of samples collected by the profiler at this source
1269 d. [OPTIONAL] Potential call targets and samples. If present, this
1270 line contains a call instruction. This models both direct and
1271 number of samples. For example,
1273 .. code-block:: console
1275 130: 7 foo:3 bar:2 baz:7
1277 The above means that at relative line offset 130 there is a call
1278 instruction that calls one of ``foo()``, ``bar()`` and ``baz()``,
1279 with ``baz()`` being the relatively more frequently called target.
1282 Controlling Size of Debug Information
1283 -------------------------------------
1285 Debug info kind generated by Clang can be set by one of the flags listed
1286 below. If multiple flags are present, the last one is used.
1290 Don't generate any debug info (default).
1292 .. option:: -gline-tables-only
1294 Generate line number tables only.
1296 This kind of debug info allows to obtain stack traces with function names,
1297 file names and line numbers (by such tools as ``gdb`` or ``addr2line``). It
1298 doesn't contain any other data (e.g. description of local variables or
1299 function parameters).
1301 .. option:: -fstandalone-debug **-fno-standalone-debug**
1303 Clang supports a number of optimizations to reduce the size of debug
1304 information in the binary. They work based on the assumption that
1305 the debug type information can be spread out over multiple
1306 compilation units. For instance, Clang will not emit type
1307 definitions for types that are not needed by a module and could be
1308 replaced with a forward declaration. Further, Clang will only emit
1309 type info for a dynamic C++ class in the module that contains the
1310 vtable for the class.
1312 The ``-fstandalone-debug`` option turns off these optimizations.
1313 This is useful when working with 3rd-party libraries that don't come
1314 with debug information. Note that Clang will never emit type
1315 information for types that are not referenced at all by the program.
1319 Generate complete debug info.
1321 Comment Parsing Options
1322 -----------------------
1324 Clang parses Doxygen and non-Doxygen style documentation comments and attaches
1325 them to the appropriate declaration nodes. By default, it only parses
1326 Doxygen-style comments and ignores ordinary comments starting with ``//`` and
1329 .. option:: -Wdocumentation
1331 Emit warnings about use of documentation comments. This warning group is off
1334 This includes checking that ``\param`` commands name parameters that actually
1335 present in the function signature, checking that ``\returns`` is used only on
1336 functions that actually return a value etc.
1338 .. option:: -Wno-documentation-unknown-command
1340 Don't warn when encountering an unknown Doxygen command.
1342 .. option:: -fparse-all-comments
1344 Parse all comments as documentation comments (including ordinary comments
1345 starting with ``//`` and ``/*``).
1347 .. option:: -fcomment-block-commands=[commands]
1349 Define custom documentation commands as block commands. This allows Clang to
1350 construct the correct AST for these custom commands, and silences warnings
1351 about unknown commands. Several commands must be separated by a comma
1352 *without trailing space*; e.g. ``-fcomment-block-commands=foo,bar`` defines
1353 custom commands ``\foo`` and ``\bar``.
1355 It is also possible to use ``-fcomment-block-commands`` several times; e.g.
1356 ``-fcomment-block-commands=foo -fcomment-block-commands=bar`` does the same
1364 The support for standard C in clang is feature-complete except for the
1365 C99 floating-point pragmas.
1367 Extensions supported by clang
1368 -----------------------------
1370 See :doc:`LanguageExtensions`.
1372 Differences between various standard modes
1373 ------------------------------------------
1375 clang supports the -std option, which changes what language mode clang
1376 uses. The supported modes for C are c89, gnu89, c94, c99, gnu99 and
1377 various aliases for those modes. If no -std option is specified, clang
1378 defaults to gnu99 mode.
1380 Differences between all ``c*`` and ``gnu*`` modes:
1382 - ``c*`` modes define "``__STRICT_ANSI__``".
1383 - Target-specific defines not prefixed by underscores, like "linux",
1384 are defined in ``gnu*`` modes.
1385 - Trigraphs default to being off in ``gnu*`` modes; they can be enabled by
1386 the -trigraphs option.
1387 - The parser recognizes "asm" and "typeof" as keywords in ``gnu*`` modes;
1388 the variants "``__asm__``" and "``__typeof__``" are recognized in all
1390 - The Apple "blocks" extension is recognized by default in ``gnu*`` modes
1391 on some platforms; it can be enabled in any mode with the "-fblocks"
1393 - Arrays that are VLA's according to the standard, but which can be
1394 constant folded by the frontend are treated as fixed size arrays.
1395 This occurs for things like "int X[(1, 2)];", which is technically a
1396 VLA. ``c*`` modes are strictly compliant and treat these as VLAs.
1398 Differences between ``*89`` and ``*99`` modes:
1400 - The ``*99`` modes default to implementing "inline" as specified in C99,
1401 while the ``*89`` modes implement the GNU version. This can be
1402 overridden for individual functions with the ``__gnu_inline__``
1404 - Digraphs are not recognized in c89 mode.
1405 - The scope of names defined inside a "for", "if", "switch", "while",
1406 or "do" statement is different. (example: "``if ((struct x {int
1408 - ``__STDC_VERSION__`` is not defined in ``*89`` modes.
1409 - "inline" is not recognized as a keyword in c89 mode.
1410 - "restrict" is not recognized as a keyword in ``*89`` modes.
1411 - Commas are allowed in integer constant expressions in ``*99`` modes.
1412 - Arrays which are not lvalues are not implicitly promoted to pointers
1414 - Some warnings are different.
1416 c94 mode is identical to c89 mode except that digraphs are enabled in
1417 c94 mode (FIXME: And ``__STDC_VERSION__`` should be defined!).
1419 GCC extensions not implemented yet
1420 ----------------------------------
1422 clang tries to be compatible with gcc as much as possible, but some gcc
1423 extensions are not implemented yet:
1425 - clang does not support #pragma weak (`bug
1426 3679 <http://llvm.org/bugs/show_bug.cgi?id=3679>`_). Due to the uses
1427 described in the bug, this is likely to be implemented at some point,
1429 - clang does not support decimal floating point types (``_Decimal32`` and
1430 friends) or fixed-point types (``_Fract`` and friends); nobody has
1431 expressed interest in these features yet, so it's hard to say when
1432 they will be implemented.
1433 - clang does not support nested functions; this is a complex feature
1434 which is infrequently used, so it is unlikely to be implemented
1435 anytime soon. In C++11 it can be emulated by assigning lambda
1436 functions to local variables, e.g:
1440 auto const local_function = [&](int parameter) {
1446 - clang does not support global register variables; this is unlikely to
1447 be implemented soon because it requires additional LLVM backend
1449 - clang does not support static initialization of flexible array
1450 members. This appears to be a rarely used extension, but could be
1451 implemented pending user demand.
1452 - clang does not support
1453 ``__builtin_va_arg_pack``/``__builtin_va_arg_pack_len``. This is
1454 used rarely, but in some potentially interesting places, like the
1455 glibc headers, so it may be implemented pending user demand. Note
1456 that because clang pretends to be like GCC 4.2, and this extension
1457 was introduced in 4.3, the glibc headers will not try to use this
1458 extension with clang at the moment.
1459 - clang does not support the gcc extension for forward-declaring
1460 function parameters; this has not shown up in any real-world code
1461 yet, though, so it might never be implemented.
1463 This is not a complete list; if you find an unsupported extension
1464 missing from this list, please send an e-mail to cfe-dev. This list
1465 currently excludes C++; see :ref:`C++ Language Features <cxx>`. Also, this
1466 list does not include bugs in mostly-implemented features; please see
1468 tracker <http://llvm.org/bugs/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer>`_
1469 for known existing bugs (FIXME: Is there a section for bug-reporting
1470 guidelines somewhere?).
1472 Intentionally unsupported GCC extensions
1473 ----------------------------------------
1475 - clang does not support the gcc extension that allows variable-length
1476 arrays in structures. This is for a few reasons: one, it is tricky to
1477 implement, two, the extension is completely undocumented, and three,
1478 the extension appears to be rarely used. Note that clang *does*
1479 support flexible array members (arrays with a zero or unspecified
1480 size at the end of a structure).
1481 - clang does not have an equivalent to gcc's "fold"; this means that
1482 clang doesn't accept some constructs gcc might accept in contexts
1483 where a constant expression is required, like "x-x" where x is a
1485 - clang does not support ``__builtin_apply`` and friends; this extension
1486 is extremely obscure and difficult to implement reliably.
1490 Microsoft extensions
1491 --------------------
1493 clang has some experimental support for extensions from Microsoft Visual
1494 C++; to enable it, use the ``-fms-extensions`` command-line option. This is
1495 the default for Windows targets. Note that the support is incomplete.
1496 Some constructs such as ``dllexport`` on classes are ignored with a warning,
1497 and others such as `Microsoft IDL annotations
1498 <http://msdn.microsoft.com/en-us/library/8tesw2eh.aspx>`_ are silently
1501 clang has a ``-fms-compatibility`` flag that makes clang accept enough
1502 invalid C++ to be able to parse most Microsoft headers. For example, it
1503 allows `unqualified lookup of dependent base class members
1504 <http://clang.llvm.org/compatibility.html#dep_lookup_bases>`_, which is
1505 a common compatibility issue with clang. This flag is enabled by default
1506 for Windows targets.
1508 ``-fdelayed-template-parsing`` lets clang delay parsing of function template
1509 definitions until the end of a translation unit. This flag is enabled by
1510 default for Windows targets.
1512 - clang allows setting ``_MSC_VER`` with ``-fmsc-version=``. It defaults to
1513 1700 which is the same as Visual C/C++ 2012. Any number is supported
1514 and can greatly affect what Windows SDK and c++stdlib headers clang
1516 - clang does not support the Microsoft extension where anonymous record
1517 members can be declared using user defined typedefs.
1518 - clang supports the Microsoft ``#pragma pack`` feature for controlling
1519 record layout. GCC also contains support for this feature, however
1520 where MSVC and GCC are incompatible clang follows the MSVC
1522 - clang supports the Microsoft ``#pragma comment(lib, "foo.lib")`` feature for
1523 automatically linking against the specified library. Currently this feature
1524 only works with the Visual C++ linker.
1525 - clang supports the Microsoft ``#pragma comment(linker, "/flag:foo")`` feature
1526 for adding linker flags to COFF object files. The user is responsible for
1527 ensuring that the linker understands the flags.
1528 - clang defaults to C++11 for Windows targets.
1532 C++ Language Features
1533 =====================
1535 clang fully implements all of standard C++98 except for exported
1536 templates (which were removed in C++11), and all of standard C++11
1537 and the current draft standard for C++1y.
1539 Controlling implementation limits
1540 ---------------------------------
1542 .. option:: -fbracket-depth=N
1544 Sets the limit for nested parentheses, brackets, and braces to N. The
1547 .. option:: -fconstexpr-depth=N
1549 Sets the limit for recursive constexpr function invocations to N. The
1552 .. option:: -ftemplate-depth=N
1554 Sets the limit for recursively nested template instantiations to N. The
1557 .. option:: -foperator-arrow-depth=N
1559 Sets the limit for iterative calls to 'operator->' functions to N. The
1564 Objective-C Language Features
1565 =============================
1569 Objective-C++ Language Features
1570 ===============================
1573 .. _target_features:
1575 Target-Specific Features and Limitations
1576 ========================================
1578 CPU Architectures Features and Limitations
1579 ------------------------------------------
1584 The support for X86 (both 32-bit and 64-bit) is considered stable on
1585 Darwin (Mac OS X), Linux, FreeBSD, and Dragonfly BSD: it has been tested
1586 to correctly compile many large C, C++, Objective-C, and Objective-C++
1589 On ``x86_64-mingw32``, passing i128(by value) is incompatible with the
1590 Microsoft x64 calling convention. You might need to tweak
1591 ``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp.
1593 For the X86 target, clang supports the :option:`-m16` command line
1594 argument which enables 16-bit code output. This is broadly similar to
1595 using ``asm(".code16gcc")`` with the GNU toolchain. The generated code
1596 and the ABI remains 32-bit but the assembler emits instructions
1597 appropriate for a CPU running in 16-bit mode, with address-size and
1598 operand-size prefixes to enable 32-bit addressing and operations.
1603 The support for ARM (specifically ARMv6 and ARMv7) is considered stable
1604 on Darwin (iOS): it has been tested to correctly compile many large C,
1605 C++, Objective-C, and Objective-C++ codebases. Clang only supports a
1606 limited number of ARM architectures. It does not yet fully support
1612 The support for PowerPC (especially PowerPC64) is considered stable
1613 on Linux and FreeBSD: it has been tested to correctly compile many
1614 large C and C++ codebases. PowerPC (32bit) is still missing certain
1615 features (e.g. PIC code on ELF platforms).
1620 clang currently contains some support for other architectures (e.g. Sparc);
1621 however, significant pieces of code generation are still missing, and they
1622 haven't undergone significant testing.
1624 clang contains limited support for the MSP430 embedded processor, but
1625 both the clang support and the LLVM backend support are highly
1628 Other platforms are completely unsupported at the moment. Adding the
1629 minimal support needed for parsing and semantic analysis on a new
1630 platform is quite easy; see ``lib/Basic/Targets.cpp`` in the clang source
1631 tree. This level of support is also sufficient for conversion to LLVM IR
1632 for simple programs. Proper support for conversion to LLVM IR requires
1633 adding code to ``lib/CodeGen/CGCall.cpp`` at the moment; this is likely to
1634 change soon, though. Generating assembly requires a suitable LLVM
1637 Operating System Features and Limitations
1638 -----------------------------------------
1643 Thread Sanitizer is not supported.
1648 Clang has experimental support for targeting "Cygming" (Cygwin / MinGW)
1651 See also :ref:`Microsoft Extensions <c_ms>`.
1656 Clang works on Cygwin-1.7.
1661 Clang works on some mingw32 distributions. Clang assumes directories as
1664 - ``C:/mingw/include``
1666 - ``C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++``
1668 On MSYS, a few tests might fail.
1673 For 32-bit (i686-w64-mingw32), and 64-bit (x86\_64-w64-mingw32), Clang
1676 - ``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)``
1677 - ``some_directory/bin/gcc.exe``
1678 - ``some_directory/bin/clang.exe``
1679 - ``some_directory/bin/clang++.exe``
1680 - ``some_directory/bin/../include/c++/GCC_version``
1681 - ``some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32``
1682 - ``some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32``
1683 - ``some_directory/bin/../include/c++/GCC_version/backward``
1684 - ``some_directory/bin/../x86_64-w64-mingw32/include``
1685 - ``some_directory/bin/../i686-w64-mingw32/include``
1686 - ``some_directory/bin/../include``
1688 This directory layout is standard for any toolchain you will find on the
1689 official `MinGW-w64 website <http://mingw-w64.sourceforge.net>`_.
1691 Clang expects the GCC executable "gcc.exe" compiled for
1692 ``i686-w64-mingw32`` (or ``x86_64-w64-mingw32``) to be present on PATH.
1694 `Some tests might fail <http://llvm.org/bugs/show_bug.cgi?id=9072>`_ on
1695 ``x86_64-w64-mingw32``.
1702 clang-cl is an alternative command-line interface to Clang driver, designed for
1703 compatibility with the Visual C++ compiler, cl.exe.
1705 To enable clang-cl to find system headers, libraries, and the linker when run
1706 from the command-line, it should be executed inside a Visual Studio Native Tools
1707 Command Prompt or a regular Command Prompt where the environment has been set
1708 up using e.g. `vcvars32.bat <http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_.
1710 clang-cl can also be used from inside Visual Studio by using an LLVM Platform
1713 Command-Line Options
1714 --------------------
1716 To be compatible with cl.exe, clang-cl supports most of the same command-line
1717 options. Those options can start with either ``/`` or ``-``. It also supports
1718 some of Clang's core options, such as the ``-W`` options.
1720 Options that are known to clang-cl, but not currently supported, are ignored
1721 with a warning. For example:
1725 clang-cl.exe: warning: argument unused during compilation: '/Zi'
1727 To suppress warnings about unused arguments, use the ``-Qunused-arguments`` option.
1729 Options that are not known to clang-cl will cause errors. If they are spelled with a
1730 leading ``/``, they will be mistaken for a filename:
1734 clang-cl.exe: error: no such file or directory: '/foobar'
1736 Please `file a bug <http://llvm.org/bugs/enter_bug.cgi?product=clang&component=Driver>`_
1737 for any valid cl.exe flags that clang-cl does not understand.
1739 Execute ``clang-cl /?`` to see a list of supported options:
1743 /? Display available options
1745 /D <macro[=value]> Define macro
1746 /fallback Fall back to cl.exe if clang-cl fails to compile
1747 /FA Output assembly code file during compilation
1748 /Fa<file or directory> Output assembly code to this file during compilation
1749 /Fe<file or directory> Set output executable file or directory (ends in / or \)
1750 /FI<value> Include file before parsing
1751 /Fo<file or directory> Set output object file, or directory (ends in / or \)
1752 /GF- Disable string pooling
1755 /help Display available options
1756 /I <dir> Add directory to include search path
1757 /J Make char type unsigned
1758 /LDd Create debug DLL
1760 /link <options> Forward options to the linker
1761 /MDd Use DLL debug run-time
1762 /MD Use DLL run-time
1763 /MTd Use static debug run-time
1764 /MT Use static run-time
1765 /Ob0 Disable inlining
1766 /Od Disable optimization
1767 /Oi- Disable use of builtin functions
1768 /Oi Enable use of builtin functions
1769 /Os Optimize for size
1770 /Ot Optimize for speed
1771 /Ox Maximum optimization
1772 /Oy- Disable frame pointer omission
1773 /Oy Enable frame pointer omission
1774 /O<n> Optimization level
1775 /P Only run the preprocessor
1776 /showIncludes Print info about included files to stderr
1777 /TC Treat all source files as C
1778 /Tc <filename> Specify a C source file
1779 /TP Treat all source files as C++
1780 /Tp <filename> Specify a C++ source file
1781 /U <macro> Undefine macro
1782 /W0 Disable all warnings
1788 /WX- Do not treat warnings as errors
1789 /WX Treat warnings as errors
1790 /w Disable all warnings
1791 /Zs Syntax-check only
1793 The /fallback Option
1794 ^^^^^^^^^^^^^^^^^^^^
1796 When clang-cl is run with the ``/fallback`` option, it will first try to
1797 compile files itself. For any file that it fails to compile, it will fall back
1798 and try to compile the file by invoking cl.exe.
1800 This option is intended to be used as a temporary means to build projects where
1801 clang-cl cannot successfully compile all the files. clang-cl may fail to compile
1802 a file either because it cannot generate code for some C++ feature, or because
1803 it cannot parse some Microsoft language extension.