diff options
Diffstat (limited to 'clang/docs')
| -rw-r--r-- | clang/docs/InternalsManual.rst | 42 | ||||
| -rw-r--r-- | clang/docs/LanguageExtensions.rst | 24 | ||||
| -rw-r--r-- | clang/docs/ReleaseNotes.rst | 11 | ||||
| -rw-r--r-- | clang/docs/ShadowCallStack.rst | 2 | ||||
| -rw-r--r-- | clang/docs/ThinLTO.rst | 25 | ||||
| -rw-r--r-- | clang/docs/analyzer/user-docs/CrossTranslationUnit.rst | 4 |
6 files changed, 67 insertions, 41 deletions
diff --git a/clang/docs/InternalsManual.rst b/clang/docs/InternalsManual.rst index 8a44db7..756db85 100644 --- a/clang/docs/InternalsManual.rst +++ b/clang/docs/InternalsManual.rst @@ -139,7 +139,7 @@ wording a diagnostic. you mean %1?``. * Appropriately capitalize proper nouns like ``Clang``, ``OpenCL``, ``GCC``, - ``Objective-C``, etc and language standard versions like ``C11`` or ``C++11``. + ``Objective-C``, etc. and language standard versions like ``C11`` or ``C++11``. * The wording should be succinct. If necessary, use a semicolon to combine sentence fragments instead of using complete sentences. e.g., prefer wording like ``'%0' is deprecated; it will be removed in a future release of Clang`` @@ -312,7 +312,7 @@ Description: * number: A simple decimal number matches if the argument is the same as the number. Example: ``"%plural{1:mouse|:mice}0"`` * range: A range in square brackets matches if the argument is within the - range. Then range is inclusive on both ends. Example: + range. The range is inclusive on both ends. Example: ``"%plural{0:none|1:one|[2,5]:some|:many}0"`` * modulo: A modulo operator is followed by a number, and equals sign and either a number or a range. The tests are the same as for plain numbers @@ -341,7 +341,7 @@ Example: Class: Integers Description: - This is a formatter which represents the argument number in a human readable + This is a formatter which represents the argument number in a human-readable format: the value ``123`` stays ``123``, ``12345`` becomes ``12.34k``, ``6666666` becomes ``6.67M``, and so on for 'G' and 'T'. @@ -561,7 +561,7 @@ documentation for the ``-verify`` mode can be found at There are many other possible implementations of this interface, and this is why we prefer diagnostics to pass down rich structured information in -arguments. For example, an HTML output might want declaration names be +arguments. For example, an HTML output might want declaration names to be linkified to where they come from in the source. Another example is that a GUI might let you click on typedefs to expand them. This application would want to pass significantly more information about types through to the GUI than a @@ -846,7 +846,7 @@ Option Marshalling Infrastructure The option marshalling infrastructure automates the parsing of the Clang ``-cc1`` frontend command line arguments into ``CompilerInvocation`` and their generation from ``CompilerInvocation``. The system replaces lots of repetitive -C++ code with simple, declarative tablegen annotations and it's being used for +C++ code with simple, declarative tablegen annotations and is being used for the majority of the ``-cc1`` command line interface. This section provides an overview of the system. @@ -886,7 +886,7 @@ a string that the tablegen backend uses as a prefix to the LANG_OPTION_WITH_MARSHALLING([...], LangOpts->IgnoreExceptions, [...]) #endif // LANG_OPTION_WITH_MARSHALLING -Such definition can be used used in the function for parsing and generating +Such definition can be used in the function for parsing and generating command line: .. code-block:: c++ @@ -986,7 +986,7 @@ line. NegFlag<SetFalse, [], [], "Use the new pass manager in LLVM">, BothFlags<[], [ClangOption, CC1Option]>>; -With most such pair of flags, the ``-cc1`` frontend accepts only the flag that +With most such pairs of flags, the ``-cc1`` frontend accepts only the flag that changes the default key path value. The Clang driver is responsible for accepting both and either forwarding the changing flag or discarding the flag that would just set the key path to its default. @@ -1042,8 +1042,8 @@ and the result is assigned to the key path on success. The key path defaults to the value specified in ``MarshallingInfoEnum`` prefixed by the contents of ``NormalizedValuesScope`` and ``::``. This ensures correct reference to an enum case is formed even if the enum resides in different -namespace or is an enum class. If the value present on command line does not -match any of the comma-separated values from ``Values``, an error diagnostics is +namespace or is an enum class. If the value present on the command line does not +match any of the comma-separated values from ``Values``, an error diagnostic is issued. Otherwise, the corresponding element from ``NormalizedValues`` at the same index is assigned to the key path (also correctly scoped). The number of comma-separated string values and elements of the array within @@ -1111,7 +1111,7 @@ The Token class --------------- The ``Token`` class is used to represent a single lexed token. Tokens are -intended to be used by the lexer/preprocess and parser libraries, but are not +intended to be used by the lexer/preprocessor and parser libraries, but are not intended to live beyond them (for example, they should not live in the ASTs). Tokens most often live on the stack (or some other location that is efficient @@ -1253,7 +1253,7 @@ In order to do this, whenever the parser expects a ``tok::identifier`` or ``tok::coloncolon``, it should call the ``TryAnnotateTypeOrScopeToken`` or ``TryAnnotateCXXScopeToken`` methods to form the annotation token. These methods will maximally form the specified annotation tokens and replace the -current token with them, if applicable. If the current tokens is not valid for +current token with them, if applicable. If the current token is not valid for an annotation token, it will remain an identifier or "``::``" token. .. _Lexer: @@ -1276,7 +1276,7 @@ The lexer has a couple of interesting modal features: This mode is used for lexing within an "``#if 0``" block, for example. * The lexer can capture and return comments as tokens. This is required to support the ``-C`` preprocessor mode, which passes comments through, and is - used by the diagnostic checker to identifier expect-error annotations. + used by the diagnostic checker to identify expect-error annotations. * The lexer can be in ``ParsingFilename`` mode, which happens when preprocessing after reading a ``#include`` directive. This mode changes the parsing of "``<``" to return an "angled string" instead of a bunch of tokens @@ -1308,7 +1308,7 @@ The ``TokenLexer`` class ------------------------ The ``TokenLexer`` class is a token provider that returns tokens from a list of -tokens that came from somewhere else. It typically used for two things: 1) +tokens that came from somewhere else. It is typically used for two things: 1) returning tokens from a macro definition as it is being expanded 2) returning tokens from an arbitrary buffer of tokens. The later use is used by ``_Pragma`` and will most likely be used to handle unbounded look-ahead for the @@ -1509,7 +1509,7 @@ type checker must verify that the operand has a pointer type. It would not be correct to check that with "``isa<PointerType>(SubExpr->getType())``", because this predicate would fail if the subexpression had a typedef type. -The solution to this problem are a set of helper methods on ``Type``, used to +The solution to this problem is a set of helper methods on ``Type``, used to check their properties. In this case, it would be correct to use "``SubExpr->getType()->isPointerType()``" to do the check. This predicate will return true if the *canonical type is a pointer*, which is true any time the @@ -1632,7 +1632,7 @@ the names are inside the ``DeclarationName`` class). ``CXXLiteralOperatorName`` - The name is a C++11 user defined literal operator. User defined + The name is a C++11 user-defined literal operator. User-defined Literal operators are named according to the suffix they define, e.g., "``_foo``" for "``operator "" _foo``". Use ``N.getCXXLiteralIdentifier()`` to retrieve the corresponding @@ -1745,7 +1745,7 @@ will be found by the lookup, since it effectively replaces the first declaration of "``f``". (Note that because ``f`` can be redeclared at block scope, or in a friend -declaration, etc. it is possible that the declaration of ``f`` found by name +declaration, etc., it is possible that the declaration of ``f`` found by name lookup will not be the most recent one.) In the semantics-centric view, overloading of functions is represented @@ -1945,7 +1945,7 @@ range of iterators over declarations of "``f``". function ``DeclContext::getPrimaryContext`` retrieves the "primary" context for a given ``DeclContext`` instance, which is the ``DeclContext`` responsible for maintaining the lookup table used for the semantics-centric view. Given a -DeclContext, one can obtain the set of declaration contexts that are +``DeclContext``, one can obtain the set of declaration contexts that are semantically connected to this declaration context, in source order, including this context (which will be the only result, for non-namespace contexts) via ``DeclContext::collectAllContexts``. Note that these functions are used @@ -1985,7 +1985,7 @@ broken code in the AST: errors, the Decl node is marked as invalid. - dropping invalid node: this often happens for errors that we don’t have graceful recovery. Prior to Recovery AST, a mismatched-argument function call - expression was dropped though a CallExpr was created for semantic analysis. + expression was dropped though a ``CallExpr`` was created for semantic analysis. With these strategies, clang surfaces better diagnostics, and provides AST consumers a rich AST reflecting the written source code as much as possible even @@ -2215,7 +2215,7 @@ Consequently, we must either set the virtual flag for the definition (but then we create a malformed AST which the parser would never create), or we import the whole redeclaration chain of the function. The most recent version of the ``ASTImporter`` uses the latter mechanism. We do import all function -declarations - regardless if they are definitions or prototypes - in the order +declarations - regardless of whether they are definitions or prototypes - in the order as they appear in the "from" context. .. One definition @@ -2338,7 +2338,7 @@ library receive an Error object, which they must check. During import of a specific declaration, it may happen that some AST nodes had already been created before we recognize an error. In this case, we signal back the error to the caller, but the "to" context remains polluted with those nodes -which had been created. Ideally, those nodes should not had been created, but +which had been created. Ideally, those nodes should not have been created, but that time we did not know about the error, the error happened later. Since the AST is immutable (most of the cases we can't remove existing nodes) we choose to mark these nodes as erroneous. @@ -2579,7 +2579,7 @@ that there are global declarations which collide with declarations from other translation units, but they are not referenced outside from their translation unit. These declarations should be in an unnamed namespace ideally. If we treat these collisions liberally then CTU analysis can find more results. Note, the -feature be able to choose between name conflict handling strategies is still an +feature to be able to choose between name conflict handling strategies is still an ongoing work. .. _CFG: diff --git a/clang/docs/LanguageExtensions.rst b/clang/docs/LanguageExtensions.rst index 29ef20f..b5bb198 100644 --- a/clang/docs/LanguageExtensions.rst +++ b/clang/docs/LanguageExtensions.rst @@ -2018,7 +2018,7 @@ even if there is no valid ``std::tuple_element`` specialization or suitable Blocks ====== -The syntax and high level language feature description is in +The syntax and high-level language feature description is in :doc:`BlockLanguageSpec<BlockLanguageSpec>`. Implementation and ABI details for the clang implementation are in :doc:`Block-ABI-Apple<Block-ABI-Apple>`. @@ -2088,7 +2088,7 @@ producing an object with the following member functions constexpr size_t size() const; such as ``std::string``, ``std::string_view``, ``std::vector<char>``. -This mechanism follow the same rules as ``static_assert`` messages in +This mechanism follows the same rules as ``static_assert`` messages in C++26, see ``[dcl.pre]/p12``. Query for this feature with ``__has_extension(gnu_asm_constexpr_strings)``. @@ -2335,7 +2335,7 @@ Objective-C Autosynthesis of Properties Clang provides support for autosynthesis of declared properties. Using this feature, clang provides default synthesis of those properties not declared -@dynamic and not having user provided backing getter and setter methods. +@dynamic and not having user-provided backing getter and setter methods. ``__has_feature(objc_default_synthesize_properties)`` checks for availability of this feature in version of clang being used. @@ -2349,7 +2349,7 @@ In Objective-C, functions and methods are generally assumed to follow the <https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmRules.html>`_ conventions for ownership of object arguments and return values. However, there are exceptions, and so Clang provides attributes -to allow these exceptions to be documented. This are used by ARC and the +to allow these exceptions to be documented. These are used by ARC and the `static analyzer <https://clang-analyzer.llvm.org>`_ Some exceptions may be better described using the ``objc_method_family`` attribute instead. @@ -2575,7 +2575,7 @@ Such functionality is not conformant and does not guarantee to compile correctly in any circumstances. It can be used if: - the kernel source does not contain call expressions to (member-) function - pointers, or virtual functions. For example this extension can be used in + pointers, or virtual functions. For example, this extension can be used in metaprogramming algorithms to be able to specify/detect types generically. - the generated kernel binary does not contain indirect calls because they @@ -2613,7 +2613,7 @@ functions with variadic prototypes do not get generated in binary e.g. the variadic prototype is used to specify a function type with any number of arguments in metaprogramming algorithms in C++ for OpenCL. -This extensions can also be used when the kernel code is intended for targets +This extension can also be used when the kernel code is intended for targets supporting the variadic arguments e.g. majority of CPU targets. **Example of Use**: @@ -2702,7 +2702,7 @@ address space qualifiers, therefore, other type qualifiers such as Legacy 1.x atomics with generic address space --------------------------------------------- -Clang allows use of atomic functions from the OpenCL 1.x standards +Clang allows the use of atomic functions from the OpenCL 1.x standards with the generic address space pointer in C++ for OpenCL mode. This is a non-portable feature and might not be supported by all @@ -2833,7 +2833,7 @@ to a possibly overlapping destination region. It takes five arguments. The first argument is the destination WebAssembly table, and the second argument is the source WebAssembly table. The third argument is the destination index from where the copy starts, the fourth argument is the -source index from there the copy starts, and the fifth and last argument +source index from where the copy starts, and the fifth and last argument is the number of elements to copy. It returns nothing. .. code-block:: c++ @@ -3133,7 +3133,7 @@ Query for this feature with ``__has_builtin(__builtin_get_vtable_pointer)``. ------------------------------------ ``__builtin_call_with_static_chain`` is used to perform a static call while -setting updating the static chain register. +updating the static chain register. **Syntax**: @@ -3245,7 +3245,7 @@ Query for this feature with ``__has_builtin(__builtin_readsteadycounter)``. The ``__builtin_cpu_supports`` function detects if the run-time CPU supports features specified in string argument. It returns a positive integer if all features are supported and 0 otherwise. Feature names are target specific. On -AArch64 features are combined using ``+`` like this +AArch64, features are combined using ``+`` like this ``__builtin_cpu_supports("flagm+sha3+lse+rcpc2+fcma+memtag+bti+sme2")``. If a feature name is not supported, Clang will issue a warning and replace builtin by the constant 0. @@ -3465,7 +3465,7 @@ Query for this feature with ``__has_builtin(__builtin_convertvector)``. **Description**: The '``__builtin_bitreverse``' family of builtins is used to reverse -the bitpattern of an integer value; for example ``0b10110110`` becomes +the bitpattern of an integer value; for example, ``0b10110110`` becomes ``0b01101101``. These builtins can be used within constant expressions. ``__builtin_rotateleft`` @@ -3970,7 +3970,7 @@ the debugging experience. ``__builtin_allow_runtime_check`` returns true if the check at the current program location should be executed. It is expected to be used to implement -``assert`` like checks which can be safely removed by optimizer. +``assert`` like checks which can be safely removed by the optimizer. **Syntax**: diff --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst index 9d9a000..0bd4857 100644 --- a/clang/docs/ReleaseNotes.rst +++ b/clang/docs/ReleaseNotes.rst @@ -123,6 +123,8 @@ Improvements to Clang's diagnostics Moved the warning for a missing (though implied) attribute on a redeclaration into this group. Added a new warning in this group for the case where the attribute is missing/implicit on an override of a virtual method. +- Fixed fix-it hint for fold expressions. Clang now correctly places the suggested right + parenthesis when diagnosing malformed fold expressions. (#GH151787) Improvements to Clang's time-trace ---------------------------------- @@ -134,6 +136,11 @@ Bug Fixes in This Version ------------------------- - Fix a crash when marco name is empty in ``#pragma push_macro("")`` or ``#pragma pop_macro("")``. (#GH149762). +- `-Wunreachable-code`` now diagnoses tautological or contradictory + comparisons such as ``x != 0 || x != 1.0`` and ``x == 0 && x == 1.0`` on + targets that treat ``_Float16``/``__fp16`` as native scalar types. Previously + the warning was silently lost because the operands differed only by an implicit + cast chain. (#GH149967). Bug Fixes to Compiler Builtins ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -236,12 +243,16 @@ Static Analyzer --------------- - The Clang Static Analyzer now handles parenthesized initialization. (#GH148875) +- ``__datasizeof`` (C++) and ``_Countof`` (C) no longer cause a failed assertion + when given an operand of VLA type. (#GH151711) New features ^^^^^^^^^^^^ Crash and bug fixes ^^^^^^^^^^^^^^^^^^^ +- Fixed a crash in the static analyzer that when the expression in an + ``[[assume(expr)]]`` attribute was enclosed in parentheses. (#GH151529) Improvements ^^^^^^^^^^^^ diff --git a/clang/docs/ShadowCallStack.rst b/clang/docs/ShadowCallStack.rst index fc8bea8..9b104cc 100644 --- a/clang/docs/ShadowCallStack.rst +++ b/clang/docs/ShadowCallStack.rst @@ -61,7 +61,7 @@ The instrumentation makes use of the platform register ``x18`` on AArch64, ``x3`` (``gp``) on RISC-V with software shadow stack and ``ssp`` on RISC-V with hardware shadow stack, which needs `Zicfiss`_ and ``-fcf-protection=return``. Users can choose between the software and hardware based shadow stack -implementation on RISC-V backend by passing ``-fsanitize=shadowcallstack`` +implementation on RISC-V backend by passing ``-fsanitize=shadow-call-stack`` or ``Zicfiss`` with ``-fcf-protection=return``. For simplicity we will refer to this as the ``SCSReg``. On some platforms, ``SCSReg`` is reserved, and on others, it is designated as a scratch register. diff --git a/clang/docs/ThinLTO.rst b/clang/docs/ThinLTO.rst index 569405f..8cb3e0b 100644 --- a/clang/docs/ThinLTO.rst +++ b/clang/docs/ThinLTO.rst @@ -249,6 +249,9 @@ during the traditional link step. The implementation is documented here: https://llvm.org/docs/DTLTO.html. +Command-Line Options +^^^^^^^^^^^^^^^^^^^^ + DTLTO requires the LLD linker (``-fuse-ld=lld``). ``-fthinlto-distributor=<path>`` @@ -260,17 +263,29 @@ DTLTO requires the LLD linker (``-fuse-ld=lld``). - Can be specified multiple times to pass multiple options. - Multiple options can also be specified by separating them with commas. -Examples: - - ``clang -flto=thin -fthinlto-distributor=incredibuild.exe -Xthinlto-distributor=--verbose,--j10 -fuse-ld=lld`` - - ``clang -flto=thin -fthinlto-distributor=$(which python) -Xthinlto-distributor=incredibuild.py -fuse-ld=lld`` - If ``-fthinlto-distributor=`` is specified, Clang supplies the path to a compiler to be executed remotely to perform the ThinLTO backend compilations. Currently, this is Clang itself. +Usage +^^^^^ + +Compilation is unchanged from ThinLTO. DTLTO options need to supplied for the link step: + +.. code-block:: console + + % clang -flto=thin -fthinlto-distributor=distribute.sh -Xthinlto-distributor=--verbose,--j10 -fuse-ld=lld file1.o file2.o + % clang -flto=thin -fthinlto-distributor=$(which python) -Xthinlto-distributor=distribute.py -fuse-ld=lld file1.o file2.o + +When using lld-link: + +.. code-block:: console + + % lld-link /out:a.exe file1.obj file2.obj /thinlto-distributor:distribute.exe /thinlto-remote-compiler:${LLVM}\bin\clang.exe /thinlto-distributor-arg:--verbose + Note that currently, DTLTO is only supported in some LLD flavors. Support can be added to other LLD flavours in the future. -See `DTLTO <https://lld.llvm.org/dtlto.html>`_ for more information. +See `DTLTO <https://lld.llvm.org/DTLTO.html>`_ for more information. More Information ================ diff --git a/clang/docs/analyzer/user-docs/CrossTranslationUnit.rst b/clang/docs/analyzer/user-docs/CrossTranslationUnit.rst index 700dac0..a04b9f8 100644 --- a/clang/docs/analyzer/user-docs/CrossTranslationUnit.rst +++ b/clang/docs/analyzer/user-docs/CrossTranslationUnit.rst @@ -132,7 +132,7 @@ Once we have set up the `PATH` environment variable and we activated the python .. code-block:: bash - $ CodeChecker analyze --ctu compile_commands.json -o reports + $ CodeChecker analyze --ctu --ctu-ast-mode load-from-pch compile_commands.json -o reports $ ls -F compile_commands.json foo.cpp foo.cpp.ast main.cpp reports/ $ tree reports @@ -318,7 +318,7 @@ Once we have set up the `PATH` environment variable and we activated the python .. code-block:: bash - $ CodeChecker analyze --ctu --ctu-ast-loading-mode on-demand compile_commands.json -o reports + $ CodeChecker analyze --ctu compile_commands.json -o reports $ ls -F compile_commands.json foo.cpp main.cpp reports/ $ tree reports |