clang-tools-extra/docs/ReleaseNotes.rst

   1 ====================================================
   2 Extra Clang Tools |release| |ReleaseNotesTitle|
   3 ====================================================
   4
   5 .. contents::
   6    :local:
   7    :depth: 3
   8
   9 Written by the `LLVM Team <https://llvm.org/>`_
  10
  11 .. only:: PreRelease
  12
  13   .. warning::
  14      These are in-progress notes for the upcoming Extra Clang Tools |version| release.
  15      Release notes for previous releases can be found on
  16      `the Download Page <https://releases.llvm.org/download.html>`_.
  17
  18 Introduction
  19 ============
  20
  21 This document contains the release notes for the Extra Clang Tools, part of the
  22 Clang release |release|. Here we describe the status of the Extra Clang Tools in
  23 some detail, including major improvements from the previous release and new
  24 feature work. All LLVM releases may be downloaded from the `LLVM releases web
  25 site <https://llvm.org/releases/>`_.
  26
  27 For more information about Clang or LLVM, including information about
  28 the latest release, please see the `Clang Web Site <https://clang.llvm.org>`_ or
  29 the `LLVM Web Site <https://llvm.org>`_.
  30
  31 Note that if you are reading this file from a Git checkout or the
  32 main Clang web page, this document applies to the *next* release, not
  33 the current one. To see the release notes for a specific release, please
  34 see the `releases page <https://llvm.org/releases/>`_.
  35
  36 What's New in Extra Clang Tools |release|?
  37 ==========================================
  38
  39 Some of the major new features and improvements to Extra Clang Tools are listed
  40 here. Generic improvements to Extra Clang Tools as a whole or to its underlying
  41 infrastructure are described first, followed by tool-specific sections.
  42
  43 Major New Features
  44 ------------------
  45
  46 ...
  47
  48 Improvements to clangd
  49 ----------------------
  50
  51 Inlay hints
  52 ^^^^^^^^^^^
  53
  54 Diagnostics
  55 ^^^^^^^^^^^
  56
  57 Semantic Highlighting
  58 ^^^^^^^^^^^^^^^^^^^^^
  59
  60 Compile flags
  61 ^^^^^^^^^^^^^
  62
  63 Hover
  64 ^^^^^
  65
  66 Code completion
  67 ^^^^^^^^^^^^^^^
  68
  69 Code actions
  70 ^^^^^^^^^^^^
  71
  72 - The extract variable tweak gained support for extracting lambda expressions to a variable.
  73
  74 Signature help
  75 ^^^^^^^^^^^^^^
  76
  77 Cross-references
  78 ^^^^^^^^^^^^^^^^
  79
  80 Objective-C
  81 ^^^^^^^^^^^
  82
  83 Miscellaneous
  84 ^^^^^^^^^^^^^
  85
  86 Improvements to clang-doc
  87 -------------------------
  88
  89 Improvements to clang-query
  90 ---------------------------
  91
  92 The improvements are...
  93
  94 Improvements to clang-rename
  95 ----------------------------
  96
  97 The improvements are...
  98
  99 Improvements to clang-tidy
 100 --------------------------
 101
 102 - Preprocessor-level module header parsing is now disabled by default due to
 103   the problems it caused in C++20 and above, leading to performance and code
 104   parsing issues regardless of whether modules were used or not. This change
 105   will impact only the following checks:
 106   :doc:`modernize-replace-disallow-copy-and-assign-macro
 107   <clang-tidy/checks/modernize/replace-disallow-copy-and-assign-macro>`,
 108   :doc:`bugprone-reserved-identifier
 109   <clang-tidy/checks/bugprone/reserved-identifier>`, and
 110   :doc:`readability-identifier-naming
 111   <clang-tidy/checks/readability/identifier-naming>`. Those checks will no
 112   longer see macros defined in modules. Users can still enable this
 113   functionality using the newly added command line option
 114   `--enable-module-headers-parsing`.
 115
 116 - Remove configuration option `AnalyzeTemporaryDestructors`, which was deprecated since
 117   :program:`clang-tidy` 16.
 118
 119 - Improved `--dump-config` to print check options in alphabetical order.
 120
 121 - Improved :program:`clang-tidy-diff.py` script. It now returns exit code `1`
 122   if any :program:`clang-tidy` subprocess exits with a non-zero code or if
 123   exporting fixes fails. It now accepts a directory as a value for
 124   `-export-fixes` to export individual yaml files for each compilation unit.
 125
 126 - Improved :program:`run-clang-tidy.py` script. It now accepts a directory
 127   as a value for `-export-fixes` to export individual yaml files for each
 128   compilation unit.
 129
 130 New checks
 131 ^^^^^^^^^^
 132
 133 - New :doc:`bugprone-casting-through-void
 134   <clang-tidy/checks/bugprone/casting-through-void>` check.
 135
 136   Detects unsafe or redundant two-step casting operations involving ``void*``.
 137
 138 - New :doc:`bugprone-compare-pointer-to-member-virtual-function
 139   <clang-tidy/checks/bugprone/compare-pointer-to-member-virtual-function>` check.
 140
 141   Detects equality comparison between pointer to member virtual function and
 142   anything other than null-pointer-constant.
 143
 144 - New :doc:`bugprone-inc-dec-in-conditions
 145   <clang-tidy/checks/bugprone/inc-dec-in-conditions>` check.
 146
 147   Detects when a variable is both incremented/decremented and referenced inside
 148   a complex condition and suggests moving them outside to avoid ambiguity in
 149   the variable's value.
 150
 151 - New :doc:`bugprone-incorrect-enable-if
 152   <clang-tidy/checks/bugprone/incorrect-enable-if>` check.
 153
 154   Detects incorrect usages of ``std::enable_if`` that don't name the nested
 155   ``type`` type.
 156
 157 - New :doc:`bugprone-multi-level-implicit-pointer-conversion
 158   <clang-tidy/checks/bugprone/multi-level-implicit-pointer-conversion>` check.
 159
 160   Detects implicit conversions between pointers of different levels of
 161   indirection.
 162
 163 - New :doc:`bugprone-optional-value-conversion
 164   <clang-tidy/checks/bugprone/optional-value-conversion>` check.
 165
 166   Detects potentially unintentional and redundant conversions where a value is
 167   extracted from an optional-like type and then used to create a new instance
 168   of the same optional-like type.
 169
 170 - New :doc:`cppcoreguidelines-no-suspend-with-lock
 171   <clang-tidy/checks/cppcoreguidelines/no-suspend-with-lock>` check.
 172
 173   Flags coroutines that suspend while a lock guard is in scope at the
 174   suspension point.
 175
 176 - New :doc:`misc-coroutine-hostile-raii
 177   <clang-tidy/checks/misc/coroutine-hostile-raii>` check.
 178
 179   Detects when objects of certain hostile RAII types persists across suspension
 180   points in a coroutine. Such hostile types include scoped-lockable types and
 181   types belonging to a configurable denylist.
 182
 183 - New :doc:`modernize-use-constraints
 184   <clang-tidy/checks/modernize/use-constraints>` check.
 185
 186   Replace ``enable_if`` with C++20 requires clauses.
 187
 188 - New :doc:`performance-enum-size
 189   <clang-tidy/checks/performance/enum-size>` check.
 190
 191   Recommends the smallest possible underlying type for an ``enum`` or ``enum``
 192   class based on the range of its enumerators.
 193
 194 - New :doc:`readability-reference-to-constructed-temporary
 195   <clang-tidy/checks/readability/reference-to-constructed-temporary>` check.
 196
 197   Detects C++ code where a reference variable is used to extend the lifetime
 198   of a temporary object that has just been constructed.
 199
 200 New check aliases
 201 ^^^^^^^^^^^^^^^^^
 202
 203 - New alias :doc:`cppcoreguidelines-macro-to-enum
 204   <clang-tidy/checks/cppcoreguidelines/macro-to-enum>` to :doc:`modernize-macro-to-enum
 205   <clang-tidy/checks/modernize/macro-to-enum>` was added.
 206
 207 Changes in existing checks
 208 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 209
 210 - Improved :doc:`bugprone-dangling-handle
 211   <clang-tidy/checks/bugprone/dangling-handle>` check to support functional
 212   casting during type conversions at variable initialization, now with improved
 213   compatibility for C++17 and later versions.
 214
 215 - Improved :doc:`bugprone-lambda-function-name
 216   <clang-tidy/checks/bugprone/lambda-function-name>` check by adding option
 217   `IgnoreMacros` to ignore warnings in macros.
 218
 219 - Improved :doc:`bugprone-non-zero-enum-to-bool-conversion
 220   <clang-tidy/checks/bugprone/non-zero-enum-to-bool-conversion>` check by
 221   eliminating false positives resulting from direct usage of bitwise operators.
 222
 223 - Improved :doc:`bugprone-reserved-identifier
 224   <clang-tidy/checks/bugprone/reserved-identifier>` check, so that it does not
 225   warn on macros starting with underscore and lowercase letter.
 226
 227 - Improved :doc:`bugprone-unchecked-optional-access
 228   <clang-tidy/checks/bugprone/unchecked-optional-access>` check, so that it does
 229   not crash during handling of optional values.
 230
 231 - Improved :doc:`bugprone-undefined-memory-manipulation
 232   <clang-tidy/checks/bugprone/undefined-memory-manipulation>` check to support
 233   fixed-size arrays of non-trivial types.
 234
 235 - Improved :doc:`bugprone-unused-return-value
 236   <clang-tidy/checks/bugprone/unused-return-value>` check diagnostic message,
 237   added support for detection of unused results when cast to non-``void`` type.
 238   Casting to ``void`` no longer suppresses issues by default, control this
 239   behavior with the new `AllowCastToVoid` option.
 240
 241 - Improved :doc:`cppcoreguidelines-avoid-non-const-global-variables
 242   <clang-tidy/checks/cppcoreguidelines/avoid-non-const-global-variables>` check
 243   to ignore ``static`` variables declared within the scope of
 244   ``class``/``struct``.
 245
 246 - Improved :doc:`cppcoreguidelines-avoid-reference-coroutine-parameters
 247   <clang-tidy/checks/cppcoreguidelines/avoid-reference-coroutine-parameters>`
 248   check to ignore false positives related to matching parameters of non
 249   coroutine functions and increase issue detection for cases involving type
 250   aliases with references.
 251
 252 - Improved :doc:`cppcoreguidelines-narrowing-conversions
 253   <clang-tidy/checks/cppcoreguidelines/narrowing-conversions>` check by
 254   extending the `IgnoreConversionFromTypes` option to include types without a
 255   declaration, such as built-in types.
 256
 257 - Improved :doc:`cppcoreguidelines-prefer-member-initializer
 258   <clang-tidy/checks/cppcoreguidelines/prefer-member-initializer>` check to
 259   ignore delegate constructors and ignore re-assignment for reference or when
 260   initialization depend on field that is initialized before.
 261
 262 - Improved :doc:`cppcoreguidelines-pro-bounds-array-to-pointer-decay
 263   <clang-tidy/checks/cppcoreguidelines/pro-bounds-array-to-pointer-decay>` check
 264   to ignore predefined expression (e.g., ``__func__``, ...).
 265
 266 - Improved :doc:`cppcoreguidelines-pro-bounds-constant-array-index
 267   <clang-tidy/checks/cppcoreguidelines/pro-bounds-constant-array-index>` check
 268   to perform checks on derived classes of  ``std::array``.
 269
 270 - Improved :doc:`cppcoreguidelines-pro-type-const-cast
 271   <clang-tidy/checks/cppcoreguidelines/pro-type-const-cast>` check to ignore
 272   casts to ``const`` or ``volatile`` type (controlled by `StrictMode` option)
 273   and casts in implicitly invoked code.
 274
 275 - Improved :doc:`cppcoreguidelines-pro-type-member-init
 276   <clang-tidy/checks/cppcoreguidelines/pro-type-member-init>` check to ignore
 277   dependent delegate constructors.
 278
 279 - Improved :doc:`cppcoreguidelines-pro-type-static-cast-downcast
 280   <clang-tidy/checks/cppcoreguidelines/pro-type-static-cast-downcast>` check to
 281   disregard casts on non-polymorphic types when the `StrictMode` option is set
 282   to `false`.
 283
 284 - Improved :doc:`cppcoreguidelines-pro-type-vararg
 285   <clang-tidy/checks/cppcoreguidelines/pro-type-vararg>` check to ignore
 286   false-positives in unevaluated context (e.g., ``decltype``, ``sizeof``, ...).
 287
 288 - Improved :doc:`cppcoreguidelines-rvalue-reference-param-not-moved
 289   <clang-tidy/checks/cppcoreguidelines/rvalue-reference-param-not-moved>` check
 290   to ignore unused parameters when they are marked as unused and parameters of
 291   deleted functions and constructors.
 292
 293 - Improved :doc:`llvm-namespace-comment
 294   <clang-tidy/checks/llvm/namespace-comment>` check to provide fixes for
 295   ``inline`` namespaces in the same format as :program:`clang-format`.
 296
 297 - Improved :doc:`llvmlibc-callee-namespace
 298   <clang-tidy/checks/llvmlibc/callee-namespace>` to support
 299   customizable namespace. This matches the change made to implementation in
 300   namespace.
 301
 302 - Improved :doc:`llvmlibc-implementation-in-namespace
 303   <clang-tidy/checks/llvmlibc/implementation-in-namespace>` to support
 304   customizable namespace. This further allows for testing the libc when the
 305   system-libc is also LLVM's libc.
 306
 307 - Improved :doc:`misc-const-correctness
 308   <clang-tidy/checks/misc/const-correctness>` check to avoid false positive when
 309   using pointer to member function.
 310
 311 - Improved :doc:`misc-include-cleaner
 312   <clang-tidy/checks/misc/include-cleaner>` check by adding option
 313   `DeduplicateFindings` to output one finding per symbol occurrence, avoid
 314   inserting the same header multiple times, fix a bug where `IgnoreHeaders`
 315   option won't work with verbatim/std headers.
 316
 317 - Improved :doc:`misc-redundant-expression
 318   <clang-tidy/checks/misc/redundant-expression>` check to ignore
 319   false-positives in unevaluated context (e.g., ``decltype``).
 320
 321 - Improved :doc:`misc-unused-using-decls
 322   <clang-tidy/checks/misc/unused-using-decls>` check to avoid false positive when
 323   using in elaborated type.
 324
 325 - Improved :doc:`modernize-avoid-bind
 326   <clang-tidy/checks/modernize/avoid-bind>` check to
 327   not emit a ``return`` for fixes when the function returns ``void``.
 328
 329 - Improved :doc:`modernize-loop-convert
 330   <clang-tidy/checks/modernize/loop-convert>` to support for-loops with
 331   iterators initialized by free functions like ``begin``, ``end``, or ``size``
 332   and avoid crash for array of dependent array.
 333
 334 - Improved :doc:`modernize-return-braced-init-list
 335   <clang-tidy/checks/modernize/return-braced-init-list>` check to ignore
 336   false-positives when constructing the container with ``count`` copies of
 337   elements with value ``value``.
 338
 339 - Improved :doc:`modernize-use-equals-delete
 340   <clang-tidy/checks/modernize/use-equals-delete>` check to ignore
 341   false-positives when special member function is actually used or implicit.
 342
 343 - Improved :doc:`modernize-use-nullptr
 344   <clang-tidy/checks/modernize/use-nullptr>` check by adding option
 345   `IgnoredTypes` that can be used to exclude some pointer types.
 346
 347 - Improved :doc:`modernize-use-std-print
 348   <clang-tidy/checks/modernize/use-std-print>` check to accurately generate
 349   fixes for reordering arguments.
 350
 351 - Improved :doc:`modernize-use-using
 352   <clang-tidy/checks/modernize/use-using>` check to fix function pointer and
 353   forward declared ``typedef`` correctly.
 354
 355 - Improved :doc:`performance-faster-string-find
 356   <clang-tidy/checks/performance/faster-string-find>` check to properly escape
 357   single quotes.
 358
 359 - Improved :doc:`performance-noexcept-move-constructor
 360   <clang-tidy/checks/performance/noexcept-move-constructor>` to better handle
 361   conditional noexcept expressions, eliminating false-positives.
 362
 363 - Improved :doc:`performance-noexcept-swap
 364   <clang-tidy/checks/performance/noexcept-swap>` check to enforce a stricter
 365   match with the swap function signature and better handling of condition
 366   noexcept expressions, eliminating false-positives.
 367
 368 - Improved :doc:`readability-braces-around-statements
 369   <clang-tidy/checks/readability/braces-around-statements>` check to
 370   ignore false-positive for ``if constexpr`` in lambda expression.
 371
 372 - Improved :doc:`readability-avoid-const-params-in-decls
 373   <clang-tidy/checks/readability/avoid-const-params-in-decls>` diagnositics to
 374   highlight the const location
 375
 376 - Improved :doc:`readability-container-size-empty
 377   <clang-tidy/checks/readability/container-size-empty>` check to
 378   detect comparison between string and empty string literals and support
 379   ``length()`` method as an alternative to ``size()``.
 380
 381 - Improved :doc:`readability-function-size
 382   <clang-tidy/checks/readability/function-size>` check configuration to use
 383   `none` rather than `-1` to disable some parameters.
 384
 385 - Improved :doc:`readability-identifier-naming
 386   <clang-tidy/checks/readability/identifier-naming>` check to issue accurate
 387   warnings when a type's forward declaration precedes its definition.
 388   Additionally, it now provides appropriate warnings for ``struct`` and
 389   ``union`` in C, while also incorporating support for the
 390   ``Leading_upper_snake_case`` naming convention. The handling of ``typedef``
 391   has been enhanced, particularly within complex types like function pointers
 392   and cases where style checks were omitted when functions started with macros.
 393
 394 - Improved :doc:`readability-implicit-bool-conversion
 395   <clang-tidy/checks/readability/implicit-bool-conversion>` check to take
 396   do-while loops into account for the `AllowIntegerConditions` and
 397   `AllowPointerConditions` options.
 398
 399 - Improved :doc:`readability-non-const-parameter
 400   <clang-tidy/checks/readability/non-const-parameter>` check to ignore
 401   false-positives in initializer list of record.
 402
 403 - Improved :doc:`readability-static-accessed-through-instance
 404   <clang-tidy/checks/readability/static-accessed-through-instance>` check to
 405   identify calls to static member functions with out-of-class inline definitions.
 406
 407 Removed checks
 408 ^^^^^^^^^^^^^^
 409
 410 Improvements to include-fixer
 411 -----------------------------
 412
 413 The improvements are...
 414
 415 Improvements to clang-include-fixer
 416 -----------------------------------
 417
 418 The improvements are...
 419
 420 Improvements to modularize
 421 --------------------------
 422
 423 The improvements are...
 424
 425 Improvements to pp-trace
 426 ------------------------
 427
 428 Clang-tidy Visual Studio plugin
 429 -------------------------------