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 one component in a complete toolchain for C family languages.
29 A separate document describes the other pieces necessary to
30 :doc:`assemble a complete toolchain <Toolchain>`.
32 Clang is designed to support the C family of programming languages,
33 which includes :ref:`C <c>`, :ref:`Objective-C <objc>`, :ref:`C++ <cxx>`, and
34 :ref:`Objective-C++ <objcxx>` as well as many dialects of those. For
35 language-specific information, please see the corresponding language
38 - :ref:`C Language <c>`: K&R C, ANSI C89, ISO C90, ISO C94 (C89+AMD1), ISO
40 - :ref:`Objective-C Language <objc>`: ObjC 1, ObjC 2, ObjC 2.1, plus
41 variants depending on base language.
42 - :ref:`C++ Language <cxx>`
43 - :ref:`Objective C++ Language <objcxx>`
44 - :ref:`OpenCL C Language <opencl>`: v1.0, v1.1, v1.2, v2.0.
46 In addition to these base languages and their dialects, Clang supports a
47 broad variety of language extensions, which are documented in the
48 corresponding language section. These extensions are provided to be
49 compatible with the GCC, Microsoft, and other popular compilers as well
50 as to improve functionality through Clang-specific features. The Clang
51 driver and language features are intentionally designed to be as
52 compatible with the GNU GCC compiler as reasonably possible, easing
53 migration from GCC to Clang. In most cases, code "just works".
54 Clang also provides an alternative driver, :ref:`clang-cl`, that is designed
55 to be compatible with the Visual C++ compiler, cl.exe.
57 In addition to language specific features, Clang has a variety of
58 features that depend on what CPU architecture or operating system is
59 being compiled for. Please see the :ref:`Target-Specific Features and
60 Limitations <target_features>` section for more details.
62 The rest of the introduction introduces some basic :ref:`compiler
63 terminology <terminology>` that is used throughout this manual and
64 contains a basic :ref:`introduction to using Clang <basicusage>` as a
65 command line compiler.
72 Front end, parser, backend, preprocessor, undefined behavior,
80 Intro to how to use a C compiler for newbies.
82 compile + link compile then link debug info enabling optimizations
83 picking a language to use, defaults to C11 by default. Autosenses based
84 on extension. using a makefile
89 This section is generally an index into other sections. It does not go
90 into depth on the ones that are covered by other sections. However, the
91 first part introduces the language selection and other high level
92 options like :option:`-c`, :option:`-g`, etc.
94 Options to Control Error and Warning Messages
95 ---------------------------------------------
99 Turn warnings into errors.
101 .. This is in plain monospaced font because it generates the same label as
102 .. -Werror, and Sphinx complains.
106 Turn warning "foo" into an error.
108 .. option:: -Wno-error=foo
110 Turn warning "foo" into a warning even if :option:`-Werror` is specified.
114 Enable warning "foo".
115 See the :doc:`diagnostics reference <DiagnosticsReference>` for a complete
116 list of the warning flags that can be specified in this way.
120 Disable warning "foo".
124 Disable all diagnostics.
126 .. option:: -Weverything
128 :ref:`Enable all diagnostics. <diagnostics_enable_everything>`
130 .. option:: -pedantic
132 Warn on language extensions.
134 .. option:: -pedantic-errors
136 Error on language extensions.
138 .. option:: -Wsystem-headers
140 Enable warnings from system headers.
142 .. option:: -ferror-limit=123
144 Stop emitting diagnostics after 123 errors have been produced. The default is
145 20, and the error limit can be disabled with `-ferror-limit=0`.
147 .. option:: -ftemplate-backtrace-limit=123
149 Only emit up to 123 template instantiation notes within the template
150 instantiation backtrace for a single warning or error. The default is 10, and
151 the limit can be disabled with `-ftemplate-backtrace-limit=0`.
153 .. _cl_diag_formatting:
155 Formatting of Diagnostics
156 ^^^^^^^^^^^^^^^^^^^^^^^^^
158 Clang aims to produce beautiful diagnostics by default, particularly for
159 new users that first come to Clang. However, different people have
160 different preferences, and sometimes Clang is driven not by a human,
161 but by a program that wants consistent and easily parsable output. For
162 these cases, Clang provides a wide range of options to control the exact
163 output format of the diagnostics that it generates.
165 .. _opt_fshow-column:
167 **-f[no-]show-column**
168 Print column number in diagnostic.
170 This option, which defaults to on, controls whether or not Clang
171 prints the column number of a diagnostic. For example, when this is
172 enabled, Clang will print something like:
176 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
181 When this is disabled, Clang will print "test.c:28: warning..." with
184 The printed column numbers count bytes from the beginning of the
185 line; take care if your source contains multibyte characters.
187 .. _opt_fshow-source-location:
189 **-f[no-]show-source-location**
190 Print source file/line/column information in diagnostic.
192 This option, which defaults to on, controls whether or not Clang
193 prints the filename, line number and column number of a diagnostic.
194 For example, when this is enabled, Clang will print something like:
198 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
203 When this is disabled, Clang will not print the "test.c:28:8: "
206 .. _opt_fcaret-diagnostics:
208 **-f[no-]caret-diagnostics**
209 Print source line and ranges from source code in diagnostic.
210 This option, which defaults to on, controls whether or not Clang
211 prints the source line, source ranges, and caret when emitting a
212 diagnostic. For example, when this is enabled, Clang will print
217 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
222 **-f[no-]color-diagnostics**
223 This option, which defaults to on when a color-capable terminal is
224 detected, controls whether or not Clang prints diagnostics in color.
226 When this option is enabled, Clang will use colors to highlight
227 specific parts of the diagnostic, e.g.,
229 .. nasty hack to not lose our dignity
234 <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>
236 <span style="color:green">^</span>
237 <span style="color:green">//</span>
240 When this is disabled, Clang will just print:
244 test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
249 **-fansi-escape-codes**
250 Controls whether ANSI escape codes are used instead of the Windows Console
251 API to output colored diagnostics. This option is only used on Windows and
254 .. option:: -fdiagnostics-format=clang/msvc/vi
256 Changes diagnostic output format to better match IDEs and command line tools.
258 This option controls the output format of the filename, line number,
259 and column printed in diagnostic messages. The options, and their
260 affect on formatting a simple conversion diagnostic, follow:
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'
275 t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
277 .. _opt_fdiagnostics-show-option:
279 **-f[no-]diagnostics-show-option**
280 Enable ``[-Woption]`` information in diagnostic line.
282 This option, which defaults to on, controls whether or not Clang
283 prints the associated :ref:`warning group <cl_diag_warning_groups>`
284 option name when outputting a warning diagnostic. For example, in
289 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
294 Passing **-fno-diagnostics-show-option** will prevent Clang from
295 printing the [:ref:`-Wextra-tokens <opt_Wextra-tokens>`] information in
296 the diagnostic. This information tells you the flag needed to enable
297 or disable the diagnostic, either from the command line or through
298 :ref:`#pragma GCC diagnostic <pragma_GCC_diagnostic>`.
300 .. _opt_fdiagnostics-show-category:
302 .. option:: -fdiagnostics-show-category=none/id/name
304 Enable printing category information in diagnostic line.
306 This option, which defaults to "none", controls whether or not Clang
307 prints the category associated with a diagnostic when emitting it.
308 Each diagnostic may or many not have an associated category, if it
309 has one, it is listed in the diagnostic categorization field of the
310 diagnostic line (in the []'s).
312 For example, a format string warning will produce these three
313 renditions based on the setting of this option:
317 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat]
318 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1]
319 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String]
321 This category can be used by clients that want to group diagnostics
322 by category, so it should be a high level category. We want dozens
323 of these, not hundreds or thousands of them.
325 .. _opt_fsave-optimization-record:
327 **-fsave-optimization-record**
328 Write optimization remarks to a YAML file.
330 This option, which defaults to off, controls whether Clang writes
331 optimization reports to a YAML file. By recording diagnostics in a file,
332 using a structured YAML format, users can parse or sort the remarks in a
335 .. _opt_foptimization-record-file:
337 **-foptimization-record-file**
338 Control the file to which optimization reports are written.
340 When optimization reports are being output (see
341 :ref:`-fsave-optimization-record <opt_fsave-optimization-record>`), this
342 option controls the file to which those reports are written.
344 If this option is not used, optimization records are output to a file named
345 after the primary file being compiled. If that's "foo.c", for example,
346 optimization records are output to "foo.opt.yaml".
348 .. _opt_fdiagnostics-show-hotness:
350 **-f[no-]diagnostics-show-hotness**
351 Enable profile hotness information in diagnostic line.
353 This option controls whether Clang prints the profile hotness associated
354 with diagnostics in the presence of profile-guided optimization information.
355 This is currently supported with optimization remarks (see
356 :ref:`Options to Emit Optimization Reports <rpass>`). The hotness information
357 allows users to focus on the hot optimization remarks that are likely to be
358 more relevant for run-time performance.
360 For example, in this output, the block containing the callsite of `foo` was
361 executed 3000 times according to the profile data:
365 s.c:7:10: remark: foo inlined into bar (hotness: 3000) [-Rpass-analysis=inline]
366 sum += foo(x, x - 2);
369 This option is implied when
370 :ref:`-fsave-optimization-record <opt_fsave-optimization-record>` is used.
371 Otherwise, it defaults to off.
373 .. _opt_fdiagnostics-hotness-threshold:
375 **-fdiagnostics-hotness-threshold**
376 Prevent optimization remarks from being output if they do not have at least
379 This option, which defaults to zero, controls the minimum hotness an
380 optimization remark would need in order to be output by Clang. This is
381 currently supported with optimization remarks (see :ref:`Options to Emit
382 Optimization Reports <rpass>`) when profile hotness information in
383 diagnostics is enabled (see
384 :ref:`-fdiagnostics-show-hotness <opt_fdiagnostics-show-hotness>`).
386 .. _opt_fdiagnostics-fixit-info:
388 **-f[no-]diagnostics-fixit-info**
389 Enable "FixIt" information in the diagnostics output.
391 This option, which defaults to on, controls whether or not Clang
392 prints the information on how to fix a specific diagnostic
393 underneath it when it knows. For example, in this output:
397 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
402 Passing **-fno-diagnostics-fixit-info** will prevent Clang from
403 printing the "//" line at the end of the message. This information
404 is useful for users who may not understand what is wrong, but can be
405 confusing for machine parsing.
407 .. _opt_fdiagnostics-print-source-range-info:
409 **-fdiagnostics-print-source-range-info**
410 Print machine parsable information about source ranges.
411 This option makes Clang print information about source ranges in a machine
412 parsable format after the file/line/column number information. The
413 information is a simple sequence of brace enclosed ranges, where each range
414 lists the start and end line/column locations. For example, in this output:
418 exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float')
419 P = (P-42) + Gamma*4;
422 The {}'s are generated by -fdiagnostics-print-source-range-info.
424 The printed column numbers count bytes from the beginning of the
425 line; take care if your source contains multibyte characters.
427 .. option:: -fdiagnostics-parseable-fixits
429 Print Fix-Its in a machine parseable form.
431 This option makes Clang print available Fix-Its in a machine
432 parseable format at the end of diagnostics. The following example
433 illustrates the format:
437 fix-it:"t.cpp":{7:25-7:29}:"Gamma"
439 The range printed is a half-open range, so in this example the
440 characters at column 25 up to but not including column 29 on line 7
441 in t.cpp should be replaced with the string "Gamma". Either the
442 range or the replacement string may be empty (representing strict
443 insertions and strict erasures, respectively). Both the file name
444 and the insertion string escape backslash (as "\\\\"), tabs (as
445 "\\t"), newlines (as "\\n"), double quotes(as "\\"") and
446 non-printable characters (as octal "\\xxx").
448 The printed column numbers count bytes from the beginning of the
449 line; take care if your source contains multibyte characters.
451 .. option:: -fno-elide-type
453 Turns off elision in template type printing.
455 The default for template type printing is to elide as many template
456 arguments as possible, removing those which are the same in both
457 template types, leaving only the differences. Adding this flag will
458 print all the template arguments. If supported by the terminal,
459 highlighting will still appear on differing arguments.
465 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;
471 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;
473 .. option:: -fdiagnostics-show-template-tree
475 Template type diffing prints a text tree.
477 For diffing large templated types, this option will cause Clang to
478 display the templates as an indented text tree, one argument per
479 line, with differences marked inline. This is compatible with
486 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;
488 With :option:`-fdiagnostics-show-template-tree`:
492 t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument;
500 .. _cl_diag_warning_groups:
502 Individual Warning Groups
503 ^^^^^^^^^^^^^^^^^^^^^^^^^
505 TODO: Generate this from tblgen. Define one anchor per warning group.
507 .. _opt_wextra-tokens:
509 .. option:: -Wextra-tokens
511 Warn about excess tokens at the end of a preprocessor directive.
513 This option, which defaults to on, enables warnings about extra
514 tokens at the end of preprocessor directives. For example:
518 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
522 These extra tokens are not strictly conforming, and are usually best
523 handled by commenting them out.
525 .. option:: -Wambiguous-member-template
527 Warn about unqualified uses of a member template whose name resolves to
528 another template at the location of the use.
530 This option, which defaults to on, enables a warning in the
535 template<typename T> struct set{};
536 template<typename T> struct trait { typedef const T& type; };
538 template<typename T> void set(typename trait<T>::type value) {}
545 C++ [basic.lookup.classref] requires this to be an error, but,
546 because it's hard to work around, Clang downgrades it to a warning
549 .. option:: -Wbind-to-temporary-copy
551 Warn about an unusable copy constructor when binding a reference to a
554 This option enables warnings about binding a
555 reference to a temporary when the temporary doesn't have a usable
556 copy constructor. For example:
563 NonCopyable(const NonCopyable&);
565 void foo(const NonCopyable&);
567 foo(NonCopyable()); // Disallowed in C++98; allowed in C++11.
572 struct NonCopyable2 {
574 NonCopyable2(NonCopyable2&);
576 void foo(const NonCopyable2&);
578 foo(NonCopyable2()); // Disallowed in C++98; allowed in C++11.
581 Note that if ``NonCopyable2::NonCopyable2()`` has a default argument
582 whose instantiation produces a compile error, that error will still
583 be a hard error in C++98 mode even if this warning is turned off.
585 Options to Control Clang Crash Diagnostics
586 ------------------------------------------
588 As unbelievable as it may sound, Clang does crash from time to time.
589 Generally, this only occurs to those living on the `bleeding
590 edge <http://llvm.org/releases/download.html#svn>`_. Clang goes to great
591 lengths to assist you in filing a bug report. Specifically, Clang
592 generates preprocessed source file(s) and associated run script(s) upon
593 a crash. These files should be attached to a bug report to ease
594 reproducibility of the failure. Below are the command line options to
595 control the crash diagnostics.
597 .. option:: -fno-crash-diagnostics
599 Disable auto-generation of preprocessed source files during a clang crash.
601 The -fno-crash-diagnostics flag can be helpful for speeding the process
602 of generating a delta reduced test case.
604 Clang is also capable of generating preprocessed source file(s) and associated
605 run script(s) even without a crash. This is specially useful when trying to
606 generate a reproducer for warnings or errors while using modules.
608 .. option:: -gen-reproducer
610 Generates preprocessed source files, a reproducer script and if relevant, a
611 cache containing: built module pcm's and all headers needed to rebuilt the
616 Options to Emit Optimization Reports
617 ------------------------------------
619 Optimization reports trace, at a high-level, all the major decisions
620 done by compiler transformations. For instance, when the inliner
621 decides to inline function ``foo()`` into ``bar()``, or the loop unroller
622 decides to unroll a loop N times, or the vectorizer decides to
623 vectorize a loop body.
625 Clang offers a family of flags which the optimizers can use to emit
626 a diagnostic in three cases:
628 1. When the pass makes a transformation (`-Rpass`).
630 2. When the pass fails to make a transformation (`-Rpass-missed`).
632 3. When the pass determines whether or not to make a transformation
635 NOTE: Although the discussion below focuses on `-Rpass`, the exact
636 same options apply to `-Rpass-missed` and `-Rpass-analysis`.
638 Since there are dozens of passes inside the compiler, each of these flags
639 take a regular expression that identifies the name of the pass which should
640 emit the associated diagnostic. For example, to get a report from the inliner,
641 compile the code with:
643 .. code-block:: console
645 $ clang -O2 -Rpass=inline code.cc -o code
646 code.cc:4:25: remark: foo inlined into bar [-Rpass=inline]
647 int bar(int j) { return foo(j, j - 2); }
650 Note that remarks from the inliner are identified with `[-Rpass=inline]`.
651 To request a report from every optimization pass, you should use
652 `-Rpass=.*` (in fact, you can use any valid POSIX regular
653 expression). However, do not expect a report from every transformation
654 made by the compiler. Optimization remarks do not really make sense
655 outside of the major transformations (e.g., inlining, vectorization,
656 loop optimizations) and not every optimization pass supports this
659 Note that when using profile-guided optimization information, profile hotness
660 information can be included in the remarks (see
661 :ref:`-fdiagnostics-show-hotness <opt_fdiagnostics-show-hotness>`).
666 1. Optimization remarks that refer to function names will display the
667 mangled name of the function. Since these remarks are emitted by the
668 back end of the compiler, it does not know anything about the input
669 language, nor its mangling rules.
671 2. Some source locations are not displayed correctly. The front end has
672 a more detailed source location tracking than the locations included
673 in the debug info (e.g., the front end can locate code inside macro
674 expansions). However, the locations used by `-Rpass` are
675 translated from debug annotations. That translation can be lossy,
676 which results in some remarks having no location information.
680 Clang options that don't fit neatly into other categories.
684 When emitting a dependency file, use formatting conventions appropriate
685 for NMake or Jom. Ignored unless another option causes Clang to emit a
688 When Clang emits a dependency file (e.g., you supplied the -M option)
689 most filenames can be written to the file without any special formatting.
690 Different Make tools will treat different sets of characters as "special"
691 and use different conventions for telling the Make tool that the character
692 is actually part of the filename. Normally Clang uses backslash to "escape"
693 a special character, which is the convention used by GNU Make. The -MV
694 option tells Clang to put double-quotes around the entire filename, which
695 is the convention used by NMake and Jom.
700 Configuration files group command-line options and allow all of them to be
701 specified just by referencing the configuration file. They may be used, for
702 example, to collect options required to tune compilation for particular
703 target, such as -L, -I, -l, --sysroot, codegen options, etc.
705 The command line option `--config` can be used to specify configuration
706 file in a Clang invocation. For example:
710 clang --config /home/user/cfgs/testing.txt
711 clang --config debug.cfg
713 If the provided argument contains a directory separator, it is considered as
714 a file path, and options are read from that file. Otherwise the argument is
715 treated as a file name and is searched for sequentially in the directories:
719 - the directory where Clang executable resides.
721 Both user and system directories for configuration files are specified during
722 clang build using CMake parameters, CLANG_CONFIG_FILE_USER_DIR and
723 CLANG_CONFIG_FILE_SYSTEM_DIR respectively. The first file found is used. It is
724 an error if the required file cannot be found.
726 Another way to specify a configuration file is to encode it in executable name.
727 For example, if the Clang executable is named `armv7l-clang` (it may be a
728 symbolic link to `clang`), then Clang will search for file `armv7l.cfg` in the
729 directory where Clang resides.
731 If a driver mode is specified in invocation, Clang tries to find a file specific
732 for the specified mode. For example, if the executable file is named
733 `x86_64-clang-cl`, Clang first looks for `x86_64-cl.cfg` and if it is not found,
734 looks for `x86_64.cfg`.
736 If the command line contains options that effectively change target architecture
737 (these are -m32, -EL, and some others) and the configuration file starts with an
738 architecture name, Clang tries to load the configuration file for the effective
739 architecture. For example, invocation:
743 x86_64-clang -m32 abc.c
745 causes Clang search for a file `i368.cfg` first, and if no such file is found,
746 Clang looks for the file `x86_64.cfg`.
748 The configuration file consists of command-line options specified on one or
749 more lines. Lines composed of whitespace characters only are ignored as well as
750 lines in which the first non-blank character is `#`. Long options may be split
751 between several lines by a trailing backslash. Here is example of a
756 # Several options on line
757 -c --target=x86_64-unknown-linux-gnu
759 # Long option split between lines
760 -I/usr/lib/gcc/x86_64-linux-gnu/5.4.0/../../../../\
763 # other config files may be included
766 Files included by `@file` directives in configuration files are resolved
767 relative to the including file. For example, if a configuration file
768 `~/.llvm/target.cfg` contains the directive `@os/linux.opts`, the file
769 `linux.opts` is searched for in the directory `~/.llvm/os`.
771 Language and Target-Independent Features
772 ========================================
774 Controlling Errors and Warnings
775 -------------------------------
777 Clang provides a number of ways to control which code constructs cause
778 it to emit errors and warning messages, and how they are displayed to
781 Controlling How Clang Displays Diagnostics
782 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
784 When Clang emits a diagnostic, it includes rich information in the
785 output, and gives you fine-grain control over which information is
786 printed. Clang has the ability to print this information, and these are
787 the options that control it:
789 #. A file/line/column indicator that shows exactly where the diagnostic
790 occurs in your code [:ref:`-fshow-column <opt_fshow-column>`,
791 :ref:`-fshow-source-location <opt_fshow-source-location>`].
792 #. A categorization of the diagnostic as a note, warning, error, or
794 #. A text string that describes what the problem is.
795 #. An option that indicates how to control the diagnostic (for
796 diagnostics that support it)
797 [:ref:`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`].
798 #. A :ref:`high-level category <diagnostics_categories>` for the diagnostic
799 for clients that want to group diagnostics by class (for diagnostics
801 [:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>`].
802 #. The line of source code that the issue occurs on, along with a caret
803 and ranges that indicate the important locations
804 [:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`].
805 #. "FixIt" information, which is a concise explanation of how to fix the
806 problem (when Clang is certain it knows)
807 [:ref:`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`].
808 #. A machine-parsable representation of the ranges involved (off by
810 [:ref:`-fdiagnostics-print-source-range-info <opt_fdiagnostics-print-source-range-info>`].
812 For more information please see :ref:`Formatting of
813 Diagnostics <cl_diag_formatting>`.
818 All diagnostics are mapped into one of these 6 classes:
827 .. _diagnostics_categories:
829 Diagnostic Categories
830 ^^^^^^^^^^^^^^^^^^^^^
832 Though not shown by default, diagnostics may each be associated with a
833 high-level category. This category is intended to make it possible to
834 triage builds that produce a large number of errors or warnings in a
837 Categories are not shown by default, but they can be turned on with the
838 :ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>` option.
839 When set to "``name``", the category is printed textually in the
840 diagnostic output. When it is set to "``id``", a category number is
841 printed. The mapping of category names to category id's can be obtained
842 by running '``clang --print-diagnostic-categories``'.
844 Controlling Diagnostics via Command Line Flags
845 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
847 TODO: -W flags, -pedantic, etc
849 .. _pragma_gcc_diagnostic:
851 Controlling Diagnostics via Pragmas
852 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
854 Clang can also control what diagnostics are enabled through the use of
855 pragmas in the source code. This is useful for turning off specific
856 warnings in a section of source code. Clang supports GCC's pragma for
857 compatibility with existing source code, as well as several extensions.
859 The pragma may control any warning that can be used from the command
860 line. Warnings may be set to ignored, warning, error, or fatal. The
861 following example code will tell Clang or GCC to ignore the -Wall
866 #pragma GCC diagnostic ignored "-Wall"
868 In addition to all of the functionality provided by GCC's pragma, Clang
869 also allows you to push and pop the current warning state. This is
870 particularly useful when writing a header file that will be compiled by
871 other people, because you don't know what warning flags they build with.
873 In the below example :option:`-Wextra-tokens` is ignored for only a single line
874 of code, after which the diagnostics return to whatever state had previously
880 #endif foo // warning: extra tokens at end of #endif directive
882 #pragma clang diagnostic push
883 #pragma clang diagnostic ignored "-Wextra-tokens"
886 #endif foo // no warning
888 #pragma clang diagnostic pop
890 The push and pop pragmas will save and restore the full diagnostic state
891 of the compiler, regardless of how it was set. That means that it is
892 possible to use push and pop around GCC compatible diagnostics and Clang
893 will push and pop them appropriately, while GCC will ignore the pushes
894 and pops as unknown pragmas. It should be noted that while Clang
895 supports the GCC pragma, Clang and GCC do not support the exact same set
896 of warnings, so even when using GCC compatible #pragmas there is no
897 guarantee that they will have identical behaviour on both compilers.
899 In addition to controlling warnings and errors generated by the compiler, it is
900 possible to generate custom warning and error messages through the following
905 // The following will produce warning messages
906 #pragma message "some diagnostic message"
907 #pragma GCC warning "TODO: replace deprecated feature"
909 // The following will produce an error message
910 #pragma GCC error "Not supported"
912 These pragmas operate similarly to the ``#warning`` and ``#error`` preprocessor
913 directives, except that they may also be embedded into preprocessor macros via
914 the C99 ``_Pragma`` operator, for example:
919 #define DEFER(M,...) M(__VA_ARGS__)
920 #define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__))))
922 CUSTOM_ERROR("Feature not available");
924 Controlling Diagnostics in System Headers
925 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
927 Warnings are suppressed when they occur in system headers. By default,
928 an included file is treated as a system header if it is found in an
929 include path specified by ``-isystem``, but this can be overridden in
932 The ``system_header`` pragma can be used to mark the current file as
933 being a system header. No warnings will be produced from the location of
934 the pragma onwards within the same file.
939 #endif foo // warning: extra tokens at end of #endif directive
941 #pragma clang system_header
944 #endif foo // no warning
946 The `--system-header-prefix=` and `--no-system-header-prefix=`
947 command-line arguments can be used to override whether subsets of an include
948 path are treated as system headers. When the name in a ``#include`` directive
949 is found within a header search path and starts with a system prefix, the
950 header is treated as a system header. The last prefix on the
951 command-line which matches the specified header name takes precedence.
954 .. code-block:: console
956 $ clang -Ifoo -isystem bar --system-header-prefix=x/ \
957 --no-system-header-prefix=x/y/
959 Here, ``#include "x/a.h"`` is treated as including a system header, even
960 if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated
961 as not including a system header, even if the header is found in
964 A ``#include`` directive which finds a file relative to the current
965 directory is treated as including a system header if the including file
966 is treated as a system header.
968 .. _diagnostics_enable_everything:
970 Enabling All Diagnostics
971 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
973 In addition to the traditional ``-W`` flags, one can enable **all**
974 diagnostics by passing :option:`-Weverything`. This works as expected
976 :option:`-Werror`, and also includes the warnings from :option:`-pedantic`.
978 Note that when combined with :option:`-w` (which disables all warnings), that
981 Controlling Static Analyzer Diagnostics
982 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
984 While not strictly part of the compiler, the diagnostics from Clang's
985 `static analyzer <http://clang-analyzer.llvm.org>`_ can also be
986 influenced by the user via changes to the source code. See the available
987 `annotations <http://clang-analyzer.llvm.org/annotations.html>`_ and the
989 page <http://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more
992 .. _usersmanual-precompiled-headers:
997 `Precompiled headers <http://en.wikipedia.org/wiki/Precompiled_header>`__
998 are a general approach employed by many compilers to reduce compilation
999 time. The underlying motivation of the approach is that it is common for
1000 the same (and often large) header files to be included by multiple
1001 source files. Consequently, compile times can often be greatly improved
1002 by caching some of the (redundant) work done by a compiler to process
1003 headers. Precompiled header files, which represent one of many ways to
1004 implement this optimization, are literally files that represent an
1005 on-disk cache that contains the vital information necessary to reduce
1006 some of the work needed to process a corresponding header file. While
1007 details of precompiled headers vary between compilers, precompiled
1008 headers have been shown to be highly effective at speeding up program
1009 compilation on systems with very large system headers (e.g., Mac OS X).
1011 Generating a PCH File
1012 ^^^^^^^^^^^^^^^^^^^^^
1014 To generate a PCH file using Clang, one invokes Clang with the
1015 `-x <language>-header` option. This mirrors the interface in GCC
1016 for generating PCH files:
1018 .. code-block:: console
1020 $ gcc -x c-header test.h -o test.h.gch
1021 $ clang -x c-header test.h -o test.h.pch
1026 A PCH file can then be used as a prefix header when a :option:`-include`
1027 option is passed to ``clang``:
1029 .. code-block:: console
1031 $ clang -include test.h test.c -o test
1033 The ``clang`` driver will first check if a PCH file for ``test.h`` is
1034 available; if so, the contents of ``test.h`` (and the files it includes)
1035 will be processed from the PCH file. Otherwise, Clang falls back to
1036 directly processing the content of ``test.h``. This mirrors the behavior
1041 Clang does *not* automatically use PCH files for headers that are directly
1042 included within a source file. For example:
1044 .. code-block:: console
1046 $ clang -x c-header test.h -o test.h.pch
1049 $ clang test.c -o test
1051 In this example, ``clang`` will not automatically use the PCH file for
1052 ``test.h`` since ``test.h`` was included directly in the source file and not
1053 specified on the command line using :option:`-include`.
1055 Relocatable PCH Files
1056 ^^^^^^^^^^^^^^^^^^^^^
1058 It is sometimes necessary to build a precompiled header from headers
1059 that are not yet in their final, installed locations. For example, one
1060 might build a precompiled header within the build tree that is then
1061 meant to be installed alongside the headers. Clang permits the creation
1062 of "relocatable" precompiled headers, which are built with a given path
1063 (into the build directory) and can later be used from an installed
1066 To build a relocatable precompiled header, place your headers into a
1067 subdirectory whose structure mimics the installed location. For example,
1068 if you want to build a precompiled header for the header ``mylib.h``
1069 that will be installed into ``/usr/include``, create a subdirectory
1070 ``build/usr/include`` and place the header ``mylib.h`` into that
1071 subdirectory. If ``mylib.h`` depends on other headers, then they can be
1072 stored within ``build/usr/include`` in a way that mimics the installed
1075 Building a relocatable precompiled header requires two additional
1076 arguments. First, pass the ``--relocatable-pch`` flag to indicate that
1077 the resulting PCH file should be relocatable. Second, pass
1078 ``-isysroot /path/to/build``, which makes all includes for your library
1079 relative to the build directory. For example:
1081 .. code-block:: console
1083 # clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
1085 When loading the relocatable PCH file, the various headers used in the
1086 PCH file are found from the system header root. For example, ``mylib.h``
1087 can be found in ``/usr/include/mylib.h``. If the headers are installed
1088 in some other system root, the ``-isysroot`` option can be used provide
1089 a different system root from which the headers will be based. For
1090 example, ``-isysroot /Developer/SDKs/MacOSX10.4u.sdk`` will look for
1091 ``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``.
1093 Relocatable precompiled headers are intended to be used in a limited
1094 number of cases where the compilation environment is tightly controlled
1095 and the precompiled header cannot be generated after headers have been
1098 .. _controlling-code-generation:
1100 Controlling Code Generation
1101 ---------------------------
1103 Clang provides a number of ways to control code generation. The options
1106 **-f[no-]sanitize=check1,check2,...**
1107 Turn on runtime checks for various forms of undefined or suspicious
1110 This option controls whether Clang adds runtime checks for various
1111 forms of undefined or suspicious behavior, and is disabled by
1112 default. If a check fails, a diagnostic message is produced at
1113 runtime explaining the problem. The main checks are:
1115 - .. _opt_fsanitize_address:
1117 ``-fsanitize=address``:
1118 :doc:`AddressSanitizer`, a memory error
1120 - .. _opt_fsanitize_thread:
1122 ``-fsanitize=thread``: :doc:`ThreadSanitizer`, a data race detector.
1123 - .. _opt_fsanitize_memory:
1125 ``-fsanitize=memory``: :doc:`MemorySanitizer`,
1126 a detector of uninitialized reads. Requires instrumentation of all
1128 - .. _opt_fsanitize_undefined:
1130 ``-fsanitize=undefined``: :doc:`UndefinedBehaviorSanitizer`,
1131 a fast and compatible undefined behavior checker.
1133 - ``-fsanitize=dataflow``: :doc:`DataFlowSanitizer`, a general data
1135 - ``-fsanitize=cfi``: :doc:`control flow integrity <ControlFlowIntegrity>`
1136 checks. Requires ``-flto``.
1137 - ``-fsanitize=safe-stack``: :doc:`safe stack <SafeStack>`
1138 protection against stack-based memory corruption errors.
1140 There are more fine-grained checks available: see
1141 the :ref:`list <ubsan-checks>` of specific kinds of
1142 undefined behavior that can be detected and the :ref:`list <cfi-schemes>`
1143 of control flow integrity schemes.
1145 The ``-fsanitize=`` argument must also be provided when linking, in
1146 order to link to the appropriate runtime library.
1148 It is not possible to combine more than one of the ``-fsanitize=address``,
1149 ``-fsanitize=thread``, and ``-fsanitize=memory`` checkers in the same
1152 **-f[no-]sanitize-recover=check1,check2,...**
1154 **-f[no-]sanitize-recover=all**
1156 Controls which checks enabled by ``-fsanitize=`` flag are non-fatal.
1157 If the check is fatal, program will halt after the first error
1158 of this kind is detected and error report is printed.
1160 By default, non-fatal checks are those enabled by
1161 :doc:`UndefinedBehaviorSanitizer`,
1162 except for ``-fsanitize=return`` and ``-fsanitize=unreachable``. Some
1163 sanitizers may not support recovery (or not support it by default
1164 e.g. :doc:`AddressSanitizer`), and always crash the program after the issue
1167 Note that the ``-fsanitize-trap`` flag has precedence over this flag.
1168 This means that if a check has been configured to trap elsewhere on the
1169 command line, or if the check traps by default, this flag will not have
1170 any effect unless that sanitizer's trapping behavior is disabled with
1171 ``-fno-sanitize-trap``.
1173 For example, if a command line contains the flags ``-fsanitize=undefined
1174 -fsanitize-trap=undefined``, the flag ``-fsanitize-recover=alignment``
1175 will have no effect on its own; it will need to be accompanied by
1176 ``-fno-sanitize-trap=alignment``.
1178 **-f[no-]sanitize-trap=check1,check2,...**
1180 Controls which checks enabled by the ``-fsanitize=`` flag trap. This
1181 option is intended for use in cases where the sanitizer runtime cannot
1182 be used (for instance, when building libc or a kernel module), or where
1183 the binary size increase caused by the sanitizer runtime is a concern.
1185 This flag is only compatible with :doc:`control flow integrity
1186 <ControlFlowIntegrity>` schemes and :doc:`UndefinedBehaviorSanitizer`
1187 checks other than ``vptr``. If this flag
1188 is supplied together with ``-fsanitize=undefined``, the ``vptr`` sanitizer
1189 will be implicitly disabled.
1191 This flag is enabled by default for sanitizers in the ``cfi`` group.
1193 .. option:: -fsanitize-blacklist=/path/to/blacklist/file
1195 Disable or modify sanitizer checks for objects (source files, functions,
1196 variables, types) listed in the file. See
1197 :doc:`SanitizerSpecialCaseList` for file format description.
1199 .. option:: -fno-sanitize-blacklist
1201 Don't use blacklist file, if it was specified earlier in the command line.
1203 **-f[no-]sanitize-coverage=[type,features,...]**
1205 Enable simple code coverage in addition to certain sanitizers.
1206 See :doc:`SanitizerCoverage` for more details.
1208 **-f[no-]sanitize-stats**
1210 Enable simple statistics gathering for the enabled sanitizers.
1211 See :doc:`SanitizerStats` for more details.
1213 .. option:: -fsanitize-undefined-trap-on-error
1215 Deprecated alias for ``-fsanitize-trap=undefined``.
1217 .. option:: -fsanitize-cfi-cross-dso
1219 Enable cross-DSO control flow integrity checks. This flag modifies
1220 the behavior of sanitizers in the ``cfi`` group to allow checking
1221 of cross-DSO virtual and indirect calls.
1223 .. option:: -fsanitize-cfi-icall-generalize-pointers
1225 Generalize pointers in return and argument types in function type signatures
1226 checked by Control Flow Integrity indirect call checking. See
1227 :doc:`ControlFlowIntegrity` for more details.
1229 .. option:: -fstrict-vtable-pointers
1231 Enable optimizations based on the strict rules for overwriting polymorphic
1232 C++ objects, i.e. the vptr is invariant during an object's lifetime.
1233 This enables better devirtualization. Turned off by default, because it is
1236 .. option:: -ffast-math
1238 Enable fast-math mode. This defines the ``__FAST_MATH__`` preprocessor
1239 macro, and lets the compiler make aggressive, potentially-lossy assumptions
1240 about floating-point math. These include:
1242 * Floating-point math obeys regular algebraic rules for real numbers (e.g.
1243 ``+`` and ``*`` are associative, ``x/y == x * (1/y)``, and
1244 ``(a + b) * c == a * c + b * c``),
1245 * operands to floating-point operations are not equal to ``NaN`` and
1247 * ``+0`` and ``-0`` are interchangeable.
1249 .. option:: -fdenormal-fp-math=[values]
1251 Select which denormal numbers the code is permitted to require.
1253 Valid values are: ``ieee``, ``preserve-sign``, and ``positive-zero``,
1254 which correspond to IEEE 754 denormal numbers, the sign of a
1255 flushed-to-zero number is preserved in the sign of 0, denormals are
1256 flushed to positive zero, respectively.
1258 .. option:: -f[no-]strict-float-cast-overflow
1260 When a floating-point value is not representable in a destination integer
1261 type, the code has undefined behavior according to the language standard.
1262 By default, Clang will not guarantee any particular result in that case.
1263 With the 'no-strict' option, Clang attempts to match the overflowing behavior
1264 of the target's native float-to-int conversion instructions.
1266 .. option:: -fwhole-program-vtables
1268 Enable whole-program vtable optimizations, such as single-implementation
1269 devirtualization and virtual constant propagation, for classes with
1270 :doc:`hidden LTO visibility <LTOVisibility>`. Requires ``-flto``.
1272 .. option:: -fforce-emit-vtables
1274 In order to improve devirtualization, forces emitting of vtables even in
1275 modules where it isn't necessary. It causes more inline virtual functions
1278 .. option:: -fno-assume-sane-operator-new
1280 Don't assume that the C++'s new operator is sane.
1282 This option tells the compiler to do not assume that C++'s global
1283 new operator will always return a pointer that does not alias any
1284 other pointer when the function returns.
1286 .. option:: -ftrap-function=[name]
1288 Instruct code generator to emit a function call to the specified
1289 function name for ``__builtin_trap()``.
1291 LLVM code generator translates ``__builtin_trap()`` to a trap
1292 instruction if it is supported by the target ISA. Otherwise, the
1293 builtin is translated into a call to ``abort``. If this option is
1294 set, then the code generator will always lower the builtin to a call
1295 to the specified function regardless of whether the target ISA has a
1296 trap instruction. This option is useful for environments (e.g.
1297 deeply embedded) where a trap cannot be properly handled, or when
1298 some custom behavior is desired.
1300 .. option:: -ftls-model=[model]
1302 Select which TLS model to use.
1304 Valid values are: ``global-dynamic``, ``local-dynamic``,
1305 ``initial-exec`` and ``local-exec``. The default value is
1306 ``global-dynamic``. The compiler may use a different model if the
1307 selected model is not supported by the target, or if a more
1308 efficient model can be used. The TLS model can be overridden per
1309 variable using the ``tls_model`` attribute.
1311 .. option:: -femulated-tls
1313 Select emulated TLS model, which overrides all -ftls-model choices.
1315 In emulated TLS mode, all access to TLS variables are converted to
1316 calls to __emutls_get_address in the runtime library.
1318 .. option:: -mhwdiv=[values]
1320 Select the ARM modes (arm or thumb) that support hardware division
1323 Valid values are: ``arm``, ``thumb`` and ``arm,thumb``.
1324 This option is used to indicate which mode (arm or thumb) supports
1325 hardware division instructions. This only applies to the ARM
1328 .. option:: -m[no-]crc
1330 Enable or disable CRC instructions.
1332 This option is used to indicate whether CRC instructions are to
1333 be generated. This only applies to the ARM architecture.
1335 CRC instructions are enabled by default on ARMv8.
1337 .. option:: -mgeneral-regs-only
1339 Generate code which only uses the general purpose registers.
1341 This option restricts the generated code to use general registers
1342 only. This only applies to the AArch64 architecture.
1344 .. option:: -mcompact-branches=[values]
1346 Control the usage of compact branches for MIPSR6.
1348 Valid values are: ``never``, ``optimal`` and ``always``.
1349 The default value is ``optimal`` which generates compact branches
1350 when a delay slot cannot be filled. ``never`` disables the usage of
1351 compact branches and ``always`` generates compact branches whenever
1354 **-f[no-]max-type-align=[number]**
1355 Instruct the code generator to not enforce a higher alignment than the given
1356 number (of bytes) when accessing memory via an opaque pointer or reference.
1357 This cap is ignored when directly accessing a variable or when the pointee
1358 type has an explicit “aligned” attribute.
1360 The value should usually be determined by the properties of the system allocator.
1361 Some builtin types, especially vector types, have very high natural alignments;
1362 when working with values of those types, Clang usually wants to use instructions
1363 that take advantage of that alignment. However, many system allocators do
1364 not promise to return memory that is more than 8-byte or 16-byte-aligned. Use
1365 this option to limit the alignment that the compiler can assume for an arbitrary
1366 pointer, which may point onto the heap.
1368 This option does not affect the ABI alignment of types; the layout of structs and
1369 unions and the value returned by the alignof operator remain the same.
1371 This option can be overridden on a case-by-case basis by putting an explicit
1372 “aligned” alignment on a struct, union, or typedef. For example:
1374 .. code-block:: console
1376 #include <immintrin.h>
1377 // Make an aligned typedef of the AVX-512 16-int vector type.
1378 typedef __v16si __aligned_v16si __attribute__((aligned(64)));
1380 void initialize_vector(__aligned_v16si *v) {
1381 // The compiler may assume that ‘v’ is 64-byte aligned, regardless of the
1382 // value of -fmax-type-align.
1385 .. option:: -faddrsig, -fno-addrsig
1387 Controls whether Clang emits an address-significance table into the object
1388 file. Address-significance tables allow linkers to implement `safe ICF
1389 <https://research.google.com/pubs/archive/36912.pdf>`_ without the false
1390 positives that can result from other implementation techniques such as
1391 relocation scanning. Address-significance tables are enabled by default
1392 on ELF targets when using the integrated assembler. This flag currently
1393 only has an effect on ELF targets.
1395 Profile Guided Optimization
1396 ---------------------------
1398 Profile information enables better optimization. For example, knowing that a
1399 branch is taken very frequently helps the compiler make better decisions when
1400 ordering basic blocks. Knowing that a function ``foo`` is called more
1401 frequently than another function ``bar`` helps the inliner. Optimization
1402 levels ``-O2`` and above are recommended for use of profile guided optimization.
1404 Clang supports profile guided optimization with two different kinds of
1405 profiling. A sampling profiler can generate a profile with very low runtime
1406 overhead, or you can build an instrumented version of the code that collects
1407 more detailed profile information. Both kinds of profiles can provide execution
1408 counts for instructions in the code and information on branches taken and
1409 function invocation.
1411 Regardless of which kind of profiling you use, be careful to collect profiles
1412 by running your code with inputs that are representative of the typical
1413 behavior. Code that is not exercised in the profile will be optimized as if it
1414 is unimportant, and the compiler may make poor optimization choices for code
1415 that is disproportionately used while profiling.
1417 Differences Between Sampling and Instrumentation
1418 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1420 Although both techniques are used for similar purposes, there are important
1421 differences between the two:
1423 1. Profile data generated with one cannot be used by the other, and there is no
1424 conversion tool that can convert one to the other. So, a profile generated
1425 via ``-fprofile-instr-generate`` must be used with ``-fprofile-instr-use``.
1426 Similarly, sampling profiles generated by external profilers must be
1427 converted and used with ``-fprofile-sample-use``.
1429 2. Instrumentation profile data can be used for code coverage analysis and
1432 3. Sampling profiles can only be used for optimization. They cannot be used for
1433 code coverage analysis. Although it would be technically possible to use
1434 sampling profiles for code coverage, sample-based profiles are too
1435 coarse-grained for code coverage purposes; it would yield poor results.
1437 4. Sampling profiles must be generated by an external tool. The profile
1438 generated by that tool must then be converted into a format that can be read
1439 by LLVM. The section on sampling profilers describes one of the supported
1440 sampling profile formats.
1443 Using Sampling Profilers
1444 ^^^^^^^^^^^^^^^^^^^^^^^^
1446 Sampling profilers are used to collect runtime information, such as
1447 hardware counters, while your application executes. They are typically
1448 very efficient and do not incur a large runtime overhead. The
1449 sample data collected by the profiler can be used during compilation
1450 to determine what the most executed areas of the code are.
1452 Using the data from a sample profiler requires some changes in the way
1453 a program is built. Before the compiler can use profiling information,
1454 the code needs to execute under the profiler. The following is the
1455 usual build cycle when using sample profilers for optimization:
1457 1. Build the code with source line table information. You can use all the
1458 usual build flags that you always build your application with. The only
1459 requirement is that you add ``-gline-tables-only`` or ``-g`` to the
1460 command line. This is important for the profiler to be able to map
1461 instructions back to source line locations.
1463 .. code-block:: console
1465 $ clang++ -O2 -gline-tables-only code.cc -o code
1467 2. Run the executable under a sampling profiler. The specific profiler
1468 you use does not really matter, as long as its output can be converted
1469 into the format that the LLVM optimizer understands. Currently, there
1470 exists a conversion tool for the Linux Perf profiler
1471 (https://perf.wiki.kernel.org/), so these examples assume that you
1472 are using Linux Perf to profile your code.
1474 .. code-block:: console
1476 $ perf record -b ./code
1478 Note the use of the ``-b`` flag. This tells Perf to use the Last Branch
1479 Record (LBR) to record call chains. While this is not strictly required,
1480 it provides better call information, which improves the accuracy of
1483 3. Convert the collected profile data to LLVM's sample profile format.
1484 This is currently supported via the AutoFDO converter ``create_llvm_prof``.
1485 It is available at http://github.com/google/autofdo. Once built and
1486 installed, you can convert the ``perf.data`` file to LLVM using
1489 .. code-block:: console
1491 $ create_llvm_prof --binary=./code --out=code.prof
1493 This will read ``perf.data`` and the binary file ``./code`` and emit
1494 the profile data in ``code.prof``. Note that if you ran ``perf``
1495 without the ``-b`` flag, you need to use ``--use_lbr=false`` when
1496 calling ``create_llvm_prof``.
1498 4. Build the code again using the collected profile. This step feeds
1499 the profile back to the optimizers. This should result in a binary
1500 that executes faster than the original one. Note that you are not
1501 required to build the code with the exact same arguments that you
1502 used in the first step. The only requirement is that you build the code
1503 with ``-gline-tables-only`` and ``-fprofile-sample-use``.
1505 .. code-block:: console
1507 $ clang++ -O2 -gline-tables-only -fprofile-sample-use=code.prof code.cc -o code
1510 Sample Profile Formats
1511 """"""""""""""""""""""
1513 Since external profilers generate profile data in a variety of custom formats,
1514 the data generated by the profiler must be converted into a format that can be
1515 read by the backend. LLVM supports three different sample profile formats:
1517 1. ASCII text. This is the easiest one to generate. The file is divided into
1518 sections, which correspond to each of the functions with profile
1519 information. The format is described below. It can also be generated from
1520 the binary or gcov formats using the ``llvm-profdata`` tool.
1522 2. Binary encoding. This uses a more efficient encoding that yields smaller
1523 profile files. This is the format generated by the ``create_llvm_prof`` tool
1524 in http://github.com/google/autofdo.
1526 3. GCC encoding. This is based on the gcov format, which is accepted by GCC. It
1527 is only interesting in environments where GCC and Clang co-exist. This
1528 encoding is only generated by the ``create_gcov`` tool in
1529 http://github.com/google/autofdo. It can be read by LLVM and
1530 ``llvm-profdata``, but it cannot be generated by either.
1532 If you are using Linux Perf to generate sampling profiles, you can use the
1533 conversion tool ``create_llvm_prof`` described in the previous section.
1534 Otherwise, you will need to write a conversion tool that converts your
1535 profiler's native format into one of these three.
1538 Sample Profile Text Format
1539 """"""""""""""""""""""""""
1541 This section describes the ASCII text format for sampling profiles. It is,
1542 arguably, the easiest one to generate. If you are interested in generating any
1543 of the other two, consult the ``ProfileData`` library in LLVM's source tree
1544 (specifically, ``include/llvm/ProfileData/SampleProfReader.h``).
1546 .. code-block:: console
1548 function1:total_samples:total_head_samples
1549 offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ]
1550 offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ]
1552 offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]
1553 offsetA[.discriminator]: fnA:num_of_total_samples
1554 offsetA1[.discriminator]: number_of_samples [fn7:num fn8:num ... ]
1555 offsetA1[.discriminator]: number_of_samples [fn9:num fn10:num ... ]
1556 offsetB[.discriminator]: fnB:num_of_total_samples
1557 offsetB1[.discriminator]: number_of_samples [fn11:num fn12:num ... ]
1559 This is a nested tree in which the indentation represents the nesting level
1560 of the inline stack. There are no blank lines in the file. And the spacing
1561 within a single line is fixed. Additional spaces will result in an error
1562 while reading the file.
1564 Any line starting with the '#' character is completely ignored.
1566 Inlined calls are represented with indentation. The Inline stack is a
1567 stack of source locations in which the top of the stack represents the
1568 leaf function, and the bottom of the stack represents the actual
1569 symbol to which the instruction belongs.
1571 Function names must be mangled in order for the profile loader to
1572 match them in the current translation unit. The two numbers in the
1573 function header specify how many total samples were accumulated in the
1574 function (first number), and the total number of samples accumulated
1575 in the prologue of the function (second number). This head sample
1576 count provides an indicator of how frequently the function is invoked.
1578 There are two types of lines in the function body.
1580 - Sampled line represents the profile information of a source location.
1581 ``offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]``
1583 - Callsite line represents the profile information of an inlined callsite.
1584 ``offsetA[.discriminator]: fnA:num_of_total_samples``
1586 Each sampled line may contain several items. Some are optional (marked
1589 a. Source line offset. This number represents the line number
1590 in the function where the sample was collected. The line number is
1591 always relative to the line where symbol of the function is
1592 defined. So, if the function has its header at line 280, the offset
1593 13 is at line 293 in the file.
1595 Note that this offset should never be a negative number. This could
1596 happen in cases like macros. The debug machinery will register the
1597 line number at the point of macro expansion. So, if the macro was
1598 expanded in a line before the start of the function, the profile
1599 converter should emit a 0 as the offset (this means that the optimizers
1600 will not be able to associate a meaningful weight to the instructions
1603 b. [OPTIONAL] Discriminator. This is used if the sampled program
1604 was compiled with DWARF discriminator support
1605 (http://wiki.dwarfstd.org/index.php?title=Path_Discriminators).
1606 DWARF discriminators are unsigned integer values that allow the
1607 compiler to distinguish between multiple execution paths on the
1608 same source line location.
1610 For example, consider the line of code ``if (cond) foo(); else bar();``.
1611 If the predicate ``cond`` is true 80% of the time, then the edge
1612 into function ``foo`` should be considered to be taken most of the
1613 time. But both calls to ``foo`` and ``bar`` are at the same source
1614 line, so a sample count at that line is not sufficient. The
1615 compiler needs to know which part of that line is taken more
1618 This is what discriminators provide. In this case, the calls to
1619 ``foo`` and ``bar`` will be at the same line, but will have
1620 different discriminator values. This allows the compiler to correctly
1621 set edge weights into ``foo`` and ``bar``.
1623 c. Number of samples. This is an integer quantity representing the
1624 number of samples collected by the profiler at this source
1627 d. [OPTIONAL] Potential call targets and samples. If present, this
1628 line contains a call instruction. This models both direct and
1629 number of samples. For example,
1631 .. code-block:: console
1633 130: 7 foo:3 bar:2 baz:7
1635 The above means that at relative line offset 130 there is a call
1636 instruction that calls one of ``foo()``, ``bar()`` and ``baz()``,
1637 with ``baz()`` being the relatively more frequently called target.
1639 As an example, consider a program with the call chain ``main -> foo -> bar``.
1640 When built with optimizations enabled, the compiler may inline the
1641 calls to ``bar`` and ``foo`` inside ``main``. The generated profile
1642 could then be something like this:
1644 .. code-block:: console
1652 This profile indicates that there were a total of 35,504 samples
1653 collected in main. All of those were at line 1 (the call to ``foo``).
1654 Of those, 31,977 were spent inside the body of ``bar``. The last line
1655 of the profile (``2: 0``) corresponds to line 2 inside ``main``. No
1656 samples were collected there.
1658 Profiling with Instrumentation
1659 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1661 Clang also supports profiling via instrumentation. This requires building a
1662 special instrumented version of the code and has some runtime
1663 overhead during the profiling, but it provides more detailed results than a
1664 sampling profiler. It also provides reproducible results, at least to the
1665 extent that the code behaves consistently across runs.
1667 Here are the steps for using profile guided optimization with
1670 1. Build an instrumented version of the code by compiling and linking with the
1671 ``-fprofile-instr-generate`` option.
1673 .. code-block:: console
1675 $ clang++ -O2 -fprofile-instr-generate code.cc -o code
1677 2. Run the instrumented executable with inputs that reflect the typical usage.
1678 By default, the profile data will be written to a ``default.profraw`` file
1679 in the current directory. You can override that default by using option
1680 ``-fprofile-instr-generate=`` or by setting the ``LLVM_PROFILE_FILE``
1681 environment variable to specify an alternate file. If non-default file name
1682 is specified by both the environment variable and the command line option,
1683 the environment variable takes precedence. The file name pattern specified
1684 can include different modifiers: ``%p``, ``%h``, and ``%m``.
1686 Any instance of ``%p`` in that file name will be replaced by the process
1687 ID, so that you can easily distinguish the profile output from multiple
1690 .. code-block:: console
1692 $ LLVM_PROFILE_FILE="code-%p.profraw" ./code
1694 The modifier ``%h`` can be used in scenarios where the same instrumented
1695 binary is run in multiple different host machines dumping profile data
1696 to a shared network based storage. The ``%h`` specifier will be substituted
1697 with the hostname so that profiles collected from different hosts do not
1700 While the use of ``%p`` specifier can reduce the likelihood for the profiles
1701 dumped from different processes to clobber each other, such clobbering can still
1702 happen because of the ``pid`` re-use by the OS. Another side-effect of using
1703 ``%p`` is that the storage requirement for raw profile data files is greatly
1704 increased. To avoid issues like this, the ``%m`` specifier can used in the profile
1705 name. When this specifier is used, the profiler runtime will substitute ``%m``
1706 with a unique integer identifier associated with the instrumented binary. Additionally,
1707 multiple raw profiles dumped from different processes that share a file system (can be
1708 on different hosts) will be automatically merged by the profiler runtime during the
1709 dumping. If the program links in multiple instrumented shared libraries, each library
1710 will dump the profile data into its own profile data file (with its unique integer
1711 id embedded in the profile name). Note that the merging enabled by ``%m`` is for raw
1712 profile data generated by profiler runtime. The resulting merged "raw" profile data
1713 file still needs to be converted to a different format expected by the compiler (
1716 .. code-block:: console
1718 $ LLVM_PROFILE_FILE="code-%m.profraw" ./code
1721 3. Combine profiles from multiple runs and convert the "raw" profile format to
1722 the input expected by clang. Use the ``merge`` command of the
1723 ``llvm-profdata`` tool to do this.
1725 .. code-block:: console
1727 $ llvm-profdata merge -output=code.profdata code-*.profraw
1729 Note that this step is necessary even when there is only one "raw" profile,
1730 since the merge operation also changes the file format.
1732 4. Build the code again using the ``-fprofile-instr-use`` option to specify the
1733 collected profile data.
1735 .. code-block:: console
1737 $ clang++ -O2 -fprofile-instr-use=code.profdata code.cc -o code
1739 You can repeat step 4 as often as you like without regenerating the
1740 profile. As you make changes to your code, clang may no longer be able to
1741 use the profile data. It will warn you when this happens.
1743 Profile generation using an alternative instrumentation method can be
1744 controlled by the GCC-compatible flags ``-fprofile-generate`` and
1745 ``-fprofile-use``. Although these flags are semantically equivalent to
1746 their GCC counterparts, they *do not* handle GCC-compatible profiles.
1747 They are only meant to implement GCC's semantics with respect to
1748 profile creation and use.
1750 .. option:: -fprofile-generate[=<dirname>]
1752 The ``-fprofile-generate`` and ``-fprofile-generate=`` flags will use
1753 an alternative instrumentation method for profile generation. When
1754 given a directory name, it generates the profile file
1755 ``default_%m.profraw`` in the directory named ``dirname`` if specified.
1756 If ``dirname`` does not exist, it will be created at runtime. ``%m`` specifier
1757 will be substituted with a unique id documented in step 2 above. In other words,
1758 with ``-fprofile-generate[=<dirname>]`` option, the "raw" profile data automatic
1759 merging is turned on by default, so there will no longer any risk of profile
1760 clobbering from different running processes. For example,
1762 .. code-block:: console
1764 $ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code
1766 When ``code`` is executed, the profile will be written to the file
1767 ``yyy/zzz/default_xxxx.profraw``.
1769 To generate the profile data file with the compiler readable format, the
1770 ``llvm-profdata`` tool can be used with the profile directory as the input:
1772 .. code-block:: console
1774 $ llvm-profdata merge -output=code.profdata yyy/zzz/
1776 If the user wants to turn off the auto-merging feature, or simply override the
1777 the profile dumping path specified at command line, the environment variable
1778 ``LLVM_PROFILE_FILE`` can still be used to override
1779 the directory and filename for the profile file at runtime.
1781 .. option:: -fprofile-use[=<pathname>]
1783 Without any other arguments, ``-fprofile-use`` behaves identically to
1784 ``-fprofile-instr-use``. Otherwise, if ``pathname`` is the full path to a
1785 profile file, it reads from that file. If ``pathname`` is a directory name,
1786 it reads from ``pathname/default.profdata``.
1788 Disabling Instrumentation
1789 ^^^^^^^^^^^^^^^^^^^^^^^^^
1791 In certain situations, it may be useful to disable profile generation or use
1792 for specific files in a build, without affecting the main compilation flags
1793 used for the other files in the project.
1795 In these cases, you can use the flag ``-fno-profile-instr-generate`` (or
1796 ``-fno-profile-generate``) to disable profile generation, and
1797 ``-fno-profile-instr-use`` (or ``-fno-profile-use``) to disable profile use.
1799 Note that these flags should appear after the corresponding profile
1800 flags to have an effect.
1802 Controlling Debug Information
1803 -----------------------------
1805 Controlling Size of Debug Information
1806 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1808 Debug info kind generated by Clang can be set by one of the flags listed
1809 below. If multiple flags are present, the last one is used.
1813 Don't generate any debug info (default).
1815 .. option:: -gline-tables-only
1817 Generate line number tables only.
1819 This kind of debug info allows to obtain stack traces with function names,
1820 file names and line numbers (by such tools as ``gdb`` or ``addr2line``). It
1821 doesn't contain any other data (e.g. description of local variables or
1822 function parameters).
1824 .. option:: -fstandalone-debug
1826 Clang supports a number of optimizations to reduce the size of debug
1827 information in the binary. They work based on the assumption that
1828 the debug type information can be spread out over multiple
1829 compilation units. For instance, Clang will not emit type
1830 definitions for types that are not needed by a module and could be
1831 replaced with a forward declaration. Further, Clang will only emit
1832 type info for a dynamic C++ class in the module that contains the
1833 vtable for the class.
1835 The **-fstandalone-debug** option turns off these optimizations.
1836 This is useful when working with 3rd-party libraries that don't come
1837 with debug information. Note that Clang will never emit type
1838 information for types that are not referenced at all by the program.
1840 .. option:: -fno-standalone-debug
1842 On Darwin **-fstandalone-debug** is enabled by default. The
1843 **-fno-standalone-debug** option can be used to get to turn on the
1844 vtable-based optimization described above.
1848 Generate complete debug info.
1850 Controlling Macro Debug Info Generation
1851 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1853 Debug info for C preprocessor macros increases the size of debug information in
1854 the binary. Macro debug info generated by Clang can be controlled by the flags
1857 .. option:: -fdebug-macro
1859 Generate debug info for preprocessor macros. This flag is discarded when
1862 .. option:: -fno-debug-macro
1864 Do not generate debug info for preprocessor macros (default).
1866 Controlling Debugger "Tuning"
1867 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1869 While Clang generally emits standard DWARF debug info (http://dwarfstd.org),
1870 different debuggers may know how to take advantage of different specific DWARF
1871 features. You can "tune" the debug info for one of several different debuggers.
1873 .. option:: -ggdb, -glldb, -gsce
1875 Tune the debug info for the ``gdb``, ``lldb``, or Sony PlayStation\ |reg|
1876 debugger, respectively. Each of these options implies **-g**. (Therefore, if
1877 you want both **-gline-tables-only** and debugger tuning, the tuning option
1881 Controlling LLVM IR Output
1882 --------------------------
1884 Controlling Value Names in LLVM IR
1885 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1887 Emitting value names in LLVM IR increases the size and verbosity of the IR.
1888 By default, value names are only emitted in assertion-enabled builds of Clang.
1889 However, when reading IR it can be useful to re-enable the emission of value
1890 names to improve readability.
1892 .. option:: -fdiscard-value-names
1894 Discard value names when generating LLVM IR.
1896 .. option:: -fno-discard-value-names
1898 Do not discard value names when generating LLVM IR. This option can be used
1899 to re-enable names for release builds of Clang.
1902 Comment Parsing Options
1903 -----------------------
1905 Clang parses Doxygen and non-Doxygen style documentation comments and attaches
1906 them to the appropriate declaration nodes. By default, it only parses
1907 Doxygen-style comments and ignores ordinary comments starting with ``//`` and
1910 .. option:: -Wdocumentation
1912 Emit warnings about use of documentation comments. This warning group is off
1915 This includes checking that ``\param`` commands name parameters that actually
1916 present in the function signature, checking that ``\returns`` is used only on
1917 functions that actually return a value etc.
1919 .. option:: -Wno-documentation-unknown-command
1921 Don't warn when encountering an unknown Doxygen command.
1923 .. option:: -fparse-all-comments
1925 Parse all comments as documentation comments (including ordinary comments
1926 starting with ``//`` and ``/*``).
1928 .. option:: -fcomment-block-commands=[commands]
1930 Define custom documentation commands as block commands. This allows Clang to
1931 construct the correct AST for these custom commands, and silences warnings
1932 about unknown commands. Several commands must be separated by a comma
1933 *without trailing space*; e.g. ``-fcomment-block-commands=foo,bar`` defines
1934 custom commands ``\foo`` and ``\bar``.
1936 It is also possible to use ``-fcomment-block-commands`` several times; e.g.
1937 ``-fcomment-block-commands=foo -fcomment-block-commands=bar`` does the same
1945 The support for standard C in clang is feature-complete except for the
1946 C99 floating-point pragmas.
1948 Extensions supported by clang
1949 -----------------------------
1951 See :doc:`LanguageExtensions`.
1953 Differences between various standard modes
1954 ------------------------------------------
1956 clang supports the -std option, which changes what language mode clang
1957 uses. The supported modes for C are c89, gnu89, c99, gnu99, c11, gnu11,
1958 c17, gnu17, and various aliases for those modes. If no -std option is
1959 specified, clang defaults to gnu11 mode. Many C99 and C11 features are
1960 supported in earlier modes as a conforming extension, with a warning. Use
1961 ``-pedantic-errors`` to request an error if a feature from a later standard
1962 revision is used in an earlier mode.
1964 Differences between all ``c*`` and ``gnu*`` modes:
1966 - ``c*`` modes define "``__STRICT_ANSI__``".
1967 - Target-specific defines not prefixed by underscores, like "linux",
1968 are defined in ``gnu*`` modes.
1969 - Trigraphs default to being off in ``gnu*`` modes; they can be enabled by
1970 the -trigraphs option.
1971 - The parser recognizes "asm" and "typeof" as keywords in ``gnu*`` modes;
1972 the variants "``__asm__``" and "``__typeof__``" are recognized in all
1974 - The Apple "blocks" extension is recognized by default in ``gnu*`` modes
1975 on some platforms; it can be enabled in any mode with the "-fblocks"
1977 - Arrays that are VLA's according to the standard, but which can be
1978 constant folded by the frontend are treated as fixed size arrays.
1979 This occurs for things like "int X[(1, 2)];", which is technically a
1980 VLA. ``c*`` modes are strictly compliant and treat these as VLAs.
1982 Differences between ``*89`` and ``*99`` modes:
1984 - The ``*99`` modes default to implementing "inline" as specified in C99,
1985 while the ``*89`` modes implement the GNU version. This can be
1986 overridden for individual functions with the ``__gnu_inline__``
1988 - Digraphs are not recognized in c89 mode.
1989 - The scope of names defined inside a "for", "if", "switch", "while",
1990 or "do" statement is different. (example: "``if ((struct x {int
1992 - ``__STDC_VERSION__`` is not defined in ``*89`` modes.
1993 - "inline" is not recognized as a keyword in c89 mode.
1994 - "restrict" is not recognized as a keyword in ``*89`` modes.
1995 - Commas are allowed in integer constant expressions in ``*99`` modes.
1996 - Arrays which are not lvalues are not implicitly promoted to pointers
1998 - Some warnings are different.
2000 Differences between ``*99`` and ``*11`` modes:
2002 - Warnings for use of C11 features are disabled.
2003 - ``__STDC_VERSION__`` is defined to ``201112L`` rather than ``199901L``.
2005 Differences between ``*11`` and ``*17`` modes:
2007 - ``__STDC_VERSION__`` is defined to ``201710L`` rather than ``201112L``.
2009 GCC extensions not implemented yet
2010 ----------------------------------
2012 clang tries to be compatible with gcc as much as possible, but some gcc
2013 extensions are not implemented yet:
2015 - clang does not support decimal floating point types (``_Decimal32`` and
2016 friends) or fixed-point types (``_Fract`` and friends); nobody has
2017 expressed interest in these features yet, so it's hard to say when
2018 they will be implemented.
2019 - clang does not support nested functions; this is a complex feature
2020 which is infrequently used, so it is unlikely to be implemented
2021 anytime soon. In C++11 it can be emulated by assigning lambda
2022 functions to local variables, e.g:
2026 auto const local_function = [&](int parameter) {
2032 - clang only supports global register variables when the register specified
2033 is non-allocatable (e.g. the stack pointer). Support for general global
2034 register variables is unlikely to be implemented soon because it requires
2035 additional LLVM backend support.
2036 - clang does not support static initialization of flexible array
2037 members. This appears to be a rarely used extension, but could be
2038 implemented pending user demand.
2039 - clang does not support
2040 ``__builtin_va_arg_pack``/``__builtin_va_arg_pack_len``. This is
2041 used rarely, but in some potentially interesting places, like the
2042 glibc headers, so it may be implemented pending user demand. Note
2043 that because clang pretends to be like GCC 4.2, and this extension
2044 was introduced in 4.3, the glibc headers will not try to use this
2045 extension with clang at the moment.
2046 - clang does not support the gcc extension for forward-declaring
2047 function parameters; this has not shown up in any real-world code
2048 yet, though, so it might never be implemented.
2050 This is not a complete list; if you find an unsupported extension
2051 missing from this list, please send an e-mail to cfe-dev. This list
2052 currently excludes C++; see :ref:`C++ Language Features <cxx>`. Also, this
2053 list does not include bugs in mostly-implemented features; please see
2055 tracker <https://bugs.llvm.org/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer>`_
2056 for known existing bugs (FIXME: Is there a section for bug-reporting
2057 guidelines somewhere?).
2059 Intentionally unsupported GCC extensions
2060 ----------------------------------------
2062 - clang does not support the gcc extension that allows variable-length
2063 arrays in structures. This is for a few reasons: one, it is tricky to
2064 implement, two, the extension is completely undocumented, and three,
2065 the extension appears to be rarely used. Note that clang *does*
2066 support flexible array members (arrays with a zero or unspecified
2067 size at the end of a structure).
2068 - clang does not have an equivalent to gcc's "fold"; this means that
2069 clang doesn't accept some constructs gcc might accept in contexts
2070 where a constant expression is required, like "x-x" where x is a
2072 - clang does not support ``__builtin_apply`` and friends; this extension
2073 is extremely obscure and difficult to implement reliably.
2077 Microsoft extensions
2078 --------------------
2080 clang has support for many extensions from Microsoft Visual C++. To enable these
2081 extensions, use the ``-fms-extensions`` command-line option. This is the default
2082 for Windows targets. Clang does not implement every pragma or declspec provided
2083 by MSVC, but the popular ones, such as ``__declspec(dllexport)`` and ``#pragma
2084 comment(lib)`` are well supported.
2086 clang has a ``-fms-compatibility`` flag that makes clang accept enough
2087 invalid C++ to be able to parse most Microsoft headers. For example, it
2088 allows `unqualified lookup of dependent base class members
2089 <http://clang.llvm.org/compatibility.html#dep_lookup_bases>`_, which is
2090 a common compatibility issue with clang. This flag is enabled by default
2091 for Windows targets.
2093 ``-fdelayed-template-parsing`` lets clang delay parsing of function template
2094 definitions until the end of a translation unit. This flag is enabled by
2095 default for Windows targets.
2097 For compatibility with existing code that compiles with MSVC, clang defines the
2098 ``_MSC_VER`` and ``_MSC_FULL_VER`` macros. These default to the values of 1800
2099 and 180000000 respectively, making clang look like an early release of Visual
2100 C++ 2013. The ``-fms-compatibility-version=`` flag overrides these values. It
2101 accepts a dotted version tuple, such as 19.00.23506. Changing the MSVC
2102 compatibility version makes clang behave more like that version of MSVC. For
2103 example, ``-fms-compatibility-version=19`` will enable C++14 features and define
2104 ``char16_t`` and ``char32_t`` as builtin types.
2108 C++ Language Features
2109 =====================
2111 clang fully implements all of standard C++98 except for exported
2112 templates (which were removed in C++11), and all of standard C++11
2113 and the current draft standard for C++1y.
2115 Controlling implementation limits
2116 ---------------------------------
2118 .. option:: -fbracket-depth=N
2120 Sets the limit for nested parentheses, brackets, and braces to N. The
2123 .. option:: -fconstexpr-depth=N
2125 Sets the limit for recursive constexpr function invocations to N. The
2128 .. option:: -fconstexpr-steps=N
2130 Sets the limit for the number of full-expressions evaluated in a single
2131 constant expression evaluation. The default is 1048576.
2133 .. option:: -ftemplate-depth=N
2135 Sets the limit for recursively nested template instantiations to N. The
2138 .. option:: -foperator-arrow-depth=N
2140 Sets the limit for iterative calls to 'operator->' functions to N. The
2145 Objective-C Language Features
2146 =============================
2150 Objective-C++ Language Features
2151 ===============================
2158 Clang supports all OpenMP 3.1 directives and clauses. In addition, some
2159 features of OpenMP 4.0 are supported. For example, ``#pragma omp simd``,
2160 ``#pragma omp for simd``, ``#pragma omp parallel for simd`` directives, extended
2161 set of atomic constructs, ``proc_bind`` clause for all parallel-based
2162 directives, ``depend`` clause for ``#pragma omp task`` directive (except for
2163 array sections), ``#pragma omp cancel`` and ``#pragma omp cancellation point``
2164 directives, and ``#pragma omp taskgroup`` directive.
2166 Use `-fopenmp` to enable OpenMP. Support for OpenMP can be disabled with
2169 Use `-fopenmp-simd` to enable OpenMP simd features only, without linking
2170 the runtime library; for combined constructs
2171 (e.g. ``#pragma omp parallel for simd``) the non-simd directives and clauses
2172 will be ignored. This can be disabled with `-fno-openmp-simd`.
2174 Controlling implementation limits
2175 ---------------------------------
2177 .. option:: -fopenmp-use-tls
2179 Controls code generation for OpenMP threadprivate variables. In presence of
2180 this option all threadprivate variables are generated the same way as thread
2181 local variables, using TLS support. If `-fno-openmp-use-tls`
2182 is provided or target does not support TLS, code generation for threadprivate
2183 variables relies on OpenMP runtime library.
2190 Clang can be used to compile OpenCL kernels for execution on a device
2191 (e.g. GPU). It is possible to compile the kernel into a binary (e.g. for AMD or
2192 Nvidia targets) that can be uploaded to run directly on a device (e.g. using
2193 `clCreateProgramWithBinary
2194 <https://www.khronos.org/registry/OpenCL/specs/opencl-1.1.pdf#111>`_) or
2195 into generic bitcode files loadable into other toolchains.
2197 Compiling to a binary using the default target from the installation can be done
2200 .. code-block:: console
2202 $ echo "kernel void k(){}" > test.cl
2205 Compiling for a specific target can be done by specifying the triple corresponding
2206 to the target, for example:
2208 .. code-block:: console
2210 $ clang -target nvptx64-unknown-unknown test.cl
2211 $ clang -target amdgcn-amd-amdhsa -mcpu=gfx900 test.cl
2213 Compiling to bitcode can be done as follows:
2215 .. code-block:: console
2217 $ clang -c -emit-llvm test.cl
2219 This will produce a generic test.bc file that can be used in vendor toolchains
2220 to perform machine code generation.
2222 Clang currently supports OpenCL C language standards up to v2.0.
2224 OpenCL Specific Options
2225 -----------------------
2227 Most of the OpenCL build options from `the specification v2.0 section 5.8.4
2228 <https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf#200>`_ are available.
2232 .. code-block:: console
2234 $ clang -cl-std=CL2.0 -cl-single-precision-constant test.cl
2236 Some extra options are available to support special OpenCL features.
2238 .. option:: -finclude-default-header
2240 Loads standard includes during compilations. By default OpenCL headers are not
2241 loaded and therefore standard library includes are not available. To load them
2242 automatically a flag has been added to the frontend (see also :ref:`the section
2243 on the OpenCL Header <opencl_header>`):
2245 .. code-block:: console
2247 $ clang -Xclang -finclude-default-header test.cl
2249 Alternatively ``-include`` or ``-I`` followed by the path to the header location
2250 can be given manually.
2252 .. code-block:: console
2254 $ clang -I<path to clang>/lib/Headers/opencl-c.h test.cl
2256 In this case the kernel code should contain ``#include <opencl-c.h>`` just as a
2263 Disables support of OpenCL extensions. All OpenCL targets provide a list
2264 of extensions that they support. Clang allows to amend this using the ``-cl-ext``
2265 flag with a comma-separated list of extensions prefixed with ``'+'`` or ``'-'``.
2266 The syntax: ``-cl-ext=<(['-'|'+']<extension>[,])+>``, where extensions
2267 can be either one of `the OpenCL specification extensions
2268 <https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/EXTENSION.html>`_
2269 or any known vendor extension. Alternatively, ``'all'`` can be used to enable
2270 or disable all known extensions.
2271 Example disabling double support for the 64-bit SPIR target:
2273 .. code-block:: console
2275 $ clang -cc1 -triple spir64-unknown-unknown -cl-ext=-cl_khr_fp64 test.cl
2277 Enabling all extensions except double support in R600 AMD GPU can be done using:
2279 .. code-block:: console
2281 $ clang -cc1 -triple r600-unknown-unknown -cl-ext=-all,+cl_khr_fp16 test.cl
2283 .. _opencl_fake_address_space_map:
2285 .. option:: -ffake-address-space-map
2287 Overrides the target address space map with a fake map.
2288 This allows adding explicit address space IDs to the bitcode for non-segmented
2289 memory architectures that don't have separate IDs for each of the OpenCL
2290 logical address spaces by default. Passing ``-ffake-address-space-map`` will
2291 add/override address spaces of the target compiled for with the following values:
2292 ``1-global``, ``2-constant``, ``3-local``, ``4-generic``. The private address
2293 space is represented by the absence of an address space attribute in the IR (see
2294 also :ref:`the section on the address space attribute <opencl_addrsp>`).
2296 .. code-block:: console
2298 $ clang -ffake-address-space-map test.cl
2300 Some other flags used for the compilation for C can also be passed while
2301 compiling for OpenCL, examples: ``-c``, ``-O<1-4|s>``, ``-o``, ``-emit-llvm``, etc.
2306 OpenCL targets are derived from the regular Clang target classes. The OpenCL
2307 specific parts of the target representation provide address space mapping as
2308 well as a set of supported extensions.
2313 There is a set of concrete HW architectures that OpenCL can be compiled for.
2317 .. code-block:: console
2319 $ clang -target amdgcn-amd-amdhsa -mcpu=gfx900 test.cl
2321 - For Nvidia architectures:
2323 .. code-block:: console
2325 $ clang -target nvptx64-unknown-unknown test.cl
2331 - SPIR is available as a generic target to allow portable bitcode to be produced
2332 that can be used across GPU toolchains. The implementation follows `the SPIR
2333 specification <https://www.khronos.org/spir>`_. There are two flavors
2334 available for 32 and 64 bits.
2336 .. code-block:: console
2338 $ clang -target spir-unknown-unknown test.cl
2339 $ clang -target spir64-unknown-unknown test.cl
2341 All known OpenCL extensions are supported in the SPIR targets. Clang will
2342 generate SPIR v1.2 compatible IR for OpenCL versions up to 2.0 and SPIR v2.0
2345 - x86 is used by some implementations that are x86 compatible and currently
2346 remains for backwards compatibility (with older implementations prior to
2347 SPIR target support). For "non-SPMD" targets which cannot spawn multiple
2348 work-items on the fly using hardware, which covers practically all non-GPU
2349 devices such as CPUs and DSPs, additional processing is needed for the kernels
2350 to support multiple work-item execution. For this, a 3rd party toolchain,
2351 such as for example `POCL <http://portablecl.org/>`_, can be used.
2353 This target does not support multiple memory segments and, therefore, the fake
2354 address space map can be added using the :ref:`-ffake-address-space-map
2355 <opencl_fake_address_space_map>` flag.
2362 By default Clang will not include standard headers and therefore OpenCL builtin
2363 functions and some types (i.e. vectors) are unknown. The default CL header is,
2364 however, provided in the Clang installation and can be enabled by passing the
2365 ``-finclude-default-header`` flag to the Clang frontend.
2367 .. code-block:: console
2369 $ echo "bool is_wg_uniform(int i){return get_enqueued_local_size(i)==get_local_size(i);}" > test.cl
2370 $ clang -Xclang -finclude-default-header -cl-std=CL2.0 test.cl
2372 Because the header is very large and long to parse, PCH (:doc:`PCHInternals`)
2373 and modules (:doc:`Modules`) are used internally to improve the compilation
2376 To enable modules for OpenCL:
2378 .. code-block:: console
2380 $ clang -target spir-unknown-unknown -c -emit-llvm -Xclang -finclude-default-header -fmodules -fimplicit-module-maps -fmodules-cache-path=<path to the generated module> test.cl
2385 All of the ``cl_khr_*`` extensions from `the official OpenCL specification
2386 <https://www.khronos.org/registry/OpenCL/sdk/2.0/docs/man/xhtml/EXTENSION.html>`_
2387 up to and including version 2.0 are available and set per target depending on the
2388 support available in the specific architecture.
2390 It is possible to alter the default extensions setting per target using
2391 ``-cl-ext`` flag. (See :ref:`flags description <opencl_cl_ext>` for more details).
2393 Vendor extensions can be added flexibly by declaring the list of types and
2394 functions associated with each extensions enclosed within the following
2395 compiler pragma directives:
2399 #pragma OPENCL EXTENSION the_new_extension_name : begin
2400 // declare types and functions associated with the extension here
2401 #pragma OPENCL EXTENSION the_new_extension_name : end
2403 For example, parsing the following code adds ``my_t`` type and ``my_func``
2404 function to the custom ``my_ext`` extension.
2408 #pragma OPENCL EXTENSION my_ext : begin
2413 #pragma OPENCL EXTENSION my_ext : end
2415 Declaring the same types in different vendor extensions is disallowed.
2420 Clang uses metadata to provide additional OpenCL semantics in IR needed for
2421 backends and OpenCL runtime.
2423 Each kernel will have function metadata attached to it, specifying the arguments.
2424 Kernel argument metadata is used to provide source level information for querying
2425 at runtime, for example using the `clGetKernelArgInfo
2426 <https://www.khronos.org/registry/OpenCL/specs/opencl-1.2.pdf#167>`_
2429 Note that ``-cl-kernel-arg-info`` enables more information about the original CL
2430 code to be added e.g. kernel parameter names will appear in the OpenCL metadata
2431 along with other information.
2433 The IDs used to encode the OpenCL's logical address spaces in the argument info
2434 metadata follows the SPIR address space mapping as defined in the SPIR
2435 specification `section 2.2
2436 <https://www.khronos.org/registry/spir/specs/spir_spec-2.0.pdf#18>`_
2438 OpenCL-Specific Attributes
2439 --------------------------
2441 OpenCL support in Clang contains a set of attribute taken directly from the
2442 specification as well as additional attributes.
2444 See also :doc:`AttributeReference`.
2449 Clang supports this attribute to comply to OpenCL v2.0 conformance, but it
2450 does not have any effect on the IR. For more details reffer to the specification
2452 <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#49>`_
2458 The implementation of this feature mirrors the unroll hint for C.
2459 More details on the syntax can be found in the specification
2461 <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#61>`_
2466 To make sure no invalid optimizations occur for single program multiple data
2467 (SPMD) / single instruction multiple thread (SIMT) Clang provides attributes that
2468 can be used for special functions that have cross work item semantics.
2469 An example is the subgroup operations such as `intel_sub_group_shuffle
2470 <https://www.khronos.org/registry/cl/extensions/intel/cl_intel_subgroups.txt>`_
2474 // Define custom my_sub_group_shuffle(data, c)
2475 // that makes use of intel_sub_group_shuffle
2477 if (r0) r1 = computeA();
2478 // Shuffle data from r1 into r3
2479 // of threads id r2.
2480 r3 = my_sub_group_shuffle(r1, r2);
2481 if (r0) r3 = computeB();
2483 with non-SPMD semantics this is optimized to the following equivalent code:
2489 // Incorrect functionality! The data in r1
2490 // have not been computed by all threads yet.
2491 r3 = my_sub_group_shuffle(r1, r2);
2494 r3 = my_sub_group_shuffle(r1, r2);
2498 Declaring the function ``my_sub_group_shuffle`` with the convergent attribute
2503 my_sub_group_shuffle() __attribute__((convergent));
2505 Using ``convergent`` guarantees correct execution by keeping CFG equivalence
2506 wrt operations marked as ``convergent``. CFG ``G´`` is equivalent to ``G`` wrt
2507 node ``Ni`` : ``iff ∀ Nj (i≠j)`` domination and post-domination relations with
2508 respect to ``Ni`` remain the same in both ``G`` and ``G´``.
2513 ``noduplicate`` is more restrictive with respect to optimizations than
2514 ``convergent`` because a convergent function only preserves CFG equivalence.
2515 This allows some optimizations to happen as long as the control flow remains
2520 for (int i=0; i<4; i++)
2521 my_sub_group_shuffle()
2527 my_sub_group_shuffle();
2528 my_sub_group_shuffle();
2529 my_sub_group_shuffle();
2530 my_sub_group_shuffle();
2532 while using ``noduplicate`` would disallow this. Also ``noduplicate`` doesn't
2533 have the same safe semantics of CFG as ``convergent`` and can cause changes in
2534 CFG that modify semantics of the original program.
2536 ``noduplicate`` is kept for backwards compatibility only and it considered to be
2537 deprecated for future uses.
2544 Clang has arbitrary address space support using the ``address_space(N)``
2545 attribute, where ``N`` is an integer number in the range ``0`` to ``16777215``
2548 An OpenCL implementation provides a list of standard address spaces using
2549 keywords: ``private``, ``local``, ``global``, and ``generic``. In the AST and
2550 in the IR local, global, or generic will be represented by the address space
2551 attribute with the corresponding unique number. Note that private does not have
2552 any corresponding attribute added and, therefore, is represented by the absence
2553 of an address space number. The specific IDs for an address space do not have to
2554 match between the AST and the IR. Typically in the AST address space numbers
2555 represent logical segments while in the IR they represent physical segments.
2556 Therefore, machines with flat memory segments can map all AST address space
2557 numbers to the same physical segment ID or skip address space attribute
2558 completely while generating the IR. However, if the address space information
2559 is needed by the IR passes e.g. to improve alias analysis, it is recommended
2560 to keep it and only lower to reflect physical memory segments in the late
2566 There are some standard OpenCL functions that are implemented as Clang builtins:
2568 - All pipe functions from `section 6.13.16.2/6.13.16.3
2569 <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#160>`_ of
2570 the OpenCL v2.0 kernel language specification. `
2572 - Address space qualifier conversion functions ``to_global``/``to_local``/``to_private``
2573 from `section 6.13.9
2574 <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#101>`_.
2576 - All the ``enqueue_kernel`` functions from `section 6.13.17.1
2577 <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#164>`_ and
2578 enqueue query functions from `section 6.13.17.5
2579 <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#171>`_.
2581 .. _target_features:
2583 Target-Specific Features and Limitations
2584 ========================================
2586 CPU Architectures Features and Limitations
2587 ------------------------------------------
2592 The support for X86 (both 32-bit and 64-bit) is considered stable on
2593 Darwin (Mac OS X), Linux, FreeBSD, and Dragonfly BSD: it has been tested
2594 to correctly compile many large C, C++, Objective-C, and Objective-C++
2597 On ``x86_64-mingw32``, passing i128(by value) is incompatible with the
2598 Microsoft x64 calling convention. You might need to tweak
2599 ``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp.
2601 For the X86 target, clang supports the `-m16` command line
2602 argument which enables 16-bit code output. This is broadly similar to
2603 using ``asm(".code16gcc")`` with the GNU toolchain. The generated code
2604 and the ABI remains 32-bit but the assembler emits instructions
2605 appropriate for a CPU running in 16-bit mode, with address-size and
2606 operand-size prefixes to enable 32-bit addressing and operations.
2611 The support for ARM (specifically ARMv6 and ARMv7) is considered stable
2612 on Darwin (iOS): it has been tested to correctly compile many large C,
2613 C++, Objective-C, and Objective-C++ codebases. Clang only supports a
2614 limited number of ARM architectures. It does not yet fully support
2620 The support for PowerPC (especially PowerPC64) is considered stable
2621 on Linux and FreeBSD: it has been tested to correctly compile many
2622 large C and C++ codebases. PowerPC (32bit) is still missing certain
2623 features (e.g. PIC code on ELF platforms).
2628 clang currently contains some support for other architectures (e.g. Sparc);
2629 however, significant pieces of code generation are still missing, and they
2630 haven't undergone significant testing.
2632 clang contains limited support for the MSP430 embedded processor, but
2633 both the clang support and the LLVM backend support are highly
2636 Other platforms are completely unsupported at the moment. Adding the
2637 minimal support needed for parsing and semantic analysis on a new
2638 platform is quite easy; see ``lib/Basic/Targets.cpp`` in the clang source
2639 tree. This level of support is also sufficient for conversion to LLVM IR
2640 for simple programs. Proper support for conversion to LLVM IR requires
2641 adding code to ``lib/CodeGen/CGCall.cpp`` at the moment; this is likely to
2642 change soon, though. Generating assembly requires a suitable LLVM
2645 Operating System Features and Limitations
2646 -----------------------------------------
2651 Thread Sanitizer is not supported.
2656 Clang has experimental support for targeting "Cygming" (Cygwin / MinGW)
2659 See also :ref:`Microsoft Extensions <c_ms>`.
2664 Clang works on Cygwin-1.7.
2669 Clang works on some mingw32 distributions. Clang assumes directories as
2672 - ``C:/mingw/include``
2674 - ``C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++``
2676 On MSYS, a few tests might fail.
2681 For 32-bit (i686-w64-mingw32), and 64-bit (x86\_64-w64-mingw32), Clang
2684 - ``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)``
2685 - ``some_directory/bin/gcc.exe``
2686 - ``some_directory/bin/clang.exe``
2687 - ``some_directory/bin/clang++.exe``
2688 - ``some_directory/bin/../include/c++/GCC_version``
2689 - ``some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32``
2690 - ``some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32``
2691 - ``some_directory/bin/../include/c++/GCC_version/backward``
2692 - ``some_directory/bin/../x86_64-w64-mingw32/include``
2693 - ``some_directory/bin/../i686-w64-mingw32/include``
2694 - ``some_directory/bin/../include``
2696 This directory layout is standard for any toolchain you will find on the
2697 official `MinGW-w64 website <http://mingw-w64.sourceforge.net>`_.
2699 Clang expects the GCC executable "gcc.exe" compiled for
2700 ``i686-w64-mingw32`` (or ``x86_64-w64-mingw32``) to be present on PATH.
2702 `Some tests might fail <https://bugs.llvm.org/show_bug.cgi?id=9072>`_ on
2703 ``x86_64-w64-mingw32``.
2710 clang-cl is an alternative command-line interface to Clang, designed for
2711 compatibility with the Visual C++ compiler, cl.exe.
2713 To enable clang-cl to find system headers, libraries, and the linker when run
2714 from the command-line, it should be executed inside a Visual Studio Native Tools
2715 Command Prompt or a regular Command Prompt where the environment has been set
2716 up using e.g. `vcvarsall.bat <http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_.
2718 clang-cl can also be used from inside Visual Studio by selecting the LLVM
2719 Platform Toolset. The toolset is installed by the LLVM installer, which can be
2720 downloaded from the `LLVM release <http://releases.llvm.org/download.html>`_ or
2721 `snapshot build <http://llvm.org/builds/>`_ web pages. To use the toolset,
2722 select a project in Solution Explorer, open its Property Page (Alt+F7), and in
2723 the "General" section of "Configuration Properties" change "Platform Toolset"
2724 to e.g. LLVM-vs2014.
2726 To use the toolset with MSBuild directly, invoke it with e.g.
2727 ``/p:PlatformToolset=LLVM-vs2014``. This allows trying out the clang-cl
2728 toolchain without modifying your project files.
2730 It's also possible to point MSBuild at clang-cl without changing toolset by
2731 passing ``/p:CLToolPath=c:\llvm\bin /p:CLToolExe=clang-cl.exe``.
2733 When using CMake and the Visual Studio generators, the toolset can be set with the ``-T`` flag:
2737 cmake -G"Visual Studio 15 2017" -T LLVM-vs2014 ..
2739 When using CMake with the Ninja generator, set the ``CMAKE_C_COMPILER`` and
2740 ``CMAKE_CXX_COMPILER`` variables to clang-cl:
2744 cmake -GNinja -DCMAKE_C_COMPILER="c:/Program Files (x86)/LLVM/bin/clang-cl.exe"
2745 -DCMAKE_CXX_COMPILER="c:/Program Files (x86)/LLVM/bin/clang-cl.exe" ..
2748 Command-Line Options
2749 --------------------
2751 To be compatible with cl.exe, clang-cl supports most of the same command-line
2752 options. Those options can start with either ``/`` or ``-``. It also supports
2753 some of Clang's core options, such as the ``-W`` options.
2755 Options that are known to clang-cl, but not currently supported, are ignored
2756 with a warning. For example:
2760 clang-cl.exe: warning: argument unused during compilation: '/AI'
2762 To suppress warnings about unused arguments, use the ``-Qunused-arguments`` option.
2764 Options that are not known to clang-cl will be ignored by default. Use the
2765 ``-Werror=unknown-argument`` option in order to treat them as errors. If these
2766 options are spelled with a leading ``/``, they will be mistaken for a filename:
2770 clang-cl.exe: error: no such file or directory: '/foobar'
2772 Please `file a bug <https://bugs.llvm.org/enter_bug.cgi?product=clang&component=Driver>`_
2773 for any valid cl.exe flags that clang-cl does not understand.
2775 Execute ``clang-cl /?`` to see a list of supported options:
2779 CL.EXE COMPATIBILITY OPTIONS:
2780 /? Display available options
2781 /arch:<value> Set architecture for code generation
2782 /Brepro- Emit an object file which cannot be reproduced over time
2783 /Brepro Emit an object file which can be reproduced over time
2784 /C Don't discard comments when preprocessing
2786 /d1reportAllClassLayout Dump record layout information
2787 /diagnostics:caret Enable caret and column diagnostics (on by default)
2788 /diagnostics:classic Disable column and caret diagnostics
2789 /diagnostics:column Disable caret diagnostics but keep column info
2790 /D <macro[=value]> Define macro
2791 /EH<value> Exception handling model
2792 /EP Disable linemarker output and preprocess to stdout
2793 /execution-charset:<value>
2794 Runtime encoding, supports only UTF-8
2795 /E Preprocess to stdout
2796 /fallback Fall back to cl.exe if clang-cl fails to compile
2797 /FA Output assembly code file during compilation
2798 /Fa<file or directory> Output assembly code to this file during compilation (with /FA)
2799 /Fe<file or directory> Set output executable file or directory (ends in / or \)
2800 /FI <value> Include file before parsing
2801 /Fi<file> Set preprocess output file name (with /P)
2802 /Fo<file or directory> Set output object file, or directory (ends in / or \) (with /c)
2808 /Fp<filename> Set pch filename (with /Yc and /Yu)
2809 /GA Assume thread-local variables are defined in the executable
2810 /Gd Set __cdecl as a default calling convention
2811 /GF- Disable string pooling
2812 /GR- Disable emission of RTTI data
2813 /Gregcall Set __regcall as a default calling convention
2814 /GR Enable emission of RTTI data
2815 /Gr Set __fastcall as a default calling convention
2816 /GS- Disable buffer security check
2817 /GS Enable buffer security check
2818 /Gs<value> Set stack probe size
2819 /Gv Set __vectorcall as a default calling convention
2820 /Gw- Don't put each data item in its own section
2821 /Gw Put each data item in its own section
2822 /GX- Disable exception handling
2823 /GX Enable exception handling
2824 /Gy- Don't put each function in its own section
2825 /Gy Put each function in its own section
2826 /Gz Set __stdcall as a default calling convention
2827 /help Display available options
2828 /imsvc <dir> Add directory to system include search path, as if part of %INCLUDE%
2829 /I <dir> Add directory to include search path
2830 /J Make char type unsigned
2831 /LDd Create debug DLL
2833 /link <options> Forward options to the linker
2834 /MDd Use DLL debug run-time
2835 /MD Use DLL run-time
2836 /MTd Use static debug run-time
2837 /MT Use static run-time
2838 /Od Disable optimization
2839 /Oi- Disable use of builtin functions
2840 /Oi Enable use of builtin functions
2841 /Os Optimize for size
2842 /Ot Optimize for speed
2843 /O<value> Optimization level
2844 /o <file or directory> Set output file or directory (ends in / or \)
2845 /P Preprocess to file
2846 /Qvec- Disable the loop vectorization passes
2847 /Qvec Enable the loop vectorization passes
2848 /showIncludes Print info about included files to stderr
2849 /source-charset:<value> Source encoding, supports only UTF-8
2850 /std:<value> Language standard to compile for
2851 /TC Treat all source files as C
2852 /Tc <filename> Specify a C source file
2853 /TP Treat all source files as C++
2854 /Tp <filename> Specify a C++ source file
2855 /utf-8 Set source and runtime encoding to UTF-8 (default)
2856 /U <macro> Undefine macro
2857 /vd<value> Control vtordisp placement
2858 /vmb Use a best-case representation method for member pointers
2859 /vmg Use a most-general representation for member pointers
2860 /vmm Set the default most-general representation to multiple inheritance
2861 /vms Set the default most-general representation to single inheritance
2862 /vmv Set the default most-general representation to virtual inheritance
2863 /volatile:iso Volatile loads and stores have standard semantics
2864 /volatile:ms Volatile loads and stores have acquire and release semantics
2865 /W0 Disable all warnings
2869 /W4 Enable -Wall and -Wextra
2870 /Wall Enable -Weverything
2871 /WX- Do not treat warnings as errors
2872 /WX Treat warnings as errors
2873 /w Disable all warnings
2874 /Y- Disable precompiled headers, overrides /Yc and /Yu
2875 /Yc<filename> Generate a pch file for all code up to and including <filename>
2876 /Yu<filename> Load a pch file and use it instead of all code up to and including <filename>
2877 /Z7 Enable CodeView debug information in object files
2878 /Zc:sizedDealloc- Disable C++14 sized global deallocation functions
2879 /Zc:sizedDealloc Enable C++14 sized global deallocation functions
2880 /Zc:strictStrings Treat string literals as const
2881 /Zc:threadSafeInit- Disable thread-safe initialization of static variables
2882 /Zc:threadSafeInit Enable thread-safe initialization of static variables
2883 /Zc:trigraphs- Disable trigraphs (default)
2884 /Zc:trigraphs Enable trigraphs
2885 /Zc:twoPhase- Disable two-phase name lookup in templates
2886 /Zc:twoPhase Enable two-phase name lookup in templates
2887 /Zd Emit debug line number tables only
2888 /Zi Alias for /Z7. Does not produce PDBs.
2889 /Zl Don't mention any default libraries in the object file
2890 /Zp Set the default maximum struct packing alignment to 1
2891 /Zp<value> Specify the default maximum struct packing alignment
2892 /Zs Syntax-check only
2895 -### Print (but do not run) the commands to run for this compilation
2896 --analyze Run the static analyzer
2897 -fansi-escape-codes Use ANSI escape codes for diagnostics
2898 -fcolor-diagnostics Use colors in diagnostics
2899 -fdebug-macro Emit macro debug information
2900 -fdelayed-template-parsing
2901 Parse templated function definitions at the end of the translation unit
2902 -fdiagnostics-absolute-paths
2903 Print absolute paths in diagnostics
2904 -fdiagnostics-parseable-fixits
2905 Print fix-its in machine parseable form
2906 -flto=<value> Set LTO mode to either 'full' or 'thin'
2907 -flto Enable LTO in 'full' mode
2908 -fms-compatibility-version=<value>
2909 Dot-separated value representing the Microsoft compiler version
2910 number to report in _MSC_VER (0 = don't define it (default))
2911 -fms-compatibility Enable full Microsoft Visual C++ compatibility
2912 -fms-extensions Accept some non-standard constructs supported by the Microsoft compiler
2913 -fmsc-version=<value> Microsoft compiler version number to report in _MSC_VER
2914 (0 = don't define it (default))
2915 -fno-debug-macro Do not emit macro debug information
2916 -fno-delayed-template-parsing
2917 Disable delayed template parsing
2918 -fno-sanitize-address-use-after-scope
2919 Disable use-after-scope detection in AddressSanitizer
2920 -fno-sanitize-blacklist Don't use blacklist file for sanitizers
2921 -fno-sanitize-cfi-cross-dso
2922 Disable control flow integrity (CFI) checks for cross-DSO calls.
2923 -fno-sanitize-coverage=<value>
2924 Disable specified features of coverage instrumentation for Sanitizers
2925 -fno-sanitize-memory-track-origins
2926 Disable origins tracking in MemorySanitizer
2927 -fno-sanitize-memory-use-after-dtor
2928 Disable use-after-destroy detection in MemorySanitizer
2929 -fno-sanitize-recover=<value>
2930 Disable recovery for specified sanitizers
2931 -fno-sanitize-stats Disable sanitizer statistics gathering.
2932 -fno-sanitize-thread-atomics
2933 Disable atomic operations instrumentation in ThreadSanitizer
2934 -fno-sanitize-thread-func-entry-exit
2935 Disable function entry/exit instrumentation in ThreadSanitizer
2936 -fno-sanitize-thread-memory-access
2937 Disable memory access instrumentation in ThreadSanitizer
2938 -fno-sanitize-trap=<value>
2939 Disable trapping for specified sanitizers
2940 -fno-standalone-debug Limit debug information produced to reduce size of debug binary
2941 -fprofile-instr-generate=<file>
2942 Generate instrumented code to collect execution counts into <file>
2943 (overridden by LLVM_PROFILE_FILE env var)
2944 -fprofile-instr-generate
2945 Generate instrumented code to collect execution counts into default.profraw file
2946 (overridden by '=' form of option or LLVM_PROFILE_FILE env var)
2947 -fprofile-instr-use=<value>
2948 Use instrumentation data for profile-guided optimization
2949 -fsanitize-address-field-padding=<value>
2950 Level of field padding for AddressSanitizer
2951 -fsanitize-address-globals-dead-stripping
2952 Enable linker dead stripping of globals in AddressSanitizer
2953 -fsanitize-address-use-after-scope
2954 Enable use-after-scope detection in AddressSanitizer
2955 -fsanitize-blacklist=<value>
2956 Path to blacklist file for sanitizers
2957 -fsanitize-cfi-cross-dso
2958 Enable control flow integrity (CFI) checks for cross-DSO calls.
2959 -fsanitize-cfi-icall-generalize-pointers
2960 Generalize pointers in CFI indirect call type signature checks
2961 -fsanitize-coverage=<value>
2962 Specify the type of coverage instrumentation for Sanitizers
2963 -fsanitize-memory-track-origins=<value>
2964 Enable origins tracking in MemorySanitizer
2965 -fsanitize-memory-track-origins
2966 Enable origins tracking in MemorySanitizer
2967 -fsanitize-memory-use-after-dtor
2968 Enable use-after-destroy detection in MemorySanitizer
2969 -fsanitize-recover=<value>
2970 Enable recovery for specified sanitizers
2971 -fsanitize-stats Enable sanitizer statistics gathering.
2972 -fsanitize-thread-atomics
2973 Enable atomic operations instrumentation in ThreadSanitizer (default)
2974 -fsanitize-thread-func-entry-exit
2975 Enable function entry/exit instrumentation in ThreadSanitizer (default)
2976 -fsanitize-thread-memory-access
2977 Enable memory access instrumentation in ThreadSanitizer (default)
2978 -fsanitize-trap=<value> Enable trapping for specified sanitizers
2979 -fsanitize-undefined-strip-path-components=<number>
2980 Strip (or keep only, if negative) a given number of path components when emitting check metadata.
2981 -fsanitize=<check> Turn on runtime checks for various forms of undefined or suspicious
2982 behavior. See user manual for available checks
2983 -fstandalone-debug Emit full debug info for all types used by the program
2984 -fwhole-program-vtables Enables whole-program vtable optimization. Requires -flto
2985 -gcodeview Generate CodeView debug information
2986 -gline-tables-only Emit debug line number tables only
2987 -miamcu Use Intel MCU ABI
2988 -mllvm <value> Additional arguments to forward to LLVM's option processing
2989 -nobuiltininc Disable builtin #include directories
2990 -Qunused-arguments Don't emit warning for unused driver arguments
2991 -R<remark> Enable the specified remark
2992 --target=<value> Generate code for the given target
2993 --version Print version information
2994 -v Show commands to run and use verbose output
2995 -W<warning> Enable the specified warning
2996 -Xclang <arg> Pass <arg> to the clang compiler
2998 The /fallback Option
2999 ^^^^^^^^^^^^^^^^^^^^
3001 When clang-cl is run with the ``/fallback`` option, it will first try to
3002 compile files itself. For any file that it fails to compile, it will fall back
3003 and try to compile the file by invoking cl.exe.
3005 This option is intended to be used as a temporary means to build projects where
3006 clang-cl cannot successfully compile all the files. clang-cl may fail to compile
3007 a file either because it cannot generate code for some C++ feature, or because
3008 it cannot parse some Microsoft language extension.