Updated to Clang 3.5a.
Change-Id: I8127eb568f674c2e72635b639a3295381fe8af82
diff --git a/docs/AddressSanitizer.rst b/docs/AddressSanitizer.rst
index 5bc6d0b..93a6a0e 100644
--- a/docs/AddressSanitizer.rst
+++ b/docs/AddressSanitizer.rst
@@ -61,14 +61,14 @@
% clang -g -fsanitize=address example_UseAfterFree.o
If a bug is detected, the program will print an error message to stderr and
-exit with a non-zero exit code. Currently, AddressSanitizer does not symbolize
-its output, so you may need to use a separate script to symbolize the result
-offline (this will be fixed in future).
+exit with a non-zero exit code. To make AddressSanitizer symbolize its output
+you need to set the ``ASAN_SYMBOLIZER_PATH`` environment variable to point to
+the ``llvm-symbolizer`` binary (or make sure ``llvm-symbolizer`` is in your
+``$PATH``):
.. code-block:: console
- % ./a.out 2> log
- % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
+ % ASAN_SYMBOLIZER_PATH=/usr/local/bin/llvm-symbolizer ./a.out
==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8
READ of size 4 at 0x7f7ddab8c084 thread T0
#0 0x403c8c in main example_UseAfterFree.cc:4
@@ -84,6 +84,23 @@
#2 0x7f7ddabcac4d in __libc_start_main ??:0
==9442== ABORTING
+If that does not work for you (e.g. your process is sandboxed), you can use a
+separate script to symbolize the result offline (online symbolization can be
+force disabled by setting ``ASAN_OPTIONS=symbolize=0``):
+
+.. code-block:: console
+
+ % ASAN_OPTIONS=symbolize=0 ./a.out 2> log
+ % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
+ ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8
+ READ of size 4 at 0x7f7ddab8c084 thread T0
+ #0 0x403c8c in main example_UseAfterFree.cc:4
+ #1 0x7f7ddabcac4d in __libc_start_main ??:0
+ ...
+
+Note that on OS X you may need to run ``dsymutil`` on your binary to have the
+file\:line info in the AddressSanitizer reports.
+
AddressSanitizer exits on the first detected error. This is by design.
One reason: it makes the generated code smaller and faster (both by
~5%). Another reason: this makes fixing bugs unavoidable. With Valgrind,
@@ -167,11 +184,11 @@
AddressSanitizer is supported on
-* Linux i386/x86\_64 (tested on Ubuntu 10.04 and 12.04);
-* MacOS 10.6, 10.7 and 10.8 (i386/x86\_64).
+* Linux i386/x86\_64 (tested on Ubuntu 12.04);
+* MacOS 10.6 - 10.9 (i386/x86\_64).
+* Android ARM
-Support for Linux ARM (and Android ARM) is in progress (it may work, but
-is not guaranteed too).
+Ports to various other platforms are in progress.
Limitations
===========
diff --git a/docs/AttributeReference.rst b/docs/AttributeReference.rst
new file mode 100644
index 0000000..34a812d
--- /dev/null
+++ b/docs/AttributeReference.rst
@@ -0,0 +1,1026 @@
+..
+ -------------------------------------------------------------------
+ NOTE: This file is automatically generated by running clang-tblgen
+ -gen-attr-docs. Do not edit this file by hand!!
+ -------------------------------------------------------------------
+
+===================
+Attributes in Clang
+===================
+.. contents::
+ :local:
+
+Introduction
+============
+
+This page lists the attributes currently supported by Clang.
+
+Function Attributes
+===================
+
+
+interrupt
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Clang supports the GNU style ``__attribute__((interrupt("TYPE")))`` attribute on
+ARM targets. This attribute may be attached to a function definition and
+instructs the backend to generate appropriate function entry/exit code so that
+it can be used directly as an interrupt service routine.
+
+The parameter passed to the interrupt attribute is optional, but if
+provided it must be a string literal with one of the following values: "IRQ",
+"FIQ", "SWI", "ABORT", "UNDEF".
+
+The semantics are as follows:
+
+- If the function is AAPCS, Clang instructs the backend to realign the stack to
+ 8 bytes on entry. This is a general requirement of the AAPCS at public
+ interfaces, but may not hold when an exception is taken. Doing this allows
+ other AAPCS functions to be called.
+- If the CPU is M-class this is all that needs to be done since the architecture
+ itself is designed in such a way that functions obeying the normal AAPCS ABI
+ constraints are valid exception handlers.
+- If the CPU is not M-class, the prologue and epilogue are modified to save all
+ non-banked registers that are used, so that upon return the user-mode state
+ will not be corrupted. Note that to avoid unnecessary overhead, only
+ general-purpose (integer) registers are saved in this way. If VFP operations
+ are needed, that state must be saved manually.
+
+ Specifically, interrupt kinds other than "FIQ" will save all core registers
+ except "lr" and "sp". "FIQ" interrupts will save r0-r7.
+- If the CPU is not M-class, the return instruction is changed to one of the
+ canonical sequences permitted by the architecture for exception return. Where
+ possible the function itself will make the necessary "lr" adjustments so that
+ the "preferred return address" is selected.
+
+ Unfortunately the compiler is unable to make this guarantee for an "UNDEF"
+ handler, where the offset from "lr" to the preferred return address depends on
+ the execution state of the code which generated the exception. In this case
+ a sequence equivalent to "movs pc, lr" will be used.
+
+
+acquire_capability (acquire_shared_capability, clang::acquire_capability, clang::acquire_shared_capability)
+-----------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","X","",""
+
+Marks a function as acquiring a capability.
+
+
+assert_capability (assert_shared_capability, clang::assert_capability, clang::assert_shared_capability)
+-------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","X","",""
+
+Marks a function that dynamically tests whether a capability is held, and halts
+the program if it is not held.
+
+
+availability
+------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+The ``availability`` attribute can be placed on declarations to describe the
+lifecycle of that declaration relative to operating system versions. Consider
+the function declaration for a hypothetical function ``f``:
+
+.. code-block:: c++
+
+ void f(void) __attribute__((availability(macosx,introduced=10.4,deprecated=10.6,obsoleted=10.7)));
+
+The availability attribute states that ``f`` was introduced in Mac OS X 10.4,
+deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7. This information
+is used by Clang to determine when it is safe to use ``f``: for example, if
+Clang is instructed to compile code for Mac OS X 10.5, a call to ``f()``
+succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the call
+succeeds but Clang emits a warning specifying that the function is deprecated.
+Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call
+fails because ``f()`` is no longer available.
+
+The availability attribute is a comma-separated list starting with the
+platform name and then including clauses specifying important milestones in the
+declaration's lifetime (in any order) along with additional information. Those
+clauses can be:
+
+introduced=\ *version*
+ The first version in which this declaration was introduced.
+
+deprecated=\ *version*
+ The first version in which this declaration was deprecated, meaning that
+ users should migrate away from this API.
+
+obsoleted=\ *version*
+ The first version in which this declaration was obsoleted, meaning that it
+ was removed completely and can no longer be used.
+
+unavailable
+ This declaration is never available on this platform.
+
+message=\ *string-literal*
+ Additional message text that Clang will provide when emitting a warning or
+ error about use of a deprecated or obsoleted declaration. Useful to direct
+ users to replacement APIs.
+
+Multiple availability attributes can be placed on a declaration, which may
+correspond to different platforms. Only the availability attribute with the
+platform corresponding to the target platform will be used; any others will be
+ignored. If no availability attribute specifies availability for the current
+target platform, the availability attributes are ignored. Supported platforms
+are:
+
+``ios``
+ Apple's iOS operating system. The minimum deployment target is specified by
+ the ``-mios-version-min=*version*`` or ``-miphoneos-version-min=*version*``
+ command-line arguments.
+
+``macosx``
+ Apple's Mac OS X operating system. The minimum deployment target is
+ specified by the ``-mmacosx-version-min=*version*`` command-line argument.
+
+A declaration can be used even when deploying back to a platform version prior
+to when the declaration was introduced. When this happens, the declaration is
+`weakly linked
+<https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html>`_,
+as if the ``weak_import`` attribute were added to the declaration. A
+weakly-linked declaration may or may not be present a run-time, and a program
+can determine whether the declaration is present by checking whether the
+address of that declaration is non-NULL.
+
+If there are multiple declarations of the same entity, the availability
+attributes must either match on a per-platform basis or later
+declarations must not have availability attributes for that
+platform. For example:
+
+.. code-block:: c
+
+ void g(void) __attribute__((availability(macosx,introduced=10.4)));
+ void g(void) __attribute__((availability(macosx,introduced=10.4))); // okay, matches
+ void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform
+ void g(void); // okay, inherits both macosx and ios availability from above.
+ void g(void) __attribute__((availability(macosx,introduced=10.5))); // error: mismatch
+
+When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,:
+
+.. code-block:: objc
+
+ @interface A
+ - (id)method __attribute__((availability(macosx,introduced=10.4)));
+ - (id)method2 __attribute__((availability(macosx,introduced=10.4)));
+ @end
+
+ @interface B : A
+ - (id)method __attribute__((availability(macosx,introduced=10.3))); // okay: method moved into base class later
+ - (id)method __attribute__((availability(macosx,introduced=10.5))); // error: this method was available via the base class in 10.4
+ @end
+
+
+_Noreturn
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "","","","X"
+
+A function declared as ``_Noreturn`` shall not return to its caller. The
+compiler will generate a diagnostic for a function declared as ``_Noreturn``
+that appears to be capable of returning to its caller.
+
+
+noreturn
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "","X","",""
+
+A function declared as ``[[noreturn]]`` shall not return to its caller. The
+compiler will generate a diagnostic for a function declared as ``[[noreturn]]``
+that appears to be capable of returning to its caller.
+
+
+carries_dependency
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","X","",""
+
+The ``carries_dependency`` attribute specifies dependency propagation into and
+out of functions.
+
+When specified on a function or Objective-C method, the ``carries_depedency``
+attribute means that the return value carries a dependency out of the function,
+so that the implementation need not constrain ordering upon return from that
+function. Implementations of the function and its caller may choose to preserve
+dependencies instead of emitting memory ordering instructions such as fences.
+
+Note, this attribute does not change the meaning of the program, but may result
+in generatation of more efficient code.
+
+
+enable_if
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+The ``enable_if`` attribute can be placed on function declarations to control
+which overload is selected based on the values of the function's arguments.
+When combined with the ``overloadable`` attribute, this feature is also
+available in C.
+
+.. code-block:: c++
+
+ int isdigit(int c);
+ int isdigit(int c) __attribute__((enable_if(c <= -1 || c > 255, "chosen when 'c' is out of range"))) __attribute__((unavailable("'c' must have the value of an unsigned char or EOF")));
+
+ void foo(char c) {
+ isdigit(c);
+ isdigit(10);
+ isdigit(-10); // results in a compile-time error.
+ }
+
+The enable_if attribute takes two arguments, the first is an expression written
+in terms of the function parameters, the second is a string explaining why this
+overload candidate could not be selected to be displayed in diagnostics. The
+expression is part of the function signature for the purposes of determining
+whether it is a redeclaration (following the rules used when determining
+whether a C++ template specialization is ODR-equivalent), but is not part of
+the type.
+
+The enable_if expression is evaluated as if it were the body of a
+bool-returning constexpr function declared with the arguments of the function
+it is being applied to, then called with the parameters at the callsite. If the
+result is false or could not be determined through constant expression
+evaluation, then this overload will not be chosen and the provided string may
+be used in a diagnostic if the compile fails as a result.
+
+Because the enable_if expression is an unevaluated context, there are no global
+state changes, nor the ability to pass information from the enable_if
+expression to the function body. For example, suppose we want calls to
+strnlen(strbuf, maxlen) to resolve to strnlen_chk(strbuf, maxlen, size of
+strbuf) only if the size of strbuf can be determined:
+
+.. code-block:: c++
+
+ __attribute__((always_inline))
+ static inline size_t strnlen(const char *s, size_t maxlen)
+ __attribute__((overloadable))
+ __attribute__((enable_if(__builtin_object_size(s, 0) != -1))),
+ "chosen when the buffer size is known but 'maxlen' is not")))
+ {
+ return strnlen_chk(s, maxlen, __builtin_object_size(s, 0));
+ }
+
+Multiple enable_if attributes may be applied to a single declaration. In this
+case, the enable_if expressions are evaluated from left to right in the
+following manner. First, the candidates whose enable_if expressions evaluate to
+false or cannot be evaluated are discarded. If the remaining candidates do not
+share ODR-equivalent enable_if expressions, the overload resolution is
+ambiguous. Otherwise, enable_if overload resolution continues with the next
+enable_if attribute on the candidates that have not been discarded and have
+remaining enable_if attributes. In this way, we pick the most specific
+overload out of a number of viable overloads using enable_if.
+
+.. code-block:: c++
+
+ void f() __attribute__((enable_if(true, ""))); // #1
+ void f() __attribute__((enable_if(true, ""))) __attribute__((enable_if(true, ""))); // #2
+
+ void g(int i, int j) __attribute__((enable_if(i, ""))); // #1
+ void g(int i, int j) __attribute__((enable_if(j, ""))) __attribute__((enable_if(true))); // #2
+
+In this example, a call to f() is always resolved to #2, as the first enable_if
+expression is ODR-equivalent for both declarations, but #1 does not have another
+enable_if expression to continue evaluating, so the next round of evaluation has
+only a single candidate. In a call to g(1, 1), the call is ambiguous even though
+#2 has more enable_if attributes, because the first enable_if expressions are
+not ODR-equivalent.
+
+Query for this feature with ``__has_attribute(enable_if)``.
+
+
+format (gnu::format)
+--------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","X","",""
+
+Clang supports the ``format`` attribute, which indicates that the function
+accepts a ``printf`` or ``scanf``-like format string and corresponding
+arguments or a ``va_list`` that contains these arguments.
+
+Please see `GCC documentation about format attribute
+<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ to find details
+about attribute syntax.
+
+Clang implements two kinds of checks with this attribute.
+
+#. Clang checks that the function with the ``format`` attribute is called with
+ a format string that uses format specifiers that are allowed, and that
+ arguments match the format string. This is the ``-Wformat`` warning, it is
+ on by default.
+
+#. Clang checks that the format string argument is a literal string. This is
+ the ``-Wformat-nonliteral`` warning, it is off by default.
+
+ Clang implements this mostly the same way as GCC, but there is a difference
+ for functions that accept a ``va_list`` argument (for example, ``vprintf``).
+ GCC does not emit ``-Wformat-nonliteral`` warning for calls to such
+ fuctions. Clang does not warn if the format string comes from a function
+ parameter, where the function is annotated with a compatible attribute,
+ otherwise it warns. For example:
+
+ .. code-block:: c
+
+ __attribute__((__format__ (__scanf__, 1, 3)))
+ void foo(const char* s, char *buf, ...) {
+ va_list ap;
+ va_start(ap, buf);
+
+ vprintf(s, ap); // warning: format string is not a string literal
+ }
+
+ In this case we warn because ``s`` contains a format string for a
+ ``scanf``-like function, but it is passed to a ``printf``-like function.
+
+ If the attribute is removed, clang still warns, because the format string is
+ not a string literal.
+
+ Another example:
+
+ .. code-block:: c
+
+ __attribute__((__format__ (__printf__, 1, 3)))
+ void foo(const char* s, char *buf, ...) {
+ va_list ap;
+ va_start(ap, buf);
+
+ vprintf(s, ap); // warning
+ }
+
+ In this case Clang does not warn because the format string ``s`` and
+ the corresponding arguments are annotated. If the arguments are
+ incorrect, the caller of ``foo`` will receive a warning.
+
+
+noduplicate (clang::noduplicate)
+--------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","X","",""
+
+The ``noduplicate`` attribute can be placed on function declarations to control
+whether function calls to this function can be duplicated or not as a result of
+optimizations. This is required for the implementation of functions with
+certain special requirements, like the OpenCL "barrier" function, that might
+need to be run concurrently by all the threads that are executing in lockstep
+on the hardware. For example this attribute applied on the function
+"nodupfunc" in the code below avoids that:
+
+.. code-block:: c
+
+ void nodupfunc() __attribute__((noduplicate));
+ // Setting it as a C++11 attribute is also valid
+ // void nodupfunc() [[clang::noduplicate]];
+ void foo();
+ void bar();
+
+ nodupfunc();
+ if (a > n) {
+ foo();
+ } else {
+ bar();
+ }
+
+gets possibly modified by some optimizations into code similar to this:
+
+.. code-block:: c
+
+ if (a > n) {
+ nodupfunc();
+ foo();
+ } else {
+ nodupfunc();
+ bar();
+ }
+
+where the call to "nodupfunc" is duplicated and sunk into the two branches
+of the condition.
+
+
+no_sanitize_address (no_address_safety_analysis, gnu::no_address_safety_analysis, gnu::no_sanitize_address)
+-----------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","X","",""
+
+.. _langext-address_sanitizer:
+
+Use ``__attribute__((no_sanitize_address))`` on a function declaration to
+specify that address safety instrumentation (e.g. AddressSanitizer) should
+not be applied to that function.
+
+
+no_sanitize_memory
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+.. _langext-memory_sanitizer:
+
+Use ``__attribute__((no_sanitize_memory))`` on a function declaration to
+specify that checks for uninitialized memory should not be inserted
+(e.g. by MemorySanitizer). The function may still be instrumented by the tool
+to avoid false positives in other places.
+
+
+no_sanitize_thread
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+.. _langext-thread_sanitizer:
+
+Use ``__attribute__((no_sanitize_thread))`` on a function declaration to
+specify that checks for data races on plain (non-atomic) memory accesses should
+not be inserted by ThreadSanitizer. The function is still instrumented by the
+tool to avoid false positives and provide meaningful stack traces.
+
+
+objc_method_family
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Many methods in Objective-C have conventional meanings determined by their
+selectors. It is sometimes useful to be able to mark a method as having a
+particular conventional meaning despite not having the right selector, or as
+not having the conventional meaning that its selector would suggest. For these
+use cases, we provide an attribute to specifically describe the "method family"
+that a method belongs to.
+
+**Usage**: ``__attribute__((objc_method_family(X)))``, where ``X`` is one of
+``none``, ``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``. This
+attribute can only be placed at the end of a method declaration:
+
+.. code-block:: objc
+
+ - (NSString *)initMyStringValue __attribute__((objc_method_family(none)));
+
+Users who do not wish to change the conventional meaning of a method, and who
+merely want to document its non-standard retain and release semantics, should
+use the retaining behavior attributes (``ns_returns_retained``,
+``ns_returns_not_retained``, etc).
+
+Query for this feature with ``__has_attribute(objc_method_family)``.
+
+
+objc_requires_super
+-------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Some Objective-C classes allow a subclass to override a particular method in a
+parent class but expect that the overriding method also calls the overridden
+method in the parent class. For these cases, we provide an attribute to
+designate that a method requires a "call to ``super``" in the overriding
+method in the subclass.
+
+**Usage**: ``__attribute__((objc_requires_super))``. This attribute can only
+be placed at the end of a method declaration:
+
+.. code-block:: objc
+
+ - (void)foo __attribute__((objc_requires_super));
+
+This attribute can only be applied the method declarations within a class, and
+not a protocol. Currently this attribute does not enforce any placement of
+where the call occurs in the overriding method (such as in the case of
+``-dealloc`` where the call must appear at the end). It checks only that it
+exists.
+
+Note that on both OS X and iOS that the Foundation framework provides a
+convenience macro ``NS_REQUIRES_SUPER`` that provides syntactic sugar for this
+attribute:
+
+.. code-block:: objc
+
+ - (void)foo NS_REQUIRES_SUPER;
+
+This macro is conditionally defined depending on the compiler's support for
+this attribute. If the compiler does not support the attribute the macro
+expands to nothing.
+
+Operationally, when a method has this annotation the compiler will warn if the
+implementation of an override in a subclass does not call super. For example:
+
+.. code-block:: objc
+
+ warning: method possibly missing a [super AnnotMeth] call
+ - (void) AnnotMeth{};
+ ^
+
+
+overloadable
+------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Clang provides support for C++ function overloading in C. Function overloading
+in C is introduced using the ``overloadable`` attribute. For example, one
+might provide several overloaded versions of a ``tgsin`` function that invokes
+the appropriate standard function computing the sine of a value with ``float``,
+``double``, or ``long double`` precision:
+
+.. code-block:: c
+
+ #include <math.h>
+ float __attribute__((overloadable)) tgsin(float x) { return sinf(x); }
+ double __attribute__((overloadable)) tgsin(double x) { return sin(x); }
+ long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); }
+
+Given these declarations, one can call ``tgsin`` with a ``float`` value to
+receive a ``float`` result, with a ``double`` to receive a ``double`` result,
+etc. Function overloading in C follows the rules of C++ function overloading
+to pick the best overload given the call arguments, with a few C-specific
+semantics:
+
+* Conversion from ``float`` or ``double`` to ``long double`` is ranked as a
+ floating-point promotion (per C99) rather than as a floating-point conversion
+ (as in C++).
+
+* A conversion from a pointer of type ``T*`` to a pointer of type ``U*`` is
+ considered a pointer conversion (with conversion rank) if ``T`` and ``U`` are
+ compatible types.
+
+* A conversion from type ``T`` to a value of type ``U`` is permitted if ``T``
+ and ``U`` are compatible types. This conversion is given "conversion" rank.
+
+The declaration of ``overloadable`` functions is restricted to function
+declarations and definitions. Most importantly, if any function with a given
+name is given the ``overloadable`` attribute, then all function declarations
+and definitions with that name (and in that scope) must have the
+``overloadable`` attribute. This rule even applies to redeclarations of
+functions whose original declaration had the ``overloadable`` attribute, e.g.,
+
+.. code-block:: c
+
+ int f(int) __attribute__((overloadable));
+ float f(float); // error: declaration of "f" must have the "overloadable" attribute
+
+ int g(int) __attribute__((overloadable));
+ int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute
+
+Functions marked ``overloadable`` must have prototypes. Therefore, the
+following code is ill-formed:
+
+.. code-block:: c
+
+ int h() __attribute__((overloadable)); // error: h does not have a prototype
+
+However, ``overloadable`` functions are allowed to use a ellipsis even if there
+are no named parameters (as is permitted in C++). This feature is particularly
+useful when combined with the ``unavailable`` attribute:
+
+.. code-block:: c++
+
+ void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error
+
+Functions declared with the ``overloadable`` attribute have their names mangled
+according to the same rules as C++ function names. For example, the three
+``tgsin`` functions in our motivating example get the mangled names
+``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively. There are two
+caveats to this use of name mangling:
+
+* Future versions of Clang may change the name mangling of functions overloaded
+ in C, so you should not depend on an specific mangling. To be completely
+ safe, we strongly urge the use of ``static inline`` with ``overloadable``
+ functions.
+
+* The ``overloadable`` attribute has almost no meaning when used in C++,
+ because names will already be mangled and functions are already overloadable.
+ However, when an ``overloadable`` function occurs within an ``extern "C"``
+ linkage specification, it's name *will* be mangled in the same way as it
+ would in C.
+
+Query for this feature with ``__has_extension(attribute_overloadable)``.
+
+
+release_capability (release_shared_capability, clang::release_capability, clang::release_shared_capability)
+-----------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","X","",""
+
+Marks a function as releasing a capability.
+
+
+try_acquire_capability (try_acquire_shared_capability, clang::try_acquire_capability, clang::try_acquire_shared_capability)
+---------------------------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","X","",""
+
+Marks a function that attempts to acquire a capability. This function may fail to
+actually acquire the capability; they accept a Boolean value determining
+whether acquiring the capability means success (true), or failing to acquire
+the capability means success (false).
+
+
+Variable Attributes
+===================
+
+
+tls_model (gnu::tls_model)
+--------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","X","",""
+
+The ``tls_model`` attribute allows you to specify which thread-local storage
+model to use. It accepts the following strings:
+
+* global-dynamic
+* local-dynamic
+* initial-exec
+* local-exec
+
+TLS models are mutually exclusive.
+
+
+Type Attributes
+===============
+
+
+__single_inhertiance, __multiple_inheritance, __virtual_inheritance
+-------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "","","","X"
+
+This collection of keywords is enabled under ``-fms-extensions`` and controls
+the pointer-to-member representation used on ``*-*-win32`` targets.
+
+The ``*-*-win32`` targets utilize a pointer-to-member representation which
+varies in size and alignment depending on the definition of the underlying
+class.
+
+However, this is problematic when a forward declaration is only available and
+no definition has been made yet. In such cases, Clang is forced to utilize the
+most general representation that is available to it.
+
+These keywords make it possible to use a pointer-to-member representation other
+than the most general one regardless of whether or not the definition will ever
+be present in the current translation unit.
+
+This family of keywords belong between the ``class-key`` and ``class-name``:
+
+.. code-block:: c++
+
+ struct __single_inheritance S;
+ int S::*i;
+ struct S {};
+
+This keyword can be applied to class templates but only has an effect when used
+on full specializations:
+
+.. code-block:: c++
+
+ template <typename T, typename U> struct __single_inheritance A; // warning: inheritance model ignored on primary template
+ template <typename T> struct __multiple_inheritance A<T, T>; // warning: inheritance model ignored on partial specialization
+ template <> struct __single_inheritance A<int, float>;
+
+Note that choosing an inheritance model less general than strictly necessary is
+an error:
+
+.. code-block:: c++
+
+ struct __multiple_inheritance S; // error: inheritance model does not match definition
+ int S::*i;
+ struct S {};
+
+
+Statement Attributes
+====================
+
+
+fallthrough (clang::fallthrough)
+--------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "","X","",""
+
+The ``clang::fallthrough`` attribute is used along with the
+``-Wimplicit-fallthrough`` argument to annotate intentional fall-through
+between switch labels. It can only be applied to a null statement placed at a
+point of execution between any statement and the next switch label. It is
+common to mark these places with a specific comment, but this attribute is
+meant to replace comments with a more strict annotation, which can be checked
+by the compiler. This attribute doesn't change semantics of the code and can
+be used wherever an intended fall-through occurs. It is designed to mimic
+control-flow statements like ``break;``, so it can be placed in most places
+where ``break;`` can, but only if there are no statements on the execution path
+between it and the next switch label.
+
+Here is an example:
+
+.. code-block:: c++
+
+ // compile with -Wimplicit-fallthrough
+ switch (n) {
+ case 22:
+ case 33: // no warning: no statements between case labels
+ f();
+ case 44: // warning: unannotated fall-through
+ g();
+ [[clang::fallthrough]];
+ case 55: // no warning
+ if (x) {
+ h();
+ break;
+ }
+ else {
+ i();
+ [[clang::fallthrough]];
+ }
+ case 66: // no warning
+ p();
+ [[clang::fallthrough]]; // warning: fallthrough annotation does not
+ // directly precede case label
+ q();
+ case 77: // warning: unannotated fall-through
+ r();
+ }
+
+
+Consumed Annotation Checking
+============================
+Clang supports additional attributes for checking basic resource management
+properties, specifically for unique objects that have a single owning reference.
+The following attributes are currently supported, although **the implementation
+for these annotations is currently in development and are subject to change.**
+
+callable_when
+-------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Use ``__attribute__((callable_when(...)))`` to indicate what states a method
+may be called in. Valid states are unconsumed, consumed, or unknown. Each
+argument to this attribute must be a quoted string. E.g.:
+
+``__attribute__((callable_when("unconsumed", "unknown")))``
+
+
+consumable
+----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Each ``class`` that uses any of the typestate annotations must first be marked
+using the ``consumable`` attribute. Failure to do so will result in a warning.
+
+This attribute accepts a single parameter that must be one of the following:
+``unknown``, ``consumed``, or ``unconsumed``.
+
+
+param_typestate
+---------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+This attribute specifies expectations about function parameters. Calls to an
+function with annotated parameters will issue a warning if the corresponding
+argument isn't in the expected state. The attribute is also used to set the
+initial state of the parameter when analyzing the function's body.
+
+
+return_typestate
+----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+The ``return_typestate`` attribute can be applied to functions or parameters.
+When applied to a function the attribute specifies the state of the returned
+value. The function's body is checked to ensure that it always returns a value
+in the specified state. On the caller side, values returned by the annotated
+function are initialized to the given state.
+
+When applied to a function parameter it modifies the state of an argument after
+a call to the function returns. The function's body is checked to ensure that
+the parameter is in the expected state before returning.
+
+
+set_typestate
+-------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Annotate methods that transition an object into a new state with
+``__attribute__((set_typestate(new_state)))``. The new new state must be
+unconsumed, consumed, or unknown.
+
+
+test_typestate
+--------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Use ``__attribute__((test_typestate(tested_state)))`` to indicate that a method
+returns true if the object is in the specified state..
+
+
+Type Safety Checking
+====================
+Clang supports additional attributes to enable checking type safety properties
+that can't be enforced by the C type system. Use cases include:
+
+* MPI library implementations, where these attributes enable checking that
+ the buffer type matches the passed ``MPI_Datatype``;
+* for HDF5 library there is a similar use case to MPI;
+* checking types of variadic functions' arguments for functions like
+ ``fcntl()`` and ``ioctl()``.
+
+You can detect support for these attributes with ``__has_attribute()``. For
+example:
+
+.. code-block:: c++
+
+ #if defined(__has_attribute)
+ # if __has_attribute(argument_with_type_tag) && \
+ __has_attribute(pointer_with_type_tag) && \
+ __has_attribute(type_tag_for_datatype)
+ # define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx)))
+ /* ... other macros ... */
+ # endif
+ #endif
+
+ #if !defined(ATTR_MPI_PWT)
+ # define ATTR_MPI_PWT(buffer_idx, type_idx)
+ #endif
+
+ int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
+ ATTR_MPI_PWT(1,3);
+
+argument_with_type_tag
+----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Use ``__attribute__((argument_with_type_tag(arg_kind, arg_idx,
+type_tag_idx)))`` on a function declaration to specify that the function
+accepts a type tag that determines the type of some other argument.
+``arg_kind`` is an identifier that should be used when annotating all
+applicable type tags.
+
+This attribute is primarily useful for checking arguments of variadic functions
+(``pointer_with_type_tag`` can be used in most non-variadic cases).
+
+For example:
+
+.. code-block:: c++
+
+ int fcntl(int fd, int cmd, ...)
+ __attribute__(( argument_with_type_tag(fcntl,3,2) ));
+
+
+pointer_with_type_tag
+---------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Use ``__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, type_tag_idx)))``
+on a function declaration to specify that the function accepts a type tag that
+determines the pointee type of some other pointer argument.
+
+For example:
+
+.. code-block:: c++
+
+ int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
+ __attribute__(( pointer_with_type_tag(mpi,1,3) ));
+
+
+type_tag_for_datatype
+---------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","","",""
+
+Clang supports annotating type tags of two forms.
+
+* **Type tag that is an expression containing a reference to some declared
+ identifier.** Use ``__attribute__((type_tag_for_datatype(kind, type)))`` on a
+ declaration with that identifier:
+
+ .. code-block:: c++
+
+ extern struct mpi_datatype mpi_datatype_int
+ __attribute__(( type_tag_for_datatype(mpi,int) ));
+ #define MPI_INT ((MPI_Datatype) &mpi_datatype_int)
+
+* **Type tag that is an integral literal.** Introduce a ``static const``
+ variable with a corresponding initializer value and attach
+ ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration,
+ for example:
+
+ .. code-block:: c++
+
+ #define MPI_INT ((MPI_Datatype) 42)
+ static const MPI_Datatype mpi_datatype_int
+ __attribute__(( type_tag_for_datatype(mpi,int) )) = 42
+
+The attribute also accepts an optional third argument that determines how the
+expression is compared to the type tag. There are two supported flags:
+
+* ``layout_compatible`` will cause types to be compared according to
+ layout-compatibility rules (C++11 [class.mem] p 17, 18). This is
+ implemented to support annotating types like ``MPI_DOUBLE_INT``.
+
+ For example:
+
+ .. code-block:: c++
+
+ /* In mpi.h */
+ struct internal_mpi_double_int { double d; int i; };
+ extern struct mpi_datatype mpi_datatype_double_int
+ __attribute__(( type_tag_for_datatype(mpi, struct internal_mpi_double_int, layout_compatible) ));
+
+ #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int)
+
+ /* In user code */
+ struct my_pair { double a; int b; };
+ struct my_pair *buffer;
+ MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning
+
+ struct my_int_pair { int a; int b; }
+ struct my_int_pair *buffer2;
+ MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning: actual buffer element
+ // type 'struct my_int_pair'
+ // doesn't match specified MPI_Datatype
+
+* ``must_be_null`` specifies that the expression should be a null pointer
+ constant, for example:
+
+ .. code-block:: c++
+
+ /* In mpi.h */
+ extern struct mpi_datatype mpi_datatype_null
+ __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) ));
+
+ #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null)
+
+ /* In user code */
+ MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL
+ // was specified but buffer
+ // is not a null pointer
+
+
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index 8528c7a..635ea1f 100644
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -22,6 +22,31 @@
set(extra_search_mappings "")
endif()
+ # If asked, configure doxygen for the creation of a Qt Compressed Help file.
+ if (LLVM_ENABLE_DOXYGEN_QT_HELP)
+ set(CLANG_DOXYGEN_QCH_FILENAME "org.llvm.clang.qch" CACHE STRING
+ "Filename of the Qt Compressed help file")
+ set(CLANG_DOXYGEN_QHP_NAMESPACE "org.llvm.clang" CACHE STRING
+ "Namespace under which the intermediate Qt Help Project file lives")
+ set(CLANG_DOXYGEN_QHP_CUST_FILTER_NAME "Clang ${CLANG_VERSION}" CACHE STRING
+ "See http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters")
+ set(CLANG_DOXYGEN_QHP_CUST_FILTER_ATTRS "Clang,${CLANG_VERSION}" CACHE STRING
+ "See http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes")
+ set(clang_doxygen_generate_qhp "YES")
+ set(clang_doxygen_qch_filename "${CLANG_DOXYGEN_QCH_FILENAME}")
+ set(clang_doxygen_qhp_namespace "${CLANG_DOXYGEN_QHP_NAMESPACE}")
+ set(clang_doxygen_qhelpgenerator_path "${LLVM_DOXYGEN_QHELPGENERATOR_PATH}")
+ set(clang_doxygen_qhp_cust_filter_name "${CLANG_DOXYGEN_QHP_CUST_FILTER_NAME}")
+ set(clang_doxygen_qhp_cust_filter_attrs "${CLANG_DOXYGEN_QHP_CUST_FILTER_ATTRS}")
+ else()
+ set(clang_doxygen_generate_qhp "NO")
+ set(clang_doxygen_qch_filename "")
+ set(clang_doxygen_qhp_namespace "")
+ set(clang_doxygen_qhelpgenerator_path "")
+ set(clang_doxygen_qhp_cust_filter_name "")
+ set(clang_doxygen_qhp_cust_filter_attrs "")
+ endif()
+
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in
${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @ONLY)
@@ -33,6 +58,12 @@
set(enable_server_based_search)
set(enable_external_search)
set(extra_search_mappings)
+ set(clang_doxygen_generate_qhp)
+ set(clang_doxygen_qch_filename)
+ set(clang_doxygen_qhp_namespace)
+ set(clang_doxygen_qhelpgenerator_path)
+ set(clang_doxygen_qhp_cust_filter_name)
+ set(clang_doxygen_qhp_cust_filter_attrs)
add_custom_target(doxygen-clang
COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg
diff --git a/docs/ClangFormat.rst b/docs/ClangFormat.rst
index bc6b8a2..3f8499b 100644
--- a/docs/ClangFormat.rst
+++ b/docs/ClangFormat.rst
@@ -146,7 +146,7 @@
Visual Studio Integration
=========================
-Download the latest Visual Studio plugin from the `alpha build site
+Download the latest Visual Studio extension from the `alpha build site
<http://llvm.org/builds/>`_. The default key-binding is Ctrl-R,Ctrl-F.
@@ -158,21 +158,24 @@
.. code-block:: console
- usage: clang-format-diff.py [-h] [-p P] [-style STYLE]
+ usage: clang-format-diff.py [-h] [-i] [-p NUM] [-regex PATTERN] [-style STYLE]
- Reformat changed lines in diff.
+ Reformat changed lines in diff. Without -i option just output the diff that
+ would be introduced.
optional arguments:
- -h, --help show this help message and exit
- -p P strip the smallest prefix containing P slashes
- -style STYLE formatting style to apply (LLVM, Google, Chromium, Mozilla,
- WebKit)
+ -h, --help show this help message and exit
+ -i apply edits to files instead of displaying a diff
+ -p NUM strip the smallest prefix containing P slashes
+ -regex PATTERN custom pattern selecting file paths to reformat
+ -style STYLE formatting style to apply (LLVM, Google, Chromium, Mozilla,
+ WebKit)
So to reformat all the lines in the latest :program:`git` commit, just do:
.. code-block:: console
- git diff -U0 HEAD^ | clang-format-diff.py -p1
+ git diff -U0 HEAD^ | clang-format-diff.py -i -p1
The :option:`-U0` will create a diff without context lines (the script would format
those as well).
diff --git a/docs/ClangFormatStyleOptions.rst b/docs/ClangFormatStyleOptions.rst
index d73801c..db77372 100644
--- a/docs/ClangFormatStyleOptions.rst
+++ b/docs/ClangFormatStyleOptions.rst
@@ -106,6 +106,10 @@
Allow putting all parameters of a function declaration onto
the next line even if ``BinPackParameters`` is ``false``.
+**AllowShortFunctionsOnASingleLine** (``bool``)
+ If ``true``, ``int f() { return 0; }`` can be put on a single
+ line.
+
**AllowShortIfStatementsOnASingleLine** (``bool``)
If ``true``, ``if (a) return;`` can be put on a single
line.
@@ -142,8 +146,15 @@
Like ``Attach``, but break before function definitions.
* ``BS_Allman`` (in configuration: ``Allman``)
Always break before braces.
+ * ``BS_GNU`` (in configuration: ``GNU``)
+ Always break before braces and add an extra level of indentation to
+ braces of control statements, not to those of class, function
+ or other definitions.
+**BreakBeforeTernaryOperators** (``bool``)
+ If ``true``, ternary operators will be placed after line breaks.
+
**BreakConstructorInitializersBeforeComma** (``bool``)
Always break constructor initializers before commas and align
the commas with the colon.
@@ -153,7 +164,11 @@
A column limit of ``0`` means that there is no column limit. In this case,
clang-format will respect the input's line breaking decisions within
- statements.
+ statements unless they contradict other rules.
+
+**CommentPragmas** (``std::string``)
+ A regular expression that describes comments with special meaning,
+ which should not be split into lines or otherwise changed.
**ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``)
If the constructor initializers don't fit on a line, put each
@@ -163,6 +178,9 @@
The number of characters to use for indentation of constructor
initializer lists.
+**ContinuationIndentWidth** (``unsigned``)
+ Indent width for line continuations.
+
**Cpp11BracedListStyle** (``bool``)
If ``true``, format braced lists as best suited for C++11 braced
lists.
@@ -179,7 +197,8 @@
a zero-length name is assumed.
**DerivePointerBinding** (``bool``)
- If ``true``, analyze the formatted file for the most common binding.
+ If ``true``, analyze the formatted file for the most common binding
+ and use ``PointerBindsToType`` only as fallback.
**ExperimentalAutoDetectBinPacking** (``bool``)
If ``true``, clang-format detects whether function calls and
@@ -193,6 +212,14 @@
NOTE: This is an experimental flag, that might go away or be renamed. Do
not use this in config files, etc. Use at your own risk.
+**ForEachMacros** (``std::vector<std::string>``)
+ A list of macros that should be interpreted as foreach loops instead of as
+ function calls.
+
+ For example, ``ForEachMacros: [BOOST_FOREACH, Q_FOREACH]`` tells
+ clang-format to treat ``BOOST_FOREACH`` and ``Q_FOREACH`` as loop control
+ statements.
+
**IndentCaseLabels** (``bool``)
Indent case labels one level from the switch statement.
@@ -206,6 +233,22 @@
**IndentWidth** (``unsigned``)
The number of columns to use for indentation.
+**Language** (``LanguageKind``)
+ Language, this format style is targeted at.
+
+ Possible values:
+
+ * ``LK_None`` (in configuration: ``None``)
+ Do not use.
+ * ``LK_Cpp`` (in configuration: ``Cpp``)
+ Should be used for C, C++, ObjectiveC, ObjectiveC++.
+ * ``LK_JavaScript`` (in configuration: ``JavaScript``)
+ Should be used for JavaScript.
+ * ``LK_Proto`` (in configuration: ``Proto``)
+ Should be used for Protocol Buffers
+ (https://developers.google.com/protocol-buffers/).
+
+
**MaxEmptyLinesToKeep** (``unsigned``)
The maximum number of consecutive empty lines to keep.
@@ -222,10 +265,17 @@
Indent in all namespaces.
+**ObjCSpaceAfterProperty** (``bool``)
+ Add a space after ``@property`` in Objective-C, i.e. use
+ ``@property (readonly)`` instead of ``@property(readonly)``.
+
**ObjCSpaceBeforeProtocolList** (``bool``)
Add a space in front of an Objective-C protocol list, i.e. use
``Foo <Protocol>`` instead of ``Foo<Protocol>``.
+**PenaltyBreakBeforeFirstCallParameter** (``unsigned``)
+ The penalty for breaking a function call after "call(".
+
**PenaltyBreakComment** (``unsigned``)
The penalty for each line break introduced inside a comment.
@@ -245,25 +295,45 @@
**PointerBindsToType** (``bool``)
Set whether & and * bind to the type as opposed to the variable.
-**SpaceAfterControlStatementKeyword** (``bool``)
- If ``true``, spaces will be inserted between 'for'/'if'/'while'/...
- and '('.
-
**SpaceBeforeAssignmentOperators** (``bool``)
If ``false``, spaces will be removed before assignment operators.
+**SpaceBeforeParens** (``SpaceBeforeParensOptions``)
+ Defines in which cases to put a space before opening parentheses.
+
+ Possible values:
+
+ * ``SBPO_Never`` (in configuration: ``Never``)
+ Never put a space before opening parentheses.
+ * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``)
+ Put a space before opening parentheses only after control statement
+ keywords (``for/if/while...``).
+ * ``SBPO_Always`` (in configuration: ``Always``)
+ Always put a space before opening parentheses, except when it's
+ prohibited by the syntax rules (in function-like macro definitions) or
+ when determined by other style rules (after unary operators, opening
+ parentheses, etc.)
+
+
**SpaceInEmptyParentheses** (``bool``)
- If ``false``, spaces may be inserted into '()'.
+ If ``true``, spaces may be inserted into '()'.
**SpacesBeforeTrailingComments** (``unsigned``)
The number of spaces to before trailing line comments.
+**SpacesInAngles** (``bool``)
+ If ``true``, spaces will be inserted after '<' and before '>' in
+ template argument lists
+
**SpacesInCStyleCastParentheses** (``bool``)
- If ``false``, spaces may be inserted into C style casts.
+ If ``true``, spaces may be inserted into C style casts.
+
+**SpacesInContainerLiterals** (``bool``)
+ If ``true``, spaces are inserted inside container literals (e.g.
+ ObjC and Javascript array and dict literals).
**SpacesInParentheses** (``bool``)
- If ``true``, spaces will be inserted after every '(' and before
- every ')'.
+ If ``true``, spaces will be inserted after '(' and before ')'.
**Standard** (``LanguageStandard``)
Format compatible with this standard, e.g. use
diff --git a/docs/ClangPlugins.rst b/docs/ClangPlugins.rst
index 7c5c65c..9a5bc14 100644
--- a/docs/ClangPlugins.rst
+++ b/docs/ClangPlugins.rst
@@ -47,70 +47,10 @@
=======================
Let's look at an example plugin that prints top-level function names. This
-example is also checked into the clang repository; please also take a look at
-the latest `checked in version of PrintFunctionNames.cpp
+example is checked into the clang repository; please take a look at
+the `latest version of PrintFunctionNames.cpp
<http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/PrintFunctionNames.cpp?view=markup>`_.
-.. code-block:: c++
-
- #include "clang/Frontend/FrontendPluginRegistry.h"
- #include "clang/AST/ASTConsumer.h"
- #include "clang/AST/AST.h"
- #include "clang/Frontend/CompilerInstance.h"
- #include "llvm/Support/raw_ostream.h"
- using namespace clang;
-
- namespace {
-
- class PrintFunctionsConsumer : public ASTConsumer {
- public:
- virtual bool HandleTopLevelDecl(DeclGroupRef DG) {
- for (DeclGroupRef::iterator i = DG.begin(), e = DG.end(); i != e; ++i) {
- const Decl *D = *i;
- if (const NamedDecl *ND = dyn_cast<NamedDecl>(D))
- llvm::errs() << "top-level-decl: \"" << ND->getNameAsString() << "\"\n";
- }
-
- return true;
- }
- };
-
- class PrintFunctionNamesAction : public PluginASTAction {
- protected:
- ASTConsumer *CreateASTConsumer(CompilerInstance &CI, llvm::StringRef) {
- return new PrintFunctionsConsumer();
- }
-
- bool ParseArgs(const CompilerInstance &CI,
- const std::vector<std::string>& args) {
- for (unsigned i = 0, e = args.size(); i != e; ++i) {
- llvm::errs() << "PrintFunctionNames arg = " << args[i] << "\n";
-
- // Example error handling.
- if (args[i] == "-an-error") {
- DiagnosticsEngine &D = CI.getDiagnostics();
- unsigned DiagID = D.getCustomDiagID(
- DiagnosticsEngine::Error, "invalid argument '" + args[i] + "'");
- D.Report(DiagID);
- return false;
- }
- }
- if (args.size() && args[0] == "help")
- PrintHelp(llvm::errs());
-
- return true;
- }
- void PrintHelp(llvm::raw_ostream& ros) {
- ros << "Help for PrintFunctionNames plugin goes here\n";
- }
-
- };
-
- }
-
- static FrontendPluginRegistry::Add<PrintFunctionNamesAction>
- X("print-fns", "print function names");
-
Running the plugin
==================
diff --git a/docs/ClangTools.rst b/docs/ClangTools.rst
index f8a7c36..8957541 100644
--- a/docs/ClangTools.rst
+++ b/docs/ClangTools.rst
@@ -93,9 +93,9 @@
refactoring tools, e.g. to do a reformatting of all the lines changed during a
renaming.
-``cpp11-migrate``
-~~~~~~~~~~~~~~~~~
-``cpp11-migrate`` migrates C++ code to use C++11 features where appropriate.
+``clang-modernize``
+~~~~~~~~~~~~~~~~~~~
+``clang-modernize`` migrates C++ code to use C++11 features where appropriate.
Currently it can:
* convert loops to range-based for loops;
diff --git a/docs/ExternalClangExamples.rst b/docs/ExternalClangExamples.rst
index c7fd4c5..71d50c2 100644
--- a/docs/ExternalClangExamples.rst
+++ b/docs/ExternalClangExamples.rst
@@ -78,3 +78,10 @@
"cldoc is a Clang based documentation generator for C and C++.
cldoc tries to solve the issue of writing C/C++ software documentation
with a modern, non-intrusive and robust approach."
+
+`<https://github.com/AlexDenisov/ToyClangPlugin>`_
+ "The simplest Clang plugin implementing a semantic check for Objective-C.
+ This example shows how to use the ``DiagnosticsEngine`` (emit warnings,
+ errors, fixit hints). See also `<http://l.rw.rw/clang_plugin>`_ for
+ step-by-step instructions."
+
diff --git a/docs/InternalsManual.rst b/docs/InternalsManual.rst
index 6f55702..5830a7e 100644
--- a/docs/InternalsManual.rst
+++ b/docs/InternalsManual.rst
@@ -87,7 +87,8 @@
Since the enum is referenced in the C++ code that produces the diagnostic, it
is somewhat useful for it to be reasonably short.
-The severity of the diagnostic comes from the set {``NOTE``, ``WARNING``,
+The severity of the diagnostic comes from the set {``NOTE``, ``REMARK``,
+``WARNING``,
``EXTENSION``, ``EXTWARN``, ``ERROR``}. The ``ERROR`` severity is used for
diagnostics indicating the program is never acceptable under any circumstances.
When an error is emitted, the AST for the input code may not be fully built.
@@ -97,11 +98,13 @@
code is non-portable. The difference is that the former are ignored by
default, and the later warn by default. The ``WARNING`` severity is used for
constructs that are valid in the currently selected source language but that
-are dubious in some way. The ``NOTE`` level is used to staple more information
-onto previous diagnostics.
+are dubious in some way. The ``REMARK`` severity provides generic information
+about the compilation that is not necessarily related to any dubious code. The
+``NOTE`` level is used to staple more information onto previous diagnostics.
These *severities* are mapped into a smaller set (the ``Diagnostic::Level``
-enum, {``Ignored``, ``Note``, ``Warning``, ``Error``, ``Fatal``}) of output
+enum, {``Ignored``, ``Note``, ``Remark``, ``Warning``, ``Error``, ``Fatal``}) of
+output
*levels* by the diagnostics subsystem based on various configuration options.
Clang internally supports a fully fine grained mapping mechanism that allows
you to map almost any diagnostic to the output level that you want. The only
@@ -1588,47 +1591,171 @@
How to add an attribute
-----------------------
-To add an attribute, you'll have to add it to the list of attributes, add it to
-the parsing phase, and look for it in the AST scan.
-`r124217 <http://llvm.org/viewvc/llvm-project?view=rev&revision=124217>`_
-has a good example of adding a warning attribute.
+Attribute Basics
+^^^^^^^^^^^^^^^^
-(Beware that this hasn't been reviewed/fixed by the people who designed the
-attributes system yet.)
+Attributes in clang come in two forms: parsed form, and semantic form. Both
+forms are represented via a tablegen definition of the attribute, specified in
+Attr.td.
``include/clang/Basic/Attr.td``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-First, add your attribute to the `include/clang/Basic/Attr.td file
-<http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/Attr.td?view=markup>`_.
+First, add your attribute to the `include/clang/Basic/Attr.td
+<http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/Attr.td?view=markup>`_
+file.
Each attribute gets a ``def`` inheriting from ``Attr`` or one of its
subclasses. ``InheritableAttr`` means that the attribute also applies to
-subsequent declarations of the same name.
+subsequent declarations of the same name. ``InheritableParamAttr`` is similar
+to ``InheritableAttr``, except that the attribute is written on a parameter
+instead of a declaration, type or statement. Attributes inheriting from
+``TypeAttr`` are pure type attributes which generally are not given a
+representation in the AST. Attributes inheriting from ``TargetSpecificAttr``
+are attributes specific to one or more target architectures. An attribute that
+inherits from ``IgnoredAttr`` is parsed, but will generate an ignored attribute
+diagnostic when used. The attribute type may be useful when an attribute is
+supported by another vendor, but not supported by clang.
``Spellings`` lists the strings that can appear in ``__attribute__((here))`` or
-``[[here]]``. All such strings will be synonymous. If you want to allow the
-``[[]]`` C++11 syntax, you have to define a list of ``Namespaces``, which will
-let users write ``[[namespace::spelling]]``. Using the empty string for a
-namespace will allow users to write just the spelling with no "``::``".
-Attributes which g++-4.8 accepts should also have a
-``CXX11<"gnu", "spelling">`` spelling.
+``[[here]]``. All such strings will be synonymous. Possible ``Spellings``
+are: ``GNU`` (for use with GNU-style __attribute__ spellings), ``Declspec``
+(for use with Microsoft Visual Studio-style __declspec spellings), ``CXX11`
+(for use with C++11-style [[foo]] and [[foo::bar]] spellings), and ``Keyword``
+(for use with attributes that are implemented as keywords, like C++11's
+``override`` or ``final``). If you want to allow the ``[[]]`` C++11 syntax, you
+have to define a list of ``Namespaces``, which will let users write
+``[[namespace::spelling]]``. Using the empty string for a namespace will allow
+users to write just the spelling with no "``::``". Attributes which g++-4.8
+or later accepts should also have a ``CXX11<"gnu", "spelling">`` spelling.
``Subjects`` restricts what kinds of AST node to which this attribute can
-appertain (roughly, attach).
+appertain (roughly, attach). The subjects are specified via a ``SubjectList``,
+which specify the list of subjects. Additionally, subject-related diagnostics
+can be specified to be warnings or errors, with the default being a warning.
+The diagnostics displayed to the user are automatically determined based on
+the subjects in the list, but a custom diagnostic parameter can also be
+specified in the ``SubjectList``. The diagnostics generated for subject list
+violations are either ``diag::warn_attribute_wrong_decl_type`` or
+``diag::err_attribute_wrong_decl_type``, and the parameter enumeration is
+found in `include/clang/Sema/AttributeList.h
+<http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Sema/AttributeList.h?view=markup>`_
+If you add new Decl nodes to the ``SubjectList``, you may need to update the
+logic used to automatically determine the diagnostic parameter in `utils/TableGen/ClangAttrEmitter.cpp
+<http://llvm.org/viewvc/llvm-project/cfe/trunk/utils/TableGen/ClangAttrEmitter.cpp?view=markup>`_.
+
+Diagnostic checking for attribute subject lists is automated except when
+``HasCustomParsing`` is set to ``1``.
+
+By default, all subjects in the SubjectList must either be a Decl node defined
+in ``DeclNodes.td``, or a statement node defined in ``StmtNodes.td``. However,
+more complex subjects can be created by creating a ``SubsetSubject`` object.
+Each such object has a base subject which it appertains to (which must be a
+Decl or Stmt node, and not a SubsetSubject node), and some custom code which is
+called when determining whether an attribute appertains to the subject. For
+instance, a ``NonBitField`` SubsetSubject appertains to a ``FieldDecl``, and
+tests whether the given FieldDecl is a bit field. When a SubsetSubject is
+specified in a SubjectList, a custom diagnostic parameter must also be provided.
``Args`` names the arguments the attribute takes, in order. If ``Args`` is
``[StringArgument<"Arg1">, IntArgument<"Arg2">]`` then
-``__attribute__((myattribute("Hello", 3)))`` will be a valid use.
+``__attribute__((myattribute("Hello", 3)))`` will be a valid use. Attribute
+arguments specify both the parsed form and the semantic form of the attribute.
+The previous example shows an attribute which requires two attributes while
+parsing, and the Attr subclass' constructor for the attribute will require a
+string and integer argument.
+
+Diagnostic checking for argument counts is automated except when
+``HasCustomParsing`` is set to ``1``, or when the attribute uses an optional or
+variadic argument. Diagnostic checking for argument semantics is not automated.
+
+If the parsed form of the attribute is more complex, or differs from the
+semantic form, the ``HasCustomParsing`` bit can be set to ``1`` for the class,
+and the parsing code in `Parser::ParseGNUAttributeArgs
+<http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/Parse/ParseDecl.cpp?view=markup>`_
+can be updated for the special case. Note that this only applies to arguments
+with a GNU spelling -- attributes with a __declspec spelling currently ignore
+this flag and are handled by ``Parser::ParseMicrosoftDeclSpec``.
+
+Custom accessors can be generated for an attribute based on the spelling list
+for that attribute. For instance, if an attribute has two different spellings:
+'Foo' and 'Bar', accessors can be created:
+``[Accessor<"isFoo", [GNU<"Foo">]>, Accessor<"isBar", [GNU<"Bar">]>]``
+These accessors will be generated on the semantic form of the attribute,
+accepting no arguments and returning a Boolean.
+
+Attributes which do not require an AST node should set the ``ASTNode`` field to
+``0`` to avoid polluting the AST. Note that anything inheriting from
+``TypeAttr`` or ``IgnoredAttr`` automatically do not generate an AST node. All
+other attributes generate an AST node by default. The AST node is the semantic
+representation of the attribute.
+
+Attributes which do not require custom semantic handling should set the
+``SemaHandler`` field to ``0``. Note that anything inheriting from
+``IgnoredAttr`` automatically do not get a semantic handler. All other
+attributes are assumed to use a semantic handler by default. Attributes
+without a semantic handler are not given a parsed attribute Kind enumeration.
+
+The ``LangOpts`` field can be used to specify a list of language options
+required by the attribute. For instance, all of the CUDA-specific attributes
+specify ``[CUDA]`` for the ``LangOpts`` field, and when the CUDA language
+option is not enabled, an "attribute ignored" warning diagnostic is emitted.
+Since language options are not table generated nodes, new language options must
+be created manually and should specify the spelling used by ``LangOptions`` class.
+
+Target-specific attribute sometimes share a spelling with other attributes in
+different targets. For instance, the ARM and MSP430 targets both have an
+attribute spelled ``GNU<"interrupt">``, but with different parsing and semantic
+requirements. To support this feature, an attribute inheriting from
+``TargetSpecificAttribute`` make specify a ``ParseKind`` field. This field
+should be the same value between all arguments sharing a spelling, and
+corresponds to the parsed attribute's Kind enumeration. This allows attributes
+to share a parsed attribute kind, but have distinct semantic attribute classes.
+For instance, ``AttributeList::AT_Interrupt`` is the shared parsed attribute
+kind, but ARMInterruptAttr and MSP430InterruptAttr are the semantic attributes
+generated.
+
+By default, when declarations are merging attributes, an attribute will not be
+duplicated. However, if an attribute can be duplicated during this merging
+stage, set ``DuplicatesAllowedWhileMerging`` to ``1``, and the attribute will
+be merged.
+
+By default, attribute arguments are parsed in an evaluated context. If the
+arguments for an attribute should be parsed in an unevaluated context (akin to
+the way the argument to a ``sizeof`` expression is parsed), you can set
+``ParseArgumentsAsUnevaluated`` to ``1``.
+
+If additional functionality is desired for the semantic form of the attribute,
+the ``AdditionalMembers`` field specifies code to be copied verbatim into the
+semantic attribute class object.
+
+All attributes must have one or more form of documentation, which is provided
+in the ``Documentation`` list. Generally, the documentation for an attribute
+is a stand-alone definition in `include/clang/Basic/AttrDocs.td
+<http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/AttdDocs.td?view=markup>`_
+that is named after the attribute being documented. Each documentation element
+is given a ``Category`` (variable, function, or type) and ``Content``. A single
+attribute may contain multiple documentation elements for distinct categories.
+For instance, an attribute which can appertain to both function and types (such
+as a calling convention attribute), should contain two documentation elements.
+The ``Content`` for an attribute uses reStructuredText (RST) syntax.
+
+If an attribute is used internally by the compiler, but is not written by users
+(such as attributes with an empty spelling list), it can use the
+``Undocumented`` documentation element.
Boilerplate
^^^^^^^^^^^
-Write a new ``HandleYourAttr()`` function in `lib/Sema/SemaDeclAttr.cpp
-<http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/Sema/SemaDeclAttr.cpp?view=markup>`_,
-and add a case to the switch in ``ProcessNonInheritableDeclAttr()`` or
-``ProcessInheritableDeclAttr()`` forwarding to it.
+All semantic processing of declaration attributes happens in `lib/Sema/SemaDeclAttr.cpp
+<http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/Sema/SemaDeclAttr.cpp?view=markup>`_,
+and generally starts in the ``ProcessDeclAttribute`` function. If your
+attribute is a "simple" attribute -- meaning that it requires no custom
+semantic processing aside from what is automatically provided for you, you can
+add a call to ``handleSimpleAttribute<YourAttr>(S, D, Attr);`` to the switch
+statement. Otherwise, write a new ``handleYourAttr()`` function, and add that
+to the switch statement.
If your attribute causes extra warnings to fire, define a ``DiagGroup`` in
`include/clang/Basic/DiagnosticGroups.td
@@ -1638,6 +1765,10 @@
``InGroup<DiagGroup<"your-attribute">>`` directly in `DiagnosticSemaKinds.td
<http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/DiagnosticSemaKinds.td?view=markup>`_
+All semantic diagnostics generated for your attribute, including automatically-
+generated ones (such as subjects and argument counts), should have a
+corresponding test case.
+
The meat of your attribute
^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/docs/LanguageExtensions.rst b/docs/LanguageExtensions.rst
index 7a4b31e..392e679 100644
--- a/docs/LanguageExtensions.rst
+++ b/docs/LanguageExtensions.rst
@@ -12,7 +12,7 @@
ObjectiveCLiterals
BlockLanguageSpec
Block-ABI-Apple
- AutomaticReferenceCounting
+ AutomaticReferenceCounting
Introduction
============
@@ -113,8 +113,8 @@
-------------------
This function-like macro takes a single identifier argument that is the name of
-an attribute. It evaluates to 1 if the attribute is supported or 0 if not. It
-can be used like this:
+an attribute. It evaluates to 1 if the attribute is supported by the current
+compilation target, or 0 if not. It can be used like this:
.. code-block:: c++
@@ -134,6 +134,7 @@
(double underscore) to avoid interference from a macro with the same name. For
instance, ``__always_inline__`` can be used instead of ``always_inline``.
+
Include File Checking Macros
============================
@@ -425,103 +426,6 @@
framework search path. For consistency, we recommend that such files never be
included in installed versions of the framework.
-Availability attribute
-======================
-
-Clang introduces the ``availability`` attribute, which can be placed on
-declarations to describe the lifecycle of that declaration relative to
-operating system versions. Consider the function declaration for a
-hypothetical function ``f``:
-
-.. code-block:: c++
-
- void f(void) __attribute__((availability(macosx,introduced=10.4,deprecated=10.6,obsoleted=10.7)));
-
-The availability attribute states that ``f`` was introduced in Mac OS X 10.4,
-deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7. This information
-is used by Clang to determine when it is safe to use ``f``: for example, if
-Clang is instructed to compile code for Mac OS X 10.5, a call to ``f()``
-succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the call
-succeeds but Clang emits a warning specifying that the function is deprecated.
-Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call
-fails because ``f()`` is no longer available.
-
-The availability attribute is a comma-separated list starting with the
-platform name and then including clauses specifying important milestones in the
-declaration's lifetime (in any order) along with additional information. Those
-clauses can be:
-
-introduced=\ *version*
- The first version in which this declaration was introduced.
-
-deprecated=\ *version*
- The first version in which this declaration was deprecated, meaning that
- users should migrate away from this API.
-
-obsoleted=\ *version*
- The first version in which this declaration was obsoleted, meaning that it
- was removed completely and can no longer be used.
-
-unavailable
- This declaration is never available on this platform.
-
-message=\ *string-literal*
- Additional message text that Clang will provide when emitting a warning or
- error about use of a deprecated or obsoleted declaration. Useful to direct
- users to replacement APIs.
-
-Multiple availability attributes can be placed on a declaration, which may
-correspond to different platforms. Only the availability attribute with the
-platform corresponding to the target platform will be used; any others will be
-ignored. If no availability attribute specifies availability for the current
-target platform, the availability attributes are ignored. Supported platforms
-are:
-
-``ios``
- Apple's iOS operating system. The minimum deployment target is specified by
- the ``-mios-version-min=*version*`` or ``-miphoneos-version-min=*version*``
- command-line arguments.
-
-``macosx``
- Apple's Mac OS X operating system. The minimum deployment target is
- specified by the ``-mmacosx-version-min=*version*`` command-line argument.
-
-A declaration can be used even when deploying back to a platform version prior
-to when the declaration was introduced. When this happens, the declaration is
-`weakly linked
-<https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html>`_,
-as if the ``weak_import`` attribute were added to the declaration. A
-weakly-linked declaration may or may not be present a run-time, and a program
-can determine whether the declaration is present by checking whether the
-address of that declaration is non-NULL.
-
-If there are multiple declarations of the same entity, the availability
-attributes must either match on a per-platform basis or later
-declarations must not have availability attributes for that
-platform. For example:
-
-.. code-block:: c
-
- void g(void) __attribute__((availability(macosx,introduced=10.4)));
- void g(void) __attribute__((availability(macosx,introduced=10.4))); // okay, matches
- void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform
- void g(void); // okay, inherits both macosx and ios availability from above.
- void g(void) __attribute__((availability(macosx,introduced=10.5))); // error: mismatch
-
-When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,:
-
-.. code-block:: objc
-
- @interface A
- - (id)method __attribute__((availability(macosx,introduced=10.4)));
- - (id)method2 __attribute__((availability(macosx,introduced=10.4)));
- @end
-
- @interface B : A
- - (id)method __attribute__((availability(macosx,introduced=10.3))); // okay: method moved into base class later
- - (id)method __attribute__((availability(macosx,introduced=10.5))); // error: this method was available via the base class in 10.4
- @end
-
Checks for Standard Language Features
=====================================
@@ -830,7 +734,6 @@
``__has_extension(cxx_init_capture)`` to determine if support for
lambda captures with explicit initializers is enabled
(for instance, ``[n(0)] { return ++n; }``).
-Clang does not yet support this feature.
C++1y generic lambdas
^^^^^^^^^^^^^^^^^^^^^
@@ -839,7 +742,6 @@
``__has_extension(cxx_generic_lambda)`` to determine if support for generic
(polymorphic) lambdas is enabled
(for instance, ``[] (auto x) { return x + 1; }``).
-Clang does not yet support this feature.
C++1y relaxed constexpr
^^^^^^^^^^^^^^^^^^^^^^^
@@ -872,7 +774,6 @@
Use ``__has_feature(cxx_variable_templates)`` or
``__has_extension(cxx_variable_templates)`` to determine if support for
templated variable declarations is enabled.
-Clang does not yet support this feature.
C11
---
@@ -924,15 +825,33 @@
Use ``__has_feature(c_thread_local)`` or ``__has_extension(c_thread_local)``
to determine if support for ``_Thread_local`` variables is enabled.
-Checks for Type Traits
-======================
+Checks for Type Trait Primitives
+================================
+
+Type trait primitives are special builtin constant expressions that can be used
+by the standard C++ library to facilitate or simplify the implementation of
+user-facing type traits in the <type_traits> header.
+
+They are not intended to be used directly by user code because they are
+implementation-defined and subject to change -- as such they're tied closely to
+the supported set of system headers, currently:
+
+* LLVM's own libc++
+* GNU libstdc++
+* The Microsoft standard C++ library
Clang supports the `GNU C++ type traits
<http://gcc.gnu.org/onlinedocs/gcc/Type-Traits.html>`_ and a subset of the
`Microsoft Visual C++ Type traits
-<http://msdn.microsoft.com/en-us/library/ms177194(v=VS.100).aspx>`_. For each
-supported type trait ``__X``, ``__has_extension(X)`` indicates the presence of
-the type trait. For example:
+<http://msdn.microsoft.com/en-us/library/ms177194(v=VS.100).aspx>`_.
+
+Feature detection is supported only for some of the primitives at present. User
+code should not use these checks because they bear no direct relation to the
+actual set of type traits supported by the C++ standard library.
+
+For type trait ``__X``, ``__has_extension(X)`` indicates the presence of the
+type trait primitive in the compiler. A simplistic usage example as might be
+seen in standard C++ headers follows:
.. code-block:: c++
@@ -942,10 +861,10 @@
static const bool value = __is_convertible_to(From, To);
};
#else
- // Emulate type trait
+ // Emulate type trait for compatibility with other compilers.
#endif
-The following type traits are supported by Clang:
+The following type trait primitives are supported by Clang:
* ``__has_nothrow_assign`` (GNU, Microsoft)
* ``__has_nothrow_copy`` (GNU, Microsoft)
@@ -980,6 +899,11 @@
``argtypes...`` such that no non-trivial functions are called as part of
that initialization. This trait is required to implement the C++11 standard
library.
+* ``__is_destructible`` (MSVC 2013): partially implemented
+* ``__is_nothrow_destructible`` (MSVC 2013): partially implemented
+* ``__is_nothrow_assignable`` (MSVC 2013, clang)
+* ``__is_constructible`` (MSVC 2013, clang)
+* ``__is_nothrow_constructible`` (MSVC 2013, clang)
Blocks
======
@@ -1174,77 +1098,6 @@
``__has_feature(objc_default_synthesize_properties)`` checks for availability
of this feature in version of clang being used.
-.. _langext-objc_method_family:
-
-
-Objective-C requiring a call to ``super`` in an override
---------------------------------------------------------
-
-Some Objective-C classes allow a subclass to override a particular method in a
-parent class but expect that the overriding method also calls the overridden
-method in the parent class. For these cases, we provide an attribute to
-designate that a method requires a "call to ``super``" in the overriding
-method in the subclass.
-
-**Usage**: ``__attribute__((objc_requires_super))``. This attribute can only
-be placed at the end of a method declaration:
-
-.. code-block:: objc
-
- - (void)foo __attribute__((objc_requires_super));
-
-This attribute can only be applied the method declarations within a class, and
-not a protocol. Currently this attribute does not enforce any placement of
-where the call occurs in the overriding method (such as in the case of
-``-dealloc`` where the call must appear at the end). It checks only that it
-exists.
-
-Note that on both OS X and iOS that the Foundation framework provides a
-convenience macro ``NS_REQUIRES_SUPER`` that provides syntactic sugar for this
-attribute:
-
-.. code-block:: objc
-
- - (void)foo NS_REQUIRES_SUPER;
-
-This macro is conditionally defined depending on the compiler's support for
-this attribute. If the compiler does not support the attribute the macro
-expands to nothing.
-
-Operationally, when a method has this annotation the compiler will warn if the
-implementation of an override in a subclass does not call super. For example:
-
-.. code-block:: objc
-
- warning: method possibly missing a [super AnnotMeth] call
- - (void) AnnotMeth{};
- ^
-
-Objective-C Method Families
----------------------------
-
-Many methods in Objective-C have conventional meanings determined by their
-selectors. It is sometimes useful to be able to mark a method as having a
-particular conventional meaning despite not having the right selector, or as
-not having the conventional meaning that its selector would suggest. For these
-use cases, we provide an attribute to specifically describe the "method family"
-that a method belongs to.
-
-**Usage**: ``__attribute__((objc_method_family(X)))``, where ``X`` is one of
-``none``, ``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``. This
-attribute can only be placed at the end of a method declaration:
-
-.. code-block:: objc
-
- - (NSString *)initMyStringValue __attribute__((objc_method_family(none)));
-
-Users who do not wish to change the conventional meaning of a method, and who
-merely want to document its non-standard retain and release semantics, should
-use the :ref:`retaining behavior attributes <langext-objc-retain-release>`
-described below.
-
-Query for this feature with ``__has_attribute(objc_method_family)``.
-
.. _langext-objc-retain-release:
Objective-C retaining behavior attributes
@@ -1257,8 +1110,7 @@
return values. However, there are exceptions, and so Clang provides attributes
to allow these exceptions to be documented. This are used by ARC and the
`static analyzer <http://clang-analyzer.llvm.org>`_ Some exceptions may be
-better described using the :ref:`objc_method_family
-<langext-objc_method_family>` attribute instead.
+better described using the ``objc_method_family`` attribute instead.
**Usage**: The ``ns_returns_retained``, ``ns_returns_not_retained``,
``ns_returns_autoreleased``, ``cf_returns_retained``, and
@@ -1315,87 +1167,7 @@
Query the presence of this new mangling with
``__has_feature(objc_protocol_qualifier_mangling)``.
-Function Overloading in C
-=========================
-
-Clang provides support for C++ function overloading in C. Function overloading
-in C is introduced using the ``overloadable`` attribute. For example, one
-might provide several overloaded versions of a ``tgsin`` function that invokes
-the appropriate standard function computing the sine of a value with ``float``,
-``double``, or ``long double`` precision:
-
-.. code-block:: c
-
- #include <math.h>
- float __attribute__((overloadable)) tgsin(float x) { return sinf(x); }
- double __attribute__((overloadable)) tgsin(double x) { return sin(x); }
- long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); }
-
-Given these declarations, one can call ``tgsin`` with a ``float`` value to
-receive a ``float`` result, with a ``double`` to receive a ``double`` result,
-etc. Function overloading in C follows the rules of C++ function overloading
-to pick the best overload given the call arguments, with a few C-specific
-semantics:
-
-* Conversion from ``float`` or ``double`` to ``long double`` is ranked as a
- floating-point promotion (per C99) rather than as a floating-point conversion
- (as in C++).
-
-* A conversion from a pointer of type ``T*`` to a pointer of type ``U*`` is
- considered a pointer conversion (with conversion rank) if ``T`` and ``U`` are
- compatible types.
-
-* A conversion from type ``T`` to a value of type ``U`` is permitted if ``T``
- and ``U`` are compatible types. This conversion is given "conversion" rank.
-
-The declaration of ``overloadable`` functions is restricted to function
-declarations and definitions. Most importantly, if any function with a given
-name is given the ``overloadable`` attribute, then all function declarations
-and definitions with that name (and in that scope) must have the
-``overloadable`` attribute. This rule even applies to redeclarations of
-functions whose original declaration had the ``overloadable`` attribute, e.g.,
-
-.. code-block:: c
-
- int f(int) __attribute__((overloadable));
- float f(float); // error: declaration of "f" must have the "overloadable" attribute
-
- int g(int) __attribute__((overloadable));
- int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute
-
-Functions marked ``overloadable`` must have prototypes. Therefore, the
-following code is ill-formed:
-
-.. code-block:: c
-
- int h() __attribute__((overloadable)); // error: h does not have a prototype
-
-However, ``overloadable`` functions are allowed to use a ellipsis even if there
-are no named parameters (as is permitted in C++). This feature is particularly
-useful when combined with the ``unavailable`` attribute:
-
-.. code-block:: c++
-
- void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error
-
-Functions declared with the ``overloadable`` attribute have their names mangled
-according to the same rules as C++ function names. For example, the three
-``tgsin`` functions in our motivating example get the mangled names
-``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively. There are two
-caveats to this use of name mangling:
-
-* Future versions of Clang may change the name mangling of functions overloaded
- in C, so you should not depend on an specific mangling. To be completely
- safe, we strongly urge the use of ``static inline`` with ``overloadable``
- functions.
-
-* The ``overloadable`` attribute has almost no meaning when used in C++,
- because names will already be mangled and functions are already overloadable.
- However, when an ``overloadable`` function occurs within an ``extern "C"``
- linkage specification, it's name *will* be mangled in the same way as it
- would in C.
-
-Query for this feature with ``__has_extension(attribute_overloadable)``.
+.. _langext-overloading:
Initializer lists for complex numbers in C
==========================================
@@ -1774,7 +1546,7 @@
void __builtin_arm_clrex(void);
The types ``T`` currently supported are:
-* Integer types with width at most 64 bits.
+* Integer types with width at most 64 bits (or 128 bits on ARM64).
* Floating-point types
* Pointer types.
@@ -1798,55 +1570,7 @@
Clang's non-standard C++11 attributes live in the ``clang`` attribute
namespace.
-The ``clang::fallthrough`` attribute
-------------------------------------
-
-The ``clang::fallthrough`` attribute is used along with the
-``-Wimplicit-fallthrough`` argument to annotate intentional fall-through
-between switch labels. It can only be applied to a null statement placed at a
-point of execution between any statement and the next switch label. It is
-common to mark these places with a specific comment, but this attribute is
-meant to replace comments with a more strict annotation, which can be checked
-by the compiler. This attribute doesn't change semantics of the code and can
-be used wherever an intended fall-through occurs. It is designed to mimic
-control-flow statements like ``break;``, so it can be placed in most places
-where ``break;`` can, but only if there are no statements on the execution path
-between it and the next switch label.
-
-Here is an example:
-
-.. code-block:: c++
-
- // compile with -Wimplicit-fallthrough
- switch (n) {
- case 22:
- case 33: // no warning: no statements between case labels
- f();
- case 44: // warning: unannotated fall-through
- g();
- [[clang::fallthrough]];
- case 55: // no warning
- if (x) {
- h();
- break;
- }
- else {
- i();
- [[clang::fallthrough]];
- }
- case 66: // no warning
- p();
- [[clang::fallthrough]]; // warning: fallthrough annotation does not
- // directly precede case label
- q();
- case 77: // warning: unannotated fall-through
- r();
- }
-
-``gnu::`` attributes
---------------------
-
-Clang also supports GCC's ``gnu`` attribute namespace. All GCC attributes which
+Clang supports GCC's ``gnu`` attribute namespace. All GCC attributes which
are accepted with the ``__attribute__((foo))`` syntax are also accepted as
``[[gnu::foo]]``. This only extends to attributes which are specified by GCC
(see the list of `GCC function attributes
@@ -1902,48 +1626,6 @@
movl %gs:(%eax), %eax
ret
-ARM Language Extensions
------------------------
-
-Interrupt attribute
-^^^^^^^^^^^^^^^^^^^
-
-Clang supports the GNU style ``__attribute__((interrupt("TYPE")))`` attribute on
-ARM targets. This attribute may be attached to a function definition and
-instructs the backend to generate appropriate function entry/exit code so that
-it can be used directly as an interrupt service routine.
-
- The parameter passed to the interrupt attribute is optional, but if
-provided it must be a string literal with one of the following values: "IRQ",
-"FIQ", "SWI", "ABORT", "UNDEF".
-
-The semantics are as follows:
-
-- If the function is AAPCS, Clang instructs the backend to realign the stack to
- 8 bytes on entry. This is a general requirement of the AAPCS at public
- interfaces, but may not hold when an exception is taken. Doing this allows
- other AAPCS functions to be called.
-- If the CPU is M-class this is all that needs to be done since the architecture
- itself is designed in such a way that functions obeying the normal AAPCS ABI
- constraints are valid exception handlers.
-- If the CPU is not M-class, the prologue and epilogue are modified to save all
- non-banked registers that are used, so that upon return the user-mode state
- will not be corrupted. Note that to avoid unnecessary overhead, only
- general-purpose (integer) registers are saved in this way. If VFP operations
- are needed, that state must be saved manually.
-
- Specifically, interrupt kinds other than "FIQ" will save all core registers
- except "lr" and "sp". "FIQ" interrupts will save r0-r7.
-- If the CPU is not M-class, the return instruction is changed to one of the
- canonical sequences permitted by the architecture for exception return. Where
- possible the function itself will make the necessary "lr" adjustments so that
- the "preferred return address" is selected.
-
- Unfortunately the compiler is unable to make this guarantee for an "UNDEF"
- handler, where the offset from "lr" to the preferred return address depends on
- the execution state of the code which generated the exception. In this case
- a sequence equivalent to "movs pc, lr" will be used.
-
Extensions for Static Analysis
==============================
@@ -1957,450 +1639,11 @@
Extensions for Dynamic Analysis
===============================
-.. _langext-address_sanitizer:
-
-AddressSanitizer
-----------------
-
Use ``__has_feature(address_sanitizer)`` to check if the code is being built
with :doc:`AddressSanitizer`.
-Use ``__attribute__((no_sanitize_address))``
-on a function declaration
-to specify that address safety instrumentation (e.g. AddressSanitizer) should
-not be applied to that function.
-
-.. _langext-thread_sanitizer:
-
-ThreadSanitizer
-----------------
-
Use ``__has_feature(thread_sanitizer)`` to check if the code is being built
with :doc:`ThreadSanitizer`.
-Use ``__attribute__((no_sanitize_thread))`` on a function declaration
-to specify that checks for data races on plain (non-atomic) memory accesses
-should not be inserted by ThreadSanitizer.
-The function is still instrumented by the tool to avoid false positives and
-provide meaningful stack traces.
-
-.. _langext-memory_sanitizer:
-
-MemorySanitizer
-----------------
Use ``__has_feature(memory_sanitizer)`` to check if the code is being built
with :doc:`MemorySanitizer`.
-
-Use ``__attribute__((no_sanitize_memory))`` on a function declaration
-to specify that checks for uninitialized memory should not be inserted
-(e.g. by MemorySanitizer). The function may still be instrumented by the tool
-to avoid false positives in other places.
-
-
-Thread-Safety Annotation Checking
-=================================
-
-Clang supports additional attributes for checking basic locking policies in
-multithreaded programs. Clang currently parses the following list of
-attributes, although **the implementation for these annotations is currently in
-development.** For more details, see the `GCC implementation
-<http://gcc.gnu.org/wiki/ThreadSafetyAnnotation>`_.
-
-``no_thread_safety_analysis``
------------------------------
-
-Use ``__attribute__((no_thread_safety_analysis))`` on a function declaration to
-specify that the thread safety analysis should not be run on that function.
-This attribute provides an escape hatch (e.g. for situations when it is
-difficult to annotate the locking policy).
-
-``lockable``
-------------
-
-Use ``__attribute__((lockable))`` on a class definition to specify that it has
-a lockable type (e.g. a Mutex class). This annotation is primarily used to
-check consistency.
-
-``scoped_lockable``
--------------------
-
-Use ``__attribute__((scoped_lockable))`` on a class definition to specify that
-it has a "scoped" lockable type. Objects of this type will acquire the lock
-upon construction and release it upon going out of scope. This annotation is
-primarily used to check consistency.
-
-``guarded_var``
----------------
-
-Use ``__attribute__((guarded_var))`` on a variable declaration to specify that
-the variable must be accessed while holding some lock.
-
-``pt_guarded_var``
-------------------
-
-Use ``__attribute__((pt_guarded_var))`` on a pointer declaration to specify
-that the pointer must be dereferenced while holding some lock.
-
-``guarded_by(l)``
------------------
-
-Use ``__attribute__((guarded_by(l)))`` on a variable declaration to specify
-that the variable must be accessed while holding lock ``l``.
-
-``pt_guarded_by(l)``
---------------------
-
-Use ``__attribute__((pt_guarded_by(l)))`` on a pointer declaration to specify
-that the pointer must be dereferenced while holding lock ``l``.
-
-``acquired_before(...)``
-------------------------
-
-Use ``__attribute__((acquired_before(...)))`` on a declaration of a lockable
-variable to specify that the lock must be acquired before all attribute
-arguments. Arguments must be lockable type, and there must be at least one
-argument.
-
-``acquired_after(...)``
------------------------
-
-Use ``__attribute__((acquired_after(...)))`` on a declaration of a lockable
-variable to specify that the lock must be acquired after all attribute
-arguments. Arguments must be lockable type, and there must be at least one
-argument.
-
-``exclusive_lock_function(...)``
---------------------------------
-
-Use ``__attribute__((exclusive_lock_function(...)))`` on a function declaration
-to specify that the function acquires all listed locks exclusively. This
-attribute takes zero or more arguments: either of lockable type or integers
-indexing into function parameters of lockable type. If no arguments are given,
-the acquired lock is implicitly ``this`` of the enclosing object.
-
-``shared_lock_function(...)``
------------------------------
-
-Use ``__attribute__((shared_lock_function(...)))`` on a function declaration to
-specify that the function acquires all listed locks, although the locks may be
-shared (e.g. read locks). This attribute takes zero or more arguments: either
-of lockable type or integers indexing into function parameters of lockable
-type. If no arguments are given, the acquired lock is implicitly ``this`` of
-the enclosing object.
-
-``exclusive_trylock_function(...)``
------------------------------------
-
-Use ``__attribute__((exclusive_lock_function(...)))`` on a function declaration
-to specify that the function will try (without blocking) to acquire all listed
-locks exclusively. This attribute takes one or more arguments. The first
-argument is an integer or boolean value specifying the return value of a
-successful lock acquisition. The remaining arugments are either of lockable
-type or integers indexing into function parameters of lockable type. If only
-one argument is given, the acquired lock is implicitly ``this`` of the
-enclosing object.
-
-``shared_trylock_function(...)``
---------------------------------
-
-Use ``__attribute__((shared_lock_function(...)))`` on a function declaration to
-specify that the function will try (without blocking) to acquire all listed
-locks, although the locks may be shared (e.g. read locks). This attribute
-takes one or more arguments. The first argument is an integer or boolean value
-specifying the return value of a successful lock acquisition. The remaining
-arugments are either of lockable type or integers indexing into function
-parameters of lockable type. If only one argument is given, the acquired lock
-is implicitly ``this`` of the enclosing object.
-
-``unlock_function(...)``
-------------------------
-
-Use ``__attribute__((unlock_function(...)))`` on a function declaration to
-specify that the function release all listed locks. This attribute takes zero
-or more arguments: either of lockable type or integers indexing into function
-parameters of lockable type. If no arguments are given, the acquired lock is
-implicitly ``this`` of the enclosing object.
-
-``lock_returned(l)``
---------------------
-
-Use ``__attribute__((lock_returned(l)))`` on a function declaration to specify
-that the function returns lock ``l`` (``l`` must be of lockable type). This
-annotation is used to aid in resolving lock expressions.
-
-``locks_excluded(...)``
------------------------
-
-Use ``__attribute__((locks_excluded(...)))`` on a function declaration to
-specify that the function must not be called with the listed locks. Arguments
-must be lockable type, and there must be at least one argument.
-
-``exclusive_locks_required(...)``
----------------------------------
-
-Use ``__attribute__((exclusive_locks_required(...)))`` on a function
-declaration to specify that the function must be called while holding the
-listed exclusive locks. Arguments must be lockable type, and there must be at
-least one argument.
-
-``shared_locks_required(...)``
-------------------------------
-
-Use ``__attribute__((shared_locks_required(...)))`` on a function declaration
-to specify that the function must be called while holding the listed shared
-locks. Arguments must be lockable type, and there must be at least one
-argument.
-
-Consumed Annotation Checking
-============================
-
-Clang supports additional attributes for checking basic resource management
-properties, specifically for unique objects that have a single owning reference.
-The following attributes are currently supported, although **the implementation
-for these annotations is currently in development and are subject to change.**
-
-``consumable``
---------------
-
-Each class that uses any of the following annotations must first be marked
-using the consumable attribute. Failure to do so will result in a warning.
-
-``set_typestate(new_state)``
-----------------------------
-
-Annotate methods that transition an object into a new state with
-``__attribute__((set_typestate(new_state)))``. The new new state must be
-unconsumed, consumed, or unknown.
-
-``callable_when(...)``
-----------------------
-
-Use ``__attribute__((callable_when(...)))`` to indicate what states a method
-may be called in. Valid states are unconsumed, consumed, or unknown. Each
-argument to this attribute must be a quoted string. E.g.:
-
-``__attribute__((callable_when("unconsumed", "unknown")))``
-
-``tests_typestate(tested_state)``
----------------------------------
-
-Use ``__attribute__((tests_typestate(tested_state)))`` to indicate that a method
-returns true if the object is in the specified state..
-
-``param_typestate(expected_state)``
------------------------------------
-
-This attribute specifies expectations about function parameters. Calls to an
-function with annotated parameters will issue a warning if the corresponding
-argument isn't in the expected state. The attribute is also used to set the
-initial state of the parameter when analyzing the function's body.
-
-``return_typestate(ret_state)``
--------------------------------
-
-The ``return_typestate`` attribute can be applied to functions or parameters.
-When applied to a function the attribute specifies the state of the returned
-value. The function's body is checked to ensure that it always returns a value
-in the specified state. On the caller side, values returned by the annotated
-function are initialized to the given state.
-
-If the attribute is applied to a function parameter it modifies the state of
-an argument after a call to the function returns. The function's body is
-checked to ensure that the parameter is in the expected state before returning.
-
-Type Safety Checking
-====================
-
-Clang supports additional attributes to enable checking type safety properties
-that can't be enforced by the C type system. Use cases include:
-
-* MPI library implementations, where these attributes enable checking that
- the buffer type matches the passed ``MPI_Datatype``;
-* for HDF5 library there is a similar use case to MPI;
-* checking types of variadic functions' arguments for functions like
- ``fcntl()`` and ``ioctl()``.
-
-You can detect support for these attributes with ``__has_attribute()``. For
-example:
-
-.. code-block:: c++
-
- #if defined(__has_attribute)
- # if __has_attribute(argument_with_type_tag) && \
- __has_attribute(pointer_with_type_tag) && \
- __has_attribute(type_tag_for_datatype)
- # define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx)))
- /* ... other macros ... */
- # endif
- #endif
-
- #if !defined(ATTR_MPI_PWT)
- # define ATTR_MPI_PWT(buffer_idx, type_idx)
- #endif
-
- int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
- ATTR_MPI_PWT(1,3);
-
-``argument_with_type_tag(...)``
--------------------------------
-
-Use ``__attribute__((argument_with_type_tag(arg_kind, arg_idx,
-type_tag_idx)))`` on a function declaration to specify that the function
-accepts a type tag that determines the type of some other argument.
-``arg_kind`` is an identifier that should be used when annotating all
-applicable type tags.
-
-This attribute is primarily useful for checking arguments of variadic functions
-(``pointer_with_type_tag`` can be used in most non-variadic cases).
-
-For example:
-
-.. code-block:: c++
-
- int fcntl(int fd, int cmd, ...)
- __attribute__(( argument_with_type_tag(fcntl,3,2) ));
-
-``pointer_with_type_tag(...)``
-------------------------------
-
-Use ``__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, type_tag_idx)))``
-on a function declaration to specify that the function accepts a type tag that
-determines the pointee type of some other pointer argument.
-
-For example:
-
-.. code-block:: c++
-
- int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
- __attribute__(( pointer_with_type_tag(mpi,1,3) ));
-
-``type_tag_for_datatype(...)``
-------------------------------
-
-Clang supports annotating type tags of two forms.
-
-* **Type tag that is an expression containing a reference to some declared
- identifier.** Use ``__attribute__((type_tag_for_datatype(kind, type)))`` on a
- declaration with that identifier:
-
- .. code-block:: c++
-
- extern struct mpi_datatype mpi_datatype_int
- __attribute__(( type_tag_for_datatype(mpi,int) ));
- #define MPI_INT ((MPI_Datatype) &mpi_datatype_int)
-
-* **Type tag that is an integral literal.** Introduce a ``static const``
- variable with a corresponding initializer value and attach
- ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration,
- for example:
-
- .. code-block:: c++
-
- #define MPI_INT ((MPI_Datatype) 42)
- static const MPI_Datatype mpi_datatype_int
- __attribute__(( type_tag_for_datatype(mpi,int) )) = 42
-
-The attribute also accepts an optional third argument that determines how the
-expression is compared to the type tag. There are two supported flags:
-
-* ``layout_compatible`` will cause types to be compared according to
- layout-compatibility rules (C++11 [class.mem] p 17, 18). This is
- implemented to support annotating types like ``MPI_DOUBLE_INT``.
-
- For example:
-
- .. code-block:: c++
-
- /* In mpi.h */
- struct internal_mpi_double_int { double d; int i; };
- extern struct mpi_datatype mpi_datatype_double_int
- __attribute__(( type_tag_for_datatype(mpi, struct internal_mpi_double_int, layout_compatible) ));
-
- #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int)
-
- /* In user code */
- struct my_pair { double a; int b; };
- struct my_pair *buffer;
- MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning
-
- struct my_int_pair { int a; int b; }
- struct my_int_pair *buffer2;
- MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning: actual buffer element
- // type 'struct my_int_pair'
- // doesn't match specified MPI_Datatype
-
-* ``must_be_null`` specifies that the expression should be a null pointer
- constant, for example:
-
- .. code-block:: c++
-
- /* In mpi.h */
- extern struct mpi_datatype mpi_datatype_null
- __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) ));
-
- #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null)
-
- /* In user code */
- MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL
- // was specified but buffer
- // is not a null pointer
-
-Format String Checking
-======================
-
-Clang supports the ``format`` attribute, which indicates that the function
-accepts a ``printf`` or ``scanf``-like format string and corresponding
-arguments or a ``va_list`` that contains these arguments.
-
-Please see `GCC documentation about format attribute
-<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ to find details
-about attribute syntax.
-
-Clang implements two kinds of checks with this attribute.
-
-#. Clang checks that the function with the ``format`` attribute is called with
- a format string that uses format specifiers that are allowed, and that
- arguments match the format string. This is the ``-Wformat`` warning, it is
- on by default.
-
-#. Clang checks that the format string argument is a literal string. This is
- the ``-Wformat-nonliteral`` warning, it is off by default.
-
- Clang implements this mostly the same way as GCC, but there is a difference
- for functions that accept a ``va_list`` argument (for example, ``vprintf``).
- GCC does not emit ``-Wformat-nonliteral`` warning for calls to such
- fuctions. Clang does not warn if the format string comes from a function
- parameter, where the function is annotated with a compatible attribute,
- otherwise it warns. For example:
-
- .. code-block:: c
-
- __attribute__((__format__ (__scanf__, 1, 3)))
- void foo(const char* s, char *buf, ...) {
- va_list ap;
- va_start(ap, buf);
-
- vprintf(s, ap); // warning: format string is not a string literal
- }
-
- In this case we warn because ``s`` contains a format string for a
- ``scanf``-like function, but it is passed to a ``printf``-like function.
-
- If the attribute is removed, clang still warns, because the format string is
- not a string literal.
-
- Another example:
-
- .. code-block:: c
-
- __attribute__((__format__ (__printf__, 1, 3)))
- void foo(const char* s, char *buf, ...) {
- va_list ap;
- va_start(ap, buf);
-
- vprintf(s, ap); // warning
- }
-
- In this case Clang does not warn because the format string ``s`` and
- the corresponding arguments are annotated. If the arguments are
- incorrect, the caller of ``foo`` will receive a warning.
diff --git a/docs/LibASTMatchersReference.html b/docs/LibASTMatchersReference.html
index 2c9b3aa..f701f11 100644
--- a/docs/LibASTMatchersReference.html
+++ b/docs/LibASTMatchersReference.html
@@ -250,7 +250,7 @@
<tr><td colspan="4" class="doc" id="methodDecl0"><pre>Matches method declarations.
Example matches y
- class X { void y() };
+ class X { void y(); };
</pre></td></tr>
@@ -1311,7 +1311,7 @@
</pre></td></tr>
-<tr><td>Matcher<*></td><td class="name" onclick="toggle('unless0')"><a name="unless0Anchor">unless</a></td><td>Matcher<*> InnerMatcher</td></tr>
+<tr><td>Matcher<*></td><td class="name" onclick="toggle('unless0')"><a name="unless0Anchor">unless</a></td><td>Matcher<*></td></tr>
<tr><td colspan="4" class="doc" id="unless0"><pre>Matches if the provided matcher does not match.
Example matches Y (matcher = recordDecl(unless(hasName("X"))))
@@ -1352,6 +1352,11 @@
</pre></td></tr>
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>></td><td class="name" onclick="toggle('isListInitialization0')"><a name="isListInitialization0Anchor">isListInitialization</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isListInitialization0"><pre>Matches a constructor call expression which uses list initialization.
+</pre></td></tr>
+
+
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructorDecl.html">CXXConstructorDecl</a>></td><td class="name" onclick="toggle('isImplicit0')"><a name="isImplicit0Anchor">isImplicit</a></td><td></td></tr>
<tr><td colspan="4" class="doc" id="isImplicit0"><pre>Matches a constructor declaration that has been implicitly added
by the compiler (eg. implicit defaultcopy constructors).
@@ -1422,6 +1427,18 @@
</pre></td></tr>
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>></td><td class="name" onclick="toggle('isPure0')"><a name="isPure0Anchor">isPure</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isPure0"><pre>Matches if the given method declaration is pure.
+
+Given
+ class A {
+ public:
+ virtual void x() = 0;
+ };
+ matches A::x
+</pre></td></tr>
+
+
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>></td><td class="name" onclick="toggle('isVirtual0')"><a name="isVirtual0Anchor">isVirtual</a></td><td></td></tr>
<tr><td colspan="4" class="doc" id="isVirtual0"><pre>Matches if the given method declaration is virtual.
@@ -2026,24 +2043,6 @@
</pre></td></tr>
-<tr><td>Matcher<*></td><td class="name" onclick="toggle('forEach0')"><a name="forEach0Anchor">forEach</a></td><td>Matcher<*></td></tr>
-<tr><td colspan="4" class="doc" id="forEach0"><pre>Matches AST nodes that have child AST nodes that match the
-provided matcher.
-
-Example matches X, Y (matcher = recordDecl(forEach(recordDecl(hasName("X")))
- class X {}; Matches X, because X::X is a class of name X inside X.
- class Y { class X {}; };
- class Z { class Y { class X {}; }; }; Does not match Z.
-
-ChildT must be an AST base type.
-
-As opposed to 'has', 'forEach' will cause a match for each result that
-matches instead of only on the first one.
-
-Usable as: Any Matcher
-</pre></td></tr>
-
-
<tr><td>Matcher<*></td><td class="name" onclick="toggle('forEachDescendant0')"><a name="forEachDescendant0Anchor">forEachDescendant</a></td><td>Matcher<*></td></tr>
<tr><td colspan="4" class="doc" id="forEachDescendant0"><pre>Matches AST nodes that have descendant AST nodes that match the
provided matcher.
@@ -2068,17 +2067,20 @@
</pre></td></tr>
-<tr><td>Matcher<*></td><td class="name" onclick="toggle('has0')"><a name="has0Anchor">has</a></td><td>Matcher<*></td></tr>
-<tr><td colspan="4" class="doc" id="has0"><pre>Matches AST nodes that have child AST nodes that match the
+<tr><td>Matcher<*></td><td class="name" onclick="toggle('forEach0')"><a name="forEach0Anchor">forEach</a></td><td>Matcher<*></td></tr>
+<tr><td colspan="4" class="doc" id="forEach0"><pre>Matches AST nodes that have child AST nodes that match the
provided matcher.
-Example matches X, Y (matcher = recordDecl(has(recordDecl(hasName("X")))
+Example matches X, Y (matcher = recordDecl(forEach(recordDecl(hasName("X")))
class X {}; Matches X, because X::X is a class of name X inside X.
class Y { class X {}; };
class Z { class Y { class X {}; }; }; Does not match Z.
ChildT must be an AST base type.
+As opposed to 'has', 'forEach' will cause a match for each result that
+matches instead of only on the first one.
+
Usable as: Any Matcher
</pre></td></tr>
@@ -2112,6 +2114,21 @@
</pre></td></tr>
+<tr><td>Matcher<*></td><td class="name" onclick="toggle('has0')"><a name="has0Anchor">has</a></td><td>Matcher<*></td></tr>
+<tr><td colspan="4" class="doc" id="has0"><pre>Matches AST nodes that have child AST nodes that match the
+provided matcher.
+
+Example matches X, Y (matcher = recordDecl(has(recordDecl(hasName("X")))
+ class X {}; Matches X, because X::X is a class of name X inside X.
+ class Y { class X {}; };
+ class Z { class Y { class X {}; }; }; Does not match Z.
+
+ChildT must be an AST base type.
+
+Usable as: Any Matcher
+</pre></td></tr>
+
+
<tr><td>Matcher<*></td><td class="name" onclick="toggle('hasParent0')"><a name="hasParent0Anchor">hasParent</a></td><td>Matcher<*></td></tr>
<tr><td colspan="4" class="doc" id="hasParent0"><pre>Matches AST nodes that have a parent that matches the provided
matcher.
@@ -2313,8 +2330,6 @@
Also usable as Matcher<T> for any T supporting the getDecl() member
function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
@@ -2378,6 +2393,20 @@
</pre></td></tr>
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXForRangeStmt.html">CXXForRangeStmt</a>></td><td class="name" onclick="toggle('hasLoopVariable0')"><a name="hasLoopVariable0Anchor">hasLoopVariable</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasLoopVariable0"><pre>Matches the initialization statement of a for loop.
+
+Example:
+ forStmt(hasLoopVariable(anything()))
+matches 'int x' in
+ for (int x : a) { }
+</pre></td></tr>
+
+
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMemberCallExpr.html">CXXMemberCallExpr</a>></td><td class="name" onclick="toggle('onImplicitObjectArgument0')"><a name="onImplicitObjectArgument0Anchor">onImplicitObjectArgument</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="onImplicitObjectArgument0"><pre></pre></td></tr>
+
+
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMemberCallExpr.html">CXXMemberCallExpr</a>></td><td class="name" onclick="toggle('on0')"><a name="on0Anchor">on</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
<tr><td colspan="4" class="doc" id="on0"><pre>Matches on the implicit object argument of a member call expression.
@@ -2389,15 +2418,17 @@
</pre></td></tr>
-<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMemberCallExpr.html">CXXMemberCallExpr</a>></td><td class="name" onclick="toggle('onImplicitObjectArgument0')"><a name="onImplicitObjectArgument0Anchor">onImplicitObjectArgument</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
-<tr><td colspan="4" class="doc" id="onImplicitObjectArgument0"><pre></pre></td></tr>
-
-
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMemberCallExpr.html">CXXMemberCallExpr</a>></td><td class="name" onclick="toggle('thisPointerType1')"><a name="thisPointerType1Anchor">thisPointerType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
<tr><td colspan="4" class="doc" id="thisPointerType1"><pre>Overloaded to match the type's declaration.
</pre></td></tr>
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMemberCallExpr.html">CXXMemberCallExpr</a>></td><td class="name" onclick="toggle('thisPointerType0')"><a name="thisPointerType0Anchor">thisPointerType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="thisPointerType0"><pre>Matches if the expression's type either matches the specified
+matcher, or is a pointer to a type that matches the InnerMatcher.
+</pre></td></tr>
+
+
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>></td><td class="name" onclick="toggle('ofClass0')"><a name="ofClass0Anchor">ofClass</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>> InnerMatcher</td></tr>
<tr><td colspan="4" class="doc" id="ofClass0"><pre>Matches the class declaration that the given method declaration
belongs to.
@@ -2466,6 +2497,24 @@
</pre></td></tr>
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>></td><td class="name" onclick="toggle('callee0')"><a name="callee0Anchor">callee</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="callee0"><pre>Matches if the call expression's callee expression matches.
+
+Given
+ class Y { void x() { this->x(); x(); Y y; y.x(); } };
+ void f() { f(); }
+callExpr(callee(expr()))
+ matches this->x(), x(), y.x(), f()
+with callee(...)
+ matching this->x, x, y.x, f respectively
+
+Note: Callee cannot take the more general internal::Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>>
+because this introduces ambiguous overloads with calls to Callee taking a
+internal::Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>>, as the matcher hierarchy is purely
+implemented in terms of implicit casts.
+</pre></td></tr>
+
+
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>></td><td class="name" onclick="toggle('hasAnyArgument0')"><a name="hasAnyArgument0Anchor">hasAnyArgument</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
<tr><td colspan="4" class="doc" id="hasAnyArgument0"><pre>Matches any argument of a call expression or a constructor call
expression.
@@ -2506,8 +2555,6 @@
Also usable as Matcher<T> for any T supporting the getDecl() member
function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
@@ -2647,8 +2694,6 @@
Also usable as Matcher<T> for any T supporting the getDecl() member
function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
@@ -2813,8 +2858,6 @@
Also usable as Matcher<T> for any T supporting the getDecl() member
function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
@@ -2852,6 +2895,17 @@
</pre></td></tr>
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>></td><td class="name" onclick="toggle('hasType0')"><a name="hasType0Anchor">hasType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasType0"><pre>Matches if the expression's or declaration's type matches a type
+matcher.
+
+Example matches x (matcher = expr(hasType(recordDecl(hasName("X")))))
+ and z (matcher = varDecl(hasType(recordDecl(hasName("X")))))
+ class X {};
+ void y(X &x) { x; X z; }
+</pre></td></tr>
+
+
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>></td><td class="name" onclick="toggle('ignoringImpCasts0')"><a name="ignoringImpCasts0Anchor">ignoringImpCasts</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
<tr><td colspan="4" class="doc" id="ignoringImpCasts0"><pre>Matches expressions that match InnerMatcher after any implicit casts
are stripped off.
@@ -3034,8 +3088,6 @@
Also usable as Matcher<T> for any T supporting the getDecl() member
function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
@@ -3058,8 +3110,6 @@
Also usable as Matcher<T> for any T supporting the getDecl() member
function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
@@ -3082,8 +3132,6 @@
Also usable as Matcher<T> for any T supporting the getDecl() member
function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
@@ -3165,12 +3213,6 @@
</pre></td></tr>
-<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifierLoc.html">NestedNameSpecifierLoc</a>></td><td class="name" onclick="toggle('loc1')"><a name="loc1Anchor">loc</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifier.html">NestedNameSpecifier</a>> InnerMatcher</td></tr>
-<tr><td colspan="4" class="doc" id="loc1"><pre>Matches NestedNameSpecifierLocs for which the given inner
-NestedNameSpecifier-matcher matches.
-</pre></td></tr>
-
-
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifierLoc.html">NestedNameSpecifierLoc</a>></td><td class="name" onclick="toggle('specifiesTypeLoc0')"><a name="specifiesTypeLoc0Anchor">specifiesTypeLoc</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>> InnerMatcher</td></tr>
<tr><td colspan="4" class="doc" id="specifiesTypeLoc0"><pre>Matches nested name specifier locs that specify a type matching the
given TypeLoc.
@@ -3290,8 +3332,6 @@
Also usable as Matcher<T> for any T supporting the getDecl() member
function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
@@ -3307,11 +3347,36 @@
</pre></td></tr>
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('pointsTo0')"><a name="pointsTo0Anchor">pointsTo</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="pointsTo0"><pre>Matches if the matched type is a pointer type and the pointee type
+matches the specified matcher.
+
+Example matches y->x()
+ (matcher = callExpr(on(hasType(pointsTo(recordDecl(hasName("Y")))))))
+ class Y { public: void x(); };
+ void z() { Y *y; y->x(); }
+</pre></td></tr>
+
+
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('references1')"><a name="references1Anchor">references</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
<tr><td colspan="4" class="doc" id="references1"><pre>Overloaded to match the referenced type's declaration.
</pre></td></tr>
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('references0')"><a name="references0Anchor">references</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="references0"><pre>Matches if the matched type is a reference type and the referenced
+type matches the specified matcher.
+
+Example matches X &x and const X &y
+ (matcher = varDecl(hasType(references(recordDecl(hasName("X"))))))
+ class X {
+ void a(X b) {
+ X &x = b;
+ const X &y = b;
+ };
+</pre></td></tr>
+
+
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1RecordType.html">RecordType</a>></td><td class="name" onclick="toggle('hasDeclaration5')"><a name="hasDeclaration5Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
<tr><td colspan="4" class="doc" id="hasDeclaration5"><pre>Matches a node if the declaration associated with that node
matches the given matcher.
@@ -3324,8 +3389,6 @@
Also usable as Matcher<T> for any T supporting the getDecl() member
function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
@@ -3405,8 +3468,6 @@
Also usable as Matcher<T> for any T supporting the getDecl() member
function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
@@ -3417,8 +3478,23 @@
</pre></td></tr>
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>></td><td class="name" onclick="toggle('isExpr0')"><a name="isExpr0Anchor">isExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="isExpr0"><pre>Matches a sugar TemplateArgument that refers to a certain expression.
+
+Given
+ template<typename T> struct A {};
+ struct B { B* next; };
+ A<&B::next> a;
+templateSpecializationType(hasAnyTemplateArgument(
+ isExpr(hasDescendant(declRefExpr(to(fieldDecl(hasName("next"))))))))
+ matches the specialization A<&B::next> with fieldDecl(...) matching
+ B::next
+</pre></td></tr>
+
+
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>></td><td class="name" onclick="toggle('refersToDeclaration0')"><a name="refersToDeclaration0Anchor">refersToDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
-<tr><td colspan="4" class="doc" id="refersToDeclaration0"><pre>Matches a TemplateArgument that refers to a certain declaration.
+<tr><td colspan="4" class="doc" id="refersToDeclaration0"><pre>Matches a canonical TemplateArgument that refers to a certain
+declaration.
Given
template<typename T> struct A {};
@@ -3444,6 +3520,20 @@
</pre></td></tr>
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>></td><td class="name" onclick="toggle('hasAnyTemplateArgument1')"><a name="hasAnyTemplateArgument1Anchor">hasAnyTemplateArgument</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasAnyTemplateArgument1"><pre>Matches classTemplateSpecializations that have at least one
+TemplateArgument matching the given InnerMatcher.
+
+Given
+ template<typename T> class A {};
+ template<> class A<double> {};
+ A<int> a;
+classTemplateSpecializationDecl(hasAnyTemplateArgument(
+ refersToType(asString("int"))))
+ matches the specialization A<int>
+</pre></td></tr>
+
+
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>></td><td class="name" onclick="toggle('hasDeclaration3')"><a name="hasDeclaration3Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
<tr><td colspan="4" class="doc" id="hasDeclaration3"><pre>Matches a node if the declaration associated with that node
matches the given matcher.
@@ -3456,8 +3546,6 @@
Also usable as Matcher<T> for any T supporting the getDecl() member
function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
@@ -3468,6 +3556,20 @@
</pre></td></tr>
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>></td><td class="name" onclick="toggle('hasTemplateArgument1')"><a name="hasTemplateArgument1Anchor">hasTemplateArgument</a></td><td>unsigned N, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasTemplateArgument1"><pre>Matches classTemplateSpecializations where the n'th TemplateArgument
+matches the given InnerMatcher.
+
+Given
+ template<typename T, typename U> class A {};
+ A<bool, int> b;
+ A<int, bool> c;
+classTemplateSpecializationDecl(hasTemplateArgument(
+ 1, refersToType(asString("int"))))
+ matches the specialization A<bool, int>
+</pre></td></tr>
+
+
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateTypeParmType.html">TemplateTypeParmType</a>></td><td class="name" onclick="toggle('hasDeclaration2')"><a name="hasDeclaration2Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
<tr><td colspan="4" class="doc" id="hasDeclaration2"><pre>Matches a node if the declaration associated with that node
matches the given matcher.
@@ -3480,8 +3582,6 @@
Also usable as Matcher<T> for any T supporting the getDecl() member
function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
@@ -3507,12 +3607,6 @@
</pre></td></tr>
-<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>></td><td class="name" onclick="toggle('loc0')"><a name="loc0Anchor">loc</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
-<tr><td colspan="4" class="doc" id="loc0"><pre>Matches TypeLocs for which the given inner
-QualType-matcher matches.
-</pre></td></tr>
-
-
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypedefType.html">TypedefType</a>></td><td class="name" onclick="toggle('hasDeclaration1')"><a name="hasDeclaration1Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr>
<tr><td colspan="4" class="doc" id="hasDeclaration1"><pre>Matches a node if the declaration associated with that node
matches the given matcher.
@@ -3525,8 +3619,6 @@
Also usable as Matcher<T> for any T supporting the getDecl() member
function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
@@ -3567,8 +3659,6 @@
Also usable as Matcher<T> for any T supporting the getDecl() member
function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>>,
Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>>,
@@ -3620,6 +3710,17 @@
</pre></td></tr>
+<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ValueDecl.html">ValueDecl</a>></td><td class="name" onclick="toggle('hasType1')"><a name="hasType1Anchor">hasType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasType1"><pre>Matches if the expression's or declaration's type matches a type
+matcher.
+
+Example matches x (matcher = expr(hasType(recordDecl(hasName("X")))))
+ and z (matcher = varDecl(hasType(recordDecl(hasName("X")))))
+ class X {};
+ void y(X &x) { x; X z; }
+</pre></td></tr>
+
+
<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>></td><td class="name" onclick="toggle('hasInitializer0')"><a name="hasInitializer0Anchor">hasInitializer</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr>
<tr><td colspan="4" class="doc" id="hasInitializer0"><pre>Matches a variable declaration that has an initializer expression
that matches the given matcher.
@@ -3665,6 +3766,18 @@
if (true) {}
</pre></td></tr>
+
+<tr><td>Matcher<internal::BindableMatcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifierLoc.html">NestedNameSpecifierLoc</a>>></td><td class="name" onclick="toggle('loc1')"><a name="loc1Anchor">loc</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifier.html">NestedNameSpecifier</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="loc1"><pre>Matches NestedNameSpecifierLocs for which the given inner
+NestedNameSpecifier-matcher matches.
+</pre></td></tr>
+
+
+<tr><td>Matcher<internal::BindableMatcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>>></td><td class="name" onclick="toggle('loc0')"><a name="loc0Anchor">loc</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>> InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="loc0"><pre>Matches TypeLocs for which the given inner
+QualType-matcher matches.
+</pre></td></tr>
+
<!--END_TRAVERSAL_MATCHERS -->
</table>
diff --git a/docs/LibASTMatchersTutorial.rst b/docs/LibASTMatchersTutorial.rst
index 5bd62a1..13749fb 100644
--- a/docs/LibASTMatchersTutorial.rst
+++ b/docs/LibASTMatchersTutorial.rst
@@ -137,6 +137,10 @@
using namespace clang::tooling;
using namespace llvm;
+ // Apply a custom category to all command-line options so that they are the
+ // only ones displayed.
+ static llvm::cl::OptionCategory MyToolCategory("my-tool options");
+
// CommonOptionsParser declares HelpMessage with a description of the common
// command-line options related to the compilation database and input files.
// It's nice to have this help message in all tools.
@@ -146,7 +150,7 @@
static cl::extrahelp MoreHelp("\nMore help text...");
int main(int argc, const char **argv) {
- CommonOptionsParser OptionsParser(argc, argv);
+ CommonOptionsParser OptionsParser(argc, argv, MyToolCategory);
ClangTool Tool(OptionsParser.getCompilations(),
OptionsParser.getSourcePathList());
return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>());
@@ -287,7 +291,7 @@
.. code-block:: c++
int main(int argc, const char **argv) {
- CommonOptionsParser OptionsParser(argc, argv);
+ CommonOptionsParser OptionsParser(argc, argv, MyToolCategory);
ClangTool Tool(OptionsParser.getCompilations(),
OptionsParser.getSourcePathList());
diff --git a/docs/LibTooling.rst b/docs/LibTooling.rst
index 5058656..57f207f 100644
--- a/docs/LibTooling.rst
+++ b/docs/LibTooling.rst
@@ -60,13 +60,18 @@
.. code-block:: c++
#include "clang/Tooling/CommonOptionsParser.h"
+ #include "llvm/Support/CommandLine.h"
using namespace clang::tooling;
+ // Apply a custom category to all command-line options so that they are the
+ // only ones displayed.
+ static llvm::cl::OptionCategory MyToolCategory("my-tool options");
+
int main(int argc, const char **argv) {
// CommonOptionsParser constructor will parse arguments and create a
// CompilationDatabase. In case of error it will terminate the program.
- CommonOptionsParser OptionsParser(argc, argv);
+ CommonOptionsParser OptionsParser(argc, argv, MyToolCategory);
// Use OptionsParser.getCompilations() and OptionsParser.getSourcePathList()
// to retrieve CompilationDatabase and the list of input file paths.
@@ -99,8 +104,8 @@
Putting it together --- the first tool
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Now we combine the two previous steps into our first real tool. This example
-tool is also checked into the clang tree at
+Now we combine the two previous steps into our first real tool. A more advanced
+version of this example tool is also checked into the clang tree at
``tools/clang-check/ClangCheck.cpp``.
.. code-block:: c++
@@ -115,6 +120,10 @@
using namespace clang::tooling;
using namespace llvm;
+ // Apply a custom category to all command-line options so that they are the
+ // only ones displayed.
+ static cl::OptionCategory MyToolCategory("my-tool options");
+
// CommonOptionsParser declares HelpMessage with a description of the common
// command-line options related to the compilation database and input files.
// It's nice to have this help message in all tools.
@@ -124,9 +133,9 @@
static cl::extrahelp MoreHelp("\nMore help text...");
int main(int argc, const char **argv) {
- CommonOptionsParser OptionsParser(argc, argv);
+ CommonOptionsParser OptionsParser(argc, argv, MyToolCategory);
ClangTool Tool(OptionsParser.getCompilations(),
- OptionsParser.getSourcePathList());
+ OptionsParser.getSourcePathList());
return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>());
}
@@ -176,7 +185,7 @@
Clang tools need their builtin headers and search for them the same way Clang
does. Thus, the default location to look for builtin headers is in a path
-``$(dirname /path/to/tool)/../lib/clang/3.4/include`` relative to the tool
+``$(dirname /path/to/tool)/../lib/clang/3.3/include`` relative to the tool
binary. This works out-of-the-box for tools running from llvm's toplevel
binary directory after building clang-headers, or if the tool is running from
the binary directory of a clang install next to the clang binary.
diff --git a/docs/MSVCCompatibility.rst b/docs/MSVCCompatibility.rst
new file mode 100644
index 0000000..683ce93
--- /dev/null
+++ b/docs/MSVCCompatibility.rst
@@ -0,0 +1,124 @@
+.. raw:: html
+
+ <style type="text/css">
+ .none { background-color: #FFCCCC }
+ .partial { background-color: #FFFF99 }
+ .good { background-color: #CCFF99 }
+ </style>
+
+.. role:: none
+.. role:: partial
+.. role:: good
+
+==================
+MSVC compatibility
+==================
+
+When Clang compiles C++ code for Windows, it attempts to be compatible with
+MSVC. There are multiple dimensions to compatibility.
+
+First, Clang attempts to be ABI-compatible, meaning that Clang-compiled code
+should be able to link against MSVC-compiled code successfully. However, C++
+ABIs are particular large and complicated, and Clang's support for MSVC's C++
+ABI is a work in progress. If you don't require MSVC ABI compatibility or don't
+want to use Microsoft's C and C++ runtimes, the mingw32 toolchain might be a
+better fit for your project.
+
+Second, Clang implements many MSVC language extensions, such as
+``__declspec(dllexport)`` and a handful of pragmas. These are typically
+controlled by ``-fms-extensions``.
+
+Third, MSVC accepts some C++ code that Clang will typically diagnose as
+invalid. When these constructs are present in widely included system headers,
+Clang attempts to recover and continue compiling the user's program. Most
+parsing and semantic compatibility tweaks are controlled by
+``-fms-compatibility`` and ``-fdelayed-template-parsing``, and they are a work
+in progress.
+
+Finally, there is :ref:`clang-cl`, a driver program for clang that attempts to
+be compatible with MSVC's cl.exe.
+
+ABI features
+============
+
+The status of major ABI-impacting C++ features:
+
+* Record layout: :good:`Mostly complete`. We've tested this with a fuzzer, and
+ most of the remaining failures involve ``#pragma pack``,
+ ``__declspec(align(N))``, or other pragmas.
+
+* Class inheritance: :good:`Mostly complete`. This covers all of the standard
+ OO features you would expect: virtual method inheritance, multiple
+ inheritance, and virtual inheritance. Every so often we uncover a bug where
+ our tables are incompatible, but this is pretty well in hand.
+
+* Name mangling: :good:`Ongoing`. Every new C++ feature generally needs its own
+ mangling. For example, member pointer template arguments have an interesting
+ and distinct mangling. Fortunately, incorrect manglings usually do not result
+ in runtime errors. Non-inline functions with incorrect manglings usually
+ result in link errors, which are relatively easy to diagnose. Incorrect
+ manglings for inline functions and templates result in multiple copies in the
+ final image. The C++ standard requires that those addresses be equal, but few
+ programs rely on this.
+
+* Member pointers: :good:`Mostly complete`. Standard C++ member pointers are
+ fully implemented and should be ABI compatible. Both `#pragma
+ pointers_to_members`_ and the `/vm`_ flags are supported. However, MSVC
+ supports an extension to allow creating a `pointer to a member of a virtual
+ base class`_. Clang does not yet support this.
+
+.. _#pragma pointers_to_members:
+ http://msdn.microsoft.com/en-us/library/83cch5a6.aspx
+.. _/vm: http://msdn.microsoft.com/en-us/library/yad46a6z.aspx
+.. _pointer to a member of a virtual base class: http://llvm.org/PR15713
+
+* Debug info: :partial:`Minimal`. Clang emits CodeView line tables into the
+ object file, similar to what MSVC emits when given the ``/Z7`` flag.
+ Microsoft's link.exe will read this information and use it to create a PDB,
+ enabling stack traces in all modern Windows debuggers. Clang does not emit
+ any type info or description of variable layout.
+
+* `RTTI`_: :none:`Unstarted`. See the bug for a discussion of what needs to
+ happen first.
+
+.. _RTTI: http://llvm.org/PR18951
+
+* Exceptions and SEH: :none:`Unstarted`. Clang can parse both constructs, but
+ does not know how to emit compatible handlers. This depends on RTTI.
+
+* Thread-safe initialization of local statics: :none:`Unstarted`. We are ABI
+ compatible with MSVC 2012, which does not support thread-safe local statics.
+ MSVC 2013 changed the ABI to make initialization of local statics thread safe,
+ and we have not yet implemented this.
+
+* Lambdas in ABI boundaries: :none:`Infeasible`. It is unlikely that we will
+ ever be fully ABI compatible with lambdas declared in inline functions due to
+ what appears to be a hash code in the name mangling. Lambdas that are not
+ externally visible should work fine.
+
+Template instantiation and name lookup
+======================================
+
+In addition to the usual `dependent name lookup FAQs`_, Clang is often unable to
+parse certain invalid C++ constructs that MSVC allows. As of this writing,
+Clang will reject code with missing ``typename`` annotations:
+
+.. _dependent name lookup FAQs:
+ http://clang.llvm.org/compatibility.html#dep_lookup
+
+.. code-block:: c++
+
+ struct X {
+ typedef int type;
+ };
+ template<typename T> int f() {
+ // missing typename keyword
+ return sizeof(/*typename*/ T::type);
+ }
+ template void f<X>();
+
+Accepting code like this is ongoing work. Ultimately, it may be cleaner to
+`implement a token-based template instantiation mode`_ than it is to add
+compatibility hacks to the existing AST-based instantiation.
+
+.. _implement a token-based template instantiation mode: http://llvm.org/PR18714
diff --git a/docs/MemorySanitizer.rst b/docs/MemorySanitizer.rst
index 5fc7e74..9d6c22d 100644
--- a/docs/MemorySanitizer.rst
+++ b/docs/MemorySanitizer.rst
@@ -56,12 +56,10 @@
.. code-block:: console
- % ./a.out 2>log
- % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
- ==30106== WARNING: MemorySanitizer: UMR (uninitialized-memory-read)
+ % ./a.out
+ WARNING: MemorySanitizer: use-of-uninitialized-value
#0 0x7f45944b418a in main umr.cc:6
#1 0x7f45938b676c in __libc_start_main libc-start.c:226
- Exiting
By default, MemorySanitizer exits on the first detected error.
@@ -101,6 +99,13 @@
warnings will be suppressed and all values loaded from memory will be
considered fully initialized.
+Report symbolization
+====================
+
+MemorySanitizer uses an external symbolizer to print files and line numbers in
+reports. Make sure that ``llvm-symbolizer`` binary is in ``PATH``,
+or set environment variable ``MSAN_SYMBOLIZER_PATH`` to point to it.
+
Origin Tracking
===============
@@ -112,29 +117,59 @@
.. code-block:: console
% clang -fsanitize=memory -fsanitize-memory-track-origins -fno-omit-frame-pointer -g -O2 umr.cc
- % ./a.out 2>log
- % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
- ==14425== WARNING: MemorySanitizer: UMR (uninitialized-memory-read)
- ==14425== WARNING: Trying to symbolize code, but external symbolizer is not initialized!
- #0 0x7f8bdda3824b in main umr.cc:6
- #1 0x7f8bdce3a76c in __libc_start_main libc-start.c:226
- raw origin id: 2030043137
- ORIGIN: heap allocation:
- #0 0x7f8bdda4034b in operator new[](unsigned long) msan_new_delete.cc:39
- #1 0x7f8bdda3814d in main umr.cc:4
- #2 0x7f8bdce3a76c in __libc_start_main libc-start.c:226
- Exiting
+ % ./a.out
+ WARNING: MemorySanitizer: use-of-uninitialized-value
+ #0 0x7f7893912f0b in main umr2.cc:6
+ #1 0x7f789249b76c in __libc_start_main libc-start.c:226
-Origin tracking has proved to be very useful for debugging UMR
+ Uninitialized value was created by a heap allocation
+ #0 0x7f7893901cbd in operator new[](unsigned long) msan_new_delete.cc:44
+ #1 0x7f7893912e06 in main umr2.cc:4
+
+Origin tracking has proved to be very useful for debugging MemorySanitizer
reports. It slows down program execution by a factor of 1.5x-2x on top
of the usual MemorySanitizer slowdown.
+MemorySanitizer can provide even more information with
+``-fsanitize-memory-track-origins=2`` flag. In this mode reports
+include information about intermediate stores the uninitialized value went
+through.
+
+.. code-block:: console
+
+ % cat umr2.cc
+ #include <stdio.h>
+
+ int main(int argc, char** argv) {
+ int* a = new int[10];
+ a[5] = 0;
+ volatile int b = a[argc];
+ if (b)
+ printf("xx\n");
+ return 0;
+ }
+
+ % clang -fsanitize=memory -fsanitize-memory-track-origins=2 -fno-omit-frame-pointer -g -O2 umr2.cc
+ % ./a.out
+ WARNING: MemorySanitizer: use-of-uninitialized-value
+ #0 0x7f7893912f0b in main umr2.cc:7
+ #1 0x7f789249b76c in __libc_start_main libc-start.c:226
+
+ Uninitialized value was stored to memory at
+ #0 0x7f78938b5c25 in __msan_chain_origin msan.cc:484
+ #1 0x7f7893912ecd in main umr2.cc:6
+
+ Uninitialized value was created by a heap allocation
+ #0 0x7f7893901cbd in operator new[](unsigned long) msan_new_delete.cc:44
+ #1 0x7f7893912e06 in main umr2.cc:4
+
+
Handling external code
============================
MemorySanitizer requires that all program code is instrumented. This
also includes any libraries that the program depends on, even libc.
-Failing to achieve this may result in false UMR reports.
+Failing to achieve this may result in false reports.
Full MemorySanitizer instrumentation is very difficult to achieve. To
make it easier, MemorySanitizer runtime library includes 70+
@@ -157,7 +192,7 @@
MemorySanitizer is supported on
-* Linux x86\_64 (tested on Ubuntu 10.04 and 12.04);
+* Linux x86\_64 (tested on Ubuntu 12.04);
Limitations
===========
diff --git a/docs/Modules.rst b/docs/Modules.rst
index 9fb4c77..eec0b77 100644
--- a/docs/Modules.rst
+++ b/docs/Modules.rst
@@ -144,7 +144,7 @@
-----------
The crucial link between modules and headers is described by a *module map*, which describes how a collection of existing headers maps on to the (logical) structure of a module. For example, one could imagine a module ``std`` covering the C standard library. Each of the C standard library headers (``<stdio.h>``, ``<stdlib.h>``, ``<math.h>``, etc.) would contribute to the ``std`` module, by placing their respective APIs into the corresponding submodule (``std.io``, ``std.lib``, ``std.math``, etc.). Having a list of the headers that are part of the ``std`` module allows the compiler to build the ``std`` module as a standalone entity, and having the mapping from header names to (sub)modules allows the automatic translation of ``#include`` directives to module imports.
-Module maps are specified as separate files (each named ``module.map``) alongside the headers they describe, which allows them to be added to existing software libraries without having to change the library headers themselves (in most cases [#]_). The actual `Module map language`_ is described in a later section.
+Module maps are specified as separate files (each named ``module.modulemap``) alongside the headers they describe, which allows them to be added to existing software libraries without having to change the library headers themselves (in most cases [#]_). The actual `Module map language`_ is described in a later section.
.. note::
@@ -198,20 +198,60 @@
``-fmodule-map-file=<file>``
Load the given module map file if a header from its directory or one of its subdirectories is loaded.
+Module Semantics
+================
+
+Modules are modeled as if each submodule were a separate translation unit, and a module import makes names from the other translation unit visible. Each submodule starts with a new preprocessor state and an empty translation unit.
+
+.. note::
+
+ This behavior is currently only approximated when building a module. Entities within a submodule that has already been built are visible when building later submodules in that module. This can lead to fragile modules that depend on the build order used for the submodules of the module, and should not be relied upon.
+
+As an example, in C, this implies that if two structs are defined in different submodules with the same name, those two types are distinct types (but may be *compatible* types if their definitions match. In C++, two structs defined with the same name in different submodules are the *same* type, and must be equivalent under C++'s One Definition Rule.
+
+.. note::
+
+ Clang currently only performs minimal checking for violations of the One Definition Rule.
+
+Macros
+------
+
+The C and C++ preprocessor assumes that the input text is a single linear buffer, but with modules this is not the case. It is possible to import two modules that have conflicting definitions for a macro (or where one ``#define``\s a macro and the other ``#undef``\ines it). The rules for handling macro definitions in the presence of modules are as follows:
+
+* Each definition and undefinition of a macro is considered to be a distinct entity.
+* Such entities are *visible* if they are from the current submodule or translation unit, or if they were exported from a submodule that has been imported.
+* A ``#define X`` or ``#undef X`` directive *overrides* all definitions of ``X`` that are visible at the point of the directive.
+* A ``#define`` or ``#undef`` directive is *active* if it is visible and no visible directive overrides it.
+* A set of macro directives is *consistent* if it consists of only ``#undef`` directives, or if all ``#define`` directives in the set define the macro name to the same sequence of tokens (following the usual rules for macro redefinitions).
+* If a macro name is used and the set of active directives is not consistent, the program is ill-formed. Otherwise, the (unique) meaning of the macro name is used.
+
+For example, suppose:
+
+* ``<stdio.h>`` defines a macro ``getc`` (and exports its ``#define``)
+* ``<cstdio>`` imports the ``<stdio.h>`` module and undefines the macro (and exports its ``#undef``)
+
+The ``#undef`` overrides the ``#define``, and a source file that imports both modules *in any order* will not see ``getc`` defined as a macro.
+
Module Map Language
===================
The module map language describes the mapping from header files to the
logical structure of modules. To enable support for using a library as
-a module, one must write a ``module.map`` file for that library. The
-``module.map`` file is placed alongside the header files themselves,
+a module, one must write a ``module.modulemap`` file for that library. The
+``module.modulemap`` file is placed alongside the header files themselves,
and is written in the module map language described below.
+.. note::
+ For compatibility with previous releases, if a module map file named
+ ``module.modulemap`` is not found, Clang will also search for a file named
+ ``module.map``. This behavior is deprecated and we plan to eventually
+ remove it.
+
As an example, the module map file for the C standard library might look a bit like this:
.. parsed-literal::
- module std [system] {
+ module std [system] [extern_c] {
module complex {
header "complex.h"
export *
@@ -285,13 +325,15 @@
.. parsed-literal::
Name.framework/
- module.map Module map for the framework
+ Modules/module.modulemap Module map for the framework
Headers/ Subdirectory containing framework headers
Frameworks/ Subdirectory containing embedded frameworks
Resources/ Subdirectory containing additional resources
Name Symbolic link to the shared library for the framework
-The ``system`` attribute specifies that the module is a system module. When a system module is rebuilt, all of the module's header will be considered system headers, which suppresses warnings. This is equivalent to placing ``#pragma GCC system_header`` in each of the module's headers. The form of attributes is described in the section Attributes_, below.
+The ``system`` attribute specifies that the module is a system module. When a system module is rebuilt, all of the module's headers will be considered system headers, which suppresses warnings. This is equivalent to placing ``#pragma GCC system_header`` in each of the module's headers. The form of attributes is described in the section Attributes_, below.
+
+The ``extern_c`` attribute specifies that the module contains C code that can be used from within C++. When such a module is built for use in C++ code, all of the module's headers will be treated as if they were contained within an implicit ``extern "C"`` block. An import for a module with this attribute can appear within an ``extern "C"`` block. No other restrictions are lifted, however: the module currently cannot be imported within an ``extern "C"`` block in a namespace.
Modules can have a number of different kinds of members, each of which is described below:
@@ -573,7 +615,7 @@
use B
}
-When compiling a source file that implements a module, use the option ``-fmodule-name=``module-id to indicate that the source file is logically part of that module.
+When compiling a source file that implements a module, use the option ``-fmodule-name=module-id`` to indicate that the source file is logically part of that module.
The compiler at present only applies restrictions to the module directly being built.
@@ -691,6 +733,63 @@
Any *identifier* can be used as an attribute, and each declaration specifies what attributes can be applied to it.
+Private Module Map Files
+------------------------
+Module map files are typically named ``module.modulemap`` and live
+either alongside the headers they describe or in a parent directory of
+the headers they describe. These module maps typically describe all of
+the API for the library.
+
+However, in some cases, the presence or absence of particular headers
+is used to distinguish between the "public" and "private" APIs of a
+particular library. For example, a library may contain the headers
+``Foo.h`` and ``Foo_Private.h``, providing public and private APIs,
+respectively. Additionally, ``Foo_Private.h`` may only be available on
+some versions of library, and absent in others. One cannot easily
+express this with a single module map file in the library:
+
+.. parsed-literal::
+
+ module Foo {
+ header "Foo.h"
+
+ explicit module Private {
+ header "Foo_Private.h"
+ }
+ }
+
+
+because the header ``Foo_Private.h`` won't always be available. The
+module map file could be customized based on whether
+``Foo_Private.h``is available or not, but doing so requires custom
+build machinery.
+
+Private module map files, which are named ``module.private.modulemap``
+(or, for backward compatibility, ``module_private.map``), allow one to
+augment the primary module map file with an additional submodule. For
+example, we would split the module map file above into two module map
+files:
+
+.. parsed-literal::
+
+ /* module.modulemap */
+ module Foo {
+ header "Foo.h"
+ }
+
+ /* module.private.modulemap */
+ explicit module Foo.Private {
+ header "Foo_Private.h"
+ }
+
+
+When a ``module.private.modulemap`` file is found alongside a
+``module.modulemap`` file, it is loaded after the ``module.modulemap``
+file. In our example library, the ``module.private.modulemap`` file
+would be available when ``Foo_Private.h`` is available, making it
+easier to split a library's public and private APIs along header
+boundaries.
+
Modularizing a Platform
=======================
To get any benefit out of modules, one needs to introduce module maps for software libraries starting at the bottom of the stack. This typically means introducing a module map covering the operating system's headers and the C standard library headers (in ``/usr/include``, for a Unix system).
diff --git a/docs/ObjectiveCLiterals.rst b/docs/ObjectiveCLiterals.rst
index 8066d8f..8907c1e 100644
--- a/docs/ObjectiveCLiterals.rst
+++ b/docs/ObjectiveCLiterals.rst
@@ -91,7 +91,7 @@
and ``YES`` and ``NO`` were macros that expand to ``(BOOL)1`` and
``(BOOL)0`` respectively. To support ``@YES`` and ``@NO`` expressions,
these macros are now defined using new language keywords in
-``<objc/objc.h>``:
+``<objc/objc.h>``:
.. code-block:: objc
@@ -251,7 +251,7 @@
sub-expressions of a dictionary literal must be Objective-C object
pointer typed, as in array literals. Key sub-expressions must be of an
Objective-C object pointer type that implements the
-``<NSCopying>`` protocol.
+``<NSCopying>`` protocol.
Discussion
----------
diff --git a/docs/ReleaseNotes.rst b/docs/ReleaseNotes.rst
index b24bca9..df27af9 100644
--- a/docs/ReleaseNotes.rst
+++ b/docs/ReleaseNotes.rst
@@ -1,16 +1,24 @@
-=======================
-Clang 3.4 Release Notes
-=======================
+=====================================
+Clang 3.5 (In-Progress) Release Notes
+=====================================
.. contents::
:local:
:depth: 2
+Written by the `LLVM Team <http://llvm.org/>`_
+
+.. warning::
+
+ These are in-progress notes for the upcoming Clang 3.5 release. You may
+ prefer the `Clang 3.4 Release Notes
+ <http://llvm.org/releases/3.4/tools/clang/docs/ReleaseNotes.html>`_.
+
Introduction
============
This document contains the release notes for the Clang C/C++/Objective-C
-frontend, part of the LLVM Compiler Infrastructure, release 3.4. Here we
+frontend, part of the LLVM Compiler Infrastructure, release 3.5. Here we
describe the status of Clang in some detail, including major
improvements from the previous release and new feature work. For the
general LLVM release notes, see `the LLVM
@@ -18,252 +26,138 @@
releases may be downloaded from the `LLVM releases web
site <http://llvm.org/releases/>`_.
-For more information about Clang or LLVM, including information about the
-latest release, please check out the main `Clang Web Site
-<http://clang.llvm.org>`_ or the `LLVM Web Site <http://llvm.org>`_.
+For more information about Clang or LLVM, including information about
+the latest release, please check out the main please see the `Clang Web
+Site <http://clang.llvm.org>`_ or the `LLVM Web
+Site <http://llvm.org>`_.
-Note that if you are reading this file from a Subversion checkout or the main
-Clang web page, this document applies to the *next* release, not the current
-one. To see the release notes for a specific release, please see the `releases
-page <http://llvm.org/releases/>`_.
+Note that if you are reading this file from a Subversion checkout or the
+main Clang web page, this document applies to the *next* release, not
+the current one. To see the release notes for a specific release, please
+see the `releases page <http://llvm.org/releases/>`_.
-What's New in Clang 3.4?
+What's New in Clang 3.5?
========================
-Some of the major new features and improvements to Clang are listed here.
-Generic improvements to Clang as a whole or to its underlying infrastructure
-are described first, followed by language-specific sections with improvements
-to Clang's support for those languages.
-
-Last release which will build as C++98
---------------------------------------
-
-This is expected to be the last release of Clang which compiles using a C++98
-toolchain. We expect to start using some C++11 features in Clang starting after
-this release. That said, we are committed to supporting a reasonable set of
-modern C++ toolchains as the host compiler on all of the platforms. This will
-at least include Visual Studio 2012 on Windows, and Clang 3.1 or GCC 4.7.x on
-Mac and Linux. The final set of compilers (and the C++11 features they support)
-is not set in stone, but we wanted users of Clang to have a heads up that the
-next release will involve a substantial change in the host toolchain
-requirements.
-
-Note that this change is part of a change for the entire LLVM project, not just
-Clang.
+Some of the major new features and improvements to Clang are listed
+here. Generic improvements to Clang as a whole or to its underlying
+infrastructure are described first, followed by language-specific
+sections with improvements to Clang's support for those languages.
Major New Features
------------------
+- Clang uses the new MingW ABI
+ GCC 4.7 changed the mingw ABI. Clang 3.4 and older use the GCC 4.6
+ ABI. Clang 3.5 and newer use the GCC 4.7 abi.
+
+- The __has_attribute feature test is now target-aware. Older versions of Clang
+ would return true when the attribute spelling was known, regardless of whether
+ the attribute was available to the specific target. Clang now returns true only
+ when the attribute pertains to the current compilation target.
+
+
Improvements to Clang's diagnostics
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Clang's diagnostics are constantly being improved to catch more issues, explain
-them more clearly, and provide more accurate source information about them. The
-improvements since the 3.3 release include:
+Clang's diagnostics are constantly being improved to catch more issues,
+explain them more clearly, and provide more accurate source information
+about them. The improvements since the 3.4 release include:
-- -Wheader-guard warns on mismatches between the #ifndef and #define lines
- in a header guard.
-
- .. code-block:: c
-
- #ifndef multiple
- #define multi
- #endif
-
- returns
- `warning: 'multiple' is used as a header guard here, followed by #define of a different macro [-Wheader-guard]`
-
-- -Wlogical-not-parentheses warns when a logical not ('!') only applies to the
- left-hand side of a comparison. This warning is part of -Wparentheses.
-
- .. code-block:: c++
-
- int i1 = 0, i2 = 1;
- bool ret;
- ret = !i1 == i2;
-
- returns
- `warning: logical not is only applied to the left hand side of this comparison [-Wlogical-not-parentheses]`
-
-
-- Boolean increment, a deprecated feature, has own warning flag
- -Wdeprecated-increment-bool, and is still part of -Wdeprecated.
-- Clang errors on builtin enum increments and decrements in C++.
-
- .. code-block:: c++
-
- enum A { A1, A2 };
- void test() {
- A a;
- a++;
- }
-
- returns
- `error: cannot increment expression of enum type 'A'`
-
-
-- -Wloop-analysis now warns on for-loops which have the same increment or
- decrement in the loop header as the last statement in the loop.
-
- .. code-block:: c
-
- void foo(char *a, char *b, unsigned c) {
- for (unsigned i = 0; i < c; ++i) {
- a[i] = b[i];
- ++i;
- }
- }
-
- returns
- `warning: variable 'i' is incremented both in the loop header and in the loop body [-Wloop-analysis]`
-
-- -Wuninitialized now performs checking across field initializers to detect
- when one field in used uninitialized in another field initialization.
-
- .. code-block:: c++
-
- class A {
- int x;
- int y;
- A() : x(y) {}
- };
-
- returns
- `warning: field 'y' is uninitialized when used here [-Wuninitialized]`
-
-- Clang can detect initializer list use inside a macro and suggest parentheses
- if possible to fix.
-- Many improvements to Clang's typo correction facilities, such as:
-
- + Adding global namespace qualifiers so that corrections can refer to shadowed
- or otherwise ambiguous or unreachable namespaces.
- + Including accessible class members in the set of typo correction candidates,
- so that corrections requiring a class name in the name specifier are now
- possible.
- + Allowing typo corrections that involve removing a name specifier.
- + In some situations, correcting function names when a function was given the
- wrong number of arguments, including situations where the original function
- name was correct but was shadowed by a lexically closer function with the
- same name yet took a different number of arguments.
- + Offering typo suggestions for 'using' declarations.
- + Providing better diagnostics and fixit suggestions in more situations when
- a '->' was used instead of '.' or vice versa.
- + Providing more relevant suggestions for typos followed by '.' or '='.
- + Various performance improvements when searching for typo correction
- candidates.
-
-- `LeakSanitizer <LeakSanitizer.html>`_ is an experimental memory leak detector
- which can be combined with AddressSanitizer.
+- ...
New Compiler Flags
------------------
-- Clang no longer special cases -O4 to enable lto. Explicitly pass -flto to
- enable it.
-- Clang no longer fails on >= -O5. These flags are mapped to -O3 instead.
-- Command line "clang -O3 -flto a.c -c" and "clang -emit-llvm a.c -c"
- are no longer equivalent.
-- Clang now errors on unknown -m flags (``-munknown-to-clang``),
- unknown -f flags (``-funknown-to-clang``) and unknown
- options (``-what-is-this``).
+The integrated assembler is now turned on by default on ARM (and Thumb),
+so the use of the option `-fintegrated-as` is now redundant on those
+architectures. This is an important move to both *eat our own dog food*
+and to ease cross-compilation tremendously.
+
+We are aware of the problems that this may cause for code bases that
+rely on specific GNU syntax or extensions, and we're working towards
+getting them all fixed. Please, report bugs or feature requests if
+you find anything. In the meantime, use `-fno-integrated-as` to revert
+back the call to GNU assembler.
+
+In order to provide better diagnostics, the integrated assembler validates
+inline assembly when the integrated assembler is enabled. Because this is
+considered a feature of the compiler, it is controlled via the `fintegrated-as`
+and `fno-integrated-as` flags which enable and disable the integrated assembler
+respectively. `-integrated-as` and `-no-integrated-as` are now considered
+legacy flags (but are available as an alias to prevent breaking existing users),
+and users are encouraged to switch to the equivalent new feature flag.
+
+Deprecated flags `-faddress-sanitizer`, `-fthread-sanitizer`,
+`-fcatch-undefined-behavior` and `-fbounds-checking` were removed in favor of
+`-fsanitize=` family of flags.
C Language Changes in Clang
---------------------------
-- Added new checked arithmetic builtins for security critical applications.
+...
+
+C11 Feature Support
+^^^^^^^^^^^^^^^^^^^
+
+...
C++ Language Changes in Clang
-----------------------------
-- Fixed an ABI regression, introduced in Clang 3.2, which affected
- member offsets for classes inheriting from certain classes with tail padding.
- See `PR16537 <http://llvm.org/PR16537>`_.
+- ...
-- Clang 3.4 supports the 2013-08-28 draft of the ISO WG21 SG10 feature test
- macro recommendations. These aim to provide a portable method to determine
- whether a compiler supports a language feature, much like Clang's
- |has_feature macro|_.
-
-.. |has_feature macro| replace:: ``__has_feature`` macro
-.. _has_feature macro: LanguageExtensions.html#has-feature-and-has-extension
-
-C++1y Feature Support
+C++11 Feature Support
^^^^^^^^^^^^^^^^^^^^^
-Clang 3.4 supports all the features in the current working draft of the
-upcoming C++ standard, provisionally named C++1y. Support for the following
-major new features has been added since Clang 3.3:
+...
-- Generic lambdas and initialized lambda captures.
-- Deduced function return types (``auto f() { return 0; }``).
-- Generalized ``constexpr`` support (variable mutation and loops).
-- Variable templates and static data member templates.
-- Use of ``'`` as a digit separator in numeric literals.
-- Support for sized ``::operator delete`` functions.
+Objective-C Language Changes in Clang
+-------------------------------------
-In addition, ``[[deprecated]]`` is now accepted as a synonym for Clang's
-existing ``deprecated`` attribute.
-
-Use ``-std=c++1y`` to enable C++1y mode.
+...
OpenCL C Language Changes in Clang
----------------------------------
-- OpenCL C "long" now always has a size of 64 bit, and all OpenCL C
- types are aligned as specified in the OpenCL C standard. Also,
- "char" is now always signed.
+...
Internal API Changes
--------------------
-These are major API changes that have happened since the 3.3 release of
+These are major API changes that have happened since the 3.4 release of
Clang. If upgrading an external codebase that uses Clang as a library,
this section should help get you past the largest hurdles of upgrading.
-Wide Character Types
-^^^^^^^^^^^^^^^^^^^^
+...
-The ASTContext class now keeps track of two different types for wide character
-types: WCharTy and WideCharTy. WCharTy represents the built-in wchar_t type
-available in C++. WideCharTy is the type used for wide character literals; in
-C++ it is the same as WCharTy, but in C99, where wchar_t is a typedef, it is an
-integer type.
+libclang
+--------
+
+...
Static Analyzer
---------------
-The static analyzer has been greatly improved. This impacts the overall analyzer quality and reduces a number of false positives.
-In particular, this release provides enhanced C++ support, reasoning about initializer lists, zeroing constructors, noreturn destructors and modeling of destructor calls on calls to delete.
+...
-Clang Format
-------------
+Core Analysis Improvements
+==========================
-Clang now includes a new tool ``clang-format`` which can be used to
-automatically format C, C++ and Objective-C source code. ``clang-format``
-automatically chooses linebreaks and indentation and can be easily integrated
-into editors, IDEs and version control systems. It supports several pre-defined
-styles as well as precise style control using a multitude of formatting
-options. ``clang-format`` itself is just a thin wrapper around a library which
-can also be used directly from code refactoring and code translation tools.
-More information can be found on `Clang Format's
-site <http://clang.llvm.org/docs/ClangFormat.html>`_.
+- ...
-Windows Support
----------------
+New Issues Found
+================
-- `clang-cl <UsersManual.html#clang-cl>`_ provides a new driver mode that is
- designed for compatibility with Visual Studio's compiler, cl.exe. This driver
- mode makes Clang accept the same kind of command-line options as cl.exe. The
- installer will attempt to expose clang-cl in any Visual Studio installations
- on the system as a Platform Toolset, e.g. "LLVM-vs2012". clang-cl targets the
- Microsoft ABI by default. Please note that this driver mode and compatibility
- with the MS ABI is highly experimental.
+- ...
Python Binding Changes
----------------------
The following methods have been added:
+- ...
+
Significant Known Problems
==========================
@@ -272,7 +166,7 @@
A wide variety of additional information is available on the `Clang web
page <http://clang.llvm.org/>`_. The web page contains versions of the
-API documentation which are up-to-date with the Subversion revision of
+API documentation which are up-to-date with the Subversion version of
the source code. You can access versions of these documents specific to
this release by going into the "``clang/docs/``" directory in the Clang
tree.
diff --git a/docs/ThreadSafetyAnalysis.rst b/docs/ThreadSafetyAnalysis.rst
new file mode 100644
index 0000000..dfef80b
--- /dev/null
+++ b/docs/ThreadSafetyAnalysis.rst
@@ -0,0 +1,818 @@
+
+======================
+Thread Safety Analysis
+======================
+
+Introduction
+============
+
+Clang Thread Safety Analysis is a C++ language extension which warns about
+potential race conditions in code. The analysis is completely static (i.e.
+compile-time); there is no run-time overhead. The analysis is still
+under active development, but it is mature enough to be deployed in an
+industrial setting. It being developed by Google, and is used extensively
+on their internal code base.
+
+Thread safety analysis works very much like a type system for multi-threaded
+programs. In addition to declaring the *type* of data (e.g. ``int``, ``float``,
+etc.), the programmer can (optionally) declare how access to that data is
+controlled in a multi-threaded environment. For example, if ``foo`` is
+*guarded by* the mutex ``mu``, then the analysis will issue a warning whenever
+a piece of code reads or writes to ``foo`` without first locking ``mu``.
+Similarly, if there are particular routines that should only be called by
+the GUI thread, then the analysis will warn if other threads call those
+routines.
+
+Getting Started
+----------------
+
+.. code-block:: c++
+
+ #include "mutex.h"
+
+ class BankAccount {
+ private:
+ Mutex mu;
+ int balance GUARDED_BY(mu);
+
+ void depositImpl(int amount) {
+ balance += amount; // WARNING! Cannot write balance without locking mu.
+ }
+
+ void withdrawImpl(int amount) EXCLUSIVE_LOCKS_REQUIRED(mu) {
+ balance -= amount; // OK. Caller must have locked mu.
+ }
+
+ public:
+ void withdraw(int amount) {
+ mu.Lock();
+ withdrawImpl(amount); // OK. We've locked mu.
+ } // WARNING! Failed to unlock mu.
+
+ void transferFrom(BankAccount& b, int amount) {
+ mu.Lock();
+ b.withdrawImpl(amount); // WARNING! Calling withdrawImpl() requires locking b.mu.
+ depositImpl(amount); // OK. depositImpl() has no requirements.
+ mu.Unlock();
+ }
+ };
+
+This example demonstrates the basic concepts behind the analysis. The
+``GUARDED_BY`` attribute declares that a thread must lock ``mu`` before it can
+read or write to ``balance``, thus ensuring that the increment and decrement
+operations are atomic. Similarly, ``EXCLUSIVE_LOCKS_REQUIRED`` declares that
+the calling thread must lock ``mu`` before calling ``withdrawImpl``.
+Because the caller is assumed to have locked ``mu``, it is safe to modify
+``balance`` within the body of the method.
+
+The ``depositImpl()`` method does not have ``EXCLUSIVE_LOCKS_REQUIRED``, so the
+analysis issues a warning. Thread safety analysis is not inter-procedural, so
+caller requirements must be explicitly declared.
+There is also a warning in ``transferFrom()``, because although the method
+locks ``this->mu``, it does not lock ``b.mu``. The analysis understands
+that these are two separate mutexes, in two different objects.
+
+Finally, there is a warning in the ``withdraw()`` method, because it fails to
+unlock ``mu``. Every lock must have a corresponding unlock, and the analysis
+will detect both double locks, and double unlocks. A function is allowed to
+acquire a lock without releasing it, (or vice versa), but it must be annotated
+as such (using ``LOCK``/``UNLOCK_FUNCTION``).
+
+
+Running The Analysis
+--------------------
+
+To run the analysis, simply compile with the ``-Wthread-safety`` flag, e.g.
+
+.. code-block:: bash
+
+ clang -c -Wthread-safety example.cpp
+
+Note that this example assumes the presence of a suitably annotated
+:ref:`mutexheader` that declares which methods perform locking,
+unlocking, and so on.
+
+
+Basic Concepts: Capabilities
+============================
+
+Thread safety analysis provides a way of protecting *resources* with
+*capabilities*. A resource is either a data member, or a function/method
+that provides access to some underlying resource. The analysis ensures that
+the calling thread cannot access the *resource* (i.e. call the function, or
+read/write the data) unless it has the *capability* to do so.
+
+Capabilities are associated with named C++ objects which declare specific
+methods to acquire and release the capability. The name of the object serves
+to identify the capability. The most common example is a mutex. For example,
+if ``mu`` is a mutex, then calling ``mu.Lock()`` causes the calling thread
+to acquire the capability to access data that is protected by ``mu``. Similarly,
+calling ``mu.Unlock()`` releases that capability.
+
+A thread may hold a capability either *exclusively* or *shared*. An exclusive
+capability can be held by only one thread at a time, while a shared capability
+can be held by many threads at the same time. This mechanism enforces a
+multiple-reader, single-writer pattern. Write operations to protected data
+require exclusive access, while read operations require only shared access.
+
+At any given moment during program execution, a thread holds a specific set of
+capabilities (e.g. the set of mutexes that it has locked.) These act like keys
+or tokens that allow the thread to access a given resource. Just like physical
+security keys, a thread cannot make copy of a capability, nor can it destroy
+one. A thread can only release a capability to another thread, or acquire one
+from another thread. The annotations are deliberately agnostic about the
+exact mechanism used to acquire and release capabilities; it assumes that the
+underlying implementation (e.g. the Mutex implementation) does the handoff in
+an appropriate manner.
+
+The set of capabilities that are actually held by a given thread at a given
+point in program execution is a run-time concept. The static analysis works
+by calculating an approximation of that set, called the *capability
+environment*. The capability environment is calculated for every program point,
+and describes the set of capabilities that are statically known to be held, or
+not held, at that particular point. This environment is a conservative
+approximation of the full set of capabilities that will actually held by a
+thread at run-time.
+
+
+Reference Guide
+===============
+
+The thread safety analysis uses attributes to declare threading constraints.
+Attributes must be attached to named declarations, such as classes, methods,
+and data members. Users are *strongly advised* to define macros for the various
+attributes; example definitions can be found in :ref:`mutexheader`, below.
+The following documentation assumes the use of macros.
+
+
+GUARDED_BY(c) and PT_GUARDED_BY(c)
+----------------------------------
+
+``GUARDED_BY`` is an attribute on data members, which declares that the data
+member is protected by the given capability. Read operations on the data
+require shared access, while write operations require exclusive access.
+
+``PT_GUARDED_BY`` is similar, but is intended for use on pointers and smart
+pointers. There is no constraint on the data member itself, but the *data that
+it points to* is protected by the given capability.
+
+.. code-block:: c++
+
+ Mutex mu;
+ int *p1 GUARDED_BY(mu);
+ int *p2 PT_GUARDED_BY(mu);
+ unique_ptr<int> p3 PT_GUARDED_BY(mu);
+
+ void test() {
+ p1 = 0; // Warning!
+
+ p2 = new int; // OK.
+ *p2 = 42; // Warning!
+
+ p3.reset(new int); // OK.
+ *p3 = 42; // Warning!
+ }
+
+
+EXCLUSIVE_LOCKS_REQUIRED(...), SHARED_LOCKS_REQUIRED(...)
+---------------------------------------------------------
+
+``EXCLUSIVE_LOCKS_REQUIRED`` is an attribute on functions or methods, which
+declares that the calling thread must have exclusive access to the given
+capabilities. More than one capability may be specified. The capabilities
+must be held on entry to the function, *and must still be held on exit*.
+
+``SHARED_LOCKS_REQUIRED`` is similar, but requires only shared access.
+
+.. code-block:: c++
+
+ Mutex mu1, mu2;
+ int a GUARDED_BY(mu1);
+ int b GUARDED_BY(mu2);
+
+ void foo() EXCLUSIVE_LOCKS_REQUIRED(mu1, mu2) {
+ a = 0;
+ b = 0;
+ }
+
+ void test() {
+ mu1.Lock();
+ foo(); // Warning! Requires mu2.
+ mu1.Unlock();
+ }
+
+
+EXCLUSIVE_LOCK_FUNCTION(...), SHARED_LOCK_FUNCTION(...), UNLOCK_FUNCTION(...)
+-----------------------------------------------------------------------------
+
+``EXCLUSIVE_LOCK_FUNCTION`` is an attribute on functions or methods, which
+declares that the function acquires a capability, but does not release it. The
+caller must not hold the given capability on entry, and it will hold the
+capability on exit. ``SHARED_LOCK_FUNCTION`` is similar.
+
+``UNLOCK_FUNCTION`` declares that the function releases the given capability.
+The caller must hold the capability on entry, and will no longer hold it on
+exit. It does not matter whether the given capability is shared or exclusive.
+
+.. code-block:: c++
+
+ Mutex mu;
+ MyClass myObject GUARDED_BY(mu);
+
+ void lockAndInit() EXCLUSIVE_LOCK_FUNCTION(mu) {
+ mu.Lock();
+ myObject.init();
+ }
+
+ void cleanupAndUnlock() UNLOCK_FUNCTION(mu) {
+ myObject.cleanup();
+ } // Warning! Need to unlock mu.
+
+ void test() {
+ lockAndInit();
+ myObject.doSomething();
+ cleanupAndUnlock();
+ myObject.doSomething(); // Warning, mu is not locked.
+ }
+
+If no argument is passed to ``(UN)LOCK_FUNCTION``, then the argument is assumed
+to be ``this``, and the analysis will not check the body of the function. This
+pattern is intended for use by classes which hide locking details behind an
+abstract interface. E.g.
+
+.. code-block:: c++
+
+ template <class T>
+ class LOCKABLE Container {
+ private:
+ Mutex mu;
+ T* data;
+
+ public:
+ // Hide mu from public interface.
+ void Lock() EXCLUSIVE_LOCK_FUNCTION() { mu.Lock(); }
+ void Unlock() UNLOCK_FUNCTION() { mu.Unlock(); }
+
+ T& getElem(int i) { return data[i]; }
+ };
+
+ void test() {
+ Container<int> c;
+ c.Lock();
+ int i = c.getElem(0);
+ c.Unlock();
+ }
+
+
+LOCKS_EXCLUDED(...)
+-------------------
+
+``LOCKS_EXCLUDED`` is an attribute on functions or methods, which declares that
+the caller must *not* hold the given capabilities. This annotation is
+used to prevent deadlock. Many mutex implementations are not re-entrant, so
+deadlock can occur if the function in question acquires the mutex a second time.
+
+.. code-block:: c++
+
+ Mutex mu;
+ int a GUARDED_BY(mu);
+
+ void clear() LOCKS_EXCLUDED(mu) {
+ mu.Lock();
+ a = 0;
+ mu.Unlock();
+ }
+
+ void reset() {
+ mu.Lock();
+ clear(); // Warning! Caller cannot hold 'mu'.
+ mu.Unlock();
+ }
+
+Unlike ``LOCKS_REQUIRED``, ``LOCKS_EXCLUDED`` is optional. The analysis will
+not issue a warning if the attribute is missing. See :ref:`limitations`.
+
+
+NO_THREAD_SAFETY_ANALYSIS
+-------------------------
+
+``NO_THREAD_SAFETY_ANALYSIS`` is an attribute on functions or methods, which
+turns off thread safety checking for that method. It provides an escape hatch
+for functions which are either (1) deliberately thread-unsafe, or (2) are
+thread-safe, but too complicated for the analysis to understand. Reasons for
+(2) will be described in the :ref:`limitations`, below.
+
+.. code-block:: c++
+
+ class Counter {
+ Mutex mu;
+ int a GUARDED_BY(mu);
+
+ void unsafeIncrement() NO_THREAD_SAFETY_ANALYSIS { a++; }
+ };
+
+
+LOCK_RETURNED(c)
+----------------
+
+``LOCK_RETURNED`` is an attribute on functions or methods, which declares that
+the function returns a reference to the given capability. It is used to
+annotate getter methods that return mutexes.
+
+.. code-block:: c++
+
+ class MyClass {
+ private:
+ Mutex mu;
+ int a GUARDED_BY(mu);
+
+ public:
+ Mutex* getMu() LOCK_RETURNED(mu) { return μ }
+
+ // analysis knows that getMu() == mu
+ void clear() EXCLUSIVE_LOCKS_REQUIRED(getMu()) { a = 0; }
+ };
+
+
+ACQUIRED_BEFORE(...), ACQUIRED_AFTER(...)
+-----------------------------------------
+
+``ACQUIRED_BEFORE`` and ``ACQUIRED_AFTER`` are attributes on member
+declarations, specifically declarations of mutexes or other capabilities.
+These declarations enforce a particular order in which the mutexes must be
+acquired, in order to prevent deadlock.
+
+.. code-block:: c++
+
+ Mutex m1;
+ Mutex m2 ACQUIRED_AFTER(m1);
+
+ // Alternative declaration
+ // Mutex m2;
+ // Mutex m1 ACQUIRED_BEFORE(m2);
+
+ void foo() {
+ m2.Lock();
+ m1.Lock(); // Warning! m2 must be acquired after m1.
+ m1.Unlock();
+ m2.Unlock();
+ }
+
+
+LOCKABLE
+--------
+
+``LOCKABLE`` is an attribute on classes, which specifies that objects of the
+class can be used as a capability. See the ``Container`` example given above,
+or the ``Mutex`` class in :ref:`mutexheader`.
+
+
+SCOPED_LOCKABLE
+---------------
+
+``SCOPED_LOCKABLE`` is an attribute on classes that implement RAII-style
+locking, in which a capability is acquired in the constructor, and released in
+the destructor. Such classes require special handling because the constructor
+and destructor refer to the capability via different names; see the
+``MutexLocker`` class in :ref:`mutexheader`, below.
+
+
+EXCLUSIVE_TRYLOCK_FUNCTION(<bool>, ...), SHARED_TRYLOCK_FUNCTION(<bool>, ...)
+-----------------------------------------------------------------------------
+
+These are attributes on a function or method that tries to acquire the given
+capability, and returns a boolean value indicating success or failure.
+The first argument must be ``true`` or ``false``, to specify which return value
+indicates success, and the remaining arguments are interpreted in the same way
+as ``(UN)LOCK_FUNCTION``. See :ref:`mutexheader`, below, for example uses.
+
+
+ASSERT_EXCLUSIVE_LOCK(...) and ASSERT_SHARED_LOCK(...)
+------------------------------------------------------
+
+These are attributes on a function or method that does a run-time test to see
+whether the calling thread holds the given capability. The function is assumed
+to fail (no return) if the capability is not held. See :ref:`mutexheader`,
+below, for example uses.
+
+
+GUARDED_VAR and PT_GUARDED_VAR
+------------------------------
+
+Use of these attributes has been deprecated.
+
+
+Warning flags
+-------------
+
+* ``-Wthread-safety``: Umbrella flag which turns on the following three:
+
+ + ``-Wthread-safety-attributes``: Sanity checks on attribute syntax.
+ + ``-Wthread-safety-analysis``: The core analysis.
+ + ``-Wthread-safety-precise``: Requires that mutex expressions match precisely.
+ This warning can be disabled for code which has a lot of aliases.
+
+When new features and checks are added to the analysis, they can often introduce
+additional warnings. Those warnings are initially released as *beta* warnings
+for a period of time, after which they are migrated to the standard analysis.
+
+* ``-Wthread-safety-beta``: New features. Off by default.
+
+
+.. _faq:
+
+Frequently Asked Questions
+==========================
+
+(Q) Should I put attributes in the header file, or in the .cc/.cpp/.cxx file?
+
+(A) Attributes should always go in the header.
+
+
+(Q) "*Mutex is not locked on every path through here?*" What does that mean?
+
+(A) See :ref:`conditional_locks`, below.
+
+
+.. _limitations:
+
+Known Limitations
+=================
+
+Lexical scope
+-------------
+
+Thread safety attributes contain ordinary C++ expressions, and thus follow
+ordinary C++ scoping rules. In particular, this means that mutexes and other
+capabilities must be declared before they can be used in an attribute.
+Use-before-declaration is okay within a single class, because attributes are
+parsed at the same time as method bodies. (C++ delays parsing of method bodies
+until the end of the class.) However, use-before-declaration is not allowed
+between classes, as illustrated below.
+
+.. code-block:: c++
+
+ class Foo;
+
+ class Bar {
+ void bar(Foo* f) EXCLUSIVE_LOCKS_REQUIRED(f->mu); // Error: mu undeclared.
+ };
+
+ class Foo {
+ Mutex mu;
+ };
+
+
+Private Mutexes
+---------------
+
+Good software engineering practice dictates that mutexes should be private
+members, because the locking mechanism used by a thread-safe class is part of
+its internal implementation. However, private mutexes can sometimes leak into
+the public interface of a class.
+Thread safety attributes follow normal C++ access restrictions, so if ``mu``
+is a private member of ``c``, then it is an error to write ``c.mu`` in an
+attribute.
+
+One workround is to (ab)use the ``LOCK_RETURNED`` attribute to provide a public
+*name* for a private mutex, without actually exposing the underlying mutex.
+For example:
+
+.. code-block:: c++
+
+ class MyClass {
+ private:
+ Mutex mu;
+
+ public:
+ // For thread safety analysis only. Does not actually return mu.
+ Mutex* getMu() LOCK_RETURNED(mu) { return 0; }
+
+ void doSomething() EXCLUSIVE_LOCKS_REQUIRED(mu);
+ };
+
+ void doSomethingTwice(MyClass& c) EXCLUSIVE_LOCKS_REQUIRED(c.getMu()) {
+ // The analysis thinks that c.getMu() == c.mu
+ c.doSomething();
+ c.doSomething();
+ }
+
+In the above example, ``doSomethingTwice()`` is an external routine that
+requires ``c.mu`` to be locked, which cannot be declared directly because ``mu``
+is private. This pattern is discouraged because it
+violates encapsulation, but it is sometimes necessary, especially when adding
+annotations to an existing code base. The workaround is to define ``getMu()``
+as a fake getter method, which is provided only for the benefit of thread
+safety analysis.
+
+
+False negatives on pass by reference.
+-------------------------------------
+
+The current version of the analysis only checks operations which refer to
+guarded data members directly by name. If the data members are accessed
+indirectly, via a pointer or reference, then no warning is generated. Thus,
+no warnings will be generated for the following code:
+
+.. code-block:: c++
+
+ Mutex mu;
+ int a GUARDED_BY(mu);
+
+ void clear(int& ra) { ra = 0; }
+
+ void test() {
+ int *p = &a;
+ *p = 0; // No warning. *p is an alias to a.
+
+ clear(a); // No warning. 'a' is passed by reference.
+ }
+
+This issue is by far the biggest source of false negatives in the current
+version of the analysis. At a fundamental level, the
+false negatives are caused by the fact that annotations are attached to data
+members, rather than types. The type of ``&a`` should really be
+``int GUARDED_BY(mu)*``, rather than ``int*``, and the statement ``p = &a``
+should thus generate a type error. However, attaching attributes to types
+would be an invasive change to the C++ type system, with potential
+ramifications with respect to template instantation, function overloading,
+and so on. Thus, a complete solution to this issue is simply not feasible.
+
+Future versions of the analysis will include better support for pointer
+alias analysis, along with limited checking of guarded types, in order to
+reduce the number of false negatives.
+
+
+.. _conditional_locks:
+
+No conditionally held locks.
+----------------------------
+
+The analysis must be able to determine whether a lock is held, or not held, at
+every program point. Thus, sections of code where a lock *might be held* will
+generate spurious warnings (false positives). For example:
+
+.. code-block:: c++
+
+ void foo() {
+ bool b = needsToLock();
+ if (b) mu.Lock();
+ ... // Warning! Mutex 'mu' is not held on every path through here.
+ if (b) mu.Unlock();
+ }
+
+
+No checking inside constructors and destructors.
+------------------------------------------------
+
+The analysis currently does not do any checking inside constructors or
+destructors. In other words, every constructor and destructor is treated as
+if it was annotated with ``NO_THREAD_SAFETY_ANALYSIS``.
+The reason for this is that during initialization, only one thread typically
+has access to the object which is being initialized, and it is thus safe (and
+common practice) to initialize guarded members without acquiring any locks.
+The same is true of destructors.
+
+Ideally, the analysis would allow initialization of guarded members inside the
+object being initialized or destroyed, while still enforcing the usual access
+restrictions on everything else. However, this is difficult to enforce in
+practice, because in complex pointer-based data structures, it is hard to
+determine what data is "owned by" the enclosing object.
+
+No inlining.
+------------
+
+Thread safety analysis is strictly intra-procedural, just like ordinary type
+checking. It relies only on the declared attributes of a function, and will
+not attempt to "step inside", or inline any method calls. As a result, code
+such as the following will not work:
+
+.. code-block:: c++
+
+ template<class T>
+ class AutoCleanup {
+ T* object;
+ void (T::*mp)();
+
+ public:
+ AutoCleanup(T* obj, void (T::*imp)()) : object(obj), mp(imp) { }
+ ~AutoCleanup() { (object->*mp)(); }
+ };
+
+ Mutex mu;
+ void foo() {
+ mu.Lock();
+ AutoCleanup<Mutex>(&mu, &Mutex::Unlock);
+ ...
+ } // Warning, mu is not unlocked.
+
+In this case, the destructor of ``Autocleanup`` calls ``mu.Unlock()``, so
+the warning is bogus. However,
+thread safety analysis cannot see the unlock, because it does not attempt to
+inline the destructor. Moreover, there is no way to annotate the destructor,
+because the destructor is calling a function that is not statically known.
+This pattern is simply not supported.
+
+
+LOCKS_EXCLUDED is not transitive.
+---------------------------------
+
+A function which calls a method marked with LOCKS_EXCLUDED is not required to
+put LOCKS_EXCLUDED in its own interface. LOCKS_EXCLUDED behaves differently
+from LOCKS_REQUIRED in this respect, and it can result in false negatives:
+
+.. code-block:: c++
+
+ class Foo {
+ Mutex mu;
+
+ void foo() {
+ mu.Lock();
+ bar(); // No warning
+ mu.Unlock();
+ }
+
+ void bar() { baz(); } // No warning. (Should have LOCKS_EXCLUDED(mu).)
+
+ void baz() LOCKS_EXCLUDED(mu);
+ };
+
+The lack of transitivity is due to the fact that LOCKS_EXCLUDED can easily
+break encapsulation; it would be a bad idea to require functions to list the
+names private locks which happen to be acquired internally.
+
+
+No alias analysis.
+------------------
+
+The analysis currently does not track pointer aliases. Thus, there can be
+false positives if two pointers both point to the same mutex.
+
+
+.. code-block:: c++
+
+ class MutexUnlocker {
+ Mutex* mu;
+
+ public:
+ MutexUnlocker(Mutex* m) UNLOCK_FUNCTION(m) : mu(m) { mu->Unlock(); }
+ ~MutexUnlocker() EXCLUSIVE_LOCK_FUNCTION(mu) { mu->Lock(); }
+ };
+
+ Mutex mutex;
+ void test() EXCLUSIVE_LOCKS_REQUIRED(mutex) {
+ {
+ MutexUnlocker munl(&mutex); // unlocks mutex
+ doSomeIO();
+ } // Warning: locks munl.mu
+ }
+
+The MutexUnlocker class is intended to be the dual of the MutexLocker class,
+defined in :ref:`mutexheader`. However, it doesn't work because the analysis
+doesn't know that munl.mu == mutex. The SCOPED_LOCKABLE attribute handles
+aliasing
+
+
+ACQUIRED_BEFORE(...) and ACQUIRED_AFTER(...) are currently unimplemented.
+-------------------------------------------------------------------------
+
+To be fixed in a future update.
+
+
+.. _mutexheader:
+
+mutex.h
+=======
+
+Thread safety analysis can be used with any threading library, but it does
+require that the threading API be wrapped in classes and methods which have the
+appropriate annotations. The following code provides ``mutex.h`` as an example;
+these methods should be filled in to call the appropriate underlying
+implementation.
+
+
+.. code-block:: c++
+
+ #ifndef THREAD_SAFETY_ANALYSIS_MUTEX_H
+ #define THREAD_SAFETY_ANALYSIS_MUTEX_H
+
+ // Enable thread safety attributes only with clang.
+ // The attributes can be safely erased when compiling with other compilers.
+ #if defined(__clang__) && (!defined(SWIG))
+ #define THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x))
+ #else
+ #define THREAD_ANNOTATION_ATTRIBUTE__(x) // no-op
+ #endif
+
+ #define THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x))
+
+ #define GUARDED_BY(x) \
+ THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))
+
+ #define GUARDED_VAR \
+ THREAD_ANNOTATION_ATTRIBUTE__(guarded)
+
+ #define PT_GUARDED_BY(x) \
+ THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x))
+
+ #define PT_GUARDED_VAR \
+ THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded)
+
+ #define ACQUIRED_AFTER(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__))
+
+ #define ACQUIRED_BEFORE(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__))
+
+ #define EXCLUSIVE_LOCKS_REQUIRED(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__))
+
+ #define SHARED_LOCKS_REQUIRED(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__))
+
+ #define LOCKS_EXCLUDED(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))
+
+ #define LOCK_RETURNED(x) \
+ THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))
+
+ #define LOCKABLE \
+ THREAD_ANNOTATION_ATTRIBUTE__(lockable)
+
+ #define SCOPED_LOCKABLE \
+ THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)
+
+ #define EXCLUSIVE_LOCK_FUNCTION(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__))
+
+ #define SHARED_LOCK_FUNCTION(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__))
+
+ #define ASSERT_EXCLUSIVE_LOCK(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(assert_exclusive_lock(__VA_ARGS__))
+
+ #define ASSERT_SHARED_LOCK(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_lock(__VA_ARGS__))
+
+ #define EXCLUSIVE_TRYLOCK_FUNCTION(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__))
+
+ #define SHARED_TRYLOCK_FUNCTION(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__))
+
+ #define UNLOCK_FUNCTION(...) \
+ THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__))
+
+ #define NO_THREAD_SAFETY_ANALYSIS \
+ THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)
+
+
+ // Defines an annotated interface for mutexes.
+ // These methods can be implemented to use any internal mutex implementation.
+ class LOCKABLE Mutex {
+ public:
+ // Acquire/lock this mutex exclusively. Only one thread can have exclusive
+ // access at any one time. Write operations to guarded data require an
+ // exclusive lock.
+ void Lock() EXCLUSIVE_LOCK_FUNCTION();
+
+ // Acquire/lock this mutex for read operations, which require only a shared
+ // lock. This assumes a multiple-reader, single writer semantics. Multiple
+ // threads may acquire the mutex simultaneously as readers, but a writer must
+ // wait for all of them to release the mutex before it can acquire it
+ // exclusively.
+ void ReaderLock() SHARED_LOCK_FUNCTION();
+
+ // Release/unlock the mutex, regardless of whether it is exclusive or shared.
+ void Unlock() UNLOCK_FUNCTION();
+
+ // Try to acquire the mutex. Returns true on success, and false on failure.
+ bool TryLock() EXCLUSIVE_TRYLOCK_FUNCTION(true);
+
+ // Try to acquire the mutex for read operations.
+ bool ReaderTryLock() SHARED_TRYLOCK_FUNCTION(true);
+
+ // Assert that this mutex is currently held by the calling thread.
+ void AssertHeld() ASSERT_EXCLUSIVE_LOCK();
+
+ // Assert that is mutex is currently held for read operations.
+ void AssertReaderHeld() ASSERT_SHARED_LOCK();
+ };
+
+
+ // MutexLocker is an RAII class that acquires a mutex in its constructor, and
+ // releases it in its destructor.
+ class SCOPED_LOCKABLE MutexLocker {
+ private:
+ Mutex* mut;
+
+ public:
+ MutexLocker(Mutex *mu) EXCLUSIVE_LOCK_FUNCTION(mu) : mut(mu) {
+ mu->Lock();
+ }
+ ~MutexLocker() UNLOCK_FUNCTION() {
+ mut->Unlock();
+ }
+ };
+
+ #endif // THREAD_SAFETY_ANALYSIS_MUTEX_H
diff --git a/docs/ThreadSanitizer.rst b/docs/ThreadSanitizer.rst
index 194ad4a..a1d81e9 100644
--- a/docs/ThreadSanitizer.rst
+++ b/docs/ThreadSanitizer.rst
@@ -18,9 +18,9 @@
Supported Platforms
-------------------
-ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 10.04 and 12.04).
-Support for MacOS 10.7 (64-bit only) is planned for 2013. Support for 32-bit
-platforms is problematic and not yet planned.
+ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 12.04).
+Support for other 64-bit architectures is possible, contributions are welcome.
+Support for 32-bit platforms is problematic and is not planned.
Usage
-----
diff --git a/docs/UsersManual.rst b/docs/UsersManual.rst
index 96d65a4..5b761a8 100644
--- a/docs/UsersManual.rst
+++ b/docs/UsersManual.rst
@@ -112,11 +112,11 @@
.. option:: -w
- Disable all warnings.
+ Disable all diagnostics.
.. option:: -Weverything
- :ref:`Enable all warnings. <diagnostics_enable_everything>`
+ :ref:`Enable all diagnostics. <diagnostics_enable_everything>`
.. option:: -pedantic
@@ -265,11 +265,6 @@
t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
-**-f[no-]diagnostics-show-name**
- Enable the display of the diagnostic name.
- This option, which defaults to off, controls whether or not Clang
- prints the associated name.
-
.. _opt_fdiagnostics-show-option:
**-f[no-]diagnostics-show-option**
@@ -587,6 +582,7 @@
- Ignored
- Note
+- Remark
- Warning
- Error
- Fatal
@@ -704,17 +700,18 @@
char b = 'ab'; // no warning
-The :option:`-isystem-prefix` and :option:`-ino-system-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
+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 -isystem-prefix x/ -ino-system-prefix x/y/
+ $ 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
@@ -727,11 +724,12 @@
.. _diagnostics_enable_everything:
-Enabling All Warnings
-^^^^^^^^^^^^^^^^^^^^^
+Enabling All Diagnostics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In addition to the traditional ``-W`` flags, one can enable **all**
-warnings by passing :option:`-Weverything`. This works as expected with
+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
@@ -765,7 +763,7 @@
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).
+compilation on systems with very large system headers (e.g., Mac OS X).
Generating a PCH File
^^^^^^^^^^^^^^^^^^^^^
@@ -971,12 +969,17 @@
Extra features of MemorySanitizer (require explicit
``-fsanitize=memory``):
- - ``-fsanitize-memory-track-origins``: Enables origin tracking in
+ - ``-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
@@ -1002,18 +1005,6 @@
program. The ``-fsanitize=undefined`` checks can be combined with other
sanitizers.
-**-f[no-]address-sanitizer**
- Deprecated synonym for :ref:`-f[no-]sanitize=address
- <opt_fsanitize_address>`.
-**-f[no-]thread-sanitizer**
- Deprecated synonym for :ref:`-f[no-]sanitize=thread
- <opt_fsanitize_thread>`.
-
-.. option:: -fcatch-undefined-behavior
-
- Deprecated synonym for :ref:`-fsanitize=undefined
- <opt_fsanitize_undefined>`.
-
.. option:: -fno-assume-sane-operator-new
Don't assume that the C++'s new operator is sane.
@@ -1066,6 +1057,13 @@
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
-------------------------------------
@@ -1091,18 +1089,43 @@
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
@@ -1329,14 +1352,21 @@
^^^
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
+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 conversion. You might need to tweak
+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
^^^
@@ -1377,10 +1407,10 @@
Operating System Features and Limitations
-----------------------------------------
-Darwin (Mac OS/X)
+Darwin (Mac OS X)
^^^^^^^^^^^^^^^^^
-None
+Thread Sanitizer is not supported.
Windows
^^^^^^^
diff --git a/docs/analyzer/conf.py b/docs/analyzer/conf.py
index 3690f93..1514708 100644
--- a/docs/analyzer/conf.py
+++ b/docs/analyzer/conf.py
@@ -41,7 +41,7 @@
# General information about the project.
project = u'Clang Static Analyzer'
-copyright = u'2013, Analyzer Team'
+copyright = u'2013-2014, Analyzer Team'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
diff --git a/docs/conf.py b/docs/conf.py
index 183a285..1963a05 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -41,16 +41,16 @@
# General information about the project.
project = u'Clang'
-copyright = u'2007-2013, The Clang Team'
+copyright = u'2007-2014, The Clang Team'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
-version = '3.4'
+version = '3.5'
# The full version, including alpha/beta/rc tags.
-release = '3.4'
+release = '3.5'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/docs/doxygen.cfg.in b/docs/doxygen.cfg.in
index 61c0bd8..2372e04 100644
--- a/docs/doxygen.cfg.in
+++ b/docs/doxygen.cfg.in
@@ -697,6 +697,59 @@
TOC_EXPAND = NO
+# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and
+# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated
+# that can be used as input for Qt's qhelpgenerator to generate a
+# Qt Compressed Help (.qch) of the generated HTML documentation.
+
+GENERATE_QHP = @clang_doxygen_generate_qhp@
+
+# If the QHG_LOCATION tag is specified, the QCH_FILE tag can
+# be used to specify the file name of the resulting .qch file.
+# The path specified is relative to the HTML output folder.
+
+QCH_FILE = @clang_doxygen_qch_filename@
+
+# The QHP_NAMESPACE tag specifies the namespace to use when generating
+# Qt Help Project output. For more information please see
+# http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace
+
+QHP_NAMESPACE = @clang_doxygen_qhp_namespace@
+
+# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating
+# Qt Help Project output. For more information please see
+# http://qt-project.org/doc/qt-4.8/qthelpproject.html#virtual-folders
+
+QHP_VIRTUAL_FOLDER = doc
+
+# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to
+# add. For more information please see
+# http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters
+
+QHP_CUST_FILTER_NAME = @clang_doxygen_qhp_cust_filter_name@
+
+# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the
+# custom filter to add. For more information please see
+# <a href="http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters">
+# Qt Help Project / Custom Filters</a>.
+
+QHP_CUST_FILTER_ATTRS = @clang_doxygen_qhp_cust_filter_attrs@
+
+# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this
+# project's
+# filter section matches.
+# <a href="http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes">
+# Qt Help Project / Filter Attributes</a>.
+
+QHP_SECT_FILTER_ATTRS =
+
+# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can
+# be used to specify the location of Qt's qhelpgenerator.
+# If non-empty doxygen will try to run qhelpgenerator on the generated
+# .qhp file.
+
+QHG_LOCATION = @clang_doxygen_qhelpgenerator_path@
+
# The DISABLE_INDEX tag can be used to turn on/off the condensed index at
# top of each HTML page. The value NO (the default) enables the index and
# the value YES disables it.
diff --git a/docs/index.rst b/docs/index.rst
index b18deb9..bf2de7e 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -18,7 +18,9 @@
UsersManual
LanguageExtensions
+ AttributeReference
CrossCompilation
+ ThreadSafetyAnalysis
AddressSanitizer
ThreadSanitizer
MemorySanitizer
@@ -26,6 +28,7 @@
LeakSanitizer
SanitizerSpecialCaseList
Modules
+ MSVCCompatibility
FAQ
Using Clang as a Library
diff --git a/docs/tools/clang.pod b/docs/tools/clang.pod
index a58986c..6ccdbba 100644
--- a/docs/tools/clang.pod
+++ b/docs/tools/clang.pod
@@ -237,7 +237,7 @@
=item B<-mmacosx-version-min>=I<version>
-When building for Mac OS/X, specify the minimum version supported by your
+When building for Mac OS X, specify the minimum version supported by your
application.
=item B<-miphoneos-version-min>
@@ -310,8 +310,22 @@
=item B<-g>
Generate debug information. Note that Clang debug information works best at
-B<-O0>. At higher optimization levels, only line number information is
-currently available.
+B<-O0>.
+
+=item B<-fstandalone-debug> B<-fno-standalone-debug>
+
+Clang supports a number of optimizations to reduce the size of debug
+information in the binary. They work based on the assumption that the
+debug type information can be spread out over multiple compilation
+units. For instance, Clang will not emit type definitions for types
+that are not needed by a module and could be replaced with a forward
+declaration. Further, Clang will only emit type info for a dynamic
+C++ class in the module that contains the vtable for the class.
+
+The B<-fstandalone-debug> option turns off these optimizations. This
+is useful when working with 3rd-party libraries that don't come with
+debug information. Note that Clang will never emit type information
+for types that are not referenced at all by the program.
=item B<-fexceptions>
@@ -366,7 +380,7 @@
=item B<-###>
-Print the commands to run for this compilation.
+Print (but do not run) the commands to run for this compilation.
=item B<--help>
diff --git a/docs/tools/dump_ast_matchers.py b/docs/tools/dump_ast_matchers.py
index 564dc38..4ece46a 100644
--- a/docs/tools/dump_ast_matchers.py
+++ b/docs/tools/dump_ast_matchers.py
@@ -119,9 +119,9 @@
# arguments.
elif ('Matcher<' not in args or
name in ['allOf', 'anyOf', 'anything', 'unless']):
- narrowing_matchers[result_type + name] = matcher_html
+ narrowing_matchers[result_type + name + esc(args)] = matcher_html
else:
- traversal_matchers[result_type + name] = matcher_html
+ traversal_matchers[result_type + name + esc(args)] = matcher_html
def act_on_decl(declaration, comment, allowed_types):
"""Parse the matcher out of the given declaration and comment.
@@ -204,6 +204,25 @@
add_matcher(result_type, name, args, comment)
return
+ m = re.match(r"""^\s*AST_MATCHER_FUNCTION(_P)?(.?)(?:_OVERLOAD)?\(
+ (?:\s*([^\s,]+)\s*,)?
+ \s*([^\s,]+)\s*
+ (?:,\s*([^\s,]+)\s*
+ ,\s*([^\s,]+)\s*)?
+ (?:,\s*([^\s,]+)\s*
+ ,\s*([^\s,]+)\s*)?
+ (?:,\s*\d+\s*)?
+ \)\s*{\s*$""", declaration, flags=re.X)
+ if m:
+ p, n, result, name = m.groups()[0:4]
+ args = m.groups()[4:]
+ if n not in ['', '2']:
+ raise Exception('Cannot parse "%s"' % declaration)
+ args = ', '.join('%s %s' % (args[i], args[i+1])
+ for i in range(0, len(args), 2) if args[i])
+ add_matcher(result, name, args, comment)
+ return
+
m = re.match(r"""^\s*AST_MATCHER(_P)?(.?)(?:_OVERLOAD)?\(
(?:\s*([^\s,]+)\s*,)?
\s*([^\s,]+)\s*
@@ -242,12 +261,17 @@
# Parse Variadic operator matchers.
m = re.match(
- r"""^.*VariadicOperatorMatcherFunc\s*([a-zA-Z]*)\s*=\s*{.*};$""",
+ r"""^.*VariadicOperatorMatcherFunc\s*<\s*([^,]+),\s*([^\s>]+)\s*>\s*
+ ([a-zA-Z]*)\s*=\s*{.*};$""",
declaration, flags=re.X)
if m:
- name = m.groups()[0]
- add_matcher('*', name, 'Matcher<*>, ..., Matcher<*>', comment)
- return
+ min_args, max_args, name = m.groups()[:3]
+ if max_args == '1':
+ add_matcher('*', name, 'Matcher<*>', comment)
+ return
+ elif max_args == 'UINT_MAX':
+ add_matcher('*', name, 'Matcher<*>, ..., Matcher<*>', comment)
+ return
# Parse free standing matcher functions, like:
diff --git a/docs/tools/dump_format_style.py b/docs/tools/dump_format_style.py
index 0c8ca6d..addda2a 100644
--- a/docs/tools/dump_format_style.py
+++ b/docs/tools/dump_format_style.py
@@ -98,7 +98,7 @@
enum = Enum(name, comment)
elif line.endswith(';'):
state = State.InStruct
- field_type, field_name = re.match(r'(\w+)\s+(\w+);', line).groups()
+ field_type, field_name = re.match(r'([:\w]+)\s+(\w+);', line).groups()
option = Option(str(field_name), str(field_type), comment)
options.append(option)
else:
@@ -122,7 +122,7 @@
raise Exception('Not finished by the end of file')
for option in options:
- if not option.type in ['bool', 'unsigned', 'int']:
+ if not option.type in ['bool', 'unsigned', 'int', 'std::string']:
if enums.has_key(option.type):
option.enum = enums[option.type]
else: