diff options
Diffstat (limited to 'docs')
37 files changed, 2293 insertions, 495 deletions
diff --git a/docs/AddressSanitizer.rst b/docs/AddressSanitizer.rst index f58995576f91..7549159a39ab 100644 --- a/docs/AddressSanitizer.rst +++ b/docs/AddressSanitizer.rst @@ -197,13 +197,17 @@ this purpose. Disabling Instrumentation with ``__attribute__((no_sanitize("address")))`` -------------------------------------------------------------------------- -Some code should not be instrumented by AddressSanitizer. One may use the -function attribute ``__attribute__((no_sanitize("address")))`` (which has -deprecated synonyms `no_sanitize_address` and `no_address_safety_analysis`) to -disable instrumentation of a particular function. This attribute may not be -supported by other compilers, so we suggest to use it together with +Some code should not be instrumented by AddressSanitizer. One may use +the attribute ``__attribute__((no_sanitize("address")))`` (which has +deprecated synonyms `no_sanitize_address` and +`no_address_safety_analysis`) to disable instrumentation of a +particular function. This attribute may not be supported by other +compilers, so we suggest to use it together with ``__has_feature(address_sanitizer)``. +The same attribute used on a global variable prevents AddressSanitizer +from adding redzones around it and detecting out of bounds accesses. + Suppressing Errors in Recompiled Code (Blacklist) ------------------------------------------------- @@ -272,6 +276,7 @@ AddressSanitizer is supported on: * OS X 10.7 - 10.11 (i386/x86\_64) * iOS Simulator * Android ARM +* NetBSD i386/x86\_64 * FreeBSD i386/x86\_64 (tested on FreeBSD 11-current) Ports to various other platforms are in progress. diff --git a/docs/AutomaticReferenceCounting.rst b/docs/AutomaticReferenceCounting.rst index fbd1ba4c4d47..bf4d0945672a 100644 --- a/docs/AutomaticReferenceCounting.rst +++ b/docs/AutomaticReferenceCounting.rst @@ -974,28 +974,66 @@ It is undefined behavior to access an ownership-qualified object through an lvalue of a differently-qualified type, except that any non-``__weak`` object may be read through an ``__unsafe_unretained`` lvalue. -It is undefined behavior if a managed operation is performed on a ``__strong`` -or ``__weak`` object without a guarantee that it contains a primitive zero -bit-pattern, or if the storage for such an object is freed or reused without the -object being first assigned a null pointer. +It is undefined behavior if the storage of a ``__strong`` or ``__weak`` +object is not properly initialized before the first managed operation +is performed on the object, or if the storage of such an object is freed +or reused before the object has been properly deinitialized. Storage for +a ``__strong`` or ``__weak`` object may be properly initialized by filling +it with the representation of a null pointer, e.g. by acquiring the memory +with ``calloc`` or using ``bzero`` to zero it out. A ``__strong`` or +``__weak`` object may be properly deinitialized by assigning a null pointer +into it. A ``__strong`` object may also be properly initialized +by copying into it (e.g. with ``memcpy``) the representation of a +different ``__strong`` object whose storage has been properly initialized; +doing this properly deinitializes the source object and causes its storage +to no longer be properly initialized. A ``__weak`` object may not be +representation-copied in this way. + +These requirements are followed automatically for objects whose +initialization and deinitialization are under the control of ARC: + +* objects of static, automatic, and temporary storage duration +* instance variables of Objective-C objects +* elements of arrays where the array object's initialization and + deinitialization are under the control of ARC +* fields of Objective-C struct types where the struct object's + initialization and deinitialization are under the control of ARC +* non-static data members of Objective-C++ non-union class types +* Objective-C++ objects and arrays of dynamic storage duration created + with the ``new`` or ``new[]`` operators and destroyed with the + corresponding ``delete`` or ``delete[]`` operator + +They are not followed automatically for these objects: + +* objects of dynamic storage duration created in other memory, such as + that returned by ``malloc`` +* union members .. admonition:: Rationale - ARC cannot differentiate between an assignment operator which is intended to - "initialize" dynamic memory and one which is intended to potentially replace - a value. Therefore the object's pointer must be valid before letting ARC at - it. Similarly, C and Objective-C do not provide any language hooks for - destroying objects held in dynamic memory, so it is the programmer's - responsibility to avoid leaks (``__strong`` objects) and consistency errors - (``__weak`` objects). - -These requirements are followed automatically in Objective-C++ when creating -objects of retainable object owner type with ``new`` or ``new[]`` and destroying -them with ``delete``, ``delete[]``, or a pseudo-destructor expression. Note -that arrays of nontrivially-ownership-qualified type are not ABI compatible with -non-ARC code because the element type is non-POD: such arrays that are -``new[]``'d in ARC translation units cannot be ``delete[]``'d in non-ARC -translation units and vice-versa. + ARC must perform special operations when initializing an object and + when destroying it. In many common situations, ARC knows when an + object is created and when it is destroyed and can ensure that these + operations are performed correctly. Otherwise, however, ARC requires + programmer cooperation to establish its initialization invariants + because it is infeasible for ARC to dynamically infer whether they + are intact. For example, there is no syntactic difference in C between + an assignment that is intended by the programmer to initialize a variable + and one that is intended to replace the existing value stored there, + but ARC must perform one operation or the other. ARC chooses to always + assume that objects are initialized (except when it is in charge of + initializing them) because the only workable alternative would be to + ban all code patterns that could potentially be used to access + uninitialized memory, and that would be too limiting. In practice, + this is rarely a problem because programmers do not generally need to + work with objects for which the requirements are not handled + automatically. + +Note that dynamically-allocated Objective-C++ arrays of +nontrivially-ownership-qualified type are not ABI-compatible with non-ARC +code because the non-ARC code will consider the element type to be POD. +Such arrays that are ``new[]``'d in ARC translation units cannot be +``delete[]``'d in non-ARC translation units and vice-versa. .. _arc.ownership.restrictions.pass_by_writeback: diff --git a/docs/Block-ABI-Apple.rst b/docs/Block-ABI-Apple.rst index 7f49bbd40d71..e48a24b43ce5 100644 --- a/docs/Block-ABI-Apple.rst +++ b/docs/Block-ABI-Apple.rst @@ -61,6 +61,14 @@ The following flags bits are in use thusly for a possible ABI.2010.3.16: .. code-block:: c enum { + // Set to true on blocks that have captures (and thus are not true + // global blocks) but are known not to escape for various other + // reasons. For backward compatiblity with old runtimes, whenever + // BLOCK_IS_NOESCAPE is set, BLOCK_IS_GLOBAL is set too. Copying a + // non-escaping block returns the original block and releasing such a + // block is a no-op, which is exactly how global blocks are handled. + BLOCK_IS_NOESCAPE = (1 << 23), + BLOCK_HAS_COPY_DISPOSE = (1 << 25), BLOCK_HAS_CTOR = (1 << 26), // helpers have C++ code BLOCK_IS_GLOBAL = (1 << 28), diff --git a/docs/ClangCommandLineReference.rst b/docs/ClangCommandLineReference.rst index 4d095883a4b7..5c15482cb251 100644 --- a/docs/ClangCommandLineReference.rst +++ b/docs/ClangCommandLineReference.rst @@ -36,10 +36,18 @@ Treat source input files as Objective-C inputs Treat source input files as Objective-C++ inputs +.. option:: -Qn + +Do not emit metadata containing compiler name and version + .. option:: -Qunused-arguments Don't emit warning for unused driver arguments +.. option:: -Qy + +Emit metadata containing compiler name and version + .. option:: -Wa,<arg>,<arg2>... Pass the comma separated arguments in <arg> to the assembler @@ -61,10 +69,10 @@ Pass <arg> to the ptxas assembler Pass <arg> to the target offloading toolchain. .. program:: clang1 -.. option:: -Xopenmp-target=<arg> <arg2> +.. option:: -Xopenmp-target=<triple> <arg> .. program:: clang -Pass <arg> to the specified target offloading toolchain. The triple that identifies the toolchain must be provided after the equals sign. +Pass <arg> to the target offloading toolchain identified by <triple>. .. option:: -Z<arg> @@ -116,10 +124,18 @@ Output path for the plist report .. option:: -bundle\_loader <arg> .. program:: clang +.. option:: -cfguard + +Emit tables required for Windows Control Flow Guard. + .. option:: -client\_name<arg> .. option:: -compatibility\_version<arg> +.. option:: --config <arg> + +Specifies configuration file + .. option:: --constant-cfstrings .. option:: -coverage, --coverage @@ -140,6 +156,10 @@ CUDA GPU architecture (e.g. sm\_35). May be specified more than once. Compile CUDA code for host only. Has no effect on non-CUDA compilations. +.. option:: --cuda-include-ptx=<arg>, --no-cuda-include-ptx=<arg> + +Include PTX for the follwing GPU architecture (e.g. sm\_35) or 'all'. May be specified more than once. + .. option:: --cuda-noopt-device-debug, --no-cuda-noopt-device-debug Enable device-side debug info generation. Disables ptxas optimizations. @@ -190,6 +210,14 @@ Use approximate transcendental functions Flush denormal floating point values to zero in CUDA device mode. +.. option:: -fcuda-rdc, -fno-cuda-rdc + +Generate relocatable device code, also known as separate compilation mode. + +.. option:: -ffixed-r19 + +Reserve the r19 register (Hexagon only) + .. option:: -fheinous-gnu-extensions .. option:: -flat\_namespace @@ -230,6 +258,8 @@ Display available options .. option:: --help-hidden +Display help for hidden options + .. option:: -image\_base <arg> .. option:: -index-header-map @@ -702,6 +732,14 @@ Print source range spans in numeric form .. option:: -fdiagnostics-show-category=<arg> +.. option:: -fdiscard-value-names, -fno-discard-value-names + +Discard value names in LLVM IR + +.. option:: -fexperimental-isel, -fno-experimental-isel + +Enables the experimental global instruction selector + .. option:: -fexperimental-new-pass-manager, -fno-experimental-new-pass-manager Enables an experimental new pass manager in LLVM. @@ -736,6 +774,10 @@ Level of field padding for AddressSanitizer Enable linker dead stripping of globals in AddressSanitizer +.. option:: -fsanitize-address-poison-class-member-array-new-cookie, -fno-sanitize-address-poison-class-member-array-new-cookie + +Enable poisoning array cookies when using class member operator new\[\] in AddressSanitizer + .. option:: -fsanitize-address-use-after-scope, -fno-sanitize-address-use-after-scope Enable use-after-scope detection in AddressSanitizer @@ -868,6 +910,10 @@ Add directory to include search path Restrict all prior -I flags to double-quoted inclusion and remove current directory from include path +.. option:: --cuda-path-ignore-env + +Ignore environment variables to detect CUDA installation + .. option:: --cuda-path=<arg> CUDA installation path @@ -912,7 +958,7 @@ Specify the module user build path Don't verify input files for the modules if the module has been successfully validated or loaded during this build session -.. option:: -fmodules-validate-system-headers +.. option:: -fmodules-validate-system-headers, -fno-modules-validate-system-headers Validate the system headers that a module depends on when loading the module @@ -920,8 +966,6 @@ Validate the system headers that a module depends on when loading the module Specify the prebuilt module path -.. option:: -i<arg> - .. option:: -idirafter<arg>, --include-directory-after <arg>, --include-directory-after=<arg> Add directory to AFTER include search path @@ -1107,6 +1151,12 @@ Target-independent compilation options .. option:: -faccess-control, -fno-access-control +.. option:: -falign-functions, -fno-align-functions + +.. program:: clang1 +.. option:: -falign-functions=<arg> +.. program:: clang + .. program:: clang1 .. option:: -faligned-allocation, -faligned-new, -fno-aligned-allocation .. program:: clang @@ -1175,6 +1225,10 @@ Load the clang builtins module map file. .. option:: -fcaret-diagnostics, -fno-caret-diagnostics +.. option:: -fcf-protection=<arg>, -fcf-protection (equivalent to -fcf-protection=full) + +Instrument control-flow architecture protection. Options: return, branch, full, none. + .. option:: -fclasspath=<arg>, --CLASSPATH <arg>, --CLASSPATH=<arg>, --classpath <arg>, --classpath=<arg> .. option:: -fcolor-diagnostics, -fno-color-diagnostics @@ -1305,6 +1359,8 @@ Use emutls functions to access thread\_local variables .. option:: -ferror-limit=<arg> +.. option:: -fescaping-block-tail-calls, -fno-escaping-block-tail-calls + .. option:: -fexceptions, -fno-exceptions Enable support for exception handling @@ -1321,6 +1377,10 @@ Allow aggressive, lossy floating-point optimizations .. option:: -ffor-scope, -fno-for-scope +.. option:: -fforce-enable-int128, -fno-force-enable-int128 + +Enable support for int128\_t type + .. option:: -ffp-contract=<arg> Form fused FP ops (e.g. FMAs): fast (everywhere) \| on (according to FP\_CONTRACT pragma, default) \| off (never fuse) @@ -1409,6 +1469,8 @@ Specify the maximum alignment to enforce on pointers lacking an explicit alignme .. option:: -fmerge-all-constants, -fno-merge-all-constants +Allow merging of constants + .. option:: -fmessage-length=<arg> .. option:: -fmodule-file-deps, -fno-module-file-deps @@ -1481,6 +1543,14 @@ Specifies the largest alignment guaranteed by '::operator new(size\_t)' Disable implicit builtin knowledge of a specific function +.. option:: -fdelete-null-pointer-checks, -fno-delete-null-pointer-checks + +When enabled, treat null pointer dereference, creation of a reference to null, +or passing a null pointer to a function parameter annotated with the "nonnull" +attribute as undefined behavior. (And, thus the optimizer may assume that any +pointer used in such a way must not have been null and optimize away the +branches accordingly.) On by default. + .. option:: -fno-elide-type Do not elide types when printing diagnostics @@ -1491,15 +1561,15 @@ Do not elide types when printing diagnostics Do not treat C++ operator name keywords as synonyms for operators -.. option:: -fno-strict-modules-decluse +.. option:: -fno-rtti-data -.. option:: -fno-working-directory +Control emission of RTTI data -.. option:: -fnoopenmp-relocatable-target +.. option:: -fno-strict-modules-decluse -Do not compile OpenMP target code as relocatable. +.. option:: -fno-working-directory -.. option:: -fnoopenmp-use-tls +.. option:: -fnoxray-link-deps .. option:: -fobjc-abi-version=<arg> @@ -1539,13 +1609,11 @@ Enable ARC-style weak references in Objective-C .. option:: -fopenmp, -fno-openmp -.. option:: -fopenmp-dump-offload-linker-script - -.. option:: -fopenmp-relocatable-target +Parse OpenMP pragmas and generate parallel code. -OpenMP target code is compiled as relocatable using the -c flag. For OpenMP targets the code is relocatable by default. +.. option:: -fopenmp-simd, -fno-openmp-simd -.. option:: -fopenmp-use-tls +Emit OpenMP code only for SIMD-based constructs. .. option:: -fopenmp-version=<arg> @@ -1656,6 +1724,10 @@ Allow division operations to be reassociated Override the default ABI to return small structs in registers +.. option:: -fregister-global-dtors-with-atexit, -fno-register-global-dtors-with-atexit + +Use atexit or \_\_cxa\_atexit to register global destructors + .. option:: -frelaxed-template-template-args, -fno-relaxed-template-template-args Enable C++17 relaxed template template argument matching @@ -1732,7 +1804,7 @@ Enable the superword-level parallelism vectorization passes .. option:: -fsplit-dwarf-inlining, -fno-split-dwarf-inlining -Place debug types in their own section (ELF Only) +Provide minimal debug info in the object/executable to facilitate online symbolication/stack traces in the absence of .dwo/.dwp files when using Split DWARF .. option:: -fsplit-stack @@ -1748,6 +1820,10 @@ Force the usage of stack protectors for all functions Use a strong heuristic to apply stack protectors to functions +.. option:: -fstack-size-section, -fno-stack-size-section + +Emit section containing metadata on function stack sizes + .. option:: -fstandalone-debug, -fno-limit-debug-info, -fno-standalone-debug Emit full debug info for all types used by the program @@ -1852,7 +1928,7 @@ Enable the loop vectorization passes .. option:: -fvisibility-inlines-hidden -Give inline C++ member functions default visibility by default +Give inline C++ member functions hidden visibility by default .. option:: -fvisibility-ms-compat @@ -1866,6 +1942,12 @@ Set the default symbol visibility for all global declarations Enables whole-program vtable optimization. Requires -flto +.. option:: -fforce-emit-vtables, -fno-force-emit-vtables + +In order to improve devirtualization, forces emitting of vtables even in +modules where it isn't necessary. It causes more inline virtual functions +to be emitted. + .. option:: -fwrapv, -fno-wrapv Treat signed integer overflow as two's complement @@ -1878,9 +1960,17 @@ Store string literals as writable data Determine whether to always emit \_\_xray\_customevent(...) calls even if the function it appears in is not always instrumented. +.. option:: -fxray-always-emit-typedevents, -fno-xray-always-emit-typedevents + +Determine whether to always emit \_\_xray\_typedevent(...) calls even if the function it appears in is not always instrumented. + .. option:: -fxray-always-instrument=<arg> -Filename defining the whitelist for imbuing the 'always instrument' XRay attribute. +DEPRECATED: Filename defining the whitelist for imbuing the 'always instrument' XRay attribute. + +.. option:: -fxray-attr-list=<arg> + +Filename defining the list of functions/types for imbuing XRay attributes. .. option:: -fxray-instruction-threshold<arg> @@ -1894,9 +1984,21 @@ Sets the minimum function size to instrument with XRay Generate XRay instrumentation sleds on function entry and exit +.. option:: -fxray-instrumentation-bundle=<arg> + +Select which XRay instrumentation points to emit. Options: all, none, function, custom. Default is 'all'. + +.. option:: -fxray-link-deps + +Tells clang to add the link dependencies for XRay. + +.. option:: -fxray-modes=<arg> + +List of modes to link in by default into XRay instrumented binaries. + .. option:: -fxray-never-instrument=<arg> -Filename defining the whitelist for imbuing the 'never instrument' XRay attribute. +DEPRECATED: Filename defining the whitelist for imbuing the 'never instrument' XRay attribute. .. option:: -fzero-initialized-in-bss, -fno-zero-initialized-in-bss @@ -1954,6 +2056,10 @@ OpenCL language standard to compile for. OpenCL only. This option is added for compatibility with OpenCL 1.0. +.. option:: -cl-uniform-work-group-size + +OpenCL only. Defines that the global work-size be a multiple of the work-group size specified to clEnqueueNDRangeKernel + .. option:: -cl-unsafe-math-optimizations OpenCL only. Allow unsafe floating-point optimizations. Also implies -cl-no-signed-zeros and -cl-mad-enable. @@ -1998,7 +2104,7 @@ Link stack frames through backchain on System Z .. option:: -mconsole<arg> -.. option:: -mcpu=<arg>, -mv4 (equivalent to -mcpu=hexagonv4), -mv5 (equivalent to -mcpu=hexagonv5), -mv55 (equivalent to -mcpu=hexagonv55), -mv60 (equivalent to -mcpu=hexagonv60), -mv62 (equivalent to -mcpu=hexagonv62) +.. option:: -mcpu=<arg>, -mv4 (equivalent to -mcpu=hexagonv4), -mv5 (equivalent to -mcpu=hexagonv5), -mv55 (equivalent to -mcpu=hexagonv55), -mv60 (equivalent to -mcpu=hexagonv60), -mv62 (equivalent to -mcpu=hexagonv62), -mv65 (equivalent to -mcpu=hexagonv65) .. option:: -mdefault-build-attributes<arg>, -mno-default-build-attributes<arg> @@ -2066,6 +2172,10 @@ Use Intel MCU ABI (integrated-as) Emit an object file which can be used with an incremental linker +.. option:: -mindirect-jump=<arg> + +Change indirect jump instructions to inhibit speculation + .. option:: -miphoneos-version-min=<arg>, -mios-version-min=<arg> .. option:: -mips16 @@ -2156,6 +2266,10 @@ Use software floating point Set the stack alignment +.. option:: -mstack-arg-probe, -mno-stack-arg-probe + +Enable stack probes + .. option:: -mstack-probe-size=<arg> Set the stack probe size @@ -2196,6 +2310,10 @@ AARCH64 Reserve the x18 register (AArch64 only) +.. option:: -ffixed-x20 + +Reserve the x20 register (AArch64 only) + .. option:: -mfix-cortex-a53-835769, -mno-fix-cortex-a53-835769 Workaround Cortex-A53 erratum 835769 (AArch64 only) @@ -2252,16 +2370,16 @@ Hexagon ------- .. option:: -mieee-rnd-near +.. option:: -mpackets, -mno-packets + +Enable generation of instruction packets + Hexagon ------- .. option:: -mhvx, -mno-hvx Enable Hexagon Vector eXtensions -.. option:: -mhvx-double, -mno-hvx-double - -Enable Hexagon Double Vector eXtensions - .. option:: -mhvx-length=<arg> Set Hexagon Vector Length @@ -2306,12 +2424,18 @@ PowerPC .. option:: -mqpx, -mno-qpx +.. option:: -msecure-plt + .. option:: -mvsx, -mno-vsx WebAssembly ----------- +.. option:: -mexception-handling, -mno-exception-handling + .. option:: -mnontrapping-fptoint, -mno-nontrapping-fptoint +.. option:: -msign-ext, -mno-sign-ext + .. option:: -msimd128, -mno-simd128 X86 @@ -2328,6 +2452,8 @@ X86 .. option:: -mavx2, -mno-avx2 +.. option:: -mavx512bitalg, -mno-avx512bitalg + .. option:: -mavx512bw, -mno-avx512bw .. option:: -mavx512cd, -mno-avx512cd @@ -2344,14 +2470,20 @@ X86 .. option:: -mavx512vbmi, -mno-avx512vbmi +.. option:: -mavx512vbmi2, -mno-avx512vbmi2 + .. option:: -mavx512vl, -mno-avx512vl +.. option:: -mavx512vnni, -mno-avx512vnni + .. option:: -mavx512vpopcntdq, -mno-avx512vpopcntdq .. option:: -mbmi, -mno-bmi .. option:: -mbmi2, -mno-bmi2 +.. option:: -mcldemote, -mno-cldemote + .. option:: -mclflushopt, -mno-clflushopt .. option:: -mclwb, -mno-clwb @@ -2370,7 +2502,7 @@ X86 .. option:: -mfxsr, -mno-fxsr -.. option:: -mibt, -mno-ibt +.. option:: -mgfni, -mno-gfni .. option:: -mlwp, -mno-lwp @@ -2380,6 +2512,10 @@ X86 .. option:: -mmovbe, -mno-movbe +.. option:: -mmovdiri, -mno-movdiri + +.. option:: -mmovdir64b, -mno-movdir64b + .. option:: -mmpx, -mno-mpx .. option:: -mmwaitx, -mno-mwaitx @@ -2394,12 +2530,20 @@ X86 .. option:: -mprfchw, -mno-prfchw +.. option:: -mrdpid, -mno-rdpid + .. option:: -mrdrnd, -mno-rdrnd .. option:: -mrdseed, -mno-rdseed +.. option:: -mretpoline, -mno-retpoline + +.. option:: -mretpoline-external-thunk, -mno-retpoline-external-thunk + .. option:: -mrtm, -mno-rtm +.. option:: -msahf, -mno-sahf + .. option:: -msgx, -mno-sgx .. option:: -msha, -mno-sha @@ -2424,6 +2568,14 @@ X86 .. option:: -mtbm, -mno-tbm +.. option:: -mvaes, -mno-vaes + +.. option:: -mvpclmulqdq, -mno-vpclmulqdq + +.. option:: -mwaitpkg, -mno-waitpkg + +.. option:: -mwbnoinvd, -mno-wbnoinvd + .. option:: -mx87, -m80387, -mno-x87 .. option:: -mxop, -mno-xop @@ -2515,6 +2667,10 @@ Debug information flags .. option:: -gdwarf-aranges +.. option:: -gembed-source, -gno-embed-source + +Embed source text in DWARF debug sections + .. option:: -ggnu-pubnames .. option:: -grecord-gcc-switches, -gno-record-gcc-switches @@ -2680,6 +2836,8 @@ a Fortran input. .. option:: -fwhole-file, -fno-whole-file +.. option:: -imultilib <arg> + .. option:: -nocpp .. option:: -static-libgfortran @@ -2704,11 +2862,11 @@ Set starting address of BSS to <addr> .. option:: -Tdata<addr> -Set starting address of BSS to <addr> +Set starting address of DATA to <addr> .. option:: -Ttext<addr> -Set starting address of BSS to <addr> +Set starting address of TEXT to <addr> .. option:: -Wl,<arg>,<arg2>... diff --git a/docs/ClangFormatStyleOptions.rst b/docs/ClangFormatStyleOptions.rst index 04267928a92a..e4892d79b91f 100644 --- a/docs/ClangFormatStyleOptions.rst +++ b/docs/ClangFormatStyleOptions.rst @@ -490,15 +490,50 @@ the configuration (without a prefix: ``Auto``). "bbbb" "cccc"; "cccc"; -**AlwaysBreakTemplateDeclarations** (``bool``) - If ``true``, always break after the ``template<...>`` of a template - declaration. +**AlwaysBreakTemplateDeclarations** (``BreakTemplateDeclarationsStyle``) + The template declaration breaking style to use. + + Possible values: + + * ``BTDS_No`` (in configuration: ``No``) + Do not force break before declaration. + ``PenaltyBreakTemplateDeclaration`` is taken into account. + + .. code-block:: c++ + + template <typename T> T foo() { + } + template <typename T> T foo(int aaaaaaaaaaaaaaaaaaaaa, + int bbbbbbbbbbbbbbbbbbbbb) { + } + + * ``BTDS_MultiLine`` (in configuration: ``MultiLine``) + Force break after template declaration only when the following + declaration spans multiple lines. + + .. code-block:: c++ + + template <typename T> T foo() { + } + template <typename T> + T foo(int aaaaaaaaaaaaaaaaaaaaa, + int bbbbbbbbbbbbbbbbbbbbb) { + } + + * ``BTDS_Yes`` (in configuration: ``Yes``) + Always break after template declaration. + + .. code-block:: c++ + + template <typename T> + T foo() { + } + template <typename T> + T foo(int aaaaaaaaaaaaaaaaaaaaa, + int bbbbbbbbbbbbbbbbbbbbb) { + } - .. code-block:: c++ - true: false: - template <typename T> vs. template <typename T> class C {}; - class C {}; **BinPackArguments** (``bool``) If ``false``, a function call's arguments will either be all on the @@ -629,7 +664,9 @@ the configuration (without a prefix: ``Auto``). int bar(); } - * ``bool AfterObjCDeclaration`` Wrap ObjC definitions (``@autoreleasepool``, interfaces, ..). + * ``bool AfterObjCDeclaration`` Wrap ObjC definitions (interfaces, implementations...). + @autoreleasepool and @synchronized blocks are wrapped + according to `AfterControlStatement` flag. * ``bool AfterStruct`` Wrap struct definitions. @@ -957,18 +994,6 @@ the configuration (without a prefix: ``Auto``). -**BreakBeforeInheritanceComma** (``bool``) - If ``true``, in the class inheritance expression clang-format will - break before ``:`` and ``,`` if there is multiple inheritance. - - .. code-block:: c++ - - true: false: - class MyClass vs. class MyClass : public X, public Y { - : public X }; - , public Y { - }; - **BreakBeforeTernaryOperators** (``bool``) If ``true``, ternary operators will be placed after line breaks. @@ -994,9 +1019,9 @@ the configuration (without a prefix: ``Auto``). .. code-block:: c++ - Constructor() - : initializer1(), - initializer2() + Constructor() + : initializer1(), + initializer2() * ``BCIS_BeforeComma`` (in configuration: ``BeforeComma``) Break constructor initializers before the colon and commas, and align @@ -1004,18 +1029,56 @@ the configuration (without a prefix: ``Auto``). .. code-block:: c++ - Constructor() - : initializer1() - , initializer2() + Constructor() + : initializer1() + , initializer2() * ``BCIS_AfterColon`` (in configuration: ``AfterColon``) Break constructor initializers after the colon and commas. .. code-block:: c++ - Constructor() : - initializer1(), - initializer2() + Constructor() : + initializer1(), + initializer2() + + + +**BreakInheritanceList** (``BreakInheritanceListStyle``) + The inheritance list style to use. + + Possible values: + + * ``BILS_BeforeColon`` (in configuration: ``BeforeColon``) + Break inheritance list before the colon and after the commas. + + .. code-block:: c++ + + class Foo + : Base1, + Base2 + {}; + + * ``BILS_BeforeComma`` (in configuration: ``BeforeComma``) + Break inheritance list before the colon and commas, and align + the commas with the colon. + + .. code-block:: c++ + + class Foo + : Base1 + , Base2 + {}; + + * ``BILS_AfterColon`` (in configuration: ``AfterColon``) + Break inheritance list after the colon and commas. + + .. code-block:: c++ + + class Foo : + Base1, + Base2 + {}; @@ -1085,7 +1148,7 @@ the configuration (without a prefix: ``Auto``). **ConstructorInitializerIndentWidth** (``unsigned``) The number of characters to use for indentation of constructor - initializer lists. + initializer lists as well as inheritance lists. **ContinuationIndentWidth** (``unsigned``) Indent width for line continuations. @@ -1201,7 +1264,8 @@ the configuration (without a prefix: ``Auto``). * ``IBS_Regroup`` (in configuration: ``Regroup``) Merge multiple ``#include`` blocks together and sort as one. - Then split into groups based on category priority. See ``IncludeCategories``. + Then split into groups based on category priority. See + ``IncludeCategories``. .. code-block:: c++ @@ -1216,6 +1280,10 @@ the configuration (without a prefix: ``Auto``). Regular expressions denoting the different ``#include`` categories used for ordering ``#includes``. + `POSIX extended + <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html>`_ + regular expressions are supported. + These regular expressions are matched against the filename of an include (including the <> or "") in order. The value belonging to the first matching regular expression is assigned and ``#includes`` are sorted first @@ -1238,6 +1306,8 @@ the configuration (without a prefix: ``Auto``). Priority: 2 - Regex: '^(<|"(gtest|gmock|isl|json)/)' Priority: 3 + - Regex: '<[[:alnum:].]+>' + Priority: 4 - Regex: '.*' Priority: 1 @@ -1507,6 +1577,52 @@ the configuration (without a prefix: ``Auto``). +**ObjCBinPackProtocolList** (``BinPackStyle``) + Controls bin-packing Objective-C protocol conformance list + items into as few lines as possible when they go over ``ColumnLimit``. + + If ``Auto`` (the default), delegates to the value in + ``BinPackParameters``. If that is ``true``, bin-packs Objective-C + protocol conformance list items into as few lines as possible + whenever they go over ``ColumnLimit``. + + If ``Always``, always bin-packs Objective-C protocol conformance + list items into as few lines as possible whenever they go over + ``ColumnLimit``. + + If ``Never``, lays out Objective-C protocol conformance list items + onto individual lines whenever they go over ``ColumnLimit``. + + + .. code-block:: objc + + Always (or Auto, if BinPackParameters=true): + @interface ccccccccccccc () < + ccccccccccccc, ccccccccccccc, + ccccccccccccc, ccccccccccccc> { + } + + Never (or Auto, if BinPackParameters=false): + @interface ddddddddddddd () < + ddddddddddddd, + ddddddddddddd, + ddddddddddddd, + ddddddddddddd> { + } + + Possible values: + + * ``BPS_Auto`` (in configuration: ``Auto``) + Automatically determine parameter bin-packing behavior. + + * ``BPS_Always`` (in configuration: ``Always``) + Always bin-pack parameters. + + * ``BPS_Never`` (in configuration: ``Never``) + Never bin-pack parameters. + + + **ObjCBlockIndentWidth** (``unsigned``) The number of characters to use for indentation of ObjC blocks. @@ -1541,6 +1657,9 @@ the configuration (without a prefix: ``Auto``). **PenaltyBreakString** (``unsigned``) The penalty for each line break introduced inside a string literal. +**PenaltyBreakTemplateDeclaration** (``unsigned``) + The penalty for breaking after template declaration. + **PenaltyExcessCharacter** (``unsigned``) The penalty for each character outside of the column limit. @@ -1577,24 +1696,42 @@ the configuration (without a prefix: ``Auto``). **RawStringFormats** (``std::vector<RawStringFormat>``) - Raw string delimiters denoting that the raw string contents are - code in a particular language and can be reformatted. + Defines hints for detecting supported languages code blocks in raw + strings. + + A raw string with a matching delimiter or a matching enclosing function + name will be reformatted assuming the specified language based on the + style for that language defined in the .clang-format file. If no style has + been defined in the .clang-format file for the specific language, a + predefined style given by 'BasedOnStyle' is used. If 'BasedOnStyle' is not + found, the formatting is based on llvm style. A matching delimiter takes + precedence over a matching enclosing function name for determining the + language of the raw string contents. - A raw string with a matching delimiter will be reformatted assuming the - specified language based on a predefined style given by 'BasedOnStyle'. - If 'BasedOnStyle' is not found, the formatting is based on llvm style. + If a canonical delimiter is specified, occurrences of other delimiters for + the same language will be updated to the canonical if possible. + + There should be at most one specification per language and each delimiter + and enclosing function should not occur in multiple specifications. To configure this in the .clang-format file, use: .. code-block:: yaml RawStringFormats: - - Delimiter: 'pb' - Language: TextProto - BasedOnStyle: llvm - - Delimiter: 'proto' - Language: TextProto - BasedOnStyle: google + - Language: TextProto + Delimiters: + - 'pb' + - 'proto' + EnclosingFunctions: + - 'PARSE_TEXT_PROTO' + BasedOnStyle: google + - Language: Cpp + Delimiters: + - 'cc' + - 'cpp' + BasedOnStyle: llvm + CanonicalDelimiter: 'cc' **ReflowComments** (``bool``) If ``true``, clang-format will attempt to re-flow comments. @@ -1643,7 +1780,7 @@ the configuration (without a prefix: ``Auto``). .. code-block:: c++ true: false: - (int)i; vs. (int) i; + (int) i; vs. (int)i; **SpaceAfterTemplateKeyword** (``bool``) If ``true``, a space will be inserted after the 'template' keyword. @@ -1662,6 +1799,35 @@ the configuration (without a prefix: ``Auto``). int a = 5; vs. int a=5; a += 42 a+=42; +**SpaceBeforeCpp11BracedList** (``bool``) + If ``true``, a space will be inserted before a C++11 braced list + used to initialize an object (after the preceding identifier or type). + + .. code-block:: c++ + + true: false: + Foo foo { bar }; vs. Foo foo{ bar }; + Foo {}; Foo{}; + vector<int> { 1, 2, 3 }; vector<int>{ 1, 2, 3 }; + new int[3] { 1, 2, 3 }; new int[3]{ 1, 2, 3 }; + +**SpaceBeforeCtorInitializerColon** (``bool``) + If ``false``, spaces will be removed before constructor initializer + colon. + + .. code-block:: c++ + + true: false: + Foo::Foo() : a(a) {} Foo::Foo(): a(a) {} + +**SpaceBeforeInheritanceColon** (``bool``) + If ``false``, spaces will be removed before inheritance colon. + + .. code-block:: c++ + + true: false: + class Foo : Bar {} vs. class Foo: Bar {} + **SpaceBeforeParens** (``SpaceBeforeParensOptions``) Defines in which cases to put a space before opening parentheses. @@ -1706,6 +1872,15 @@ the configuration (without a prefix: ``Auto``). +**SpaceBeforeRangeBasedForLoopColon** (``bool``) + If ``false``, spaces will be removed before range-based for loop + colon. + + .. code-block:: c++ + + true: false: + for (auto v : values) {} vs. for(auto v: values) {} + **SpaceInEmptyParentheses** (``bool``) If ``true``, spaces may be inserted into ``()``. diff --git a/docs/CommandGuide/clang.rst b/docs/CommandGuide/clang.rst index 16bb09f3c740..d440d915d686 100644 --- a/docs/CommandGuide/clang.rst +++ b/docs/CommandGuide/clang.rst @@ -98,10 +98,129 @@ Language Selection and Mode Options Treat subsequent input files as having type language. -.. option:: -std=<language> +.. option:: -std=<standard> Specify the language standard to compile for. + Supported values for the C language are: + + | ``c89`` + | ``c90`` + | ``iso9899:1990`` + + ISO C 1990 + + | ``iso9899:199409`` + + ISO C 1990 with amendment 1 + + | ``gnu89`` + | ``gnu90`` + + ISO C 1990 with GNU extensions + + | ``c99`` + | ``iso9899:1999`` + + ISO C 1999 + + | ``gnu99`` + + ISO C 1999 with GNU extensions + + | ``c11`` + | ``iso9899:2011`` + + ISO C 2011 + + | ``gnu11`` + + ISO C 2011 with GNU extensions + + | ``c17`` + | ``iso9899:2017`` + + ISO C 2017 + + | ``gnu17`` + + ISO C 2017 with GNU extensions + + The default C language standard is ``gnu11``, except on PS4, where it is + ``gnu99``. + + Supported values for the C++ language are: + + | ``c++98`` + | ``c++03`` + + ISO C++ 1998 with amendments + + | ``gnu++98`` + | ``gnu++03`` + + ISO C++ 1998 with amendments and GNU extensions + + | ``c++11`` + + ISO C++ 2011 with amendments + + | ``gnu++11`` + + ISO C++ 2011 with amendments and GNU extensions + + | ``c++14`` + + ISO C++ 2014 with amendments + + | ``gnu++14`` + + ISO C++ 2014 with amendments and GNU extensions + + | ``c++17`` + + ISO C++ 2017 with amendments + + | ``gnu++17`` + + ISO C++ 2017 with amendments and GNU extensions + + | ``c++2a`` + + Working draft for ISO C++ 2020 + + | ``gnu++2a`` + + Working draft for ISO C++ 2020 with GNU extensions + + The default C++ language standard is ``gnu++14``. + + Supported values for the OpenCL language are: + + | ``cl1.0`` + + OpenCL 1.0 + + | ``cl1.1`` + + OpenCL 1.1 + + | ``cl1.2`` + + OpenCL 1.2 + + | ``cl2.0`` + + OpenCL 2.0 + + The default OpenCL language standard is ``cl1.0``. + + Supported values for the CUDA language are: + + | ``cuda`` + + NVIDIA CUDA(tm) + .. option:: -stdlib=<library> Specify the C++ standard library to use; supported options are libstdc++ and diff --git a/docs/CommandGuide/diagtool.rst b/docs/CommandGuide/diagtool.rst new file mode 100644 index 000000000000..59417f71f69d --- /dev/null +++ b/docs/CommandGuide/diagtool.rst @@ -0,0 +1,52 @@ +diagtool - clang diagnostics tool +================================= + +SYNOPSIS +-------- + +:program:`diagtool` *command* [*args*] + +DESCRIPTION +----------- + +:program:`diagtool` is a combination of four tool for dealing with diagnostics in :program:`clang`. + +SUBCOMMANDS +----------- + +:program:`diagtool` is separated into several subcommands each tailored to a +different purpose. A brief summary of each command follows, with more detail in +the sections that follow. + + * :ref:`find_diagnostic_id` - Print the id of the given diagnostic. + * :ref:`list_warnings` - List warnings and their corresponding flags. + * :ref:`show_enabled` - Show which warnings are enabled for a given command line. + * :ref:`tree` - Show warning flags in a tree view. + +.. _find_diagnostic_id: + +find-diagnostic-id +~~~~~~~~~~~~~~~~~~ + +:program:`diagtool` find-diagnostic-id *diagnostic-name* + +.. _list_warnings: + +list-warnings +~~~~~~~~~~~~~ + +:program:`diagtool` list-warnings + +.. _show_enabled: + +show-enabled +~~~~~~~~~~~~ + +:program:`diagtool` show-enabled [*options*] *filename ...* + +.. _tree: + +tree +~~~~ + +:program:`diagtool` tree [*diagnostic-group*] diff --git a/docs/CommandGuide/index.rst b/docs/CommandGuide/index.rst index 826ed9711980..83a91182e9ca 100644 --- a/docs/CommandGuide/index.rst +++ b/docs/CommandGuide/index.rst @@ -15,3 +15,4 @@ Basic Commands :maxdepth: 1 clang + diagtool diff --git a/docs/ControlFlowIntegrity.rst b/docs/ControlFlowIntegrity.rst index 12b4610f8a28..fcc640988897 100644 --- a/docs/ControlFlowIntegrity.rst +++ b/docs/ControlFlowIntegrity.rst @@ -66,6 +66,8 @@ Available schemes are: wrong dynamic type. - ``-fsanitize=cfi-icall``: Indirect call of a function with wrong dynamic type. + - ``-fsanitize=cfi-mfcall``: Indirect call via a member function pointer with + wrong dynamic type. You can use ``-fsanitize=cfi`` to enable all the schemes and use ``-fno-sanitize`` flag to narrow down the set of schemes as desired. @@ -106,8 +108,9 @@ This CFI scheme can be enabled on its own using ``-fsanitize=cfi-vcall``. For this scheme to work, all translation units containing the definition of a virtual member function (whether inline or not), other than members -of :ref:`blacklisted <cfi-blacklist>` types, must be compiled with -``-fsanitize=cfi-vcall`` enabled and be statically linked into the program. +of :ref:`blacklisted <cfi-blacklist>` types or types with public :doc:`LTO +visibility <LTOVisibility>`, must be compiled with ``-flto`` or ``-flto=thin`` +enabled and be statically linked into the program. Performance ----------- @@ -152,9 +155,9 @@ functions may be :ref:`blacklisted <cfi-blacklist>`. For this scheme to work, all translation units containing the definition of a virtual member function (whether inline or not), other than members -of :ref:`blacklisted <cfi-blacklist>` types, must be compiled with -``-fsanitize=cfi-derived-cast`` or ``-fsanitize=cfi-unrelated-cast`` enabled -and be statically linked into the program. +of :ref:`blacklisted <cfi-blacklist>` types or types with public :doc:`LTO +visibility <LTOVisibility>`, must be compiled with ``-flto`` or ``-flto=thin`` +enabled and be statically linked into the program. Non-Virtual Member Function Call Checking ========================================= @@ -168,8 +171,9 @@ polymorphic class type. This CFI scheme can be enabled on its own using For this scheme to work, all translation units containing the definition of a virtual member function (whether inline or not), other than members -of :ref:`blacklisted <cfi-blacklist>` types, must be compiled with -``-fsanitize=cfi-nvcall`` enabled and be statically linked into the program. +of :ref:`blacklisted <cfi-blacklist>` types or types with public :doc:`LTO +visibility <LTOVisibility>`, must be compiled with ``-flto`` or ``-flto=thin`` +enabled and be statically linked into the program. .. _cfi-strictness: @@ -224,8 +228,8 @@ flag relax pointer type checking for call sites in that translation unit, applied across all functions compiled with ``-fsanitize=cfi-icall``. Specifically, pointers in return and argument types are treated as equivalent as -long as the qualifiers for the type they point to match. For example, ``char*`` -``char**`, and ``int*`` are considered equivalent types. However, ``char*`` and +long as the qualifiers for the type they point to match. For example, ``char*``, +``char**``, and ``int*`` are considered equivalent types. However, ``char*`` and ``const char*`` are considered separate types. ``-fsanitize-cfi-icall-generalize-pointers`` is not compatible with @@ -253,6 +257,34 @@ the identity of function pointers is maintained, and calls across shared library boundaries are no different from calls within a single program or shared library. +Member Function Pointer Call Checking +===================================== + +This scheme checks that indirect calls via a member function pointer +take place using an object of the correct dynamic type. Specifically, we +check that the dynamic type of the member function referenced by the member +function pointer matches the "function pointer" part of the member function +pointer, and that the member function's class type is related to the base +type of the member function. This CFI scheme can be enabled on its own using +``-fsanitize=cfi-mfcall``. + +The compiler will only emit a full CFI check if the member function pointer's +base type is complete. This is because the complete definition of the base +type contains information that is necessary to correctly compile the CFI +check. To ensure that the compiler always emits a full CFI check, it is +recommended to also pass the flag ``-fcomplete-member-pointers``, which +enables a non-conforming language extension that requires member pointer +base types to be complete if they may be used for a call. + +For this scheme to work, all translation units containing the definition +of a virtual member function (whether inline or not), other than members +of :ref:`blacklisted <cfi-blacklist>` types or types with public :doc:`LTO +visibility <LTOVisibility>`, must be compiled with ``-flto`` or ``-flto=thin`` +enabled and be statically linked into the program. + +This scheme is currently not compatible with cross-DSO CFI or the +Microsoft ABI. + .. _cfi-blacklist: Blacklist diff --git a/docs/DiagnosticsReference.rst b/docs/DiagnosticsReference.rst index e2b0bd7dd550..734a45902484 100644 --- a/docs/DiagnosticsReference.rst +++ b/docs/DiagnosticsReference.rst @@ -7555,9 +7555,9 @@ This diagnostic is enabled by default. **Diagnostic text:** -+------------------------------------------------------------------------------------------------------------+ -|:warning:`warning:` |nbsp| :diagtext:`default property attribute 'assign' not appropriate for non-GC object`| -+------------------------------------------------------------------------------------------------------------+ ++-----------------------------------------------------------------------------------------------------+ +|:warning:`warning:` |nbsp| :diagtext:`default property attribute 'assign' not appropriate for object`| ++-----------------------------------------------------------------------------------------------------+ +--------------------------------------------------------------------------------------------------------------------+ |:warning:`warning:` |nbsp| :diagtext:`no 'assign', 'retain', or 'copy' attribute is specified - 'assign' is assumed`| diff --git a/docs/HardwareAssistedAddressSanitizerDesign.rst b/docs/HardwareAssistedAddressSanitizerDesign.rst index 5904cceaead2..2578914376ae 100644 --- a/docs/HardwareAssistedAddressSanitizerDesign.rst +++ b/docs/HardwareAssistedAddressSanitizerDesign.rst @@ -7,8 +7,6 @@ This page is a design document for a tool similar to :doc:`AddressSanitizer`, but based on partial hardware assistance. -The document is a draft, suggestions are welcome. - Introduction ============ @@ -30,15 +28,16 @@ accuracy guarantees. Algorithm ========= -* Every heap/stack/global memory object is forcibly aligned by `N` bytes - (`N` is e.g. 16 or 64). We call `N` the **granularity** of tagging. -* For every such object a random `K`-bit tag `T` is chosen (`K` is e.g. 4 or 8) +* Every heap/stack/global memory object is forcibly aligned by `TG` bytes + (`TG` is e.g. 16 or 64). We call `TG` the **tagging granularity**. +* For every such object a random `TS`-bit tag `T` is chosen (`TS`, or tag size, is e.g. 4 or 8) * The pointer to the object is tagged with `T`. -* The memory for the object is also tagged with `T` - (using a `N=>1` shadow memory) +* The memory for the object is also tagged with `T` (using a `TG=>1` shadow memory) * Every load and store is instrumented to read the memory tag and compare it with the pointer tag, exception is raised on tag mismatch. +For a more detailed discussion of this approach see https://arxiv.org/pdf/1802.09517.pdf + Instrumentation =============== @@ -53,17 +52,16 @@ verifies the tags. Currently, the following sequence is used: // int foo(int *a) { return *a; } // clang -O2 --target=aarch64-linux -fsanitize=hwaddress -c load.c foo: - 0: 08 dc 44 d3 ubfx x8, x0, #4, #52 // shadow address - 4: 08 01 40 39 ldrb w8, [x8] // load shadow - 8: 09 fc 78 d3 lsr x9, x0, #56 // address tag - c: 3f 01 08 6b cmp w9, w8 // compare tags - 10: 61 00 00 54 b.ne #12 // jump on mismatch - 14: 00 00 40 b9 ldr w0, [x0] // original load - 18: c0 03 5f d6 ret - 1c: 40 20 40 d4 hlt #0x102 // halt - 20: 00 00 40 b9 ldr w0, [x0] // original load - 24: c0 03 5f d6 ret - + 0: 08 00 00 90 adrp x8, 0 <__hwasan_shadow> + 4: 08 01 40 f9 ldr x8, [x8] // shadow base (to be resolved by the loader) + 8: 09 dc 44 d3 ubfx x9, x0, #4, #52 // shadow offset + c: 28 69 68 38 ldrb w8, [x9, x8] // load shadow tag + 10: 09 fc 78 d3 lsr x9, x0, #56 // extract address tag + 14: 3f 01 08 6b cmp w9, w8 // compare tags + 18: 61 00 00 54 b.ne 24 // jump on mismatch + 1c: 00 00 40 b9 ldr w0, [x0] // original load + 20: c0 03 5f d6 ret + 24: 40 20 21 d4 brk #0x902 // trap Alternatively, memory accesses are prefixed with a function call. @@ -71,17 +69,24 @@ Heap ---- Tagging the heap memory/pointers is done by `malloc`. -This can be based on any malloc that forces all objects to be N-aligned. +This can be based on any malloc that forces all objects to be TG-aligned. `free` tags the memory with a different tag. Stack ----- -Special compiler instrumentation is required to align the local variables -by N, tag the memory and the pointers. +Stack frames are instrumented by aligning all non-promotable allocas +by `TG` and tagging stack memory in function prologue and epilogue. + +Tags for different allocas in one function are **not** generated +independently; doing that in a function with `M` allocas would require +maintaining `M` live stack pointers, significantly increasing register +pressure. Instead we generate a single base tag value in the prologue, +and build the tag for alloca number `M` as `ReTag(BaseTag, M)`, where +ReTag can be as simple as exclusive-or with constant `M`. + Stack instrumentation is expected to be a major source of overhead, but could be optional. -TODO: details. Globals ------- @@ -126,15 +131,25 @@ HWASAN: https://www.kernel.org/doc/Documentation/arm64/tagged-pointers.txt). * **Does not require redzones to detect buffer overflows**, but the buffer overflow detection is probabilistic, with roughly - `(2**K-1)/(2**K)` probability of catching a bug. + `(2**TS-1)/(2**TS)` probability of catching a bug. * **Does not require quarantine to detect heap-use-after-free, or stack-use-after-return**. The detection is similarly probabilistic. The memory overhead of HWASAN is expected to be much smaller than that of AddressSanitizer: -`1/N` extra memory for the shadow -and some overhead due to `N`-aligning all objects. +`1/TG` extra memory for the shadow +and some overhead due to `TG`-aligning all objects. + +Supported architectures +======================= +HWASAN relies on `Address Tagging`_ which is only available on AArch64. +For other 64-bit architectures it is possible to remove the address tags +before every load and store by compiler instrumentation, but this variant +will have limited deployability since not all of the code is +typically instrumented. + +The HWASAN's approach is not applicable to 32-bit architectures. Related Work diff --git a/docs/HowToSetupToolingForLLVM.rst b/docs/HowToSetupToolingForLLVM.rst index 3812fc9f46e7..686aca840ada 100644 --- a/docs/HowToSetupToolingForLLVM.rst +++ b/docs/HowToSetupToolingForLLVM.rst @@ -133,7 +133,8 @@ Examples: if (this->ASTList.operator _Bool()) return clang::CreateASTDeclNodeLister(); if (this->ASTDump.operator _Bool()) - return clang::CreateASTDumper(this->ASTDumpFilter); + return clang::CreateASTDumper(nullptr /*Dump to stdout.*/, + this->ASTDumpFilter); if (this->ASTPrint.operator _Bool()) return clang::CreateASTPrinter(&llvm::outs(), this->ASTDumpFilter); return new clang::ASTConsumer(); diff --git a/docs/InternalsManual.rst b/docs/InternalsManual.rst index 058c63f0afd6..af15b2e51e1c 100644 --- a/docs/InternalsManual.rst +++ b/docs/InternalsManual.rst @@ -54,7 +54,7 @@ number of source ranges that related to the diagnostic. In this section, we'll be giving examples produced by the Clang command line driver, but diagnostics can be :ref:`rendered in many different ways -<DiagnosticClient>` depending on how the ``DiagnosticClient`` interface is +<DiagnosticConsumer>` depending on how the ``DiagnosticConsumer`` interface is implemented. A representative example of a diagnostic is: .. code-block:: text @@ -188,7 +188,7 @@ Formatting a Diagnostic Argument Arguments to diagnostics are fully typed internally, and come from a couple different classes: integers, types, names, and random strings. Depending on the class of the argument, it can be optionally formatted in different ways. -This gives the ``DiagnosticClient`` information about what the argument means +This gives the ``DiagnosticConsumer`` information about what the argument means without requiring it to use a specific presentation (consider this MVC for Clang :). @@ -319,6 +319,32 @@ they should be discussed before they are added. If you are creating a lot of repetitive diagnostics and/or have an idea for a useful formatter, please bring it up on the cfe-dev mailing list. +**"sub" format** + +Example: + Given the following record definition of type ``TextSubstitution``: + + .. code-block:: text + + def select_ovl_candidate : TextSubstitution< + "%select{function|constructor}0%select{| template| %2}1">; + + which can be used as + + .. code-block:: text + + def note_ovl_candidate : Note< + "candidate %sub{select_ovl_candidate}3,2,1 not viable">; + + and will act as if it was written + ``"candidate %select{function|constructor}3%select{| template| %1}2 not viable"``. +Description: + This format specifier is used to avoid repeating strings verbatim in multiple + diagnostics. The argument to ``%sub`` must name a ``TextSubstitution`` tblgen + record. The substitution must specify all arguments used by the substitution, + and the modifier indexes in the substitution are re-numbered accordingly. The + substituted text must itself be a valid format string before substitution. + .. _internals-producing-diag: Producing the Diagnostic @@ -387,7 +413,7 @@ exactly where those parentheses would be inserted into the source code. The fix-it hints themselves describe what changes to make to the source code in an abstract manner, which the text diagnostic printer renders as a line of "insertions" below the caret line. :ref:`Other diagnostic clients -<DiagnosticClient>` might choose to render the code differently (e.g., as +<DiagnosticConsumer>` might choose to render the code differently (e.g., as markup inline) or even give the user the ability to automatically fix the problem. @@ -420,26 +446,26 @@ Fix-it hints can be created with one of three constructors: Specifies that the code in the given source ``Range`` should be removed, and replaced with the given ``Code`` string. -.. _DiagnosticClient: +.. _DiagnosticConsumer: -The ``DiagnosticClient`` Interface -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The ``DiagnosticConsumer`` Interface +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Once code generates a diagnostic with all of the arguments and the rest of the relevant information, Clang needs to know what to do with it. As previously mentioned, the diagnostic machinery goes through some filtering to map a severity onto a diagnostic level, then (assuming the diagnostic is not mapped -to "``Ignore``") it invokes an object that implements the ``DiagnosticClient`` +to "``Ignore``") it invokes an object that implements the ``DiagnosticConsumer`` interface with the information. It is possible to implement this interface in many different ways. For -example, the normal Clang ``DiagnosticClient`` (named +example, the normal Clang ``DiagnosticConsumer`` (named ``TextDiagnosticPrinter``) turns the arguments into strings (according to the various formatting rules), prints out the file/line/column information and the string, then prints out the line of code, the source ranges, and the caret. However, this behavior isn't required. -Another implementation of the ``DiagnosticClient`` interface is the +Another implementation of the ``DiagnosticConsumer`` interface is the ``TextDiagnosticBuffer`` class, which is used when Clang is in ``-verify`` mode. Instead of formatting and printing out the diagnostics, this implementation just captures and remembers the diagnostics as they fly by. @@ -1638,15 +1664,15 @@ and then the semantic handling of the attribute. Parsing of the attribute is determined by the various syntactic forms attributes can take, such as GNU, C++11, and Microsoft style attributes, as well as other information provided by the table definition of the attribute. Ultimately, the -parsed representation of an attribute object is an ``AttributeList`` object. +parsed representation of an attribute object is an ``ParsedAttr`` object. These parsed attributes chain together as a list of parsed attributes attached to a declarator or declaration specifier. The parsing of attributes is handled automatically by Clang, except for attributes spelled as keywords. When implementing a keyword attribute, the parsing of the keyword and creation of the -``AttributeList`` object must be done manually. +``ParsedAttr`` object must be done manually. Eventually, ``Sema::ProcessDeclAttributeList()`` is called with a ``Decl`` and -an ``AttributeList``, at which point the parsed attribute can be transformed +an ``ParsedAttr``, at which point the parsed attribute can be transformed into a semantic attribute. The process by which a parsed attribute is converted into a semantic attribute depends on the attribute definition and semantic requirements of the attribute. The end result, however, is that the semantic @@ -1725,8 +1751,8 @@ 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>`_ +in `include/clang/Sema/ParsedAttr.h +<http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Sema/ParsedAttr.h?view=markup>`_ If a previously unused Decl node is added to the ``SubjectList``, 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>`_ @@ -1823,7 +1849,7 @@ Note that setting this member to 1 will opt out of common attribute semantic handling, requiring extra implementation efforts to ensure the attribute appertains to the appropriate subject, etc. -If the attribute should not be propagated from from a template declaration to an +If the attribute should not be propagated from a template declaration to an instantiation of the template, set the ``Clone`` member to 0. By default, all attributes will be cloned to template instantiations. @@ -1861,15 +1887,10 @@ requirements. To support this feature, an attribute inheriting from should be the same value between all arguments sharing a spelling, and corresponds to the parsed attribute's ``Kind`` enumerator. This allows attributes to share a parsed attribute kind, but have distinct semantic -attribute classes. For instance, ``AttributeList::AT_Interrupt`` is the shared +attribute classes. For instance, ``ParsedAttr`` 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), set diff --git a/docs/LTOVisibility.rst b/docs/LTOVisibility.rst index e1372d667a1a..ed15d8d78678 100644 --- a/docs/LTOVisibility.rst +++ b/docs/LTOVisibility.rst @@ -11,9 +11,9 @@ linkage unit's LTO unit is empty. Each linkage unit has only a single LTO unit. The LTO visibility of a class is used by the compiler to determine which classes the whole-program devirtualization (``-fwhole-program-vtables``) and -control flow integrity (``-fsanitize=cfi-vcall``) features apply to. These -features use whole-program information, so they require the entire class -hierarchy to be visible in order to work correctly. +control flow integrity (``-fsanitize=cfi-vcall`` and ``-fsanitize=cfi-mfcall``) +features apply to. These features use whole-program information, so they +require the entire class hierarchy to be visible in order to work correctly. If any translation unit in the program uses either of the whole-program devirtualization or control flow integrity features, it is effectively an ODR diff --git a/docs/LanguageExtensions.rst b/docs/LanguageExtensions.rst index 9b407f31d973..1aef265a8589 100644 --- a/docs/LanguageExtensions.rst +++ b/docs/LanguageExtensions.rst @@ -1096,6 +1096,11 @@ The following type trait primitives are supported by Clang: * ``__is_constructible`` (MSVC 2013, clang) * ``__is_nothrow_constructible`` (MSVC 2013, clang) * ``__is_assignable`` (MSVC 2015, clang) +* ``__reference_binds_to_temporary(T, U)`` (Clang): Determines whether a + reference of type ``T`` bound to an expression of type ``U`` would bind to a + materialized temporary object. If ``T`` is not a reference type the result + is false. Note this trait will also return false when the initialization of + ``T`` from ``U`` is ill-formed. Blocks ====== @@ -1186,12 +1191,59 @@ Automatic reference counting Clang provides support for :doc:`automated reference counting <AutomaticReferenceCounting>` in Objective-C, which eliminates the need -for manual ``retain``/``release``/``autorelease`` message sends. There are two +for manual ``retain``/``release``/``autorelease`` message sends. There are three feature macros associated with automatic reference counting: ``__has_feature(objc_arc)`` indicates the availability of automated reference counting in general, while ``__has_feature(objc_arc_weak)`` indicates that automated reference counting also includes support for ``__weak`` pointers to -Objective-C objects. +Objective-C objects. ``__has_feature(objc_arc_fields)`` indicates that C structs +are allowed to have fields that are pointers to Objective-C objects managed by +automatic reference counting. + +.. _objc-weak: + +Weak references +--------------- + +Clang supports ARC-style weak and unsafe references in Objective-C even +outside of ARC mode. Weak references must be explicitly enabled with +the ``-fobjc-weak`` option; use ``__has_feature((objc_arc_weak))`` +to test whether they are enabled. Unsafe references are enabled +unconditionally. ARC-style weak and unsafe references cannot be used +when Objective-C garbage collection is enabled. + +Except as noted below, the language rules for the ``__weak`` and +``__unsafe_unretained`` qualifiers (and the ``weak`` and +``unsafe_unretained`` property attributes) are just as laid out +in the :doc:`ARC specification <AutomaticReferenceCounting>`. +In particular, note that some classes do not support forming weak +references to their instances, and note that special care must be +taken when storing weak references in memory where initialization +and deinitialization are outside the responsibility of the compiler +(such as in ``malloc``-ed memory). + +Loading from a ``__weak`` variable always implicitly retains the +loaded value. In non-ARC modes, this retain is normally balanced +by an implicit autorelease. This autorelease can be suppressed +by performing the load in the receiver position of a ``-retain`` +message send (e.g. ``[weakReference retain]``); note that this performs +only a single retain (the retain done when primitively loading from +the weak reference). + +For the most part, ``__unsafe_unretained`` in non-ARC modes is just the +default behavior of variables and therefore is not needed. However, +it does have an effect on the semantics of block captures: normally, +copying a block which captures an Objective-C object or block pointer +causes the captured pointer to be retained or copied, respectively, +but that behavior is suppressed when the captured variable is qualified +with ``__unsafe_unretained``. + +Note that the ``__weak`` qualifier formerly meant the GC qualifier in +all non-ARC modes and was silently ignored outside of GC modes. It now +means the ARC-style qualifier in all non-GC modes and is no longer +allowed if not enabled by either ``-fobjc-arc`` or ``-fobjc-weak``. +It is expected that ``-fobjc-weak`` will eventually be enabled by default +in all non-GC Objective-C modes. .. _objc-fixed-enum: @@ -1968,6 +2020,32 @@ is disallowed in general). Support for constant expression evaluation for the above builtins be detected with ``__has_feature(cxx_constexpr_string_builtins)``. +Atomic Min/Max builtins with memory ordering +-------------------------------------------- + +There are two atomic builtins with min/max in-memory comparison and swap. +The syntax and semantics are similar to GCC-compatible __atomic_* builtins. + +* ``__atomic_fetch_min`` +* ``__atomic_fetch_max`` + +The builtins work with signed and unsigned integers and require to specify memory ordering. +The return value is the original value that was stored in memory before comparison. + +Example: + +.. code-block:: c + + unsigned int val = __atomic_fetch_min(unsigned int *pi, unsigned int ui, __ATOMIC_RELAXED); + +The third argument is one of the memory ordering specifiers ``__ATOMIC_RELAXED``, +``__ATOMIC_CONSUME``, ``__ATOMIC_ACQUIRE``, ``__ATOMIC_RELEASE``, +``__ATOMIC_ACQ_REL``, or ``__ATOMIC_SEQ_CST`` following C++11 memory model semantics. + +In terms or aquire-release ordering barriers these two operations are always +considered as operations with *load-store* semantics, even when the original value +is not actually modified after comparison. + .. _langext-__c11_atomic: __c11_atomic builtins @@ -2720,3 +2798,10 @@ The ``#pragma clang section`` directive obeys the following rules: * The decision about which section-kind applies to each global is taken in the back-end. Once the section-kind is known, appropriate section name, as specified by the user using ``#pragma clang section`` directive, is applied to that global. + +Specifying Linker Options on ELF Targets +======================================== + +The ``#pragma comment(lib, ...)`` directive is supported on all ELF targets. +The second parameter is the library name (without the traditional Unix prefix of +``lib``). This allows you to provide an implicit link of dependent libraries. diff --git a/docs/LibASTMatchersReference.html b/docs/LibASTMatchersReference.html index ed1ec193d8df..cf32a5ce4a0f 100644 --- a/docs/LibASTMatchersReference.html +++ b/docs/LibASTMatchersReference.html @@ -124,6 +124,18 @@ accessSpecDecl() </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('blockDecl0')"><a name="blockDecl0Anchor">blockDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BlockDecl.html">BlockDecl</a>>...</td></tr> +<tr><td colspan="4" class="doc" id="blockDecl0"><pre>Matches block declarations. + +Example matches the declaration of the nameless block printing an input +integer. + + myFunc(^(int p) { + printf("%d", p); + }) +</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('classTemplateDecl0')"><a name="classTemplateDecl0Anchor">classTemplateDecl</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ClassTemplateDecl.html">ClassTemplateDecl</a>>...</td></tr> <tr><td colspan="4" class="doc" id="classTemplateDecl0"><pre>Matches C++ class template declarations. @@ -650,6 +662,18 @@ Example matches __atomic_load_n(ptr, 1) </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('autoreleasePoolStmt0')"><a name="autoreleasePoolStmt0Anchor">autoreleasePoolStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ObjCAutoreleasePoolStmt.html">ObjCAutoreleasePoolStmt</a>>...</td></tr> +<tr><td colspan="4" class="doc" id="autoreleasePoolStmt0"><pre>Matches an Objective-C autorelease pool statement. + +Given + @autoreleasepool { + int x = 0; + } +autoreleasePoolStmt(stmt()) matches the declaration of "x" +inside the autorelease pool. +</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('binaryConditionalOperator0')"><a name="binaryConditionalOperator0Anchor">binaryConditionalOperator</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BinaryConditionalOperator.html">BinaryConditionalOperator</a>>...</td></tr> <tr><td colspan="4" class="doc" id="binaryConditionalOperator0"><pre>Matches binary conditional operator expressions (GNU extension). @@ -700,7 +724,7 @@ Example matches x.y() and y() Given switch(a) { case 42: break; default: break; } caseStmt() - matches 'case 42: break;'. + matches 'case 42:'. </pre></td></tr> @@ -741,7 +765,7 @@ Example match: {1}, (1, 2) <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('compoundStmt0')"><a name="compoundStmt0Anchor">compoundStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CompoundStmt.html">CompoundStmt</a>>...</td></tr> <tr><td colspan="4" class="doc" id="compoundStmt0"><pre>Matches compound statements. -Example matches '{}' and '{{}}'in 'for (;;) {{}}' +Example matches '{}' and '{{}}' in 'for (;;) {{}}' for (;;) {{}} </pre></td></tr> @@ -1028,7 +1052,7 @@ declStmt() Given switch(a) { case 42: break; default: break; } defaultStmt() - matches 'default: break;'. + matches 'default:'. </pre></td></tr> @@ -1197,9 +1221,9 @@ Example: Given materializeTemporaryExpr() matches 'f()' in these statements T u(f()); g(f()); + f().func(); but does not match f(); - f().func(); </pre></td></tr> @@ -1243,6 +1267,20 @@ Example matches @finally </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('objcIvarRefExpr0')"><a name="objcIvarRefExpr0Anchor">objcIvarRefExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ObjCIvarRefExpr.html">ObjCIvarRefExpr</a>>...</td></tr> +<tr><td colspan="4" class="doc" id="objcIvarRefExpr0"><pre>Matches a reference to an ObjCIvar. + +Example: matches "a" in "init" method: +@implementation A { + NSString *a; +} +- (void) init { + a = @"hello"; +} +} +</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('objcMessageExpr0')"><a name="objcMessageExpr0Anchor">objcMessageExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ObjCMessageExpr.html">ObjCMessageExpr</a>>...</td></tr> <tr><td colspan="4" class="doc" id="objcMessageExpr0"><pre>Matches ObjectiveC Message invocation expressions. @@ -1255,10 +1293,9 @@ NSString's "alloc". This matcher should match both message sends. <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('objcThrowStmt0')"><a name="objcThrowStmt0Anchor">objcThrowStmt</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ObjCAtThrowStmt.html">ObjCAtThrowStmt</a>>...</td></tr> -<tr><td colspan="4" class="doc" id="objcThrowStmt0"><pre>Matches Objective-C @throw statements. +<tr><td colspan="4" class="doc" id="objcThrowStmt0"><pre>Matches Objective-C statements. -Example matches @throw - @throw obj; +Example matches @throw obj; </pre></td></tr> @@ -1370,7 +1407,7 @@ substNonTypeTemplateParmExpr() Given switch(a) { case 42: break; default: break; } switchCase() - matches 'case 42: break;' and 'default: break;'. + matches 'case 42:' and 'default:'. </pre></td></tr> @@ -1554,6 +1591,18 @@ Example matches i[1]. </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('decltypeType0')"><a name="decltypeType0Anchor">decltypeType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DecltypeType.html">DecltypeType</a>>...</td></tr> +<tr><td colspan="4" class="doc" id="decltypeType0"><pre>Matches types nodes representing C++11 decltype(<expr>) types. + +Given: + short i = 1; + int j = 42; + decltype(i + j) result = i + j; +decltypeType() + matches "decltype(i + j)" +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td><td class="name" onclick="toggle('dependentSizedArrayType0')"><a name="dependentSizedArrayType0Anchor">dependentSizedArrayType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DependentSizedArrayType.html">DependentSizedArrayType</a>>...</td></tr> <tr><td colspan="4" class="doc" id="dependentSizedArrayType0"><pre>Matches C++ arrays whose size is a value-dependent expression. @@ -1927,7 +1976,25 @@ Example matches a || b (matcher = binaryOperator(hasOperatorName("||"))) </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXBoolLiteralExpr.html">CXXBoolLiteralExpr</a>></td><td class="name" onclick="toggle('equals2')"><a name="equals2Anchor">equals</a></td><td>ValueT Value</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BinaryOperator.html">BinaryOperator</a>></td><td class="name" onclick="toggle('isAssignmentOperator0')"><a name="isAssignmentOperator0Anchor">isAssignmentOperator</a></td><td></td></tr> +<tr><td colspan="4" class="doc" id="isAssignmentOperator0"><pre>Matches all kinds of assignment operators. + +Example 1: matches a += b (matcher = binaryOperator(isAssignmentOperator())) + if (a == b) + a += b; + +Example 2: matches s1 = s2 + (matcher = cxxOperatorCallExpr(isAssignmentOperator())) + struct S { S& operator=(const S&); }; + void x() { S s1, s2; s1 = s2; }) +</pre></td></tr> + + +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXBoolLiteralExpr.html">CXXBoolLiteralExpr</a>></td><td class="name" onclick="toggle('equals5')"><a name="equals5Anchor">equals</a></td><td>bool Value</td></tr> +<tr><td colspan="4" class="doc" id="equals5"><pre></pre></td></tr> + + +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXBoolLiteralExpr.html">CXXBoolLiteralExpr</a>></td><td class="name" onclick="toggle('equals2')"><a name="equals2Anchor">equals</a></td><td>const ValueT Value</td></tr> <tr><td colspan="4" class="doc" id="equals2"><pre>Matches literals that are equal to the given value of type ValueT. Given @@ -1953,10 +2020,6 @@ Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Chara </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXBoolLiteralExpr.html">CXXBoolLiteralExpr</a>></td><td class="name" onclick="toggle('equals5')"><a name="equals5Anchor">equals</a></td><td>bool Value</td></tr> -<tr><td colspan="4" class="doc" id="equals5"><pre></pre></td></tr> - - <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXBoolLiteralExpr.html">CXXBoolLiteralExpr</a>></td><td class="name" onclick="toggle('equals11')"><a name="equals11Anchor">equals</a></td><td>double Value</td></tr> <tr><td colspan="4" class="doc" id="equals11"><pre></pre></td></tr> @@ -2307,6 +2370,20 @@ Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXOp </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXOperatorCallExpr.html">CXXOperatorCallExpr</a>></td><td class="name" onclick="toggle('isAssignmentOperator1')"><a name="isAssignmentOperator1Anchor">isAssignmentOperator</a></td><td></td></tr> +<tr><td colspan="4" class="doc" id="isAssignmentOperator1"><pre>Matches all kinds of assignment operators. + +Example 1: matches a += b (matcher = binaryOperator(isAssignmentOperator())) + if (a == b) + a += b; + +Example 2: matches s1 = s2 + (matcher = cxxOperatorCallExpr(isAssignmentOperator())) + struct S { S& operator=(const S&); }; + void x() { S s1, s2; s1 = s2; }) +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>></td><td class="name" onclick="toggle('hasDefinition0')"><a name="hasDefinition0Anchor">hasDefinition</a></td><td></td></tr> <tr><td colspan="4" class="doc" id="hasDefinition0"><pre>Matches a class declaration that is defined. @@ -2377,6 +2454,8 @@ Given template <typename T> class X {}; class A {}; X<A> x; or template <typename T> class X {}; class A {}; template class X<A>; +or + template <typename T> class X {}; class A {}; extern template class X<A>; cxxRecordDecl(hasName("::X"), isTemplateInstantiation()) matches the template instantiation of X<A>. @@ -2409,7 +2488,11 @@ Example: matches the implicit cast around 0 </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CharacterLiteral.html">CharacterLiteral</a>></td><td class="name" onclick="toggle('equals3')"><a name="equals3Anchor">equals</a></td><td>ValueT Value</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CharacterLiteral.html">CharacterLiteral</a>></td><td class="name" onclick="toggle('equals4')"><a name="equals4Anchor">equals</a></td><td>bool Value</td></tr> +<tr><td colspan="4" class="doc" id="equals4"><pre></pre></td></tr> + + +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CharacterLiteral.html">CharacterLiteral</a>></td><td class="name" onclick="toggle('equals3')"><a name="equals3Anchor">equals</a></td><td>const ValueT Value</td></tr> <tr><td colspan="4" class="doc" id="equals3"><pre>Matches literals that are equal to the given value of type ValueT. Given @@ -2435,10 +2518,6 @@ Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Chara </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CharacterLiteral.html">CharacterLiteral</a>></td><td class="name" onclick="toggle('equals4')"><a name="equals4Anchor">equals</a></td><td>bool Value</td></tr> -<tr><td colspan="4" class="doc" id="equals4"><pre></pre></td></tr> - - <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CharacterLiteral.html">CharacterLiteral</a>></td><td class="name" onclick="toggle('equals10')"><a name="equals10Anchor">equals</a></td><td>double Value</td></tr> <tr><td colspan="4" class="doc" id="equals10"><pre></pre></td></tr> @@ -2645,6 +2724,15 @@ designatorCountIs(2) </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumDecl.html">EnumDecl</a>></td><td class="name" onclick="toggle('isScoped0')"><a name="isScoped0Anchor">isScoped</a></td><td></td></tr> +<tr><td colspan="4" class="doc" id="isScoped0"><pre>Matches C++11 scoped enum declaration. + +Example matches Y (matcher = enumDecl(isScoped())) +enum X {}; +enum class Y {}; +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FieldDecl.html">FieldDecl</a>></td><td class="name" onclick="toggle('hasBitWidth0')"><a name="hasBitWidth0Anchor">hasBitWidth</a></td><td>unsigned Width</td></tr> <tr><td colspan="4" class="doc" id="hasBitWidth0"><pre>Matches non-static data members that are bit-fields of the specified bit width. @@ -2673,7 +2761,7 @@ fieldDecl(isBitField()) </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FloatingLiteral.html">FloatingLiteral</a>></td><td class="name" onclick="toggle('equals1')"><a name="equals1Anchor">equals</a></td><td>ValueT Value</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FloatingLiteral.html">FloatingLiteral</a>></td><td class="name" onclick="toggle('equals1')"><a name="equals1Anchor">equals</a></td><td>const ValueT Value</td></tr> <tr><td colspan="4" class="doc" id="equals1"><pre>Matches literals that are equal to the given value of type ValueT. Given @@ -2741,16 +2829,29 @@ Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXOp </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('hasTrailingReturn0')"><a name="hasTrailingReturn0Anchor">hasTrailingReturn</a></td><td></td></tr> +<tr><td colspan="4" class="doc" id="hasTrailingReturn0"><pre>Matches a function declared with a trailing return type. + +Example matches Y (matcher = functionDecl(hasTrailingReturn())) +int X() {} +auto Y() -> int {} +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('isConstexpr1')"><a name="isConstexpr1Anchor">isConstexpr</a></td><td></td></tr> -<tr><td colspan="4" class="doc" id="isConstexpr1"><pre>Matches constexpr variable and function declarations. +<tr><td colspan="4" class="doc" id="isConstexpr1"><pre>Matches constexpr variable and function declarations, + and if constexpr. Given: constexpr int foo = 42; constexpr int bar(); + void baz() { if constexpr(1 > 0) {} } varDecl(isConstexpr()) matches the declaration of foo. functionDecl(isConstexpr()) matches the declaration of bar. +ifStmt(isConstexpr()) + matches the if statement in baz. </pre></td></tr> @@ -2811,6 +2912,7 @@ functionDecl(isExplicitTemplateSpecialization()) Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>> </pre></td></tr> + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('isExternC0')"><a name="isExternC0Anchor">isExternC</a></td><td></td></tr> <tr><td colspan="4" class="doc" id="isExternC0"><pre>Matches extern "C" function or variable declarations. @@ -2827,6 +2929,7 @@ varDecl(isExternC()) matches the declaration of x and y, but not the declaration of z. </pre></td></tr> + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('isInline1')"><a name="isInline1Anchor">isInline</a></td><td></td></tr> <tr><td colspan="4" class="doc" id="isInline1"><pre>Matches function and namespace declarations that are marked with the inline keyword. @@ -2842,6 +2945,26 @@ namespaceDecl(isInline()) will match n::m. </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('isMain0')"><a name="isMain0Anchor">isMain</a></td><td></td></tr> +<tr><td colspan="4" class="doc" id="isMain0"><pre>Determines whether the function is "main", which is the entry point +into an executable program. +</pre></td></tr> + + +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('isNoReturn0')"><a name="isNoReturn0Anchor">isNoReturn</a></td><td></td></tr> +<tr><td colspan="4" class="doc" id="isNoReturn0"><pre>Matches FunctionDecls that have a noreturn attribute. + +Given + void nope(); + [[noreturn]] void a(); + __attribute__((noreturn)) void b(); + struct c { [[noreturn]] c(); }; +functionDecl(isNoReturn()) + matches all of those except + void nope(); +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('isNoThrow0')"><a name="isNoThrow0Anchor">isNoThrow</a></td><td></td></tr> <tr><td colspan="4" class="doc" id="isNoThrow0"><pre>Matches functions that have a non-throwing exception specification. @@ -2880,6 +3003,8 @@ Given template <typename T> class X {}; class A {}; X<A> x; or template <typename T> class X {}; class A {}; template class X<A>; +or + template <typename T> class X {}; class A {}; extern template class X<A>; cxxRecordDecl(hasName("::X"), isTemplateInstantiation()) matches the template instantiation of X<A>. @@ -2916,11 +3041,11 @@ Given void j(int i); void k(int x, int y, int z, ...); functionDecl(parameterCountIs(2)) - matches void g(int i, int j) {} + matches g and h functionProtoType(parameterCountIs(2)) - matches void h(int i, int j) + matches g and h functionProtoType(parameterCountIs(3)) - matches void k(int x, int y, int z, ...); + matches k </pre></td></tr> @@ -2966,15 +3091,36 @@ Given void j(int i); void k(int x, int y, int z, ...); functionDecl(parameterCountIs(2)) - matches void g(int i, int j) {} + matches g and h functionProtoType(parameterCountIs(2)) - matches void h(int i, int j) + matches g and h functionProtoType(parameterCountIs(3)) - matches void k(int x, int y, int z, ...); + matches k +</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('isConstexpr2')"><a name="isConstexpr2Anchor">isConstexpr</a></td><td></td></tr> +<tr><td colspan="4" class="doc" id="isConstexpr2"><pre>Matches constexpr variable and function declarations, + and if constexpr. + +Given: + constexpr int foo = 42; + constexpr int bar(); + void baz() { if constexpr(1 > 0) {} } +varDecl(isConstexpr()) + matches the declaration of foo. +functionDecl(isConstexpr()) + matches the declaration of bar. +ifStmt(isConstexpr()) + matches the if statement in baz. </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>></td><td class="name" onclick="toggle('equals0')"><a name="equals0Anchor">equals</a></td><td>ValueT Value</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>></td><td class="name" onclick="toggle('equals6')"><a name="equals6Anchor">equals</a></td><td>bool Value</td></tr> +<tr><td colspan="4" class="doc" id="equals6"><pre></pre></td></tr> + + +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>></td><td class="name" onclick="toggle('equals0')"><a name="equals0Anchor">equals</a></td><td>const ValueT Value</td></tr> <tr><td colspan="4" class="doc" id="equals0"><pre>Matches literals that are equal to the given value of type ValueT. Given @@ -3000,10 +3146,6 @@ Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Chara </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>></td><td class="name" onclick="toggle('equals6')"><a name="equals6Anchor">equals</a></td><td>bool Value</td></tr> -<tr><td colspan="4" class="doc" id="equals6"><pre></pre></td></tr> - - <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>></td><td class="name" onclick="toggle('equals13')"><a name="equals13Anchor">equals</a></td><td>double Value</td></tr> <tr><td colspan="4" class="doc" id="equals13"><pre></pre></td></tr> @@ -3049,7 +3191,7 @@ void f() {} </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NamedDecl.html">NamedDecl</a>></td><td class="name" onclick="toggle('hasName0')"><a name="hasName0Anchor">hasName</a></td><td>std::string Name</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1NamedDecl.html">NamedDecl</a>></td><td class="name" onclick="toggle('hasName0')"><a name="hasName0Anchor">hasName</a></td><td>const std::string Name</td></tr> <tr><td colspan="4" class="doc" id="hasName0"><pre>Matches NamedDecl nodes that have the specified name. Supports specifying enclosing namespaces or classes by prefixing the name @@ -3158,6 +3300,19 @@ represent an error condition in the tree! </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ObjCMessageExpr.html">ObjCMessageExpr</a>></td><td class="name" onclick="toggle('isInstanceMessage0')"><a name="isInstanceMessage0Anchor">isInstanceMessage</a></td><td></td></tr> +<tr><td colspan="4" class="doc" id="isInstanceMessage0"><pre>Returns true when the Objective-C message is sent to an instance. + +Example +matcher = objcMessagaeExpr(isInstanceMessage()) +matches + NSString *x = @"hello"; + [x containsString:@"h"]; +but not + [NSString stringWithFormat:@"format"]; +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ObjCMessageExpr.html">ObjCMessageExpr</a>></td><td class="name" onclick="toggle('matchesSelector0')"><a name="matchesSelector0Anchor">matchesSelector</a></td><td>std::string RegExp</td></tr> <tr><td colspan="4" class="doc" id="matchesSelector0"><pre>Matches ObjC selectors whose name contains a substring matched by the given RegExp. @@ -3510,7 +3665,7 @@ an arbitrary precision integer. 'Value' must be euqal to the canonical representation of that integral value in base 10. Given - template<int T> struct A {}; + template<int T> struct C {}; C<42> c; classTemplateSpecializationDecl( hasAnyTemplateArgument(equalsIntegralValue("42"))) @@ -3522,7 +3677,7 @@ classTemplateSpecializationDecl( <tr><td colspan="4" class="doc" id="isIntegral0"><pre>Matches a TemplateArgument that is an integral value. Given - template<int T> struct A {}; + template<int T> struct C {}; C<42> c; classTemplateSpecializationDecl( hasAnyTemplateArgument(isIntegral())) @@ -3738,15 +3893,19 @@ int a; <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>></td><td class="name" onclick="toggle('isConstexpr0')"><a name="isConstexpr0Anchor">isConstexpr</a></td><td></td></tr> -<tr><td colspan="4" class="doc" id="isConstexpr0"><pre>Matches constexpr variable and function declarations. +<tr><td colspan="4" class="doc" id="isConstexpr0"><pre>Matches constexpr variable and function declarations, + and if constexpr. Given: constexpr int foo = 42; constexpr int bar(); + void baz() { if constexpr(1 > 0) {} } varDecl(isConstexpr()) matches the declaration of foo. functionDecl(isConstexpr()) matches the declaration of bar. +ifStmt(isConstexpr()) + matches the if statement in baz. </pre></td></tr> @@ -3798,6 +3957,7 @@ functionDecl(isExplicitTemplateSpecialization()) Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXRecordDecl.html">CXXRecordDecl</a>> </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('isExternC1')"><a name="isExternC1Anchor">isExternC</a></td><td></td></tr> <tr><td colspan="4" class="doc" id="isExternC1"><pre>Matches extern "C" function or variable declarations. @@ -3814,6 +3974,7 @@ varDecl(isExternC()) matches the declaration of x and y, but not the declaration of 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('isStaticStorageClass1')"><a name="isStaticStorageClass1Anchor">isStaticStorageClass</a></td><td></td></tr> <tr><td colspan="4" class="doc" id="isStaticStorageClass1"><pre>Matches variablefunction declarations that have "static" storage class specifier ("static" keyword) written in the source. @@ -3838,6 +3999,8 @@ Given template <typename T> class X {}; class A {}; X<A> x; or template <typename T> class X {}; class A {}; template class X<A>; +or + template <typename T> class X {}; class A {}; extern template class X<A>; cxxRecordDecl(hasName("::X"), isTemplateInstantiation()) matches the template instantiation of X<A>. @@ -3891,6 +4054,17 @@ This matcher is only provided as a performance optimization of hasName. </pre></td></tr> +<tr><td>Matcher<internal::Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ObjCMessageExpr.html">ObjCMessageExpr</a>>></td><td class="name" onclick="toggle('hasAnySelector0')"><a name="hasAnySelector0Anchor">hasAnySelector</a></td><td>StringRef, ..., StringRef</td></tr> +<tr><td colspan="4" class="doc" id="hasAnySelector0"><pre>Matches when at least one of the supplied string equals to the +Selector.getAsString() + + matcher = objCMessageExpr(hasSelector("methodA:", "methodB:")); + matches both of the expressions below: + [myObj methodA:argA]; + [myObj methodB:argB]; +</pre></td></tr> + + <tr><td>Matcher<internal::Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>>></td><td class="name" onclick="toggle('isInTemplateInstantiation0')"><a name="isInTemplateInstantiation0Anchor">isInTemplateInstantiation</a></td><td></td></tr> <tr><td colspan="4" class="doc" id="isInTemplateInstantiation0"><pre>Matches statements inside of a template instantiation. @@ -3947,10 +4121,11 @@ Usable as: Any Matcher <tr><td colspan="4" class="doc" id="forEachDescendant0"><pre>Matches AST nodes that have descendant AST nodes that match the provided matcher. -Example matches X, A, B, C +Example matches X, A, A::X, B, B::C, B::C::X (matcher = cxxRecordDecl(forEachDescendant(cxxRecordDecl(hasName("X"))))) - class X {}; Matches X, because X::X is a class of name X inside X. - class A { class X {}; }; + class X {}; + class A { class X {}; }; Matches A, because A::X is a class of name + X inside A. class B { class C { class X {}; }; }; DescendantT must be an AST base type. @@ -3973,10 +4148,11 @@ Usable as: Any Matcher <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 +Example matches X, Y, Y::X, Z::Y, Z::Y::X (matcher = cxxRecordDecl(forEach(cxxRecordDecl(hasName("X"))) - class X {}; Matches X, because X::X is a class of name X inside X. - class Y { class X {}; }; + class X {}; + class Y { class X {}; }; Matches Y, because Y::X is a class of name X + inside Y. class Z { class Y { class X {}; }; }; Does not match Z. ChildT must be an AST base type. @@ -4079,7 +4255,7 @@ Example 2 (conditional binary operator): matches opaqueValueExpr(condition) </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>></td><td class="name" onclick="toggle('hasDeclaration15')"><a name="hasDeclaration15Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>></td><td class="name" onclick="toggle('hasDeclaration15')"><a name="hasDeclaration15Anchor">hasDeclaration</a></td><td>const Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> <tr><td colspan="4" class="doc" id="hasDeclaration15"><pre>Matches a node if the declaration associated with that node matches the given matcher. @@ -4089,9 +4265,19 @@ The associated declaration is: - for MemberExpr, the declaration of the referenced member - for CXXConstructExpr, the declaration of the constructor - for CXXNewExpr, the declaration of the operator new +- for ObjCIvarExpr, the declaration of the ivar -Also usable as Matcher<T> for any T supporting the getDecl() member -function. e.g. various subtypes of clang::Type and various expressions. +For type nodes, hasDeclaration will generally match the declaration of the +sugared type. Given + class X {}; + typedef X Y; + Y y; +in varDecl(hasType(hasDeclaration(decl()))) the decl will match the +typedefDecl. A common use case is to match the underlying, desugared type. +This can be achieved by using the hasUnqualifiedDesugaredType matcher: + varDecl(hasType(hasUnqualifiedDesugaredType( + recordType(hasDeclaration(decl()))))) +In this matcher, the decl will match the CXXRecordDecl of class X. Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, 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_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, @@ -4214,7 +4400,7 @@ Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AutoT </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BinaryOperator.html">BinaryOperator</a>></td><td class="name" onclick="toggle('hasEitherOperand0')"><a name="hasEitherOperand0Anchor">hasEitherOperand</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BinaryOperator.html">BinaryOperator</a>></td><td class="name" onclick="toggle('hasEitherOperand0')"><a name="hasEitherOperand0Anchor">hasEitherOperand</a></td><td>const Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr> <tr><td colspan="4" class="doc" id="hasEitherOperand0"><pre>Matches if either the left hand side or the right hand side of a binary operator matches. </pre></td></tr> @@ -4236,6 +4422,55 @@ Example matches b (matcher = binaryOperator(hasRHS())) </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BlockDecl.html">BlockDecl</a>></td><td class="name" onclick="toggle('hasAnyParameter2')"><a name="hasAnyParameter2Anchor">hasAnyParameter</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ParmVarDecl.html">ParmVarDecl</a>> InnerMatcher</td></tr> +<tr><td colspan="4" class="doc" id="hasAnyParameter2"><pre>Matches any parameter of a function or an ObjC method declaration or a +block. + +Does not match the 'this' parameter of a method. + +Given + class X { void f(int x, int y, int z) {} }; +cxxMethodDecl(hasAnyParameter(hasName("y"))) + matches f(int x, int y, int z) {} +with hasAnyParameter(...) + matching int y + +For ObjectiveC, given + @interface I - (void) f:(int) y; @end + +the matcher objcMethodDecl(hasAnyParameter(hasName("y"))) +matches the declaration of method f with hasParameter +matching y. + +For blocks, given + b = ^(int y) { printf("%d", y) }; + +the matcher blockDecl(hasAnyParameter(hasName("y"))) +matches the declaration of the block b with hasParameter +matching y. +</pre></td></tr> + + +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BlockDecl.html">BlockDecl</a>></td><td class="name" onclick="toggle('hasParameter2')"><a name="hasParameter2Anchor">hasParameter</a></td><td>unsigned N, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ParmVarDecl.html">ParmVarDecl</a>> InnerMatcher</td></tr> +<tr><td colspan="4" class="doc" id="hasParameter2"><pre>Matches the n'th parameter of a function or an ObjC method +declaration or a block. + +Given + class X { void f(int x) {} }; +cxxMethodDecl(hasParameter(0, hasType(varDecl()))) + matches f(int x) {} +with hasParameter(...) + matching int x + +For ObjectiveC, given + @interface I - (void) f:(int) y; @end + +the matcher objcMethodDecl(hasParameter(0, hasName("y"))) +matches the declaration of method f with hasParameter +matching y. +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1BlockPointerTypeLoc.html">BlockPointerTypeLoc</a>></td><td class="name" onclick="toggle('pointeeLoc0')"><a name="pointeeLoc0Anchor">pointeeLoc</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>></td></tr> <tr><td colspan="4" class="doc" id="pointeeLoc0"><pre>Narrows PointerType (and similar) matchers to those where the pointee matches a given matcher. @@ -4290,7 +4525,7 @@ and parmVarDecl(...) <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>></td><td class="name" onclick="toggle('hasAnyArgument1')"><a name="hasAnyArgument1Anchor">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="hasAnyArgument1"><pre>Matches any argument of a call expression or a constructor call -expression. +expression, or an ObjC-message-send expression. Given void x(int, int, int) { int y; x(1, y, 42); } @@ -4298,6 +4533,12 @@ callExpr(hasAnyArgument(declRefExpr())) matches x(1, y, 42) with hasAnyArgument(...) matching y + +For ObjectiveC, given + @interface I - (void) f:(int) y; @end + void foo(I *i) { [i f:12]; } +objcMessageExpr(hasAnyArgument(integerLiteral(equals(12)))) + matches [i f:12] </pre></td></tr> @@ -4311,7 +4552,7 @@ Example matches y in x(y) </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>></td><td class="name" onclick="toggle('hasDeclaration13')"><a name="hasDeclaration13Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>></td><td class="name" onclick="toggle('hasDeclaration13')"><a name="hasDeclaration13Anchor">hasDeclaration</a></td><td>const Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> <tr><td colspan="4" class="doc" id="hasDeclaration13"><pre>Matches a node if the declaration associated with that node matches the given matcher. @@ -4321,9 +4562,19 @@ The associated declaration is: - for MemberExpr, the declaration of the referenced member - for CXXConstructExpr, the declaration of the constructor - for CXXNewExpr, the declaration of the operator new +- for ObjCIvarExpr, the declaration of the ivar -Also usable as Matcher<T> for any T supporting the getDecl() member -function. e.g. various subtypes of clang::Type and various expressions. +For type nodes, hasDeclaration will generally match the declaration of the +sugared type. Given + class X {}; + typedef X Y; + Y y; +in varDecl(hasType(hasDeclaration(decl()))) the decl will match the +typedefDecl. A common use case is to match the underlying, desugared type. +This can be achieved by using the hasUnqualifiedDesugaredType matcher: + varDecl(hasType(hasUnqualifiedDesugaredType( + recordType(hasDeclaration(decl()))))) +In this matcher, the decl will match the CXXRecordDecl of class X. Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, 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_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, @@ -4435,7 +4686,7 @@ matches 'a' in Example matches y.x() (matcher = cxxMemberCallExpr(on(hasType(cxxRecordDecl(hasName("Y")))))) class Y { public: void x(); }; - void z() { Y y; y.x(); }", + void z() { Y y; y.x(); } FIXME: Overload to allow directly matching types? </pre></td></tr> @@ -4453,7 +4704,7 @@ matcher, or is a pointer to a type that matches the InnerMatcher. <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>></td><td class="name" onclick="toggle('forEachOverridden0')"><a name="forEachOverridden0Anchor">forEachOverridden</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXMethodDecl.html">CXXMethodDecl</a>> InnerMatcher</td></tr> -<tr><td colspan="4" class="doc" id="forEachOverridden0"><pre>Matches each method overriden by the given method. This matcher may +<tr><td colspan="4" class="doc" id="forEachOverridden0"><pre>Matches each method overridden by the given method. This matcher may produce multiple matches. Given @@ -4505,7 +4756,7 @@ cxxNewExpr(hasArraySize(intgerLiteral(equals(10)))) </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>></td><td class="name" onclick="toggle('hasDeclaration12')"><a name="hasDeclaration12Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXNewExpr.html">CXXNewExpr</a>></td><td class="name" onclick="toggle('hasDeclaration12')"><a name="hasDeclaration12Anchor">hasDeclaration</a></td><td>const Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> <tr><td colspan="4" class="doc" id="hasDeclaration12"><pre>Matches a node if the declaration associated with that node matches the given matcher. @@ -4515,9 +4766,19 @@ The associated declaration is: - for MemberExpr, the declaration of the referenced member - for CXXConstructExpr, the declaration of the constructor - for CXXNewExpr, the declaration of the operator new +- for ObjCIvarExpr, the declaration of the ivar -Also usable as Matcher<T> for any T supporting the getDecl() member -function. e.g. various subtypes of clang::Type and various expressions. +For type nodes, hasDeclaration will generally match the declaration of the +sugared type. Given + class X {}; + typedef X Y; + Y y; +in varDecl(hasType(hasDeclaration(decl()))) the decl will match the +typedefDecl. A common use case is to match the underlying, desugared type. +This can be achieved by using the hasUnqualifiedDesugaredType matcher: + varDecl(hasType(hasUnqualifiedDesugaredType( + recordType(hasDeclaration(decl()))))) +In this matcher, the decl will match the CXXRecordDecl of class X. Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, 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_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, @@ -4619,7 +4880,7 @@ and parmVarDecl(...) <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. +expression, or an ObjC-message-send expression. Given void x(int, int, int) { int y; x(1, y, 42); } @@ -4627,6 +4888,12 @@ callExpr(hasAnyArgument(declRefExpr())) matches x(1, y, 42) with hasAnyArgument(...) matching y + +For ObjectiveC, given + @interface I - (void) f:(int) y; @end + void foo(I *i) { [i f:12]; } +objcMessageExpr(hasAnyArgument(integerLiteral(equals(12)))) + matches [i f:12] </pre></td></tr> @@ -4640,7 +4907,7 @@ Example matches y in x(y) </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('hasDeclaration14')"><a name="hasDeclaration14Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>></td><td class="name" onclick="toggle('hasDeclaration14')"><a name="hasDeclaration14Anchor">hasDeclaration</a></td><td>const Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> <tr><td colspan="4" class="doc" id="hasDeclaration14"><pre>Matches a node if the declaration associated with that node matches the given matcher. @@ -4650,9 +4917,19 @@ The associated declaration is: - for MemberExpr, the declaration of the referenced member - for CXXConstructExpr, the declaration of the constructor - for CXXNewExpr, the declaration of the operator new +- for ObjCIvarExpr, the declaration of the ivar -Also usable as Matcher<T> for any T supporting the getDecl() member -function. e.g. various subtypes of clang::Type and various expressions. +For type nodes, hasDeclaration will generally match the declaration of the +sugared type. Given + class X {}; + typedef X Y; + Y y; +in varDecl(hasType(hasDeclaration(decl()))) the decl will match the +typedefDecl. A common use case is to match the underlying, desugared type. +This can be achieved by using the hasUnqualifiedDesugaredType matcher: + varDecl(hasType(hasUnqualifiedDesugaredType( + recordType(hasDeclaration(decl()))))) +In this matcher, the decl will match the CXXRecordDecl of class X. Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, 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_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, @@ -4676,7 +4953,18 @@ caseStmt(hasCaseConstant(integerLiteral())) <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CastExpr.html">CastExpr</a>></td><td class="name" onclick="toggle('hasSourceExpression0')"><a name="hasSourceExpression0Anchor">hasSourceExpression</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="hasSourceExpression0"><pre></pre></td></tr> +<tr><td colspan="4" class="doc" id="hasSourceExpression0"><pre>Matches if the cast's source expression +or opaque value's source expression matches the given matcher. + +Example 1: matches "a string" +(matcher = castExpr(hasSourceExpression(cxxConstructExpr()))) +class URL { URL(string); }; +URL url = "a string"; + +Example 2: matches 'b' (matcher = +opaqueValueExpr(hasSourceExpression(implicitCastExpr(declRefExpr()))) +int a = b ?: 1; +</pre></td></tr> <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ClassTemplateSpecializationDecl.html">ClassTemplateSpecializationDecl</a>></td><td class="name" onclick="toggle('hasAnyTemplateArgument0')"><a name="hasAnyTemplateArgument0Anchor">hasAnyTemplateArgument</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TemplateArgument.html">TemplateArgument</a>> InnerMatcher</td></tr> @@ -4722,7 +5010,7 @@ Given A<bool, int> b; A<int, bool> c; - template<typename T> f() {}; + template<typename T> void f() {} void func() { f<int>(); }; classTemplateSpecializationDecl(hasTemplateArgument( 1, refersToType(asString("int")))) @@ -4781,7 +5069,7 @@ with compoundStmt() </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>></td><td class="name" onclick="toggle('hasDeclaration11')"><a name="hasDeclaration11Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>></td><td class="name" onclick="toggle('hasDeclaration11')"><a name="hasDeclaration11Anchor">hasDeclaration</a></td><td>const Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> <tr><td colspan="4" class="doc" id="hasDeclaration11"><pre>Matches a node if the declaration associated with that node matches the given matcher. @@ -4791,9 +5079,19 @@ The associated declaration is: - for MemberExpr, the declaration of the referenced member - for CXXConstructExpr, the declaration of the constructor - for CXXNewExpr, the declaration of the operator new +- for ObjCIvarExpr, the declaration of the ivar -Also usable as Matcher<T> for any T supporting the getDecl() member -function. e.g. various subtypes of clang::Type and various expressions. +For type nodes, hasDeclaration will generally match the declaration of the +sugared type. Given + class X {}; + typedef X Y; + Y y; +in varDecl(hasType(hasDeclaration(decl()))) the decl will match the +typedefDecl. A common use case is to match the underlying, desugared type. +This can be achieved by using the hasUnqualifiedDesugaredType matcher: + varDecl(hasType(hasUnqualifiedDesugaredType( + recordType(hasDeclaration(decl()))))) +In this matcher, the decl will match the CXXRecordDecl of class X. Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, 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_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, @@ -4889,6 +5187,19 @@ declaration of class D. </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DecltypeType.html">DecltypeType</a>></td><td class="name" onclick="toggle('hasUnderlyingType0')"><a name="hasUnderlyingType0Anchor">hasUnderlyingType</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Type.html">Type</a>></td></tr> +<tr><td colspan="4" class="doc" id="hasUnderlyingType0"><pre>Matches DecltypeType nodes to find out the underlying type. + +Given + decltype(1) a = 1; + decltype(2.0) b = 2.0; +decltypeType(hasUnderlyingType(isInteger())) + matches "auto a" + +Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DecltypeType.html">DecltypeType</a>> +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DoStmt.html">DoStmt</a>></td><td class="name" onclick="toggle('hasBody0')"><a name="hasBody0Anchor">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="hasBody0"><pre>Matches a 'for', 'while', 'do while' statement or a function definition that has a given body. @@ -4945,7 +5256,7 @@ declaration of d. </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>></td><td class="name" onclick="toggle('hasDeclaration10')"><a name="hasDeclaration10Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>></td><td class="name" onclick="toggle('hasDeclaration10')"><a name="hasDeclaration10Anchor">hasDeclaration</a></td><td>const Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> <tr><td colspan="4" class="doc" id="hasDeclaration10"><pre>Matches a node if the declaration associated with that node matches the given matcher. @@ -4955,9 +5266,19 @@ The associated declaration is: - for MemberExpr, the declaration of the referenced member - for CXXConstructExpr, the declaration of the constructor - for CXXNewExpr, the declaration of the operator new +- for ObjCIvarExpr, the declaration of the ivar -Also usable as Matcher<T> for any T supporting the getDecl() member -function. e.g. various subtypes of clang::Type and various expressions. +For type nodes, hasDeclaration will generally match the declaration of the +sugared type. Given + class X {}; + typedef X Y; + Y y; +in varDecl(hasType(hasDeclaration(decl()))) the decl will match the +typedefDecl. A common use case is to match the underlying, desugared type. +This can be achieved by using the hasUnqualifiedDesugaredType matcher: + varDecl(hasType(hasUnqualifiedDesugaredType( + recordType(hasDeclaration(decl()))))) +In this matcher, the decl will match the CXXRecordDecl of class X. Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, 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_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, @@ -4977,8 +5298,8 @@ actual casts "explicit" casts.) </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('hasType3')"><a name="hasType3Anchor">hasType</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="hasType3"><pre>Overloaded to match the declaration of the expression's or value +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>></td><td class="name" onclick="toggle('hasType4')"><a name="hasType4Anchor">hasType</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="hasType4"><pre>Overloaded to match the declaration of the expression's or value declaration's type. In case of a value declaration (for example a variable declaration), @@ -4989,8 +5310,10 @@ declaration of x. Example matches x (matcher = expr(hasType(cxxRecordDecl(hasName("X"))))) and z (matcher = varDecl(hasType(cxxRecordDecl(hasName("X"))))) + and friend class X (matcher = friendDecl(hasType("X")) class X {}; void y(X &x) { x; X z; } + class Y { friend class X; }; Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ValueDecl.html">ValueDecl</a>> </pre></td></tr> @@ -5003,9 +5326,11 @@ matcher. Example matches x (matcher = expr(hasType(cxxRecordDecl(hasName("X"))))) and z (matcher = varDecl(hasType(cxxRecordDecl(hasName("X"))))) and U (matcher = typedefDecl(hasType(asString("int"))) + and friend class X (matcher = friendDecl(hasType("X")) class X {}; void y(X &x) { x; X z; } typedef int U; + class Y { friend class X; }; </pre></td></tr> @@ -5032,7 +5357,7 @@ only match the declarations for b, c, and d. </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('ignoringImplicit0')"><a name="ignoringImplicit0Anchor">ignoringImplicit</a></td><td>ast_matchers::Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>></td><td class="name" onclick="toggle('ignoringImplicit0')"><a name="ignoringImplicit0Anchor">ignoringImplicit</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="ignoringImplicit0"><pre>Matches expressions that match InnerMatcher after any implicit AST nodes are stripped off. @@ -5151,8 +5476,45 @@ matches 'int x = 0' in </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FriendDecl.html">FriendDecl</a>></td><td class="name" onclick="toggle('hasType5')"><a name="hasType5Anchor">hasType</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="hasType5"><pre>Overloaded to match the declaration of the expression's or value +declaration's type. + +In case of a value declaration (for example a variable declaration), +this resolves one layer of indirection. For example, in the value +declaration "X x;", cxxRecordDecl(hasName("X")) matches the declaration of +X, while varDecl(hasType(cxxRecordDecl(hasName("X")))) matches the +declaration of x. + +Example matches x (matcher = expr(hasType(cxxRecordDecl(hasName("X"))))) + and z (matcher = varDecl(hasType(cxxRecordDecl(hasName("X"))))) + and friend class X (matcher = friendDecl(hasType("X")) + class X {}; + void y(X &x) { x; X z; } + class Y { friend class X; }; + +Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ValueDecl.html">ValueDecl</a>> +</pre></td></tr> + + +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FriendDecl.html">FriendDecl</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(cxxRecordDecl(hasName("X"))))) + and z (matcher = varDecl(hasType(cxxRecordDecl(hasName("X"))))) + and U (matcher = typedefDecl(hasType(asString("int"))) + and friend class X (matcher = friendDecl(hasType("X")) + class X {}; + void y(X &x) { x; X z; } + typedef int U; + class Y { friend class X; }; +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('hasAnyParameter0')"><a name="hasAnyParameter0Anchor">hasAnyParameter</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ParmVarDecl.html">ParmVarDecl</a>> InnerMatcher</td></tr> -<tr><td colspan="4" class="doc" id="hasAnyParameter0"><pre>Matches any parameter of a function declaration. +<tr><td colspan="4" class="doc" id="hasAnyParameter0"><pre>Matches any parameter of a function or an ObjC method declaration or a +block. Does not match the 'this' parameter of a method. @@ -5162,6 +5524,20 @@ cxxMethodDecl(hasAnyParameter(hasName("y"))) matches f(int x, int y, int z) {} with hasAnyParameter(...) matching int y + +For ObjectiveC, given + @interface I - (void) f:(int) y; @end + +the matcher objcMethodDecl(hasAnyParameter(hasName("y"))) +matches the declaration of method f with hasParameter +matching y. + +For blocks, given + b = ^(int y) { printf("%d", y) }; + +the matcher blockDecl(hasAnyParameter(hasName("y"))) +matches the declaration of the block b with hasParameter +matching y. </pre></td></tr> @@ -5201,7 +5577,8 @@ with compoundStmt() <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>></td><td class="name" onclick="toggle('hasParameter0')"><a name="hasParameter0Anchor">hasParameter</a></td><td>unsigned N, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ParmVarDecl.html">ParmVarDecl</a>> InnerMatcher</td></tr> -<tr><td colspan="4" class="doc" id="hasParameter0"><pre>Matches the n'th parameter of a function declaration. +<tr><td colspan="4" class="doc" id="hasParameter0"><pre>Matches the n'th parameter of a function or an ObjC method +declaration or a block. Given class X { void f(int x) {} }; @@ -5209,6 +5586,13 @@ cxxMethodDecl(hasParameter(0, hasType(varDecl()))) matches f(int x) {} with hasParameter(...) matching int x + +For ObjectiveC, given + @interface I - (void) f:(int) y; @end + +the matcher objcMethodDecl(hasParameter(0, hasName("y"))) +matches the declaration of method f with hasParameter +matching y. </pre></td></tr> @@ -5221,7 +5605,7 @@ Given A<bool, int> b; A<int, bool> c; - template<typename T> f() {}; + template<typename T> void f() {} void func() { f<int>(); }; classTemplateSpecializationDecl(hasTemplateArgument( 1, refersToType(asString("int")))) @@ -5293,7 +5677,7 @@ FIXME: Unit test this matcher </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>></td><td class="name" onclick="toggle('hasDeclaration9')"><a name="hasDeclaration9Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>></td><td class="name" onclick="toggle('hasDeclaration9')"><a name="hasDeclaration9Anchor">hasDeclaration</a></td><td>const Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> <tr><td colspan="4" class="doc" id="hasDeclaration9"><pre>Matches a node if the declaration associated with that node matches the given matcher. @@ -5303,9 +5687,19 @@ The associated declaration is: - for MemberExpr, the declaration of the referenced member - for CXXConstructExpr, the declaration of the constructor - for CXXNewExpr, the declaration of the operator new +- for ObjCIvarExpr, the declaration of the ivar -Also usable as Matcher<T> for any T supporting the getDecl() member -function. e.g. various subtypes of clang::Type and various expressions. +For type nodes, hasDeclaration will generally match the declaration of the +sugared type. Given + class X {}; + typedef X Y; + Y y; +in varDecl(hasType(hasDeclaration(decl()))) the decl will match the +typedefDecl. A common use case is to match the underlying, desugared type. +This can be achieved by using the hasUnqualifiedDesugaredType matcher: + varDecl(hasType(hasUnqualifiedDesugaredType( + recordType(hasDeclaration(decl()))))) +In this matcher, the decl will match the CXXRecordDecl of class X. Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, 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_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, @@ -5317,7 +5711,7 @@ Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrL </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LabelStmt.html">LabelStmt</a>></td><td class="name" onclick="toggle('hasDeclaration8')"><a name="hasDeclaration8Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1LabelStmt.html">LabelStmt</a>></td><td class="name" onclick="toggle('hasDeclaration8')"><a name="hasDeclaration8Anchor">hasDeclaration</a></td><td>const Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> <tr><td colspan="4" class="doc" id="hasDeclaration8"><pre>Matches a node if the declaration associated with that node matches the given matcher. @@ -5327,9 +5721,19 @@ The associated declaration is: - for MemberExpr, the declaration of the referenced member - for CXXConstructExpr, the declaration of the constructor - for CXXNewExpr, the declaration of the operator new +- for ObjCIvarExpr, the declaration of the ivar -Also usable as Matcher<T> for any T supporting the getDecl() member -function. e.g. various subtypes of clang::Type and various expressions. +For type nodes, hasDeclaration will generally match the declaration of the +sugared type. Given + class X {}; + typedef X Y; + Y y; +in varDecl(hasType(hasDeclaration(decl()))) the decl will match the +typedefDecl. A common use case is to match the underlying, desugared type. +This can be achieved by using the hasUnqualifiedDesugaredType matcher: + varDecl(hasType(hasUnqualifiedDesugaredType( + recordType(hasDeclaration(decl()))))) +In this matcher, the decl will match the CXXRecordDecl of class X. Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, 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_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, @@ -5341,7 +5745,7 @@ Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrL </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>></td><td class="name" onclick="toggle('hasDeclaration7')"><a name="hasDeclaration7Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>></td><td class="name" onclick="toggle('hasDeclaration7')"><a name="hasDeclaration7Anchor">hasDeclaration</a></td><td>const Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> <tr><td colspan="4" class="doc" id="hasDeclaration7"><pre>Matches a node if the declaration associated with that node matches the given matcher. @@ -5351,9 +5755,19 @@ The associated declaration is: - for MemberExpr, the declaration of the referenced member - for CXXConstructExpr, the declaration of the constructor - for CXXNewExpr, the declaration of the operator new +- for ObjCIvarExpr, the declaration of the ivar -Also usable as Matcher<T> for any T supporting the getDecl() member -function. e.g. various subtypes of clang::Type and various expressions. +For type nodes, hasDeclaration will generally match the declaration of the +sugared type. Given + class X {}; + typedef X Y; + Y y; +in varDecl(hasType(hasDeclaration(decl()))) the decl will match the +typedefDecl. A common use case is to match the underlying, desugared type. +This can be achieved by using the hasUnqualifiedDesugaredType matcher: + varDecl(hasType(hasUnqualifiedDesugaredType( + recordType(hasDeclaration(decl()))))) +In this matcher, the decl will match the CXXRecordDecl of class X. Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, 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_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, @@ -5499,6 +5913,25 @@ nestedNameSpecifier(specifiesType( </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ObjCMessageExpr.html">ObjCMessageExpr</a>></td><td class="name" onclick="toggle('hasAnyArgument2')"><a name="hasAnyArgument2Anchor">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="hasAnyArgument2"><pre>Matches any argument of a call expression or a constructor call +expression, or an ObjC-message-send expression. + +Given + void x(int, int, int) { int y; x(1, y, 42); } +callExpr(hasAnyArgument(declRefExpr())) + matches x(1, y, 42) +with hasAnyArgument(...) + matching y + +For ObjectiveC, given + @interface I - (void) f:(int) y; @end + void foo(I *i) { [i f:12]; } +objcMessageExpr(hasAnyArgument(integerLiteral(equals(12)))) + matches [i f:12] +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ObjCMessageExpr.html">ObjCMessageExpr</a>></td><td class="name" onclick="toggle('hasArgument2')"><a name="hasArgument2Anchor">hasArgument</a></td><td>unsigned N, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>> InnerMatcher</td></tr> <tr><td colspan="4" class="doc" id="hasArgument2"><pre>Matches the n'th argument of a call expression or a constructor call expression. @@ -5509,6 +5942,18 @@ Example matches y in x(y) </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ObjCMessageExpr.html">ObjCMessageExpr</a>></td><td class="name" onclick="toggle('hasReceiver0')"><a name="hasReceiver0Anchor">hasReceiver</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="hasReceiver0"><pre>Matches if the Objective-C message is sent to an instance, +and the inner matcher matches on that instance. + +For example the method call in + NSString *x = @"hello"; + [x containsString:@"h"]; +is matched by +objcMessageExpr(hasReceiver(declRefExpr(to(varDecl(hasName("x")))))) +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ObjCMessageExpr.html">ObjCMessageExpr</a>></td><td class="name" onclick="toggle('hasReceiverType0')"><a name="hasReceiverType0Anchor">hasReceiverType</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="hasReceiverType0"><pre>Matches on the receiver of an ObjectiveC Message expression. @@ -5521,8 +5966,68 @@ matches the [webView ...] message invocation. </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ObjCMethodDecl.html">ObjCMethodDecl</a>></td><td class="name" onclick="toggle('hasAnyParameter1')"><a name="hasAnyParameter1Anchor">hasAnyParameter</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ParmVarDecl.html">ParmVarDecl</a>> InnerMatcher</td></tr> +<tr><td colspan="4" class="doc" id="hasAnyParameter1"><pre>Matches any parameter of a function or an ObjC method declaration or a +block. + +Does not match the 'this' parameter of a method. + +Given + class X { void f(int x, int y, int z) {} }; +cxxMethodDecl(hasAnyParameter(hasName("y"))) + matches f(int x, int y, int z) {} +with hasAnyParameter(...) + matching int y + +For ObjectiveC, given + @interface I - (void) f:(int) y; @end + +the matcher objcMethodDecl(hasAnyParameter(hasName("y"))) +matches the declaration of method f with hasParameter +matching y. + +For blocks, given + b = ^(int y) { printf("%d", y) }; + +the matcher blockDecl(hasAnyParameter(hasName("y"))) +matches the declaration of the block b with hasParameter +matching y. +</pre></td></tr> + + +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ObjCMethodDecl.html">ObjCMethodDecl</a>></td><td class="name" onclick="toggle('hasParameter1')"><a name="hasParameter1Anchor">hasParameter</a></td><td>unsigned N, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ParmVarDecl.html">ParmVarDecl</a>> InnerMatcher</td></tr> +<tr><td colspan="4" class="doc" id="hasParameter1"><pre>Matches the n'th parameter of a function or an ObjC method +declaration or a block. + +Given + class X { void f(int x) {} }; +cxxMethodDecl(hasParameter(0, hasType(varDecl()))) + matches f(int x) {} +with hasParameter(...) + matching int x + +For ObjectiveC, given + @interface I - (void) f:(int) y; @end + +the matcher objcMethodDecl(hasParameter(0, hasName("y"))) +matches the declaration of method f with hasParameter +matching y. +</pre></td></tr> + + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1OpaqueValueExpr.html">OpaqueValueExpr</a>></td><td class="name" onclick="toggle('hasSourceExpression1')"><a name="hasSourceExpression1Anchor">hasSourceExpression</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="hasSourceExpression1"><pre></pre></td></tr> +<tr><td colspan="4" class="doc" id="hasSourceExpression1"><pre>Matches if the cast's source expression +or opaque value's source expression matches the given matcher. + +Example 1: matches "a string" +(matcher = castExpr(hasSourceExpression(cxxConstructExpr()))) +class URL { URL(string); }; +URL url = "a string"; + +Example 2: matches 'b' (matcher = +opaqueValueExpr(hasSourceExpression(implicitCastExpr(declRefExpr()))) +int a = b ?: 1; +</pre></td></tr> <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1OverloadExpr.html">OverloadExpr</a>></td><td class="name" onclick="toggle('hasAnyDeclaration0')"><a name="hasAnyDeclaration0Anchor">hasAnyDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> @@ -5601,7 +6106,7 @@ declaration of b but varDecl(hasType(qualType(hasCanonicalType(referenceType())) </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('hasDeclaration6')"><a name="hasDeclaration6Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>></td><td class="name" onclick="toggle('hasDeclaration6')"><a name="hasDeclaration6Anchor">hasDeclaration</a></td><td>const Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> <tr><td colspan="4" class="doc" id="hasDeclaration6"><pre>Matches a node if the declaration associated with that node matches the given matcher. @@ -5611,9 +6116,19 @@ The associated declaration is: - for MemberExpr, the declaration of the referenced member - for CXXConstructExpr, the declaration of the constructor - for CXXNewExpr, the declaration of the operator new +- for ObjCIvarExpr, the declaration of the ivar -Also usable as Matcher<T> for any T supporting the getDecl() member -function. e.g. various subtypes of clang::Type and various expressions. +For type nodes, hasDeclaration will generally match the declaration of the +sugared type. Given + class X {}; + typedef X Y; + Y y; +in varDecl(hasType(hasDeclaration(decl()))) the decl will match the +typedefDecl. A common use case is to match the underlying, desugared type. +This can be achieved by using the hasUnqualifiedDesugaredType matcher: + varDecl(hasType(hasUnqualifiedDesugaredType( + recordType(hasDeclaration(decl()))))) +In this matcher, the decl will match the CXXRecordDecl of class X. Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, 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_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, @@ -5673,7 +6188,7 @@ Example matches X &x and const X &y </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>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>const 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. @@ -5683,9 +6198,19 @@ The associated declaration is: - for MemberExpr, the declaration of the referenced member - for CXXConstructExpr, the declaration of the constructor - for CXXNewExpr, the declaration of the operator new +- for ObjCIvarExpr, the declaration of the ivar -Also usable as Matcher<T> for any T supporting the getDecl() member -function. e.g. various subtypes of clang::Type and various expressions. +For type nodes, hasDeclaration will generally match the declaration of the +sugared type. Given + class X {}; + typedef X Y; + Y y; +in varDecl(hasType(hasDeclaration(decl()))) the decl will match the +typedefDecl. A common use case is to match the underlying, desugared type. +This can be achieved by using the hasUnqualifiedDesugaredType matcher: + varDecl(hasType(hasUnqualifiedDesugaredType( + recordType(hasDeclaration(decl()))))) +In this matcher, the decl will match the CXXRecordDecl of class X. Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, 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_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, @@ -5754,7 +6279,7 @@ with compoundStmt() </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('alignOfExpr0')"><a name="alignOfExpr0Anchor">alignOfExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnaryExprOrTypeTraitExpr.html">UnaryExprOrTypeTraitExpr</a>> InnerMatcher</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('alignOfExpr0')"><a name="alignOfExpr0Anchor">alignOfExpr</a></td><td>const Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnaryExprOrTypeTraitExpr.html">UnaryExprOrTypeTraitExpr</a>> InnerMatcher</td></tr> <tr><td colspan="4" class="doc" id="alignOfExpr0"><pre>Same as unaryExprOrTypeTraitExpr, but only matching alignof. </pre></td></tr> @@ -5774,7 +6299,7 @@ returnStmt(forFunction(hasName("operator="))) </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('sizeOfExpr0')"><a name="sizeOfExpr0Anchor">sizeOfExpr</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnaryExprOrTypeTraitExpr.html">UnaryExprOrTypeTraitExpr</a>> InnerMatcher</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>></td><td class="name" onclick="toggle('sizeOfExpr0')"><a name="sizeOfExpr0Anchor">sizeOfExpr</a></td><td>const Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnaryExprOrTypeTraitExpr.html">UnaryExprOrTypeTraitExpr</a>> InnerMatcher</td></tr> <tr><td colspan="4" class="doc" id="sizeOfExpr0"><pre>Same as unaryExprOrTypeTraitExpr, but only matching sizeof. </pre></td></tr> @@ -5816,7 +6341,7 @@ Example matches true (matcher = hasCondition(cxxBoolLiteral(equals(true)))) </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagType.html">TagType</a>></td><td class="name" onclick="toggle('hasDeclaration4')"><a name="hasDeclaration4Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TagType.html">TagType</a>></td><td class="name" onclick="toggle('hasDeclaration4')"><a name="hasDeclaration4Anchor">hasDeclaration</a></td><td>const Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> <tr><td colspan="4" class="doc" id="hasDeclaration4"><pre>Matches a node if the declaration associated with that node matches the given matcher. @@ -5826,9 +6351,19 @@ The associated declaration is: - for MemberExpr, the declaration of the referenced member - for CXXConstructExpr, the declaration of the constructor - for CXXNewExpr, the declaration of the operator new +- for ObjCIvarExpr, the declaration of the ivar -Also usable as Matcher<T> for any T supporting the getDecl() member -function. e.g. various subtypes of clang::Type and various expressions. +For type nodes, hasDeclaration will generally match the declaration of the +sugared type. Given + class X {}; + typedef X Y; + Y y; +in varDecl(hasType(hasDeclaration(decl()))) the decl will match the +typedefDecl. A common use case is to match the underlying, desugared type. +This can be achieved by using the hasUnqualifiedDesugaredType matcher: + varDecl(hasType(hasUnqualifiedDesugaredType( + recordType(hasDeclaration(decl()))))) +In this matcher, the decl will match the CXXRecordDecl of class X. Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, 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_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, @@ -5844,8 +6379,8 @@ Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrL <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; }; + struct B { int next; }; + template<int(B::*next_ptr)> struct A {}; A<&B::next> a; templateSpecializationType(hasAnyTemplateArgument( isExpr(hasDescendant(declRefExpr(to(fieldDecl(hasName("next")))))))) @@ -5859,11 +6394,11 @@ templateSpecializationType(hasAnyTemplateArgument( declaration. Given - template<typename T> struct A {}; - struct B { B* next; }; + struct B { int next; }; + template<int(B::*next_ptr)> struct A {}; A<&B::next> a; classTemplateSpecializationDecl(hasAnyTemplateArgument( - refersToDeclaration(fieldDecl(hasName("next")))) + refersToDeclaration(fieldDecl(hasName("next"))))) matches the specialization A<&B::next> with fieldDecl(...) matching B::next </pre></td></tr> @@ -5873,7 +6408,7 @@ classTemplateSpecializationDecl(hasAnyTemplateArgument( <tr><td colspan="4" class="doc" id="refersToIntegralType0"><pre>Matches a TemplateArgument that referes to an integral type. Given - template<int T> struct A {}; + template<int T> struct C {}; C<42> c; classTemplateSpecializationDecl( hasAnyTemplateArgument(refersToIntegralType(asString("int")))) @@ -5929,7 +6464,7 @@ functionDecl(hasAnyTemplateArgument(refersToType(asString("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>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>const 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. @@ -5939,9 +6474,19 @@ The associated declaration is: - for MemberExpr, the declaration of the referenced member - for CXXConstructExpr, the declaration of the constructor - for CXXNewExpr, the declaration of the operator new +- for ObjCIvarExpr, the declaration of the ivar -Also usable as Matcher<T> for any T supporting the getDecl() member -function. e.g. various subtypes of clang::Type and various expressions. +For type nodes, hasDeclaration will generally match the declaration of the +sugared type. Given + class X {}; + typedef X Y; + Y y; +in varDecl(hasType(hasDeclaration(decl()))) the decl will match the +typedefDecl. A common use case is to match the underlying, desugared type. +This can be achieved by using the hasUnqualifiedDesugaredType matcher: + varDecl(hasType(hasUnqualifiedDesugaredType( + recordType(hasDeclaration(decl()))))) +In this matcher, the decl will match the CXXRecordDecl of class X. Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, 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_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, @@ -5962,7 +6507,7 @@ Given A<bool, int> b; A<int, bool> c; - template<typename T> f() {}; + template<typename T> void f() {} void func() { f<int>(); }; classTemplateSpecializationDecl(hasTemplateArgument( 1, refersToType(asString("int")))) @@ -5973,7 +6518,7 @@ functionDecl(hasTemplateArgument(0, refersToType(asString("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>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>const 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. @@ -5983,9 +6528,19 @@ The associated declaration is: - for MemberExpr, the declaration of the referenced member - for CXXConstructExpr, the declaration of the constructor - for CXXNewExpr, the declaration of the operator new +- for ObjCIvarExpr, the declaration of the ivar -Also usable as Matcher<T> for any T supporting the getDecl() member -function. e.g. various subtypes of clang::Type and various expressions. +For type nodes, hasDeclaration will generally match the declaration of the +sugared type. Given + class X {}; + typedef X Y; + Y y; +in varDecl(hasType(hasDeclaration(decl()))) the decl will match the +typedefDecl. A common use case is to match the underlying, desugared type. +This can be achieved by using the hasUnqualifiedDesugaredType matcher: + varDecl(hasType(hasUnqualifiedDesugaredType( + recordType(hasDeclaration(decl()))))) +In this matcher, the decl will match the CXXRecordDecl of class X. Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, 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_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, @@ -5997,7 +6552,7 @@ Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrL </pre></td></tr> -<tr><td>Matcher<T></td><td class="name" onclick="toggle('findAll0')"><a name="findAll0Anchor">findAll</a></td><td>Matcher<T> Matcher</td></tr> +<tr><td>Matcher<T></td><td class="name" onclick="toggle('findAll0')"><a name="findAll0Anchor">findAll</a></td><td>const Matcher<T> Matcher</td></tr> <tr><td colspan="4" class="doc" id="findAll0"><pre>Matches if the node or any descendant matches. Generates results for each match. @@ -6013,20 +6568,22 @@ Usable as: Any Matcher </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypedefNameDecl.html">TypedefNameDecl</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 +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1TypedefNameDecl.html">TypedefNameDecl</a>></td><td class="name" onclick="toggle('hasType2')"><a name="hasType2Anchor">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="hasType2"><pre>Matches if the expression's or declaration's type matches a type matcher. Example matches x (matcher = expr(hasType(cxxRecordDecl(hasName("X"))))) and z (matcher = varDecl(hasType(cxxRecordDecl(hasName("X"))))) and U (matcher = typedefDecl(hasType(asString("int"))) + and friend class X (matcher = friendDecl(hasType("X")) class X {}; void y(X &x) { x; X z; } typedef int U; + class Y { friend class X; }; </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>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>const 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. @@ -6036,9 +6593,19 @@ The associated declaration is: - for MemberExpr, the declaration of the referenced member - for CXXConstructExpr, the declaration of the constructor - for CXXNewExpr, the declaration of the operator new +- for ObjCIvarExpr, the declaration of the ivar -Also usable as Matcher<T> for any T supporting the getDecl() member -function. e.g. various subtypes of clang::Type and various expressions. +For type nodes, hasDeclaration will generally match the declaration of the +sugared type. Given + class X {}; + typedef X Y; + Y y; +in varDecl(hasType(hasDeclaration(decl()))) the decl will match the +typedefDecl. A common use case is to match the underlying, desugared type. +This can be achieved by using the hasUnqualifiedDesugaredType matcher: + varDecl(hasType(hasUnqualifiedDesugaredType( + recordType(hasDeclaration(decl()))))) +In this matcher, the decl will match the CXXRecordDecl of class X. Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, 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_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, @@ -6057,7 +6624,7 @@ type of the matched node. For example, in: class A {}; using B = A; -The matcher type(hasUniqualifeidDesugaredType(recordType())) matches +The matcher type(hasUnqualifiedDesugaredType(recordType())) matches both B and A. </pre></td></tr> @@ -6081,7 +6648,7 @@ Example matches true (matcher = hasUnaryOperand( </pre></td></tr> -<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingType.html">UnresolvedUsingType</a>></td><td class="name" onclick="toggle('hasDeclaration0')"><a name="hasDeclaration0Anchor">hasDeclaration</a></td><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingType.html">UnresolvedUsingType</a>></td><td class="name" onclick="toggle('hasDeclaration0')"><a name="hasDeclaration0Anchor">hasDeclaration</a></td><td>const Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>> InnerMatcher</td></tr> <tr><td colspan="4" class="doc" id="hasDeclaration0"><pre>Matches a node if the declaration associated with that node matches the given matcher. @@ -6091,9 +6658,19 @@ The associated declaration is: - for MemberExpr, the declaration of the referenced member - for CXXConstructExpr, the declaration of the constructor - for CXXNewExpr, the declaration of the operator new +- for ObjCIvarExpr, the declaration of the ivar -Also usable as Matcher<T> for any T supporting the getDecl() member -function. e.g. various subtypes of clang::Type and various expressions. +For type nodes, hasDeclaration will generally match the declaration of the +sugared type. Given + class X {}; + typedef X Y; + Y y; +in varDecl(hasType(hasDeclaration(decl()))) the decl will match the +typedefDecl. A common use case is to match the underlying, desugared type. +This can be achieved by using the hasUnqualifiedDesugaredType matcher: + varDecl(hasType(hasUnqualifiedDesugaredType( + recordType(hasDeclaration(decl()))))) +In this matcher, the decl will match the CXXRecordDecl of class X. Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>>, 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_1CXXNewExpr.html">CXXNewExpr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1DeclRefExpr.html">DeclRefExpr</a>>, @@ -6127,8 +6704,8 @@ usingDecl(hasAnyUsingShadowDecl(hasTargetDecl(functionDecl()))) matches using X::b but not using X::a </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('hasType4')"><a name="hasType4Anchor">hasType</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="hasType4"><pre>Overloaded to match the declaration of the expression's or value +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ValueDecl.html">ValueDecl</a>></td><td class="name" onclick="toggle('hasType6')"><a name="hasType6Anchor">hasType</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="hasType6"><pre>Overloaded to match the declaration of the expression's or value declaration's type. In case of a value declaration (for example a variable declaration), @@ -6139,23 +6716,27 @@ declaration of x. Example matches x (matcher = expr(hasType(cxxRecordDecl(hasName("X"))))) and z (matcher = varDecl(hasType(cxxRecordDecl(hasName("X"))))) + and friend class X (matcher = friendDecl(hasType("X")) class X {}; void y(X &x) { x; X z; } + class Y { friend class X; }; Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ValueDecl.html">ValueDecl</a>> </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('hasType2')"><a name="hasType2Anchor">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="hasType2"><pre>Matches if the expression's or declaration's type matches a type +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1ValueDecl.html">ValueDecl</a>></td><td class="name" onclick="toggle('hasType3')"><a name="hasType3Anchor">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="hasType3"><pre>Matches if the expression's or declaration's type matches a type matcher. Example matches x (matcher = expr(hasType(cxxRecordDecl(hasName("X"))))) and z (matcher = varDecl(hasType(cxxRecordDecl(hasName("X"))))) and U (matcher = typedefDecl(hasType(asString("int"))) + and friend class X (matcher = friendDecl(hasType("X")) class X {}; void y(X &x) { x; X z; } typedef int U; + class Y { friend class X; }; </pre></td></tr> diff --git a/docs/LibASTMatchersTutorial.rst b/docs/LibASTMatchersTutorial.rst index baf2c1c3e699..832b47efd1b8 100644 --- a/docs/LibASTMatchersTutorial.rst +++ b/docs/LibASTMatchersTutorial.rst @@ -146,7 +146,7 @@ documentation <LibTooling.html>`_. static cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage); // A help message for this specific tool can be added afterwards. - static cl::extrahelp MoreHelp("\nMore help text..."); + static cl::extrahelp MoreHelp("\nMore help text...\n"); int main(int argc, const char **argv) { CommonOptionsParser OptionsParser(argc, argv, MyToolCategory); diff --git a/docs/LibFormat.rst b/docs/LibFormat.rst index 086a52827d8c..2863a076edf4 100644 --- a/docs/LibFormat.rst +++ b/docs/LibFormat.rst @@ -44,11 +44,11 @@ two style guides are hard-coded: .. code-block:: c++ - /// \brief Returns a format style complying with the LLVM coding standards: + /// Returns a format style complying with the LLVM coding standards: /// http://llvm.org/docs/CodingStandards.html. FormatStyle getLLVMStyle(); - /// \brief Returns a format style complying with Google's C++ style guide: + /// Returns a format style complying with Google's C++ style guide: /// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml. FormatStyle getGoogleStyle(); diff --git a/docs/LibTooling.rst b/docs/LibTooling.rst index 75ef6a0fe7ea..a422a1d5665a 100644 --- a/docs/LibTooling.rst +++ b/docs/LibTooling.rst @@ -130,7 +130,7 @@ version of this example tool is also checked into the clang tree at static cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage); // A help message for this specific tool can be added afterwards. - static cl::extrahelp MoreHelp("\nMore help text..."); + static cl::extrahelp MoreHelp("\nMore help text...\n"); int main(int argc, const char **argv) { CommonOptionsParser OptionsParser(argc, argv, MyToolCategory); diff --git a/docs/MemorySanitizer.rst b/docs/MemorySanitizer.rst index 5bb19ed8a509..4e033fa1941d 100644 --- a/docs/MemorySanitizer.rst +++ b/docs/MemorySanitizer.rst @@ -185,7 +185,11 @@ self-built instrumented libc++ (as a replacement for libstdc++). Supported Platforms =================== -MemorySanitizer is supported on Linux x86\_64/MIPS64/AArch64. +MemorySanitizer is supported on the following OS: + +* Linux +* NetBSD +* FreeBSD Limitations =========== diff --git a/docs/Modules.rst b/docs/Modules.rst index 2fa38be6f493..493c54d3913a 100644 --- a/docs/Modules.rst +++ b/docs/Modules.rst @@ -430,6 +430,21 @@ cplusplus cplusplus11 C++11 support is available. +cplusplus14 + C++14 support is available. + +cplusplus17 + C++17 support is available. + +c99 + C99 support is available. + +c11 + C11 support is available. + +c17 + C17 support is available. + freestanding A freestanding environment is available. diff --git a/docs/OpenMPSupport.rst b/docs/OpenMPSupport.rst new file mode 100644 index 000000000000..e8ec1e371b04 --- /dev/null +++ b/docs/OpenMPSupport.rst @@ -0,0 +1,131 @@ +.. 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 + +.. contents:: + :local: + +================== +OpenMP Support +================== + +Clang fully supports OpenMP 4.5. Clang supports offloading to X86_64, AArch64, +PPC64[LE] and has `basic support for Cuda devices`_. + +Standalone directives +===================== + +* #pragma omp [for] simd: :good:`Complete`. + +* #pragma omp declare simd: :partial:`Partial`. We support parsing/semantic + analysis + generation of special attributes for X86 target, but still + missing the LLVM pass for vectorization. + +* #pragma omp taskloop [simd]: :good:`Complete`. + +* #pragma omp target [enter|exit] data: :good:`Complete`. + +* #pragma omp target update: :good:`Complete`. + +* #pragma omp target: :good:`Complete`. + +* #pragma omp declare target: :good:`Complete`. + +* #pragma omp teams: :good:`Complete`. + +* #pragma omp distribute [simd]: :good:`Complete`. + +* #pragma omp distribute parallel for [simd]: :good:`Complete`. + +Combined directives +=================== + +* #pragma omp parallel for simd: :good:`Complete`. + +* #pragma omp target parallel: :good:`Complete`. + +* #pragma omp target parallel for [simd]: :good:`Complete`. + +* #pragma omp target simd: :good:`Complete`. + +* #pragma omp target teams: :good:`Complete`. + +* #pragma omp teams distribute [simd]: :good:`Complete`. + +* #pragma omp target teams distribute [simd]: :good:`Complete`. + +* #pragma omp teams distribute parallel for [simd]: :good:`Complete`. + +* #pragma omp target teams distribute parallel for [simd]: :good:`Complete`. + +Clang does not support any constructs/updates from upcoming OpenMP 5.0 except +for `reduction`-based clauses in the `task` and `target`-based directives. + +In addition, the LLVM OpenMP runtime `libomp` supports the OpenMP Tools +Interface (OMPT) on x86, x86_64, AArch64, and PPC64 on Linux, Windows, and mac OS. +ows, and mac OS. + +.. _basic support for Cuda devices: + +Cuda devices support +==================== + +Directives execution modes +-------------------------- + +Clang code generation for target regions supports two modes: the SPMD and +non-SPMD modes. Clang chooses one of these two modes automatically based on the +way directives and clauses on those directives are used. The SPMD mode uses a +simplified set of runtime functions thus increasing performance at the cost of +supporting some OpenMP features. The non-SPMD mode is the most generic mode and +supports all currently available OpenMP features. The compiler will always +attempt to use the SPMD mode wherever possible. SPMD mode will not be used if: + + - The target region contains an `if()` clause that refers to a `parallel` + directive. + + - The target region contains a `parallel` directive with a `num_threads()` + clause. + + - The target region contains user code (other than OpenMP-specific + directives) in between the `target` and the `parallel` directives. + +Data-sharing modes +------------------ + +Clang supports two data-sharing models for Cuda devices: `Generic` and `Cuda` +modes. The default mode is `Generic`. `Cuda` mode can give an additional +performance and can be activated using the `-fopenmp-cuda-mode` flag. In +`Generic` mode all local variables that can be shared in the parallel regions +are stored in the global memory. In `Cuda` mode local variables are not shared +between the threads and it is user responsibility to share the required data +between the threads in the parallel regions. + +Features not supported or with limited support for Cuda devices +--------------------------------------------------------------- + +- Reductions across the teams are not supported yet. + +- Cancellation constructs are not supported. + +- Doacross loop nest is not supported. + +- User-defined reductions are supported only for trivial types. + +- Nested parallelism: inner parallel regions are executed sequentially. + +- Static linking of libraries containing device code is not supported yet. + +- Automatic translation of math functions in target regions to device-specific + math functions is not implemented yet. + +- Debug information for OpenMP target regions is not supported yet. + diff --git a/docs/ReleaseNotes.rst b/docs/ReleaseNotes.rst index 8dce92341c3b..342fed3393b1 100644 --- a/docs/ReleaseNotes.rst +++ b/docs/ReleaseNotes.rst @@ -1,5 +1,5 @@ ======================================= -Clang 6.0.0 (In-Progress) Release Notes +Clang 7.0.0 (In-Progress) Release Notes ======================================= .. contents:: @@ -10,7 +10,7 @@ Written by the `LLVM Team <http://llvm.org/>`_ .. warning:: - These are in-progress notes for the upcoming Clang 6 release. + These are in-progress notes for the upcoming Clang 7 release. Release notes for previous releases can be found on `the Download Page <http://releases.llvm.org/download.html>`_. @@ -18,7 +18,7 @@ Introduction ============ This document contains the release notes for the Clang C/C++/Objective-C -frontend, part of the LLVM Compiler Infrastructure, release 6.0.0. Here we +frontend, part of the LLVM Compiler Infrastructure, release 7.0.0. 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 @@ -35,7 +35,7 @@ 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 6.0.0? +What's New in Clang 7.0.0? ========================== Some of the major new features and improvements to Clang are listed @@ -51,86 +51,81 @@ Major New Features Improvements to Clang's diagnostics ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- ``-Wpragma-pack`` is a new warning that warns in the following cases: +- ``-Wc++98-compat-extra-semi`` is a new flag, which was previously inseparable + from ``-Wc++98-compat-pedantic``. The latter still controls the new flag. - - When a translation unit is missing terminating ``#pragma pack (pop)`` - directives. +- ``-Wextra-semi`` now also controls ``-Wc++98-compat-extra-semi``. + Please do note that if you pass ``-Wno-c++98-compat-pedantic``, it implies + ``-Wno-c++98-compat-extra-semi``, so if you want that diagnostic, you need + to explicitly re-enable it (e.g. by appending ``-Wextra-semi``). - - When leaving an included file that changes the current alignment value, - i.e. when the alignment before ``#include`` is different to the alignment - after ``#include``. - - - ``-Wpragma-pack-suspicious-include`` (disabled by default) warns on an - ``#include`` when the included file contains structures or unions affected by - a non-default alignment that has been specified using a ``#pragma pack`` - directive prior to the ``#include``. - -- ``-Wobjc-messaging-id`` is a new, non-default warning that warns about - message sends to unqualified ``id`` in Objective-C. This warning is useful - for projects that would like to avoid any potential future compiler - errors/warnings, as the system frameworks might add a method with the same - selector which could make the message send to ``id`` ambiguous. - -- ``-Wtautological-compare`` now warns when comparing an unsigned integer and 0 - regardless of whether the constant is signed or unsigned." - -- ``-Wtautological-compare`` now warns about comparing a signed integer and 0 - when the signed integer is coerced to an unsigned type for the comparison. - ``-Wsign-compare`` was adjusted not to warn in this case. - -- ``-Wtautological-constant-compare`` is a new warning that warns on - tautological comparisons between integer variable of the type ``T`` and the - largest/smallest possible integer constant of that same type. - -- For C code, ``-Wsign-compare``, ``-Wsign-conversion``, - ``-Wtautological-constant-compare`` and - ``-Wtautological-constant-out-of-range-compare`` were adjusted to use the - underlying datatype of ``enum``. - -- ``-Wnull-pointer-arithmetic`` now warns about performing pointer arithmetic - on a null pointer. Such pointer arithmetic has an undefined behavior if the - offset is nonzero. It also now warns about arithmetic on a null pointer - treated as a cast from integer to pointer (GNU extension). - -- ``-Wzero-as-null-pointer-constant`` was adjusted not to warn on null pointer - constants that originate from system macros, except ``NULL`` macro. +- ``-Wself-assign`` and ``-Wself-assign-field`` were extended to diagnose + self-assignment operations using overloaded operators (i.e. classes). + If you are doing such an assignment intentionally, e.g. in a unit test for + a data structure, the first warning can be disabled by passing + ``-Wno-self-assign-overloaded``, also the warning can be suppressed by adding + ``*&`` to the right-hand side or casting it to the appropriate reference type. Non-comprehensive list of changes in this release ------------------------------------------------- -- Bitrig OS was merged back into OpenBSD, so Bitrig support has been - removed from Clang/LLVM. - -- The default value of _MSC_VER was raised from 1800 to 1911, making it - compatible with the Visual Studio 2015 and 2017 C++ standard library headers. - Users should generally expect this to be regularly raised to match the most - recently released version of the Visual C++ compiler. +- Clang binary and libraries have been renamed from 7.0 to 7. + For example, the ``clang`` binary will be called ``clang-7`` + instead of ``clang-7.0``. + +- Clang implements a collection of recent fixes to the C++ standard's definition + of "standard-layout". In particular, a class is only considered to be + standard-layout if all base classes and the first data member (or bit-field) + can be laid out at offset zero. + +- Clang's handling of the GCC ``packed`` class attribute in C++ has been fixed + to apply only to non-static data members and not to base classes. This fixes + an ABI difference between Clang and GCC, but creates an ABI difference between + Clang 7 and earlier versions. The old behavior can be restored by setting + ``-fclang-abi-compat`` to ``6`` or earlier. + +- Clang implements the proposed resolution of LWG issue 2358, along with the + `corresponding change to the Itanium C++ ABI + <https://github.com/itanium-cxx-abi/cxx-abi/pull/51>`_, which make classes + containing only unnamed non-zero-length bit-fields be considered non-empty. + This is an ABI break compared to prior Clang releases, but makes Clang + generate code that is ABI-compatible with other compilers. The old + behavior can be restored by setting ``-fclang-abi-compat`` to ``6`` or + lower. + +- An existing tool named ``diagtool`` has been added to the release. As the + name suggests, it helps with dealing with diagnostics in ``clang``, such as + finding out the warning hierarchy, and which of them are enabled by default + or for a particular compiler invocation. + +- By default, Clang emits an address-significance table into + every ELF object file when using the integrated assembler. + Address-significance tables allow linkers to implement `safe ICF + <https://research.google.com/pubs/archive/36912.pdf>`_ without the false + positives that can result from other implementation techniques such as + relocation scanning. The ``-faddrsig`` and ``-fno-addrsig`` flags can be + used to control whether to emit the address-significance table. -- clang now defaults to ``.init_array`` if no gcc installation can be found. - If a gcc installation is found, it still prefers ``.ctors`` if the found - gcc is older than 4.7.0. - -- The new builtin preprocessor macros ``__is_target_arch``, - ``__is_target_vendor``, ``__is_target_os``, and ``__is_target_environment`` - can be used to to examine the individual components of the target triple. +- ... New Compiler Flags ------------------ -- --autocomplete was implemented to obtain a list of flags and its arguments. This is used for shell autocompletion. - -- The ``-fdouble-square-bracket-attributes`` and corresponding - ``-fno-double-square-bracket-attributes`` flags were added to enable or - disable [[]] attributes in any language mode. Currently, only a limited - number of attributes are supported outside of C++ mode. See the Clang - attribute documentation for more information about which attributes are - supported for each syntax. - -- Added the ``-std=c17``, ``-std=gnu17``, and ``-std=iso9899:2017`` language - mode flags for compatibility with GCC. This enables support for the next - version of the C standard, expected to be published by ISO in 2018. The only - difference between the ``-std=c17`` and ``-std=c11`` language modes is the - value of the ``__STDC_VERSION__`` macro, as C17 is a bug fix release. +- ``-fstrict-float-cast-overflow`` and ``-fno-strict-float-cast-overflow``. + + When a floating-point value is not representable in a destination integer + type, the code has undefined behavior according to the language standard. By + default, Clang will not guarantee any particular result in that case. With the + 'no-strict' option, Clang attempts to match the overflowing behavior of the + target's native float-to-int conversion instructions. + +- ``-fforce-emit-vtables`` and ``-fno-force-emit-vtables``. + + In order to improve devirtualization, forces emitting of vtables even in + modules where it isn't necessary. It causes more inline virtual functions + to be emitted. + +- ... Deprecated Compiler Flags ------------------------- @@ -140,35 +135,50 @@ future versions of Clang. - ... -New Pragmas in Clang +Modified Compiler Flags ----------------------- +- Before Clang 7, we prepended the `#` character to the `--autocomplete` + argument to enable cc1 flags. For example, when the `-cc1` or `-Xclang` flag + is in the :program:`clang` invocation, the shell executed + `clang --autocomplete=#-<flag to be completed>`. Clang 7 now requires the + whole invocation including all flags to be passed to the `--autocomplete` like + this: `clang --autocomplete=-cc1,-xc++,-fsyn`. + +New Pragmas in Clang +-------------------- + Clang now supports the ... Attribute Changes in Clang -------------------------- -- Clang now supports the majority of its attributes under both the GNU-style - spelling (``__attribute((name))``) and the double square-bracket spelling - in the ``clang`` vendor namespace (``[[clang::name]]``). Attributes whose - syntax is specified by some other standard (such as CUDA and OpenCL - attributes) continue to follow their respective specification. - -- Added the ``__has_c_attribute()`` builtin preprocessor macro which allows - users to dynamically detect whether a double square-bracket attribute is - supported in C mode. This attribute syntax can be enabled with the - ``-fdouble-square-bracket-attributes`` flag. - -- The presence of __attribute__((availability(...))) on a declaration no longer - implies default visibility for that declaration on macOS. +- Clang now supports function multiversioning with attribute 'target' on ELF + based x86/x86-64 environments by using indirect functions. This implementation + has a few minor limitations over the GCC implementation for the sake of AST + sanity, however it is otherwise compatible with existing code using this + feature for GCC. Consult the documentation for the target attribute for more + information. - ... Windows Support --------------- -Clang's support for building native Windows programs ... +- clang-cl's support for precompiled headers has been much improved: + + - When using a pch file, clang-cl now no longer redundantly emits inline + methods that are already stored in the obj that was built together with + the pch file (matching cl.exe). This speeds up builds using pch files + by around 30%. + + - The /Ycfoo.h and /Yufoo.h flags can now be used without /FIfoo.h when + foo.h is instead included by an explicit `#include` directive. This means + Visual Studio's default stdafx.h setup now uses precompiled headers with + clang-cl. + +- ... C Language Changes in Clang @@ -186,10 +196,7 @@ C11 Feature Support C++ Language Changes in Clang ----------------------------- -- Clang's default C++ dialect is now ``gnu++14`` instead of ``gnu++98``. This - means Clang will by default accept code using features from C++14 and - conforming GNU extensions. Projects incompatible with C++14 can add - ``-std=gnu++98`` to their build settings to restore the previous behaviour. +- ... C++1z Feature Support ^^^^^^^^^^^^^^^^^^^^^ @@ -209,12 +216,38 @@ OpenCL C Language Changes in Clang OpenMP Support in Clang ---------------------------------- -... +- Clang gained basic support for OpenMP 4.5 offloading for NVPTX target. + To compile your program for NVPTX target use the following options: + `-fopenmp -fopenmp-targets=nvptx64-nvidia-cuda` for 64 bit platforms or + `-fopenmp -fopenmp-targets=nvptx-nvidia-cuda` for 32 bit platform. + +- Passing options to the OpenMP device offloading toolchain can be done using + the `-Xopenmp-target=<triple> -opt=val` flag. In this way the `-opt=val` + option will be forwarded to the respective OpenMP device offloading toolchain + described by the triple. For example passing the compute capability to + the OpenMP NVPTX offloading toolchain can be done as follows: + `-Xopenmp-target=nvptx64-nvidia-cuda -march=sm_60`. For the case when only one + target offload toolchain is specified under the `-fopenmp-targets=<triples>` + option, then the triple can be skipped: `-Xopenmp-target -march=sm_60`. + +- Other bugfixes. + +CUDA Support in Clang +--------------------- + +- Clang will now try to locate the CUDA installation next to :program:`ptxas` + in the `PATH` environment variable. This behavior can be turned off by passing + the new flag `--cuda-path-ignore-env`. + +- Clang now supports generating object files with relocatable device code. This + feature needs to be enabled with `-fcuda-rdc` and my result in performance + penalties compared to whole program compilation. Please note that NVIDIA's + :program:`nvcc` must be used for linking. Internal API Changes -------------------- -These are major API changes that have happened since the 4.0.0 release of +These are major API changes that have happened since the 6.0.0 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. @@ -223,67 +256,16 @@ this section should help get you past the largest hurdles of upgrading. AST Matchers ------------ -The hasDeclaration matcher now works the same for Type and QualType and only -ever looks through one level of sugaring in a limited number of cases. - -There are two main patterns affected by this: - -- qualType(hasDeclaration(recordDecl(...))): previously, we would look through - sugar like TypedefType to get at the underlying recordDecl; now, we need - to explicitly remove the sugaring: - qualType(hasUnqualifiedDesugaredType(hasDeclaration(recordDecl(...)))) - -- hasType(recordDecl(...)): hasType internally uses hasDeclaration; previously, - this matcher used to match for example TypedefTypes of the RecordType, but - after the change they don't; to fix, use: - -:: - hasType(hasUnqualifiedDesugaredType( - recordType(hasDeclaration(recordDecl(...))))) - -- templateSpecializationType(hasDeclaration(classTemplateDecl(...))): - previously, we would directly match the underlying ClassTemplateDecl; - now, we can explicitly match the ClassTemplateSpecializationDecl, but that - requires to explicitly get the ClassTemplateDecl: - -:: - templateSpecializationType(hasDeclaration( - classTemplateSpecializationDecl( - hasSpecializedTemplate(classTemplateDecl(...))))) +- ... clang-format ------------ -* Option *IndentPPDirectives* added to indent preprocessor directives on - conditionals. - - +----------------------+----------------------+ - | Before | After | - +======================+======================+ - | .. code-block:: c++ | .. code-block:: c++ | - | | | - | #if FOO | #if FOO | - | #if BAR | # if BAR | - | #include <foo> | # include <foo> | - | #endif | # endif | - | #endif | #endif | - +----------------------+----------------------+ - -* Option -verbose added to the command line. - Shows the list of processed files. - -* Option *IncludeBlocks* added to merge and regroup multiple ``#include`` blocks during sorting. - - +-------------------------+-------------------------+-------------------------+ - | Before (Preserve) | Merge | Regroup | - +=========================+=========================+=========================+ - | .. code-block:: c++ | .. code-block:: c++ | .. code-block:: c++ | - | | | | - | #include "b.h" | #include "a.h" | #include "a.h" | - | | #include "b.h" | #include "b.h" | - | #include "a.b" | #include <lib/main.h> | | - | #include <lib/main.h> | | #include <lib/main.h> | - +-------------------------+-------------------------+-------------------------+ +- Clang-format will now support detecting and formatting code snippets in raw + string literals. This is configured through the `RawStringFormats` style + option. + +- ... libclang -------- @@ -294,18 +276,14 @@ libclang Static Analyzer --------------- -- Static Analyzer can now properly detect and diagnose unary pre-/post- - increment/decrement on an uninitialized value. +- ... ... Undefined Behavior Sanitizer (UBSan) ------------------------------------ -* A minimal runtime is now available. It is suitable for use in production - environments, and has a small attack surface. It only provides very basic - issue logging and deduplication, and does not support ``-fsanitize=vptr`` - checking. +* ... Core Analysis Improvements ========================== diff --git a/docs/SafeStack.rst b/docs/SafeStack.rst index f01b75f5cb37..b046aa616898 100644 --- a/docs/SafeStack.rst +++ b/docs/SafeStack.rst @@ -126,7 +126,7 @@ and link command lines. Supported Platforms ------------------- -SafeStack was tested on Linux, FreeBSD and MacOSX. +SafeStack was tested on Linux, NetBSD, FreeBSD and MacOSX. Low-level API ------------- @@ -165,11 +165,23 @@ never be stored on the heap, as it would leak the location of the SafeStack. This builtin function returns current unsafe stack pointer of the current thread. +``__builtin___get_unsafe_stack_bottom()`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This builtin function returns a pointer to the bottom of the unsafe stack of the +current thread. + +``__builtin___get_unsafe_stack_top()`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This builtin function returns a pointer to the top of the unsafe stack of the +current thread. + ``__builtin___get_unsafe_stack_start()`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This builtin function returns a pointer to the start of the unsafe stack of the -current thread. +Deprecated: This builtin function is an alias for +``__builtin___get_unsafe_stack_bottom()``. Design ====== diff --git a/docs/SanitizerStats.rst b/docs/SanitizerStats.rst index cff68f6b5d53..cbc3b37d31c5 100644 --- a/docs/SanitizerStats.rst +++ b/docs/SanitizerStats.rst @@ -56,7 +56,7 @@ Example: 10 A a; 11 g(&a); 12 } - $ clang++ -fsanitize=cfi -flto -fuse-ld=gold vcall.cc -fsanitize-stats -g + $ clang++ -fsanitize=cfi -fvisibility=hidden -flto -fuse-ld=gold vcall.cc -fsanitize-stats -g $ SANITIZER_STATS_PATH=a.stats ./a.out $ sanstats a.stats vcall.cc:6 _Z1gP1A cfi-vcall 1 diff --git a/docs/ShadowCallStack.rst b/docs/ShadowCallStack.rst new file mode 100644 index 000000000000..da609dcd9de4 --- /dev/null +++ b/docs/ShadowCallStack.rst @@ -0,0 +1,193 @@ +=============== +ShadowCallStack +=============== + +.. contents:: + :local: + +Introduction +============ + +ShadowCallStack is an **experimental** instrumentation pass, currently only +implemented for x86_64 and aarch64, that protects programs against return +address overwrites (e.g. stack buffer overflows.) It works by saving a +function's return address to a separately allocated 'shadow call stack' +in the function prolog and checking the return address on the stack against +the shadow call stack in the function epilog. + +Comparison +---------- + +To optimize for memory consumption and cache locality, the shadow call stack +stores an index followed by an array of return addresses. This is in contrast +to other schemes, like :doc:`SafeStack`, that mirror the entire stack and +trade-off consuming more memory for shorter function prologs and epilogs with +fewer memory accesses. Similarly, `Return Flow Guard`_ consumes more memory with +shorter function prologs and epilogs than ShadowCallStack but suffers from the +same race conditions (see `Security`_). Intel `Control-flow Enforcement Technology`_ +(CET) is a proposed hardware extension that would add native support to +use a shadow stack to store/check return addresses at call/return time. It +would not suffer from race conditions at calls and returns and not incur the +overhead of function instrumentation, but it does require operating system +support. + +.. _`Return Flow Guard`: https://xlab.tencent.com/en/2016/11/02/return-flow-guard/ +.. _`Control-flow Enforcement Technology`: https://software.intel.com/sites/default/files/managed/4d/2a/control-flow-enforcement-technology-preview.pdf + +Compatibility +------------- + +ShadowCallStack currently only supports x86_64 and aarch64. A runtime is not +currently provided in compiler-rt so one must be provided by the compiled +application. + +On aarch64, the instrumentation makes use of the platform register ``x18``. +On some platforms, ``x18`` is reserved, and on others, it is designated as +a scratch register. This generally means that any code that may run on the +same thread as code compiled with ShadowCallStack must either target one +of the platforms whose ABI reserves ``x18`` (currently Darwin, Fuchsia and +Windows) or be compiled with the flag ``-ffixed-x18``. + +Security +======== + +ShadowCallStack is intended to be a stronger alternative to +``-fstack-protector``. It protects from non-linear overflows and arbitrary +memory writes to the return address slot; however, similarly to +``-fstack-protector`` this protection suffers from race conditions because of +the call-return semantics on x86_64. There is a short race between the call +instruction and the first instruction in the function that reads the return +address where an attacker could overwrite the return address and bypass +ShadowCallStack. Similarly, there is a time-of-check-to-time-of-use race in the +function epilog where an attacker could overwrite the return address after it +has been checked and before it has been returned to. Modifying the call-return +semantics to fix this on x86_64 would incur an unacceptable performance overhead +due to return branch prediction. + +The instrumentation makes use of the ``gs`` segment register on x86_64, +or the ``x18`` register on aarch64, to reference the shadow call stack +meaning that references to the shadow call stack do not have to be stored in +memory. This makes it possible to implement a runtime that avoids exposing +the address of the shadow call stack to attackers that can read arbitrary +memory. However, attackers could still try to exploit side channels exposed +by the operating system `[1]`_ `[2]`_ or processor `[3]`_ to discover the +address of the shadow call stack. + +.. _`[1]`: https://eyalitkin.wordpress.com/2017/09/01/cartography-lighting-up-the-shadows/ +.. _`[2]`: https://www.blackhat.com/docs/eu-16/materials/eu-16-Goktas-Bypassing-Clangs-SafeStack.pdf +.. _`[3]`: https://www.vusec.net/projects/anc/ + +On x86_64, leaf functions are optimized to store the return address in a +free register and avoid writing to the shadow call stack if a register is +available. Very short leaf functions are uninstrumented if their execution +is judged to be shorter than the race condition window intrinsic to the +instrumentation. + +On aarch64, the architecture's call and return instructions (``bl`` and +``ret``) operate on a register rather than the stack, which means that +leaf functions are generally protected from return address overwrites even +without ShadowCallStack. It also means that ShadowCallStack on aarch64 is not +vulnerable to the same types of time-of-check-to-time-of-use races as x86_64. + +Usage +===== + +To enable ShadowCallStack, just pass the ``-fsanitize=shadow-call-stack`` +flag to both compile and link command lines. On aarch64, you also need to pass +``-ffixed-x18`` unless your target already reserves ``x18``. + +Low-level API +------------- + +``__has_feature(shadow_call_stack)`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In some cases one may need to execute different code depending on whether +ShadowCallStack is enabled. The macro ``__has_feature(shadow_call_stack)`` can +be used for this purpose. + +.. code-block:: c + + #if defined(__has_feature) + # if __has_feature(shadow_call_stack) + // code that builds only under ShadowCallStack + # endif + #endif + +``__attribute__((no_sanitize("shadow-call-stack")))`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use ``__attribute__((no_sanitize("shadow-call-stack")))`` on a function +declaration to specify that the shadow call stack instrumentation should not be +applied to that function, even if enabled globally. + +Example +======= + +The following example code: + +.. code-block:: c++ + + int foo() { + return bar() + 1; + } + +Generates the following x86_64 assembly when compiled with ``-O2``: + +.. code-block:: gas + + push %rax + callq bar + add $0x1,%eax + pop %rcx + retq + +or the following aarch64 assembly: + +.. code-block:: none + + stp x29, x30, [sp, #-16]! + mov x29, sp + bl bar + add w0, w0, #1 + ldp x29, x30, [sp], #16 + ret + + +Adding ``-fsanitize=shadow-call-stack`` would output the following x86_64 +assembly: + +.. code-block:: gas + + mov (%rsp),%r10 + xor %r11,%r11 + addq $0x8,%gs:(%r11) + mov %gs:(%r11),%r11 + mov %r10,%gs:(%r11) + push %rax + callq bar + add $0x1,%eax + pop %rcx + xor %r11,%r11 + mov %gs:(%r11),%r10 + mov %gs:(%r10),%r10 + subq $0x8,%gs:(%r11) + cmp %r10,(%rsp) + jne trap + retq + + trap: + ud2 + +or the following aarch64 assembly: + +.. code-block:: none + + str x30, [x18], #8 + stp x29, x30, [sp, #-16]! + mov x29, sp + bl bar + add w0, w0, #1 + ldp x29, x30, [sp], #16 + ldr x30, [x18, #-8]! + ret diff --git a/docs/ThinLTO.rst b/docs/ThinLTO.rst index 14c098b052df..38873f464c29 100644 --- a/docs/ThinLTO.rst +++ b/docs/ThinLTO.rst @@ -156,7 +156,7 @@ A policy string is a series of key-value pairs separated by ``:`` characters. Possible key-value pairs are: - ``cache_size=X%``: The maximum size for the cache directory is ``X`` percent - of the available space on the the disk. Set to 100 to indicate no limit, + of the available space on the disk. Set to 100 to indicate no limit, 50 to indicate that the cache size will not be left over half the available disk space. A value over 100 is invalid. A value of 0 disables the percentage size-based pruning. The default is 75%. diff --git a/docs/ThreadSanitizer.rst b/docs/ThreadSanitizer.rst index cfbaa63d6432..d1e2c65ec5f1 100644 --- a/docs/ThreadSanitizer.rst +++ b/docs/ThreadSanitizer.rst @@ -17,7 +17,12 @@ Build LLVM/Clang with `CMake <http://llvm.org/docs/CMake.html>`_. Supported Platforms ------------------- -ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 12.04). +ThreadSanitizer is supported on the following OS: + +* Linux +* NetBSD +* FreeBSD + Support for other 64-bit architectures is possible, contributions are welcome. Support for 32-bit platforms is problematic and is not planned. diff --git a/docs/Toolchain.rst b/docs/Toolchain.rst index e727ccdc7c1a..06bde35c3da6 100644 --- a/docs/Toolchain.rst +++ b/docs/Toolchain.rst @@ -106,7 +106,7 @@ Assember Clang can either use LLVM's integrated assembler or an external system-specific tool (for instance, the GNU Assembler on GNU OSes) to produce machine code from assembly. -By default, Clang uses LLVM's integrataed assembler on all targets where it is +By default, Clang uses LLVM's integrated assembler on all targets where it is supported. If you wish to use the system assember instead, use the ``-fno-integrated-as`` option. diff --git a/docs/UndefinedBehaviorSanitizer.rst b/docs/UndefinedBehaviorSanitizer.rst index e9f85c24dde0..71a8ebd4bc64 100644 --- a/docs/UndefinedBehaviorSanitizer.rst +++ b/docs/UndefinedBehaviorSanitizer.rst @@ -180,6 +180,13 @@ will need to: ``UBSAN_OPTIONS=print_stacktrace=1``. #. Make sure ``llvm-symbolizer`` binary is in ``PATH``. +Silencing Unsigned Integer Overflow +=================================== +To silence reports from unsigned integer overflow, you can set +``UBSAN_OPTIONS=silence_unsigned_overflow=1``. This feature, combined with +``-fsanitize-recover=unsigned-integer-overflow``, is particularly useful for +providing fuzzing signal without blowing up logs. + Issue Suppression ================= @@ -245,17 +252,11 @@ UndefinedBehaviorSanitizer is supported on the following OS: * Android * Linux +* NetBSD * FreeBSD +* OpenBSD * OS X 10.6 onwards -and for the following architectures: - -* i386/x86\_64 -* ARM -* AArch64 -* PowerPC64 -* MIPS/MIPS64 - Current Status ============== diff --git a/docs/UsersManual.rst b/docs/UsersManual.rst index 023f9f5528ba..418afb2d546c 100644 --- a/docs/UsersManual.rst +++ b/docs/UsersManual.rst @@ -694,6 +694,79 @@ a special character, which is the convention used by GNU Make. The -MV option tells Clang to put double-quotes around the entire filename, which is the convention used by NMake and Jom. +Configuration files +------------------- + +Configuration files group command-line options and allow all of them to be +specified just by referencing the configuration file. They may be used, for +example, to collect options required to tune compilation for particular +target, such as -L, -I, -l, --sysroot, codegen options, etc. + +The command line option `--config` can be used to specify configuration +file in a Clang invocation. For example: + +:: + + clang --config /home/user/cfgs/testing.txt + clang --config debug.cfg + +If the provided argument contains a directory separator, it is considered as +a file path, and options are read from that file. Otherwise the argument is +treated as a file name and is searched for sequentially in the directories: + + - user directory, + - system directory, + - the directory where Clang executable resides. + +Both user and system directories for configuration files are specified during +clang build using CMake parameters, CLANG_CONFIG_FILE_USER_DIR and +CLANG_CONFIG_FILE_SYSTEM_DIR respectively. The first file found is used. It is +an error if the required file cannot be found. + +Another way to specify a configuration file is to encode it in executable name. +For example, if the Clang executable is named `armv7l-clang` (it may be a +symbolic link to `clang`), then Clang will search for file `armv7l.cfg` in the +directory where Clang resides. + +If a driver mode is specified in invocation, Clang tries to find a file specific +for the specified mode. For example, if the executable file is named +`x86_64-clang-cl`, Clang first looks for `x86_64-cl.cfg` and if it is not found, +looks for `x86_64.cfg`. + +If the command line contains options that effectively change target architecture +(these are -m32, -EL, and some others) and the configuration file starts with an +architecture name, Clang tries to load the configuration file for the effective +architecture. For example, invocation: + +:: + + x86_64-clang -m32 abc.c + +causes Clang search for a file `i368.cfg` first, and if no such file is found, +Clang looks for the file `x86_64.cfg`. + +The configuration file consists of command-line options specified on one or +more lines. Lines composed of whitespace characters only are ignored as well as +lines in which the first non-blank character is `#`. Long options may be split +between several lines by a trailing backslash. Here is example of a +configuration file: + +:: + + # Several options on line + -c --target=x86_64-unknown-linux-gnu + + # Long option split between lines + -I/usr/lib/gcc/x86_64-linux-gnu/5.4.0/../../../../\ + include/c++/5.4.0 + + # other config files may be included + @linux.options + +Files included by `@file` directives in configuration files are resolved +relative to the including file. For example, if a configuration file +`~/.llvm/target.cfg` contains the directive `@os/linux.opts`, the file +`linux.opts` is searched for in the directory `~/.llvm/os`. Language and Target-Independent Features ======================================== @@ -1002,7 +1075,7 @@ location. Building a relocatable precompiled header requires two additional arguments. First, pass the ``--relocatable-pch`` flag to indicate that the resulting PCH file should be relocatable. Second, pass -`-isysroot /path/to/build`, which makes all includes for your library +``-isysroot /path/to/build``, which makes all includes for your library relative to the build directory. For example: .. code-block:: console @@ -1012,9 +1085,9 @@ relative to the build directory. For example: When loading the relocatable PCH file, the various headers used in the PCH file are found from the system header root. For example, ``mylib.h`` can be found in ``/usr/include/mylib.h``. If the headers are installed -in some other system root, the `-isysroot` option can be used provide +in some other system root, the ``-isysroot`` option can be used provide a different system root from which the headers will be based. For -example, `-isysroot /Developer/SDKs/MacOSX10.4u.sdk` will look for +example, ``-isysroot /Developer/SDKs/MacOSX10.4u.sdk`` will look for ``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``. Relocatable precompiled headers are intended to be used in a limited @@ -1182,12 +1255,26 @@ are listed below. flushed-to-zero number is preserved in the sign of 0, denormals are flushed to positive zero, respectively. +.. option:: -f[no-]strict-float-cast-overflow + + When a floating-point value is not representable in a destination integer + type, the code has undefined behavior according to the language standard. + By default, Clang will not guarantee any particular result in that case. + With the 'no-strict' option, Clang attempts to match the overflowing behavior + of the target's native float-to-int conversion instructions. + .. option:: -fwhole-program-vtables Enable whole-program vtable optimizations, such as single-implementation devirtualization and virtual constant propagation, for classes with :doc:`hidden LTO visibility <LTOVisibility>`. Requires ``-flto``. +.. option:: -fforce-emit-vtables + + In order to improve devirtualization, forces emitting of vtables even in + modules where it isn't necessary. It causes more inline virtual functions + to be emitted. + .. option:: -fno-assume-sane-operator-new Don't assume that the C++'s new operator is sane. @@ -1295,6 +1382,15 @@ are listed below. // value of -fmax-type-align. } +.. option:: -faddrsig, -fno-addrsig + + Controls whether Clang emits an address-significance table into the object + file. Address-significance tables allow linkers to implement `safe ICF + <https://research.google.com/pubs/archive/36912.pdf>`_ without the false + positives that can result from other implementation techniques such as + relocation scanning. Address-significance tables are enabled by default + on ELF targets when using the integrated assembler. This flag currently + only has an effect on ELF targets. Profile Guided Optimization --------------------------- @@ -1302,7 +1398,8 @@ 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. +frequently than another function ``bar`` helps the inliner. Optimization +levels ``-O2`` and above are recommended for use of profile guided optimization. Clang supports profile guided optimization with two different kinds of profiling. A sampling profiler can generate a profile with very low runtime @@ -1653,11 +1750,11 @@ profile creation and use. .. option:: -fprofile-generate[=<dirname>] The ``-fprofile-generate`` and ``-fprofile-generate=`` flags will use - an alterantive instrumentation method for profile generation. When + an alternative instrumentation method for profile generation. When given a directory name, it generates the profile file ``default_%m.profraw`` in the directory named ``dirname`` if specified. If ``dirname`` does not exist, it will be created at runtime. ``%m`` specifier - will be substibuted with a unique id documented in step 2 above. In other words, + will be substituted with a unique id documented in step 2 above. In other words, with ``-fprofile-generate[=<dirname>]`` option, the "raw" profile data automatic merging is turned on by default, so there will no longer any risk of profile clobbering from different running processes. For example, @@ -1781,6 +1878,27 @@ features. You can "tune" the debug info for one of several different debuggers. must come first.) +Controlling LLVM IR Output +-------------------------- + +Controlling Value Names in LLVM IR +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Emitting value names in LLVM IR increases the size and verbosity of the IR. +By default, value names are only emitted in assertion-enabled builds of Clang. +However, when reading IR it can be useful to re-enable the emission of value +names to improve readability. + +.. option:: -fdiscard-value-names + + Discard value names when generating LLVM IR. + +.. option:: -fno-discard-value-names + + Do not discard value names when generating LLVM IR. This option can be used + to re-enable names for release builds of Clang. + + Comment Parsing Options ----------------------- @@ -1836,8 +1954,8 @@ Differences between various standard modes ------------------------------------------ clang supports the -std option, which changes what language mode clang -uses. The supported modes for C are c89, gnu89, c94, c99, gnu99, c11, -gnu11, and various aliases for those modes. If no -std option is +uses. The supported modes for C are c89, gnu89, c99, gnu99, c11, gnu11, +c17, gnu17, and various aliases for those modes. If no -std option is specified, clang defaults to gnu11 mode. Many C99 and C11 features are supported in earlier modes as a conforming extension, with a warning. Use ``-pedantic-errors`` to request an error if a feature from a later standard @@ -1884,8 +2002,9 @@ Differences between ``*99`` and ``*11`` modes: - Warnings for use of C11 features are disabled. - ``__STDC_VERSION__`` is defined to ``201112L`` rather than ``199901L``. -c94 mode is identical to c89 mode except that digraphs are enabled in -c94 mode (FIXME: And ``__STDC_VERSION__`` should be defined!). +Differences between ``*11`` and ``*17`` modes: + +- ``__STDC_VERSION__`` is defined to ``201710L`` rather than ``201112L``. GCC extensions not implemented yet ---------------------------------- @@ -2006,10 +2125,15 @@ Controlling implementation limits Sets the limit for recursive constexpr function invocations to N. The default is 512. +.. option:: -fconstexpr-steps=N + + Sets the limit for the number of full-expressions evaluated in a single + constant expression evaluation. The default is 1048576. + .. option:: -ftemplate-depth=N Sets the limit for recursively nested template instantiations to N. The - default is 256. + default is 1024. .. option:: -foperator-arrow-depth=N @@ -2042,6 +2166,11 @@ directives, and ``#pragma omp taskgroup`` directive. Use `-fopenmp` to enable OpenMP. Support for OpenMP can be disabled with `-fno-openmp`. +Use `-fopenmp-simd` to enable OpenMP simd features only, without linking +the runtime library; for combined constructs +(e.g. ``#pragma omp parallel for simd``) the non-simd directives and clauses +will be ignored. This can be disabled with `-fno-openmp-simd`. + Controlling implementation limits --------------------------------- @@ -2079,7 +2208,7 @@ to the target, for example: .. code-block:: console $ clang -target nvptx64-unknown-unknown test.cl - $ clang -target amdgcn-amd-amdhsa-opencl test.cl + $ clang -target amdgcn-amd-amdhsa -mcpu=gfx900 test.cl Compiling to bitcode can be done as follows: @@ -2187,7 +2316,7 @@ There is a set of concrete HW architectures that OpenCL can be compiled for. .. code-block:: console - $ clang -target amdgcn-amd-amdhsa-opencl test.cl + $ clang -target amdgcn-amd-amdhsa -mcpu=gfx900 test.cl - For Nvidia architectures: @@ -2584,10 +2713,37 @@ compatibility with the Visual C++ compiler, cl.exe. To enable clang-cl to find system headers, libraries, and the linker when run from the command-line, it should be executed inside a Visual Studio Native Tools Command Prompt or a regular Command Prompt where the environment has been set -up using e.g. `vcvars32.bat <http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_. +up using e.g. `vcvarsall.bat <http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_. + +clang-cl can also be used from inside Visual Studio by selecting the LLVM +Platform Toolset. The toolset is installed by the LLVM installer, which can be +downloaded from the `LLVM release <http://releases.llvm.org/download.html>`_ or +`snapshot build <http://llvm.org/builds/>`_ web pages. To use the toolset, +select a project in Solution Explorer, open its Property Page (Alt+F7), and in +the "General" section of "Configuration Properties" change "Platform Toolset" +to e.g. LLVM-vs2014. + +To use the toolset with MSBuild directly, invoke it with e.g. +``/p:PlatformToolset=LLVM-vs2014``. This allows trying out the clang-cl +toolchain without modifying your project files. + +It's also possible to point MSBuild at clang-cl without changing toolset by +passing ``/p:CLToolPath=c:\llvm\bin /p:CLToolExe=clang-cl.exe``. + +When using CMake and the Visual Studio generators, the toolset can be set with the ``-T`` flag: + + :: + + cmake -G"Visual Studio 15 2017" -T LLVM-vs2014 .. + +When using CMake with the Ninja generator, set the ``CMAKE_C_COMPILER`` and +``CMAKE_CXX_COMPILER`` variables to clang-cl: + + :: + + cmake -GNinja -DCMAKE_C_COMPILER="c:/Program Files (x86)/LLVM/bin/clang-cl.exe" + -DCMAKE_CXX_COMPILER="c:/Program Files (x86)/LLVM/bin/clang-cl.exe" .. -clang-cl can also be used from inside Visual Studio by using an LLVM Platform -Toolset. Command-Line Options -------------------- @@ -2654,6 +2810,7 @@ Execute ``clang-cl /?`` to see a list of supported options: /Gd Set __cdecl as a default calling convention /GF- Disable string pooling /GR- Disable emission of RTTI data + /Gregcall Set __regcall as a default calling convention /GR Enable emission of RTTI data /Gr Set __fastcall as a default calling convention /GS- Disable buffer security check @@ -2662,7 +2819,7 @@ Execute ``clang-cl /?`` to see a list of supported options: /Gv Set __vectorcall as a default calling convention /Gw- Don't put each data item in its own section /Gw Put each data item in its own section - /GX- Enable exception handling + /GX- Disable exception handling /GX Enable exception handling /Gy- Don't put each function in its own section /Gy Put each function in its own section @@ -2710,7 +2867,7 @@ Execute ``clang-cl /?`` to see a list of supported options: /W2 Enable -Wall /W3 Enable -Wall /W4 Enable -Wall and -Wextra - /Wall Enable -Wall and -Wextra + /Wall Enable -Weverything /WX- Do not treat warnings as errors /WX Treat warnings as errors /w Disable all warnings @@ -2767,6 +2924,8 @@ Execute ``clang-cl /?`` to see a list of supported options: Disable specified features of coverage instrumentation for Sanitizers -fno-sanitize-memory-track-origins Disable origins tracking in MemorySanitizer + -fno-sanitize-memory-use-after-dtor + Disable use-after-destroy detection in MemorySanitizer -fno-sanitize-recover=<value> Disable recovery for specified sanitizers -fno-sanitize-stats Disable sanitizer statistics gathering. @@ -2797,6 +2956,8 @@ Execute ``clang-cl /?`` to see a list of supported options: Path to blacklist file for sanitizers -fsanitize-cfi-cross-dso Enable control flow integrity (CFI) checks for cross-DSO calls. + -fsanitize-cfi-icall-generalize-pointers + Generalize pointers in CFI indirect call type signature checks -fsanitize-coverage=<value> Specify the type of coverage instrumentation for Sanitizers -fsanitize-memory-track-origins=<value> @@ -2820,6 +2981,7 @@ Execute ``clang-cl /?`` to see a list of supported options: -fsanitize=<check> Turn on runtime checks for various forms of undefined or suspicious behavior. See user manual for available checks -fstandalone-debug Emit full debug info for all types used by the program + -fwhole-program-vtables Enables whole-program vtable optimization. Requires -flto -gcodeview Generate CodeView debug information -gline-tables-only Emit debug line number tables only -miamcu Use Intel MCU ABI @@ -2828,6 +2990,7 @@ Execute ``clang-cl /?`` to see a list of supported options: -Qunused-arguments Don't emit warning for unused driver arguments -R<remark> Enable the specified remark --target=<value> Generate code for the given target + --version Print version information -v Show commands to run and use verbose output -W<warning> Enable the specified warning -Xclang <arg> Pass <arg> to the clang compiler diff --git a/docs/analyzer/DesignDiscussions/InitializerLists.rst b/docs/analyzer/DesignDiscussions/InitializerLists.rst index b826547bf12c..af41e4ec8f0a 100644 --- a/docs/analyzer/DesignDiscussions/InitializerLists.rst +++ b/docs/analyzer/DesignDiscussions/InitializerLists.rst @@ -21,7 +21,7 @@ This fix is overly conservative though. So i did a bit of investigation as to how model std::initializer_list better. According to the standard, std::initializer_list<T> is an object that has -methods begin(), end(), and size(), where begin() returns a pointer to continous +methods begin(), end(), and size(), where begin() returns a pointer to continuous array of size() objects of type T, and end() is equal to begin() plus size(). The standard does hint that it should be possible to implement std::initializer_list<T> as a pair of pointers, or as a pointer and a size diff --git a/docs/conf.py b/docs/conf.py index a12f99ad6d9a..b38c93af23c2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -49,9 +49,9 @@ copyright = u'2007-%d, The Clang Team' % date.today().year # built documents. # # The short version. -version = '6' +version = '7' # The full version, including alpha/beta/rc tags. -release = '6' +release = '7' # 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 13ed72222bea..61f9120017f1 100644 --- a/docs/doxygen.cfg.in +++ b/docs/doxygen.cfg.in @@ -174,7 +174,7 @@ JAVADOC_AUTOBRIEF = YES # If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first # line (until the first dot) of a Qt-style comment as the brief description. If # set to NO, the Qt-style will behave just like regular Qt-style comments (thus -# requiring an explicit \brief command for a brief description.) +# requiring an explicit command for a brief description.) # The default value is: NO. QT_AUTOBRIEF = YES @@ -284,7 +284,7 @@ MARKDOWN_SUPPORT = YES # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can -# be prevented in individual cases by by putting a % sign in front of the word +# be prevented in individual cases by putting a % sign in front of the word # or globally by setting AUTOLINK_SUPPORT to NO. # The default value is: YES. @@ -1065,7 +1065,7 @@ HTML_STYLESHEET = # defined cascading style sheet that is included after the standard style sheets # created by doxygen. Using this option one can overrule certain style aspects. # This is preferred over using HTML_STYLESHEET since it does not replace the -# standard style sheet and is therefor more robust against future updates. +# standard style sheet and is therefore more robust against future updates. # Doxygen will copy the style sheet file to the output directory. For an example # see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. diff --git a/docs/index.rst b/docs/index.rst index 342ab74d2d80..be7a371cd711 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -36,9 +36,11 @@ Using Clang as a Compiler ControlFlowIntegrity LTOVisibility SafeStack + ShadowCallStack SourceBasedCodeCoverage Modules MSVCCompatibility + OpenMPSupport ThinLTO CommandGuide/index FAQ diff --git a/docs/tools/dump_ast_matchers.py b/docs/tools/dump_ast_matchers.py index 45540405de97..d38977548fd9 100644 --- a/docs/tools/dump_ast_matchers.py +++ b/docs/tools/dump_ast_matchers.py @@ -95,7 +95,7 @@ def strip_doxygen(comment): def unify_arguments(args): """Gets rid of anything the user doesn't care about in the argument list.""" args = re.sub(r'internal::', r'', args) - args = re.sub(r'const\s+(.*)&', r'\1 ', args) + args = re.sub(r'extern const\s+(.*)&', r'\1 ', args) args = re.sub(r'&', r' ', args) args = re.sub(r'(^|\s)M\d?(\s)', r'\1Matcher<*>\2', args) return args @@ -150,11 +150,11 @@ def act_on_decl(declaration, comment, allowed_types): comment, is_dyncast=True) return - # Parse the various matcher definition macros. - m = re.match(""".*AST_TYPE_MATCHER\( - \s*([^\s,]+\s*), - \s*([^\s,]+\s*) - \)\s*;\s*$""", declaration, flags=re.X) + # Special case of type matchers: + # AstTypeMatcher<ArgumentType> name + m = re.match(r""".*AstTypeMatcher\s*< + \s*([^\s>]+)\s*> + \s*([^\s;]+)\s*;\s*$""", declaration, flags=re.X) if m: inner, name = m.groups() add_matcher('Type', name, 'Matcher<%s>...' % inner, @@ -165,7 +165,8 @@ def act_on_decl(declaration, comment, allowed_types): # comment, is_dyncast=True) return - m = re.match(""".*AST_TYPE(LOC)?_TRAVERSE_MATCHER\( + # Parse the various matcher definition macros. + m = re.match(""".*AST_TYPE(LOC)?_TRAVERSE_MATCHER(?:_DECL)?\( \s*([^\s,]+\s*), \s*(?:[^\s,]+\s*), \s*AST_POLYMORPHIC_SUPPORTED_TYPES\(([^)]*)\) @@ -236,7 +237,7 @@ def act_on_decl(declaration, comment, allowed_types): (?:,\s*([^\s,]+)\s* ,\s*([^\s,]+)\s*)? (?:,\s*\d+\s*)? - \)\s*{\s*$""", declaration, flags=re.X) + \)\s*{""", declaration, flags=re.X) if m: p, n, result, name = m.groups()[0:4] args = m.groups()[4:] @@ -256,8 +257,8 @@ def act_on_decl(declaration, comment, allowed_types): # Parse ArgumentAdapting matchers. m = re.match( - r"""^.*ArgumentAdaptingMatcherFunc<.*>\s*(?:LLVM_ATTRIBUTE_UNUSED\s*) - ([a-zA-Z]*)\s*=\s*{};$""", + r"""^.*ArgumentAdaptingMatcherFunc<.*>\s* + ([a-zA-Z]*);$""", declaration, flags=re.X) if m: name = m.groups()[0] @@ -267,7 +268,7 @@ def act_on_decl(declaration, comment, allowed_types): # Parse Variadic functions. m = re.match( r"""^.*internal::VariadicFunction\s*<\s*([^,]+),\s*([^,]+),\s*[^>]+>\s* - ([a-zA-Z]*)\s*=\s*{.*};$""", + ([a-zA-Z]*);$""", declaration, flags=re.X) if m: result, arg, name = m.groups()[:3] @@ -276,15 +277,15 @@ def act_on_decl(declaration, comment, allowed_types): # Parse Variadic operator matchers. m = re.match( - r"""^.*VariadicOperatorMatcherFunc\s*<\s*([^,]+),\s*([^\s>]+)\s*>\s* - ([a-zA-Z]*)\s*=\s*{.*};$""", + r"""^.*VariadicOperatorMatcherFunc\s*<\s*([^,]+),\s*([^\s]+)\s*>\s* + ([a-zA-Z]*);$""", declaration, flags=re.X) if m: min_args, max_args, name = m.groups()[:3] if max_args == '1': add_matcher('*', name, 'Matcher<*>', comment) return - elif max_args == 'UINT_MAX': + elif max_args == 'std::numeric_limits<unsigned>::max()': add_matcher('*', name, 'Matcher<*>, ..., Matcher<*>', comment) return diff --git a/docs/tools/dump_format_style.py b/docs/tools/dump_format_style.py index 1ca050e062b7..3d61227f7361 100644 --- a/docs/tools/dump_format_style.py +++ b/docs/tools/dump_format_style.py @@ -10,6 +10,7 @@ import urllib2 CLANG_DIR = os.path.join(os.path.dirname(__file__), '../..') FORMAT_STYLE_FILE = os.path.join(CLANG_DIR, 'include/clang/Format/Format.h') +INCLUDE_STYLE_FILE = os.path.join(CLANG_DIR, 'include/clang/Tooling/Inclusions/IncludeStyle.h') DOC_FILE = os.path.join(CLANG_DIR, 'docs/ClangFormatStyleOptions.rst') @@ -115,7 +116,7 @@ def read_options(header): for line in header: line = line.strip() if state == State.BeforeStruct: - if line == 'struct FormatStyle {': + if line == 'struct FormatStyle {' or line == 'struct IncludeStyle {': state = State.InStruct elif state == State.InStruct: if line.startswith('///'): @@ -188,6 +189,7 @@ def read_options(header): return options options = read_options(open(FORMAT_STYLE_FILE)) +options += read_options(open(INCLUDE_STYLE_FILE)) options = sorted(options, key=lambda x: x.name) options_text = '\n\n'.join(map(str, options)) |