diff options
Diffstat (limited to 'docs')
30 files changed, 3911 insertions, 1305 deletions
diff --git a/docs/AddressSanitizer.rst b/docs/AddressSanitizer.rst index 5bc6d0b88b43..93a6a0ebaa50 100644 --- a/docs/AddressSanitizer.rst +++ b/docs/AddressSanitizer.rst @@ -61,14 +61,14 @@ or: % 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 @@ offline (this will be fixed in future). #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 @@ Supported Platforms 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 000000000000..115a217c4c19 --- /dev/null +++ b/docs/AttributeReference.rst @@ -0,0 +1,1116 @@ +.. + ------------------------------------------------------------------- + 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_dependency`` +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 generation of more efficient code. + + +enable_if +--------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","","","" + +.. Note:: Some features of this attribute are experimental. The meaning of + multiple enable_if attributes on a single declaration is subject to change in + a future version of clang. Also, the ABI is not standardized and the name + mangling may change in future versions. To avoid that, use asm labels. + +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)``. + + +flatten (gnu::flatten) +---------------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","X","","" + +The ``flatten`` attribute causes calls within the attributed function to +be inlined unless it is impossible to do so, for example if the body of the +callee is unavailable or if the callee has the ``noinline`` attribute. + + +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. + + +no_split_stack (gnu::no_split_stack) +------------------------------------ +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","X","","" + +The ``no_split_stack`` attribute disables the emission of the split stack +preamble for a particular function. It has no effect if ``-fsplit-stack`` +is not specified. + + +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{}; + ^ + + +optnone (clang::optnone) +------------------------ +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","X","","" + +The ``optnone`` attribute suppresses essentially all optimizations +on a function or method, regardless of the optimization level applied to +the compilation unit as a whole. This is particularly useful when you +need to debug a particular function, but it is infeasible to build the +entire application without optimization. Avoiding optimization on the +specified function can improve the quality of the debugging information +for that function. + +This attribute is incompatible with the ``always_inline`` attribute. + + +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)``. + + +pcs (gnu::pcs) +-------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","X","","" + +On ARM targets, this can attribute can be used to select calling conventions, +similar to ``stdcall`` on x86. Valid parameter values are "aapcs" and +"aapcs-vfp". + + +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 +=================== + + +section (gnu::section, __declspec(allocate)) +-------------------------------------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","X","X","" + +The ``section`` attribute allows you to specify a specific section a +global variable or function should be in after translation. + + +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. + + +thread +------ +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "","","X","" + +The ``__declspec(thread)`` attribute declares a variable with thread local +storage. It is available under the ``-fms-extensions`` flag for MSVC +compatibility. Documentation for the Visual C++ attribute is available on MSDN_. + +.. _MSDN: http://msdn.microsoft.com/en-us/library/9w1sdazb.aspx + +In Clang, ``__declspec(thread)`` is generally equivalent in functionality to the +GNU ``__thread`` keyword. The variable must not have a destructor and must have +a constant initializer, if any. The attribute only applies to variables +declared with static storage duration, such as globals, class static data +members, and static locals. + + +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 8528c7af5840..20a1396c4877 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -22,6 +22,31 @@ if (LLVM_ENABLE_DOXYGEN) 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 @@ if (LLVM_ENABLE_DOXYGEN) 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 @@ -49,3 +80,12 @@ if (LLVM_ENABLE_DOXYGEN) endif() endif() endif() + +if (LLVM_ENABLE_SPHINX) + if (SPHINX_FOUND) + include(AddSphinxTarget) + if (${SPHINX_OUTPUT_HTML}) + add_sphinx_target(html clang) + endif() + endif() +endif() diff --git a/docs/ClangFormat.rst b/docs/ClangFormat.rst index bc6b8a2c41fa..86c5ec5e5873 100644 --- a/docs/ClangFormat.rst +++ b/docs/ClangFormat.rst @@ -146,7 +146,7 @@ shortcut in the BBEdit preferences, under Menus & Shortcuts. 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,30 @@ a unified diff and reformats all contained lines with :program:`clang-format`. .. 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 + +In an SVN client, you can do: + +.. code-block:: console + + svn diff --diff-cmd=diff -x-U0 | clang-format-diff.py -i 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 d73801c7e73d..07febaf3898b 100644 --- a/docs/ClangFormatStyleOptions.rst +++ b/docs/ClangFormatStyleOptions.rst @@ -106,6 +106,25 @@ the configuration (without a prefix: ``Auto``). Allow putting all parameters of a function declaration onto the next line even if ``BinPackParameters`` is ``false``. +**AllowShortBlocksOnASingleLine** (``bool``) + Allows contracting simple braced statements to a single line. + + E.g., this allows ``if (a) { return; }`` to be put on a single line. + +**AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``) + Dependent on the value, ``int f() { return 0; }`` can be put + on a single line. + + Possible values: + + * ``SFS_None`` (in configuration: ``None``) + Never merge functions into a single line. + * ``SFS_Inline`` (in configuration: ``Inline``) + Only merge functions defined inside a class. + * ``SFS_All`` (in configuration: ``All``) + Merge all functions fitting on a single line. + + **AllowShortIfStatementsOnASingleLine** (``bool``) If ``true``, ``if (a) return;`` can be put on a single line. @@ -142,8 +161,15 @@ the configuration (without a prefix: ``Auto``). 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 +179,11 @@ the configuration (without a prefix: ``Auto``). 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 +193,9 @@ the configuration (without a prefix: ``Auto``). 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. @@ -178,8 +211,12 @@ the configuration (without a prefix: ``Auto``). the parentheses of a function call with that name. If there is no name, a zero-length name is assumed. -**DerivePointerBinding** (``bool``) - If ``true``, analyze the formatted file for the most common binding. +**DerivePointerAlignment** (``bool``) + If ``true``, analyze the formatted file for the most common + alignment of & and \*. ``PointerAlignment`` is then used only as fallback. + +**DisableFormat** (``bool``) + Disables formatting at all. **ExperimentalAutoDetectBinPacking** (``bool``) If ``true``, clang-format detects whether function calls and @@ -193,19 +230,50 @@ the configuration (without a prefix: ``Auto``). 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 vector of macros that should be interpreted as foreach loops + instead of as function calls. + + These are expected to be macros of the form: + \code + FOREACH(<variable-declaration>, ...) + <loop-body> + \endcode + + For example: BOOST_FOREACH. + **IndentCaseLabels** (``bool``) Indent case labels one level from the switch statement. When ``false``, use the same indentation level as for the switch statement. Switch statement body is always indented one level more than case labels. -**IndentFunctionDeclarationAfterType** (``bool``) - If ``true``, indent when breaking function declarations which - are not also definitions after the type. - **IndentWidth** (``unsigned``) The number of columns to use for indentation. +**IndentWrappedFunctionNames** (``bool``) + Indent if a function definition or declaration is wrapped after the + type. + +**KeepEmptyLinesAtTheStartOfBlocks** (``bool``) + If true, empty lines at the start of blocks are kept. + +**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 +290,17 @@ the configuration (without a prefix: ``Auto``). 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. @@ -242,28 +317,62 @@ the configuration (without a prefix: ``Auto``). Penalty for putting the return type of a function onto its own line. -**PointerBindsToType** (``bool``) - Set whether & and * bind to the type as opposed to the variable. +**PointerAlignment** (``PointerAlignmentStyle``) + Pointer and reference alignment style. + + Possible values: + + * ``PAS_Left`` (in configuration: ``Left``) + Align pointer to the left. + * ``PAS_Right`` (in configuration: ``Right``) + Align pointer to the right. + * ``PAS_Middle`` (in configuration: ``Middle``) + Align pointer in the middle. -**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. + The number of spaces before trailing line comments + (``//`` - comments). + + This does not affect trailing block comments (``/**/`` - comments) as those + commonly have different usage patterns and a number of special cases. + +**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 7c5c65ccf1d4..9a5bc142130b 100644 --- a/docs/ClangPlugins.rst +++ b/docs/ClangPlugins.rst @@ -47,70 +47,10 @@ Putting it all together ======================= 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 f8a7c366dbaf..8957541c2504 100644 --- a/docs/ClangTools.rst +++ b/docs/ClangTools.rst @@ -93,9 +93,9 @@ as a user tool (ideally with powerful IDE integrations) and as part of other 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 c7fd4c51faac..71d50c23fa1e 100644 --- a/docs/ExternalClangExamples.rst +++ b/docs/ExternalClangExamples.rst @@ -78,3 +78,10 @@ List of projects and tools "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 6f5570263fc5..8e047dbdae7a 100644 --- a/docs/InternalsManual.rst +++ b/docs/InternalsManual.rst @@ -87,7 +87,8 @@ start with ``err_``, ``warn_``, ``ext_`` to encode the severity into the name. 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 @@ represent them in the AST, but we produce diagnostics to tell the user their 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 change Clang 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 @@ only defining one diagnostic, you can skip ``DiagnosticGroups.td`` and use ``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 ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1721,13 +1852,14 @@ are similar. * Make sure that ``children()`` visits all of the subexpressions. This is important for a number of features (e.g., IDE support, C++ variadic templates). If you have sub-types, you'll also need to visit those - sub-types in the ``RecursiveASTVisitor``. - * Add printing support (``StmtPrinter.cpp``) and dumping support - (``StmtDumper.cpp``) for your expression. + sub-types in ``RecursiveASTVisitor`` and ``DataRecursiveASTVisitor``. + * Add printing support (``StmtPrinter.cpp``) for your expression. * Add profiling support (``StmtProfile.cpp``) for your AST node, noting the distinguishing (non-source location) characteristics of an instance of your expression. Omitting this step will lead to hard-to-diagnose failures regarding matching of template declarations. + * Add serialization support (``ASTReaderStmt.cpp``, ``ASTWriterStmt.cpp``) + for your AST node. #. Teach semantic analysis to build your AST node. At this point, you can wire up your ``Sema::BuildXXX`` function to actually create your AST. A few diff --git a/docs/LanguageExtensions.rst b/docs/LanguageExtensions.rst index 7a4b31e7acc0..35f759f4cf97 100644 --- a/docs/LanguageExtensions.rst +++ b/docs/LanguageExtensions.rst @@ -12,7 +12,7 @@ Clang Language Extensions ObjectiveCLiterals BlockLanguageSpec Block-ABI-Apple - AutomaticReferenceCounting + AutomaticReferenceCounting Introduction ============ @@ -91,7 +91,7 @@ feature) or 0 if not. They can be used like this: .. _langext-has-feature-back-compat: -For backwards compatibility reasons, ``__has_feature`` can also be used to test +For backward compatibility, ``__has_feature`` can also be used to test for support for non-standardized features, i.e. features not prefixed ``c_``, ``cxx_`` or ``objc_``. @@ -113,8 +113,8 @@ of ``cxx_rvalue_references``. ------------------- 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,27 @@ The attribute name can also be specified with a preceding and following ``__`` (double underscore) to avoid interference from a macro with the same name. For instance, ``__always_inline__`` can be used instead of ``always_inline``. +``__is_identifier`` +------------------- + +This function-like macro takes a single identifier argument that might be either +a reserved word or a regular identifier. It evaluates to 1 if the argument is just +a regular identifier and not a reserved word, in the sense that it can then be +used as the name of a user-defined function or variable. Otherwise it evaluates +to 0. It can be used like this: + +.. code-block:: c++ + + ... + #ifdef __is_identifier // Compatibility with non-clang compilers. + #if __is_identifier(__wchar_t) + typedef wchar_t __wchar_t; + #endif + #endif + + __wchar_t WideCharacter; + ... + Include File Checking Macros ============================ @@ -425,103 +446,6 @@ should be treated as a system framework, regardless of how it was found in the 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 ===================================== @@ -826,20 +750,18 @@ for default initializers in aggregate members is enabled. C++1y generalized lambda capture ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Use ``__has_feature(cxx_init_capture)`` or -``__has_extension(cxx_init_capture)`` to determine if support for +Use ``__has_feature(cxx_init_captures)`` or +``__has_extension(cxx_init_captures)`` 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 ^^^^^^^^^^^^^^^^^^^^^ -Use ``__has_feature(cxx_generic_lambda)`` or -``__has_extension(cxx_generic_lambda)`` to determine if support for generic +Use ``__has_feature(cxx_generic_lambdas)`` or +``__has_extension(cxx_generic_lambdas)`` 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 +794,6 @@ C++1y variable templates 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 +845,33 @@ C11 ``_Thread_local`` 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 +881,10 @@ the type trait. For example: 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 +919,11 @@ The following type traits are supported by Clang: ``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 +1118,6 @@ feature, clang provides default synthesis of those properties not declared ``__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 +1130,7 @@ conventions for ownership of object arguments and 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 +1187,7 @@ parameters of protocol-qualified type. 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 ========================================== @@ -1654,6 +1446,24 @@ object that overloads ``operator&``. return __builtin_addressof(value); } +``__builtin_operator_new`` and ``__builtin_operator_delete`` +------------------------------------------------------------ + +``__builtin_operator_new`` allocates memory just like a non-placement non-class +*new-expression*. This is exactly like directly calling the normal +non-placement ``::operator new``, except that it allows certain optimizations +that the C++ standard does not permit for a direct function call to +``::operator new`` (in particular, removing ``new`` / ``delete`` pairs and +merging allocations). + +Likewise, ``__builtin_operator_delete`` deallocates memory just like a +non-class *delete-expression*, and is exactly like directly calling the normal +``::operator delete``, except that it permits optimizations. Only the unsized +form of ``__builtin_operator_delete`` is currently available. + +These builtins are intended for use in the implementation of ``std::allocator`` +and other similar allocation libraries, and are only available in C++. + Multiprecision Arithmetic Builtins ---------------------------------- @@ -1770,20 +1580,22 @@ instructions for implementing atomic operations. .. code-block:: c T __builtin_arm_ldrex(const volatile T *addr); + T __builtin_arm_ldaex(const volatile T *addr); int __builtin_arm_strex(T val, volatile T *addr); + int __builtin_arm_stlex(T val, volatile T *addr); 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 AArch64). * Floating-point types * Pointer types. Note that the compiler does not guarantee it will not insert stores which clear -the exclusive monitor in between an ``ldrex`` and its paired ``strex``. In -practice this is only usually a risk when the extra store is on the same cache -line as the variable being modified and Clang will only insert stack stores on -its own, so it is best not to use these operations on variables with automatic -storage duration. +the exclusive monitor in between an ``ldrex`` type operation and its paired +``strex``. In practice this is only usually a risk when the extra store is on +the same cache line as the variable being modified and Clang will only insert +stack stores on its own, so it is best not to use these operations on variables +with automatic storage duration. Also, loads and stores may be implicit in code written between the ``ldrex`` and ``strex``. Clang will not necessarily mitigate the effects of these either, so @@ -1798,55 +1610,7 @@ Non-standard C++11 Attributes 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 @@ -1870,6 +1634,19 @@ Target-Specific Extensions Clang supports some language features conditionally on some targets. +ARM/AArch64 Language Extensions +------------------------------- + +Memory Barrier Intrinsics +^^^^^^^^^^^^^^^^^^^^^^^^^ +Clang implements the ``__dmb``, ``__dsb`` and ``__isb`` intrinsics as defined +in the `ARM C Language Extensions Release 2.0 +<http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf>`_. +Note that these intrinsics are implemented as motion barriers that block +reordering of memory accesses and side effect instructions. Other instructions +like simple arithmatic may be reordered around the intrinsic. If you expect to +have no reordering at all, use inline assembly instead. + X86/X86-64 Language Extensions ------------------------------ @@ -1902,48 +1679,6 @@ Which compiles to (on X86-32): 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 +1692,156 @@ in the analyzer's `list of source-level annotations 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 -================================= +Extensions for selectively disabling optimization +================================================= -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>`_. +Clang provides a mechanism for selectively disabling optimizations in functions +and methods. -``no_thread_safety_analysis`` ------------------------------ +To disable optimizations in a single function definition, the GNU-style or C++11 +non-standard attribute ``optnone`` can be used. -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 -==================== +.. code-block:: c++ -Clang supports additional attributes to enable checking type safety properties -that can't be enforced by the C type system. Use cases include: + // The following functions will not be optimized. + // GNU-style attribute + __attribute__((optnone)) int foo() { + // ... code + } + // C++11 attribute + [[clang::optnone]] int bar() { + // ... code + } -* 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()``. +To facilitate disabling optimization for a range of function definitions, a +range-based pragma is provided. Its syntax is ``#pragma clang optimize`` +followed by ``off`` or ``on``. -You can detect support for these attributes with ``__has_attribute()``. For -example: +All function definitions in the region between an ``off`` and the following +``on`` will be decorated with the ``optnone`` attribute unless doing so would +conflict with explicit attributes already present on the function (e.g. the +ones that control inlining). .. 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); + #pragma clang optimize off + // This function will be decorated with optnone. + int foo() { + // ... code + } -``argument_with_type_tag(...)`` -------------------------------- + // optnone conflicts with always_inline, so bar() will not be decorated. + __attribute__((always_inline)) int bar() { + // ... code + } + #pragma clang optimize on -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. +If no ``on`` is found to close an ``off`` region, the end of the region is the +end of the compilation unit. -This attribute is primarily useful for checking arguments of variadic functions -(``pointer_with_type_tag`` can be used in most non-variadic cases). +Note that a stray ``#pragma clang optimize on`` does not selectively enable +additional optimizations when compiling at low optimization levels. This feature +can only be used to selectively disable optimizations. -For example: +The pragma has an effect on functions only at the point of their definition; for +function templates, this means that the state of the pragma at the point of an +instantiation is not necessarily relevant. Consider the following example: .. code-block:: c++ - int fcntl(int fd, int cmd, ...) - __attribute__(( argument_with_type_tag(fcntl,3,2) )); - -``pointer_with_type_tag(...)`` ------------------------------- + template<typename T> T twice(T t) { + return 2 * t; + } -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. + #pragma clang optimize off + template<typename T> T thrice(T t) { + return 3 * t; + } -For example: + int container(int a, int b) { + return twice(a) + thrice(b); + } + #pragma clang optimize on + +In this example, the definition of the template function ``twice`` is outside +the pragma region, whereas the definition of ``thrice`` is inside the region. +The ``container`` function is also in the region and will not be optimized, but +it causes the instantiation of ``twice`` and ``thrice`` with an ``int`` type; of +these two instantiations, ``twice`` will be optimized (because its definition +was outside the region) and ``thrice`` will not be optimized. + +.. _langext-pragma-loop: + +Extensions for loop hint optimizations +====================================== + +The ``#pragma clang loop`` directive is used to specify hints for optimizing the +subsequent for, while, do-while, or c++11 range-based for loop. The directive +provides options for vectorization and interleaving. Loop hints can be specified +before any loop and will be ignored if the optimization is not safe to apply. + +A vectorized loop performs multiple iterations of the original loop +in parallel using vector instructions. The instruction set of the target +processor determines which vector instructions are available and their vector +widths. This restricts the types of loops that can be vectorized. The vectorizer +automatically determines if the loop is safe and profitable to vectorize. A +vector instruction cost model is used to select the vector width. + +Interleaving multiple loop iterations allows modern processors to further +improve instruction-level parallelism (ILP) using advanced hardware features, +such as multiple execution units and out-of-order execution. The vectorizer uses +a cost model that depends on the register pressure and generated code size to +select the interleaving count. + +Vectorization is enabled by ``vectorize(enable)`` and interleaving is enabled +by ``interleave(enable)``. This is useful when compiling with ``-Os`` to +manually enable vectorization or interleaving. .. 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); + #pragma clang loop vectorize(enable) + #pragma clang loop interleave(enable) + for(...) { + ... + } - vprintf(s, ap); // warning: format string is not a string literal - } +The vector width is specified by ``vectorize_width(_value_)`` and the interleave +count is specified by ``interleave_count(_value_)``, where +_value_ is a positive integer. This is useful for specifying the optimal +width/count of the set of target architectures supported by your application. - 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. +.. code-block:: c++ - If the attribute is removed, clang still warns, because the format string is - not a string literal. + #pragma clang loop vectorize_width(2) + #pragma clang loop interleave_count(2) + for(...) { + ... + } - Another example: +Specifying a width/count of 1 disables the optimization, and is equivalent to +``vectorize(disable)`` or ``interleave(disable)``. - .. code-block:: c +For convenience multiple loop hints can be specified on a single line. - __attribute__((__format__ (__printf__, 1, 3))) - void foo(const char* s, char *buf, ...) { - va_list ap; - va_start(ap, buf); +.. code-block:: c++ - vprintf(s, ap); // warning - } + #pragma clang loop vectorize_width(4) interleave_count(8) + for(...) { + ... + } - 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. +If an optimization cannot be applied any hints that apply to it will be ignored. +For example, the hint ``vectorize_width(4)`` is ignored if the loop is not +proven safe to vectorize. To identify and diagnose optimization issues use +`-Rpass`, `-Rpass-missed`, and `-Rpass-analysis` command line options. See the +user guide for details. diff --git a/docs/LibASTMatchersReference.html b/docs/LibASTMatchersReference.html index 2c9b3aae0a89..49880539bc98 100644 --- a/docs/LibASTMatchersReference.html +++ b/docs/LibASTMatchersReference.html @@ -250,7 +250,7 @@ Example matches f <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> @@ -631,6 +631,15 @@ Example matches x() </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('exprWithCleanups0')"><a name="exprWithCleanups0Anchor">exprWithCleanups</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ExprWithCleanups.html">ExprWithCleanups</a>>...</td></tr> +<tr><td colspan="4" class="doc" id="exprWithCleanups0"><pre>Matches expressions that introduce cleanups to be run at the end +of the sub-expression's evaluation. + +Example matches std::string() + const std::string str = std::string(); +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('floatLiteral0')"><a name="floatLiteral0Anchor">floatLiteral</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FloatingLiteral.html">FloatingLiteral</a>>...</td></tr> <tr><td colspan="4" class="doc" id="floatLiteral0"><pre>Matches float literals of all sizes encodings, e.g. 1.0, 1.0f, 1.0L and 1e10. @@ -1311,7 +1320,7 @@ Usable as: Any Matcher </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,9 +1361,8 @@ Example matches f(0, 0) (matcher = callExpr(argumentCountIs(2))) </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). +<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> @@ -1422,6 +1430,18 @@ Given </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. @@ -1581,13 +1601,19 @@ and reference to that variable declaration within a compound statement. </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('equalsNode0')"><a name="equalsNode0Anchor">equalsNode</a></td><td>Decl* Other</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('equalsNode0')"><a name="equalsNode0Anchor">equalsNode</a></td><td>Decl *Node</td></tr> <tr><td colspan="4" class="doc" id="equalsNode0"><pre>Matches if a node equals another node. Decl has pointer identity in the AST. </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</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 declaration that has been implicitly added +by the compiler (eg. implicit defaultcopy constructors). +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>></td><td class="name" onclick="toggle('isPrivate0')"><a name="isPrivate0Anchor">isPrivate</a></td><td></td></tr> <tr><td colspan="4" class="doc" id="isPrivate0"><pre>Matches private C++ declarations. @@ -1874,7 +1900,7 @@ and reference to that variable declaration within a compound statement. </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('equalsNode1')"><a name="equalsNode1Anchor">equalsNode</a></td><td>Stmt* Other</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('equalsNode1')"><a name="equalsNode1Anchor">equalsNode</a></td><td>Stmt *Node</td></tr> <tr><td colspan="4" class="doc" id="equalsNode1"><pre>Matches if a node equals another node. Stmt has pointer identity in the AST. @@ -1940,6 +1966,31 @@ Example matches a || b (matcher = binaryOperator(hasOperatorName("||"))) </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('hasGlobalStorage0')"><a name="hasGlobalStorage0Anchor">hasGlobalStorage</a></td><td></td></tr> +<tr><td colspan="4" class="doc" id="hasGlobalStorage0"><pre>Matches a variable declaration that does not have local storage. + +Example matches y and z (matcher = varDecl(hasGlobalStorage()) +void f() { + int x; + static int y; +} +int 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('hasLocalStorage0')"><a name="hasLocalStorage0Anchor">hasLocalStorage</a></td><td></td></tr> +<tr><td colspan="4" class="doc" id="hasLocalStorage0"><pre>Matches a variable declaration that has function scope and is a +non-static local variable. + +Example matches x (matcher = varDecl(hasLocalStorage()) +void f() { + int x; + static int y; +} +int 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('isDefinition1')"><a name="isDefinition1Anchor">isDefinition</a></td><td></td></tr> <tr><td colspan="4" class="doc" id="isDefinition1"><pre>Matches if a declaration has a body attached. @@ -2026,24 +2077,6 @@ Usable as: Any Matcher </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 +2101,20 @@ Usable as: Any Matcher </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 +2148,21 @@ Usable as: Any Matcher </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 +2364,6 @@ The associated declaration is: 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 +2427,43 @@ with withInitializer matching (1) </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('hasBody3')"><a name="hasBody3Anchor">hasBody</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="hasBody3"><pre>Matches a 'for', 'while', or 'do while' statement that has +a given body. + +Given + for (;;) {} +hasBody(compoundStmt()) + matches 'for (;;) {}' +with compoundStmt() + matching '{}' +</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_1CXXForRangeStmt.html">CXXForRangeStmt</a>></td><td class="name" onclick="toggle('hasRangeInit0')"><a name="hasRangeInit0Anchor">hasRangeInit</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="hasRangeInit0"><pre>Matches the range initialization statement of a for loop. + +Example: + forStmt(hasRangeInit(anything())) +matches 'a' 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 +2475,17 @@ FIXME: Overload to allow directly matching types? </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 +2554,24 @@ Example matches y.x() (matcher = callExpr(callee(methodDecl(hasName("x"))))) </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 +2612,6 @@ The associated declaration is: 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 +2751,6 @@ The associated declaration is: 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 +2915,6 @@ The associated declaration is: 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 +2952,17 @@ Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.h </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. @@ -3014,6 +3125,24 @@ hasConditionVariableStatement(...) </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IfStmt.html">IfStmt</a>></td><td class="name" onclick="toggle('hasElse0')"><a name="hasElse0Anchor">hasElse</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="hasElse0"><pre>Matches the else-statement of an if statement. + +Examples matches the if statement + (matcher = ifStmt(hasElse(boolLiteral(equals(true))))) + if (false) false; else true; +</pre></td></tr> + + +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IfStmt.html">IfStmt</a>></td><td class="name" onclick="toggle('hasThen0')"><a name="hasThen0Anchor">hasThen</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="hasThen0"><pre>Matches the then-statement of an if statement. + +Examples matches the if statement + (matcher = ifStmt(hasThen(boolLiteral(equals(true))))) + if (false) true; else false; +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ImplicitCastExpr.html">ImplicitCastExpr</a>></td><td class="name" onclick="toggle('hasImplicitDestinationType0')"><a name="hasImplicitDestinationType0Anchor">hasImplicitDestinationType</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="hasImplicitDestinationType0"><pre>Matches implicit casts whose destination type matches a given matcher. @@ -3034,8 +3163,6 @@ The associated declaration is: 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 +3185,6 @@ The associated declaration is: 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 +3207,6 @@ The associated declaration is: 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 +3288,6 @@ nestedNameSpecifierLoc(hasPrefix(loc(specifiesType(asString("struct A"))))) </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 +3407,6 @@ The associated declaration is: 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 +3422,36 @@ Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallEx </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 +3464,6 @@ The associated declaration is: 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 +3543,6 @@ The associated declaration is: 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 +3553,23 @@ Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallEx </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 +3595,20 @@ classTemplateSpecializationDecl(hasAnyTemplateArgument( </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 +3621,6 @@ The associated declaration is: 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 +3631,20 @@ Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallEx </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 +3657,6 @@ The associated declaration is: 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 +3682,6 @@ Usable as: Any Matcher </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 +3694,6 @@ The associated declaration is: 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 +3734,6 @@ The associated declaration is: 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 +3785,17 @@ Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.h </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 +3841,18 @@ Example matches true (matcher = hasCondition(boolLiteral(equals(true)))) 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 5bd62a133649..1e88ec203c9f 100644 --- a/docs/LibASTMatchersTutorial.rst +++ b/docs/LibASTMatchersTutorial.rst @@ -137,6 +137,10 @@ documentation <LibTooling.html>`_. 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,10 +150,10 @@ documentation <LibTooling.html>`_. 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>()); + return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>().get()); } And that's it! You can compile our new tool by running ninja from the @@ -287,7 +291,7 @@ And change ``main()`` to: .. 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()); @@ -295,7 +299,7 @@ And change ``main()`` to: MatchFinder Finder; Finder.addMatcher(LoopMatcher, &Printer); - return Tool.run(newFrontendActionFactory(&Finder)); + return Tool.run(newFrontendActionFactory(&Finder).get()); } Now, you should be able to recompile and run the code to discover for diff --git a/docs/LibTooling.rst b/docs/LibTooling.rst index 505865606433..75ef6a0fe7ea 100644 --- a/docs/LibTooling.rst +++ b/docs/LibTooling.rst @@ -60,13 +60,18 @@ and automatic location of the compilation database using source files paths. .. 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. @@ -94,13 +99,13 @@ our ``FrontendAction`` over some code. For example, to run the // on. Thus, it takes a FrontendActionFactory as parameter. To create a // FrontendActionFactory from a given FrontendAction type, we call // newFrontendActionFactory<clang::SyntaxOnlyAction>(). - int result = Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>()); + int result = Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>().get()); 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 @@ tool is also checked into the clang tree at 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,10 +133,10 @@ tool is also checked into the clang tree at 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>()); + OptionsParser.getSourcePathList()); + return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>().get()); } Running the tool on some code @@ -176,7 +185,7 @@ Builtin includes 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 000000000000..32efb76db251 --- /dev/null +++ b/docs/MSVCCompatibility.rst @@ -0,0 +1,141 @@ +.. 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 particularly 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:`Complete`. We've tested this with a fuzzer and have + fixed all known bugs. + +* 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. This feature + has also been fuzz tested. + +* 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: :good:`Complete`. Generation of RTTI data structures has been + finished, along with support for the ``/GR`` flag. + +* Exceptions and SEH: :none:`Unstarted`. Clang can parse both constructs, but + does not know how to emit compatible handlers. + +* Thread-safe initialization of local statics: :none:`Unstarted`. We are ABI + compatible with MSVC 2013, which does not support thread-safe local statics. + MSVC "14" changed the ABI to make initialization of local statics thread safe, + and we have not yet implemented this. + +* Lambdas: :good:`Mostly complete`. Clang is compatible with Microsoft's + implementation of lambdas except for providing overloads for conversion to + function pointer for different calling conventions. However, Microsoft's + extension is non-conforming. + +Template instantiation and name lookup +====================================== + +MSVC allows many invalid constructs in class templates that Clang has +historically rejected. In order to parse widely distributed headers for +libraries such as the Active Template Library (ATL) and Windows Runtime Library +(WRL), some template rules have been relaxed or extended in Clang on Windows. + +The first major semantic difference is that MSVC appears to defer all parsing +an analysis of inline method bodies in class templates until instantiation +time. By default on Windows, Clang attempts to follow suit. This behavior is +controlled by the ``-fdelayed-template-parsing`` flag. While Clang delays +parsing of method bodies, it still parses the bodies *before* template argument +substitution, which is not what MSVC does. The following compatibility tweaks +are necessary to parse the the template in those cases. + +MSVC allows some name lookup into dependent base classes. Even on other +platforms, this has been a `frequently asked question`_ for Clang users. A +dependent base class is a base class that depends on the value of a template +parameter. Clang cannot see any of the names inside dependent bases while it +is parsing your template, so the user is sometimes required to use the +``typename`` keyword to assist the parser. On Windows, Clang attempts to +follow the normal lookup rules, but if lookup fails, it will assume that the +user intended to find the name in a dependent base. While parsing the +following program, Clang will recover as if the user had written the +commented-out code: + +.. _frequently asked question: + http://clang.llvm.org/compatibility.html#dep_lookup + +.. code-block:: c++ + + template <typename T> + struct Foo : T { + void f() { + /*typename*/ T::UnknownType x = /*this->*/unknownMember; + } + }; + +After recovery, Clang warns the user that this code is non-standard and issues +a hint suggesting how to fix the problem. + +As of this writing, Clang is able to compile a simple ATL hello world +application. There are still issues parsing WRL headers for modern Windows 8 +apps, but they should be addressed soon. diff --git a/docs/MemorySanitizer.rst b/docs/MemorySanitizer.rst index 5fc7e745d19f..9d6c22d8af08 100644 --- a/docs/MemorySanitizer.rst +++ b/docs/MemorySanitizer.rst @@ -56,12 +56,10 @@ future). .. 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 @@ checks for certain source files and functions. All "Use of uninitialized value" 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 @@ the example above, .. 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 - -Origin tracking has proved to be very useful for debugging UMR + % ./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 + + 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 @@ Supported Platforms 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 9fb4c774874c..ce1e717bc2a0 100644 --- a/docs/Modules.rst +++ b/docs/Modules.rst @@ -144,7 +144,7 @@ Module maps ----------- 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,63 @@ Command-line parameters ``-fmodule-map-file=<file>`` Load the given module map file if a header from its directory or one of its subdirectories is loaded. +``-fmodules-search-all`` + If a symbol is not found, search modules referenced in the current module maps but not imported for symbols, so the error message can reference the module by name. Note that if the global module index has not been built before, this might take some time as it needs to build all the modules. Note that this option doesn't apply in module builds, to avoid the recursion. + +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 +328,15 @@ The ``framework`` qualifier specifies that this module corresponds to a Darwin-s .. 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 +618,7 @@ A *use-declaration* specifies one of the other modules that the module is allowe 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 +736,63 @@ Attributes are used in a number of places in the grammar to describe specific be 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: + +.. code-block:: c + + /* 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). @@ -740,7 +842,7 @@ Where To Learn More About Modules ================================= The Clang source code provides additional information about modules: -``clang/lib/Headers/module.map`` +``clang/lib/Headers/module.modulemap`` Module map for Clang's compiler-specific header files. ``clang/test/Modules/`` diff --git a/docs/ObjectiveCLiterals.rst b/docs/ObjectiveCLiterals.rst index 8066d8f6bead..8907c1efc77d 100644 --- a/docs/ObjectiveCLiterals.rst +++ b/docs/ObjectiveCLiterals.rst @@ -91,7 +91,7 @@ Previously, the ``BOOL`` type was simply a typedef for ``signed char``, 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 @@ This creates an ``NSDictionary`` with 3 key/value pairs. Value 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/PTHInternals.rst b/docs/PTHInternals.rst index 10dda6117b75..7401cf9b4d4b 100644 --- a/docs/PTHInternals.rst +++ b/docs/PTHInternals.rst @@ -135,11 +135,11 @@ copy-on-write pages, the approach itself can fundamentally dominate at an algorithmic level, especially when one considers header files of arbitrary size. -There are plans to potentially implement an complementary PCH -implementation for Clang based on the lazy deserialization of ASTs. This -approach would theoretically have the same constant-time algorithmic -advantages just mentioned but would also retain some of the strengths of -PTH such as reduced memory pressure (ideal for multi-core builds). +There is also a PCH implementation for Clang based on the lazy +deserialization of ASTs. This approach theoretically has the same +constant-time algorithmic advantages just mentioned but also retains some +of the strengths of PTH such as reduced memory pressure (ideal for +multi-core builds). Internal PTH Optimizations -------------------------- diff --git a/docs/ReleaseNotes.rst b/docs/ReleaseNotes.rst index b24bca9ce0c4..dc1c88b6fb3c 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,281 @@ documentation <http://llvm.org/docs/ReleaseNotes.html>`_. All LLVM 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. + +- Clang 3.5 now has parsing and semantic-analysis support for all OpenMP 3.1 + pragmas (except atomics and ordered). LLVM's OpenMP runtime library, + originally developed by Intel, has been modified to work on ARM, PowerPC, + as well as X86. Code generation support is minimal at this point and will + continue to be developed for 3.6, along with the rest of OpenMP 3.1. + Support for OpenMP 4.0 features, such as SIMD and target accelerator + directives, is also in progress. Contributors to this work include AMD, + Argonne National Lab., IBM, Intel, Texas Instruments, University of Houston + and many others. + 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: - -- -Wheader-guard warns on mismatches between the #ifndef and #define lines - in a header guard. +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: - .. code-block:: c +- GCC compatibility: Clang displays a warning on unsupported gcc + optimization flags instead of an error. - #ifndef multiple - #define multi - #endif +- Remarks system: Clang supports `-R` flags for enabling remarks. These are + diagnostic messages that provide information about the compilation process, + but don't suggest that a problem has been detected. As such, they cannot + be upgraded to errors with `-Werror` or `-Rerror`. A `-Reverything` flag + is provided (paralleling `-Weverything`) to turn on all remarks. - returns - `warning: 'multiple' is used as a header guard here, followed by #define of a different macro [-Wheader-guard]` +- New remark `-Rpass`: Clang provides information about decisions made by + optimization passes during compilation. See :ref:`opt_rpass`. -- -Wlogical-not-parentheses warns when a logical not ('!') only applies to the - left-hand side of a comparison. This warning is part of -Wparentheses. +- New warning `-Wabsolute-value`: Clang warns about incorrect or useless usage + of the absolute functions (`abs`, `fabsf`, etc). - .. code-block:: c++ + .. code-block:: c - int i1 = 0, i2 = 1; - bool ret; - ret = !i1 == i2; + #include <stdlib.h> + void foo() { + unsigned int i=0; + abs(i); + } returns - `warning: logical not is only applied to the left hand side of this comparison [-Wlogical-not-parentheses]` - + `warning: taking the absolute value of unsigned type 'unsigned int' has no effect [-Wabsolute-value]` -- 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++. + or - .. code-block:: c++ + .. code-block:: c - enum A { A1, A2 }; - void test() { - A a; - a++; + #include <stdlib.h> + void plop() { + long long i=0; + abs(i); } returns - `error: cannot increment expression of enum type 'A'` + `warning: absolute value function 'abs' given an argument of type 'long long' but has parameter of type 'int' which may cause truncation of value [-Wabsolute-value] use function 'llabs' instead` +- New warning `-Wtautological-pointer-compare`: -- -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 + .. code-block:: c++ - void foo(char *a, char *b, unsigned c) { - for (unsigned i = 0; i < c; ++i) { - a[i] = b[i]; - ++i; - } + #include <stddef.h> + void foo() { + int arr[5]; + int x; + // warn on these conditionals + if (foo); + if (arr); + if (&x); + if (foo == NULL); + if (arr == NULL); + if (&x == NULL); } returns - `warning: variable 'i' is incremented both in the loop header and in the loop body [-Wloop-analysis]` + `warning: comparison of address of 'x' equal to a null pointer is always false [-Wtautological-pointer-compare]` -- -Wuninitialized now performs checking across field initializers to detect - when one field in used uninitialized in another field initialization. +- New warning `-Wtautological-undefined-compare`: .. code-block:: c++ - class A { - int x; - int y; - A() : x(y) {} - }; + #include <stddef.h> + void f(int &x) { + if (&x == nullptr) { } + } 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. + `warning: reference cannot be bound to dereferenced null pointer in well-defined C++ code; comparison may be assumed to always evaluate to false [-Wtautological-undefined-compare]` + +- ... 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. + +It is now possible to get optimization reports from the major transformation +passes via three new flags: `-Rpass`, `-Rpass-missed` and `-Rpass-analysis`. +These flags take a POSIX regular expression which indicates the name +of the pass (or passes) that should emit optimization remarks. + +Options `-u` and `-z` are forwarded to the linker on gnutools toolchains. + + +New Pragmas in Clang +----------------------- + +Loop optimization hints can be specified using the new `#pragma clang loop` +directive just prior to the desired loop. The directive allows vectorization and +interleaving to be enabled or disabled. Vector width as well as interleave count +can be manually specified. See :ref:`langext-pragma-loop` for details. 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|_. +- Reference parameters and return values from functions are more aggressively + assumed to refer to valid objects when optimizing. Clang will attempt to + issue a warning by default if it sees null checks being performed on + references, and `-fsanitize=null` can be used to detect null references + being formed at runtime. -.. |has_feature macro| replace:: ``__has_feature`` macro -.. _has_feature macro: LanguageExtensions.html#has-feature-and-has-extension +- ... -C++1y Feature Support +C++17 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: +Clang has experimental support for some proposed C++1z (tentatively, C++17) +features. This support can be enabled using the `-std=c++1z` flag. The +supported features are: -- 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. +- `static_assert(expr)` with no message -In addition, ``[[deprecated]]`` is now accepted as a synonym for Clang's -existing ``deprecated`` attribute. +- `for (identifier : range)` as a synonym for `for (auto &&identifier : range)` -Use ``-std=c++1y`` to enable C++1y mode. +- `template<template<...> typename>` as a synonym for `template<template<...> class>` + +Additionally, trigraphs are not recognized by default in this mode. +`-ftrigraphs` can be used if you need to parse legacy code that uses trigraphs. +Note that these features may be changed or removed in future Clang releases +without notice. + +Objective-C Language Changes in Clang +------------------------------------- + +... 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. +... + +OpenMP C/C++ Language Changes in Clang +-------------------------------------- + +- `Status of supported OpenMP constructs + <https://github.com/clang-omp/clang/wiki/Status-of-supported-OpenMP-constructs>`_. + 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 -^^^^^^^^^^^^^^^^^^^^ +- Clang uses `std::unique_ptr<T>` in many places where it used to use + raw `T *` pointers. + +libclang +-------- -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. +... 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. +Check for code testing a variable for 0 after using it as a denominator. +This new checker, alpha.core.TestAfterDivZero, catches issues like this: -Clang Format ------------- +.. code-block:: c -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>`_. + int sum = ... + int avg = sum / count; // potential division by zero... + if (count == 0) { ... } // ...caught here -Windows Support ---------------- -- `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. +The `-analyzer-config` options are now passed from scan-build through to +ccc-analyzer and then to Clang. + +With the option `-analyzer-config stable-report-filename=true`, +instead of `report-XXXXXX.html`, scan-build/clang analyzer generate +`report-<filename>-<function, method name>-<function position>-<id>.html`. +(id = i++ for several issues found in the same function/method). + +List the function/method name in the index page of scan-build. + +... + +Core Analysis Improvements +========================== + +- ... + +New Issues Found +================ + +- ... Python Binding Changes ---------------------- The following methods have been added: +- ... + Significant Known Problems ========================== @@ -272,7 +309,7 @@ Additional Information 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/SanitizerSpecialCaseList.rst b/docs/SanitizerSpecialCaseList.rst index 8f4727c2fbc3..a4165b2521cf 100644 --- a/docs/SanitizerSpecialCaseList.rst +++ b/docs/SanitizerSpecialCaseList.rst @@ -24,7 +24,7 @@ certain source-level entities to: thread stack, bypassing the frame boundaries); * ignore a known problem. -To achieve this, user may create a file listing the entities he wants to +To achieve this, user may create a file listing the entities they want to ignore, and pass it to clang at compile-time using ``-fsanitize-blacklist`` flag. See :doc:`UsersManual` for details. diff --git a/docs/ThreadSafetyAnalysis.rst b/docs/ThreadSafetyAnalysis.rst new file mode 100644 index 000000000000..dfef80b69fa2 --- /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 194ad4a8efb0..a1d81e9a9c29 100644 --- a/docs/ThreadSanitizer.rst +++ b/docs/ThreadSanitizer.rst @@ -18,9 +18,9 @@ supported. 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 96d65a47d1b8..90f16ee0d431 100644 --- a/docs/UsersManual.rst +++ b/docs/UsersManual.rst @@ -112,11 +112,11 @@ Options to Control Error and Warning Messages .. 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 @@ output format of the diagnostics that it generates. 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** @@ -536,6 +531,67 @@ control the crash diagnostics. The -fno-crash-diagnostics flag can be helpful for speeding the process of generating a delta reduced test case. +.. _opt_rpass: + +Options to Emit Optimization Reports +------------------------------------ + +Optimization reports trace, at a high-level, all the major decisions +done by compiler transformations. For instance, when the inliner +decides to inline function ``foo()`` into ``bar()``, or the loop unroller +decides to unroll a loop N times, or the vectorizer decides to +vectorize a loop body. + +Clang offers a family of flags which the optimizers can use to emit +a diagnostic in three cases: + +1. When the pass makes a transformation (:option:`-Rpass`). + +2. When the pass fails to make a transformation (:option:`-Rpass-missed`). + +3. When the pass determines whether or not to make a transformation + (:option:`-Rpass-analysis`). + +NOTE: Although the discussion below focuses on :option:`-Rpass`, the exact +same options apply to :option:`-Rpass-missed` and :option:`-Rpass-analysis`. + +Since there are dozens of passes inside the compiler, each of these flags +take a regular expression that identifies the name of the pass which should +emit the associated diagnostic. For example, to get a report from the inliner, +compile the code with: + +.. code-block:: console + + $ clang -O2 -Rpass=inline code.cc -o code + code.cc:4:25: remark: foo inlined into bar [-Rpass=inline] + int bar(int j) { return foo(j, j - 2); } + ^ + +Note that remarks from the inliner are identified with `[-Rpass=inline]`. +To request a report from every optimization pass, you should use +:option:`-Rpass=.*` (in fact, you can use any valid POSIX regular +expression). However, do not expect a report from every transformation +made by the compiler. Optimization remarks do not really make sense +outside of the major transformations (e.g., inlining, vectorization, +loop optimizations) and not every optimization pass supports this +feature. + +Current limitations +^^^^^^^^^^^^^^^^^^^ + +1. Optimization remarks that refer to function names will display the + mangled name of the function. Since these remarks are emitted by the + back end of the compiler, it does not know anything about the input + language, nor its mangling rules. + +2. Some source locations are not displayed correctly. The front end has + a more detailed source location tracking than the locations included + in the debug info (e.g., the front end can locate code inside macro + expansions). However, the locations used by :option:`-Rpass` are + translated from debug annotations. That translation can be lossy, + which results in some remarks having no location information. + + Language and Target-Independent Features ======================================== @@ -587,6 +643,7 @@ All diagnostics are mapped into one of these 5 classes: - Ignored - Note +- Remark - Warning - Error - Fatal @@ -704,17 +761,18 @@ the pragma onwards within the same file. 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 +785,12 @@ is treated as a system header. .. _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 +824,7 @@ on-disk cache that contains the vital information necessary to reduce some of the work needed to process a corresponding header file. While details of precompiled headers vary between compilers, precompiled headers have been shown to be highly effective at speeding up program -compilation on systems with very large system headers (e.g., Mac OS/X). +compilation on systems with very large system headers (e.g., Mac OS X). Generating a PCH File ^^^^^^^^^^^^^^^^^^^^^ @@ -874,10 +933,6 @@ are listed below. ``-fsanitize=address``: :doc:`AddressSanitizer`, a memory error detector. - - ``-fsanitize=init-order``: Make AddressSanitizer check for - dynamic initialization order problems. Implied by ``-fsanitize=address``. - - ``-fsanitize=address-full``: AddressSanitizer with all the - experimental features listed below. - ``-fsanitize=integer``: Enables checks for undefined or suspicious integer behavior. - .. _opt_fsanitize_thread: @@ -960,23 +1015,20 @@ are listed below. - ``-fno-sanitize-blacklist``: don't use blacklist file, if it was specified earlier in the command line. - Experimental features of AddressSanitizer (not ready for widespread - use, require explicit ``-fsanitize=address``): - - - ``-fsanitize=use-after-return``: Check for use-after-return - errors (accessing local variable after the function exit). - - ``-fsanitize=use-after-scope``: Check for use-after-scope errors - (accesing local variable after it went out of scope). - Extra features of MemorySanitizer (require explicit ``-fsanitize=memory``): - - ``-fsanitize-memory-track-origins``: 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 +1054,6 @@ are listed below. 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 +1106,240 @@ are listed below. 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. + + +Profile Guided Optimization +--------------------------- + +Profile information enables better optimization. For example, knowing that a +branch is taken very frequently helps the compiler make better decisions when +ordering basic blocks. Knowing that a function ``foo`` is called more +frequently than another function ``bar`` helps the inliner. + +Clang supports profile guided optimization with two different kinds of +profiling. A sampling profiler can generate a profile with very low runtime +overhead, or you can build an instrumented version of the code that collects +more detailed profile information. Both kinds of profiles can provide execution +counts for instructions in the code and information on branches taken and +function invocation. + +Regardless of which kind of profiling you use, be careful to collect profiles +by running your code with inputs that are representative of the typical +behavior. Code that is not exercised in the profile will be optimized as if it +is unimportant, and the compiler may make poor optimization choices for code +that is disproportionately used while profiling. + +Using Sampling Profilers +^^^^^^^^^^^^^^^^^^^^^^^^ + +Sampling profilers are used to collect runtime information, such as +hardware counters, while your application executes. They are typically +very efficient and do not incur a large runtime overhead. The +sample data collected by the profiler can be used during compilation +to determine what the most executed areas of the code are. + +Using the data from a sample profiler requires some changes in the way +a program is built. Before the compiler can use profiling information, +the code needs to execute under the profiler. The following is the +usual build cycle when using sample profilers for optimization: + +1. Build the code with source line table information. You can use all the + usual build flags that you always build your application with. The only + requirement is that you add ``-gline-tables-only`` or ``-g`` to the + command line. This is important for the profiler to be able to map + instructions back to source line locations. + + .. code-block:: console + + $ clang++ -O2 -gline-tables-only code.cc -o code + +2. Run the executable under a sampling profiler. The specific profiler + you use does not really matter, as long as its output can be converted + into the format that the LLVM optimizer understands. Currently, there + exists a conversion tool for the Linux Perf profiler + (https://perf.wiki.kernel.org/), so these examples assume that you + are using Linux Perf to profile your code. + + .. code-block:: console + + $ perf record -b ./code + + Note the use of the ``-b`` flag. This tells Perf to use the Last Branch + Record (LBR) to record call chains. While this is not strictly required, + it provides better call information, which improves the accuracy of + the profile data. + +3. Convert the collected profile data to LLVM's sample profile format. + This is currently supported via the AutoFDO converter ``create_llvm_prof``. + It is available at http://github.com/google/autofdo. Once built and + installed, you can convert the ``perf.data`` file to LLVM using + the command: + + .. code-block:: console + + $ create_llvm_prof --binary=./code --out=code.prof + + This will read ``perf.data`` and the binary file ``./code`` and emit + the profile data in ``code.prof``. Note that if you ran ``perf`` + without the ``-b`` flag, you need to use ``--use_lbr=false`` when + calling ``create_llvm_prof``. + +4. Build the code again using the collected profile. This step feeds + the profile back to the optimizers. This should result in a binary + that executes faster than the original one. Note that you are not + required to build the code with the exact same arguments that you + used in the first step. The only requirement is that you build the code + with ``-gline-tables-only`` and ``-fprofile-sample-use``. + + .. code-block:: console + + $ clang++ -O2 -gline-tables-only -fprofile-sample-use=code.prof code.cc -o code + + +Sample Profile Format +""""""""""""""""""""" + +If you are not using Linux Perf to collect profiles, you will need to +write a conversion tool from your profiler to LLVM's format. This section +explains the file format expected by the backend. + +Sample profiles are written as ASCII text. The file is divided into sections, +which correspond to each of the functions executed at runtime. Each +section has the following format (taken from +https://github.com/google/autofdo/blob/master/profile_writer.h): + +.. code-block:: console + + function1:total_samples:total_head_samples + offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ] + offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ] + ... + offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ] + +The file may contain blank lines between sections and within a +section. However, the spacing within a single line is fixed. Additional +spaces will result in an error while reading the file. + +Function names must be mangled in order for the profile loader to +match them in the current translation unit. The two numbers in the +function header specify how many total samples were accumulated in the +function (first number), and the total number of samples accumulated +in the prologue of the function (second number). This head sample +count provides an indicator of how frequently the function is invoked. + +Each sampled line may contain several items. Some are optional (marked +below): + +a. Source line offset. This number represents the line number + in the function where the sample was collected. The line number is + always relative to the line where symbol of the function is + defined. So, if the function has its header at line 280, the offset + 13 is at line 293 in the file. + + Note that this offset should never be a negative number. This could + happen in cases like macros. The debug machinery will register the + line number at the point of macro expansion. So, if the macro was + expanded in a line before the start of the function, the profile + converter should emit a 0 as the offset (this means that the optimizers + will not be able to associate a meaningful weight to the instructions + in the macro). + +b. [OPTIONAL] Discriminator. This is used if the sampled program + was compiled with DWARF discriminator support + (http://wiki.dwarfstd.org/index.php?title=Path_Discriminators). + DWARF discriminators are unsigned integer values that allow the + compiler to distinguish between multiple execution paths on the + same source line location. + + For example, consider the line of code ``if (cond) foo(); else bar();``. + If the predicate ``cond`` is true 80% of the time, then the edge + into function ``foo`` should be considered to be taken most of the + time. But both calls to ``foo`` and ``bar`` are at the same source + line, so a sample count at that line is not sufficient. The + compiler needs to know which part of that line is taken more + frequently. + + This is what discriminators provide. In this case, the calls to + ``foo`` and ``bar`` will be at the same line, but will have + different discriminator values. This allows the compiler to correctly + set edge weights into ``foo`` and ``bar``. + +c. Number of samples. This is an integer quantity representing the + number of samples collected by the profiler at this source + location. + +d. [OPTIONAL] Potential call targets and samples. If present, this + line contains a call instruction. This models both direct and + number of samples. For example, + + .. code-block:: console + + 130: 7 foo:3 bar:2 baz:7 + + The above means that at relative line offset 130 there is a call + instruction that calls one of ``foo()``, ``bar()`` and ``baz()``, + with ``baz()`` being the relatively more frequently called target. + + +Profiling with Instrumentation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Clang also supports profiling via instrumentation. This requires building a +special instrumented version of the code and has some runtime +overhead during the profiling, but it provides more detailed results than a +sampling profiler. It also provides reproducible results, at least to the +extent that the code behaves consistently across runs. + +Here are the steps for using profile guided optimization with +instrumentation: + +1. Build an instrumented version of the code by compiling and linking with the + ``-fprofile-instr-generate`` option. + + .. code-block:: console + + $ clang++ -O2 -fprofile-instr-generate code.cc -o code + +2. Run the instrumented executable with inputs that reflect the typical usage. + By default, the profile data will be written to a ``default.profraw`` file + in the current directory. You can override that default by setting the + ``LLVM_PROFILE_FILE`` environment variable to specify an alternate file. + Any instance of ``%p`` in that file name will be replaced by the process + ID, so that you can easily distinguish the profile output from multiple + runs. + + .. code-block:: console + + $ LLVM_PROFILE_FILE="code-%p.profraw" ./code + +3. Combine profiles from multiple runs and convert the "raw" profile format to + the input expected by clang. Use the ``merge`` command of the llvm-profdata + tool to do this. + + .. code-block:: console + + $ llvm-profdata merge -output=code.profdata code-*.profraw + + Note that this step is necessary even when there is only one "raw" profile, + since the merge operation also changes the file format. + +4. Build the code again using the ``-fprofile-instr-use`` option to specify the + collected profile data. + + .. code-block:: console + + $ clang++ -O2 -fprofile-instr-use=code.profdata code.cc -o code + + You can repeat step 4 as often as you like without regenerating the + profile. As you make changes to your code, clang may no longer be able to + use the profile data. It will warn you when this happens. + Controlling Size of Debug Information ------------------------------------- @@ -1086,23 +1360,70 @@ below. If multiple flags are present, the last one is used. doesn't contain any other data (e.g. description of local variables or function parameters). +.. option:: -fstandalone-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 **-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. + +.. option:: -fno-standalone-debug + + On Darwin **-fstandalone-debug** is enabled by default. The + **-fno-standalone-debug** option can be used to get to turn on the + vtable-based optimization described above. + .. option:: -g Generate complete debug info. Comment Parsing Options --------------------------- +----------------------- Clang parses Doxygen and non-Doxygen style documentation comments and attaches them to the appropriate declaration nodes. By default, it only parses Doxygen-style comments and ignores ordinary comments starting with ``//`` and ``/*``. +.. option:: -Wdocumentation + + Emit warnings about use of documentation comments. This warning group is off + by default. + + This includes checking that ``\param`` commands name parameters that actually + present in the function signature, checking that ``\returns`` is used only on + functions that actually return a value etc. + +.. option:: -Wno-documentation-unknown-command + + Don't warn when encountering an unknown Doxygen command. + .. option:: -fparse-all-comments Parse all comments as documentation comments (including ordinary comments starting with ``//`` and ``/*``). +.. option:: -fcomment-block-commands=[commands] + + Define custom documentation commands as block commands. This allows Clang to + construct the correct AST for these custom commands, and silences warnings + about unknown commands. Several commands must be separated by a comma + *without trailing space*; e.g. ``-fcomment-block-commands=foo,bar`` defines + custom commands ``\foo`` and ``\bar``. + + It is also possible to use ``-fcomment-block-commands`` several times; e.g. + ``-fcomment-block-commands=foo -fcomment-block-commands=bar`` does the same + as above. + .. _c: C Language Features @@ -1329,14 +1650,21 @@ X86 ^^^ The support for X86 (both 32-bit and 64-bit) is considered stable on -Darwin (Mac OS/X), Linux, FreeBSD, and Dragonfly BSD: it has been tested +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 +1705,10 @@ backend. Operating System Features and Limitations ----------------------------------------- -Darwin (Mac OS/X) +Darwin (Mac OS X) ^^^^^^^^^^^^^^^^^ -None +Thread Sanitizer is not supported. Windows ^^^^^^^ @@ -1480,55 +1808,92 @@ Execute ``clang-cl /?`` to see a list of supported options: :: - /? Display available options - /c Compile only - /D <macro[=value]> Define macro - /fallback Fall back to cl.exe if clang-cl fails to compile - /FA Output assembly code file during compilation - /Fa<file or directory> Output assembly code to this file during compilation - /Fe<file or directory> Set output executable file or directory (ends in / or \) - /FI<value> Include file before parsing - /Fo<file or directory> Set output object file, or directory (ends in / or \) - /GF- Disable string pooling - /GR- Disable RTTI - /GR Enable RTTI - /help Display available options - /I <dir> Add directory to include search path - /J Make char type unsigned - /LDd Create debug DLL - /LD Create DLL - /link <options> Forward options to the linker - /MDd Use DLL debug run-time - /MD Use DLL run-time - /MTd Use static debug run-time - /MT Use static run-time - /Ob0 Disable inlining - /Od Disable optimization - /Oi- Disable use of builtin functions - /Oi Enable use of builtin functions - /Os Optimize for size - /Ot Optimize for speed - /Ox Maximum optimization - /Oy- Disable frame pointer omission - /Oy Enable frame pointer omission - /O<n> Optimization level - /P Only run the preprocessor - /showIncludes Print info about included files to stderr - /TC Treat all source files as C - /Tc <filename> Specify a C source file - /TP Treat all source files as C++ - /Tp <filename> Specify a C++ source file - /U <macro> Undefine macro - /W0 Disable all warnings - /W1 Enable -Wall - /W2 Enable -Wall - /W3 Enable -Wall - /W4 Enable -Wall - /Wall Enable -Wall - /WX- Do not treat warnings as errors - /WX Treat warnings as errors - /w Disable all warnings - /Zs Syntax-check only + CL.EXE COMPATIBILITY OPTIONS: + /? Display available options + /arch:<value> Set architecture for code generation + /C Don't discard comments when preprocessing + /c Compile only + /D <macro[=value]> Define macro + /EH<value> Exception handling model + /EP Disable linemarker output and preprocess to stdout + /E Preprocess to stdout + /fallback Fall back to cl.exe if clang-cl fails to compile + /FA Output assembly code file during compilation + /Fa<file or directory> Output assembly code to this file during compilation + /Fe<file or directory> Set output executable file or directory (ends in / or \) + /FI <value> Include file before parsing + /Fi<file> Set preprocess output file name + /Fo<file or directory> Set output object file, or directory (ends in / or \) + /GF- Disable string pooling + /GR- Disable emission of RTTI data + /GR Enable emission of RTTI data + /Gw- Don't put each data item in its own section + /Gw Put each data item in its own section + /Gy- Don't put each function in its own section + /Gy Put each function in its own section + /help Display available options + /I <dir> Add directory to include search path + /J Make char type unsigned + /LDd Create debug DLL + /LD Create DLL + /link <options> Forward options to the linker + /MDd Use DLL debug run-time + /MD Use DLL run-time + /MTd Use static debug run-time + /MT Use static run-time + /Ob0 Disable inlining + /Od Disable optimization + /Oi- Disable use of builtin functions + /Oi Enable use of builtin functions + /Os Optimize for size + /Ot Optimize for speed + /Ox Maximum optimization + /Oy- Disable frame pointer omission + /Oy Enable frame pointer omission + /O<n> Optimization level + /P Preprocess to file + /showIncludes Print info about included files to stderr + /TC Treat all source files as C + /Tc <filename> Specify a C source file + /TP Treat all source files as C++ + /Tp <filename> Specify a C++ source file + /U <macro> Undefine macro + /vd<value> Control vtordisp placement + /vmb Use a best-case representation method for member pointers + /vmg Use a most-general representation for member pointers + /vmm Set the default most-general representation to multiple inheritance + /vms Set the default most-general representation to single inheritance + /vmv Set the default most-general representation to virtual inheritance + /W0 Disable all warnings + /W1 Enable -Wall + /W2 Enable -Wall + /W3 Enable -Wall + /W4 Enable -Wall + /Wall Enable -Wall + /WX- Do not treat warnings as errors + /WX Treat warnings as errors + /w Disable all warnings + /Zi Enable debug information + /Zs Syntax-check only + + OPTIONS: + -### Print (but do not run) the commands to run for this compilation + -fms-compatibility-version=<value> + Dot-separated value representing the Microsoft compiler version + number to report in _MSC_VER (0 = don't define it (default)) + -fmsc-version=<value> Microsoft compiler version number to report in _MSC_VER (0 = don't + define it (default)) + -fsanitize-blacklist=<value> + Path to blacklist file for sanitizers + -fsanitize=<check> Enable runtime instrumentation for bug detection: address (memory + errors) | thread (race detection) | undefined (miscellaneous + undefined behavior) + -mllvm <value> Additional arguments to forward to LLVM's option processing + -Qunused-arguments Don't emit warning for unused driver arguments + --target=<value> Generate code for the given target + -v Show commands to run and use verbose output + -W<warning> Enable the specified warning + -Xclang <arg> Pass <arg> to the clang compiler The /fallback Option ^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/analyzer/conf.py b/docs/analyzer/conf.py index 3690f936d336..1514708c0d5e 100644 --- a/docs/analyzer/conf.py +++ b/docs/analyzer/conf.py @@ -41,7 +41,7 @@ master_doc = 'index' # 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 183a285de249..1963a05385e8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -41,16 +41,16 @@ master_doc = 'index' # 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 61c0bd847f8a..2372e044cde8 100644 --- a/docs/doxygen.cfg.in +++ b/docs/doxygen.cfg.in @@ -697,6 +697,59 @@ BINARY_TOC = NO 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 b18deb9b063d..bf2de7ebfdab 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,7 +18,9 @@ Using Clang as a Compiler UsersManual LanguageExtensions + AttributeReference CrossCompilation + ThreadSafetyAnalysis AddressSanitizer ThreadSanitizer MemorySanitizer @@ -26,6 +28,7 @@ Using Clang as a Compiler LeakSanitizer SanitizerSpecialCaseList Modules + MSVCCompatibility FAQ Using Clang as a Library diff --git a/docs/tools/clang.pod b/docs/tools/clang.pod index a58986c3a6b9..f7d2eaf683cb 100644 --- a/docs/tools/clang.pod +++ b/docs/tools/clang.pod @@ -237,7 +237,7 @@ Specify the architecture to build for. =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,23 @@ Currently equivalent to B<-O3> =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. This is the default on Darwin. Note that Clang +will never emit type information for types that are not referenced at +all by the program. =item B<-fexceptions> @@ -366,7 +381,7 @@ to the linker depending on the stage selection options). =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 564dc380d648..4ece46ae34fa 100644 --- a/docs/tools/dump_ast_matchers.py +++ b/docs/tools/dump_ast_matchers.py @@ -119,9 +119,9 @@ def add_matcher(result_type, name, args, comment, is_dyncast=False): # 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 @@ def act_on_decl(declaration, comment, allowed_types): 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 @@ def act_on_decl(declaration, comment, allowed_types): # 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 0c8ca6d610f1..66bad8bb4e7e 100644 --- a/docs/tools/dump_format_style.py +++ b/docs/tools/dump_format_style.py @@ -98,7 +98,7 @@ def read_options(header): 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,8 @@ def read_options(header): 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', + 'std::vector<std::string>']: if enums.has_key(option.type): option.enum = enums[option.type] else: |