forked from OSchip/llvm-project
1574 lines
58 KiB
ReStructuredText
1574 lines
58 KiB
ReStructuredText
============================
|
|
Clang Compiler User's Manual
|
|
============================
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
Introduction
|
|
============
|
|
|
|
The Clang Compiler is an open-source compiler for the C family of
|
|
programming languages, aiming to be the best in class implementation of
|
|
these languages. Clang builds on the LLVM optimizer and code generator,
|
|
allowing it to provide high-quality optimization and code generation
|
|
support for many targets. For more general information, please see the
|
|
`Clang Web Site <http://clang.llvm.org>`_ or the `LLVM Web
|
|
Site <http://llvm.org>`_.
|
|
|
|
This document describes important notes about using Clang as a compiler
|
|
for an end-user, documenting the supported features, command line
|
|
options, etc. If you are interested in using Clang to build a tool that
|
|
processes code, please see :doc:`InternalsManual`. If you are interested in the
|
|
`Clang Static Analyzer <http://clang-analyzer.llvm.org>`_, please see its web
|
|
page.
|
|
|
|
Clang is designed to support the C family of programming languages,
|
|
which includes :ref:`C <c>`, :ref:`Objective-C <objc>`, :ref:`C++ <cxx>`, and
|
|
:ref:`Objective-C++ <objcxx>` as well as many dialects of those. For
|
|
language-specific information, please see the corresponding language
|
|
specific section:
|
|
|
|
- :ref:`C Language <c>`: K&R C, ANSI C89, ISO C90, ISO C94 (C89+AMD1), ISO
|
|
C99 (+TC1, TC2, TC3).
|
|
- :ref:`Objective-C Language <objc>`: ObjC 1, ObjC 2, ObjC 2.1, plus
|
|
variants depending on base language.
|
|
- :ref:`C++ Language <cxx>`
|
|
- :ref:`Objective C++ Language <objcxx>`
|
|
|
|
In addition to these base languages and their dialects, Clang supports a
|
|
broad variety of language extensions, which are documented in the
|
|
corresponding language section. These extensions are provided to be
|
|
compatible with the GCC, Microsoft, and other popular compilers as well
|
|
as to improve functionality through Clang-specific features. The Clang
|
|
driver and language features are intentionally designed to be as
|
|
compatible with the GNU GCC compiler as reasonably possible, easing
|
|
migration from GCC to Clang. In most cases, code "just works".
|
|
Clang also provides an alternative driver, :ref:`clang-cl`, that is designed
|
|
to be compatible with the Visual C++ compiler, cl.exe.
|
|
|
|
In addition to language specific features, Clang has a variety of
|
|
features that depend on what CPU architecture or operating system is
|
|
being compiled for. Please see the :ref:`Target-Specific Features and
|
|
Limitations <target_features>` section for more details.
|
|
|
|
The rest of the introduction introduces some basic :ref:`compiler
|
|
terminology <terminology>` that is used throughout this manual and
|
|
contains a basic :ref:`introduction to using Clang <basicusage>` as a
|
|
command line compiler.
|
|
|
|
.. _terminology:
|
|
|
|
Terminology
|
|
-----------
|
|
|
|
Front end, parser, backend, preprocessor, undefined behavior,
|
|
diagnostic, optimizer
|
|
|
|
.. _basicusage:
|
|
|
|
Basic Usage
|
|
-----------
|
|
|
|
Intro to how to use a C compiler for newbies.
|
|
|
|
compile + link compile then link debug info enabling optimizations
|
|
picking a language to use, defaults to C99 by default. Autosenses based
|
|
on extension. using a makefile
|
|
|
|
Command Line Options
|
|
====================
|
|
|
|
This section is generally an index into other sections. It does not go
|
|
into depth on the ones that are covered by other sections. However, the
|
|
first part introduces the language selection and other high level
|
|
options like :option:`-c`, :option:`-g`, etc.
|
|
|
|
Options to Control Error and Warning Messages
|
|
---------------------------------------------
|
|
|
|
.. option:: -Werror
|
|
|
|
Turn warnings into errors.
|
|
|
|
.. This is in plain monospaced font because it generates the same label as
|
|
.. -Werror, and Sphinx complains.
|
|
|
|
``-Werror=foo``
|
|
|
|
Turn warning "foo" into an error.
|
|
|
|
.. option:: -Wno-error=foo
|
|
|
|
Turn warning "foo" into an warning even if :option:`-Werror` is specified.
|
|
|
|
.. option:: -Wfoo
|
|
|
|
Enable warning "foo".
|
|
|
|
.. option:: -Wno-foo
|
|
|
|
Disable warning "foo".
|
|
|
|
.. option:: -w
|
|
|
|
Disable all diagnostics.
|
|
|
|
.. option:: -Weverything
|
|
|
|
:ref:`Enable all diagnostics. <diagnostics_enable_everything>`
|
|
|
|
.. option:: -pedantic
|
|
|
|
Warn on language extensions.
|
|
|
|
.. option:: -pedantic-errors
|
|
|
|
Error on language extensions.
|
|
|
|
.. option:: -Wsystem-headers
|
|
|
|
Enable warnings from system headers.
|
|
|
|
.. option:: -ferror-limit=123
|
|
|
|
Stop emitting diagnostics after 123 errors have been produced. The default is
|
|
20, and the error limit can be disabled with :option:`-ferror-limit=0`.
|
|
|
|
.. option:: -ftemplate-backtrace-limit=123
|
|
|
|
Only emit up to 123 template instantiation notes within the template
|
|
instantiation backtrace for a single warning or error. The default is 10, and
|
|
the limit can be disabled with :option:`-ftemplate-backtrace-limit=0`.
|
|
|
|
.. _cl_diag_formatting:
|
|
|
|
Formatting of Diagnostics
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Clang aims to produce beautiful diagnostics by default, particularly for
|
|
new users that first come to Clang. However, different people have
|
|
different preferences, and sometimes Clang is driven by another program
|
|
that wants to parse simple and consistent output, not a person. For
|
|
these cases, Clang provides a wide range of options to control the exact
|
|
output format of the diagnostics that it generates.
|
|
|
|
.. _opt_fshow-column:
|
|
|
|
**-f[no-]show-column**
|
|
Print column number in diagnostic.
|
|
|
|
This option, which defaults to on, controls whether or not Clang
|
|
prints the column number of a diagnostic. For example, when this is
|
|
enabled, Clang will print something like:
|
|
|
|
::
|
|
|
|
test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
|
|
#endif bad
|
|
^
|
|
//
|
|
|
|
When this is disabled, Clang will print "test.c:28: warning..." with
|
|
no column number.
|
|
|
|
The printed column numbers count bytes from the beginning of the
|
|
line; take care if your source contains multibyte characters.
|
|
|
|
.. _opt_fshow-source-location:
|
|
|
|
**-f[no-]show-source-location**
|
|
Print source file/line/column information in diagnostic.
|
|
|
|
This option, which defaults to on, controls whether or not Clang
|
|
prints the filename, line number and column number of a diagnostic.
|
|
For example, when this is enabled, Clang will print something like:
|
|
|
|
::
|
|
|
|
test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
|
|
#endif bad
|
|
^
|
|
//
|
|
|
|
When this is disabled, Clang will not print the "test.c:28:8: "
|
|
part.
|
|
|
|
.. _opt_fcaret-diagnostics:
|
|
|
|
**-f[no-]caret-diagnostics**
|
|
Print source line and ranges from source code in diagnostic.
|
|
This option, which defaults to on, controls whether or not Clang
|
|
prints the source line, source ranges, and caret when emitting a
|
|
diagnostic. For example, when this is enabled, Clang will print
|
|
something like:
|
|
|
|
::
|
|
|
|
test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
|
|
#endif bad
|
|
^
|
|
//
|
|
|
|
**-f[no-]color-diagnostics**
|
|
This option, which defaults to on when a color-capable terminal is
|
|
detected, controls whether or not Clang prints diagnostics in color.
|
|
|
|
When this option is enabled, Clang will use colors to highlight
|
|
specific parts of the diagnostic, e.g.,
|
|
|
|
.. nasty hack to not lose our dignity
|
|
|
|
.. raw:: html
|
|
|
|
<pre>
|
|
<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>
|
|
#endif bad
|
|
<span style="color:green">^</span>
|
|
<span style="color:green">//</span>
|
|
</pre>
|
|
|
|
When this is disabled, Clang will just print:
|
|
|
|
::
|
|
|
|
test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
|
|
#endif bad
|
|
^
|
|
//
|
|
|
|
**-fansi-escape-codes**
|
|
Controls whether ANSI escape codes are used instead of the Windows Console
|
|
API to output colored diagnostics. This option is only used on Windows and
|
|
defaults to off.
|
|
|
|
.. option:: -fdiagnostics-format=clang/msvc/vi
|
|
|
|
Changes diagnostic output format to better match IDEs and command line tools.
|
|
|
|
This option controls the output format of the filename, line number,
|
|
and column printed in diagnostic messages. The options, and their
|
|
affect on formatting a simple conversion diagnostic, follow:
|
|
|
|
**clang** (default)
|
|
::
|
|
|
|
t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
|
|
|
|
**msvc**
|
|
::
|
|
|
|
t.c(3,11) : warning: conversion specifies type 'char *' but the argument has type 'int'
|
|
|
|
**vi**
|
|
::
|
|
|
|
t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
|
|
|
|
.. _opt_fdiagnostics-show-option:
|
|
|
|
**-f[no-]diagnostics-show-option**
|
|
Enable ``[-Woption]`` information in diagnostic line.
|
|
|
|
This option, which defaults to on, controls whether or not Clang
|
|
prints the associated :ref:`warning group <cl_diag_warning_groups>`
|
|
option name when outputting a warning diagnostic. For example, in
|
|
this output:
|
|
|
|
::
|
|
|
|
test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
|
|
#endif bad
|
|
^
|
|
//
|
|
|
|
Passing **-fno-diagnostics-show-option** will prevent Clang from
|
|
printing the [:ref:`-Wextra-tokens <opt_Wextra-tokens>`] information in
|
|
the diagnostic. This information tells you the flag needed to enable
|
|
or disable the diagnostic, either from the command line or through
|
|
:ref:`#pragma GCC diagnostic <pragma_GCC_diagnostic>`.
|
|
|
|
.. _opt_fdiagnostics-show-category:
|
|
|
|
.. option:: -fdiagnostics-show-category=none/id/name
|
|
|
|
Enable printing category information in diagnostic line.
|
|
|
|
This option, which defaults to "none", controls whether or not Clang
|
|
prints the category associated with a diagnostic when emitting it.
|
|
Each diagnostic may or many not have an associated category, if it
|
|
has one, it is listed in the diagnostic categorization field of the
|
|
diagnostic line (in the []'s).
|
|
|
|
For example, a format string warning will produce these three
|
|
renditions based on the setting of this option:
|
|
|
|
::
|
|
|
|
t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat]
|
|
t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1]
|
|
t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String]
|
|
|
|
This category can be used by clients that want to group diagnostics
|
|
by category, so it should be a high level category. We want dozens
|
|
of these, not hundreds or thousands of them.
|
|
|
|
.. _opt_fdiagnostics-fixit-info:
|
|
|
|
**-f[no-]diagnostics-fixit-info**
|
|
Enable "FixIt" information in the diagnostics output.
|
|
|
|
This option, which defaults to on, controls whether or not Clang
|
|
prints the information on how to fix a specific diagnostic
|
|
underneath it when it knows. For example, in this output:
|
|
|
|
::
|
|
|
|
test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
|
|
#endif bad
|
|
^
|
|
//
|
|
|
|
Passing **-fno-diagnostics-fixit-info** will prevent Clang from
|
|
printing the "//" line at the end of the message. This information
|
|
is useful for users who may not understand what is wrong, but can be
|
|
confusing for machine parsing.
|
|
|
|
.. _opt_fdiagnostics-print-source-range-info:
|
|
|
|
**-fdiagnostics-print-source-range-info**
|
|
Print machine parsable information about source ranges.
|
|
This option makes Clang print information about source ranges in a machine
|
|
parsable format after the file/line/column number information. The
|
|
information is a simple sequence of brace enclosed ranges, where each range
|
|
lists the start and end line/column locations. For example, in this output:
|
|
|
|
::
|
|
|
|
exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float')
|
|
P = (P-42) + Gamma*4;
|
|
~~~~~~ ^ ~~~~~~~
|
|
|
|
The {}'s are generated by -fdiagnostics-print-source-range-info.
|
|
|
|
The printed column numbers count bytes from the beginning of the
|
|
line; take care if your source contains multibyte characters.
|
|
|
|
.. option:: -fdiagnostics-parseable-fixits
|
|
|
|
Print Fix-Its in a machine parseable form.
|
|
|
|
This option makes Clang print available Fix-Its in a machine
|
|
parseable format at the end of diagnostics. The following example
|
|
illustrates the format:
|
|
|
|
::
|
|
|
|
fix-it:"t.cpp":{7:25-7:29}:"Gamma"
|
|
|
|
The range printed is a half-open range, so in this example the
|
|
characters at column 25 up to but not including column 29 on line 7
|
|
in t.cpp should be replaced with the string "Gamma". Either the
|
|
range or the replacement string may be empty (representing strict
|
|
insertions and strict erasures, respectively). Both the file name
|
|
and the insertion string escape backslash (as "\\\\"), tabs (as
|
|
"\\t"), newlines (as "\\n"), double quotes(as "\\"") and
|
|
non-printable characters (as octal "\\xxx").
|
|
|
|
The printed column numbers count bytes from the beginning of the
|
|
line; take care if your source contains multibyte characters.
|
|
|
|
.. option:: -fno-elide-type
|
|
|
|
Turns off elision in template type printing.
|
|
|
|
The default for template type printing is to elide as many template
|
|
arguments as possible, removing those which are the same in both
|
|
template types, leaving only the differences. Adding this flag will
|
|
print all the template arguments. If supported by the terminal,
|
|
highlighting will still appear on differing arguments.
|
|
|
|
Default:
|
|
|
|
::
|
|
|
|
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;
|
|
|
|
-fno-elide-type:
|
|
|
|
::
|
|
|
|
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;
|
|
|
|
.. option:: -fdiagnostics-show-template-tree
|
|
|
|
Template type diffing prints a text tree.
|
|
|
|
For diffing large templated types, this option will cause Clang to
|
|
display the templates as an indented text tree, one argument per
|
|
line, with differences marked inline. This is compatible with
|
|
-fno-elide-type.
|
|
|
|
Default:
|
|
|
|
::
|
|
|
|
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;
|
|
|
|
With :option:`-fdiagnostics-show-template-tree`:
|
|
|
|
::
|
|
|
|
t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument;
|
|
vector<
|
|
map<
|
|
[...],
|
|
map<
|
|
[float != double],
|
|
[...]>>>
|
|
|
|
.. _cl_diag_warning_groups:
|
|
|
|
Individual Warning Groups
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
TODO: Generate this from tblgen. Define one anchor per warning group.
|
|
|
|
.. _opt_wextra-tokens:
|
|
|
|
.. option:: -Wextra-tokens
|
|
|
|
Warn about excess tokens at the end of a preprocessor directive.
|
|
|
|
This option, which defaults to on, enables warnings about extra
|
|
tokens at the end of preprocessor directives. For example:
|
|
|
|
::
|
|
|
|
test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
|
|
#endif bad
|
|
^
|
|
|
|
These extra tokens are not strictly conforming, and are usually best
|
|
handled by commenting them out.
|
|
|
|
.. option:: -Wambiguous-member-template
|
|
|
|
Warn about unqualified uses of a member template whose name resolves to
|
|
another template at the location of the use.
|
|
|
|
This option, which defaults to on, enables a warning in the
|
|
following code:
|
|
|
|
::
|
|
|
|
template<typename T> struct set{};
|
|
template<typename T> struct trait { typedef const T& type; };
|
|
struct Value {
|
|
template<typename T> void set(typename trait<T>::type value) {}
|
|
};
|
|
void foo() {
|
|
Value v;
|
|
v.set<double>(3.2);
|
|
}
|
|
|
|
C++ [basic.lookup.classref] requires this to be an error, but,
|
|
because it's hard to work around, Clang downgrades it to a warning
|
|
as an extension.
|
|
|
|
.. option:: -Wbind-to-temporary-copy
|
|
|
|
Warn about an unusable copy constructor when binding a reference to a
|
|
temporary.
|
|
|
|
This option, which defaults to on, enables warnings about binding a
|
|
reference to a temporary when the temporary doesn't have a usable
|
|
copy constructor. For example:
|
|
|
|
::
|
|
|
|
struct NonCopyable {
|
|
NonCopyable();
|
|
private:
|
|
NonCopyable(const NonCopyable&);
|
|
};
|
|
void foo(const NonCopyable&);
|
|
void bar() {
|
|
foo(NonCopyable()); // Disallowed in C++98; allowed in C++11.
|
|
}
|
|
|
|
::
|
|
|
|
struct NonCopyable2 {
|
|
NonCopyable2();
|
|
NonCopyable2(NonCopyable2&);
|
|
};
|
|
void foo(const NonCopyable2&);
|
|
void bar() {
|
|
foo(NonCopyable2()); // Disallowed in C++98; allowed in C++11.
|
|
}
|
|
|
|
Note that if ``NonCopyable2::NonCopyable2()`` has a default argument
|
|
whose instantiation produces a compile error, that error will still
|
|
be a hard error in C++98 mode even if this warning is turned off.
|
|
|
|
Options to Control Clang Crash Diagnostics
|
|
------------------------------------------
|
|
|
|
As unbelievable as it may sound, Clang does crash from time to time.
|
|
Generally, this only occurs to those living on the `bleeding
|
|
edge <http://llvm.org/releases/download.html#svn>`_. Clang goes to great
|
|
lengths to assist you in filing a bug report. Specifically, Clang
|
|
generates preprocessed source file(s) and associated run script(s) upon
|
|
a crash. These files should be attached to a bug report to ease
|
|
reproducibility of the failure. Below are the command line options to
|
|
control the crash diagnostics.
|
|
|
|
.. option:: -fno-crash-diagnostics
|
|
|
|
Disable auto-generation of preprocessed source files during a clang crash.
|
|
|
|
The -fno-crash-diagnostics flag can be helpful for speeding the process
|
|
of generating a delta reduced test case.
|
|
|
|
Language and Target-Independent Features
|
|
========================================
|
|
|
|
Controlling Errors and Warnings
|
|
-------------------------------
|
|
|
|
Clang provides a number of ways to control which code constructs cause
|
|
it to emit errors and warning messages, and how they are displayed to
|
|
the console.
|
|
|
|
Controlling How Clang Displays Diagnostics
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
When Clang emits a diagnostic, it includes rich information in the
|
|
output, and gives you fine-grain control over which information is
|
|
printed. Clang has the ability to print this information, and these are
|
|
the options that control it:
|
|
|
|
#. A file/line/column indicator that shows exactly where the diagnostic
|
|
occurs in your code [:ref:`-fshow-column <opt_fshow-column>`,
|
|
:ref:`-fshow-source-location <opt_fshow-source-location>`].
|
|
#. A categorization of the diagnostic as a note, warning, error, or
|
|
fatal error.
|
|
#. A text string that describes what the problem is.
|
|
#. An option that indicates how to control the diagnostic (for
|
|
diagnostics that support it)
|
|
[:ref:`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`].
|
|
#. A :ref:`high-level category <diagnostics_categories>` for the diagnostic
|
|
for clients that want to group diagnostics by class (for diagnostics
|
|
that support it)
|
|
[:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>`].
|
|
#. The line of source code that the issue occurs on, along with a caret
|
|
and ranges that indicate the important locations
|
|
[:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`].
|
|
#. "FixIt" information, which is a concise explanation of how to fix the
|
|
problem (when Clang is certain it knows)
|
|
[:ref:`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`].
|
|
#. A machine-parsable representation of the ranges involved (off by
|
|
default)
|
|
[:ref:`-fdiagnostics-print-source-range-info <opt_fdiagnostics-print-source-range-info>`].
|
|
|
|
For more information please see :ref:`Formatting of
|
|
Diagnostics <cl_diag_formatting>`.
|
|
|
|
Diagnostic Mappings
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
All diagnostics are mapped into one of these 5 classes:
|
|
|
|
- Ignored
|
|
- Note
|
|
- Remark
|
|
- Warning
|
|
- Error
|
|
- Fatal
|
|
|
|
.. _diagnostics_categories:
|
|
|
|
Diagnostic Categories
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Though not shown by default, diagnostics may each be associated with a
|
|
high-level category. This category is intended to make it possible to
|
|
triage builds that produce a large number of errors or warnings in a
|
|
grouped way.
|
|
|
|
Categories are not shown by default, but they can be turned on with the
|
|
:ref:`-fdiagnostics-show-category <opt_fdiagnostics-show-category>` option.
|
|
When set to "``name``", the category is printed textually in the
|
|
diagnostic output. When it is set to "``id``", a category number is
|
|
printed. The mapping of category names to category id's can be obtained
|
|
by running '``clang --print-diagnostic-categories``'.
|
|
|
|
Controlling Diagnostics via Command Line Flags
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
TODO: -W flags, -pedantic, etc
|
|
|
|
.. _pragma_gcc_diagnostic:
|
|
|
|
Controlling Diagnostics via Pragmas
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Clang can also control what diagnostics are enabled through the use of
|
|
pragmas in the source code. This is useful for turning off specific
|
|
warnings in a section of source code. Clang supports GCC's pragma for
|
|
compatibility with existing source code, as well as several extensions.
|
|
|
|
The pragma may control any warning that can be used from the command
|
|
line. Warnings may be set to ignored, warning, error, or fatal. The
|
|
following example code will tell Clang or GCC to ignore the -Wall
|
|
warnings:
|
|
|
|
.. code-block:: c
|
|
|
|
#pragma GCC diagnostic ignored "-Wall"
|
|
|
|
In addition to all of the functionality provided by GCC's pragma, Clang
|
|
also allows you to push and pop the current warning state. This is
|
|
particularly useful when writing a header file that will be compiled by
|
|
other people, because you don't know what warning flags they build with.
|
|
|
|
In the below example :option:`-Wmultichar` is ignored for only a single line of
|
|
code, after which the diagnostics return to whatever state had previously
|
|
existed.
|
|
|
|
.. code-block:: c
|
|
|
|
#pragma clang diagnostic push
|
|
#pragma clang diagnostic ignored "-Wmultichar"
|
|
|
|
char b = 'df'; // no warning.
|
|
|
|
#pragma clang diagnostic pop
|
|
|
|
The push and pop pragmas will save and restore the full diagnostic state
|
|
of the compiler, regardless of how it was set. That means that it is
|
|
possible to use push and pop around GCC compatible diagnostics and Clang
|
|
will push and pop them appropriately, while GCC will ignore the pushes
|
|
and pops as unknown pragmas. It should be noted that while Clang
|
|
supports the GCC pragma, Clang and GCC do not support the exact same set
|
|
of warnings, so even when using GCC compatible #pragmas there is no
|
|
guarantee that they will have identical behaviour on both compilers.
|
|
|
|
In addition to controlling warnings and errors generated by the compiler, it is
|
|
possible to generate custom warning and error messages through the following
|
|
pragmas:
|
|
|
|
.. code-block:: c
|
|
|
|
// The following will produce warning messages
|
|
#pragma message "some diagnostic message"
|
|
#pragma GCC warning "TODO: replace deprecated feature"
|
|
|
|
// The following will produce an error message
|
|
#pragma GCC error "Not supported"
|
|
|
|
These pragmas operate similarly to the ``#warning`` and ``#error`` preprocessor
|
|
directives, except that they may also be embedded into preprocessor macros via
|
|
the C99 ``_Pragma`` operator, for example:
|
|
|
|
.. code-block:: c
|
|
|
|
#define STR(X) #X
|
|
#define DEFER(M,...) M(__VA_ARGS__)
|
|
#define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__))))
|
|
|
|
CUSTOM_ERROR("Feature not available");
|
|
|
|
Controlling Diagnostics in System Headers
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Warnings are suppressed when they occur in system headers. By default,
|
|
an included file is treated as a system header if it is found in an
|
|
include path specified by ``-isystem``, but this can be overridden in
|
|
several ways.
|
|
|
|
The ``system_header`` pragma can be used to mark the current file as
|
|
being a system header. No warnings will be produced from the location of
|
|
the pragma onwards within the same file.
|
|
|
|
.. code-block:: c
|
|
|
|
char a = 'xy'; // warning
|
|
|
|
#pragma clang system_header
|
|
|
|
char b = 'ab'; // no warning
|
|
|
|
The :option:`--system-header-prefix=` and :option:`--no-system-header-prefix=`
|
|
command-line arguments can be used to override whether subsets of an include
|
|
path are treated as system headers. When the name in a ``#include`` directive
|
|
is found within a header search path and starts with a system prefix, the
|
|
header is treated as a system header. The last prefix on the
|
|
command-line which matches the specified header name takes precedence.
|
|
For instance:
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang -Ifoo -isystem bar --system-header-prefix=x/ \
|
|
--no-system-header-prefix=x/y/
|
|
|
|
Here, ``#include "x/a.h"`` is treated as including a system header, even
|
|
if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated
|
|
as not including a system header, even if the header is found in
|
|
``bar``.
|
|
|
|
A ``#include`` directive which finds a file relative to the current
|
|
directory is treated as including a system header if the including file
|
|
is treated as a system header.
|
|
|
|
.. _diagnostics_enable_everything:
|
|
|
|
Enabling All Diagnostics
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
In addition to the traditional ``-W`` flags, one can enable **all**
|
|
diagnostics by passing :option:`-Weverything`. This works as expected
|
|
with
|
|
:option:`-Werror`, and also includes the warnings from :option:`-pedantic`.
|
|
|
|
Note that when combined with :option:`-w` (which disables all warnings), that
|
|
flag wins.
|
|
|
|
Controlling Static Analyzer Diagnostics
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
While not strictly part of the compiler, the diagnostics from Clang's
|
|
`static analyzer <http://clang-analyzer.llvm.org>`_ can also be
|
|
influenced by the user via changes to the source code. See the available
|
|
`annotations <http://clang-analyzer.llvm.org/annotations.html>`_ and the
|
|
analyzer's `FAQ
|
|
page <http://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more
|
|
information.
|
|
|
|
.. _usersmanual-precompiled-headers:
|
|
|
|
Precompiled Headers
|
|
-------------------
|
|
|
|
`Precompiled headers <http://en.wikipedia.org/wiki/Precompiled_header>`__
|
|
are a general approach employed by many compilers to reduce compilation
|
|
time. The underlying motivation of the approach is that it is common for
|
|
the same (and often large) header files to be included by multiple
|
|
source files. Consequently, compile times can often be greatly improved
|
|
by caching some of the (redundant) work done by a compiler to process
|
|
headers. Precompiled header files, which represent one of many ways to
|
|
implement this optimization, are literally files that represent an
|
|
on-disk cache that contains the vital information necessary to reduce
|
|
some of the work needed to process a corresponding header file. While
|
|
details of precompiled headers vary between compilers, precompiled
|
|
headers have been shown to be highly effective at speeding up program
|
|
compilation on systems with very large system headers (e.g., Mac OS X).
|
|
|
|
Generating a PCH File
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
To generate a PCH file using Clang, one invokes Clang with the
|
|
:option:`-x <language>-header` option. This mirrors the interface in GCC
|
|
for generating PCH files:
|
|
|
|
.. code-block:: console
|
|
|
|
$ gcc -x c-header test.h -o test.h.gch
|
|
$ clang -x c-header test.h -o test.h.pch
|
|
|
|
Using a PCH File
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
A PCH file can then be used as a prefix header when a :option:`-include`
|
|
option is passed to ``clang``:
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang -include test.h test.c -o test
|
|
|
|
The ``clang`` driver will first check if a PCH file for ``test.h`` is
|
|
available; if so, the contents of ``test.h`` (and the files it includes)
|
|
will be processed from the PCH file. Otherwise, Clang falls back to
|
|
directly processing the content of ``test.h``. This mirrors the behavior
|
|
of GCC.
|
|
|
|
.. note::
|
|
|
|
Clang does *not* automatically use PCH files for headers that are directly
|
|
included within a source file. For example:
|
|
|
|
.. code-block:: console
|
|
|
|
$ clang -x c-header test.h -o test.h.pch
|
|
$ cat test.c
|
|
#include "test.h"
|
|
$ clang test.c -o test
|
|
|
|
In this example, ``clang`` will not automatically use the PCH file for
|
|
``test.h`` since ``test.h`` was included directly in the source file and not
|
|
specified on the command line using :option:`-include`.
|
|
|
|
Relocatable PCH Files
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
It is sometimes necessary to build a precompiled header from headers
|
|
that are not yet in their final, installed locations. For example, one
|
|
might build a precompiled header within the build tree that is then
|
|
meant to be installed alongside the headers. Clang permits the creation
|
|
of "relocatable" precompiled headers, which are built with a given path
|
|
(into the build directory) and can later be used from an installed
|
|
location.
|
|
|
|
To build a relocatable precompiled header, place your headers into a
|
|
subdirectory whose structure mimics the installed location. For example,
|
|
if you want to build a precompiled header for the header ``mylib.h``
|
|
that will be installed into ``/usr/include``, create a subdirectory
|
|
``build/usr/include`` and place the header ``mylib.h`` into that
|
|
subdirectory. If ``mylib.h`` depends on other headers, then they can be
|
|
stored within ``build/usr/include`` in a way that mimics the installed
|
|
location.
|
|
|
|
Building a relocatable precompiled header requires two additional
|
|
arguments. First, pass the ``--relocatable-pch`` flag to indicate that
|
|
the resulting PCH file should be relocatable. Second, pass
|
|
:option:`-isysroot /path/to/build`, which makes all includes for your library
|
|
relative to the build directory. For example:
|
|
|
|
.. code-block:: console
|
|
|
|
# clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
|
|
|
|
When loading the relocatable PCH file, the various headers used in the
|
|
PCH file are found from the system header root. For example, ``mylib.h``
|
|
can be found in ``/usr/include/mylib.h``. If the headers are installed
|
|
in some other system root, the :option:`-isysroot` option can be used provide
|
|
a different system root from which the headers will be based. For
|
|
example, :option:`-isysroot /Developer/SDKs/MacOSX10.4u.sdk` will look for
|
|
``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``.
|
|
|
|
Relocatable precompiled headers are intended to be used in a limited
|
|
number of cases where the compilation environment is tightly controlled
|
|
and the precompiled header cannot be generated after headers have been
|
|
installed.
|
|
|
|
Controlling Code Generation
|
|
---------------------------
|
|
|
|
Clang provides a number of ways to control code generation. The options
|
|
are listed below.
|
|
|
|
**-f[no-]sanitize=check1,check2,...**
|
|
Turn on runtime checks for various forms of undefined or suspicious
|
|
behavior.
|
|
|
|
This option controls whether Clang adds runtime checks for various
|
|
forms of undefined or suspicious behavior, and is disabled by
|
|
default. If a check fails, a diagnostic message is produced at
|
|
runtime explaining the problem. The main checks are:
|
|
|
|
- .. _opt_fsanitize_address:
|
|
|
|
``-fsanitize=address``:
|
|
:doc:`AddressSanitizer`, a memory error
|
|
detector.
|
|
- ``-fsanitize=init-order``: Make AddressSanitizer check for
|
|
dynamic initialization order problems. Implied by ``-fsanitize=address``.
|
|
- ``-fsanitize=address-full``: AddressSanitizer with all the
|
|
experimental features listed below.
|
|
- ``-fsanitize=integer``: Enables checks for undefined or
|
|
suspicious integer behavior.
|
|
- .. _opt_fsanitize_thread:
|
|
|
|
``-fsanitize=thread``: :doc:`ThreadSanitizer`, a data race detector.
|
|
- .. _opt_fsanitize_memory:
|
|
|
|
``-fsanitize=memory``: :doc:`MemorySanitizer`,
|
|
an *experimental* detector of uninitialized reads. Not ready for
|
|
widespread use.
|
|
- .. _opt_fsanitize_undefined:
|
|
|
|
``-fsanitize=undefined``: Fast and compatible undefined behavior
|
|
checker. Enables the undefined behavior checks that have small
|
|
runtime cost and no impact on address space layout or ABI. This
|
|
includes all of the checks listed below other than
|
|
``unsigned-integer-overflow``.
|
|
|
|
- ``-fsanitize=undefined-trap``: This includes all sanitizers
|
|
included by ``-fsanitize=undefined``, except those that require
|
|
runtime support. This group of sanitizers is intended to be
|
|
used in conjunction with the ``-fsanitize-undefined-trap-on-error``
|
|
flag. This includes all of the checks listed below other than
|
|
``unsigned-integer-overflow`` and ``vptr``.
|
|
- ``-fsanitize=dataflow``: :doc:`DataFlowSanitizer`, a general data
|
|
flow analysis.
|
|
|
|
The following more fine-grained checks are also available:
|
|
|
|
- ``-fsanitize=alignment``: Use of a misaligned pointer or creation
|
|
of a misaligned reference.
|
|
- ``-fsanitize=bool``: Load of a ``bool`` value which is neither
|
|
``true`` nor ``false``.
|
|
- ``-fsanitize=bounds``: Out of bounds array indexing, in cases
|
|
where the array bound can be statically determined.
|
|
- ``-fsanitize=enum``: Load of a value of an enumerated type which
|
|
is not in the range of representable values for that enumerated
|
|
type.
|
|
- ``-fsanitize=float-cast-overflow``: Conversion to, from, or
|
|
between floating-point types which would overflow the
|
|
destination.
|
|
- ``-fsanitize=float-divide-by-zero``: Floating point division by
|
|
zero.
|
|
- ``-fsanitize=function``: Indirect call of a function through a
|
|
function pointer of the wrong type (Linux, C++ and x86/x86_64 only).
|
|
- ``-fsanitize=integer-divide-by-zero``: Integer division by zero.
|
|
- ``-fsanitize=null``: Use of a null pointer or creation of a null
|
|
reference.
|
|
- ``-fsanitize=object-size``: An attempt to use bytes which the
|
|
optimizer can determine are not part of the object being
|
|
accessed. The sizes of objects are determined using
|
|
``__builtin_object_size``, and consequently may be able to detect
|
|
more problems at higher optimization levels.
|
|
- ``-fsanitize=return``: In C++, reaching the end of a
|
|
value-returning function without returning a value.
|
|
- ``-fsanitize=shift``: Shift operators where the amount shifted is
|
|
greater or equal to the promoted bit-width of the left hand side
|
|
or less than zero, or where the left hand side is negative. For a
|
|
signed left shift, also checks for signed overflow in C, and for
|
|
unsigned overflow in C++.
|
|
- ``-fsanitize=signed-integer-overflow``: Signed integer overflow,
|
|
including all the checks added by ``-ftrapv``, and checking for
|
|
overflow in signed division (``INT_MIN / -1``).
|
|
- ``-fsanitize=unreachable``: If control flow reaches
|
|
``__builtin_unreachable``.
|
|
- ``-fsanitize=unsigned-integer-overflow``: Unsigned integer
|
|
overflows.
|
|
- ``-fsanitize=vla-bound``: A variable-length array whose bound
|
|
does not evaluate to a positive value.
|
|
- ``-fsanitize=vptr``: Use of an object whose vptr indicates that
|
|
it is of the wrong dynamic type, or that its lifetime has not
|
|
begun or has ended. Incompatible with ``-fno-rtti``.
|
|
|
|
You can turn off or modify checks for certain source files, functions
|
|
or even variables by providing a special file:
|
|
|
|
- ``-fsanitize-blacklist=/path/to/blacklist/file``: disable or modify
|
|
sanitizer checks for objects listed in the file. See
|
|
:doc:`SanitizerSpecialCaseList` for file format description.
|
|
- ``-fno-sanitize-blacklist``: don't use blacklist file, if it was
|
|
specified earlier in the command line.
|
|
|
|
Experimental features of AddressSanitizer (not ready for widespread
|
|
use, require explicit ``-fsanitize=address``):
|
|
|
|
- ``-fsanitize=use-after-return``: Check for use-after-return
|
|
errors (accessing local variable after the function exit).
|
|
- ``-fsanitize=use-after-scope``: Check for use-after-scope errors
|
|
(accesing local variable after it went out of scope).
|
|
|
|
Extra features of MemorySanitizer (require explicit
|
|
``-fsanitize=memory``):
|
|
|
|
- ``-fsanitize-memory-track-origins[=level]``: Enables origin tracking in
|
|
MemorySanitizer. Adds a second section to MemorySanitizer
|
|
reports pointing to the heap or stack allocation the
|
|
uninitialized bits came from. Slows down execution by additional
|
|
1.5x-2x.
|
|
|
|
Possible values for level are 0 (off), 1 (default), 2. Level 2 adds more
|
|
sections to MemorySanitizer reports describing the order of memory stores
|
|
the uninitialized value went through. Beware, this mode may use a lot of
|
|
extra memory.
|
|
|
|
Extra features of UndefinedBehaviorSanitizer:
|
|
|
|
- ``-fno-sanitize-recover``: By default, after a sanitizer diagnoses
|
|
an issue, it will attempt to continue executing the program if there
|
|
is a reasonable behavior it can give to the faulting operation. This
|
|
option causes the program to abort instead.
|
|
- ``-fsanitize-undefined-trap-on-error``: Causes traps to be emitted
|
|
rather than calls to runtime libraries when a problem is detected.
|
|
This option is intended for use in cases where the sanitizer runtime
|
|
cannot be used (for instance, when building libc or a kernel module).
|
|
This is only compatible with the sanitizers in the ``undefined-trap``
|
|
group.
|
|
|
|
The ``-fsanitize=`` argument must also be provided when linking, in
|
|
order to link to the appropriate runtime library. When using
|
|
``-fsanitize=vptr`` (or a group that includes it, such as
|
|
``-fsanitize=undefined``) with a C++ program, the link must be
|
|
performed by ``clang++``, not ``clang``, in order to link against the
|
|
C++-specific parts of the runtime library.
|
|
|
|
It is not possible to combine more than one of the ``-fsanitize=address``,
|
|
``-fsanitize=thread``, and ``-fsanitize=memory`` checkers in the same
|
|
program. The ``-fsanitize=undefined`` checks can be combined with other
|
|
sanitizers.
|
|
|
|
.. option:: -fno-assume-sane-operator-new
|
|
|
|
Don't assume that the C++'s new operator is sane.
|
|
|
|
This option tells the compiler to do not assume that C++'s global
|
|
new operator will always return a pointer that does not alias any
|
|
other pointer when the function returns.
|
|
|
|
.. option:: -ftrap-function=[name]
|
|
|
|
Instruct code generator to emit a function call to the specified
|
|
function name for ``__builtin_trap()``.
|
|
|
|
LLVM code generator translates ``__builtin_trap()`` to a trap
|
|
instruction if it is supported by the target ISA. Otherwise, the
|
|
builtin is translated into a call to ``abort``. If this option is
|
|
set, then the code generator will always lower the builtin to a call
|
|
to the specified function regardless of whether the target ISA has a
|
|
trap instruction. This option is useful for environments (e.g.
|
|
deeply embedded) where a trap cannot be properly handled, or when
|
|
some custom behavior is desired.
|
|
|
|
.. option:: -ftls-model=[model]
|
|
|
|
Select which TLS model to use.
|
|
|
|
Valid values are: ``global-dynamic``, ``local-dynamic``,
|
|
``initial-exec`` and ``local-exec``. The default value is
|
|
``global-dynamic``. The compiler may use a different model if the
|
|
selected model is not supported by the target, or if a more
|
|
efficient model can be used. The TLS model can be overridden per
|
|
variable using the ``tls_model`` attribute.
|
|
|
|
.. option:: -mhwdiv=[values]
|
|
|
|
Select the ARM modes (arm or thumb) that support hardware division
|
|
instructions.
|
|
|
|
Valid values are: ``arm``, ``thumb`` and ``arm,thumb``.
|
|
This option is used to indicate which mode (arm or thumb) supports
|
|
hardware division instructions. This only applies to the ARM
|
|
architecture.
|
|
|
|
.. option:: -m[no-]crc
|
|
|
|
Enable or disable CRC instructions.
|
|
|
|
This option is used to indicate whether CRC instructions are to
|
|
be generated. This only applies to the ARM architecture.
|
|
|
|
CRC instructions are enabled by default on ARMv8.
|
|
|
|
.. option:: -mgeneral-regs-only
|
|
|
|
Generate code which only uses the general purpose registers.
|
|
|
|
This option restricts the generated code to use general registers
|
|
only. This only applies to the AArch64 architecture.
|
|
|
|
|
|
Controlling Size of Debug Information
|
|
-------------------------------------
|
|
|
|
Debug info kind generated by Clang can be set by one of the flags listed
|
|
below. If multiple flags are present, the last one is used.
|
|
|
|
.. option:: -g0
|
|
|
|
Don't generate any debug info (default).
|
|
|
|
.. option:: -gline-tables-only
|
|
|
|
Generate line number tables only.
|
|
|
|
This kind of debug info allows to obtain stack traces with function names,
|
|
file names and line numbers (by such tools as ``gdb`` or ``addr2line``). It
|
|
doesn't contain any other data (e.g. description of local variables or
|
|
function parameters).
|
|
|
|
.. option:: -g
|
|
|
|
Generate complete debug info.
|
|
|
|
Comment Parsing Options
|
|
-----------------------
|
|
|
|
Clang parses Doxygen and non-Doxygen style documentation comments and attaches
|
|
them to the appropriate declaration nodes. By default, it only parses
|
|
Doxygen-style comments and ignores ordinary comments starting with ``//`` and
|
|
``/*``.
|
|
|
|
.. option:: -Wdocumentation
|
|
|
|
Emit warnings about use of documentation comments. This warning group is off
|
|
by default.
|
|
|
|
This includes checking that ``\param`` commands name parameters that actually
|
|
present in the function signature, checking that ``\returns`` is used only on
|
|
functions that actually return a value etc.
|
|
|
|
.. option:: -Wno-documentation-unknown-command
|
|
|
|
Don't warn when encountering an unknown Doxygen command.
|
|
|
|
.. option:: -fparse-all-comments
|
|
|
|
Parse all comments as documentation comments (including ordinary comments
|
|
starting with ``//`` and ``/*``).
|
|
|
|
.. option:: -fcomment-block-commands=[commands]
|
|
|
|
Define custom documentation commands as block commands. This allows Clang to
|
|
construct the correct AST for these custom commands, and silences warnings
|
|
about unknown commands. Several commands must be separated by a comma
|
|
*without trailing space*; e.g. ``-fcomment-block-commands=foo,bar`` defines
|
|
custom commands ``\foo`` and ``\bar``.
|
|
|
|
It is also possible to use ``-fcomment-block-commands`` several times; e.g.
|
|
``-fcomment-block-commands=foo -fcomment-block-commands=bar`` does the same
|
|
as above.
|
|
|
|
.. _c:
|
|
|
|
C Language Features
|
|
===================
|
|
|
|
The support for standard C in clang is feature-complete except for the
|
|
C99 floating-point pragmas.
|
|
|
|
Extensions supported by clang
|
|
-----------------------------
|
|
|
|
See :doc:`LanguageExtensions`.
|
|
|
|
Differences between various standard modes
|
|
------------------------------------------
|
|
|
|
clang supports the -std option, which changes what language mode clang
|
|
uses. The supported modes for C are c89, gnu89, c94, c99, gnu99 and
|
|
various aliases for those modes. If no -std option is specified, clang
|
|
defaults to gnu99 mode.
|
|
|
|
Differences between all ``c*`` and ``gnu*`` modes:
|
|
|
|
- ``c*`` modes define "``__STRICT_ANSI__``".
|
|
- Target-specific defines not prefixed by underscores, like "linux",
|
|
are defined in ``gnu*`` modes.
|
|
- Trigraphs default to being off in ``gnu*`` modes; they can be enabled by
|
|
the -trigraphs option.
|
|
- The parser recognizes "asm" and "typeof" as keywords in ``gnu*`` modes;
|
|
the variants "``__asm__``" and "``__typeof__``" are recognized in all
|
|
modes.
|
|
- The Apple "blocks" extension is recognized by default in ``gnu*`` modes
|
|
on some platforms; it can be enabled in any mode with the "-fblocks"
|
|
option.
|
|
- Arrays that are VLA's according to the standard, but which can be
|
|
constant folded by the frontend are treated as fixed size arrays.
|
|
This occurs for things like "int X[(1, 2)];", which is technically a
|
|
VLA. ``c*`` modes are strictly compliant and treat these as VLAs.
|
|
|
|
Differences between ``*89`` and ``*99`` modes:
|
|
|
|
- The ``*99`` modes default to implementing "inline" as specified in C99,
|
|
while the ``*89`` modes implement the GNU version. This can be
|
|
overridden for individual functions with the ``__gnu_inline__``
|
|
attribute.
|
|
- Digraphs are not recognized in c89 mode.
|
|
- The scope of names defined inside a "for", "if", "switch", "while",
|
|
or "do" statement is different. (example: "``if ((struct x {int
|
|
x;}*)0) {}``".)
|
|
- ``__STDC_VERSION__`` is not defined in ``*89`` modes.
|
|
- "inline" is not recognized as a keyword in c89 mode.
|
|
- "restrict" is not recognized as a keyword in ``*89`` modes.
|
|
- Commas are allowed in integer constant expressions in ``*99`` modes.
|
|
- Arrays which are not lvalues are not implicitly promoted to pointers
|
|
in ``*89`` modes.
|
|
- Some warnings are different.
|
|
|
|
c94 mode is identical to c89 mode except that digraphs are enabled in
|
|
c94 mode (FIXME: And ``__STDC_VERSION__`` should be defined!).
|
|
|
|
GCC extensions not implemented yet
|
|
----------------------------------
|
|
|
|
clang tries to be compatible with gcc as much as possible, but some gcc
|
|
extensions are not implemented yet:
|
|
|
|
- clang does not support #pragma weak (`bug
|
|
3679 <http://llvm.org/bugs/show_bug.cgi?id=3679>`_). Due to the uses
|
|
described in the bug, this is likely to be implemented at some point,
|
|
at least partially.
|
|
- clang does not support decimal floating point types (``_Decimal32`` and
|
|
friends) or fixed-point types (``_Fract`` and friends); nobody has
|
|
expressed interest in these features yet, so it's hard to say when
|
|
they will be implemented.
|
|
- clang does not support nested functions; this is a complex feature
|
|
which is infrequently used, so it is unlikely to be implemented
|
|
anytime soon. In C++11 it can be emulated by assigning lambda
|
|
functions to local variables, e.g:
|
|
|
|
.. code-block:: cpp
|
|
|
|
auto const local_function = [&](int parameter) {
|
|
// Do something
|
|
};
|
|
...
|
|
local_function(1);
|
|
|
|
- clang does not support global register variables; this is unlikely to
|
|
be implemented soon because it requires additional LLVM backend
|
|
support.
|
|
- clang does not support static initialization of flexible array
|
|
members. This appears to be a rarely used extension, but could be
|
|
implemented pending user demand.
|
|
- clang does not support
|
|
``__builtin_va_arg_pack``/``__builtin_va_arg_pack_len``. This is
|
|
used rarely, but in some potentially interesting places, like the
|
|
glibc headers, so it may be implemented pending user demand. Note
|
|
that because clang pretends to be like GCC 4.2, and this extension
|
|
was introduced in 4.3, the glibc headers will not try to use this
|
|
extension with clang at the moment.
|
|
- clang does not support the gcc extension for forward-declaring
|
|
function parameters; this has not shown up in any real-world code
|
|
yet, though, so it might never be implemented.
|
|
|
|
This is not a complete list; if you find an unsupported extension
|
|
missing from this list, please send an e-mail to cfe-dev. This list
|
|
currently excludes C++; see :ref:`C++ Language Features <cxx>`. Also, this
|
|
list does not include bugs in mostly-implemented features; please see
|
|
the `bug
|
|
tracker <http://llvm.org/bugs/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer>`_
|
|
for known existing bugs (FIXME: Is there a section for bug-reporting
|
|
guidelines somewhere?).
|
|
|
|
Intentionally unsupported GCC extensions
|
|
----------------------------------------
|
|
|
|
- clang does not support the gcc extension that allows variable-length
|
|
arrays in structures. This is for a few reasons: one, it is tricky to
|
|
implement, two, the extension is completely undocumented, and three,
|
|
the extension appears to be rarely used. Note that clang *does*
|
|
support flexible array members (arrays with a zero or unspecified
|
|
size at the end of a structure).
|
|
- clang does not have an equivalent to gcc's "fold"; this means that
|
|
clang doesn't accept some constructs gcc might accept in contexts
|
|
where a constant expression is required, like "x-x" where x is a
|
|
variable.
|
|
- clang does not support ``__builtin_apply`` and friends; this extension
|
|
is extremely obscure and difficult to implement reliably.
|
|
|
|
.. _c_ms:
|
|
|
|
Microsoft extensions
|
|
--------------------
|
|
|
|
clang has some experimental support for extensions from Microsoft Visual
|
|
C++; to enable it, use the ``-fms-extensions`` command-line option. This is
|
|
the default for Windows targets. Note that the support is incomplete.
|
|
Some constructs such as ``dllexport`` on classes are ignored with a warning,
|
|
and others such as `Microsoft IDL annotations
|
|
<http://msdn.microsoft.com/en-us/library/8tesw2eh.aspx>`_ are silently
|
|
ignored.
|
|
|
|
clang has a ``-fms-compatibility`` flag that makes clang accept enough
|
|
invalid C++ to be able to parse most Microsoft headers. For example, it
|
|
allows `unqualified lookup of dependent base class members
|
|
<http://clang.llvm.org/compatibility.html#dep_lookup_bases>`_, which is
|
|
a common compatibility issue with clang. This flag is enabled by default
|
|
for Windows targets.
|
|
|
|
``-fdelayed-template-parsing`` lets clang delay parsing of function template
|
|
definitions until the end of a translation unit. This flag is enabled by
|
|
default for Windows targets.
|
|
|
|
- clang allows setting ``_MSC_VER`` with ``-fmsc-version=``. It defaults to
|
|
1700 which is the same as Visual C/C++ 2012. Any number is supported
|
|
and can greatly affect what Windows SDK and c++stdlib headers clang
|
|
can compile.
|
|
- clang does not support the Microsoft extension where anonymous record
|
|
members can be declared using user defined typedefs.
|
|
- clang supports the Microsoft ``#pragma pack`` feature for controlling
|
|
record layout. GCC also contains support for this feature, however
|
|
where MSVC and GCC are incompatible clang follows the MSVC
|
|
definition.
|
|
- clang supports the Microsoft ``#pragma comment(lib, "foo.lib")`` feature for
|
|
automatically linking against the specified library. Currently this feature
|
|
only works with the Visual C++ linker.
|
|
- clang supports the Microsoft ``#pragma comment(linker, "/flag:foo")`` feature
|
|
for adding linker flags to COFF object files. The user is responsible for
|
|
ensuring that the linker understands the flags.
|
|
- clang defaults to C++11 for Windows targets.
|
|
|
|
.. _cxx:
|
|
|
|
C++ Language Features
|
|
=====================
|
|
|
|
clang fully implements all of standard C++98 except for exported
|
|
templates (which were removed in C++11), and all of standard C++11
|
|
and the current draft standard for C++1y.
|
|
|
|
Controlling implementation limits
|
|
---------------------------------
|
|
|
|
.. option:: -fbracket-depth=N
|
|
|
|
Sets the limit for nested parentheses, brackets, and braces to N. The
|
|
default is 256.
|
|
|
|
.. option:: -fconstexpr-depth=N
|
|
|
|
Sets the limit for recursive constexpr function invocations to N. The
|
|
default is 512.
|
|
|
|
.. option:: -ftemplate-depth=N
|
|
|
|
Sets the limit for recursively nested template instantiations to N. The
|
|
default is 256.
|
|
|
|
.. option:: -foperator-arrow-depth=N
|
|
|
|
Sets the limit for iterative calls to 'operator->' functions to N. The
|
|
default is 256.
|
|
|
|
.. _objc:
|
|
|
|
Objective-C Language Features
|
|
=============================
|
|
|
|
.. _objcxx:
|
|
|
|
Objective-C++ Language Features
|
|
===============================
|
|
|
|
|
|
.. _target_features:
|
|
|
|
Target-Specific Features and Limitations
|
|
========================================
|
|
|
|
CPU Architectures Features and Limitations
|
|
------------------------------------------
|
|
|
|
X86
|
|
^^^
|
|
|
|
The support for X86 (both 32-bit and 64-bit) is considered stable on
|
|
Darwin (Mac OS X), Linux, FreeBSD, and Dragonfly BSD: it has been tested
|
|
to correctly compile many large C, C++, Objective-C, and Objective-C++
|
|
codebases.
|
|
|
|
On ``x86_64-mingw32``, passing i128(by value) is incompatible with the
|
|
Microsoft x64 calling convention. You might need to tweak
|
|
``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp.
|
|
|
|
For the X86 target, clang supports the :option:`-m16` command line
|
|
argument which enables 16-bit code output. This is broadly similar to
|
|
using ``asm(".code16gcc")`` with the GNU toolchain. The generated code
|
|
and the ABI remains 32-bit but the assembler emits instructions
|
|
appropriate for a CPU running in 16-bit mode, with address-size and
|
|
operand-size prefixes to enable 32-bit addressing and operations.
|
|
|
|
ARM
|
|
^^^
|
|
|
|
The support for ARM (specifically ARMv6 and ARMv7) is considered stable
|
|
on Darwin (iOS): it has been tested to correctly compile many large C,
|
|
C++, Objective-C, and Objective-C++ codebases. Clang only supports a
|
|
limited number of ARM architectures. It does not yet fully support
|
|
ARMv5, for example.
|
|
|
|
PowerPC
|
|
^^^^^^^
|
|
|
|
The support for PowerPC (especially PowerPC64) is considered stable
|
|
on Linux and FreeBSD: it has been tested to correctly compile many
|
|
large C and C++ codebases. PowerPC (32bit) is still missing certain
|
|
features (e.g. PIC code on ELF platforms).
|
|
|
|
Other platforms
|
|
^^^^^^^^^^^^^^^
|
|
|
|
clang currently contains some support for other architectures (e.g. Sparc);
|
|
however, significant pieces of code generation are still missing, and they
|
|
haven't undergone significant testing.
|
|
|
|
clang contains limited support for the MSP430 embedded processor, but
|
|
both the clang support and the LLVM backend support are highly
|
|
experimental.
|
|
|
|
Other platforms are completely unsupported at the moment. Adding the
|
|
minimal support needed for parsing and semantic analysis on a new
|
|
platform is quite easy; see ``lib/Basic/Targets.cpp`` in the clang source
|
|
tree. This level of support is also sufficient for conversion to LLVM IR
|
|
for simple programs. Proper support for conversion to LLVM IR requires
|
|
adding code to ``lib/CodeGen/CGCall.cpp`` at the moment; this is likely to
|
|
change soon, though. Generating assembly requires a suitable LLVM
|
|
backend.
|
|
|
|
Operating System Features and Limitations
|
|
-----------------------------------------
|
|
|
|
Darwin (Mac OS X)
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
Thread Sanitizer is not supported.
|
|
|
|
Windows
|
|
^^^^^^^
|
|
|
|
Clang has experimental support for targeting "Cygming" (Cygwin / MinGW)
|
|
platforms.
|
|
|
|
See also :ref:`Microsoft Extensions <c_ms>`.
|
|
|
|
Cygwin
|
|
""""""
|
|
|
|
Clang works on Cygwin-1.7.
|
|
|
|
MinGW32
|
|
"""""""
|
|
|
|
Clang works on some mingw32 distributions. Clang assumes directories as
|
|
below;
|
|
|
|
- ``C:/mingw/include``
|
|
- ``C:/mingw/lib``
|
|
- ``C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++``
|
|
|
|
On MSYS, a few tests might fail.
|
|
|
|
MinGW-w64
|
|
"""""""""
|
|
|
|
For 32-bit (i686-w64-mingw32), and 64-bit (x86\_64-w64-mingw32), Clang
|
|
assumes as below;
|
|
|
|
- ``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)``
|
|
- ``some_directory/bin/gcc.exe``
|
|
- ``some_directory/bin/clang.exe``
|
|
- ``some_directory/bin/clang++.exe``
|
|
- ``some_directory/bin/../include/c++/GCC_version``
|
|
- ``some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32``
|
|
- ``some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32``
|
|
- ``some_directory/bin/../include/c++/GCC_version/backward``
|
|
- ``some_directory/bin/../x86_64-w64-mingw32/include``
|
|
- ``some_directory/bin/../i686-w64-mingw32/include``
|
|
- ``some_directory/bin/../include``
|
|
|
|
This directory layout is standard for any toolchain you will find on the
|
|
official `MinGW-w64 website <http://mingw-w64.sourceforge.net>`_.
|
|
|
|
Clang expects the GCC executable "gcc.exe" compiled for
|
|
``i686-w64-mingw32`` (or ``x86_64-w64-mingw32``) to be present on PATH.
|
|
|
|
`Some tests might fail <http://llvm.org/bugs/show_bug.cgi?id=9072>`_ on
|
|
``x86_64-w64-mingw32``.
|
|
|
|
.. _clang-cl:
|
|
|
|
clang-cl
|
|
========
|
|
|
|
clang-cl is an alternative command-line interface to Clang driver, designed for
|
|
compatibility with the Visual C++ compiler, cl.exe.
|
|
|
|
To enable clang-cl to find system headers, libraries, and the linker when run
|
|
from the command-line, it should be executed inside a Visual Studio Native Tools
|
|
Command Prompt or a regular Command Prompt where the environment has been set
|
|
up using e.g. `vcvars32.bat <http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_.
|
|
|
|
clang-cl can also be used from inside Visual Studio by using an LLVM Platform
|
|
Toolset.
|
|
|
|
Command-Line Options
|
|
--------------------
|
|
|
|
To be compatible with cl.exe, clang-cl supports most of the same command-line
|
|
options. Those options can start with either ``/`` or ``-``. It also supports
|
|
some of Clang's core options, such as the ``-W`` options.
|
|
|
|
Options that are known to clang-cl, but not currently supported, are ignored
|
|
with a warning. For example:
|
|
|
|
::
|
|
|
|
clang-cl.exe: warning: argument unused during compilation: '/Zi'
|
|
|
|
To suppress warnings about unused arguments, use the ``-Qunused-arguments`` option.
|
|
|
|
Options that are not known to clang-cl will cause errors. If they are spelled with a
|
|
leading ``/``, they will be mistaken for a filename:
|
|
|
|
::
|
|
|
|
clang-cl.exe: error: no such file or directory: '/foobar'
|
|
|
|
Please `file a bug <http://llvm.org/bugs/enter_bug.cgi?product=clang&component=Driver>`_
|
|
for any valid cl.exe flags that clang-cl does not understand.
|
|
|
|
Execute ``clang-cl /?`` to see a list of supported options:
|
|
|
|
::
|
|
|
|
/? Display available options
|
|
/c Compile only
|
|
/D <macro[=value]> Define macro
|
|
/fallback Fall back to cl.exe if clang-cl fails to compile
|
|
/FA Output assembly code file during compilation
|
|
/Fa<file or directory> Output assembly code to this file during compilation
|
|
/Fe<file or directory> Set output executable file or directory (ends in / or \)
|
|
/FI<value> Include file before parsing
|
|
/Fo<file or directory> Set output object file, or directory (ends in / or \)
|
|
/GF- Disable string pooling
|
|
/GR- Disable RTTI
|
|
/GR Enable RTTI
|
|
/help Display available options
|
|
/I <dir> Add directory to include search path
|
|
/J Make char type unsigned
|
|
/LDd Create debug DLL
|
|
/LD Create DLL
|
|
/link <options> Forward options to the linker
|
|
/MDd Use DLL debug run-time
|
|
/MD Use DLL run-time
|
|
/MTd Use static debug run-time
|
|
/MT Use static run-time
|
|
/Ob0 Disable inlining
|
|
/Od Disable optimization
|
|
/Oi- Disable use of builtin functions
|
|
/Oi Enable use of builtin functions
|
|
/Os Optimize for size
|
|
/Ot Optimize for speed
|
|
/Ox Maximum optimization
|
|
/Oy- Disable frame pointer omission
|
|
/Oy Enable frame pointer omission
|
|
/O<n> Optimization level
|
|
/P Only run the preprocessor
|
|
/showIncludes Print info about included files to stderr
|
|
/TC Treat all source files as C
|
|
/Tc <filename> Specify a C source file
|
|
/TP Treat all source files as C++
|
|
/Tp <filename> Specify a C++ source file
|
|
/U <macro> Undefine macro
|
|
/W0 Disable all warnings
|
|
/W1 Enable -Wall
|
|
/W2 Enable -Wall
|
|
/W3 Enable -Wall
|
|
/W4 Enable -Wall
|
|
/Wall Enable -Wall
|
|
/WX- Do not treat warnings as errors
|
|
/WX Treat warnings as errors
|
|
/w Disable all warnings
|
|
/Zs Syntax-check only
|
|
|
|
The /fallback Option
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
When clang-cl is run with the ``/fallback`` option, it will first try to
|
|
compile files itself. For any file that it fails to compile, it will fall back
|
|
and try to compile the file by invoking cl.exe.
|
|
|
|
This option is intended to be used as a temporary means to build projects where
|
|
clang-cl cannot successfully compile all the files. clang-cl may fail to compile
|
|
a file either because it cannot generate code for some C++ feature, or because
|
|
it cannot parse some Microsoft language extension.
|