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".
48 In addition to language specific features, Clang has a variety of
49 features that depend on what CPU architecture or operating system is
50 being compiled for. Please see the :ref:`Target-Specific Features and
51 Limitations <target_features>` section for more details.
53 The rest of the introduction introduces some basic :ref:`compiler
54 terminology <terminology>` that is used throughout this manual and
55 contains a basic :ref:`introduction to using Clang <basicusage>` as a
56 command line compiler.
63 Front end, parser, backend, preprocessor, undefined behavior,
71 Intro to how to use a C compiler for newbies.
73 compile + link compile then link debug info enabling optimizations
74 picking a language to use, defaults to C99 by default. Autosenses based
75 on extension. using a makefile
80 This section is generally an index into other sections. It does not go
81 into depth on the ones that are covered by other sections. However, the
82 first part introduces the language selection and other high level
83 options like :option:`-c`, :option:`-g`, etc.
85 Options to Control Error and Warning Messages
86 ---------------------------------------------
90 Turn warnings into errors.
92 .. This is in plain monospaced font because it generates the same label as
93 .. -Werror, and Sphinx complains.
97 Turn warning "foo" into an error.
99 .. option:: -Wno-error=foo
101 Turn warning "foo" into an warning even if :option:`-Werror` is specified.
105 Enable warning "foo".
109 Disable warning "foo".
113 Disable all warnings.
115 .. option:: -Weverything
117 :ref:`Enable all warnings. <diagnostics_enable_everything>`
119 .. option:: -pedantic
121 Warn on language extensions.
123 .. option:: -pedantic-errors
125 Error on language extensions.
127 .. option:: -Wsystem-headers
129 Enable warnings from system headers.
131 .. option:: -ferror-limit=123
133 Stop emitting diagnostics after 123 errors have been produced. The default is
134 20, and the error limit can be disabled with :option:`-ferror-limit=0`.
136 .. option:: -ftemplate-backtrace-limit=123
138 Only emit up to 123 template instantiation notes within the template
139 instantiation backtrace for a single warning or error. The default is 10, and
140 the limit can be disabled with :option:`-ftemplate-backtrace-limit=0`.
142 .. _cl_diag_formatting:
144 Formatting of Diagnostics
145 ^^^^^^^^^^^^^^^^^^^^^^^^^
147 Clang aims to produce beautiful diagnostics by default, particularly for
148 new users that first come to Clang. However, different people have
149 different preferences, and sometimes Clang is driven by another program
150 that wants to parse simple and consistent output, not a person. For
151 these cases, Clang provides a wide range of options to control the exact
152 output format of the diagnostics that it generates.
154 .. _opt_fshow-column:
156 **-f[no-]show-column**
157 Print column number in diagnostic.
159 This option, which defaults to on, controls whether or not Clang
160 prints the column number of a diagnostic. For example, when this is
161 enabled, Clang will print something like:
165 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
170 When this is disabled, Clang will print "test.c:28: warning..." with
173 The printed column numbers count bytes from the beginning of the
174 line; take care if your source contains multibyte characters.
176 .. _opt_fshow-source-location:
178 **-f[no-]show-source-location**
179 Print source file/line/column information in diagnostic.
181 This option, which defaults to on, controls whether or not Clang
182 prints the filename, line number and column number of a diagnostic.
183 For example, when this is enabled, Clang will print something like:
187 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
192 When this is disabled, Clang will not print the "test.c:28:8: "
195 .. _opt_fcaret-diagnostics:
197 **-f[no-]caret-diagnostics**
198 Print source line and ranges from source code in diagnostic.
199 This option, which defaults to on, controls whether or not Clang
200 prints the source line, source ranges, and caret when emitting a
201 diagnostic. For example, when this is enabled, Clang will print
206 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
211 **-f[no-]color-diagnostics**
212 This option, which defaults to on when a color-capable terminal is
213 detected, controls whether or not Clang prints diagnostics in color.
215 When this option is enabled, Clang will use colors to highlight
216 specific parts of the diagnostic, e.g.,
218 .. nasty hack to not lose our dignity
223 <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>
225 <span style="color:green">^</span>
226 <span style="color:green">//</span>
229 When this is disabled, Clang will just print:
233 test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
238 .. option:: -fdiagnostics-format=clang/msvc/vi
240 Changes diagnostic output format to better match IDEs and command line tools.
242 This option controls the output format of the filename, line number,
243 and column printed in diagnostic messages. The options, and their
244 affect on formatting a simple conversion diagnostic, follow:
249 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
254 t.c(3,11) : warning: conversion specifies type 'char *' but the argument has type 'int'
259 t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
261 **-f[no-]diagnostics-show-name**
262 Enable the display of the diagnostic name.
263 This option, which defaults to off, controls whether or not Clang
264 prints the associated name.
266 .. _opt_fdiagnostics-show-option:
268 **-f[no-]diagnostics-show-option**
269 Enable ``[-Woption]`` information in diagnostic line.
271 This option, which defaults to on, controls whether or not Clang
272 prints the associated :ref:`warning group <cl_diag_warning_groups>`
273 option name when outputting a warning diagnostic. For example, in
278 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
283 Passing **-fno-diagnostics-show-option** will prevent Clang from
284 printing the [:ref:`-Wextra-tokens <opt_Wextra-tokens>`] information in
285 the diagnostic. This information tells you the flag needed to enable
286 or disable the diagnostic, either from the command line or through
287 :ref:`#pragma GCC diagnostic <pragma_GCC_diagnostic>`.
289 .. _opt_fdiagnostics-show-category:
291 .. option:: -fdiagnostics-show-category=none/id/name
293 Enable printing category information in diagnostic line.
295 This option, which defaults to "none", controls whether or not Clang
296 prints the category associated with a diagnostic when emitting it.
297 Each diagnostic may or many not have an associated category, if it
298 has one, it is listed in the diagnostic categorization field of the
299 diagnostic line (in the []'s).
301 For example, a format string warning will produce these three
302 renditions based on the setting of this option:
306 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat]
307 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1]
308 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String]
310 This category can be used by clients that want to group diagnostics
311 by category, so it should be a high level category. We want dozens
312 of these, not hundreds or thousands of them.
314 .. _opt_fdiagnostics-fixit-info:
316 **-f[no-]diagnostics-fixit-info**
317 Enable "FixIt" information in the diagnostics output.
319 This option, which defaults to on, controls whether or not Clang
320 prints the information on how to fix a specific diagnostic
321 underneath it when it knows. For example, in this output:
325 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
330 Passing **-fno-diagnostics-fixit-info** will prevent Clang from
331 printing the "//" line at the end of the message. This information
332 is useful for users who may not understand what is wrong, but can be
333 confusing for machine parsing.
335 .. _opt_fdiagnostics-print-source-range-info:
337 **-fdiagnostics-print-source-range-info**
338 Print machine parsable information about source ranges.
339 This option makes Clang print information about source ranges in a machine
340 parsable format after the file/line/column number information. The
341 information is a simple sequence of brace enclosed ranges, where each range
342 lists the start and end line/column locations. For example, in this output:
346 exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float')
347 P = (P-42) + Gamma*4;
350 The {}'s are generated by -fdiagnostics-print-source-range-info.
352 The printed column numbers count bytes from the beginning of the
353 line; take care if your source contains multibyte characters.
355 .. option:: -fdiagnostics-parseable-fixits
357 Print Fix-Its in a machine parseable form.
359 This option makes Clang print available Fix-Its in a machine
360 parseable format at the end of diagnostics. The following example
361 illustrates the format:
365 fix-it:"t.cpp":{7:25-7:29}:"Gamma"
367 The range printed is a half-open range, so in this example the
368 characters at column 25 up to but not including column 29 on line 7
369 in t.cpp should be replaced with the string "Gamma". Either the
370 range or the replacement string may be empty (representing strict
371 insertions and strict erasures, respectively). Both the file name
372 and the insertion string escape backslash (as "\\\\"), tabs (as
373 "\\t"), newlines (as "\\n"), double quotes(as "\\"") and
374 non-printable characters (as octal "\\xxx").
376 The printed column numbers count bytes from the beginning of the
377 line; take care if your source contains multibyte characters.
379 .. option:: -fno-elide-type
381 Turns off elision in template type printing.
383 The default for template type printing is to elide as many template
384 arguments as possible, removing those which are the same in both
385 template types, leaving only the differences. Adding this flag will
386 print all the template arguments. If supported by the terminal,
387 highlighting will still appear on differing arguments.
393 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;
399 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;
401 .. option:: -fdiagnostics-show-template-tree
403 Template type diffing prints a text tree.
405 For diffing large templated types, this option will cause Clang to
406 display the templates as an indented text tree, one argument per
407 line, with differences marked inline. This is compatible with
414 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;
416 With :option:`-fdiagnostics-show-template-tree`:
420 t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument;
428 .. _cl_diag_warning_groups:
430 Individual Warning Groups
431 ^^^^^^^^^^^^^^^^^^^^^^^^^
433 TODO: Generate this from tblgen. Define one anchor per warning group.
435 .. _opt_wextra-tokens:
437 .. option:: -Wextra-tokens
439 Warn about excess tokens at the end of a preprocessor directive.
441 This option, which defaults to on, enables warnings about extra
442 tokens at the end of preprocessor directives. For example:
446 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
450 These extra tokens are not strictly conforming, and are usually best
451 handled by commenting them out.
453 .. option:: -Wambiguous-member-template
455 Warn about unqualified uses of a member template whose name resolves to
456 another template at the location of the use.
458 This option, which defaults to on, enables a warning in the
463 template<typename T> struct set{};
464 template<typename T> struct trait { typedef const T& type; };
466 template<typename T> void set(typename trait<T>::type value) {}
473 C++ [basic.lookup.classref] requires this to be an error, but,
474 because it's hard to work around, Clang downgrades it to a warning
477 .. option:: -Wbind-to-temporary-copy
479 Warn about an unusable copy constructor when binding a reference to a
482 This option, which defaults to on, enables warnings about binding a
483 reference to a temporary when the temporary doesn't have a usable
484 copy constructor. For example:
491 NonCopyable(const NonCopyable&);
493 void foo(const NonCopyable&);
495 foo(NonCopyable()); // Disallowed in C++98; allowed in C++11.
500 struct NonCopyable2 {
502 NonCopyable2(NonCopyable2&);
504 void foo(const NonCopyable2&);
506 foo(NonCopyable2()); // Disallowed in C++98; allowed in C++11.
509 Note that if ``NonCopyable2::NonCopyable2()`` has a default argument
510 whose instantiation produces a compile error, that error will still
511 be a hard error in C++98 mode even if this warning is turned off.
513 Options to Control Clang Crash Diagnostics
514 ------------------------------------------
516 As unbelievable as it may sound, Clang does crash from time to time.
517 Generally, this only occurs to those living on the `bleeding
518 edge <http://llvm.org/releases/download.html#svn>`_. Clang goes to great
519 lengths to assist you in filing a bug report. Specifically, Clang
520 generates preprocessed source file(s) and associated run script(s) upon
521 a crash. These files should be attached to a bug report to ease
522 reproducibility of the failure. Below are the command line options to
523 control the crash diagnostics.
525 .. option:: -fno-crash-diagnostics
527 Disable auto-generation of preprocessed source files during a clang crash.
529 The -fno-crash-diagnostics flag can be helpful for speeding the process
530 of generating a delta reduced test case.
532 Language and Target-Independent Features
533 ========================================
535 Controlling Errors and Warnings
536 -------------------------------
538 Clang provides a number of ways to control which code constructs cause
539 it to emit errors and warning messages, and how they are displayed to
542 Controlling How Clang Displays Diagnostics
543 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
545 When Clang emits a diagnostic, it includes rich information in the
546 output, and gives you fine-grain control over which information is
547 printed. Clang has the ability to print this information, and these are
548 the options that control it:
550 #. A file/line/column indicator that shows exactly where the diagnostic
551 occurs in your code [:ref:`-fshow-column <opt_fshow-column>`,
552 :ref:`-fshow-source-location <opt_fshow-source-location>`].
553 #. A categorization of the diagnostic as a note, warning, error, or
555 #. A text string that describes what the problem is.
556 #. An option that indicates how to control the diagnostic (for
557 diagnostics that support it)
558 [:ref:`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`].
559 #. A :ref:`high-level category <diagnostics_categories>` for the diagnostic
560 for clients that want to group diagnostics by class (for diagnostics
562 [:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>`].
563 #. The line of source code that the issue occurs on, along with a caret
564 and ranges that indicate the important locations
565 [:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`].
566 #. "FixIt" information, which is a concise explanation of how to fix the
567 problem (when Clang is certain it knows)
568 [:ref:`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`].
569 #. A machine-parsable representation of the ranges involved (off by
571 [:ref:`-fdiagnostics-print-source-range-info <opt_fdiagnostics-print-source-range-info>`].
573 For more information please see :ref:`Formatting of
574 Diagnostics <cl_diag_formatting>`.
579 All diagnostics are mapped into one of these 5 classes:
587 .. _diagnostics_categories:
589 Diagnostic Categories
590 ^^^^^^^^^^^^^^^^^^^^^
592 Though not shown by default, diagnostics may each be associated with a
593 high-level category. This category is intended to make it possible to
594 triage builds that produce a large number of errors or warnings in a
597 Categories are not shown by default, but they can be turned on with the
598 :ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>` option.
599 When set to "``name``", the category is printed textually in the
600 diagnostic output. When it is set to "``id``", a category number is
601 printed. The mapping of category names to category id's can be obtained
602 by running '``clang --print-diagnostic-categories``'.
604 Controlling Diagnostics via Command Line Flags
605 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
607 TODO: -W flags, -pedantic, etc
609 .. _pragma_gcc_diagnostic:
611 Controlling Diagnostics via Pragmas
612 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
614 Clang can also control what diagnostics are enabled through the use of
615 pragmas in the source code. This is useful for turning off specific
616 warnings in a section of source code. Clang supports GCC's pragma for
617 compatibility with existing source code, as well as several extensions.
619 The pragma may control any warning that can be used from the command
620 line. Warnings may be set to ignored, warning, error, or fatal. The
621 following example code will tell Clang or GCC to ignore the -Wall
626 #pragma GCC diagnostic ignored "-Wall"
628 In addition to all of the functionality provided by GCC's pragma, Clang
629 also allows you to push and pop the current warning state. This is
630 particularly useful when writing a header file that will be compiled by
631 other people, because you don't know what warning flags they build with.
633 In the below example :option:`-Wmultichar` is ignored for only a single line of
634 code, after which the diagnostics return to whatever state had previously
639 #pragma clang diagnostic push
640 #pragma clang diagnostic ignored "-Wmultichar"
642 char b = 'df'; // no warning.
644 #pragma clang diagnostic pop
646 The push and pop pragmas will save and restore the full diagnostic state
647 of the compiler, regardless of how it was set. That means that it is
648 possible to use push and pop around GCC compatible diagnostics and Clang
649 will push and pop them appropriately, while GCC will ignore the pushes
650 and pops as unknown pragmas. It should be noted that while Clang
651 supports the GCC pragma, Clang and GCC do not support the exact same set
652 of warnings, so even when using GCC compatible #pragmas there is no
653 guarantee that they will have identical behaviour on both compilers.
655 In addition to controlling warnings and errors generated by the compiler, it is
656 possible to generate custom warning and error messages through the following
661 // The following will produce warning messages
662 #pragma message "some diagnostic message"
663 #pragma GCC warning "TODO: replace deprecated feature"
665 // The following will produce an error message
666 #pragma GCC error "Not supported"
668 These pragmas operate similarly to the ``#warning`` and ``#error`` preprocessor
669 directives, except that they may also be embedded into preprocessor macros via
670 the C99 ``_Pragma`` operator, for example:
675 #define DEFER(M,...) M(__VA_ARGS__)
676 #define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__))))
678 CUSTOM_ERROR("Feature not available");
680 Controlling Diagnostics in System Headers
681 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
683 Warnings are suppressed when they occur in system headers. By default,
684 an included file is treated as a system header if it is found in an
685 include path specified by ``-isystem``, but this can be overridden in
688 The ``system_header`` pragma can be used to mark the current file as
689 being a system header. No warnings will be produced from the location of
690 the pragma onwards within the same file.
694 char a = 'xy'; // warning
696 #pragma clang system_header
698 char b = 'ab'; // no warning
700 The :option:`-isystem-prefix` and :option:`-ino-system-prefix` command-line
701 arguments can be used to override whether subsets of an include path are
702 treated as system headers. When the name in a ``#include`` directive is
703 found within a header search path and starts with a system prefix, the
704 header is treated as a system header. The last prefix on the
705 command-line which matches the specified header name takes precedence.
708 .. code-block:: console
710 $ clang -Ifoo -isystem bar -isystem-prefix x/ -ino-system-prefix x/y/
712 Here, ``#include "x/a.h"`` is treated as including a system header, even
713 if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated
714 as not including a system header, even if the header is found in
717 A ``#include`` directive which finds a file relative to the current
718 directory is treated as including a system header if the including file
719 is treated as a system header.
721 .. _diagnostics_enable_everything:
723 Enabling All Warnings
724 ^^^^^^^^^^^^^^^^^^^^^
726 In addition to the traditional ``-W`` flags, one can enable **all**
727 warnings by passing :option:`-Weverything`. This works as expected with
728 :option:`-Werror`, and also includes the warnings from :option:`-pedantic`.
730 Note that when combined with :option:`-w` (which disables all warnings), that
733 Controlling Static Analyzer Diagnostics
734 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
736 While not strictly part of the compiler, the diagnostics from Clang's
737 `static analyzer <http://clang-analyzer.llvm.org>`_ can also be
738 influenced by the user via changes to the source code. See the available
739 `annotations <http://clang-analyzer.llvm.org/annotations.html>`_ and the
741 page <http://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more
744 .. _usersmanual-precompiled-headers:
749 `Precompiled headers <http://en.wikipedia.org/wiki/Precompiled_header>`__
750 are a general approach employed by many compilers to reduce compilation
751 time. The underlying motivation of the approach is that it is common for
752 the same (and often large) header files to be included by multiple
753 source files. Consequently, compile times can often be greatly improved
754 by caching some of the (redundant) work done by a compiler to process
755 headers. Precompiled header files, which represent one of many ways to
756 implement this optimization, are literally files that represent an
757 on-disk cache that contains the vital information necessary to reduce
758 some of the work needed to process a corresponding header file. While
759 details of precompiled headers vary between compilers, precompiled
760 headers have been shown to be highly effective at speeding up program
761 compilation on systems with very large system headers (e.g., Mac OS/X).
763 Generating a PCH File
764 ^^^^^^^^^^^^^^^^^^^^^
766 To generate a PCH file using Clang, one invokes Clang with the
767 :option:`-x <language>-header` option. This mirrors the interface in GCC
768 for generating PCH files:
770 .. code-block:: console
772 $ gcc -x c-header test.h -o test.h.gch
773 $ clang -x c-header test.h -o test.h.pch
778 A PCH file can then be used as a prefix header when a :option:`-include`
779 option is passed to ``clang``:
781 .. code-block:: console
783 $ clang -include test.h test.c -o test
785 The ``clang`` driver will first check if a PCH file for ``test.h`` is
786 available; if so, the contents of ``test.h`` (and the files it includes)
787 will be processed from the PCH file. Otherwise, Clang falls back to
788 directly processing the content of ``test.h``. This mirrors the behavior
793 Clang does *not* automatically use PCH files for headers that are directly
794 included within a source file. For example:
796 .. code-block:: console
798 $ clang -x c-header test.h -o test.h.pch
801 $ clang test.c -o test
803 In this example, ``clang`` will not automatically use the PCH file for
804 ``test.h`` since ``test.h`` was included directly in the source file and not
805 specified on the command line using :option:`-include`.
807 Relocatable PCH Files
808 ^^^^^^^^^^^^^^^^^^^^^
810 It is sometimes necessary to build a precompiled header from headers
811 that are not yet in their final, installed locations. For example, one
812 might build a precompiled header within the build tree that is then
813 meant to be installed alongside the headers. Clang permits the creation
814 of "relocatable" precompiled headers, which are built with a given path
815 (into the build directory) and can later be used from an installed
818 To build a relocatable precompiled header, place your headers into a
819 subdirectory whose structure mimics the installed location. For example,
820 if you want to build a precompiled header for the header ``mylib.h``
821 that will be installed into ``/usr/include``, create a subdirectory
822 ``build/usr/include`` and place the header ``mylib.h`` into that
823 subdirectory. If ``mylib.h`` depends on other headers, then they can be
824 stored within ``build/usr/include`` in a way that mimics the installed
827 Building a relocatable precompiled header requires two additional
828 arguments. First, pass the ``--relocatable-pch`` flag to indicate that
829 the resulting PCH file should be relocatable. Second, pass
830 :option:`-isysroot /path/to/build`, which makes all includes for your library
831 relative to the build directory. For example:
833 .. code-block:: console
835 # clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
837 When loading the relocatable PCH file, the various headers used in the
838 PCH file are found from the system header root. For example, ``mylib.h``
839 can be found in ``/usr/include/mylib.h``. If the headers are installed
840 in some other system root, the :option:`-isysroot` option can be used provide
841 a different system root from which the headers will be based. For
842 example, :option:`-isysroot /Developer/SDKs/MacOSX10.4u.sdk` will look for
843 ``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``.
845 Relocatable precompiled headers are intended to be used in a limited
846 number of cases where the compilation environment is tightly controlled
847 and the precompiled header cannot be generated after headers have been
850 Controlling Code Generation
851 ---------------------------
853 Clang provides a number of ways to control code generation. The options
856 **-fsanitize=check1,check2,...**
857 Turn on runtime checks for various forms of undefined or suspicious
860 This option controls whether Clang adds runtime checks for various
861 forms of undefined or suspicious behavior, and is disabled by
862 default. If a check fails, a diagnostic message is produced at
863 runtime explaining the problem. The main checks are:
865 - .. _opt_fsanitize_address:
867 ``-fsanitize=address``:
868 :doc:`AddressSanitizer`, a memory error
870 - ``-fsanitize=init-order``: Make AddressSanitizer check for
871 dynamic initialization order problems. Implied by ``-fsanitize=address``.
872 - ``-fsanitize=address-full``: AddressSanitizer with all the
873 experimental features listed below.
874 - ``-fsanitize=integer``: Enables checks for undefined or
875 suspicious integer behavior.
876 - .. _opt_fsanitize_thread:
878 ``-fsanitize=thread``: :doc:`ThreadSanitizer`, a data race detector.
879 - .. _opt_fsanitize_memory:
881 ``-fsanitize=memory``: :doc:`MemorySanitizer`,
882 an *experimental* detector of uninitialized reads. Not ready for
884 - .. _opt_fsanitize_undefined:
886 ``-fsanitize=undefined``: Fast and compatible undefined behavior
887 checker. Enables the undefined behavior checks that have small
888 runtime cost and no impact on address space layout or ABI. This
889 includes all of the checks listed below other than
890 ``unsigned-integer-overflow``.
892 - ``-fsanitize=undefined-trap``: This includes all sanitizers
893 included by ``-fsanitize=undefined``, except those that require
894 runtime support. This group of sanitizers is intended to be
895 used in conjunction with the ``-fsanitize-undefined-trap-on-error``
896 flag. This includes all of the checks listed below other than
897 ``unsigned-integer-overflow`` and ``vptr``.
899 The following more fine-grained checks are also available:
901 - ``-fsanitize=alignment``: Use of a misaligned pointer or creation
902 of a misaligned reference.
903 - ``-fsanitize=bool``: Load of a ``bool`` value which is neither
904 ``true`` nor ``false``.
905 - ``-fsanitize=bounds``: Out of bounds array indexing, in cases
906 where the array bound can be statically determined.
907 - ``-fsanitize=enum``: Load of a value of an enumerated type which
908 is not in the range of representable values for that enumerated
910 - ``-fsanitize=float-cast-overflow``: Conversion to, from, or
911 between floating-point types which would overflow the
913 - ``-fsanitize=float-divide-by-zero``: Floating point division by
915 - ``-fsanitize=integer-divide-by-zero``: Integer division by zero.
916 - ``-fsanitize=null``: Use of a null pointer or creation of a null
918 - ``-fsanitize=object-size``: An attempt to use bytes which the
919 optimizer can determine are not part of the object being
920 accessed. The sizes of objects are determined using
921 ``__builtin_object_size``, and consequently may be able to detect
922 more problems at higher optimization levels.
923 - ``-fsanitize=return``: In C++, reaching the end of a
924 value-returning function without returning a value.
925 - ``-fsanitize=shift``: Shift operators where the amount shifted is
926 greater or equal to the promoted bit-width of the left hand side
927 or less than zero, or where the left hand side is negative. For a
928 signed left shift, also checks for signed overflow in C, and for
929 unsigned overflow in C++.
930 - ``-fsanitize=signed-integer-overflow``: Signed integer overflow,
931 including all the checks added by ``-ftrapv``, and checking for
932 overflow in signed division (``INT_MIN / -1``).
933 - ``-fsanitize=unreachable``: If control flow reaches
934 ``__builtin_unreachable``.
935 - ``-fsanitize=unsigned-integer-overflow``: Unsigned integer
937 - ``-fsanitize=vla-bound``: A variable-length array whose bound
938 does not evaluate to a positive value.
939 - ``-fsanitize=vptr``: Use of an object whose vptr indicates that
940 it is of the wrong dynamic type, or that its lifetime has not
941 begun or has ended. Incompatible with ``-fno-rtti``.
943 Experimental features of AddressSanitizer (not ready for widespread
944 use, require explicit ``-fsanitize=address``):
946 - ``-fsanitize=use-after-return``: Check for use-after-return
947 errors (accessing local variable after the function exit).
948 - ``-fsanitize=use-after-scope``: Check for use-after-scope errors
949 (accesing local variable after it went out of scope).
951 Extra features of MemorySanitizer (require explicit
952 ``-fsanitize=memory``):
954 - ``-fsanitize-memory-track-origins``: Enables origin tracking in
955 MemorySanitizer. Adds a second section to MemorySanitizer
956 reports pointing to the heap or stack allocation the
957 uninitialized bits came from. Slows down execution by additional
960 Extra features of UndefinedBehaviorSanitizer:
962 - ``-fno-sanitize-recover``: By default, after a sanitizer diagnoses
963 an issue, it will attempt to continue executing the program if there
964 is a reasonable behavior it can give to the faulting operation. This
965 option causes the program to abort instead.
966 - ``-fsanitize-undefined-trap-on-error``: Causes traps to be emitted
967 rather than calls to runtime libraries when a problem is detected.
968 This option is intended for use in cases where the sanitizer runtime
969 cannot be used (for instance, when building libc or a kernel module).
970 This is only compatible with the sanitizers in the ``undefined-trap``
973 The ``-fsanitize=`` argument must also be provided when linking, in
974 order to link to the appropriate runtime library. It is not possible
975 to combine the ``-fsanitize=address`` and ``-fsanitize=thread``
976 checkers in the same program.
977 **-f[no-]address-sanitizer**
978 Deprecated synonym for :ref:`-f[no-]sanitize=address
979 <opt_fsanitize_address>`.
980 **-f[no-]thread-sanitizer**
981 Deprecated synonym for :ref:`-f[no-]sanitize=thread
982 <opt_fsanitize_thread>`.
984 .. option:: -fcatch-undefined-behavior
986 Deprecated synonym for :ref:`-fsanitize=undefined
987 <opt_fsanitize_undefined>`.
989 .. option:: -fno-assume-sane-operator-new
991 Don't assume that the C++'s new operator is sane.
993 This option tells the compiler to do not assume that C++'s global
994 new operator will always return a pointer that does not alias any
995 other pointer when the function returns.
997 .. option:: -ftrap-function=[name]
999 Instruct code generator to emit a function call to the specified
1000 function name for ``__builtin_trap()``.
1002 LLVM code generator translates ``__builtin_trap()`` to a trap
1003 instruction if it is supported by the target ISA. Otherwise, the
1004 builtin is translated into a call to ``abort``. If this option is
1005 set, then the code generator will always lower the builtin to a call
1006 to the specified function regardless of whether the target ISA has a
1007 trap instruction. This option is useful for environments (e.g.
1008 deeply embedded) where a trap cannot be properly handled, or when
1009 some custom behavior is desired.
1011 .. option:: -ftls-model=[model]
1013 Select which TLS model to use.
1015 Valid values are: ``global-dynamic``, ``local-dynamic``,
1016 ``initial-exec`` and ``local-exec``. The default value is
1017 ``global-dynamic``. The compiler may use a different model if the
1018 selected model is not supported by the target, or if a more
1019 efficient model can be used. The TLS model can be overridden per
1020 variable using the ``tls_model`` attribute.
1022 Controlling Size of Debug Information
1023 -------------------------------------
1025 Debug info kind generated by Clang can be set by one of the flags listed
1026 below. If multiple flags are present, the last one is used.
1030 Don't generate any debug info (default).
1032 .. option:: -gline-tables-only
1034 Generate line number tables only.
1036 This kind of debug info allows to obtain stack traces with function names,
1037 file names and line numbers (by such tools as ``gdb`` or ``addr2line``). It
1038 doesn't contain any other data (e.g. description of local variables or
1039 function parameters).
1043 Generate complete debug info.
1045 Comment Parsing Options
1046 --------------------------
1048 Clang parses Doxygen and non-Doxygen style documentation comments and attaches
1049 them to the appropriate declaration nodes. By default, it only parses
1050 Doxygen-style comments and ignores ordinary comments starting with ``//`` and
1053 .. option:: -fparse-all-comments
1055 Parse all comments as documentation comments (including ordinary comments
1056 starting with ``//`` and ``/*``).
1063 The support for standard C in clang is feature-complete except for the
1064 C99 floating-point pragmas.
1066 Extensions supported by clang
1067 -----------------------------
1069 See :doc:`LanguageExtensions`.
1071 Differences between various standard modes
1072 ------------------------------------------
1074 clang supports the -std option, which changes what language mode clang
1075 uses. The supported modes for C are c89, gnu89, c94, c99, gnu99 and
1076 various aliases for those modes. If no -std option is specified, clang
1077 defaults to gnu99 mode.
1079 Differences between all ``c*`` and ``gnu*`` modes:
1081 - ``c*`` modes define "``__STRICT_ANSI__``".
1082 - Target-specific defines not prefixed by underscores, like "linux",
1083 are defined in ``gnu*`` modes.
1084 - Trigraphs default to being off in ``gnu*`` modes; they can be enabled by
1085 the -trigraphs option.
1086 - The parser recognizes "asm" and "typeof" as keywords in ``gnu*`` modes;
1087 the variants "``__asm__``" and "``__typeof__``" are recognized in all
1089 - The Apple "blocks" extension is recognized by default in ``gnu*`` modes
1090 on some platforms; it can be enabled in any mode with the "-fblocks"
1092 - Arrays that are VLA's according to the standard, but which can be
1093 constant folded by the frontend are treated as fixed size arrays.
1094 This occurs for things like "int X[(1, 2)];", which is technically a
1095 VLA. ``c*`` modes are strictly compliant and treat these as VLAs.
1097 Differences between ``*89`` and ``*99`` modes:
1099 - The ``*99`` modes default to implementing "inline" as specified in C99,
1100 while the ``*89`` modes implement the GNU version. This can be
1101 overridden for individual functions with the ``__gnu_inline__``
1103 - Digraphs are not recognized in c89 mode.
1104 - The scope of names defined inside a "for", "if", "switch", "while",
1105 or "do" statement is different. (example: "``if ((struct x {int
1107 - ``__STDC_VERSION__`` is not defined in ``*89`` modes.
1108 - "inline" is not recognized as a keyword in c89 mode.
1109 - "restrict" is not recognized as a keyword in ``*89`` modes.
1110 - Commas are allowed in integer constant expressions in ``*99`` modes.
1111 - Arrays which are not lvalues are not implicitly promoted to pointers
1113 - Some warnings are different.
1115 c94 mode is identical to c89 mode except that digraphs are enabled in
1116 c94 mode (FIXME: And ``__STDC_VERSION__`` should be defined!).
1118 GCC extensions not implemented yet
1119 ----------------------------------
1121 clang tries to be compatible with gcc as much as possible, but some gcc
1122 extensions are not implemented yet:
1124 - clang does not support #pragma weak (`bug
1125 3679 <http://llvm.org/bugs/show_bug.cgi?id=3679>`_). Due to the uses
1126 described in the bug, this is likely to be implemented at some point,
1128 - clang does not support decimal floating point types (``_Decimal32`` and
1129 friends) or fixed-point types (``_Fract`` and friends); nobody has
1130 expressed interest in these features yet, so it's hard to say when
1131 they will be implemented.
1132 - clang does not support nested functions; this is a complex feature
1133 which is infrequently used, so it is unlikely to be implemented
1134 anytime soon. In C++11 it can be emulated by assigning lambda
1135 functions to local variables, e.g:
1139 auto const local_function = [&](int parameter) {
1145 - clang does not support global register variables; this is unlikely to
1146 be implemented soon because it requires additional LLVM backend
1148 - clang does not support static initialization of flexible array
1149 members. This appears to be a rarely used extension, but could be
1150 implemented pending user demand.
1151 - clang does not support
1152 ``__builtin_va_arg_pack``/``__builtin_va_arg_pack_len``. This is
1153 used rarely, but in some potentially interesting places, like the
1154 glibc headers, so it may be implemented pending user demand. Note
1155 that because clang pretends to be like GCC 4.2, and this extension
1156 was introduced in 4.3, the glibc headers will not try to use this
1157 extension with clang at the moment.
1158 - clang does not support the gcc extension for forward-declaring
1159 function parameters; this has not shown up in any real-world code
1160 yet, though, so it might never be implemented.
1162 This is not a complete list; if you find an unsupported extension
1163 missing from this list, please send an e-mail to cfe-dev. This list
1164 currently excludes C++; see :ref:`C++ Language Features <cxx>`. Also, this
1165 list does not include bugs in mostly-implemented features; please see
1167 tracker <http://llvm.org/bugs/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer>`_
1168 for known existing bugs (FIXME: Is there a section for bug-reporting
1169 guidelines somewhere?).
1171 Intentionally unsupported GCC extensions
1172 ----------------------------------------
1174 - clang does not support the gcc extension that allows variable-length
1175 arrays in structures. This is for a few reasons: one, it is tricky to
1176 implement, two, the extension is completely undocumented, and three,
1177 the extension appears to be rarely used. Note that clang *does*
1178 support flexible array members (arrays with a zero or unspecified
1179 size at the end of a structure).
1180 - clang does not have an equivalent to gcc's "fold"; this means that
1181 clang doesn't accept some constructs gcc might accept in contexts
1182 where a constant expression is required, like "x-x" where x is a
1184 - clang does not support ``__builtin_apply`` and friends; this extension
1185 is extremely obscure and difficult to implement reliably.
1189 Microsoft extensions
1190 --------------------
1192 clang has some experimental support for extensions from Microsoft Visual
1193 C++; to enable it, use the -fms-extensions command-line option. This is
1194 the default for Windows targets. Note that the support is incomplete;
1195 enabling Microsoft extensions will silently drop certain constructs
1196 (including ``__declspec`` and Microsoft-style asm statements).
1198 clang has a -fms-compatibility flag that makes clang accept enough
1199 invalid C++ to be able to parse most Microsoft headers. This flag is
1200 enabled by default for Windows targets.
1202 -fdelayed-template-parsing lets clang delay all template instantiation
1203 until the end of a translation unit. This flag is enabled by default for
1206 - clang allows setting ``_MSC_VER`` with ``-fmsc-version=``. It defaults to
1207 1300 which is the same as Visual C/C++ 2003. Any number is supported
1208 and can greatly affect what Windows SDK and c++stdlib headers clang
1209 can compile. This option will be removed when clang supports the full
1210 set of MS extensions required for these headers.
1211 - clang does not support the Microsoft extension where anonymous record
1212 members can be declared using user defined typedefs.
1213 - clang supports the Microsoft "#pragma pack" feature for controlling
1214 record layout. GCC also contains support for this feature, however
1215 where MSVC and GCC are incompatible clang follows the MSVC
1217 - clang supports the Microsoft ``#pragma comment(lib, "foo.lib")`` feature for
1218 automatically linking against the specified library. Currently this feature
1219 only works with the Visual C++ linker.
1220 - clang supports the Microsoft ``#pragma comment(linker, "/flag:foo")`` feature
1221 for adding linker flags to COFF object files. The user is responsible for
1222 ensuring that the linker understands the flags.
1223 - clang defaults to C++11 for Windows targets.
1227 C++ Language Features
1228 =====================
1230 clang fully implements all of standard C++98 except for exported
1231 templates (which were removed in C++11), and `many C++11
1232 features <http://clang.llvm.org/cxx_status.html>`_ are also implemented.
1234 Controlling implementation limits
1235 ---------------------------------
1237 .. option:: -fbracket-depth=N
1239 Sets the limit for nested parentheses, brackets, and braces to N. The
1242 .. option:: -fconstexpr-depth=N
1244 Sets the limit for recursive constexpr function invocations to N. The
1247 .. option:: -ftemplate-depth=N
1249 Sets the limit for recursively nested template instantiations to N. The
1254 Objective-C Language Features
1255 =============================
1259 Objective-C++ Language Features
1260 ===============================
1263 .. _target_features:
1265 Target-Specific Features and Limitations
1266 ========================================
1268 CPU Architectures Features and Limitations
1269 ------------------------------------------
1274 The support for X86 (both 32-bit and 64-bit) is considered stable on
1275 Darwin (Mac OS/X), Linux, FreeBSD, and Dragonfly BSD: it has been tested
1276 to correctly compile many large C, C++, Objective-C, and Objective-C++
1279 On ``x86_64-mingw32``, passing i128(by value) is incompatible to Microsoft
1280 x64 calling conversion. You might need to tweak
1281 ``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp.
1286 The support for ARM (specifically ARMv6 and ARMv7) is considered stable
1287 on Darwin (iOS): it has been tested to correctly compile many large C,
1288 C++, Objective-C, and Objective-C++ codebases. Clang only supports a
1289 limited number of ARM architectures. It does not yet fully support
1295 clang currently contains some support for PPC and Sparc; however,
1296 significant pieces of code generation are still missing, and they
1297 haven't undergone significant testing.
1299 clang contains limited support for the MSP430 embedded processor, but
1300 both the clang support and the LLVM backend support are highly
1303 Other platforms are completely unsupported at the moment. Adding the
1304 minimal support needed for parsing and semantic analysis on a new
1305 platform is quite easy; see ``lib/Basic/Targets.cpp`` in the clang source
1306 tree. This level of support is also sufficient for conversion to LLVM IR
1307 for simple programs. Proper support for conversion to LLVM IR requires
1308 adding code to ``lib/CodeGen/CGCall.cpp`` at the moment; this is likely to
1309 change soon, though. Generating assembly requires a suitable LLVM
1312 Operating System Features and Limitations
1313 -----------------------------------------
1323 Experimental supports are on Cygming.
1325 See also `Microsoft Extensions <c_ms>`.
1330 Clang works on Cygwin-1.7.
1335 Clang works on some mingw32 distributions. Clang assumes directories as
1338 - ``C:/mingw/include``
1340 - ``C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++``
1342 On MSYS, a few tests might fail.
1347 For 32-bit (i686-w64-mingw32), and 64-bit (x86\_64-w64-mingw32), Clang
1350 - ``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)``
1351 - ``some_directory/bin/gcc.exe``
1352 - ``some_directory/bin/clang.exe``
1353 - ``some_directory/bin/clang++.exe``
1354 - ``some_directory/bin/../include/c++/GCC_version``
1355 - ``some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32``
1356 - ``some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32``
1357 - ``some_directory/bin/../include/c++/GCC_version/backward``
1358 - ``some_directory/bin/../x86_64-w64-mingw32/include``
1359 - ``some_directory/bin/../i686-w64-mingw32/include``
1360 - ``some_directory/bin/../include``
1362 This directory layout is standard for any toolchain you will find on the
1363 official `MinGW-w64 website <http://mingw-w64.sourceforge.net>`_.
1365 Clang expects the GCC executable "gcc.exe" compiled for
1366 ``i686-w64-mingw32`` (or ``x86_64-w64-mingw32``) to be present on PATH.
1368 `Some tests might fail <http://llvm.org/bugs/show_bug.cgi?id=9072>`_ on
1369 ``x86_64-w64-mingw32``.