1 ============================
2 Clang Compiler User's Manual
3 ============================
5 .. include:: <isonum.txt>
13 The Clang Compiler is an open-source compiler for the C family of
14 programming languages, aiming to be the best in class implementation of
15 these languages. Clang builds on the LLVM optimizer and code generator,
16 allowing it to provide high-quality optimization and code generation
17 support for many targets. For more general information, please see the
18 `Clang Web Site <http://clang.llvm.org>`_ or the `LLVM Web
19 Site <http://llvm.org>`_.
21 This document describes important notes about using Clang as a compiler
22 for an end-user, documenting the supported features, command line
23 options, etc. If you are interested in using Clang to build a tool that
24 processes code, please see :doc:`InternalsManual`. If you are interested in the
25 `Clang Static Analyzer <http://clang-analyzer.llvm.org>`_, please see its web
28 Clang is designed to support the C family of programming languages,
29 which includes :ref:`C <c>`, :ref:`Objective-C <objc>`, :ref:`C++ <cxx>`, and
30 :ref:`Objective-C++ <objcxx>` as well as many dialects of those. For
31 language-specific information, please see the corresponding language
34 - :ref:`C Language <c>`: K&R C, ANSI C89, ISO C90, ISO C94 (C89+AMD1), ISO
36 - :ref:`Objective-C Language <objc>`: ObjC 1, ObjC 2, ObjC 2.1, plus
37 variants depending on base language.
38 - :ref:`C++ Language <cxx>`
39 - :ref:`Objective C++ Language <objcxx>`
41 In addition to these base languages and their dialects, Clang supports a
42 broad variety of language extensions, which are documented in the
43 corresponding language section. These extensions are provided to be
44 compatible with the GCC, Microsoft, and other popular compilers as well
45 as to improve functionality through Clang-specific features. The Clang
46 driver and language features are intentionally designed to be as
47 compatible with the GNU GCC compiler as reasonably possible, easing
48 migration from GCC to Clang. In most cases, code "just works".
49 Clang also provides an alternative driver, :ref:`clang-cl`, that is designed
50 to be compatible with the Visual C++ compiler, cl.exe.
52 In addition to language specific features, Clang has a variety of
53 features that depend on what CPU architecture or operating system is
54 being compiled for. Please see the :ref:`Target-Specific Features and
55 Limitations <target_features>` section for more details.
57 The rest of the introduction introduces some basic :ref:`compiler
58 terminology <terminology>` that is used throughout this manual and
59 contains a basic :ref:`introduction to using Clang <basicusage>` as a
60 command line compiler.
67 Front end, parser, backend, preprocessor, undefined behavior,
75 Intro to how to use a C compiler for newbies.
77 compile + link compile then link debug info enabling optimizations
78 picking a language to use, defaults to C11 by default. Autosenses based
79 on extension. using a makefile
84 This section is generally an index into other sections. It does not go
85 into depth on the ones that are covered by other sections. However, the
86 first part introduces the language selection and other high level
87 options like :option:`-c`, :option:`-g`, etc.
89 Options to Control Error and Warning Messages
90 ---------------------------------------------
94 Turn warnings into errors.
96 .. This is in plain monospaced font because it generates the same label as
97 .. -Werror, and Sphinx complains.
101 Turn warning "foo" into an error.
103 .. option:: -Wno-error=foo
105 Turn warning "foo" into an warning even if :option:`-Werror` is specified.
109 Enable warning "foo".
110 See the :doc:`diagnostics reference <DiagnosticsReference>` for a complete
111 list of the warning flags that can be specified in this way.
115 Disable warning "foo".
119 Disable all diagnostics.
121 .. option:: -Weverything
123 :ref:`Enable all diagnostics. <diagnostics_enable_everything>`
125 .. option:: -pedantic
127 Warn on language extensions.
129 .. option:: -pedantic-errors
131 Error on language extensions.
133 .. option:: -Wsystem-headers
135 Enable warnings from system headers.
137 .. option:: -ferror-limit=123
139 Stop emitting diagnostics after 123 errors have been produced. The default is
140 20, and the error limit can be disabled with `-ferror-limit=0`.
142 .. option:: -ftemplate-backtrace-limit=123
144 Only emit up to 123 template instantiation notes within the template
145 instantiation backtrace for a single warning or error. The default is 10, and
146 the limit can be disabled with `-ftemplate-backtrace-limit=0`.
148 .. _cl_diag_formatting:
150 Formatting of Diagnostics
151 ^^^^^^^^^^^^^^^^^^^^^^^^^
153 Clang aims to produce beautiful diagnostics by default, particularly for
154 new users that first come to Clang. However, different people have
155 different preferences, and sometimes Clang is driven not by a human,
156 but by a program that wants consistent and easily parsable output. For
157 these cases, Clang provides a wide range of options to control the exact
158 output format of the diagnostics that it generates.
160 .. _opt_fshow-column:
162 **-f[no-]show-column**
163 Print column number in diagnostic.
165 This option, which defaults to on, controls whether or not Clang
166 prints the column number of a diagnostic. For example, when this is
167 enabled, Clang will print something like:
171 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
176 When this is disabled, Clang will print "test.c:28: warning..." with
179 The printed column numbers count bytes from the beginning of the
180 line; take care if your source contains multibyte characters.
182 .. _opt_fshow-source-location:
184 **-f[no-]show-source-location**
185 Print source file/line/column information in diagnostic.
187 This option, which defaults to on, controls whether or not Clang
188 prints the filename, line number and column number of a diagnostic.
189 For example, when this is enabled, Clang will print something like:
193 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
198 When this is disabled, Clang will not print the "test.c:28:8: "
201 .. _opt_fcaret-diagnostics:
203 **-f[no-]caret-diagnostics**
204 Print source line and ranges from source code in diagnostic.
205 This option, which defaults to on, controls whether or not Clang
206 prints the source line, source ranges, and caret when emitting a
207 diagnostic. For example, when this is enabled, Clang will print
212 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
217 **-f[no-]color-diagnostics**
218 This option, which defaults to on when a color-capable terminal is
219 detected, controls whether or not Clang prints diagnostics in color.
221 When this option is enabled, Clang will use colors to highlight
222 specific parts of the diagnostic, e.g.,
224 .. nasty hack to not lose our dignity
229 <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>
231 <span style="color:green">^</span>
232 <span style="color:green">//</span>
235 When this is disabled, Clang will just print:
239 test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
244 **-fansi-escape-codes**
245 Controls whether ANSI escape codes are used instead of the Windows Console
246 API to output colored diagnostics. This option is only used on Windows and
249 .. option:: -fdiagnostics-format=clang/msvc/vi
251 Changes diagnostic output format to better match IDEs and command line tools.
253 This option controls the output format of the filename, line number,
254 and column printed in diagnostic messages. The options, and their
255 affect on formatting a simple conversion diagnostic, follow:
260 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
265 t.c(3,11) : warning: conversion specifies type 'char *' but the argument has type 'int'
270 t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
272 .. _opt_fdiagnostics-show-option:
274 **-f[no-]diagnostics-show-option**
275 Enable ``[-Woption]`` information in diagnostic line.
277 This option, which defaults to on, controls whether or not Clang
278 prints the associated :ref:`warning group <cl_diag_warning_groups>`
279 option name when outputting a warning diagnostic. For example, in
284 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
289 Passing **-fno-diagnostics-show-option** will prevent Clang from
290 printing the [:ref:`-Wextra-tokens <opt_Wextra-tokens>`] information in
291 the diagnostic. This information tells you the flag needed to enable
292 or disable the diagnostic, either from the command line or through
293 :ref:`#pragma GCC diagnostic <pragma_GCC_diagnostic>`.
295 .. _opt_fdiagnostics-show-category:
297 .. option:: -fdiagnostics-show-category=none/id/name
299 Enable printing category information in diagnostic line.
301 This option, which defaults to "none", controls whether or not Clang
302 prints the category associated with a diagnostic when emitting it.
303 Each diagnostic may or many not have an associated category, if it
304 has one, it is listed in the diagnostic categorization field of the
305 diagnostic line (in the []'s).
307 For example, a format string warning will produce these three
308 renditions based on the setting of this option:
312 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat]
313 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1]
314 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String]
316 This category can be used by clients that want to group diagnostics
317 by category, so it should be a high level category. We want dozens
318 of these, not hundreds or thousands of them.
320 .. _opt_fdiagnostics-show-hotness:
322 **-f[no-]diagnostics-show-hotness**
323 Enable profile hotness information in diagnostic line.
325 This option, which defaults to off, controls whether Clang prints the
326 profile hotness associated with a diagnostics in the presence of
327 profile-guided optimization information. This is currently supported with
328 optimization remarks (see :ref:`Options to Emit Optimization Reports
329 <rpass>`). The hotness information allows users to focus on the hot
330 optimization remarks that are likely to be more relevant for run-time
333 For example, in this output, the block containing the callsite of `foo` was
334 executed 3000 times according to the profile data:
338 s.c:7:10: remark: foo inlined into bar (hotness: 3000) [-Rpass-analysis=inline]
339 sum += foo(x, x - 2);
342 .. _opt_fdiagnostics-fixit-info:
344 **-f[no-]diagnostics-fixit-info**
345 Enable "FixIt" information in the diagnostics output.
347 This option, which defaults to on, controls whether or not Clang
348 prints the information on how to fix a specific diagnostic
349 underneath it when it knows. For example, in this output:
353 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
358 Passing **-fno-diagnostics-fixit-info** will prevent Clang from
359 printing the "//" line at the end of the message. This information
360 is useful for users who may not understand what is wrong, but can be
361 confusing for machine parsing.
363 .. _opt_fdiagnostics-print-source-range-info:
365 **-fdiagnostics-print-source-range-info**
366 Print machine parsable information about source ranges.
367 This option makes Clang print information about source ranges in a machine
368 parsable format after the file/line/column number information. The
369 information is a simple sequence of brace enclosed ranges, where each range
370 lists the start and end line/column locations. For example, in this output:
374 exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float')
375 P = (P-42) + Gamma*4;
378 The {}'s are generated by -fdiagnostics-print-source-range-info.
380 The printed column numbers count bytes from the beginning of the
381 line; take care if your source contains multibyte characters.
383 .. option:: -fdiagnostics-parseable-fixits
385 Print Fix-Its in a machine parseable form.
387 This option makes Clang print available Fix-Its in a machine
388 parseable format at the end of diagnostics. The following example
389 illustrates the format:
393 fix-it:"t.cpp":{7:25-7:29}:"Gamma"
395 The range printed is a half-open range, so in this example the
396 characters at column 25 up to but not including column 29 on line 7
397 in t.cpp should be replaced with the string "Gamma". Either the
398 range or the replacement string may be empty (representing strict
399 insertions and strict erasures, respectively). Both the file name
400 and the insertion string escape backslash (as "\\\\"), tabs (as
401 "\\t"), newlines (as "\\n"), double quotes(as "\\"") and
402 non-printable characters (as octal "\\xxx").
404 The printed column numbers count bytes from the beginning of the
405 line; take care if your source contains multibyte characters.
407 .. option:: -fno-elide-type
409 Turns off elision in template type printing.
411 The default for template type printing is to elide as many template
412 arguments as possible, removing those which are the same in both
413 template types, leaving only the differences. Adding this flag will
414 print all the template arguments. If supported by the terminal,
415 highlighting will still appear on differing arguments.
421 t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument;
427 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;
429 .. option:: -fdiagnostics-show-template-tree
431 Template type diffing prints a text tree.
433 For diffing large templated types, this option will cause Clang to
434 display the templates as an indented text tree, one argument per
435 line, with differences marked inline. This is compatible with
442 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;
444 With :option:`-fdiagnostics-show-template-tree`:
448 t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument;
456 .. _cl_diag_warning_groups:
458 Individual Warning Groups
459 ^^^^^^^^^^^^^^^^^^^^^^^^^
461 TODO: Generate this from tblgen. Define one anchor per warning group.
463 .. _opt_wextra-tokens:
465 .. option:: -Wextra-tokens
467 Warn about excess tokens at the end of a preprocessor directive.
469 This option, which defaults to on, enables warnings about extra
470 tokens at the end of preprocessor directives. For example:
474 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
478 These extra tokens are not strictly conforming, and are usually best
479 handled by commenting them out.
481 .. option:: -Wambiguous-member-template
483 Warn about unqualified uses of a member template whose name resolves to
484 another template at the location of the use.
486 This option, which defaults to on, enables a warning in the
491 template<typename T> struct set{};
492 template<typename T> struct trait { typedef const T& type; };
494 template<typename T> void set(typename trait<T>::type value) {}
501 C++ [basic.lookup.classref] requires this to be an error, but,
502 because it's hard to work around, Clang downgrades it to a warning
505 .. option:: -Wbind-to-temporary-copy
507 Warn about an unusable copy constructor when binding a reference to a
510 This option enables warnings about binding a
511 reference to a temporary when the temporary doesn't have a usable
512 copy constructor. For example:
519 NonCopyable(const NonCopyable&);
521 void foo(const NonCopyable&);
523 foo(NonCopyable()); // Disallowed in C++98; allowed in C++11.
528 struct NonCopyable2 {
530 NonCopyable2(NonCopyable2&);
532 void foo(const NonCopyable2&);
534 foo(NonCopyable2()); // Disallowed in C++98; allowed in C++11.
537 Note that if ``NonCopyable2::NonCopyable2()`` has a default argument
538 whose instantiation produces a compile error, that error will still
539 be a hard error in C++98 mode even if this warning is turned off.
541 Options to Control Clang Crash Diagnostics
542 ------------------------------------------
544 As unbelievable as it may sound, Clang does crash from time to time.
545 Generally, this only occurs to those living on the `bleeding
546 edge <http://llvm.org/releases/download.html#svn>`_. Clang goes to great
547 lengths to assist you in filing a bug report. Specifically, Clang
548 generates preprocessed source file(s) and associated run script(s) upon
549 a crash. These files should be attached to a bug report to ease
550 reproducibility of the failure. Below are the command line options to
551 control the crash diagnostics.
553 .. option:: -fno-crash-diagnostics
555 Disable auto-generation of preprocessed source files during a clang crash.
557 The -fno-crash-diagnostics flag can be helpful for speeding the process
558 of generating a delta reduced test case.
562 Options to Emit Optimization Reports
563 ------------------------------------
565 Optimization reports trace, at a high-level, all the major decisions
566 done by compiler transformations. For instance, when the inliner
567 decides to inline function ``foo()`` into ``bar()``, or the loop unroller
568 decides to unroll a loop N times, or the vectorizer decides to
569 vectorize a loop body.
571 Clang offers a family of flags which the optimizers can use to emit
572 a diagnostic in three cases:
574 1. When the pass makes a transformation (`-Rpass`).
576 2. When the pass fails to make a transformation (`-Rpass-missed`).
578 3. When the pass determines whether or not to make a transformation
581 NOTE: Although the discussion below focuses on `-Rpass`, the exact
582 same options apply to `-Rpass-missed` and `-Rpass-analysis`.
584 Since there are dozens of passes inside the compiler, each of these flags
585 take a regular expression that identifies the name of the pass which should
586 emit the associated diagnostic. For example, to get a report from the inliner,
587 compile the code with:
589 .. code-block:: console
591 $ clang -O2 -Rpass=inline code.cc -o code
592 code.cc:4:25: remark: foo inlined into bar [-Rpass=inline]
593 int bar(int j) { return foo(j, j - 2); }
596 Note that remarks from the inliner are identified with `[-Rpass=inline]`.
597 To request a report from every optimization pass, you should use
598 `-Rpass=.*` (in fact, you can use any valid POSIX regular
599 expression). However, do not expect a report from every transformation
600 made by the compiler. Optimization remarks do not really make sense
601 outside of the major transformations (e.g., inlining, vectorization,
602 loop optimizations) and not every optimization pass supports this
605 Note that when using profile-guided optimization information, profile hotness
606 information can be included in the remarks (see
607 :ref:`-fdiagnostics-show-hotness <opt_fdiagnostics-show-hotness>`).
612 1. Optimization remarks that refer to function names will display the
613 mangled name of the function. Since these remarks are emitted by the
614 back end of the compiler, it does not know anything about the input
615 language, nor its mangling rules.
617 2. Some source locations are not displayed correctly. The front end has
618 a more detailed source location tracking than the locations included
619 in the debug info (e.g., the front end can locate code inside macro
620 expansions). However, the locations used by `-Rpass` are
621 translated from debug annotations. That translation can be lossy,
622 which results in some remarks having no location information.
626 Clang options that that don't fit neatly into other categories.
630 When emitting a dependency file, use formatting conventions appropriate
631 for NMake or Jom. Ignored unless another option causes Clang to emit a
634 When Clang emits a dependency file (e.g., you supplied the -M option)
635 most filenames can be written to the file without any special formatting.
636 Different Make tools will treat different sets of characters as "special"
637 and use different conventions for telling the Make tool that the character
638 is actually part of the filename. Normally Clang uses backslash to "escape"
639 a special character, which is the convention used by GNU Make. The -MV
640 option tells Clang to put double-quotes around the entire filename, which
641 is the convention used by NMake and Jom.
644 Language and Target-Independent Features
645 ========================================
647 Controlling Errors and Warnings
648 -------------------------------
650 Clang provides a number of ways to control which code constructs cause
651 it to emit errors and warning messages, and how they are displayed to
654 Controlling How Clang Displays Diagnostics
655 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
657 When Clang emits a diagnostic, it includes rich information in the
658 output, and gives you fine-grain control over which information is
659 printed. Clang has the ability to print this information, and these are
660 the options that control it:
662 #. A file/line/column indicator that shows exactly where the diagnostic
663 occurs in your code [:ref:`-fshow-column <opt_fshow-column>`,
664 :ref:`-fshow-source-location <opt_fshow-source-location>`].
665 #. A categorization of the diagnostic as a note, warning, error, or
667 #. A text string that describes what the problem is.
668 #. An option that indicates how to control the diagnostic (for
669 diagnostics that support it)
670 [:ref:`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`].
671 #. A :ref:`high-level category <diagnostics_categories>` for the diagnostic
672 for clients that want to group diagnostics by class (for diagnostics
674 [:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>`].
675 #. The line of source code that the issue occurs on, along with a caret
676 and ranges that indicate the important locations
677 [:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`].
678 #. "FixIt" information, which is a concise explanation of how to fix the
679 problem (when Clang is certain it knows)
680 [:ref:`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`].
681 #. A machine-parsable representation of the ranges involved (off by
683 [:ref:`-fdiagnostics-print-source-range-info <opt_fdiagnostics-print-source-range-info>`].
685 For more information please see :ref:`Formatting of
686 Diagnostics <cl_diag_formatting>`.
691 All diagnostics are mapped into one of these 6 classes:
700 .. _diagnostics_categories:
702 Diagnostic Categories
703 ^^^^^^^^^^^^^^^^^^^^^
705 Though not shown by default, diagnostics may each be associated with a
706 high-level category. This category is intended to make it possible to
707 triage builds that produce a large number of errors or warnings in a
710 Categories are not shown by default, but they can be turned on with the
711 :ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>` option.
712 When set to "``name``", the category is printed textually in the
713 diagnostic output. When it is set to "``id``", a category number is
714 printed. The mapping of category names to category id's can be obtained
715 by running '``clang --print-diagnostic-categories``'.
717 Controlling Diagnostics via Command Line Flags
718 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
720 TODO: -W flags, -pedantic, etc
722 .. _pragma_gcc_diagnostic:
724 Controlling Diagnostics via Pragmas
725 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
727 Clang can also control what diagnostics are enabled through the use of
728 pragmas in the source code. This is useful for turning off specific
729 warnings in a section of source code. Clang supports GCC's pragma for
730 compatibility with existing source code, as well as several extensions.
732 The pragma may control any warning that can be used from the command
733 line. Warnings may be set to ignored, warning, error, or fatal. The
734 following example code will tell Clang or GCC to ignore the -Wall
739 #pragma GCC diagnostic ignored "-Wall"
741 In addition to all of the functionality provided by GCC's pragma, Clang
742 also allows you to push and pop the current warning state. This is
743 particularly useful when writing a header file that will be compiled by
744 other people, because you don't know what warning flags they build with.
746 In the below example :option:`-Wextra-tokens` is ignored for only a single line
747 of code, after which the diagnostics return to whatever state had previously
753 #endif foo // warning: extra tokens at end of #endif directive
755 #pragma clang diagnostic ignored "-Wextra-tokens"
758 #endif foo // no warning
760 #pragma clang diagnostic pop
762 The push and pop pragmas will save and restore the full diagnostic state
763 of the compiler, regardless of how it was set. That means that it is
764 possible to use push and pop around GCC compatible diagnostics and Clang
765 will push and pop them appropriately, while GCC will ignore the pushes
766 and pops as unknown pragmas. It should be noted that while Clang
767 supports the GCC pragma, Clang and GCC do not support the exact same set
768 of warnings, so even when using GCC compatible #pragmas there is no
769 guarantee that they will have identical behaviour on both compilers.
771 In addition to controlling warnings and errors generated by the compiler, it is
772 possible to generate custom warning and error messages through the following
777 // The following will produce warning messages
778 #pragma message "some diagnostic message"
779 #pragma GCC warning "TODO: replace deprecated feature"
781 // The following will produce an error message
782 #pragma GCC error "Not supported"
784 These pragmas operate similarly to the ``#warning`` and ``#error`` preprocessor
785 directives, except that they may also be embedded into preprocessor macros via
786 the C99 ``_Pragma`` operator, for example:
791 #define DEFER(M,...) M(__VA_ARGS__)
792 #define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__))))
794 CUSTOM_ERROR("Feature not available");
796 Controlling Diagnostics in System Headers
797 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
799 Warnings are suppressed when they occur in system headers. By default,
800 an included file is treated as a system header if it is found in an
801 include path specified by ``-isystem``, but this can be overridden in
804 The ``system_header`` pragma can be used to mark the current file as
805 being a system header. No warnings will be produced from the location of
806 the pragma onwards within the same file.
811 #endif foo // warning: extra tokens at end of #endif directive
813 #pragma clang system_header
816 #endif foo // no warning
818 The `--system-header-prefix=` and `--no-system-header-prefix=`
819 command-line arguments can be used to override whether subsets of an include
820 path are treated as system headers. When the name in a ``#include`` directive
821 is found within a header search path and starts with a system prefix, the
822 header is treated as a system header. The last prefix on the
823 command-line which matches the specified header name takes precedence.
826 .. code-block:: console
828 $ clang -Ifoo -isystem bar --system-header-prefix=x/ \
829 --no-system-header-prefix=x/y/
831 Here, ``#include "x/a.h"`` is treated as including a system header, even
832 if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated
833 as not including a system header, even if the header is found in
836 A ``#include`` directive which finds a file relative to the current
837 directory is treated as including a system header if the including file
838 is treated as a system header.
840 .. _diagnostics_enable_everything:
842 Enabling All Diagnostics
843 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
845 In addition to the traditional ``-W`` flags, one can enable **all**
846 diagnostics by passing :option:`-Weverything`. This works as expected
848 :option:`-Werror`, and also includes the warnings from :option:`-pedantic`.
850 Note that when combined with :option:`-w` (which disables all warnings), that
853 Controlling Static Analyzer Diagnostics
854 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
856 While not strictly part of the compiler, the diagnostics from Clang's
857 `static analyzer <http://clang-analyzer.llvm.org>`_ can also be
858 influenced by the user via changes to the source code. See the available
859 `annotations <http://clang-analyzer.llvm.org/annotations.html>`_ and the
861 page <http://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more
864 .. _usersmanual-precompiled-headers:
869 `Precompiled headers <http://en.wikipedia.org/wiki/Precompiled_header>`__
870 are a general approach employed by many compilers to reduce compilation
871 time. The underlying motivation of the approach is that it is common for
872 the same (and often large) header files to be included by multiple
873 source files. Consequently, compile times can often be greatly improved
874 by caching some of the (redundant) work done by a compiler to process
875 headers. Precompiled header files, which represent one of many ways to
876 implement this optimization, are literally files that represent an
877 on-disk cache that contains the vital information necessary to reduce
878 some of the work needed to process a corresponding header file. While
879 details of precompiled headers vary between compilers, precompiled
880 headers have been shown to be highly effective at speeding up program
881 compilation on systems with very large system headers (e.g., Mac OS X).
883 Generating a PCH File
884 ^^^^^^^^^^^^^^^^^^^^^
886 To generate a PCH file using Clang, one invokes Clang with the
887 `-x <language>-header` option. This mirrors the interface in GCC
888 for generating PCH files:
890 .. code-block:: console
892 $ gcc -x c-header test.h -o test.h.gch
893 $ clang -x c-header test.h -o test.h.pch
898 A PCH file can then be used as a prefix header when a :option:`-include`
899 option is passed to ``clang``:
901 .. code-block:: console
903 $ clang -include test.h test.c -o test
905 The ``clang`` driver will first check if a PCH file for ``test.h`` is
906 available; if so, the contents of ``test.h`` (and the files it includes)
907 will be processed from the PCH file. Otherwise, Clang falls back to
908 directly processing the content of ``test.h``. This mirrors the behavior
913 Clang does *not* automatically use PCH files for headers that are directly
914 included within a source file. For example:
916 .. code-block:: console
918 $ clang -x c-header test.h -o test.h.pch
921 $ clang test.c -o test
923 In this example, ``clang`` will not automatically use the PCH file for
924 ``test.h`` since ``test.h`` was included directly in the source file and not
925 specified on the command line using :option:`-include`.
927 Relocatable PCH Files
928 ^^^^^^^^^^^^^^^^^^^^^
930 It is sometimes necessary to build a precompiled header from headers
931 that are not yet in their final, installed locations. For example, one
932 might build a precompiled header within the build tree that is then
933 meant to be installed alongside the headers. Clang permits the creation
934 of "relocatable" precompiled headers, which are built with a given path
935 (into the build directory) and can later be used from an installed
938 To build a relocatable precompiled header, place your headers into a
939 subdirectory whose structure mimics the installed location. For example,
940 if you want to build a precompiled header for the header ``mylib.h``
941 that will be installed into ``/usr/include``, create a subdirectory
942 ``build/usr/include`` and place the header ``mylib.h`` into that
943 subdirectory. If ``mylib.h`` depends on other headers, then they can be
944 stored within ``build/usr/include`` in a way that mimics the installed
947 Building a relocatable precompiled header requires two additional
948 arguments. First, pass the ``--relocatable-pch`` flag to indicate that
949 the resulting PCH file should be relocatable. Second, pass
950 `-isysroot /path/to/build`, which makes all includes for your library
951 relative to the build directory. For example:
953 .. code-block:: console
955 # clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
957 When loading the relocatable PCH file, the various headers used in the
958 PCH file are found from the system header root. For example, ``mylib.h``
959 can be found in ``/usr/include/mylib.h``. If the headers are installed
960 in some other system root, the `-isysroot` option can be used provide
961 a different system root from which the headers will be based. For
962 example, `-isysroot /Developer/SDKs/MacOSX10.4u.sdk` will look for
963 ``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``.
965 Relocatable precompiled headers are intended to be used in a limited
966 number of cases where the compilation environment is tightly controlled
967 and the precompiled header cannot be generated after headers have been
970 .. _controlling-code-generation:
972 Controlling Code Generation
973 ---------------------------
975 Clang provides a number of ways to control code generation. The options
978 **-f[no-]sanitize=check1,check2,...**
979 Turn on runtime checks for various forms of undefined or suspicious
982 This option controls whether Clang adds runtime checks for various
983 forms of undefined or suspicious behavior, and is disabled by
984 default. If a check fails, a diagnostic message is produced at
985 runtime explaining the problem. The main checks are:
987 - .. _opt_fsanitize_address:
989 ``-fsanitize=address``:
990 :doc:`AddressSanitizer`, a memory error
992 - .. _opt_fsanitize_thread:
994 ``-fsanitize=thread``: :doc:`ThreadSanitizer`, a data race detector.
995 - .. _opt_fsanitize_memory:
997 ``-fsanitize=memory``: :doc:`MemorySanitizer`,
998 a detector of uninitialized reads. Requires instrumentation of all
1000 - .. _opt_fsanitize_undefined:
1002 ``-fsanitize=undefined``: :doc:`UndefinedBehaviorSanitizer`,
1003 a fast and compatible undefined behavior checker.
1005 - ``-fsanitize=dataflow``: :doc:`DataFlowSanitizer`, a general data
1007 - ``-fsanitize=cfi``: :doc:`control flow integrity <ControlFlowIntegrity>`
1008 checks. Requires ``-flto``.
1009 - ``-fsanitize=safe-stack``: :doc:`safe stack <SafeStack>`
1010 protection against stack-based memory corruption errors.
1012 There are more fine-grained checks available: see
1013 the :ref:`list <ubsan-checks>` of specific kinds of
1014 undefined behavior that can be detected and the :ref:`list <cfi-schemes>`
1015 of control flow integrity schemes.
1017 The ``-fsanitize=`` argument must also be provided when linking, in
1018 order to link to the appropriate runtime library.
1020 It is not possible to combine more than one of the ``-fsanitize=address``,
1021 ``-fsanitize=thread``, and ``-fsanitize=memory`` checkers in the same
1024 **-f[no-]sanitize-recover=check1,check2,...**
1026 **-f[no-]sanitize-recover=all**
1028 Controls which checks enabled by ``-fsanitize=`` flag are non-fatal.
1029 If the check is fatal, program will halt after the first error
1030 of this kind is detected and error report is printed.
1032 By default, non-fatal checks are those enabled by
1033 :doc:`UndefinedBehaviorSanitizer`,
1034 except for ``-fsanitize=return`` and ``-fsanitize=unreachable``. Some
1035 sanitizers may not support recovery (or not support it by default
1036 e.g. :doc:`AddressSanitizer`), and always crash the program after the issue
1039 Note that the ``-fsanitize-trap`` flag has precedence over this flag.
1040 This means that if a check has been configured to trap elsewhere on the
1041 command line, or if the check traps by default, this flag will not have
1042 any effect unless that sanitizer's trapping behavior is disabled with
1043 ``-fno-sanitize-trap``.
1045 For example, if a command line contains the flags ``-fsanitize=undefined
1046 -fsanitize-trap=undefined``, the flag ``-fsanitize-recover=alignment``
1047 will have no effect on its own; it will need to be accompanied by
1048 ``-fno-sanitize-trap=alignment``.
1050 **-f[no-]sanitize-trap=check1,check2,...**
1052 Controls which checks enabled by the ``-fsanitize=`` flag trap. This
1053 option is intended for use in cases where the sanitizer runtime cannot
1054 be used (for instance, when building libc or a kernel module), or where
1055 the binary size increase caused by the sanitizer runtime is a concern.
1057 This flag is only compatible with :doc:`control flow integrity
1058 <ControlFlowIntegrity>` schemes and :doc:`UndefinedBehaviorSanitizer`
1059 checks other than ``vptr``. If this flag
1060 is supplied together with ``-fsanitize=undefined``, the ``vptr`` sanitizer
1061 will be implicitly disabled.
1063 This flag is enabled by default for sanitizers in the ``cfi`` group.
1065 .. option:: -fsanitize-blacklist=/path/to/blacklist/file
1067 Disable or modify sanitizer checks for objects (source files, functions,
1068 variables, types) listed in the file. See
1069 :doc:`SanitizerSpecialCaseList` for file format description.
1071 .. option:: -fno-sanitize-blacklist
1073 Don't use blacklist file, if it was specified earlier in the command line.
1075 **-f[no-]sanitize-coverage=[type,features,...]**
1077 Enable simple code coverage in addition to certain sanitizers.
1078 See :doc:`SanitizerCoverage` for more details.
1080 **-f[no-]sanitize-stats**
1082 Enable simple statistics gathering for the enabled sanitizers.
1083 See :doc:`SanitizerStats` for more details.
1085 .. option:: -fsanitize-undefined-trap-on-error
1087 Deprecated alias for ``-fsanitize-trap=undefined``.
1089 .. option:: -fsanitize-cfi-cross-dso
1091 Enable cross-DSO control flow integrity checks. This flag modifies
1092 the behavior of sanitizers in the ``cfi`` group to allow checking
1093 of cross-DSO virtual and indirect calls.
1095 .. option:: -ffast-math
1097 Enable fast-math mode. This defines the ``__FAST_MATH__`` preprocessor
1098 macro, and lets the compiler make aggressive, potentially-lossy assumptions
1099 about floating-point math. These include:
1101 * Floating-point math obeys regular algebraic rules for real numbers (e.g.
1102 ``+`` and ``*`` are associative, ``x/y == x * (1/y)``, and
1103 ``(a + b) * c == a * c + b * c``),
1104 * operands to floating-point operations are not equal to ``NaN`` and
1106 * ``+0`` and ``-0`` are interchangeable.
1108 .. option:: -fdenormal-fp-math=[values]
1110 Select which denormal numbers the code is permitted to require.
1112 Valid values are: ``ieee``, ``preserve-sign``, and ``positive-zero``,
1113 which correspond to IEEE 754 denormal numbers, the sign of a
1114 flushed-to-zero number is preserved in the sign of 0, denormals are
1115 flushed to positive zero, respectively.
1117 .. option:: -fwhole-program-vtables
1119 Enable whole-program vtable optimizations, such as single-implementation
1120 devirtualization and virtual constant propagation, for classes with
1121 :doc:`hidden LTO visibility <LTOVisibility>`. Requires ``-flto``.
1123 .. option:: -fno-assume-sane-operator-new
1125 Don't assume that the C++'s new operator is sane.
1127 This option tells the compiler to do not assume that C++'s global
1128 new operator will always return a pointer that does not alias any
1129 other pointer when the function returns.
1131 .. option:: -ftrap-function=[name]
1133 Instruct code generator to emit a function call to the specified
1134 function name for ``__builtin_trap()``.
1136 LLVM code generator translates ``__builtin_trap()`` to a trap
1137 instruction if it is supported by the target ISA. Otherwise, the
1138 builtin is translated into a call to ``abort``. If this option is
1139 set, then the code generator will always lower the builtin to a call
1140 to the specified function regardless of whether the target ISA has a
1141 trap instruction. This option is useful for environments (e.g.
1142 deeply embedded) where a trap cannot be properly handled, or when
1143 some custom behavior is desired.
1145 .. option:: -ftls-model=[model]
1147 Select which TLS model to use.
1149 Valid values are: ``global-dynamic``, ``local-dynamic``,
1150 ``initial-exec`` and ``local-exec``. The default value is
1151 ``global-dynamic``. The compiler may use a different model if the
1152 selected model is not supported by the target, or if a more
1153 efficient model can be used. The TLS model can be overridden per
1154 variable using the ``tls_model`` attribute.
1156 .. option:: -femulated-tls
1158 Select emulated TLS model, which overrides all -ftls-model choices.
1160 In emulated TLS mode, all access to TLS variables are converted to
1161 calls to __emutls_get_address in the runtime library.
1163 .. option:: -mhwdiv=[values]
1165 Select the ARM modes (arm or thumb) that support hardware division
1168 Valid values are: ``arm``, ``thumb`` and ``arm,thumb``.
1169 This option is used to indicate which mode (arm or thumb) supports
1170 hardware division instructions. This only applies to the ARM
1173 .. option:: -m[no-]crc
1175 Enable or disable CRC instructions.
1177 This option is used to indicate whether CRC instructions are to
1178 be generated. This only applies to the ARM architecture.
1180 CRC instructions are enabled by default on ARMv8.
1182 .. option:: -mgeneral-regs-only
1184 Generate code which only uses the general purpose registers.
1186 This option restricts the generated code to use general registers
1187 only. This only applies to the AArch64 architecture.
1189 .. option:: -mcompact-branches=[values]
1191 Control the usage of compact branches for MIPSR6.
1193 Valid values are: ``never``, ``optimal`` and ``always``.
1194 The default value is ``optimal`` which generates compact branches
1195 when a delay slot cannot be filled. ``never`` disables the usage of
1196 compact branches and ``always`` generates compact branches whenever
1199 **-f[no-]max-type-align=[number]**
1200 Instruct the code generator to not enforce a higher alignment than the given
1201 number (of bytes) when accessing memory via an opaque pointer or reference.
1202 This cap is ignored when directly accessing a variable or when the pointee
1203 type has an explicit “aligned” attribute.
1205 The value should usually be determined by the properties of the system allocator.
1206 Some builtin types, especially vector types, have very high natural alignments;
1207 when working with values of those types, Clang usually wants to use instructions
1208 that take advantage of that alignment. However, many system allocators do
1209 not promise to return memory that is more than 8-byte or 16-byte-aligned. Use
1210 this option to limit the alignment that the compiler can assume for an arbitrary
1211 pointer, which may point onto the heap.
1213 This option does not affect the ABI alignment of types; the layout of structs and
1214 unions and the value returned by the alignof operator remain the same.
1216 This option can be overridden on a case-by-case basis by putting an explicit
1217 “aligned” alignment on a struct, union, or typedef. For example:
1219 .. code-block:: console
1221 #include <immintrin.h>
1222 // Make an aligned typedef of the AVX-512 16-int vector type.
1223 typedef __v16si __aligned_v16si __attribute__((aligned(64)));
1225 void initialize_vector(__aligned_v16si *v) {
1226 // The compiler may assume that ‘v’ is 64-byte aligned, regardless of the
1227 // value of -fmax-type-align.
1231 Profile Guided Optimization
1232 ---------------------------
1234 Profile information enables better optimization. For example, knowing that a
1235 branch is taken very frequently helps the compiler make better decisions when
1236 ordering basic blocks. Knowing that a function ``foo`` is called more
1237 frequently than another function ``bar`` helps the inliner.
1239 Clang supports profile guided optimization with two different kinds of
1240 profiling. A sampling profiler can generate a profile with very low runtime
1241 overhead, or you can build an instrumented version of the code that collects
1242 more detailed profile information. Both kinds of profiles can provide execution
1243 counts for instructions in the code and information on branches taken and
1244 function invocation.
1246 Regardless of which kind of profiling you use, be careful to collect profiles
1247 by running your code with inputs that are representative of the typical
1248 behavior. Code that is not exercised in the profile will be optimized as if it
1249 is unimportant, and the compiler may make poor optimization choices for code
1250 that is disproportionately used while profiling.
1252 Differences Between Sampling and Instrumentation
1253 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1255 Although both techniques are used for similar purposes, there are important
1256 differences between the two:
1258 1. Profile data generated with one cannot be used by the other, and there is no
1259 conversion tool that can convert one to the other. So, a profile generated
1260 via ``-fprofile-instr-generate`` must be used with ``-fprofile-instr-use``.
1261 Similarly, sampling profiles generated by external profilers must be
1262 converted and used with ``-fprofile-sample-use``.
1264 2. Instrumentation profile data can be used for code coverage analysis and
1267 3. Sampling profiles can only be used for optimization. They cannot be used for
1268 code coverage analysis. Although it would be technically possible to use
1269 sampling profiles for code coverage, sample-based profiles are too
1270 coarse-grained for code coverage purposes; it would yield poor results.
1272 4. Sampling profiles must be generated by an external tool. The profile
1273 generated by that tool must then be converted into a format that can be read
1274 by LLVM. The section on sampling profilers describes one of the supported
1275 sampling profile formats.
1278 Using Sampling Profilers
1279 ^^^^^^^^^^^^^^^^^^^^^^^^
1281 Sampling profilers are used to collect runtime information, such as
1282 hardware counters, while your application executes. They are typically
1283 very efficient and do not incur a large runtime overhead. The
1284 sample data collected by the profiler can be used during compilation
1285 to determine what the most executed areas of the code are.
1287 Using the data from a sample profiler requires some changes in the way
1288 a program is built. Before the compiler can use profiling information,
1289 the code needs to execute under the profiler. The following is the
1290 usual build cycle when using sample profilers for optimization:
1292 1. Build the code with source line table information. You can use all the
1293 usual build flags that you always build your application with. The only
1294 requirement is that you add ``-gline-tables-only`` or ``-g`` to the
1295 command line. This is important for the profiler to be able to map
1296 instructions back to source line locations.
1298 .. code-block:: console
1300 $ clang++ -O2 -gline-tables-only code.cc -o code
1302 2. Run the executable under a sampling profiler. The specific profiler
1303 you use does not really matter, as long as its output can be converted
1304 into the format that the LLVM optimizer understands. Currently, there
1305 exists a conversion tool for the Linux Perf profiler
1306 (https://perf.wiki.kernel.org/), so these examples assume that you
1307 are using Linux Perf to profile your code.
1309 .. code-block:: console
1311 $ perf record -b ./code
1313 Note the use of the ``-b`` flag. This tells Perf to use the Last Branch
1314 Record (LBR) to record call chains. While this is not strictly required,
1315 it provides better call information, which improves the accuracy of
1318 3. Convert the collected profile data to LLVM's sample profile format.
1319 This is currently supported via the AutoFDO converter ``create_llvm_prof``.
1320 It is available at http://github.com/google/autofdo. Once built and
1321 installed, you can convert the ``perf.data`` file to LLVM using
1324 .. code-block:: console
1326 $ create_llvm_prof --binary=./code --out=code.prof
1328 This will read ``perf.data`` and the binary file ``./code`` and emit
1329 the profile data in ``code.prof``. Note that if you ran ``perf``
1330 without the ``-b`` flag, you need to use ``--use_lbr=false`` when
1331 calling ``create_llvm_prof``.
1333 4. Build the code again using the collected profile. This step feeds
1334 the profile back to the optimizers. This should result in a binary
1335 that executes faster than the original one. Note that you are not
1336 required to build the code with the exact same arguments that you
1337 used in the first step. The only requirement is that you build the code
1338 with ``-gline-tables-only`` and ``-fprofile-sample-use``.
1340 .. code-block:: console
1342 $ clang++ -O2 -gline-tables-only -fprofile-sample-use=code.prof code.cc -o code
1345 Sample Profile Formats
1346 """"""""""""""""""""""
1348 Since external profilers generate profile data in a variety of custom formats,
1349 the data generated by the profiler must be converted into a format that can be
1350 read by the backend. LLVM supports three different sample profile formats:
1352 1. ASCII text. This is the easiest one to generate. The file is divided into
1353 sections, which correspond to each of the functions with profile
1354 information. The format is described below. It can also be generated from
1355 the binary or gcov formats using the ``llvm-profdata`` tool.
1357 2. Binary encoding. This uses a more efficient encoding that yields smaller
1358 profile files. This is the format generated by the ``create_llvm_prof`` tool
1359 in http://github.com/google/autofdo.
1361 3. GCC encoding. This is based on the gcov format, which is accepted by GCC. It
1362 is only interesting in environments where GCC and Clang co-exist. This
1363 encoding is only generated by the ``create_gcov`` tool in
1364 http://github.com/google/autofdo. It can be read by LLVM and
1365 ``llvm-profdata``, but it cannot be generated by either.
1367 If you are using Linux Perf to generate sampling profiles, you can use the
1368 conversion tool ``create_llvm_prof`` described in the previous section.
1369 Otherwise, you will need to write a conversion tool that converts your
1370 profiler's native format into one of these three.
1373 Sample Profile Text Format
1374 """"""""""""""""""""""""""
1376 This section describes the ASCII text format for sampling profiles. It is,
1377 arguably, the easiest one to generate. If you are interested in generating any
1378 of the other two, consult the ``ProfileData`` library in in LLVM's source tree
1379 (specifically, ``include/llvm/ProfileData/SampleProfReader.h``).
1381 .. code-block:: console
1383 function1:total_samples:total_head_samples
1384 offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ]
1385 offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ]
1387 offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]
1388 offsetA[.discriminator]: fnA:num_of_total_samples
1389 offsetA1[.discriminator]: number_of_samples [fn7:num fn8:num ... ]
1390 offsetA1[.discriminator]: number_of_samples [fn9:num fn10:num ... ]
1391 offsetB[.discriminator]: fnB:num_of_total_samples
1392 offsetB1[.discriminator]: number_of_samples [fn11:num fn12:num ... ]
1394 This is a nested tree in which the identation represents the nesting level
1395 of the inline stack. There are no blank lines in the file. And the spacing
1396 within a single line is fixed. Additional spaces will result in an error
1397 while reading the file.
1399 Any line starting with the '#' character is completely ignored.
1401 Inlined calls are represented with indentation. The Inline stack is a
1402 stack of source locations in which the top of the stack represents the
1403 leaf function, and the bottom of the stack represents the actual
1404 symbol to which the instruction belongs.
1406 Function names must be mangled in order for the profile loader to
1407 match them in the current translation unit. The two numbers in the
1408 function header specify how many total samples were accumulated in the
1409 function (first number), and the total number of samples accumulated
1410 in the prologue of the function (second number). This head sample
1411 count provides an indicator of how frequently the function is invoked.
1413 There are two types of lines in the function body.
1415 - Sampled line represents the profile information of a source location.
1416 ``offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]``
1418 - Callsite line represents the profile information of an inlined callsite.
1419 ``offsetA[.discriminator]: fnA:num_of_total_samples``
1421 Each sampled line may contain several items. Some are optional (marked
1424 a. Source line offset. This number represents the line number
1425 in the function where the sample was collected. The line number is
1426 always relative to the line where symbol of the function is
1427 defined. So, if the function has its header at line 280, the offset
1428 13 is at line 293 in the file.
1430 Note that this offset should never be a negative number. This could
1431 happen in cases like macros. The debug machinery will register the
1432 line number at the point of macro expansion. So, if the macro was
1433 expanded in a line before the start of the function, the profile
1434 converter should emit a 0 as the offset (this means that the optimizers
1435 will not be able to associate a meaningful weight to the instructions
1438 b. [OPTIONAL] Discriminator. This is used if the sampled program
1439 was compiled with DWARF discriminator support
1440 (http://wiki.dwarfstd.org/index.php?title=Path_Discriminators).
1441 DWARF discriminators are unsigned integer values that allow the
1442 compiler to distinguish between multiple execution paths on the
1443 same source line location.
1445 For example, consider the line of code ``if (cond) foo(); else bar();``.
1446 If the predicate ``cond`` is true 80% of the time, then the edge
1447 into function ``foo`` should be considered to be taken most of the
1448 time. But both calls to ``foo`` and ``bar`` are at the same source
1449 line, so a sample count at that line is not sufficient. The
1450 compiler needs to know which part of that line is taken more
1453 This is what discriminators provide. In this case, the calls to
1454 ``foo`` and ``bar`` will be at the same line, but will have
1455 different discriminator values. This allows the compiler to correctly
1456 set edge weights into ``foo`` and ``bar``.
1458 c. Number of samples. This is an integer quantity representing the
1459 number of samples collected by the profiler at this source
1462 d. [OPTIONAL] Potential call targets and samples. If present, this
1463 line contains a call instruction. This models both direct and
1464 number of samples. For example,
1466 .. code-block:: console
1468 130: 7 foo:3 bar:2 baz:7
1470 The above means that at relative line offset 130 there is a call
1471 instruction that calls one of ``foo()``, ``bar()`` and ``baz()``,
1472 with ``baz()`` being the relatively more frequently called target.
1474 As an example, consider a program with the call chain ``main -> foo -> bar``.
1475 When built with optimizations enabled, the compiler may inline the
1476 calls to ``bar`` and ``foo`` inside ``main``. The generated profile
1477 could then be something like this:
1479 .. code-block:: console
1487 This profile indicates that there were a total of 35,504 samples
1488 collected in main. All of those were at line 1 (the call to ``foo``).
1489 Of those, 31,977 were spent inside the body of ``bar``. The last line
1490 of the profile (``2: 0``) corresponds to line 2 inside ``main``. No
1491 samples were collected there.
1493 Profiling with Instrumentation
1494 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1496 Clang also supports profiling via instrumentation. This requires building a
1497 special instrumented version of the code and has some runtime
1498 overhead during the profiling, but it provides more detailed results than a
1499 sampling profiler. It also provides reproducible results, at least to the
1500 extent that the code behaves consistently across runs.
1502 Here are the steps for using profile guided optimization with
1505 1. Build an instrumented version of the code by compiling and linking with the
1506 ``-fprofile-instr-generate`` option.
1508 .. code-block:: console
1510 $ clang++ -O2 -fprofile-instr-generate code.cc -o code
1512 2. Run the instrumented executable with inputs that reflect the typical usage.
1513 By default, the profile data will be written to a ``default.profraw`` file
1514 in the current directory. You can override that default by using option
1515 ``-fprofile-instr-generate=`` or by setting the ``LLVM_PROFILE_FILE``
1516 environment variable to specify an alternate file. If non-default file name
1517 is specified by both the environment variable and the command line option,
1518 the environment variable takes precedence. The file name pattern specified
1519 can include different modifiers: ``%p``, ``%h``, and ``%m``.
1521 Any instance of ``%p`` in that file name will be replaced by the process
1522 ID, so that you can easily distinguish the profile output from multiple
1525 .. code-block:: console
1527 $ LLVM_PROFILE_FILE="code-%p.profraw" ./code
1529 The modifier ``%h`` can be used in scenarios where the same instrumented
1530 binary is run in multiple different host machines dumping profile data
1531 to a shared network based storage. The ``%h`` specifier will be substituted
1532 with the hostname so that profiles collected from different hosts do not
1535 While the use of ``%p`` specifier can reduce the likelihood for the profiles
1536 dumped from different processes to clobber each other, such clobbering can still
1537 happen because of the ``pid`` re-use by the OS. Another side-effect of using
1538 ``%p`` is that the storage requirement for raw profile data files is greatly
1539 increased. To avoid issues like this, the ``%m`` specifier can used in the profile
1540 name. When this specifier is used, the profiler runtime will substitute ``%m``
1541 with a unique integer identifier associated with the instrumented binary. Additionally,
1542 multiple raw profiles dumped from different processes that share a file system (can be
1543 on different hosts) will be automatically merged by the profiler runtime during the
1544 dumping. If the program links in multiple instrumented shared libraries, each library
1545 will dump the profile data into its own profile data file (with its unique integer
1546 id embedded in the profile name). Note that the merging enabled by ``%m`` is for raw
1547 profile data generated by profiler runtime. The resulting merged "raw" profile data
1548 file still needs to be converted to a different format expected by the compiler (
1551 .. code-block:: console
1553 $ LLVM_PROFILE_FILE="code-%m.profraw" ./code
1556 3. Combine profiles from multiple runs and convert the "raw" profile format to
1557 the input expected by clang. Use the ``merge`` command of the
1558 ``llvm-profdata`` tool to do this.
1560 .. code-block:: console
1562 $ llvm-profdata merge -output=code.profdata code-*.profraw
1564 Note that this step is necessary even when there is only one "raw" profile,
1565 since the merge operation also changes the file format.
1567 4. Build the code again using the ``-fprofile-instr-use`` option to specify the
1568 collected profile data.
1570 .. code-block:: console
1572 $ clang++ -O2 -fprofile-instr-use=code.profdata code.cc -o code
1574 You can repeat step 4 as often as you like without regenerating the
1575 profile. As you make changes to your code, clang may no longer be able to
1576 use the profile data. It will warn you when this happens.
1578 Profile generation using an alternative instrumentation method can be
1579 controlled by the GCC-compatible flags ``-fprofile-generate`` and
1580 ``-fprofile-use``. Although these flags are semantically equivalent to
1581 their GCC counterparts, they *do not* handle GCC-compatible profiles.
1582 They are only meant to implement GCC's semantics with respect to
1583 profile creation and use.
1585 .. option:: -fprofile-generate[=<dirname>]
1587 The ``-fprofile-generate`` and ``-fprofile-generate=`` flags will use
1588 an alterantive instrumentation method for profile generation. When
1589 given a directory name, it generates the profile file
1590 ``default_%m.profraw`` in the directory named ``dirname`` if specified.
1591 If ``dirname`` does not exist, it will be created at runtime. ``%m`` specifier
1592 will be substibuted with a unique id documented in step 2 above. In other words,
1593 with ``-fprofile-generate[=<dirname>]`` option, the "raw" profile data automatic
1594 merging is turned on by default, so there will no longer any risk of profile
1595 clobbering from different running processes. For example,
1597 .. code-block:: console
1599 $ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code
1601 When ``code`` is executed, the profile will be written to the file
1602 ``yyy/zzz/default_xxxx.profraw``.
1604 To generate the profile data file with the compiler readable format, the
1605 ``llvm-profdata`` tool can be used with the profile directory as the input:
1607 .. code-block:: console
1609 $ llvm-profdata merge -output=code.profdata yyy/zzz/
1611 If the user wants to turn off the auto-merging feature, or simply override the
1612 the profile dumping path specified at command line, the environment variable
1613 ``LLVM_PROFILE_FILE`` can still be used to override
1614 the directory and filename for the profile file at runtime.
1616 .. option:: -fprofile-use[=<pathname>]
1618 Without any other arguments, ``-fprofile-use`` behaves identically to
1619 ``-fprofile-instr-use``. Otherwise, if ``pathname`` is the full path to a
1620 profile file, it reads from that file. If ``pathname`` is a directory name,
1621 it reads from ``pathname/default.profdata``.
1623 Disabling Instrumentation
1624 ^^^^^^^^^^^^^^^^^^^^^^^^^
1626 In certain situations, it may be useful to disable profile generation or use
1627 for specific files in a build, without affecting the main compilation flags
1628 used for the other files in the project.
1630 In these cases, you can use the flag ``-fno-profile-instr-generate`` (or
1631 ``-fno-profile-generate``) to disable profile generation, and
1632 ``-fno-profile-instr-use`` (or ``-fno-profile-use``) to disable profile use.
1634 Note that these flags should appear after the corresponding profile
1635 flags to have an effect.
1637 Controlling Debug Information
1638 -----------------------------
1640 Controlling Size of Debug Information
1641 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1643 Debug info kind generated by Clang can be set by one of the flags listed
1644 below. If multiple flags are present, the last one is used.
1648 Don't generate any debug info (default).
1650 .. option:: -gline-tables-only
1652 Generate line number tables only.
1654 This kind of debug info allows to obtain stack traces with function names,
1655 file names and line numbers (by such tools as ``gdb`` or ``addr2line``). It
1656 doesn't contain any other data (e.g. description of local variables or
1657 function parameters).
1659 .. option:: -fstandalone-debug
1661 Clang supports a number of optimizations to reduce the size of debug
1662 information in the binary. They work based on the assumption that
1663 the debug type information can be spread out over multiple
1664 compilation units. For instance, Clang will not emit type
1665 definitions for types that are not needed by a module and could be
1666 replaced with a forward declaration. Further, Clang will only emit
1667 type info for a dynamic C++ class in the module that contains the
1668 vtable for the class.
1670 The **-fstandalone-debug** option turns off these optimizations.
1671 This is useful when working with 3rd-party libraries that don't come
1672 with debug information. Note that Clang will never emit type
1673 information for types that are not referenced at all by the program.
1675 .. option:: -fno-standalone-debug
1677 On Darwin **-fstandalone-debug** is enabled by default. The
1678 **-fno-standalone-debug** option can be used to get to turn on the
1679 vtable-based optimization described above.
1683 Generate complete debug info.
1685 Controlling Debugger "Tuning"
1686 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1688 While Clang generally emits standard DWARF debug info (http://dwarfstd.org),
1689 different debuggers may know how to take advantage of different specific DWARF
1690 features. You can "tune" the debug info for one of several different debuggers.
1692 .. option:: -ggdb, -glldb, -gsce
1694 Tune the debug info for the ``gdb``, ``lldb``, or Sony PlayStation\ |reg|
1695 debugger, respectively. Each of these options implies **-g**. (Therefore, if
1696 you want both **-gline-tables-only** and debugger tuning, the tuning option
1700 Comment Parsing Options
1701 -----------------------
1703 Clang parses Doxygen and non-Doxygen style documentation comments and attaches
1704 them to the appropriate declaration nodes. By default, it only parses
1705 Doxygen-style comments and ignores ordinary comments starting with ``//`` and
1708 .. option:: -Wdocumentation
1710 Emit warnings about use of documentation comments. This warning group is off
1713 This includes checking that ``\param`` commands name parameters that actually
1714 present in the function signature, checking that ``\returns`` is used only on
1715 functions that actually return a value etc.
1717 .. option:: -Wno-documentation-unknown-command
1719 Don't warn when encountering an unknown Doxygen command.
1721 .. option:: -fparse-all-comments
1723 Parse all comments as documentation comments (including ordinary comments
1724 starting with ``//`` and ``/*``).
1726 .. option:: -fcomment-block-commands=[commands]
1728 Define custom documentation commands as block commands. This allows Clang to
1729 construct the correct AST for these custom commands, and silences warnings
1730 about unknown commands. Several commands must be separated by a comma
1731 *without trailing space*; e.g. ``-fcomment-block-commands=foo,bar`` defines
1732 custom commands ``\foo`` and ``\bar``.
1734 It is also possible to use ``-fcomment-block-commands`` several times; e.g.
1735 ``-fcomment-block-commands=foo -fcomment-block-commands=bar`` does the same
1743 The support for standard C in clang is feature-complete except for the
1744 C99 floating-point pragmas.
1746 Extensions supported by clang
1747 -----------------------------
1749 See :doc:`LanguageExtensions`.
1751 Differences between various standard modes
1752 ------------------------------------------
1754 clang supports the -std option, which changes what language mode clang
1755 uses. The supported modes for C are c89, gnu89, c94, c99, gnu99, c11,
1756 gnu11, and various aliases for those modes. If no -std option is
1757 specified, clang defaults to gnu11 mode. Many C99 and C11 features are
1758 supported in earlier modes as a conforming extension, with a warning. Use
1759 ``-pedantic-errors`` to request an error if a feature from a later standard
1760 revision is used in an earlier mode.
1762 Differences between all ``c*`` and ``gnu*`` modes:
1764 - ``c*`` modes define "``__STRICT_ANSI__``".
1765 - Target-specific defines not prefixed by underscores, like "linux",
1766 are defined in ``gnu*`` modes.
1767 - Trigraphs default to being off in ``gnu*`` modes; they can be enabled by
1768 the -trigraphs option.
1769 - The parser recognizes "asm" and "typeof" as keywords in ``gnu*`` modes;
1770 the variants "``__asm__``" and "``__typeof__``" are recognized in all
1772 - The Apple "blocks" extension is recognized by default in ``gnu*`` modes
1773 on some platforms; it can be enabled in any mode with the "-fblocks"
1775 - Arrays that are VLA's according to the standard, but which can be
1776 constant folded by the frontend are treated as fixed size arrays.
1777 This occurs for things like "int X[(1, 2)];", which is technically a
1778 VLA. ``c*`` modes are strictly compliant and treat these as VLAs.
1780 Differences between ``*89`` and ``*99`` modes:
1782 - The ``*99`` modes default to implementing "inline" as specified in C99,
1783 while the ``*89`` modes implement the GNU version. This can be
1784 overridden for individual functions with the ``__gnu_inline__``
1786 - Digraphs are not recognized in c89 mode.
1787 - The scope of names defined inside a "for", "if", "switch", "while",
1788 or "do" statement is different. (example: "``if ((struct x {int
1790 - ``__STDC_VERSION__`` is not defined in ``*89`` modes.
1791 - "inline" is not recognized as a keyword in c89 mode.
1792 - "restrict" is not recognized as a keyword in ``*89`` modes.
1793 - Commas are allowed in integer constant expressions in ``*99`` modes.
1794 - Arrays which are not lvalues are not implicitly promoted to pointers
1796 - Some warnings are different.
1798 Differences between ``*99`` and ``*11`` modes:
1800 - Warnings for use of C11 features are disabled.
1801 - ``__STDC_VERSION__`` is defined to ``201112L`` rather than ``199901L``.
1803 c94 mode is identical to c89 mode except that digraphs are enabled in
1804 c94 mode (FIXME: And ``__STDC_VERSION__`` should be defined!).
1806 GCC extensions not implemented yet
1807 ----------------------------------
1809 clang tries to be compatible with gcc as much as possible, but some gcc
1810 extensions are not implemented yet:
1812 - clang does not support decimal floating point types (``_Decimal32`` and
1813 friends) or fixed-point types (``_Fract`` and friends); nobody has
1814 expressed interest in these features yet, so it's hard to say when
1815 they will be implemented.
1816 - clang does not support nested functions; this is a complex feature
1817 which is infrequently used, so it is unlikely to be implemented
1818 anytime soon. In C++11 it can be emulated by assigning lambda
1819 functions to local variables, e.g:
1823 auto const local_function = [&](int parameter) {
1829 - clang does not support static initialization of flexible array
1830 members. This appears to be a rarely used extension, but could be
1831 implemented pending user demand.
1832 - clang does not support
1833 ``__builtin_va_arg_pack``/``__builtin_va_arg_pack_len``. This is
1834 used rarely, but in some potentially interesting places, like the
1835 glibc headers, so it may be implemented pending user demand. Note
1836 that because clang pretends to be like GCC 4.2, and this extension
1837 was introduced in 4.3, the glibc headers will not try to use this
1838 extension with clang at the moment.
1839 - clang does not support the gcc extension for forward-declaring
1840 function parameters; this has not shown up in any real-world code
1841 yet, though, so it might never be implemented.
1843 This is not a complete list; if you find an unsupported extension
1844 missing from this list, please send an e-mail to cfe-dev. This list
1845 currently excludes C++; see :ref:`C++ Language Features <cxx>`. Also, this
1846 list does not include bugs in mostly-implemented features; please see
1848 tracker <http://llvm.org/bugs/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer>`_
1849 for known existing bugs (FIXME: Is there a section for bug-reporting
1850 guidelines somewhere?).
1852 Intentionally unsupported GCC extensions
1853 ----------------------------------------
1855 - clang does not support the gcc extension that allows variable-length
1856 arrays in structures. This is for a few reasons: one, it is tricky to
1857 implement, two, the extension is completely undocumented, and three,
1858 the extension appears to be rarely used. Note that clang *does*
1859 support flexible array members (arrays with a zero or unspecified
1860 size at the end of a structure).
1861 - clang does not have an equivalent to gcc's "fold"; this means that
1862 clang doesn't accept some constructs gcc might accept in contexts
1863 where a constant expression is required, like "x-x" where x is a
1865 - clang does not support ``__builtin_apply`` and friends; this extension
1866 is extremely obscure and difficult to implement reliably.
1870 Microsoft extensions
1871 --------------------
1873 clang has support for many extensions from Microsoft Visual C++. To enable these
1874 extensions, use the ``-fms-extensions`` command-line option. This is the default
1875 for Windows targets. Clang does not implement every pragma or declspec provided
1876 by MSVC, but the popular ones, such as ``__declspec(dllexport)`` and ``#pragma
1877 comment(lib)`` are well supported.
1879 clang has a ``-fms-compatibility`` flag that makes clang accept enough
1880 invalid C++ to be able to parse most Microsoft headers. For example, it
1881 allows `unqualified lookup of dependent base class members
1882 <http://clang.llvm.org/compatibility.html#dep_lookup_bases>`_, which is
1883 a common compatibility issue with clang. This flag is enabled by default
1884 for Windows targets.
1886 ``-fdelayed-template-parsing`` lets clang delay parsing of function template
1887 definitions until the end of a translation unit. This flag is enabled by
1888 default for Windows targets.
1890 For compatibility with existing code that compiles with MSVC, clang defines the
1891 ``_MSC_VER`` and ``_MSC_FULL_VER`` macros. These default to the values of 1800
1892 and 180000000 respectively, making clang look like an early release of Visual
1893 C++ 2013. The ``-fms-compatibility-version=`` flag overrides these values. It
1894 accepts a dotted version tuple, such as 19.00.23506. Changing the MSVC
1895 compatibility version makes clang behave more like that version of MSVC. For
1896 example, ``-fms-compatibility-version=19`` will enable C++14 features and define
1897 ``char16_t`` and ``char32_t`` as builtin types.
1901 C++ Language Features
1902 =====================
1904 clang fully implements all of standard C++98 except for exported
1905 templates (which were removed in C++11), and all of standard C++11
1906 and the current draft standard for C++1y.
1908 Controlling implementation limits
1909 ---------------------------------
1911 .. option:: -fbracket-depth=N
1913 Sets the limit for nested parentheses, brackets, and braces to N. The
1916 .. option:: -fconstexpr-depth=N
1918 Sets the limit for recursive constexpr function invocations to N. The
1921 .. option:: -ftemplate-depth=N
1923 Sets the limit for recursively nested template instantiations to N. The
1926 .. option:: -foperator-arrow-depth=N
1928 Sets the limit for iterative calls to 'operator->' functions to N. The
1933 Objective-C Language Features
1934 =============================
1938 Objective-C++ Language Features
1939 ===============================
1946 Clang supports all OpenMP 3.1 directives and clauses. In addition, some
1947 features of OpenMP 4.0 are supported. For example, ``#pragma omp simd``,
1948 ``#pragma omp for simd``, ``#pragma omp parallel for simd`` directives, extended
1949 set of atomic constructs, ``proc_bind`` clause for all parallel-based
1950 directives, ``depend`` clause for ``#pragma omp task`` directive (except for
1951 array sections), ``#pragma omp cancel`` and ``#pragma omp cancellation point``
1952 directives, and ``#pragma omp taskgroup`` directive.
1954 Use `-fopenmp` to enable OpenMP. Support for OpenMP can be disabled with
1957 Controlling implementation limits
1958 ---------------------------------
1960 .. option:: -fopenmp-use-tls
1962 Controls code generation for OpenMP threadprivate variables. In presence of
1963 this option all threadprivate variables are generated the same way as thread
1964 local variables, using TLS support. If `-fno-openmp-use-tls`
1965 is provided or target does not support TLS, code generation for threadprivate
1966 variables relies on OpenMP runtime library.
1968 .. _target_features:
1970 Target-Specific Features and Limitations
1971 ========================================
1973 CPU Architectures Features and Limitations
1974 ------------------------------------------
1979 The support for X86 (both 32-bit and 64-bit) is considered stable on
1980 Darwin (Mac OS X), Linux, FreeBSD, and Dragonfly BSD: it has been tested
1981 to correctly compile many large C, C++, Objective-C, and Objective-C++
1984 On ``x86_64-mingw32``, passing i128(by value) is incompatible with the
1985 Microsoft x64 calling convention. You might need to tweak
1986 ``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp.
1988 For the X86 target, clang supports the `-m16` command line
1989 argument which enables 16-bit code output. This is broadly similar to
1990 using ``asm(".code16gcc")`` with the GNU toolchain. The generated code
1991 and the ABI remains 32-bit but the assembler emits instructions
1992 appropriate for a CPU running in 16-bit mode, with address-size and
1993 operand-size prefixes to enable 32-bit addressing and operations.
1998 The support for ARM (specifically ARMv6 and ARMv7) is considered stable
1999 on Darwin (iOS): it has been tested to correctly compile many large C,
2000 C++, Objective-C, and Objective-C++ codebases. Clang only supports a
2001 limited number of ARM architectures. It does not yet fully support
2007 The support for PowerPC (especially PowerPC64) is considered stable
2008 on Linux and FreeBSD: it has been tested to correctly compile many
2009 large C and C++ codebases. PowerPC (32bit) is still missing certain
2010 features (e.g. PIC code on ELF platforms).
2015 clang currently contains some support for other architectures (e.g. Sparc);
2016 however, significant pieces of code generation are still missing, and they
2017 haven't undergone significant testing.
2019 clang contains limited support for the MSP430 embedded processor, but
2020 both the clang support and the LLVM backend support are highly
2023 Other platforms are completely unsupported at the moment. Adding the
2024 minimal support needed for parsing and semantic analysis on a new
2025 platform is quite easy; see ``lib/Basic/Targets.cpp`` in the clang source
2026 tree. This level of support is also sufficient for conversion to LLVM IR
2027 for simple programs. Proper support for conversion to LLVM IR requires
2028 adding code to ``lib/CodeGen/CGCall.cpp`` at the moment; this is likely to
2029 change soon, though. Generating assembly requires a suitable LLVM
2032 Operating System Features and Limitations
2033 -----------------------------------------
2038 Thread Sanitizer is not supported.
2043 Clang has experimental support for targeting "Cygming" (Cygwin / MinGW)
2046 See also :ref:`Microsoft Extensions <c_ms>`.
2051 Clang works on Cygwin-1.7.
2056 Clang works on some mingw32 distributions. Clang assumes directories as
2059 - ``C:/mingw/include``
2061 - ``C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++``
2063 On MSYS, a few tests might fail.
2068 For 32-bit (i686-w64-mingw32), and 64-bit (x86\_64-w64-mingw32), Clang
2071 - ``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)``
2072 - ``some_directory/bin/gcc.exe``
2073 - ``some_directory/bin/clang.exe``
2074 - ``some_directory/bin/clang++.exe``
2075 - ``some_directory/bin/../include/c++/GCC_version``
2076 - ``some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32``
2077 - ``some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32``
2078 - ``some_directory/bin/../include/c++/GCC_version/backward``
2079 - ``some_directory/bin/../x86_64-w64-mingw32/include``
2080 - ``some_directory/bin/../i686-w64-mingw32/include``
2081 - ``some_directory/bin/../include``
2083 This directory layout is standard for any toolchain you will find on the
2084 official `MinGW-w64 website <http://mingw-w64.sourceforge.net>`_.
2086 Clang expects the GCC executable "gcc.exe" compiled for
2087 ``i686-w64-mingw32`` (or ``x86_64-w64-mingw32``) to be present on PATH.
2089 `Some tests might fail <http://llvm.org/bugs/show_bug.cgi?id=9072>`_ on
2090 ``x86_64-w64-mingw32``.
2097 clang-cl is an alternative command-line interface to Clang driver, designed for
2098 compatibility with the Visual C++ compiler, cl.exe.
2100 To enable clang-cl to find system headers, libraries, and the linker when run
2101 from the command-line, it should be executed inside a Visual Studio Native Tools
2102 Command Prompt or a regular Command Prompt where the environment has been set
2103 up using e.g. `vcvars32.bat <http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_.
2105 clang-cl can also be used from inside Visual Studio by using an LLVM Platform
2108 Command-Line Options
2109 --------------------
2111 To be compatible with cl.exe, clang-cl supports most of the same command-line
2112 options. Those options can start with either ``/`` or ``-``. It also supports
2113 some of Clang's core options, such as the ``-W`` options.
2115 Options that are known to clang-cl, but not currently supported, are ignored
2116 with a warning. For example:
2120 clang-cl.exe: warning: argument unused during compilation: '/AI'
2122 To suppress warnings about unused arguments, use the ``-Qunused-arguments`` option.
2124 Options that are not known to clang-cl will be ignored by default. Use the
2125 ``-Werror=unknown-argument`` option in order to treat them as errors. If these
2126 options are spelled with a leading ``/``, they will be mistaken for a filename:
2130 clang-cl.exe: error: no such file or directory: '/foobar'
2132 Please `file a bug <http://llvm.org/bugs/enter_bug.cgi?product=clang&component=Driver>`_
2133 for any valid cl.exe flags that clang-cl does not understand.
2135 Execute ``clang-cl /?`` to see a list of supported options:
2139 CL.EXE COMPATIBILITY OPTIONS:
2140 /? Display available options
2141 /arch:<value> Set architecture for code generation
2142 /Brepro- Emit an object file which cannot be reproduced over time
2143 /Brepro Emit an object file which can be reproduced over time
2144 /C Don't discard comments when preprocessing
2146 /D <macro[=value]> Define macro
2147 /EH<value> Exception handling model
2148 /EP Disable linemarker output and preprocess to stdout
2149 /E Preprocess to stdout
2150 /fallback Fall back to cl.exe if clang-cl fails to compile
2151 /FA Output assembly code file during compilation
2152 /Fa<file or directory> Output assembly code to this file during compilation (with /FA)
2153 /Fe<file or directory> Set output executable file or directory (ends in / or \)
2154 /FI <value> Include file before parsing
2155 /Fi<file> Set preprocess output file name (with /P)
2156 /Fo<file or directory> Set output object file, or directory (ends in / or \) (with /c)
2162 /Fp<filename> Set pch filename (with /Yc and /Yu)
2163 /GA Assume thread-local variables are defined in the executable
2164 /Gd Set __cdecl as a default calling convention
2165 /GF- Disable string pooling
2166 /GR- Disable emission of RTTI data
2167 /GR Enable emission of RTTI data
2168 /Gr Set __fastcall as a default calling convention
2169 /GS- Disable buffer security check
2170 /GS Enable buffer security check
2171 /Gs<value> Set stack probe size
2172 /Gv Set __vectorcall as a default calling convention
2173 /Gw- Don't put each data item in its own section
2174 /Gw Put each data item in its own section
2175 /GX- Enable exception handling
2176 /GX Enable exception handling
2177 /Gy- Don't put each function in its own section
2178 /Gy Put each function in its own section
2179 /Gz Set __stdcall as a default calling convention
2180 /help Display available options
2181 /imsvc <dir> Add directory to system include search path, as if part of %INCLUDE%
2182 /I <dir> Add directory to include search path
2183 /J Make char type unsigned
2184 /LDd Create debug DLL
2186 /link <options> Forward options to the linker
2187 /MDd Use DLL debug run-time
2188 /MD Use DLL run-time
2189 /MTd Use static debug run-time
2190 /MT Use static run-time
2191 /Od Disable optimization
2192 /Oi- Disable use of builtin functions
2193 /Oi Enable use of builtin functions
2194 /Os Optimize for size
2195 /Ot Optimize for speed
2196 /O<value> Optimization level
2197 /o <file or directory> Set output file or directory (ends in / or \)
2198 /P Preprocess to file
2199 /Qvec- Disable the loop vectorization passes
2200 /Qvec Enable the loop vectorization passes
2201 /showIncludes Print info about included files to stderr
2202 /std:<value> Language standard to compile for
2203 /TC Treat all source files as C
2204 /Tc <filename> Specify a C source file
2205 /TP Treat all source files as C++
2206 /Tp <filename> Specify a C++ source file
2207 /U <macro> Undefine macro
2208 /vd<value> Control vtordisp placement
2209 /vmb Use a best-case representation method for member pointers
2210 /vmg Use a most-general representation for member pointers
2211 /vmm Set the default most-general representation to multiple inheritance
2212 /vms Set the default most-general representation to single inheritance
2213 /vmv Set the default most-general representation to virtual inheritance
2214 /volatile:iso Volatile loads and stores have standard semantics
2215 /volatile:ms Volatile loads and stores have acquire and release semantics
2216 /W0 Disable all warnings
2220 /W4 Enable -Wall and -Wextra
2221 /Wall Enable -Wall and -Wextra
2222 /WX- Do not treat warnings as errors
2223 /WX Treat warnings as errors
2224 /w Disable all warnings
2225 /Y- Disable precompiled headers, overrides /Yc and /Yu
2226 /Yc<filename> Generate a pch file for all code up to and including <filename>
2227 /Yu<filename> Load a pch file and use it instead of all code up to and including <filename>
2228 /Z7 Enable CodeView debug information in object files
2229 /Zc:sizedDealloc- Disable C++14 sized global deallocation functions
2230 /Zc:sizedDealloc Enable C++14 sized global deallocation functions
2231 /Zc:strictStrings Treat string literals as const
2232 /Zc:threadSafeInit- Disable thread-safe initialization of static variables
2233 /Zc:threadSafeInit Enable thread-safe initialization of static variables
2234 /Zc:trigraphs- Disable trigraphs (default)
2235 /Zc:trigraphs Enable trigraphs
2236 /Zd Emit debug line number tables only
2237 /Zi Alias for /Z7. Does not produce PDBs.
2238 /Zl Don't mention any default libraries in the object file
2239 /Zp Set the default maximum struct packing alignment to 1
2240 /Zp<value> Specify the default maximum struct packing alignment
2241 /Zs Syntax-check only
2244 -### Print (but do not run) the commands to run for this compilation
2245 --analyze Run the static analyzer
2246 -fansi-escape-codes Use ANSI escape codes for diagnostics
2247 -fcolor-diagnostics Use colors in diagnostics
2248 -fdiagnostics-parseable-fixits
2249 Print fix-its in machine parseable form
2250 -fms-compatibility-version=<value>
2251 Dot-separated value representing the Microsoft compiler version
2252 number to report in _MSC_VER (0 = don't define it (default))
2253 -fms-compatibility Enable full Microsoft Visual C++ compatibility
2254 -fms-extensions Accept some non-standard constructs supported by the Microsoft compiler
2255 -fmsc-version=<value> Microsoft compiler version number to report in _MSC_VER
2256 (0 = don't define it (default))
2257 -fno-sanitize-coverage=<value>
2258 Disable specified features of coverage instrumentation for Sanitizers
2259 -fno-sanitize-recover=<value>
2260 Disable recovery for specified sanitizers
2261 -fno-sanitize-trap=<value>
2262 Disable trapping for specified sanitizers
2263 -fsanitize-blacklist=<value>
2264 Path to blacklist file for sanitizers
2265 -fsanitize-coverage=<value>
2266 Specify the type of coverage instrumentation for Sanitizers
2267 -fsanitize-recover=<value>
2268 Enable recovery for specified sanitizers
2269 -fsanitize-trap=<value> Enable trapping for specified sanitizers
2270 -fsanitize=<check> Turn on runtime checks for various forms of undefined or suspicious
2271 behavior. See user manual for available checks
2272 -gcodeview Generate CodeView debug information
2273 -gline-tables-only Emit debug line number tables only
2274 -miamcu Use Intel MCU ABI
2275 -mllvm <value> Additional arguments to forward to LLVM's option processing
2276 -Qunused-arguments Don't emit warning for unused driver arguments
2277 -R<remark> Enable the specified remark
2278 --target=<value> Generate code for the given target
2279 -v Show commands to run and use verbose output
2280 -W<warning> Enable the specified warning
2281 -Xclang <arg> Pass <arg> to the clang compiler
2283 The /fallback Option
2284 ^^^^^^^^^^^^^^^^^^^^
2286 When clang-cl is run with the ``/fallback`` option, it will first try to
2287 compile files itself. For any file that it fails to compile, it will fall back
2288 and try to compile the file by invoking cl.exe.
2290 This option is intended to be used as a temporary means to build projects where
2291 clang-cl cannot successfully compile all the files. clang-cl may fail to compile
2292 a file either because it cannot generate code for some C++ feature, or because
2293 it cannot parse some Microsoft language extension.