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 C11 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 `-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 `-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 not by a human,
152 but by a program that wants consistent and easily parsable output. 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 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. Optimization remarks that refer to function names will display the
581 mangled name of the function. Since these remarks are emitted by the
582 back end of the compiler, it does not know anything about the input
583 language, nor its mangling rules.
585 2. Some source locations are not displayed correctly. The front end has
586 a more detailed source location tracking than the locations included
587 in the debug info (e.g., the front end can locate code inside macro
588 expansions). However, the locations used by :option:`-Rpass` are
589 translated from debug annotations. That translation can be lossy,
590 which results in some remarks having no location information.
594 Clang options that that don't fit neatly into other categories.
598 When emitting a dependency file, use formatting conventions appropriate
599 for NMake or Jom. Ignored unless another option causes Clang to emit a
602 When Clang emits a dependency file (e.g., you supplied the -M option)
603 most filenames can be written to the file without any special formatting.
604 Different Make tools will treat different sets of characters as "special"
605 and use different conventions for telling the Make tool that the character
606 is actually part of the filename. Normally Clang uses backslash to "escape"
607 a special character, which is the convention used by GNU Make. The -MV
608 option tells Clang to put double-quotes around the entire filename, which
609 is the convention used by NMake and Jom.
612 Language and Target-Independent Features
613 ========================================
615 Controlling Errors and Warnings
616 -------------------------------
618 Clang provides a number of ways to control which code constructs cause
619 it to emit errors and warning messages, and how they are displayed to
622 Controlling How Clang Displays Diagnostics
623 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
625 When Clang emits a diagnostic, it includes rich information in the
626 output, and gives you fine-grain control over which information is
627 printed. Clang has the ability to print this information, and these are
628 the options that control it:
630 #. A file/line/column indicator that shows exactly where the diagnostic
631 occurs in your code [:ref:`-fshow-column <opt_fshow-column>`,
632 :ref:`-fshow-source-location <opt_fshow-source-location>`].
633 #. A categorization of the diagnostic as a note, warning, error, or
635 #. A text string that describes what the problem is.
636 #. An option that indicates how to control the diagnostic (for
637 diagnostics that support it)
638 [:ref:`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`].
639 #. A :ref:`high-level category <diagnostics_categories>` for the diagnostic
640 for clients that want to group diagnostics by class (for diagnostics
642 [:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>`].
643 #. The line of source code that the issue occurs on, along with a caret
644 and ranges that indicate the important locations
645 [:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`].
646 #. "FixIt" information, which is a concise explanation of how to fix the
647 problem (when Clang is certain it knows)
648 [:ref:`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`].
649 #. A machine-parsable representation of the ranges involved (off by
651 [:ref:`-fdiagnostics-print-source-range-info <opt_fdiagnostics-print-source-range-info>`].
653 For more information please see :ref:`Formatting of
654 Diagnostics <cl_diag_formatting>`.
659 All diagnostics are mapped into one of these 6 classes:
668 .. _diagnostics_categories:
670 Diagnostic Categories
671 ^^^^^^^^^^^^^^^^^^^^^
673 Though not shown by default, diagnostics may each be associated with a
674 high-level category. This category is intended to make it possible to
675 triage builds that produce a large number of errors or warnings in a
678 Categories are not shown by default, but they can be turned on with the
679 :ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>` option.
680 When set to "``name``", the category is printed textually in the
681 diagnostic output. When it is set to "``id``", a category number is
682 printed. The mapping of category names to category id's can be obtained
683 by running '``clang --print-diagnostic-categories``'.
685 Controlling Diagnostics via Command Line Flags
686 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
688 TODO: -W flags, -pedantic, etc
690 .. _pragma_gcc_diagnostic:
692 Controlling Diagnostics via Pragmas
693 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
695 Clang can also control what diagnostics are enabled through the use of
696 pragmas in the source code. This is useful for turning off specific
697 warnings in a section of source code. Clang supports GCC's pragma for
698 compatibility with existing source code, as well as several extensions.
700 The pragma may control any warning that can be used from the command
701 line. Warnings may be set to ignored, warning, error, or fatal. The
702 following example code will tell Clang or GCC to ignore the -Wall
707 #pragma GCC diagnostic ignored "-Wall"
709 In addition to all of the functionality provided by GCC's pragma, Clang
710 also allows you to push and pop the current warning state. This is
711 particularly useful when writing a header file that will be compiled by
712 other people, because you don't know what warning flags they build with.
714 In the below example :option:`-Wextra-tokens` is ignored for only a single line
715 of code, after which the diagnostics return to whatever state had previously
721 #endif foo // warning: extra tokens at end of #endif directive
723 #pragma clang diagnostic ignored "-Wextra-tokens"
726 #endif foo // no warning
728 #pragma clang diagnostic pop
730 The push and pop pragmas will save and restore the full diagnostic state
731 of the compiler, regardless of how it was set. That means that it is
732 possible to use push and pop around GCC compatible diagnostics and Clang
733 will push and pop them appropriately, while GCC will ignore the pushes
734 and pops as unknown pragmas. It should be noted that while Clang
735 supports the GCC pragma, Clang and GCC do not support the exact same set
736 of warnings, so even when using GCC compatible #pragmas there is no
737 guarantee that they will have identical behaviour on both compilers.
739 In addition to controlling warnings and errors generated by the compiler, it is
740 possible to generate custom warning and error messages through the following
745 // The following will produce warning messages
746 #pragma message "some diagnostic message"
747 #pragma GCC warning "TODO: replace deprecated feature"
749 // The following will produce an error message
750 #pragma GCC error "Not supported"
752 These pragmas operate similarly to the ``#warning`` and ``#error`` preprocessor
753 directives, except that they may also be embedded into preprocessor macros via
754 the C99 ``_Pragma`` operator, for example:
759 #define DEFER(M,...) M(__VA_ARGS__)
760 #define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__))))
762 CUSTOM_ERROR("Feature not available");
764 Controlling Diagnostics in System Headers
765 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
767 Warnings are suppressed when they occur in system headers. By default,
768 an included file is treated as a system header if it is found in an
769 include path specified by ``-isystem``, but this can be overridden in
772 The ``system_header`` pragma can be used to mark the current file as
773 being a system header. No warnings will be produced from the location of
774 the pragma onwards within the same file.
779 #endif foo // warning: extra tokens at end of #endif directive
781 #pragma clang system_header
784 #endif foo // no warning
786 The :option:`--system-header-prefix=` and :option:`--no-system-header-prefix=`
787 command-line arguments can be used to override whether subsets of an include
788 path are treated as system headers. When the name in a ``#include`` directive
789 is found within a header search path and starts with a system prefix, the
790 header is treated as a system header. The last prefix on the
791 command-line which matches the specified header name takes precedence.
794 .. code-block:: console
796 $ clang -Ifoo -isystem bar --system-header-prefix=x/ \
797 --no-system-header-prefix=x/y/
799 Here, ``#include "x/a.h"`` is treated as including a system header, even
800 if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated
801 as not including a system header, even if the header is found in
804 A ``#include`` directive which finds a file relative to the current
805 directory is treated as including a system header if the including file
806 is treated as a system header.
808 .. _diagnostics_enable_everything:
810 Enabling All Diagnostics
811 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
813 In addition to the traditional ``-W`` flags, one can enable **all**
814 diagnostics by passing :option:`-Weverything`. This works as expected
816 :option:`-Werror`, and also includes the warnings from :option:`-pedantic`.
818 Note that when combined with :option:`-w` (which disables all warnings), that
821 Controlling Static Analyzer Diagnostics
822 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
824 While not strictly part of the compiler, the diagnostics from Clang's
825 `static analyzer <http://clang-analyzer.llvm.org>`_ can also be
826 influenced by the user via changes to the source code. See the available
827 `annotations <http://clang-analyzer.llvm.org/annotations.html>`_ and the
829 page <http://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more
832 .. _usersmanual-precompiled-headers:
837 `Precompiled headers <http://en.wikipedia.org/wiki/Precompiled_header>`__
838 are a general approach employed by many compilers to reduce compilation
839 time. The underlying motivation of the approach is that it is common for
840 the same (and often large) header files to be included by multiple
841 source files. Consequently, compile times can often be greatly improved
842 by caching some of the (redundant) work done by a compiler to process
843 headers. Precompiled header files, which represent one of many ways to
844 implement this optimization, are literally files that represent an
845 on-disk cache that contains the vital information necessary to reduce
846 some of the work needed to process a corresponding header file. While
847 details of precompiled headers vary between compilers, precompiled
848 headers have been shown to be highly effective at speeding up program
849 compilation on systems with very large system headers (e.g., Mac OS X).
851 Generating a PCH File
852 ^^^^^^^^^^^^^^^^^^^^^
854 To generate a PCH file using Clang, one invokes Clang with the
855 :option:`-x <language>-header` option. This mirrors the interface in GCC
856 for generating PCH files:
858 .. code-block:: console
860 $ gcc -x c-header test.h -o test.h.gch
861 $ clang -x c-header test.h -o test.h.pch
866 A PCH file can then be used as a prefix header when a :option:`-include`
867 option is passed to ``clang``:
869 .. code-block:: console
871 $ clang -include test.h test.c -o test
873 The ``clang`` driver will first check if a PCH file for ``test.h`` is
874 available; if so, the contents of ``test.h`` (and the files it includes)
875 will be processed from the PCH file. Otherwise, Clang falls back to
876 directly processing the content of ``test.h``. This mirrors the behavior
881 Clang does *not* automatically use PCH files for headers that are directly
882 included within a source file. For example:
884 .. code-block:: console
886 $ clang -x c-header test.h -o test.h.pch
889 $ clang test.c -o test
891 In this example, ``clang`` will not automatically use the PCH file for
892 ``test.h`` since ``test.h`` was included directly in the source file and not
893 specified on the command line using :option:`-include`.
895 Relocatable PCH Files
896 ^^^^^^^^^^^^^^^^^^^^^
898 It is sometimes necessary to build a precompiled header from headers
899 that are not yet in their final, installed locations. For example, one
900 might build a precompiled header within the build tree that is then
901 meant to be installed alongside the headers. Clang permits the creation
902 of "relocatable" precompiled headers, which are built with a given path
903 (into the build directory) and can later be used from an installed
906 To build a relocatable precompiled header, place your headers into a
907 subdirectory whose structure mimics the installed location. For example,
908 if you want to build a precompiled header for the header ``mylib.h``
909 that will be installed into ``/usr/include``, create a subdirectory
910 ``build/usr/include`` and place the header ``mylib.h`` into that
911 subdirectory. If ``mylib.h`` depends on other headers, then they can be
912 stored within ``build/usr/include`` in a way that mimics the installed
915 Building a relocatable precompiled header requires two additional
916 arguments. First, pass the ``--relocatable-pch`` flag to indicate that
917 the resulting PCH file should be relocatable. Second, pass
918 :option:`-isysroot /path/to/build`, which makes all includes for your library
919 relative to the build directory. For example:
921 .. code-block:: console
923 # clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
925 When loading the relocatable PCH file, the various headers used in the
926 PCH file are found from the system header root. For example, ``mylib.h``
927 can be found in ``/usr/include/mylib.h``. If the headers are installed
928 in some other system root, the :option:`-isysroot` option can be used provide
929 a different system root from which the headers will be based. For
930 example, :option:`-isysroot /Developer/SDKs/MacOSX10.4u.sdk` will look for
931 ``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``.
933 Relocatable precompiled headers are intended to be used in a limited
934 number of cases where the compilation environment is tightly controlled
935 and the precompiled header cannot be generated after headers have been
938 .. _controlling-code-generation:
940 Controlling Code Generation
941 ---------------------------
943 Clang provides a number of ways to control code generation. The options
946 **-f[no-]sanitize=check1,check2,...**
947 Turn on runtime checks for various forms of undefined or suspicious
950 This option controls whether Clang adds runtime checks for various
951 forms of undefined or suspicious behavior, and is disabled by
952 default. If a check fails, a diagnostic message is produced at
953 runtime explaining the problem. The main checks are:
955 - .. _opt_fsanitize_address:
957 ``-fsanitize=address``:
958 :doc:`AddressSanitizer`, a memory error
960 - .. _opt_fsanitize_thread:
962 ``-fsanitize=thread``: :doc:`ThreadSanitizer`, a data race detector.
963 - .. _opt_fsanitize_memory:
965 ``-fsanitize=memory``: :doc:`MemorySanitizer`,
966 a detector of uninitialized reads. Requires instrumentation of all
968 - .. _opt_fsanitize_undefined:
970 ``-fsanitize=undefined``: :doc:`UndefinedBehaviorSanitizer`,
971 a fast and compatible undefined behavior checker.
973 - ``-fsanitize=dataflow``: :doc:`DataFlowSanitizer`, a general data
975 - ``-fsanitize=cfi``: :doc:`control flow integrity <ControlFlowIntegrity>`
976 checks. Requires ``-flto``.
977 - ``-fsanitize=safe-stack``: :doc:`safe stack <SafeStack>`
978 protection against stack-based memory corruption errors.
980 There are more fine-grained checks available: see
981 the :ref:`list <ubsan-checks>` of specific kinds of
982 undefined behavior that can be detected and the :ref:`list <cfi-schemes>`
983 of control flow integrity schemes.
985 The ``-fsanitize=`` argument must also be provided when linking, in
986 order to link to the appropriate runtime library.
988 It is not possible to combine more than one of the ``-fsanitize=address``,
989 ``-fsanitize=thread``, and ``-fsanitize=memory`` checkers in the same
992 **-f[no-]sanitize-recover=check1,check2,...**
994 **-f[no-]sanitize-recover=all**
996 Controls which checks enabled by ``-fsanitize=`` flag are non-fatal.
997 If the check is fatal, program will halt after the first error
998 of this kind is detected and error report is printed.
1000 By default, non-fatal checks are those enabled by
1001 :doc:`UndefinedBehaviorSanitizer`,
1002 except for ``-fsanitize=return`` and ``-fsanitize=unreachable``. Some
1003 sanitizers may not support recovery (or not support it by default
1004 e.g. :doc:`AddressSanitizer`), and always crash the program after the issue
1007 Note that the ``-fsanitize-trap`` flag has precedence over this flag.
1008 This means that if a check has been configured to trap elsewhere on the
1009 command line, or if the check traps by default, this flag will not have
1010 any effect unless that sanitizer's trapping behavior is disabled with
1011 ``-fno-sanitize-trap``.
1013 For example, if a command line contains the flags ``-fsanitize=undefined
1014 -fsanitize-trap=undefined``, the flag ``-fsanitize-recover=alignment``
1015 will have no effect on its own; it will need to be accompanied by
1016 ``-fno-sanitize-trap=alignment``.
1018 **-f[no-]sanitize-trap=check1,check2,...**
1020 Controls which checks enabled by the ``-fsanitize=`` flag trap. This
1021 option is intended for use in cases where the sanitizer runtime cannot
1022 be used (for instance, when building libc or a kernel module), or where
1023 the binary size increase caused by the sanitizer runtime is a concern.
1025 This flag is only compatible with :doc:`control flow integrity
1026 <ControlFlowIntegrity>` schemes and :doc:`UndefinedBehaviorSanitizer`
1027 checks other than ``vptr``. If this flag
1028 is supplied together with ``-fsanitize=undefined``, the ``vptr`` sanitizer
1029 will be implicitly disabled.
1031 This flag is enabled by default for sanitizers in the ``cfi`` group.
1033 .. option:: -fsanitize-blacklist=/path/to/blacklist/file
1035 Disable or modify sanitizer checks for objects (source files, functions,
1036 variables, types) listed in the file. See
1037 :doc:`SanitizerSpecialCaseList` for file format description.
1039 .. option:: -fno-sanitize-blacklist
1041 Don't use blacklist file, if it was specified earlier in the command line.
1043 **-f[no-]sanitize-coverage=[type,features,...]**
1045 Enable simple code coverage in addition to certain sanitizers.
1046 See :doc:`SanitizerCoverage` for more details.
1048 **-f[no-]sanitize-stats**
1050 Enable simple statistics gathering for the enabled sanitizers.
1051 See :doc:`SanitizerStats` for more details.
1053 .. option:: -fsanitize-undefined-trap-on-error
1055 Deprecated alias for ``-fsanitize-trap=undefined``.
1057 .. option:: -fsanitize-cfi-cross-dso
1059 Enable cross-DSO control flow integrity checks. This flag modifies
1060 the behavior of sanitizers in the ``cfi`` group to allow checking
1061 of cross-DSO virtual and indirect calls.
1063 .. option:: -ffast-math
1065 Enable fast-math mode. This defines the ``__FAST_MATH__`` preprocessor
1066 macro, and lets the compiler make aggressive, potentially-lossy assumptions
1067 about floating-point math. These include:
1069 * Floating-point math obeys regular algebraic rules for real numbers (e.g.
1070 ``+`` and ``*`` are associative, ``x/y == x * (1/y)``, and
1071 ``(a + b) * c == a * c + b * c``),
1072 * operands to floating-point operations are not equal to ``NaN`` and
1074 * ``+0`` and ``-0`` are interchangeable.
1076 .. option:: -fwhole-program-vtables
1078 Enable whole-program vtable optimizations, such as single-implementation
1079 devirtualization and virtual constant propagation, for classes with
1080 :doc:`hidden LTO visibility <LTOVisibility>`. Requires ``-flto``.
1082 .. option:: -fno-assume-sane-operator-new
1084 Don't assume that the C++'s new operator is sane.
1086 This option tells the compiler to do not assume that C++'s global
1087 new operator will always return a pointer that does not alias any
1088 other pointer when the function returns.
1090 .. option:: -ftrap-function=[name]
1092 Instruct code generator to emit a function call to the specified
1093 function name for ``__builtin_trap()``.
1095 LLVM code generator translates ``__builtin_trap()`` to a trap
1096 instruction if it is supported by the target ISA. Otherwise, the
1097 builtin is translated into a call to ``abort``. If this option is
1098 set, then the code generator will always lower the builtin to a call
1099 to the specified function regardless of whether the target ISA has a
1100 trap instruction. This option is useful for environments (e.g.
1101 deeply embedded) where a trap cannot be properly handled, or when
1102 some custom behavior is desired.
1104 .. option:: -ftls-model=[model]
1106 Select which TLS model to use.
1108 Valid values are: ``global-dynamic``, ``local-dynamic``,
1109 ``initial-exec`` and ``local-exec``. The default value is
1110 ``global-dynamic``. The compiler may use a different model if the
1111 selected model is not supported by the target, or if a more
1112 efficient model can be used. The TLS model can be overridden per
1113 variable using the ``tls_model`` attribute.
1115 .. option:: -femulated-tls
1117 Select emulated TLS model, which overrides all -ftls-model choices.
1119 In emulated TLS mode, all access to TLS variables are converted to
1120 calls to __emutls_get_address in the runtime library.
1122 .. option:: -mhwdiv=[values]
1124 Select the ARM modes (arm or thumb) that support hardware division
1127 Valid values are: ``arm``, ``thumb`` and ``arm,thumb``.
1128 This option is used to indicate which mode (arm or thumb) supports
1129 hardware division instructions. This only applies to the ARM
1132 .. option:: -m[no-]crc
1134 Enable or disable CRC instructions.
1136 This option is used to indicate whether CRC instructions are to
1137 be generated. This only applies to the ARM architecture.
1139 CRC instructions are enabled by default on ARMv8.
1141 .. option:: -mgeneral-regs-only
1143 Generate code which only uses the general purpose registers.
1145 This option restricts the generated code to use general registers
1146 only. This only applies to the AArch64 architecture.
1148 .. option:: -mcompact-branches=[values]
1150 Control the usage of compact branches for MIPSR6.
1152 Valid values are: ``never``, ``optimal`` and ``always``.
1153 The default value is ``optimal`` which generates compact branches
1154 when a delay slot cannot be filled. ``never`` disables the usage of
1155 compact branches and ``always`` generates compact branches whenever
1158 **-f[no-]max-type-align=[number]**
1159 Instruct the code generator to not enforce a higher alignment than the given
1160 number (of bytes) when accessing memory via an opaque pointer or reference.
1161 This cap is ignored when directly accessing a variable or when the pointee
1162 type has an explicit “aligned” attribute.
1164 The value should usually be determined by the properties of the system allocator.
1165 Some builtin types, especially vector types, have very high natural alignments;
1166 when working with values of those types, Clang usually wants to use instructions
1167 that take advantage of that alignment. However, many system allocators do
1168 not promise to return memory that is more than 8-byte or 16-byte-aligned. Use
1169 this option to limit the alignment that the compiler can assume for an arbitrary
1170 pointer, which may point onto the heap.
1172 This option does not affect the ABI alignment of types; the layout of structs and
1173 unions and the value returned by the alignof operator remain the same.
1175 This option can be overridden on a case-by-case basis by putting an explicit
1176 “aligned” alignment on a struct, union, or typedef. For example:
1178 .. code-block:: console
1180 #include <immintrin.h>
1181 // Make an aligned typedef of the AVX-512 16-int vector type.
1182 typedef __v16si __aligned_v16si __attribute__((aligned(64)));
1184 void initialize_vector(__aligned_v16si *v) {
1185 // The compiler may assume that ‘v’ is 64-byte aligned, regardless of the
1186 // value of -fmax-type-align.
1190 Profile Guided Optimization
1191 ---------------------------
1193 Profile information enables better optimization. For example, knowing that a
1194 branch is taken very frequently helps the compiler make better decisions when
1195 ordering basic blocks. Knowing that a function ``foo`` is called more
1196 frequently than another function ``bar`` helps the inliner.
1198 Clang supports profile guided optimization with two different kinds of
1199 profiling. A sampling profiler can generate a profile with very low runtime
1200 overhead, or you can build an instrumented version of the code that collects
1201 more detailed profile information. Both kinds of profiles can provide execution
1202 counts for instructions in the code and information on branches taken and
1203 function invocation.
1205 Regardless of which kind of profiling you use, be careful to collect profiles
1206 by running your code with inputs that are representative of the typical
1207 behavior. Code that is not exercised in the profile will be optimized as if it
1208 is unimportant, and the compiler may make poor optimization choices for code
1209 that is disproportionately used while profiling.
1211 Differences Between Sampling and Instrumentation
1212 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1214 Although both techniques are used for similar purposes, there are important
1215 differences between the two:
1217 1. Profile data generated with one cannot be used by the other, and there is no
1218 conversion tool that can convert one to the other. So, a profile generated
1219 via ``-fprofile-instr-generate`` must be used with ``-fprofile-instr-use``.
1220 Similarly, sampling profiles generated by external profilers must be
1221 converted and used with ``-fprofile-sample-use``.
1223 2. Instrumentation profile data can be used for code coverage analysis and
1226 3. Sampling profiles can only be used for optimization. They cannot be used for
1227 code coverage analysis. Although it would be technically possible to use
1228 sampling profiles for code coverage, sample-based profiles are too
1229 coarse-grained for code coverage purposes; it would yield poor results.
1231 4. Sampling profiles must be generated by an external tool. The profile
1232 generated by that tool must then be converted into a format that can be read
1233 by LLVM. The section on sampling profilers describes one of the supported
1234 sampling profile formats.
1237 Using Sampling Profilers
1238 ^^^^^^^^^^^^^^^^^^^^^^^^
1240 Sampling profilers are used to collect runtime information, such as
1241 hardware counters, while your application executes. They are typically
1242 very efficient and do not incur a large runtime overhead. The
1243 sample data collected by the profiler can be used during compilation
1244 to determine what the most executed areas of the code are.
1246 Using the data from a sample profiler requires some changes in the way
1247 a program is built. Before the compiler can use profiling information,
1248 the code needs to execute under the profiler. The following is the
1249 usual build cycle when using sample profilers for optimization:
1251 1. Build the code with source line table information. You can use all the
1252 usual build flags that you always build your application with. The only
1253 requirement is that you add ``-gline-tables-only`` or ``-g`` to the
1254 command line. This is important for the profiler to be able to map
1255 instructions back to source line locations.
1257 .. code-block:: console
1259 $ clang++ -O2 -gline-tables-only code.cc -o code
1261 2. Run the executable under a sampling profiler. The specific profiler
1262 you use does not really matter, as long as its output can be converted
1263 into the format that the LLVM optimizer understands. Currently, there
1264 exists a conversion tool for the Linux Perf profiler
1265 (https://perf.wiki.kernel.org/), so these examples assume that you
1266 are using Linux Perf to profile your code.
1268 .. code-block:: console
1270 $ perf record -b ./code
1272 Note the use of the ``-b`` flag. This tells Perf to use the Last Branch
1273 Record (LBR) to record call chains. While this is not strictly required,
1274 it provides better call information, which improves the accuracy of
1277 3. Convert the collected profile data to LLVM's sample profile format.
1278 This is currently supported via the AutoFDO converter ``create_llvm_prof``.
1279 It is available at http://github.com/google/autofdo. Once built and
1280 installed, you can convert the ``perf.data`` file to LLVM using
1283 .. code-block:: console
1285 $ create_llvm_prof --binary=./code --out=code.prof
1287 This will read ``perf.data`` and the binary file ``./code`` and emit
1288 the profile data in ``code.prof``. Note that if you ran ``perf``
1289 without the ``-b`` flag, you need to use ``--use_lbr=false`` when
1290 calling ``create_llvm_prof``.
1292 4. Build the code again using the collected profile. This step feeds
1293 the profile back to the optimizers. This should result in a binary
1294 that executes faster than the original one. Note that you are not
1295 required to build the code with the exact same arguments that you
1296 used in the first step. The only requirement is that you build the code
1297 with ``-gline-tables-only`` and ``-fprofile-sample-use``.
1299 .. code-block:: console
1301 $ clang++ -O2 -gline-tables-only -fprofile-sample-use=code.prof code.cc -o code
1304 Sample Profile Formats
1305 """"""""""""""""""""""
1307 Since external profilers generate profile data in a variety of custom formats,
1308 the data generated by the profiler must be converted into a format that can be
1309 read by the backend. LLVM supports three different sample profile formats:
1311 1. ASCII text. This is the easiest one to generate. The file is divided into
1312 sections, which correspond to each of the functions with profile
1313 information. The format is described below. It can also be generated from
1314 the binary or gcov formats using the ``llvm-profdata`` tool.
1316 2. Binary encoding. This uses a more efficient encoding that yields smaller
1317 profile files. This is the format generated by the ``create_llvm_prof`` tool
1318 in http://github.com/google/autofdo.
1320 3. GCC encoding. This is based on the gcov format, which is accepted by GCC. It
1321 is only interesting in environments where GCC and Clang co-exist. This
1322 encoding is only generated by the ``create_gcov`` tool in
1323 http://github.com/google/autofdo. It can be read by LLVM and
1324 ``llvm-profdata``, but it cannot be generated by either.
1326 If you are using Linux Perf to generate sampling profiles, you can use the
1327 conversion tool ``create_llvm_prof`` described in the previous section.
1328 Otherwise, you will need to write a conversion tool that converts your
1329 profiler's native format into one of these three.
1332 Sample Profile Text Format
1333 """"""""""""""""""""""""""
1335 This section describes the ASCII text format for sampling profiles. It is,
1336 arguably, the easiest one to generate. If you are interested in generating any
1337 of the other two, consult the ``ProfileData`` library in in LLVM's source tree
1338 (specifically, ``include/llvm/ProfileData/SampleProfReader.h``).
1340 .. code-block:: console
1342 function1:total_samples:total_head_samples
1343 offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ]
1344 offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ]
1346 offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]
1347 offsetA[.discriminator]: fnA:num_of_total_samples
1348 offsetA1[.discriminator]: number_of_samples [fn7:num fn8:num ... ]
1349 offsetA1[.discriminator]: number_of_samples [fn9:num fn10:num ... ]
1350 offsetB[.discriminator]: fnB:num_of_total_samples
1351 offsetB1[.discriminator]: number_of_samples [fn11:num fn12:num ... ]
1353 This is a nested tree in which the identation represents the nesting level
1354 of the inline stack. There are no blank lines in the file. And the spacing
1355 within a single line is fixed. Additional spaces will result in an error
1356 while reading the file.
1358 Any line starting with the '#' character is completely ignored.
1360 Inlined calls are represented with indentation. The Inline stack is a
1361 stack of source locations in which the top of the stack represents the
1362 leaf function, and the bottom of the stack represents the actual
1363 symbol to which the instruction belongs.
1365 Function names must be mangled in order for the profile loader to
1366 match them in the current translation unit. The two numbers in the
1367 function header specify how many total samples were accumulated in the
1368 function (first number), and the total number of samples accumulated
1369 in the prologue of the function (second number). This head sample
1370 count provides an indicator of how frequently the function is invoked.
1372 There are two types of lines in the function body.
1374 - Sampled line represents the profile information of a source location.
1375 ``offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]``
1377 - Callsite line represents the profile information of an inlined callsite.
1378 ``offsetA[.discriminator]: fnA:num_of_total_samples``
1380 Each sampled line may contain several items. Some are optional (marked
1383 a. Source line offset. This number represents the line number
1384 in the function where the sample was collected. The line number is
1385 always relative to the line where symbol of the function is
1386 defined. So, if the function has its header at line 280, the offset
1387 13 is at line 293 in the file.
1389 Note that this offset should never be a negative number. This could
1390 happen in cases like macros. The debug machinery will register the
1391 line number at the point of macro expansion. So, if the macro was
1392 expanded in a line before the start of the function, the profile
1393 converter should emit a 0 as the offset (this means that the optimizers
1394 will not be able to associate a meaningful weight to the instructions
1397 b. [OPTIONAL] Discriminator. This is used if the sampled program
1398 was compiled with DWARF discriminator support
1399 (http://wiki.dwarfstd.org/index.php?title=Path_Discriminators).
1400 DWARF discriminators are unsigned integer values that allow the
1401 compiler to distinguish between multiple execution paths on the
1402 same source line location.
1404 For example, consider the line of code ``if (cond) foo(); else bar();``.
1405 If the predicate ``cond`` is true 80% of the time, then the edge
1406 into function ``foo`` should be considered to be taken most of the
1407 time. But both calls to ``foo`` and ``bar`` are at the same source
1408 line, so a sample count at that line is not sufficient. The
1409 compiler needs to know which part of that line is taken more
1412 This is what discriminators provide. In this case, the calls to
1413 ``foo`` and ``bar`` will be at the same line, but will have
1414 different discriminator values. This allows the compiler to correctly
1415 set edge weights into ``foo`` and ``bar``.
1417 c. Number of samples. This is an integer quantity representing the
1418 number of samples collected by the profiler at this source
1421 d. [OPTIONAL] Potential call targets and samples. If present, this
1422 line contains a call instruction. This models both direct and
1423 number of samples. For example,
1425 .. code-block:: console
1427 130: 7 foo:3 bar:2 baz:7
1429 The above means that at relative line offset 130 there is a call
1430 instruction that calls one of ``foo()``, ``bar()`` and ``baz()``,
1431 with ``baz()`` being the relatively more frequently called target.
1433 As an example, consider a program with the call chain ``main -> foo -> bar``.
1434 When built with optimizations enabled, the compiler may inline the
1435 calls to ``bar`` and ``foo`` inside ``main``. The generated profile
1436 could then be something like this:
1438 .. code-block:: console
1446 This profile indicates that there were a total of 35,504 samples
1447 collected in main. All of those were at line 1 (the call to ``foo``).
1448 Of those, 31,977 were spent inside the body of ``bar``. The last line
1449 of the profile (``2: 0``) corresponds to line 2 inside ``main``. No
1450 samples were collected there.
1452 Profiling with Instrumentation
1453 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1455 Clang also supports profiling via instrumentation. This requires building a
1456 special instrumented version of the code and has some runtime
1457 overhead during the profiling, but it provides more detailed results than a
1458 sampling profiler. It also provides reproducible results, at least to the
1459 extent that the code behaves consistently across runs.
1461 Here are the steps for using profile guided optimization with
1464 1. Build an instrumented version of the code by compiling and linking with the
1465 ``-fprofile-instr-generate`` option.
1467 .. code-block:: console
1469 $ clang++ -O2 -fprofile-instr-generate code.cc -o code
1471 2. Run the instrumented executable with inputs that reflect the typical usage.
1472 By default, the profile data will be written to a ``default.profraw`` file
1473 in the current directory. You can override that default by setting the
1474 ``LLVM_PROFILE_FILE`` environment variable to specify an alternate file.
1475 Any instance of ``%p`` in that file name will be replaced by the process
1476 ID, so that you can easily distinguish the profile output from multiple
1479 .. code-block:: console
1481 $ LLVM_PROFILE_FILE="code-%p.profraw" ./code
1483 3. Combine profiles from multiple runs and convert the "raw" profile format to
1484 the input expected by clang. Use the ``merge`` command of the
1485 ``llvm-profdata`` tool to do this.
1487 .. code-block:: console
1489 $ llvm-profdata merge -output=code.profdata code-*.profraw
1491 Note that this step is necessary even when there is only one "raw" profile,
1492 since the merge operation also changes the file format.
1494 4. Build the code again using the ``-fprofile-instr-use`` option to specify the
1495 collected profile data.
1497 .. code-block:: console
1499 $ clang++ -O2 -fprofile-instr-use=code.profdata code.cc -o code
1501 You can repeat step 4 as often as you like without regenerating the
1502 profile. As you make changes to your code, clang may no longer be able to
1503 use the profile data. It will warn you when this happens.
1505 Profile generation and use can also be controlled by the GCC-compatible flags
1506 ``-fprofile-generate`` and ``-fprofile-use``. Although these flags are
1507 semantically equivalent to their GCC counterparts, they *do not* handle
1508 GCC-compatible profiles. They are only meant to implement GCC's semantics
1509 with respect to profile creation and use.
1511 .. option:: -fprofile-generate[=<dirname>]
1513 Without any other arguments, ``-fprofile-generate`` behaves identically to
1514 ``-fprofile-instr-generate``. When given a directory name, it generates the
1515 profile file ``default.profraw`` in the directory named ``dirname``. If
1516 ``dirname`` does not exist, it will be created at runtime. The environment
1517 variable ``LLVM_PROFILE_FILE`` can be used to override the directory and
1518 filename for the profile file at runtime. For example,
1520 .. code-block:: console
1522 $ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code
1524 When ``code`` is executed, the profile will be written to the file
1525 ``yyy/zzz/default.profraw``. This can be altered at runtime via the
1526 ``LLVM_PROFILE_FILE`` environment variable:
1528 .. code-block:: console
1530 $ LLVM_PROFILE_FILE=/tmp/myprofile/code.profraw ./code
1532 The above invocation will produce the profile file
1533 ``/tmp/myprofile/code.profraw`` instead of ``yyy/zzz/default.profraw``.
1534 Notice that ``LLVM_PROFILE_FILE`` overrides the directory *and* the file
1535 name for the profile file.
1537 .. option:: -fprofile-use[=<pathname>]
1539 Without any other arguments, ``-fprofile-use`` behaves identically to
1540 ``-fprofile-instr-use``. Otherwise, if ``pathname`` is the full path to a
1541 profile file, it reads from that file. If ``pathname`` is a directory name,
1542 it reads from ``pathname/default.profdata``.
1544 Disabling Instrumentation
1545 ^^^^^^^^^^^^^^^^^^^^^^^^^
1547 In certain situations, it may be useful to disable profile generation or use
1548 for specific files in a build, without affecting the main compilation flags
1549 used for the other files in the project.
1551 In these cases, you can use the flag ``-fno-profile-instr-generate`` (or
1552 ``-fno-profile-generate``) to disable profile generation, and
1553 ``-fno-profile-instr-use`` (or ``-fno-profile-use``) to disable profile use.
1555 Note that these flags should appear after the corresponding profile
1556 flags to have an effect.
1558 Controlling Debug Information
1559 -----------------------------
1561 Controlling Size of Debug Information
1562 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1564 Debug info kind generated by Clang can be set by one of the flags listed
1565 below. If multiple flags are present, the last one is used.
1569 Don't generate any debug info (default).
1571 .. option:: -gline-tables-only
1573 Generate line number tables only.
1575 This kind of debug info allows to obtain stack traces with function names,
1576 file names and line numbers (by such tools as ``gdb`` or ``addr2line``). It
1577 doesn't contain any other data (e.g. description of local variables or
1578 function parameters).
1580 .. option:: -fstandalone-debug
1582 Clang supports a number of optimizations to reduce the size of debug
1583 information in the binary. They work based on the assumption that
1584 the debug type information can be spread out over multiple
1585 compilation units. For instance, Clang will not emit type
1586 definitions for types that are not needed by a module and could be
1587 replaced with a forward declaration. Further, Clang will only emit
1588 type info for a dynamic C++ class in the module that contains the
1589 vtable for the class.
1591 The **-fstandalone-debug** option turns off these optimizations.
1592 This is useful when working with 3rd-party libraries that don't come
1593 with debug information. Note that Clang will never emit type
1594 information for types that are not referenced at all by the program.
1596 .. option:: -fno-standalone-debug
1598 On Darwin **-fstandalone-debug** is enabled by default. The
1599 **-fno-standalone-debug** option can be used to get to turn on the
1600 vtable-based optimization described above.
1604 Generate complete debug info.
1606 Controlling Debugger "Tuning"
1607 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1609 While Clang generally emits standard DWARF debug info (http://dwarfstd.org),
1610 different debuggers may know how to take advantage of different specific DWARF
1611 features. You can "tune" the debug info for one of several different debuggers.
1613 .. option:: -ggdb, -glldb, -gsce
1615 Tune the debug info for the ``gdb``, ``lldb``, or Sony Computer Entertainment
1616 debugger, respectively. Each of these options implies **-g**. (Therefore, if
1617 you want both **-gline-tables-only** and debugger tuning, the tuning option
1621 Comment Parsing Options
1622 -----------------------
1624 Clang parses Doxygen and non-Doxygen style documentation comments and attaches
1625 them to the appropriate declaration nodes. By default, it only parses
1626 Doxygen-style comments and ignores ordinary comments starting with ``//`` and
1629 .. option:: -Wdocumentation
1631 Emit warnings about use of documentation comments. This warning group is off
1634 This includes checking that ``\param`` commands name parameters that actually
1635 present in the function signature, checking that ``\returns`` is used only on
1636 functions that actually return a value etc.
1638 .. option:: -Wno-documentation-unknown-command
1640 Don't warn when encountering an unknown Doxygen command.
1642 .. option:: -fparse-all-comments
1644 Parse all comments as documentation comments (including ordinary comments
1645 starting with ``//`` and ``/*``).
1647 .. option:: -fcomment-block-commands=[commands]
1649 Define custom documentation commands as block commands. This allows Clang to
1650 construct the correct AST for these custom commands, and silences warnings
1651 about unknown commands. Several commands must be separated by a comma
1652 *without trailing space*; e.g. ``-fcomment-block-commands=foo,bar`` defines
1653 custom commands ``\foo`` and ``\bar``.
1655 It is also possible to use ``-fcomment-block-commands`` several times; e.g.
1656 ``-fcomment-block-commands=foo -fcomment-block-commands=bar`` does the same
1664 The support for standard C in clang is feature-complete except for the
1665 C99 floating-point pragmas.
1667 Extensions supported by clang
1668 -----------------------------
1670 See :doc:`LanguageExtensions`.
1672 Differences between various standard modes
1673 ------------------------------------------
1675 clang supports the -std option, which changes what language mode clang
1676 uses. The supported modes for C are c89, gnu89, c94, c99, gnu99, c11,
1677 gnu11, and various aliases for those modes. If no -std option is
1678 specified, clang defaults to gnu11 mode. Many C99 and C11 features are
1679 supported in earlier modes as a conforming extension, with a warning. Use
1680 ``-pedantic-errors`` to request an error if a feature from a later standard
1681 revision is used in an earlier mode.
1683 Differences between all ``c*`` and ``gnu*`` modes:
1685 - ``c*`` modes define "``__STRICT_ANSI__``".
1686 - Target-specific defines not prefixed by underscores, like "linux",
1687 are defined in ``gnu*`` modes.
1688 - Trigraphs default to being off in ``gnu*`` modes; they can be enabled by
1689 the -trigraphs option.
1690 - The parser recognizes "asm" and "typeof" as keywords in ``gnu*`` modes;
1691 the variants "``__asm__``" and "``__typeof__``" are recognized in all
1693 - The Apple "blocks" extension is recognized by default in ``gnu*`` modes
1694 on some platforms; it can be enabled in any mode with the "-fblocks"
1696 - Arrays that are VLA's according to the standard, but which can be
1697 constant folded by the frontend are treated as fixed size arrays.
1698 This occurs for things like "int X[(1, 2)];", which is technically a
1699 VLA. ``c*`` modes are strictly compliant and treat these as VLAs.
1701 Differences between ``*89`` and ``*99`` modes:
1703 - The ``*99`` modes default to implementing "inline" as specified in C99,
1704 while the ``*89`` modes implement the GNU version. This can be
1705 overridden for individual functions with the ``__gnu_inline__``
1707 - Digraphs are not recognized in c89 mode.
1708 - The scope of names defined inside a "for", "if", "switch", "while",
1709 or "do" statement is different. (example: "``if ((struct x {int
1711 - ``__STDC_VERSION__`` is not defined in ``*89`` modes.
1712 - "inline" is not recognized as a keyword in c89 mode.
1713 - "restrict" is not recognized as a keyword in ``*89`` modes.
1714 - Commas are allowed in integer constant expressions in ``*99`` modes.
1715 - Arrays which are not lvalues are not implicitly promoted to pointers
1717 - Some warnings are different.
1719 Differences between ``*99`` and ``*11`` modes:
1721 - Warnings for use of C11 features are disabled.
1722 - ``__STDC_VERSION__`` is defined to ``201112L`` rather than ``199901L``.
1724 c94 mode is identical to c89 mode except that digraphs are enabled in
1725 c94 mode (FIXME: And ``__STDC_VERSION__`` should be defined!).
1727 GCC extensions not implemented yet
1728 ----------------------------------
1730 clang tries to be compatible with gcc as much as possible, but some gcc
1731 extensions are not implemented yet:
1733 - clang does not support decimal floating point types (``_Decimal32`` and
1734 friends) or fixed-point types (``_Fract`` and friends); nobody has
1735 expressed interest in these features yet, so it's hard to say when
1736 they will be implemented.
1737 - clang does not support nested functions; this is a complex feature
1738 which is infrequently used, so it is unlikely to be implemented
1739 anytime soon. In C++11 it can be emulated by assigning lambda
1740 functions to local variables, e.g:
1744 auto const local_function = [&](int parameter) {
1750 - clang does not support static initialization of flexible array
1751 members. This appears to be a rarely used extension, but could be
1752 implemented pending user demand.
1753 - clang does not support
1754 ``__builtin_va_arg_pack``/``__builtin_va_arg_pack_len``. This is
1755 used rarely, but in some potentially interesting places, like the
1756 glibc headers, so it may be implemented pending user demand. Note
1757 that because clang pretends to be like GCC 4.2, and this extension
1758 was introduced in 4.3, the glibc headers will not try to use this
1759 extension with clang at the moment.
1760 - clang does not support the gcc extension for forward-declaring
1761 function parameters; this has not shown up in any real-world code
1762 yet, though, so it might never be implemented.
1764 This is not a complete list; if you find an unsupported extension
1765 missing from this list, please send an e-mail to cfe-dev. This list
1766 currently excludes C++; see :ref:`C++ Language Features <cxx>`. Also, this
1767 list does not include bugs in mostly-implemented features; please see
1769 tracker <http://llvm.org/bugs/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer>`_
1770 for known existing bugs (FIXME: Is there a section for bug-reporting
1771 guidelines somewhere?).
1773 Intentionally unsupported GCC extensions
1774 ----------------------------------------
1776 - clang does not support the gcc extension that allows variable-length
1777 arrays in structures. This is for a few reasons: one, it is tricky to
1778 implement, two, the extension is completely undocumented, and three,
1779 the extension appears to be rarely used. Note that clang *does*
1780 support flexible array members (arrays with a zero or unspecified
1781 size at the end of a structure).
1782 - clang does not have an equivalent to gcc's "fold"; this means that
1783 clang doesn't accept some constructs gcc might accept in contexts
1784 where a constant expression is required, like "x-x" where x is a
1786 - clang does not support ``__builtin_apply`` and friends; this extension
1787 is extremely obscure and difficult to implement reliably.
1791 Microsoft extensions
1792 --------------------
1794 clang has support for many extensions from Microsoft Visual C++. To enable these
1795 extensions, use the ``-fms-extensions`` command-line option. This is the default
1796 for Windows targets. Clang does not implement every pragma or declspec provided
1797 by MSVC, but the popular ones, such as ``__declspec(dllexport)`` and ``#pragma
1798 comment(lib)`` are well supported.
1800 clang has a ``-fms-compatibility`` flag that makes clang accept enough
1801 invalid C++ to be able to parse most Microsoft headers. For example, it
1802 allows `unqualified lookup of dependent base class members
1803 <http://clang.llvm.org/compatibility.html#dep_lookup_bases>`_, which is
1804 a common compatibility issue with clang. This flag is enabled by default
1805 for Windows targets.
1807 ``-fdelayed-template-parsing`` lets clang delay parsing of function template
1808 definitions until the end of a translation unit. This flag is enabled by
1809 default for Windows targets.
1811 For compatibility with existing code that compiles with MSVC, clang defines the
1812 ``_MSC_VER`` and ``_MSC_FULL_VER`` macros. These default to the values of 1800
1813 and 180000000 respectively, making clang look like an early release of Visual
1814 C++ 2013. The ``-fms-compatibility-version=`` flag overrides these values. It
1815 accepts a dotted version tuple, such as 19.00.23506. Changing the MSVC
1816 compatibility version makes clang behave more like that version of MSVC. For
1817 example, ``-fms-compatibility-version=19`` will enable C++14 features and define
1818 ``char16_t`` and ``char32_t`` as builtin types.
1822 C++ Language Features
1823 =====================
1825 clang fully implements all of standard C++98 except for exported
1826 templates (which were removed in C++11), and all of standard C++11
1827 and the current draft standard for C++1y.
1829 Controlling implementation limits
1830 ---------------------------------
1832 .. option:: -fbracket-depth=N
1834 Sets the limit for nested parentheses, brackets, and braces to N. The
1837 .. option:: -fconstexpr-depth=N
1839 Sets the limit for recursive constexpr function invocations to N. The
1842 .. option:: -ftemplate-depth=N
1844 Sets the limit for recursively nested template instantiations to N. The
1847 .. option:: -foperator-arrow-depth=N
1849 Sets the limit for iterative calls to 'operator->' functions to N. The
1854 Objective-C Language Features
1855 =============================
1859 Objective-C++ Language Features
1860 ===============================
1867 Clang supports all OpenMP 3.1 directives and clauses. In addition, some
1868 features of OpenMP 4.0 are supported. For example, ``#pragma omp simd``,
1869 ``#pragma omp for simd``, ``#pragma omp parallel for simd`` directives, extended
1870 set of atomic constructs, ``proc_bind`` clause for all parallel-based
1871 directives, ``depend`` clause for ``#pragma omp task`` directive (except for
1872 array sections), ``#pragma omp cancel`` and ``#pragma omp cancellation point``
1873 directives, and ``#pragma omp taskgroup`` directive.
1875 Use :option:`-fopenmp` to enable OpenMP. Support for OpenMP can be disabled with
1876 :option:`-fno-openmp`.
1878 Controlling implementation limits
1879 ---------------------------------
1881 .. option:: -fopenmp-use-tls
1883 Controls code generation for OpenMP threadprivate variables. In presence of
1884 this option all threadprivate variables are generated the same way as thread
1885 local variables, using TLS support. If :option:`-fno-openmp-use-tls`
1886 is provided or target does not support TLS, code generation for threadprivate
1887 variables relies on OpenMP runtime library.
1889 .. _target_features:
1891 Target-Specific Features and Limitations
1892 ========================================
1894 CPU Architectures Features and Limitations
1895 ------------------------------------------
1900 The support for X86 (both 32-bit and 64-bit) is considered stable on
1901 Darwin (Mac OS X), Linux, FreeBSD, and Dragonfly BSD: it has been tested
1902 to correctly compile many large C, C++, Objective-C, and Objective-C++
1905 On ``x86_64-mingw32``, passing i128(by value) is incompatible with the
1906 Microsoft x64 calling convention. You might need to tweak
1907 ``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp.
1909 For the X86 target, clang supports the :option:`-m16` command line
1910 argument which enables 16-bit code output. This is broadly similar to
1911 using ``asm(".code16gcc")`` with the GNU toolchain. The generated code
1912 and the ABI remains 32-bit but the assembler emits instructions
1913 appropriate for a CPU running in 16-bit mode, with address-size and
1914 operand-size prefixes to enable 32-bit addressing and operations.
1919 The support for ARM (specifically ARMv6 and ARMv7) is considered stable
1920 on Darwin (iOS): it has been tested to correctly compile many large C,
1921 C++, Objective-C, and Objective-C++ codebases. Clang only supports a
1922 limited number of ARM architectures. It does not yet fully support
1928 The support for PowerPC (especially PowerPC64) is considered stable
1929 on Linux and FreeBSD: it has been tested to correctly compile many
1930 large C and C++ codebases. PowerPC (32bit) is still missing certain
1931 features (e.g. PIC code on ELF platforms).
1936 clang currently contains some support for other architectures (e.g. Sparc);
1937 however, significant pieces of code generation are still missing, and they
1938 haven't undergone significant testing.
1940 clang contains limited support for the MSP430 embedded processor, but
1941 both the clang support and the LLVM backend support are highly
1944 Other platforms are completely unsupported at the moment. Adding the
1945 minimal support needed for parsing and semantic analysis on a new
1946 platform is quite easy; see ``lib/Basic/Targets.cpp`` in the clang source
1947 tree. This level of support is also sufficient for conversion to LLVM IR
1948 for simple programs. Proper support for conversion to LLVM IR requires
1949 adding code to ``lib/CodeGen/CGCall.cpp`` at the moment; this is likely to
1950 change soon, though. Generating assembly requires a suitable LLVM
1953 Operating System Features and Limitations
1954 -----------------------------------------
1959 Thread Sanitizer is not supported.
1964 Clang has experimental support for targeting "Cygming" (Cygwin / MinGW)
1967 See also :ref:`Microsoft Extensions <c_ms>`.
1972 Clang works on Cygwin-1.7.
1977 Clang works on some mingw32 distributions. Clang assumes directories as
1980 - ``C:/mingw/include``
1982 - ``C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++``
1984 On MSYS, a few tests might fail.
1989 For 32-bit (i686-w64-mingw32), and 64-bit (x86\_64-w64-mingw32), Clang
1992 - ``GCC versions 4.5.0 to 4.5.3, 4.6.0 to 4.6.2, or 4.7.0 (for the C++ header search path)``
1993 - ``some_directory/bin/gcc.exe``
1994 - ``some_directory/bin/clang.exe``
1995 - ``some_directory/bin/clang++.exe``
1996 - ``some_directory/bin/../include/c++/GCC_version``
1997 - ``some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32``
1998 - ``some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32``
1999 - ``some_directory/bin/../include/c++/GCC_version/backward``
2000 - ``some_directory/bin/../x86_64-w64-mingw32/include``
2001 - ``some_directory/bin/../i686-w64-mingw32/include``
2002 - ``some_directory/bin/../include``
2004 This directory layout is standard for any toolchain you will find on the
2005 official `MinGW-w64 website <http://mingw-w64.sourceforge.net>`_.
2007 Clang expects the GCC executable "gcc.exe" compiled for
2008 ``i686-w64-mingw32`` (or ``x86_64-w64-mingw32``) to be present on PATH.
2010 `Some tests might fail <http://llvm.org/bugs/show_bug.cgi?id=9072>`_ on
2011 ``x86_64-w64-mingw32``.
2018 clang-cl is an alternative command-line interface to Clang driver, designed for
2019 compatibility with the Visual C++ compiler, cl.exe.
2021 To enable clang-cl to find system headers, libraries, and the linker when run
2022 from the command-line, it should be executed inside a Visual Studio Native Tools
2023 Command Prompt or a regular Command Prompt where the environment has been set
2024 up using e.g. `vcvars32.bat <http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_.
2026 clang-cl can also be used from inside Visual Studio by using an LLVM Platform
2029 Command-Line Options
2030 --------------------
2032 To be compatible with cl.exe, clang-cl supports most of the same command-line
2033 options. Those options can start with either ``/`` or ``-``. It also supports
2034 some of Clang's core options, such as the ``-W`` options.
2036 Options that are known to clang-cl, but not currently supported, are ignored
2037 with a warning. For example:
2041 clang-cl.exe: warning: argument unused during compilation: '/AI'
2043 To suppress warnings about unused arguments, use the ``-Qunused-arguments`` option.
2045 Options that are not known to clang-cl will be ignored by default. Use the
2046 ``-Werror=unknown-argument`` option in order to treat them as errors. If these
2047 options are spelled with a leading ``/``, they will be mistaken for a filename:
2051 clang-cl.exe: error: no such file or directory: '/foobar'
2053 Please `file a bug <http://llvm.org/bugs/enter_bug.cgi?product=clang&component=Driver>`_
2054 for any valid cl.exe flags that clang-cl does not understand.
2056 Execute ``clang-cl /?`` to see a list of supported options:
2060 CL.EXE COMPATIBILITY OPTIONS:
2061 /? Display available options
2062 /arch:<value> Set architecture for code generation
2063 /Brepro- Emit an object file which cannot be reproduced over time
2064 /Brepro Emit an object file which can be reproduced over time
2065 /C Don't discard comments when preprocessing
2067 /D <macro[=value]> Define macro
2068 /EH<value> Exception handling model
2069 /EP Disable linemarker output and preprocess to stdout
2070 /E Preprocess to stdout
2071 /fallback Fall back to cl.exe if clang-cl fails to compile
2072 /FA Output assembly code file during compilation
2073 /Fa<file or directory> Output assembly code to this file during compilation (with /FA)
2074 /Fe<file or directory> Set output executable file or directory (ends in / or \)
2075 /FI <value> Include file before parsing
2076 /Fi<file> Set preprocess output file name (with /P)
2077 /Fo<file or directory> Set output object file, or directory (ends in / or \) (with /c)
2083 /GA Assume thread-local variables are defined in the executable
2084 /GF- Disable string pooling
2085 /GR- Disable emission of RTTI data
2086 /GR Enable emission of RTTI data
2087 /Gs<value> Set stack probe size
2088 /Gw- Don't put each data item in its own section
2089 /Gw Put each data item in its own section
2090 /Gy- Don't put each function in its own section
2091 /Gy Put each function in its own section
2092 /help Display available options
2093 /I <dir> Add directory to include search path
2094 /J Make char type unsigned
2095 /LDd Create debug DLL
2097 /link <options> Forward options to the linker
2098 /MDd Use DLL debug run-time
2099 /MD Use DLL run-time
2100 /MTd Use static debug run-time
2101 /MT Use static run-time
2102 /Ob0 Disable inlining
2103 /Od Disable optimization
2104 /Oi- Disable use of builtin functions
2105 /Oi Enable use of builtin functions
2106 /Os Optimize for size
2107 /Ot Optimize for speed
2108 /O<value> Optimization level
2109 /o <file or directory> Set output file or directory (ends in / or \)
2110 /P Preprocess to file
2111 /Qvec- Disable the loop vectorization passes
2112 /Qvec Enable the loop vectorization passes
2113 /showIncludes Print info about included files to stderr
2114 /TC Treat all source files as C
2115 /Tc <filename> Specify a C source file
2116 /TP Treat all source files as C++
2117 /Tp <filename> Specify a C++ source file
2118 /U <macro> Undefine macro
2119 /vd<value> Control vtordisp placement
2120 /vmb Use a best-case representation method for member pointers
2121 /vmg Use a most-general representation for member pointers
2122 /vmm Set the default most-general representation to multiple inheritance
2123 /vms Set the default most-general representation to single inheritance
2124 /vmv Set the default most-general representation to virtual inheritance
2125 /volatile:iso Volatile loads and stores have standard semantics
2126 /volatile:ms Volatile loads and stores have acquire and release semantics
2127 /W0 Disable all warnings
2131 /W4 Enable -Wall and -Wextra
2132 /Wall Enable -Wall and -Wextra
2133 /WX- Do not treat warnings as errors
2134 /WX Treat warnings as errors
2135 /w Disable all warnings
2136 /Z7 Enable CodeView debug information in object files
2137 /Zc:sizedDealloc- Disable C++14 sized global deallocation functions
2138 /Zc:sizedDealloc Enable C++14 sized global deallocation functions
2139 /Zc:strictStrings Treat string literals as const
2140 /Zc:threadSafeInit- Disable thread-safe initialization of static variables
2141 /Zc:threadSafeInit Enable thread-safe initialization of static variables
2142 /Zc:trigraphs- Disable trigraphs (default)
2143 /Zc:trigraphs Enable trigraphs
2144 /Zi Alias for /Z7. Does not produce PDBs.
2145 /Zl Don't mention any default libraries in the object file
2146 /Zp Set the default maximum struct packing alignment to 1
2147 /Zp<value> Specify the default maximum struct packing alignment
2148 /Zs Syntax-check only
2151 -### Print (but do not run) the commands to run for this compilation
2152 --analyze Run the static analyzer
2153 -fansi-escape-codes Use ANSI escape codes for diagnostics
2154 -fcolor-diagnostics Use colors in diagnostics
2155 -fdiagnostics-parseable-fixits
2156 Print fix-its in machine parseable form
2157 -fms-compatibility-version=<value>
2158 Dot-separated value representing the Microsoft compiler version
2159 number to report in _MSC_VER (0 = don't define it (default))
2160 -fms-compatibility Enable full Microsoft Visual C++ compatibility
2161 -fms-extensions Accept some non-standard constructs supported by the Microsoft compiler
2162 -fmsc-version=<value> Microsoft compiler version number to report in _MSC_VER
2163 (0 = don't define it (default))
2164 -fno-sanitize-coverage=<value>
2165 Disable specified features of coverage instrumentation for Sanitizers
2166 -fno-sanitize-recover=<value>
2167 Disable recovery for specified sanitizers
2168 -fno-sanitize-trap=<value>
2169 Disable trapping for specified sanitizers
2170 -fsanitize-blacklist=<value>
2171 Path to blacklist file for sanitizers
2172 -fsanitize-coverage=<value>
2173 Specify the type of coverage instrumentation for Sanitizers
2174 -fsanitize-recover=<value>
2175 Enable recovery for specified sanitizers
2176 -fsanitize-trap=<value> Enable trapping for specified sanitizers
2177 -fsanitize=<check> Turn on runtime checks for various forms of undefined or suspicious
2178 behavior. See user manual for available checks
2179 -gcodeview Generate CodeView debug information
2180 -mllvm <value> Additional arguments to forward to LLVM's option processing
2181 -Qunused-arguments Don't emit warning for unused driver arguments
2182 -R<remark> Enable the specified remark
2183 --target=<value> Generate code for the given target
2184 -v Show commands to run and use verbose output
2185 -W<warning> Enable the specified warning
2186 -Xclang <arg> Pass <arg> to the clang compiler
2188 The /fallback Option
2189 ^^^^^^^^^^^^^^^^^^^^
2191 When clang-cl is run with the ``/fallback`` option, it will first try to
2192 compile files itself. For any file that it fails to compile, it will fall back
2193 and try to compile the file by invoking cl.exe.
2195 This option is intended to be used as a temporary means to build projects where
2196 clang-cl cannot successfully compile all the files. clang-cl may fail to compile
2197 a file either because it cannot generate code for some C++ feature, or because
2198 it cannot parse some Microsoft language extension.