clang/docs/ReleaseNotes.rst - llvm-project - Git at Google

 ========================================
 Clang 12.0.0 (In-Progress) Release Notes
 ========================================

 .. contents::
    :local:
    :depth: 2

 Written by the `LLVM Team <https://llvm.org/>`_

 .. warning::

    These are in-progress notes for the upcoming Clang 12 release.
    Release notes for previous releases can be found on
    `the Download Page <https://releases.llvm.org/download.html>`_.

 Introduction
 ============

 This document contains the release notes for the Clang C/C++/Objective-C
 frontend, part of the LLVM Compiler Infrastructure, release 12.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
 documentation <https://llvm.org/docs/ReleaseNotes.html>`_. All LLVM
 releases may be downloaded from the `LLVM releases web
 site <https://llvm.org/releases/>`_.

 For more information about Clang or LLVM, including information about the
 latest release, please see the `Clang Web Site <https://clang.llvm.org>`_ or the
 `LLVM Web Site <https://llvm.org>`_.

 Note that if you are reading this file from a Git checkout or the
 main Clang web page, this document applies to the *next* release, not
 the current one. To see the release notes for a specific release, please
 see the `releases page <https://llvm.org/releases/>`_.

 What's New in Clang 12.0.0?
 ===========================

 Some of the major new features and improvements to Clang are listed
 here. Generic improvements to Clang as a whole or to its underlying
 infrastructure are described first, followed by language-specific
 sections with improvements to Clang's support for those languages.

 Major New Features
 ------------------

 - ...

 Improvements to Clang's diagnostics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 - ...

 Non-comprehensive list of changes in this release
 -------------------------------------------------

 - The builtin intrinsics ``__builtin_bitreverse8``, ``__builtin_bitreverse16``,
   ``__builtin_bitreverse32`` and ``__builtin_bitreverse64`` may now be used
   within constant expressions.

 - The builtin intrinsics ``__builtin_rotateleft8``, ``__builtin_rotateleft16``,
   ``__builtin_rotateleft32`` and ``__builtin_rotateleft64`` may now be used
   within constant expressions.

 - The builtin intrinsics ``__builtin_rotateright8``, ``__builtin_rotateright16``,
   ``__builtin_rotateright32`` and ``__builtin_rotateright64`` may now be used
   within constant expressions.

 New Compiler Flags
 ------------------

 - ...

 - -fpch-codegen and -fpch-debuginfo generate shared code and/or debuginfo
   for contents of a precompiled header in a separate object file. This object
   file needs to be linked in, but its contents do not need to be generated
   for other objects using the precompiled header. This should usually save
   compile time. If not using clang-cl, the separate object file needs to
   be created explicitly from the precompiled header.
   Example of use:

   .. code-block:: console

     $ clang++ -x c++-header header.h -o header.pch -fpch-codegen -fpch-debuginfo
     $ clang++ -c header.pch -o shared.o
     $ clang++ -c source.cpp -o source.o -include-pch header.pch
     $ clang++ -o binary source.o shared.o

   - Using -fpch-instantiate-templates when generating the precompiled header
     usually increases the amount of code/debuginfo that can be shared.
   - In some cases, especially when building with optimizations enabled, using
     -fpch-codegen may generate so much code in the shared object that compiling
     it may be a net loss in build time.
   - Since headers may bring in private symbols of other libraries, it may be
     sometimes necessary to discard unused symbols (such as by adding
     -Wl,--gc-sections on ELF platforms to the linking command, and possibly
     adding -fdata-sections -ffunction-sections to the command generating
     the shared object).
 - New option ``-fbinutils-version=`` specifies the targeted binutils version.
   For example, ``-fbinutils-version=2.35`` means compatibility with GNU as/ld
   before 2.35 is not needed: new features can be used and there is no need to
   work around old GNU as/ld bugs.

 Deprecated Compiler Flags
 -------------------------

 The following options are deprecated and ignored. They will be removed in
 future versions of Clang.

 - ...

 Modified Compiler Flags
 -----------------------

 - On ELF, ``-gz`` now defaults to ``-gz=zlib`` with the integrated assembler.
   It produces ``SHF_COMPRESSED`` style compression of debug information. GNU
   binutils 2.26 or newer, or lld is required to link produced object files. Use
   ``-gz=zlib-gnu`` to get the old behavior.
 - Now that `this` pointers are tagged with `nonnull` and `dereferenceable(N)`,
   `-fno-delete-null-pointer-checks` has gained the power to remove the
   `nonnull` attribute on `this` for configurations that need it to be nullable.
 - ``-gsplit-dwarf`` no longer implies ``-g2``.
 - ``-fasynchronous-unwind-tables`` is now the default on Linux AArch64/PowerPC.
   This behavior matches newer GCC.
   (`D91760 <https://reviews.llvm.org/D91760>`_)
   (`D92054 <https://reviews.llvm.org/D92054>`_)

 Removed Compiler Flags
 -------------------------

 The following options no longer exist.

 - clang-cl's ``/Zd`` flag no longer exist. But ``-gline-tables-only`` still
   exists and does the same thing.

 New Pragmas in Clang
 --------------------

 - ...

 Attribute Changes in Clang
 --------------------------

 - Added support for the C++20 likelihood attributes ``[[likely]]`` and
   ``[[unlikely]]``. As an extension they can be used in C++11 and newer.
   This extension is enabled by default.

 Windows Support
 ---------------

 C Language Changes in Clang
 ---------------------------

 - ...

 C++ Language Changes in Clang
 -----------------------------

 - ...

 C++1z Feature Support
 ^^^^^^^^^^^^^^^^^^^^^
 ...

 Objective-C Language Changes in Clang
 -------------------------------------

 OpenCL C Language Changes in Clang
 ----------------------------------

 ...

 ABI Changes in Clang
 --------------------

 OpenMP Support in Clang
 -----------------------

 - ...

 CUDA Support in Clang
 ---------------------

 - ...

 X86 Support in Clang
 --------------------

 - The x86 intrinsics ``_mm_popcnt_u32``, ``_mm_popcnt_u64``, ``_popcnt32``,
   ``_popcnt64``, ``__popcntd`` and ``__popcntq``  may now be used within
   constant expressions.

 - The x86 intrinsics ``_bit_scan_forward``, ``__bsfd`` and ``__bsfq`` may now
   be used within constant expressions.

 - The x86 intrinsics ``_bit_scan_reverse``, ``__bsrd`` and ``__bsrq`` may now
   be used within constant expressions.

 - The x86 intrinsics ``__bswap``, ``__bswapd``, ``__bswap64`` and ``__bswapq``
   may now be used within constant expressions.

 - The x86 intrinsics ``_castf32_u32``, ``_castf64_u64``, ``_castu32_f32`` and
   ``_castu64_f64`` may now be used within constant expressions.

 - The x86 intrinsics ``__rolb``, ``__rolw``, ``__rold``, ``__rolq`, ``_rotl``,
   ``_rotwl`` and ``_lrotl`` may now be used within constant expressions.

 - The x86 intrinsics ``__rorb``, ``__rorw``, ``__rord``, ``__rorq`, ``_rotr``,
   ``_rotwr`` and ``_lrotr`` may now be used within constant expressions.

 - Support for ``-march=alderlake``, ``-march=sapphirerapids`` and
   ``-march=znver3`` was added.

 - Support for ``-march=x86-64-v[234]`` has been added.
   See :doc:`UsersManual` for details about these micro-architecture levels.

 - The -mtune command line option is no longer ignored for X86. This can be used
   to request microarchitectural optimizations independent on -march. -march=<cpu>
   implies -mtune=<cpu>. -mtune=generic is the default with no -march or -mtune
   specified.

 - Support for ``HRESET`` instructions has been added.

 - Support for ``UINTR`` instructions has been added.

 - Support for ``AVXVNNI`` instructions has been added.

 Internal API Changes
 --------------------

 These are major API changes that have happened since the 11.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.

 - ...

 Build System Changes
 --------------------

 These are major changes to the build system that have happened since the 11.0.0
 release of Clang. Users of the build system should adjust accordingly.

 - ...

 AST Matchers
 ------------

 - The behavior of TK_IgnoreUnlessSpelledInSource with the traverse() matcher
   has been changed to no longer match on template instantiations or on
   implicit nodes which are not spelled in the source.

 - The TK_IgnoreImplicitCastsAndParentheses traversal kind was removed. It
   is recommended to use TK_IgnoreUnlessSpelledInSource instead.

 - The behavior of the forEach() matcher was changed to not internally ignore
   implicit and parenthesis nodes.

 clang-format
 ------------

 - Option ``BitFieldColonSpacing`` has been added that decides how
   space should be added around identifier, colon and bit-width in
   bitfield definitions.

   .. code-block:: c++

     // Both (default)
     struct F {
       unsigned dscp : 6;
       unsigned ecn  : 2; // AlignConsecutiveBitFields=true
     };
     // None
     struct F {
       unsigned dscp:6;
       unsigned ecn :2;
     };
     // Before
     struct F {
       unsigned dscp :6;
       unsigned ecn  :2;
     };
     // After
     struct F {
       unsigned dscp: 6;
       unsigned ecn : 2;
     };


 - Experimental Support in clang-format for concepts has been improved, to
   aid this the follow options have been added

 - Option ``IndentRequires`` has been added to indent the ``requires`` keyword
   in templates.

 - Option ``BreakBeforeConceptDeclarations`` has been added to aid the formatting of concepts.

 - Option ``IndentPragmas`` has been added to allow #pragma to indented with the current scope
   level. This is especially useful when using #pragma to mark OpenMP sections of code.

 - Option ``SpaceBeforeCaseColon`` has been added to add a space before the
   colon in a case or default statement.

 - Option ``StatementAttributeLikeMacros`` has been added to declare
   macros which are not parsed as a type in front of a statement. See
   the documentation for an example.

 - Options ``AlignConsecutiveAssignments``, ``AlignConsecutiveBitFields``,
   ``AlignConsecutiveDeclarations`` and ``AlignConsecutiveMacros`` have been modified to allow
   alignment across empty lines and/or comments.

 libclang
 --------

 - ...

 Static Analyzer
 ---------------

 - ...

 .. _release-notes-ubsan:

 Undefined Behavior Sanitizer (UBSan)
 ------------------------------------

 Core Analysis Improvements
 ==========================

 - ...

 New Issues Found
 ================

 - ...

 Python Binding Changes
 ----------------------

 The following methods have been added:

 -  ...

 Significant Known Problems
 ==========================

 Additional Information
 ======================

 A wide variety of additional information is available on the `Clang web
 page <https://clang.llvm.org/>`_. The web page contains versions of the
 API documentation which are up-to-date with the Git version of
 the source code. You can access versions of these documents specific to
 this release by going into the "``clang/docs/``" directory in the Clang
 tree.

 If you have any questions or comments about Clang, please feel free to
 contact us via the `mailing
 list <https://lists.llvm.org/mailman/listinfo/cfe-dev>`_.
	========================================
	Clang 12.0.0 (In-Progress) Release Notes
	========================================

	.. contents::
	:local:
	:depth: 2

	Written by the `LLVM Team <https://llvm.org/>`_

	.. warning::

	These are in-progress notes for the upcoming Clang 12 release.
	Release notes for previous releases can be found on
	`the Download Page <https://releases.llvm.org/download.html>`_.

	Introduction
	============

	This document contains the release notes for the Clang C/C++/Objective-C
	frontend, part of the LLVM Compiler Infrastructure, release 12.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
	documentation <https://llvm.org/docs/ReleaseNotes.html>`_. All LLVM
	releases may be downloaded from the `LLVM releases web
	site <https://llvm.org/releases/>`_.

	For more information about Clang or LLVM, including information about the
	latest release, please see the `Clang Web Site <https://clang.llvm.org>`_ or the
	`LLVM Web Site <https://llvm.org>`_.

	Note that if you are reading this file from a Git checkout or the
	main Clang web page, this document applies to the next release, not
	the current one. To see the release notes for a specific release, please
	see the `releases page <https://llvm.org/releases/>`_.

	What's New in Clang 12.0.0?
	===========================

	Some of the major new features and improvements to Clang are listed
	here. Generic improvements to Clang as a whole or to its underlying
	infrastructure are described first, followed by language-specific
	sections with improvements to Clang's support for those languages.

	Major New Features
	------------------

	- ...

	Improvements to Clang's diagnostics
	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

	- ...

	Non-comprehensive list of changes in this release
	-------------------------------------------------

	- The builtin intrinsics ``__builtin_bitreverse8``, ``__builtin_bitreverse16``,
	``__builtin_bitreverse32`` and ``__builtin_bitreverse64`` may now be used
	within constant expressions.

	- The builtin intrinsics ``__builtin_rotateleft8``, ``__builtin_rotateleft16``,
	``__builtin_rotateleft32`` and ``__builtin_rotateleft64`` may now be used
	within constant expressions.

	- The builtin intrinsics ``__builtin_rotateright8``, ``__builtin_rotateright16``,
	``__builtin_rotateright32`` and ``__builtin_rotateright64`` may now be used
	within constant expressions.

	New Compiler Flags
	------------------

	- ...

	- -fpch-codegen and -fpch-debuginfo generate shared code and/or debuginfo
	for contents of a precompiled header in a separate object file. This object
	file needs to be linked in, but its contents do not need to be generated
	for other objects using the precompiled header. This should usually save
	compile time. If not using clang-cl, the separate object file needs to
	be created explicitly from the precompiled header.
	Example of use:

	.. code-block:: console

	$ clang++ -x c++-header header.h -o header.pch -fpch-codegen -fpch-debuginfo
	$ clang++ -c header.pch -o shared.o
	$ clang++ -c source.cpp -o source.o -include-pch header.pch
	$ clang++ -o binary source.o shared.o

	- Using -fpch-instantiate-templates when generating the precompiled header
	usually increases the amount of code/debuginfo that can be shared.
	- In some cases, especially when building with optimizations enabled, using
	-fpch-codegen may generate so much code in the shared object that compiling
	it may be a net loss in build time.
	- Since headers may bring in private symbols of other libraries, it may be
	sometimes necessary to discard unused symbols (such as by adding
	-Wl,--gc-sections on ELF platforms to the linking command, and possibly
	adding -fdata-sections -ffunction-sections to the command generating
	the shared object).
	- New option ``-fbinutils-version=`` specifies the targeted binutils version.
	For example, ``-fbinutils-version=2.35`` means compatibility with GNU as/ld
	before 2.35 is not needed: new features can be used and there is no need to
	work around old GNU as/ld bugs.

	Deprecated Compiler Flags
	-------------------------

	The following options are deprecated and ignored. They will be removed in
	future versions of Clang.

	- ...

	Modified Compiler Flags
	-----------------------

	- On ELF, ``-gz`` now defaults to ``-gz=zlib`` with the integrated assembler.
	It produces ``SHF_COMPRESSED`` style compression of debug information. GNU
	binutils 2.26 or newer, or lld is required to link produced object files. Use
	``-gz=zlib-gnu`` to get the old behavior.
	- Now that `this` pointers are tagged with `nonnull` and `dereferenceable(N)`,
	`-fno-delete-null-pointer-checks` has gained the power to remove the
	`nonnull` attribute on `this` for configurations that need it to be nullable.
	- ``-gsplit-dwarf`` no longer implies ``-g2``.
	- ``-fasynchronous-unwind-tables`` is now the default on Linux AArch64/PowerPC.
	This behavior matches newer GCC.
	(`D91760 <https://reviews.llvm.org/D91760>`_)
	(`D92054 <https://reviews.llvm.org/D92054>`_)

	Removed Compiler Flags
	-------------------------

	The following options no longer exist.

	- clang-cl's ``/Zd`` flag no longer exist. But ``-gline-tables-only`` still
	exists and does the same thing.

	New Pragmas in Clang
	--------------------

	- ...

	Attribute Changes in Clang
	--------------------------

	- Added support for the C++20 likelihood attributes ``[[likely]]`` and
	``[[unlikely]]``. As an extension they can be used in C++11 and newer.
	This extension is enabled by default.

	Windows Support
	---------------

	C Language Changes in Clang
	---------------------------

	- ...

	C++ Language Changes in Clang
	-----------------------------

	- ...

	C++1z Feature Support
	^^^^^^^^^^^^^^^^^^^^^
	...

	Objective-C Language Changes in Clang
	-------------------------------------

	OpenCL C Language Changes in Clang
	----------------------------------

	...

	ABI Changes in Clang
	--------------------

	OpenMP Support in Clang
	-----------------------

	- ...

	CUDA Support in Clang
	---------------------

	- ...

	X86 Support in Clang
	--------------------

	- The x86 intrinsics ``_mm_popcnt_u32``, ``_mm_popcnt_u64``, ``_popcnt32``,
	``_popcnt64``, ``__popcntd`` and ``__popcntq`` may now be used within
	constant expressions.

	- The x86 intrinsics ``_bit_scan_forward``, ``__bsfd`` and ``__bsfq`` may now
	be used within constant expressions.

	- The x86 intrinsics ``_bit_scan_reverse``, ``__bsrd`` and ``__bsrq`` may now
	be used within constant expressions.

	- The x86 intrinsics ``__bswap``, ``__bswapd``, ``__bswap64`` and ``__bswapq``
	may now be used within constant expressions.

	- The x86 intrinsics ``_castf32_u32``, ``_castf64_u64``, ``_castu32_f32`` and
	``_castu64_f64`` may now be used within constant expressions.

	- The x86 intrinsics ``__rolb``, ``__rolw``, ``__rold``, ``__rolq`, ``_rotl``,
	``_rotwl`` and ``_lrotl`` may now be used within constant expressions.

	- The x86 intrinsics ``__rorb``, ``__rorw``, ``__rord``, ``__rorq`, ``_rotr``,
	``_rotwr`` and ``_lrotr`` may now be used within constant expressions.

	- Support for ``-march=alderlake``, ``-march=sapphirerapids`` and
	``-march=znver3`` was added.

	- Support for ``-march=x86-64-v[234]`` has been added.
	See :doc:`UsersManual` for details about these micro-architecture levels.

	- The -mtune command line option is no longer ignored for X86. This can be used
	to request microarchitectural optimizations independent on -march. -march=<cpu>
	implies -mtune=<cpu>. -mtune=generic is the default with no -march or -mtune
	specified.

	- Support for ``HRESET`` instructions has been added.

	- Support for ``UINTR`` instructions has been added.

	- Support for ``AVXVNNI`` instructions has been added.

	Internal API Changes
	--------------------

	These are major API changes that have happened since the 11.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.

	- ...

	Build System Changes
	--------------------

	These are major changes to the build system that have happened since the 11.0.0
	release of Clang. Users of the build system should adjust accordingly.

	- ...

	AST Matchers
	------------

	- The behavior of TK_IgnoreUnlessSpelledInSource with the traverse() matcher
	has been changed to no longer match on template instantiations or on
	implicit nodes which are not spelled in the source.

	- The TK_IgnoreImplicitCastsAndParentheses traversal kind was removed. It
	is recommended to use TK_IgnoreUnlessSpelledInSource instead.

	- The behavior of the forEach() matcher was changed to not internally ignore
	implicit and parenthesis nodes.

	clang-format
	------------

	- Option ``BitFieldColonSpacing`` has been added that decides how
	space should be added around identifier, colon and bit-width in
	bitfield definitions.

	.. code-block:: c++

	// Both (default)
	struct F {
	unsigned dscp : 6;
	unsigned ecn : 2; // AlignConsecutiveBitFields=true
	};
	// None
	struct F {
	unsigned dscp:6;
	unsigned ecn :2;
	};
	// Before
	struct F {
	unsigned dscp :6;
	unsigned ecn :2;
	};
	// After
	struct F {
	unsigned dscp: 6;
	unsigned ecn : 2;
	};


	- Experimental Support in clang-format for concepts has been improved, to
	aid this the follow options have been added

	- Option ``IndentRequires`` has been added to indent the ``requires`` keyword
	in templates.

	- Option ``BreakBeforeConceptDeclarations`` has been added to aid the formatting of concepts.

	- Option ``IndentPragmas`` has been added to allow #pragma to indented with the current scope
	level. This is especially useful when using #pragma to mark OpenMP sections of code.

	- Option ``SpaceBeforeCaseColon`` has been added to add a space before the
	colon in a case or default statement.

	- Option ``StatementAttributeLikeMacros`` has been added to declare
	macros which are not parsed as a type in front of a statement. See
	the documentation for an example.

	- Options ``AlignConsecutiveAssignments``, ``AlignConsecutiveBitFields``,
	``AlignConsecutiveDeclarations`` and ``AlignConsecutiveMacros`` have been modified to allow
	alignment across empty lines and/or comments.

	libclang
	--------

	- ...

	Static Analyzer
	---------------

	- ...

	.. _release-notes-ubsan:

	Undefined Behavior Sanitizer (UBSan)
	------------------------------------

	Core Analysis Improvements
	==========================

	- ...

	New Issues Found
	================

	- ...

	Python Binding Changes
	----------------------

	The following methods have been added:

	- ...

	Significant Known Problems
	==========================

	Additional Information
	======================

	A wide variety of additional information is available on the `Clang web
	page <https://clang.llvm.org/>`_. The web page contains versions of the
	API documentation which are up-to-date with the Git version of
	the source code. You can access versions of these documents specific to
	this release by going into the "``clang/docs/``" directory in the Clang
	tree.

	If you have any questions or comments about Clang, please feel free to
	contact us via the `mailing
	list <https://lists.llvm.org/mailman/listinfo/cfe-dev>`_.