1 ============================
2 Clang Compiler User's Manual
3 ============================
11 The Clang Compiler is an open-source compiler for the C family of
12 programming languages, aiming to be the best in class implementation of
13 these languages. Clang builds on the LLVM optimizer and code generator,
14 allowing it to provide high-quality optimization and code generation
15 support for many targets. For more general information, please see the
16 `Clang Web Site <http://clang.llvm.org>`_ or the `LLVM Web
17 Site <http://llvm.org>`_.
19 This document describes important notes about using Clang as a compiler
20 for an end-user, documenting the supported features, command line
21 options, etc. If you are interested in using Clang to build a tool that
22 processes code, please see :doc:`InternalsManual`. If you are interested in the
23 `Clang Static Analyzer <http://clang-analyzer.llvm.org>`_, please see its web
26 Clang is designed to support the C family of programming languages,
27 which includes :ref:`C <c>`, :ref:`Objective-C <objc>`, :ref:`C++ <cxx>`, and
28 :ref:`Objective-C++ <objcxx>` as well as many dialects of those. For
29 language-specific information, please see the corresponding language
32 - :ref:`C Language <c>`: K&R C, ANSI C89, ISO C90, ISO C94 (C89+AMD1), ISO
34 - :ref:`Objective-C Language <objc>`: ObjC 1, ObjC 2, ObjC 2.1, plus
35 variants depending on base language.
36 - :ref:`C++ Language <cxx>`
37 - :ref:`Objective C++ Language <objcxx>`
39 In addition to these base languages and their dialects, Clang supports a
40 broad variety of language extensions, which are documented in the
41 corresponding language section. These extensions are provided to be
42 compatible with the GCC, Microsoft, and other popular compilers as well
43 as to improve functionality through Clang-specific features. The Clang
44 driver and language features are intentionally designed to be as
45 compatible with the GNU GCC compiler as reasonably possible, easing
46 migration from GCC to Clang. In most cases, code "just works".
47 Clang also provides an alternative driver, :ref:`clang-cl`, that is designed
48 to be compatible with the Visual C++ compiler, cl.exe.
50 In addition to language specific features, Clang has a variety of
51 features that depend on what CPU architecture or operating system is
52 being compiled for. Please see the :ref:`Target-Specific Features and
53 Limitations <target_features>` section for more details.
55 The rest of the introduction introduces some basic :ref:`compiler
56 terminology <terminology>` that is used throughout this manual and
57 contains a basic :ref:`introduction to using Clang <basicusage>` as a
58 command line compiler.
65 Front end, parser, backend, preprocessor, undefined behavior,
73 Intro to how to use a C compiler for newbies.
75 compile + link compile then link debug info enabling optimizations
76 picking a language to use, defaults to C99 by default. Autosenses based
77 on extension. using a makefile
82 This section is generally an index into other sections. It does not go
83 into depth on the ones that are covered by other sections. However, the
84 first part introduces the language selection and other high level
85 options like :option:`-c`, :option:`-g`, etc.
87 Options to Control Error and Warning Messages
88 ---------------------------------------------
92 Turn warnings into errors.
94 .. This is in plain monospaced font because it generates the same label as
95 .. -Werror, and Sphinx complains.
99 Turn warning "foo" into an error.
101 .. option:: -Wno-error=foo
103 Turn warning "foo" into an warning even if :option:`-Werror` is specified.
107 Enable warning "foo".
111 Disable warning "foo".
115 Disable all warnings.
117 .. option:: -Weverything
119 :ref:`Enable all warnings. <diagnostics_enable_everything>`
121 .. option:: -pedantic
123 Warn on language extensions.
125 .. option:: -pedantic-errors
127 Error on language extensions.
129 .. option:: -Wsystem-headers
131 Enable warnings from system headers.
133 .. option:: -ferror-limit=123
135 Stop emitting diagnostics after 123 errors have been produced. The default is
136 20, and the error limit can be disabled with :option:`-ferror-limit=0`.
138 .. option:: -ftemplate-backtrace-limit=123
140 Only emit up to 123 template instantiation notes within the template
141 instantiation backtrace for a single warning or error. The default is 10, and
142 the limit can be disabled with :option:`-ftemplate-backtrace-limit=0`.
144 .. _cl_diag_formatting:
146 Formatting of Diagnostics
147 ^^^^^^^^^^^^^^^^^^^^^^^^^
149 Clang aims to produce beautiful diagnostics by default, particularly for
150 new users that first come to Clang. However, different people have
151 different preferences, and sometimes Clang is driven by another program
152 that wants to parse simple and consistent output, not a person. For
153 these cases, Clang provides a wide range of options to control the exact
154 output format of the diagnostics that it generates.
156 .. _opt_fshow-column:
158 **-f[no-]show-column**
159 Print column number in diagnostic.
161 This option, which defaults to on, controls whether or not Clang
162 prints the column number of a diagnostic. For example, when this is
163 enabled, Clang will print something like:
167 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
172 When this is disabled, Clang will print "test.c:28: warning..." with
175 The printed column numbers count bytes from the beginning of the
176 line; take care if your source contains multibyte characters.
178 .. _opt_fshow-source-location:
180 **-f[no-]show-source-location**
181 Print source file/line/column information in diagnostic.
183 This option, which defaults to on, controls whether or not Clang
184 prints the filename, line number and column number of a diagnostic.
185 For example, when this is enabled, Clang will print something like:
189 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
194 When this is disabled, Clang will not print the "test.c:28:8: "
197 .. _opt_fcaret-diagnostics:
199 **-f[no-]caret-diagnostics**
200 Print source line and ranges from source code in diagnostic.
201 This option, which defaults to on, controls whether or not Clang
202 prints the source line, source ranges, and caret when emitting a
203 diagnostic. For example, when this is enabled, Clang will print
208 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
213 **-f[no-]color-diagnostics**
214 This option, which defaults to on when a color-capable terminal is
215 detected, controls whether or not Clang prints diagnostics in color.
217 When this option is enabled, Clang will use colors to highlight
218 specific parts of the diagnostic, e.g.,
220 .. nasty hack to not lose our dignity
225 <b><span style="color:black">test.c:28:8: <span style="color:magenta">warning</span>: extra tokens at end of #endif directive [-Wextra-tokens]</span></b>
227 <span style="color:green">^</span>
228 <span style="color:green">//</span>
231 When this is disabled, Clang will just print:
235 test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
240 **-fansi-escape-codes**
241 Controls whether ANSI escape codes are used instead of the Windows Console
242 API to output colored diagnostics. This option is only used on Windows and
245 .. option:: -fdiagnostics-format=clang/msvc/vi
247 Changes diagnostic output format to better match IDEs and command line tools.
249 This option controls the output format of the filename, line number,
250 and column printed in diagnostic messages. The options, and their
251 affect on formatting a simple conversion diagnostic, follow:
256 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
261 t.c(3,11) : warning: conversion specifies type 'char *' but the argument has type 'int'
266 t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
268 **-f[no-]diagnostics-show-name**
269 Enable the display of the diagnostic name.
270 This option, which defaults to off, controls whether or not Clang
271 prints the associated name.
273 .. _opt_fdiagnostics-show-option:
275 **-f[no-]diagnostics-show-option**
276 Enable ``[-Woption]`` information in diagnostic line.
278 This option, which defaults to on, controls whether or not Clang
279 prints the associated :ref:`warning group <cl_diag_warning_groups>`
280 option name when outputting a warning diagnostic. For example, in
285 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
290 Passing **-fno-diagnostics-show-option** will prevent Clang from
291 printing the [:ref:`-Wextra-tokens <opt_Wextra-tokens>`] information in
292 the diagnostic. This information tells you the flag needed to enable
293 or disable the diagnostic, either from the command line or through
294 :ref:`#pragma GCC diagnostic <pragma_GCC_diagnostic>`.
296 .. _opt_fdiagnostics-show-category:
298 .. option:: -fdiagnostics-show-category=none/id/name
300 Enable printing category information in diagnostic line.
302 This option, which defaults to "none", controls whether or not Clang
303 prints the category associated with a diagnostic when emitting it.
304 Each diagnostic may or many not have an associated category, if it
305 has one, it is listed in the diagnostic categorization field of the
306 diagnostic line (in the []'s).
308 For example, a format string warning will produce these three
309 renditions based on the setting of this option:
313 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat]
314 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1]
315 t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String]
317 This category can be used by clients that want to group diagnostics
318 by category, so it should be a high level category. We want dozens
319 of these, not hundreds or thousands of them.
321 .. _opt_fdiagnostics-fixit-info:
323 **-f[no-]diagnostics-fixit-info**
324 Enable "FixIt" information in the diagnostics output.
326 This option, which defaults to on, controls whether or not Clang
327 prints the information on how to fix a specific diagnostic
328 underneath it when it knows. For example, in this output:
332 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
337 Passing **-fno-diagnostics-fixit-info** will prevent Clang from
338 printing the "//" line at the end of the message. This information
339 is useful for users who may not understand what is wrong, but can be
340 confusing for machine parsing.
342 .. _opt_fdiagnostics-print-source-range-info:
344 **-fdiagnostics-print-source-range-info**
345 Print machine parsable information about source ranges.
346 This option makes Clang print information about source ranges in a machine
347 parsable format after the file/line/column number information. The
348 information is a simple sequence of brace enclosed ranges, where each range
349 lists the start and end line/column locations. For example, in this output:
353 exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float')
354 P = (P-42) + Gamma*4;
357 The {}'s are generated by -fdiagnostics-print-source-range-info.
359 The printed column numbers count bytes from the beginning of the
360 line; take care if your source contains multibyte characters.
362 .. option:: -fdiagnostics-parseable-fixits
364 Print Fix-Its in a machine parseable form.
366 This option makes Clang print available Fix-Its in a machine
367 parseable format at the end of diagnostics. The following example
368 illustrates the format:
372 fix-it:"t.cpp":{7:25-7:29}:"Gamma"
374 The range printed is a half-open range, so in this example the
375 characters at column 25 up to but not including column 29 on line 7
376 in t.cpp should be replaced with the string "Gamma". Either the
377 range or the replacement string may be empty (representing strict
378 insertions and strict erasures, respectively). Both the file name
379 and the insertion string escape backslash (as "\\\\"), tabs (as
380 "\\t"), newlines (as "\\n"), double quotes(as "\\"") and
381 non-printable characters (as octal "\\xxx").
383 The printed column numbers count bytes from the beginning of the
384 line; take care if your source contains multibyte characters.
386 .. option:: -fno-elide-type
388 Turns off elision in template type printing.
390 The default for template type printing is to elide as many template
391 arguments as possible, removing those which are the same in both
392 template types, leaving only the differences. Adding this flag will
393 print all the template arguments. If supported by the terminal,
394 highlighting will still appear on differing arguments.
400 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;
406 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;
408 .. option:: -fdiagnostics-show-template-tree
410 Template type diffing prints a text tree.
412 For diffing large templated types, this option will cause Clang to
413 display the templates as an indented text tree, one argument per
414 line, with differences marked inline. This is compatible with
421 t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument;
423 With :option:`-fdiagnostics-show-template-tree`:
427 t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument;
435 .. _cl_diag_warning_groups:
437 Individual Warning Groups
438 ^^^^^^^^^^^^^^^^^^^^^^^^^
440 TODO: Generate this from tblgen. Define one anchor per warning group.
442 .. _opt_wextra-tokens:
444 .. option:: -Wextra-tokens
446 Warn about excess tokens at the end of a preprocessor directive.
448 This option, which defaults to on, enables warnings about extra
449 tokens at the end of preprocessor directives. For example:
453 test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
457 These extra tokens are not strictly conforming, and are usually best
458 handled by commenting them out.
460 .. option:: -Wambiguous-member-template
462 Warn about unqualified uses of a member template whose name resolves to
463 another template at the location of the use.
465 This option, which defaults to on, enables a warning in the
470 template<typename T> struct set{};
471 template<typename T> struct trait { typedef const T& type; };
473 template<typename T> void set(typename trait<T>::type value) {}
480 C++ [basic.lookup.classref] requires this to be an error, but,
481 because it's hard to work around, Clang downgrades it to a warning
484 .. option:: -Wbind-to-temporary-copy
486 Warn about an unusable copy constructor when binding a reference to a
489 This option, which defaults to on, enables warnings about binding a
490 reference to a temporary when the temporary doesn't have a usable
491 copy constructor. For example:
498 NonCopyable(const NonCopyable&);
500 void foo(const NonCopyable&);
502 foo(NonCopyable()); // Disallowed in C++98; allowed in C++11.
507 struct NonCopyable2 {
509 NonCopyable2(NonCopyable2&);
511 void foo(const NonCopyable2&);
513 foo(NonCopyable2()); // Disallowed in C++98; allowed in C++11.
516 Note that if ``NonCopyable2::NonCopyable2()`` has a default argument
517 whose instantiation produces a compile error, that error will still
518 be a hard error in C++98 mode even if this warning is turned off.
520 Options to Control Clang Crash Diagnostics
521 ------------------------------------------
523 As unbelievable as it may sound, Clang does crash from time to time.
524 Generally, this only occurs to those living on the `bleeding
525 edge <http://llvm.org/releases/download.html#svn>`_. Clang goes to great
526 lengths to assist you in filing a bug report. Specifically, Clang
527 generates preprocessed source file(s) and associated run script(s) upon
528 a crash. These files should be attached to a bug report to ease
529 reproducibility of the failure. Below are the command line options to
530 control the crash diagnostics.
532 .. option:: -fno-crash-diagnostics
534 Disable auto-generation of preprocessed source files during a clang crash.
536 The -fno-crash-diagnostics flag can be helpful for speeding the process
537 of generating a delta reduced test case.
539 Language and Target-Independent Features
540 ========================================
542 Controlling Errors and Warnings
543 -------------------------------
545 Clang provides a number of ways to control which code constructs cause
546 it to emit errors and warning messages, and how they are displayed to
549 Controlling How Clang Displays Diagnostics
550 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
552 When Clang emits a diagnostic, it includes rich information in the
553 output, and gives you fine-grain control over which information is
554 printed. Clang has the ability to print this information, and these are
555 the options that control it:
557 #. A file/line/column indicator that shows exactly where the diagnostic
558 occurs in your code [:ref:`-fshow-column <opt_fshow-column>`,
559 :ref:`-fshow-source-location <opt_fshow-source-location>`].
560 #. A categorization of the diagnostic as a note, warning, error, or
562 #. A text string that describes what the problem is.
563 #. An option that indicates how to control the diagnostic (for
564 diagnostics that support it)
565 [:ref:`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`].
566 #. A :ref:`high-level category <diagnostics_categories>` for the diagnostic
567 for clients that want to group diagnostics by class (for diagnostics
569 [:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>`].
570 #. The line of source code that the issue occurs on, along with a caret
571 and ranges that indicate the important locations
572 [:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`].
573 #. "FixIt" information, which is a concise explanation of how to fix the
574 problem (when Clang is certain it knows)
575 [:ref:`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`].
576 #. A machine-parsable representation of the ranges involved (off by
578 [:ref:`-fdiagnostics-print-source-range-info <opt_fdiagnostics-print-source-range-info>`].
580 For more information please see :ref:`Formatting of
581 Diagnostics <cl_diag_formatting>`.
586 All diagnostics are mapped into one of these 5 classes:
594 .. _diagnostics_categories:
596 Diagnostic Categories
597 ^^^^^^^^^^^^^^^^^^^^^
599 Though not shown by default, diagnostics may each be associated with a
600 high-level category. This category is intended to make it possible to
601 triage builds that produce a large number of errors or warnings in a
604 Categories are not shown by default, but they can be turned on with the
605 :ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>` option.
606 When set to "``name``", the category is printed textually in the
607 diagnostic output. When it is set to "``id``", a category number is
608 printed. The mapping of category names to category id's can be obtained
609 by running '``clang --print-diagnostic-categories``'.
611 Controlling Diagnostics via Command Line Flags
612 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
614 TODO: -W flags, -pedantic, etc
616 .. _pragma_gcc_diagnostic:
618 Controlling Diagnostics via Pragmas
619 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
621 Clang can also control what diagnostics are enabled through the use of
622 pragmas in the source code. This is useful for turning off specific
623 warnings in a section of source code. Clang supports GCC's pragma for
624 compatibility with existing source code, as well as several extensions.
626 The pragma may control any warning that can be used from the command
627 line. Warnings may be set to ignored, warning, error, or fatal. The
628 following example code will tell Clang or GCC to ignore the -Wall
633 #pragma GCC diagnostic ignored "-Wall"
635 In addition to all of the functionality provided by GCC's pragma, Clang
636 also allows you to push and pop the current warning state. This is
637 particularly useful when writing a header file that will be compiled by
638 other people, because you don't know what warning flags they build with.
640 In the below example :option:`-Wmultichar` is ignored for only a single line of
641 code, after which the diagnostics return to whatever state had previously
646 #pragma clang diagnostic push
647 #pragma clang diagnostic ignored "-Wmultichar"
649 char b = 'df'; // no warning.
651 #pragma clang diagnostic pop
653 The push and pop pragmas will save and restore the full diagnostic state
654 of the compiler, regardless of how it was set. That means that it is
655 possible to use push and pop around GCC compatible diagnostics and Clang
656 will push and pop them appropriately, while GCC will ignore the pushes
657 and pops as unknown pragmas. It should be noted that while Clang
658 supports the GCC pragma, Clang and GCC do not support the exact same set
659 of warnings, so even when using GCC compatible #pragmas there is no
660 guarantee that they will have identical behaviour on both compilers.
662 In addition to controlling warnings and errors generated by the compiler, it is
663 possible to generate custom warning and error messages through the following
668 // The following will produce warning messages
669 #pragma message "some diagnostic message"
670 #pragma GCC warning "TODO: replace deprecated feature"
672 // The following will produce an error message
673 #pragma GCC error "Not supported"
675 These pragmas operate similarly to the ``#warning`` and ``#error`` preprocessor
676 directives, except that they may also be embedded into preprocessor macros via
677 the C99 ``_Pragma`` operator, for example:
682 #define DEFER(M,...) M(__VA_ARGS__)
683 #define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__))))
685 CUSTOM_ERROR("Feature not available");
687 Controlling Diagnostics in System Headers
688 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
690 Warnings are suppressed when they occur in system headers. By default,
691 an included file is treated as a system header if it is found in an
692 include path specified by ``-isystem``, but this can be overridden in
695 The ``system_header`` pragma can be used to mark the current file as
696 being a system header. No warnings will be produced from the location of
697 the pragma onwards within the same file.
701 char a = 'xy'; // warning
703 #pragma clang system_header
705 char b = 'ab'; // no warning
707 The :option:`-isystem-prefix` and :option:`-ino-system-prefix` command-line
708 arguments can be used to override whether subsets of an include path are
709 treated as system headers. When the name in a ``#include`` directive is
710 found within a header search path and starts with a system prefix, the
711 header is treated as a system header. The last prefix on the
712 command-line which matches the specified header name takes precedence.
715 .. code-block:: console
717 $ clang -Ifoo -isystem bar -isystem-prefix x/ -ino-system-prefix x/y/
719 Here, ``#include "x/a.h"`` is treated as including a system header, even
720 if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated
721 as not including a system header, even if the header is found in
724 A ``#include`` directive which finds a file relative to the current
725 directory is treated as including a system header if the including file
726 is treated as a system header.
728 .. _diagnostics_enable_everything:
730 Enabling All Warnings
731 ^^^^^^^^^^^^^^^^^^^^^
733 In addition to the traditional ``-W`` flags, one can enable **all**
734 warnings by passing :option:`-Weverything`. This works as expected with
735 :option:`-Werror`, and also includes the warnings from :option:`-pedantic`.
737 Note that when combined with :option:`-w` (which disables all warnings), that
740 Controlling Static Analyzer Diagnostics
741 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
743 While not strictly part of the compiler, the diagnostics from Clang's
744 `static analyzer <http://clang-analyzer.llvm.org>`_ can also be
745 influenced by the user via changes to the source code. See the available
746 `annotations <http://clang-analyzer.llvm.org/annotations.html>`_ and the
748 page <http://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more
751 .. _usersmanual-precompiled-headers:
756 `Precompiled headers <http://en.wikipedia.org/wiki/Precompiled_header>`__
757 are a general approach employed by many compilers to reduce compilation
758 time. The underlying motivation of the approach is that it is common for
759 the same (and often large) header files to be included by multiple
760 source files. Consequently, compile times can often be greatly improved
761 by caching some of the (redundant) work done by a compiler to process
762 headers. Precompiled header files, which represent one of many ways to
763 implement this optimization, are literally files that represent an
764 on-disk cache that contains the vital information necessary to reduce
765 some of the work needed to process a corresponding header file. While
766 details of precompiled headers vary between compilers, precompiled
767 headers have been shown to be highly effective at speeding up program
768 compilation on systems with very large system headers (e.g., Mac OS/X).
770 Generating a PCH File
771 ^^^^^^^^^^^^^^^^^^^^^
773 To generate a PCH file using Clang, one invokes Clang with the
774 :option:`-x <language>-header` option. This mirrors the interface in GCC
775 for generating PCH files:
777 .. code-block:: console
779 $ gcc -x c-header test.h -o test.h.gch
780 $ clang -x c-header test.h -o test.h.pch
785 A PCH file can then be used as a prefix header when a :option:`-include`
786 option is passed to ``clang``:
788 .. code-block:: console
790 $ clang -include test.h test.c -o test
792 The ``clang`` driver will first check if a PCH file for ``test.h`` is
793 available; if so, the contents of ``test.h`` (and the files it includes)
794 will be processed from the PCH file. Otherwise, Clang falls back to
795 directly processing the content of ``test.h``. This mirrors the behavior
800 Clang does *not* automatically use PCH files for headers that are directly
801 included within a source file. For example:
803 .. code-block:: console
805 $ clang -x c-header test.h -o test.h.pch
808 $ clang test.c -o test
810 In this example, ``clang`` will not automatically use the PCH file for
811 ``test.h`` since ``test.h`` was included directly in the source file and not
812 specified on the command line using :option:`-include`.
814 Relocatable PCH Files
815 ^^^^^^^^^^^^^^^^^^^^^
817 It is sometimes necessary to build a precompiled header from headers
818 that are not yet in their final, installed locations. For example, one
819 might build a precompiled header within the build tree that is then
820 meant to be installed alongside the headers. Clang permits the creation
821 of "relocatable" precompiled headers, which are built with a given path
822 (into the build directory) and can later be used from an installed
825 To build a relocatable precompiled header, place your headers into a
826 subdirectory whose structure mimics the installed location. For example,
827 if you want to build a precompiled header for the header ``mylib.h``
828 that will be installed into ``/usr/include``, create a subdirectory
829 ``build/usr/include`` and place the header ``mylib.h`` into that
830 subdirectory. If ``mylib.h`` depends on other headers, then they can be
831 stored within ``build/usr/include`` in a way that mimics the installed
834 Building a relocatable precompiled header requires two additional
835 arguments. First, pass the ``--relocatable-pch`` flag to indicate that
836 the resulting PCH file should be relocatable. Second, pass
837 :option:`-isysroot /path/to/build`, which makes all includes for your library
838 relative to the build directory. For example:
840 .. code-block:: console
842 # clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
844 When loading the relocatable PCH file, the various headers used in the
845 PCH file are found from the system header root. For example, ``mylib.h``
846 can be found in ``/usr/include/mylib.h``. If the headers are installed
847 in some other system root, the :option:`-isysroot` option can be used provide
848 a different system root from which the headers will be based. For
849 example, :option:`-isysroot /Developer/SDKs/MacOSX10.4u.sdk` will look for
850 ``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``.
852 Relocatable precompiled headers are intended to be used in a limited
853 number of cases where the compilation environment is tightly controlled
854 and the precompiled header cannot be generated after headers have been
857 Controlling Code Generation
858 ---------------------------
860 Clang provides a number of ways to control code generation. The options
863 **-f[no-]sanitize=check1,check2,...**
864 Turn on runtime checks for various forms of undefined or suspicious
867 This option controls whether Clang adds runtime checks for various
868 forms of undefined or suspicious behavior, and is disabled by
869 default. If a check fails, a diagnostic message is produced at
870 runtime explaining the problem. The main checks are:
872 - .. _opt_fsanitize_address:
874 ``-fsanitize=address``:
875 :doc:`AddressSanitizer`, a memory error
877 - ``-fsanitize=init-order``: Make AddressSanitizer check for
878 dynamic initialization order problems. Implied by ``-fsanitize=address``.
879 - ``-fsanitize=address-full``: AddressSanitizer with all the
880 experimental features listed below.
881 - ``-fsanitize=integer``: Enables checks for undefined or
882 suspicious integer behavior.
883 - .. _opt_fsanitize_thread:
885 ``-fsanitize=thread``: :doc:`ThreadSanitizer`, a data race detector.
886 - .. _opt_fsanitize_memory:
888 ``-fsanitize=memory``: :doc:`MemorySanitizer`,
889 an *experimental* detector of uninitialized reads. Not ready for
891 - .. _opt_fsanitize_undefined:
893 ``-fsanitize=undefined``: Fast and compatible undefined behavior
894 checker. Enables the undefined behavior checks that have small
895 runtime cost and no impact on address space layout or ABI. This
896 includes all of the checks listed below other than
897 ``unsigned-integer-overflow``.
899 - ``-fsanitize=undefined-trap``: This includes all sanitizers
900 included by ``-fsanitize=undefined``, except those that require
901 runtime support. This group of sanitizers is intended to be
902 used in conjunction with the ``-fsanitize-undefined-trap-on-error``
903 flag. This includes all of the checks listed below other than
904 ``unsigned-integer-overflow`` and ``vptr``.
905 - ``-fsanitize=dataflow``: :doc:`DataFlowSanitizer`, a general data
908 The following more fine-grained checks are also available:
910 - ``-fsanitize=alignment``: Use of a misaligned pointer or creation
911 of a misaligned reference.
912 - ``-fsanitize=bool``: Load of a ``bool`` value which is neither
913 ``true`` nor ``false``.
914 - ``-fsanitize=bounds``: Out of bounds array indexing, in cases
915 where the array bound can be statically determined.
916 - ``-fsanitize=enum``: Load of a value of an enumerated type which
917 is not in the range of representable values for that enumerated
919 - ``-fsanitize=float-cast-overflow``: Conversion to, from, or
920 between floating-point types which would overflow the
922 - ``-fsanitize=float-divide-by-zero``: Floating point division by
924 - ``-fsanitize=function``: Indirect call of a function through a
925 function pointer of the wrong type (Linux, C++ and x86/x86_64 only).
926 - ``-fsanitize=integer-divide-by-zero``: Integer division by zero.
927 - ``-fsanitize=null``: Use of a null pointer or creation of a null
929 - ``-fsanitize=object-size``: An attempt to use bytes which the
930 optimizer can determine are not part of the object being
931 accessed. The sizes of objects are determined using
932 ``__builtin_object_size``, and consequently may be able to detect
933 more problems at higher optimization levels.
934 - ``-fsanitize=return``: In C++, reaching the end of a
935 value-returning function without returning a value.
936 - ``-fsanitize=shift``: Shift operators where the amount shifted is
937 greater or equal to the promoted bit-width of the left hand side
938 or less than zero, or where the left hand side is negative. For a
939 signed left shift, also checks for signed overflow in C, and for
940 unsigned overflow in C++.
941 - ``-fsanitize=signed-integer-overflow``: Signed integer overflow,
942 including all the checks added by ``-ftrapv``, and checking for
943 overflow in signed division (``INT_MIN / -1``).
944 - ``-fsanitize=unreachable``: If control flow reaches
945 ``__builtin_unreachable``.
946 - ``-fsanitize=unsigned-integer-overflow``: Unsigned integer
948 - ``-fsanitize=vla-bound``: A variable-length array whose bound
949 does not evaluate to a positive value.
950 - ``-fsanitize=vptr``: Use of an object whose vptr indicates that
951 it is of the wrong dynamic type, or that its lifetime has not
952 begun or has ended. Incompatible with ``-fno-rtti``.
954 You can turn off or modify checks for certain source files, functions
955 or even variables by providing a special file:
957 - ``-fsanitize-blacklist=/path/to/blacklist/file``: disable or modify
958 sanitizer checks for objects listed in the file. See
959 :doc:`SanitizerSpecialCaseList` for file format description.
960 - ``-fno-sanitize-blacklist``: don't use blacklist file, if it was
961 specified earlier in the command line.
963 Experimental features of AddressSanitizer (not ready for widespread
964 use, require explicit ``-fsanitize=address``):
966 - ``-fsanitize=use-after-return``: Check for use-after-return
967 errors (accessing local variable after the function exit).
968 - ``-fsanitize=use-after-scope``: Check for use-after-scope errors
969 (accesing local variable after it went out of scope).
971 Extra features of MemorySanitizer (require explicit
972 ``-fsanitize=memory``):
974 - ``-fsanitize-memory-track-origins``: Enables origin tracking in
975 MemorySanitizer. Adds a second section to MemorySanitizer
976 reports pointing to the heap or stack allocation the
977 uninitialized bits came from. Slows down execution by additional
980 Extra features of UndefinedBehaviorSanitizer:
982 - ``-fno-sanitize-recover``: By default, after a sanitizer diagnoses
983 an issue, it will attempt to continue executing the program if there
984 is a reasonable behavior it can give to the faulting operation. This
985 option causes the program to abort instead.
986 - ``-fsanitize-undefined-trap-on-error``: Causes traps to be emitted
987 rather than calls to runtime libraries when a problem is detected.
988 This option is intended for use in cases where the sanitizer runtime
989 cannot be used (for instance, when building libc or a kernel module).
990 This is only compatible with the sanitizers in the ``undefined-trap``
993 The ``-fsanitize=`` argument must also be provided when linking, in
994 order to link to the appropriate runtime library. When using
995 ``-fsanitize=vptr`` (or a group that includes it, such as
996 ``-fsanitize=undefined``) with a C++ program, the link must be
997 performed by ``clang++``, not ``clang``, in order to link against the
998 C++-specific parts of the runtime library.
1000 It is not possible to combine more than one of the ``-fsanitize=address``,
1001 ``-fsanitize=thread``, and ``-fsanitize=memory`` checkers in the same
1002 program. The ``-fsanitize=undefined`` checks can be combined with other
1005 **-f[no-]address-sanitizer**
1006 Deprecated synonym for :ref:`-f[no-]sanitize=address
1007 <opt_fsanitize_address>`.
1008 **-f[no-]thread-sanitizer**
1009 Deprecated synonym for :ref:`-f[no-]sanitize=thread
1010 <opt_fsanitize_thread>`.
1012 .. option:: -fcatch-undefined-behavior
1014 Deprecated synonym for :ref:`-fsanitize=undefined
1015 <opt_fsanitize_undefined>`.
1017 .. option:: -fno-assume-sane-operator-new
1019 Don't assume that the C++'s new operator is sane.
1021 This option tells the compiler to do not assume that C++'s global
1022 new operator will always return a pointer that does not alias any
1023 other pointer when the function returns.
1025 .. option:: -ftrap-function=[name]
1027 Instruct code generator to emit a function call to the specified
1028 function name for ``__builtin_trap()``.
1030 LLVM code generator translates ``__builtin_trap()`` to a trap
1031 instruction if it is supported by the target ISA. Otherwise, the
1032 builtin is translated into a call to ``abort``. If this option is
1033 set, then the code generator will always lower the builtin to a call
1034 to the specified function regardless of whether the target ISA has a
1035 trap instruction. This option is useful for environments (e.g.
1036 deeply embedded) where a trap cannot be properly handled, or when
1037 some custom behavior is desired.
1039 .. option:: -ftls-model=[model]
1041 Select which TLS model to use.
1043 Valid values are: ``global-dynamic``, ``local-dynamic``,
1044 ``initial-exec`` and ``local-exec``. The default value is
1045 ``global-dynamic``. The compiler may use a different model if the
1046 selected model is not supported by the target, or if a more
1047 efficient model can be used. The TLS model can be overridden per
1048 variable using the ``tls_model`` attribute.
1050 .. option:: -mhwdiv=[values]
1052 Select the ARM modes (arm or thumb) that support hardware division
1055 Valid values are: ``arm``, ``thumb`` and ``arm,thumb``.
1056 This option is used to indicate which mode (arm or thumb) supports
1057 hardware division instructions. This only applies to the ARM
1060 .. option:: -m[no-]crc
1062 Enable or disable CRC instructions.
1064 This option is used to indicate whether CRC instructions are to
1065 be generated. This only applies to the ARM architecture.
1067 CRC instructions are enabled by default on ARMv8.
1070 Controlling Size of Debug Information
1071 -------------------------------------
1073 Debug info kind generated by Clang can be set by one of the flags listed
1074 below. If multiple flags are present, the last one is used.
1078 Don't generate any debug info (default).
1080 .. option:: -gline-tables-only
1082 Generate line number tables only.
1084 This kind of debug info allows to obtain stack traces with function names,
1085 file names and line numbers (by such tools as ``gdb`` or ``addr2line``). It
1086 doesn't contain any other data (e.g. description of local variables or
1087 function parameters).
1091 Generate complete debug info.
1093 Comment Parsing Options
1094 --------------------------
1096 Clang parses Doxygen and non-Doxygen style documentation comments and attaches
1097 them to the appropriate declaration nodes. By default, it only parses
1098 Doxygen-style comments and ignores ordinary comments starting with ``//`` and
1101 .. option:: -fparse-all-comments
1103 Parse all comments as documentation comments (including ordinary comments
1104 starting with ``//`` and ``/*``).
1111 The support for standard C in clang is feature-complete except for the
1112 C99 floating-point pragmas.
1114 Extensions supported by clang
1115 -----------------------------
1117 See :doc:`LanguageExtensions`.
1119 Differences between various standard modes
1120 ------------------------------------------
1122 clang supports the -std option, which changes what language mode clang
1123 uses. The supported modes for C are c89, gnu89, c94, c99, gnu99 and
1124 various aliases for those modes. If no -std option is specified, clang
1125 defaults to gnu99 mode.
1127 Differences between all ``c*`` and ``gnu*`` modes:
1129 - ``c*`` modes define "``__STRICT_ANSI__``".
1130 - Target-specific defines not prefixed by underscores, like "linux",
1131 are defined in ``gnu*`` modes.
1132 - Trigraphs default to being off in ``gnu*`` modes; they can be enabled by
1133 the -trigraphs option.
1134 - The parser recognizes "asm" and "typeof" as keywords in ``gnu*`` modes;
1135 the variants "``__asm__``" and "``__typeof__``" are recognized in all
1137 - The Apple "blocks" extension is recognized by default in ``gnu*`` modes
1138 on some platforms; it can be enabled in any mode with the "-fblocks"
1140 - Arrays that are VLA's according to the standard, but which can be
1141 constant folded by the frontend are treated as fixed size arrays.
1142 This occurs for things like "int X[(1, 2)];", which is technically a
1143 VLA. ``c*`` modes are strictly compliant and treat these as VLAs.
1145 Differences between ``*89`` and ``*99`` modes:
1147 - The ``*99`` modes default to implementing "inline" as specified in C99,
1148 while the ``*89`` modes implement the GNU version. This can be
1149 overridden for individual functions with the ``__gnu_inline__``
1151 - Digraphs are not recognized in c89 mode.
1152 - The scope of names defined inside a "for", "if", "switch", "while",
1153 or "do" statement is different. (example: "``if ((struct x {int
1155 - ``__STDC_VERSION__`` is not defined in ``*89`` modes.
1156 - "inline" is not recognized as a keyword in c89 mode.
1157 - "restrict" is not recognized as a keyword in ``*89`` modes.
1158 - Commas are allowed in integer constant expressions in ``*99`` modes.
1159 - Arrays which are not lvalues are not implicitly promoted to pointers
1161 - Some warnings are different.
1163 c94 mode is identical to c89 mode except that digraphs are enabled in
1164 c94 mode (FIXME: And ``__STDC_VERSION__`` should be defined!).
1166 GCC extensions not implemented yet
1167 ----------------------------------
1169 clang tries to be compatible with gcc as much as possible, but some gcc
1170 extensions are not implemented yet:
1172 - clang does not support #pragma weak (`bug
1173 3679 <http://llvm.org/bugs/show_bug.cgi?id=3679>`_). Due to the uses
1174 described in the bug, this is likely to be implemented at some point,
1176 - clang does not support decimal floating point types (``_Decimal32`` and
1177 friends) or fixed-point types (``_Fract`` and friends); nobody has
1178 expressed interest in these features yet, so it's hard to say when
1179 they will be implemented.
1180 - clang does not support nested functions; this is a complex feature
1181 which is infrequently used, so it is unlikely to be implemented
1182 anytime soon. In C++11 it can be emulated by assigning lambda
1183 functions to local variables, e.g:
1187 auto const local_function = [&](int parameter) {
1193 - clang does not support global register variables; this is unlikely to
1194 be implemented soon because it requires additional LLVM backend
1196 - clang does not support static initialization of flexible array
1197 members. This appears to be a rarely used extension, but could be
1198 implemented pending user demand.
1199 - clang does not support
1200 ``__builtin_va_arg_pack``/``__builtin_va_arg_pack_len``. This is
1201 used rarely, but in some potentially interesting places, like the
1202 glibc headers, so it may be implemented pending user demand. Note
1203 that because clang pretends to be like GCC 4.2, and this extension
1204 was introduced in 4.3, the glibc headers will not try to use this
1205 extension with clang at the moment.
1206 - clang does not support the gcc extension for forward-declaring
1207 function parameters; this has not shown up in any real-world code
1208 yet, though, so it might never be implemented.
1210 This is not a complete list; if you find an unsupported extension
1211 missing from this list, please send an e-mail to cfe-dev. This list
1212 currently excludes C++; see :ref:`C++ Language Features <cxx>`. Also, this
1213 list does not include bugs in mostly-implemented features; please see
1215 tracker <http://llvm.org/bugs/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer>`_
1216 for known existing bugs (FIXME: Is there a section for bug-reporting
1217 guidelines somewhere?).
1219 Intentionally unsupported GCC extensions
1220 ----------------------------------------
1222 - clang does not support the gcc extension that allows variable-length
1223 arrays in structures. This is for a few reasons: one, it is tricky to
1224 implement, two, the extension is completely undocumented, and three,
1225 the extension appears to be rarely used. Note that clang *does*
1226 support flexible array members (arrays with a zero or unspecified
1227 size at the end of a structure).
1228 - clang does not have an equivalent to gcc's "fold"; this means that
1229 clang doesn't accept some constructs gcc might accept in contexts
1230 where a constant expression is required, like "x-x" where x is a
1232 - clang does not support ``__builtin_apply`` and friends; this extension
1233 is extremely obscure and difficult to implement reliably.
1237 Microsoft extensions
1238 --------------------
1240 clang has some experimental support for extensions from Microsoft Visual
1241 C++; to enable it, use the ``-fms-extensions`` command-line option. This is
1242 the default for Windows targets. Note that the support is incomplete.
1243 Some constructs such as ``dllexport`` on classes are ignored with a warning,
1244 and others such as `Microsoft IDL annotations
1245 <http://msdn.microsoft.com/en-us/library/8tesw2eh.aspx>`_ are silently
1248 clang has a ``-fms-compatibility`` flag that makes clang accept enough
1249 invalid C++ to be able to parse most Microsoft headers. For example, it
1250 allows `unqualified lookup of dependent base class members
1251 <http://clang.llvm.org/compatibility.html#dep_lookup_bases>`_, which is
1252 a common compatibility issue with clang. This flag is enabled by default
1253 for Windows targets.
1255 ``-fdelayed-template-parsing`` lets clang delay parsing of function template
1256 definitions until the end of a translation unit. This flag is enabled by
1257 default for Windows targets.
1259 - clang allows setting ``_MSC_VER`` with ``-fmsc-version=``. It defaults to
1260 1700 which is the same as Visual C/C++ 2012. Any number is supported
1261 and can greatly affect what Windows SDK and c++stdlib headers clang
1263 - clang does not support the Microsoft extension where anonymous record
1264 members can be declared using user defined typedefs.
1265 - clang supports the Microsoft ``#pragma pack`` feature for controlling
1266 record layout. GCC also contains support for this feature, however
1267 where MSVC and GCC are incompatible clang follows the MSVC
1269 - clang supports the Microsoft ``#pragma comment(lib, "foo.lib")`` feature for
1270 automatically linking against the specified library. Currently this feature
1271 only works with the Visual C++ linker.
1272 - clang supports the Microsoft ``#pragma comment(linker, "/flag:foo")`` feature
1273 for adding linker flags to COFF object files. The user is responsible for
1274 ensuring that the linker understands the flags.
1275 - clang defaults to C++11 for Windows targets.
1279 C++ Language Features
1280 =====================
1282 clang fully implements all of standard C++98 except for exported
1283 templates (which were removed in C++11), and all of standard C++11
1284 and the current draft standard for C++1y.
1286 Controlling implementation limits
1287 ---------------------------------
1289 .. option:: -fbracket-depth=N
1291 Sets the limit for nested parentheses, brackets, and braces to N. The
1294 .. option:: -fconstexpr-depth=N
1296 Sets the limit for recursive constexpr function invocations to N. The
1299 .. option:: -ftemplate-depth=N
1301 Sets the limit for recursively nested template instantiations to N. The
1304 .. option:: -foperator-arrow-depth=N
1306 Sets the limit for iterative calls to 'operator->' functions to N. The
1311 Objective-C Language Features
1312 =============================
1316 Objective-C++ Language Features
1317 ===============================
1320 .. _target_features:
1322 Target-Specific Features and Limitations
1323 ========================================
1325 CPU Architectures Features and Limitations
1326 ------------------------------------------
1331 The support for X86 (both 32-bit and 64-bit) is considered stable on
1332 Darwin (Mac OS/X), Linux, FreeBSD, and Dragonfly BSD: it has been tested
1333 to correctly compile many large C, C++, Objective-C, and Objective-C++
1336 On ``x86_64-mingw32``, passing i128(by value) is incompatible with the
1337 Microsoft x64 calling conversion. You might need to tweak
1338 ``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp.
1343 The support for ARM (specifically ARMv6 and ARMv7) is considered stable
1344 on Darwin (iOS): it has been tested to correctly compile many large C,
1345 C++, Objective-C, and Objective-C++ codebases. Clang only supports a
1346 limited number of ARM architectures. It does not yet fully support
1352 The support for PowerPC (especially PowerPC64) is considered stable
1353 on Linux and FreeBSD: it has been tested to correctly compile many
1354 large C and C++ codebases. PowerPC (32bit) is still missing certain
1355 features (e.g. PIC code on ELF platforms).
1360 clang currently contains some support for other architectures (e.g. Sparc);
1361 however, significant pieces of code generation are still missing, and they
1362 haven't undergone significant testing.
1364 clang contains limited support for the MSP430 embedded processor, but
1365 both the clang support and the LLVM backend support are highly
1368 Other platforms are completely unsupported at the moment. Adding the
1369 minimal support needed for parsing and semantic analysis on a new
1370 platform is quite easy; see ``lib/Basic/Targets.cpp`` in the clang source
1371 tree. This level of support is also sufficient for conversion to LLVM IR
1372 for simple programs. Proper support for conversion to LLVM IR requires
1373 adding code to ``lib/CodeGen/CGCall.cpp`` at the moment; this is likely to
1374 change soon, though. Generating assembly requires a suitable LLVM
1377 Operating System Features and Limitations
1378 -----------------------------------------
1388 Clang has experimental support for targeting "Cygming" (Cygwin / MinGW)
1391 See also :ref:`Microsoft Extensions <c_ms>`.
1396 Clang works on Cygwin-1.7.
1401 Clang works on some mingw32 distributions. Clang assumes directories as
1404 - ``C:/mingw/include``
1406 - ``C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++``
1408 On MSYS, a few tests might fail.
1413 For 32-bit (i686-w64-mingw32), and 64-bit (x86\_64-w64-mingw32), Clang
1416 - ``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)``
1417 - ``some_directory/bin/gcc.exe``
1418 - ``some_directory/bin/clang.exe``
1419 - ``some_directory/bin/clang++.exe``
1420 - ``some_directory/bin/../include/c++/GCC_version``
1421 - ``some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32``
1422 - ``some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32``
1423 - ``some_directory/bin/../include/c++/GCC_version/backward``
1424 - ``some_directory/bin/../x86_64-w64-mingw32/include``
1425 - ``some_directory/bin/../i686-w64-mingw32/include``
1426 - ``some_directory/bin/../include``
1428 This directory layout is standard for any toolchain you will find on the
1429 official `MinGW-w64 website <http://mingw-w64.sourceforge.net>`_.
1431 Clang expects the GCC executable "gcc.exe" compiled for
1432 ``i686-w64-mingw32`` (or ``x86_64-w64-mingw32``) to be present on PATH.
1434 `Some tests might fail <http://llvm.org/bugs/show_bug.cgi?id=9072>`_ on
1435 ``x86_64-w64-mingw32``.
1442 clang-cl is an alternative command-line interface to Clang driver, designed for
1443 compatibility with the Visual C++ compiler, cl.exe.
1445 To enable clang-cl to find system headers, libraries, and the linker when run
1446 from the command-line, it should be executed inside a Visual Studio Native Tools
1447 Command Prompt or a regular Command Prompt where the environment has been set
1448 up using e.g. `vcvars32.bat <http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_.
1450 clang-cl can also be used from inside Visual Studio by using an LLVM Platform
1453 Command-Line Options
1454 --------------------
1456 To be compatible with cl.exe, clang-cl supports most of the same command-line
1457 options. Those options can start with either ``/`` or ``-``. It also supports
1458 some of Clang's core options, such as the ``-W`` options.
1460 Options that are known to clang-cl, but not currently supported, are ignored
1461 with a warning. For example:
1465 clang-cl.exe: warning: argument unused during compilation: '/Zi'
1467 To suppress warnings about unused arguments, use the ``-Qunused-arguments`` option.
1469 Options that are not known to clang-cl will cause errors. If they are spelled with a
1470 leading ``/``, they will be mistaken for a filename:
1474 clang-cl.exe: error: no such file or directory: '/foobar'
1476 Please `file a bug <http://llvm.org/bugs/enter_bug.cgi?product=clang&component=Driver>`_
1477 for any valid cl.exe flags that clang-cl does not understand.
1479 Execute ``clang-cl /?`` to see a list of supported options:
1483 /? Display available options
1485 /D <macro[=value]> Define macro
1486 /fallback Fall back to cl.exe if clang-cl fails to compile
1487 /FA Output assembly code file during compilation
1488 /Fa<file or directory> Output assembly code to this file during compilation
1489 /Fe<file or directory> Set output executable file or directory (ends in / or \)
1490 /FI<value> Include file before parsing
1491 /Fo<file or directory> Set output object file, or directory (ends in / or \)
1492 /GF- Disable string pooling
1495 /help Display available options
1496 /I <dir> Add directory to include search path
1497 /J Make char type unsigned
1498 /LDd Create debug DLL
1500 /link <options> Forward options to the linker
1501 /MDd Use DLL debug run-time
1502 /MD Use DLL run-time
1503 /MTd Use static debug run-time
1504 /MT Use static run-time
1505 /Ob0 Disable inlining
1506 /Od Disable optimization
1507 /Oi- Disable use of builtin functions
1508 /Oi Enable use of builtin functions
1509 /Os Optimize for size
1510 /Ot Optimize for speed
1511 /Ox Maximum optimization
1512 /Oy- Disable frame pointer omission
1513 /Oy Enable frame pointer omission
1514 /O<n> Optimization level
1515 /P Only run the preprocessor
1516 /showIncludes Print info about included files to stderr
1517 /TC Treat all source files as C
1518 /Tc <filename> Specify a C source file
1519 /TP Treat all source files as C++
1520 /Tp <filename> Specify a C++ source file
1521 /U <macro> Undefine macro
1522 /W0 Disable all warnings
1528 /WX- Do not treat warnings as errors
1529 /WX Treat warnings as errors
1530 /w Disable all warnings
1531 /Zs Syntax-check only
1533 The /fallback Option
1534 ^^^^^^^^^^^^^^^^^^^^
1536 When clang-cl is run with the ``/fallback`` option, it will first try to
1537 compile files itself. For any file that it fails to compile, it will fall back
1538 and try to compile the file by invoking cl.exe.
1540 This option is intended to be used as a temporary means to build projects where
1541 clang-cl cannot successfully compile all the files. clang-cl may fail to compile
1542 a file either because it cannot generate code for some C++ feature, or because
1543 it cannot parse some Microsoft language extension.