docs/ReleaseNotes.rst - clang - Git at Google

 =========================
 Clang 9.0.0 Release Notes
 =========================

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

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


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

 This document contains the release notes for the Clang C/C++/Objective-C
 frontend, part of the LLVM Compiler Infrastructure, release 9.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>`_.


 What's New in Clang 9.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
 ------------------

 - Experimental support for :ref:`C++ for OpenCL <openclcpp>` has been
   added.


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

 - The ``__VERSION__`` macro has been updated.
   Previously this macro contained the string '4.2.1 Compatible' to achieve
   compatibility with GCC 4.2.1, but that should no longer be necessary.
   However, to retrieve Clang's version, please favor the one of the macro
   defined in :ref:`clang namespaced version macros <languageextensions-builtin-macros>`.


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

 - ``-ftime-trace`` and ``ftime-trace-granularity=N``
   Emits flame chart style compilation time report in chrome://tracing and
   speedscope.app compatible format. A trace .json file is written next to the
   compiled object file, containing hierarchical time information about frontend
   activities (file parsing, template instantiation) and backend activities
   (modules and functions being optimized, optimization passes).


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

 - ``clang -dumpversion`` now returns the version of Clang itself.


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

 - clang-cl now treats non-existent files as possible typos for flags,
   ``clang-cl /diagnostic:caret /c test.cc`` for example now produces
   ``clang: error: no such file or directory: '/diagnostic:caret'; did you mean '/diagnostics:caret'?``

 - clang now parses the ``__declspec(allocator)`` specifier and generates debug
   information, so that memory usage can be tracked in Visual Studio.

 - The ``-print-search-dirs`` option now separates elements with semicolons,
   as is the norm for path lists on Windows

 - Improved handling of dllexport in conjunction with explicit template
   instantiations for MinGW, to allow building a shared libc++ for MinGW
   without ``--export-all-symbols`` to override the dllexport attributes


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

 - The ``__FILE_NAME__`` macro has been added as a Clang specific extension supported
   in all C-family languages. This macro is similar to ``__FILE__`` except it
   will always provide the last path component when possible.

 - Initial support for ``asm goto`` statements (a GNU C extension) has been
   added for control flow from inline assembly to labels. The main consumers of
   this construct are the Linux kernel (CONFIG_JUMP_LABEL=y) and glib. There are
   still a few unsupported corner cases in Clang's integrated assembler and
   IfConverter. Please file bugs for any issues you run into.


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

 - Support for the address space attribute in various C++ features was improved,
   refer to :ref:`C++ for OpenCL <openclcpp>` for more details. The following
   features deviated from OpenCL:

   (1) Address spaces as method qualifiers are not accepted yet;

   (2) There is no address space deduction.


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

 - Fixed encoding of ObjC pointer types that are pointers to typedefs.

   .. code-block:: objc

       typedef NSArray<NSObject *> MyArray;

       // clang used to encode this as "^{NSArray=#}" instead of "@".
       const char *s0 = @encode(MyArray *);

 OpenCL Kernel Language Changes in Clang
 ---------------------------------------

 OpenCL C
 ^^^^^^^^

 - Enabled use of variadic macro as a Clang extension.

 - Added initial support for implicitly including OpenCL builtin
   fuctions using efficient trie lookup generated by TableGen.
   A corresponding frontend-only flag ``-fdeclare-opencl-builtins``
   has been added to enable trie during parsing.

 - Refactored header file to be used for common parts between
   regular header added using ``-finclude-default-header`` and trie
   based declarations added using ``-fdeclare-opencl-builtins``.

 - Improved string formatting diagnostics in printf for vector types.

 - Simplified the internal representation of blocks, including their
   generation in IR. Furthermore, indirect calls to block function
   has been changed to direct function calls.

 - Added diagnostics for conversions of nested pointers with
   different address spaces.

 - Added ``cl_arm_integer_dot_product`` extension.

 - Fixed global samplers in OpenCL v2.0.

 - Improved math builtin functions with parameters of type ``long
   long`` for x86.

 .. _openclcpp:

 C++ for OpenCL
 ^^^^^^^^^^^^^^

 Experimental support for C++17 features in OpenCL has been added
 and backwards compatibility with OpenCL C v2.0 was enabled.
 The documentation has been added for supported language features
 into :doc:`LanguageExtensions` and :doc:`UsersManual`.

 Implemented features are:

 - Address space behavior is improved in majority of C++ features:

   - Templates parameters and arguments;

   - Reference types;

   - Type deduction;

   - Objects and member functions, including special member
     functions;

   - Builtin operators;

   - Method qualifiers now include address space;

   - Address space deduction has been extended for C++ use cases;

   - Improved overload ranking rules;

   - All standard cast operators now prevent converting address
     spaces (except for conversions allowed implicitly). They
     can still be cast using C-style cast.

 - Vector types as in OpenCL C, including compound vector
   initialization.

 - OpenCL-specific types: images, samplers, events, pipes, are
   accepted. Note that blocks are not supported yet.

 - OpenCL standard header in Clang can be compiled in C++ mode.

 - Global constructors can be invoked from the host side using
   a specific, compiler-generated kernel.

 - Overloads with generic address space are added to all atomic
   builtin functions, including the ones prior to OpenCL v2.0.


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

 - Added emission of the debug information for NVPTX target devices.

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

 - Added emission of the debug information for the device code.

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

 These are major API changes that have happened since the 8.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 8.0.0
 release of Clang. Users of the build system should adjust accordingly.

 - In 8.0.0 and below, the install-clang-headers target would install clang's
   resource directory headers. This installation is now performed by the
   install-clang-resource-headers target. Users of the old install-clang-headers
   target should switch to the new install-clang-resource-headers target. The
   install-clang-headers target now installs clang's API headers (corresponding
   to its libraries), which is consistent with the install-llvm-headers target.

 - In 9.0.0 and later Clang added a new target on Linux/Unix systems, clang-cpp,
   which generates a shared library comprised of all the clang component
   libraries and exporting the clang C++ APIs. Additionally the build system
   gained the new "CLANG_LINK_CLANG_DYLIB" option, which defaults Off, and when
   set to On, will force clang (and clang-based tools) to link the clang-cpp
   library instead of statically linking clang's components. This option will
   reduce the size of binary distributions at the expense of compiler performance.


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

 - Add language support for clang-formatting C# files.
 - Add Microsoft coding style to encapsulate default C# formatting style.
 - Added new option ``PPDIS_BeforeHash`` (in configuration: ``BeforeHash``) to
   ``IndentPPDirectives`` which indents preprocessor directives before the hash.
 - Added new option ``AlignConsecutiveMacros`` to align the C/C++ preprocessor
   macros of consecutive lines.

 libclang
 --------

 - When ``CINDEXTEST_INCLUDE_ATTRIBUTED_TYPES`` is not provided when making a
   CXType, the equivalent type of the AttributedType is returned instead of the
   modified type if the user does not want attribute sugar. The equivalent type
   represents the minimally-desugared type which the AttributedType is
   canonically equivalent to.


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

 - Fixed a bug where an incorrect checker name would be displayed for a bug
   report.

 - New checker: ``security.insecureAPI.DeprecatedOrUnsafeBufferHandling`` to detect
   uses of unsafe/deprecated buffer handling functions for C code using the C11
   standard or newer.

 - New checker: ``osx.MIGChecker`` to find violations of the Mach Interface
   Generator calling convention

 - New checker: ``optin.osx.OSObjectCStyleCast`` to find C-style casts of of XNU
   libkern OSObjects

 - New package: ``apiModeling.llvm`` contains modeling checkers to improve the
   accuracy of reports on LLVM's own codebase.

 - The Static Analyzer received
   :ref:`developer documentation <clang-static-analyzer-docs>`.

 - The UninitializedObject checker is now considered as stable.
   (moved from the ``alpha.cplusplus`` to the ``optin.cplusplus`` package)

 - New frontend flags: The list of available checkers are now split into 3
   different frontend flags:

   - ``-analyzer-checker-help``: The list of user-facing, stable checkers.

   - ``-analyzer-checker-help-alpha``: The list of in-development
     checkers not yet advised to be turned on.

   - ``-analyzer-checker-help-developer``: Checkers never meant to be
     enabled/disabled by hand + development checkers.

 - New frontend flags: While they have always been around, for the first time,
   checker and package options are listable:

   - ``-analyzer-checker-option-help``: The list of user-facing, stable checker
     and package options.

   - ``-analyzer-checker-option-help-alpha``: The list of in-development checker
     options not yet advised to be used.

   - ``-analyzer-checker-option-help-developer``: Options never meant to be
     enabled/disabled by hand + development options.

 - New frontend flag: ``-analyzer-werror`` to turn analyzer warnings into errors.

 - Numerous fixes to increase the stability of the experimental cross translation
   unit analysis (CTU).

 - CTU now handles virtual functions as well.


 Linux Kernel
 ============

 With support for asm goto, the mainline Linux kernel for x86_64 is now buildable
 (and bootable) with Clang 9.  Other architectures that don't require
 CONFIG_JUMP_LABEL=y such as arm, aarch64, ppc32, ppc64le, (and possibly mips)
 have been supported with older releases of Clang (Clang 4 was first used with
 aarch64).

 The Android and ChromeOS Linux distributions have moved to building their Linux
 kernels with Clang, and Google is currently testing Clang built kernels for
 their production Linux kernels.

 Further, LLD, llvm-objcopy, llvm-ar, llvm-nm, llvm-objdump can all be used to
 build a working Linux kernel.

 More information about building Linux kernels with Clang can be found:

 - `ClangBuiltLinux web page <https://clangbuiltlinux.github.io/>`_.
 - `Issue Tracker <https://github.com/ClangBuiltLinux/linux/issues>`_.
 - `Wiki <https://github.com/ClangBuiltLinux/linux/wiki>`_.
 - `Mailing List <clang-built-linux@googlegroups.com>`_.
 - `Bi-weekly Meeting <https://calendar.google.com/calendar/embed?src=google.com_bbf8m6m4n8nq5p2bfjpele0n5s%40group.calendar.google.com>`_.
 - #clangbuiltlinux on Freenode.
 - `Clang Meta bug <https://bugs.llvm.org/show_bug.cgi?id=4068>`_.
 - `Continuous Integration <https://travis-ci.com/ClangBuiltLinux/continuous-integration>`_.

 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 Subversion version of
 the source code. You can access versions of these documents specific to
 this release by going into the "``clang/docs/``" directory in the Clang
 tree.

 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 9.0.0 Release Notes
	=========================

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

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


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

	This document contains the release notes for the Clang C/C++/Objective-C
	frontend, part of the LLVM Compiler Infrastructure, release 9.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>`_.


	What's New in Clang 9.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
	------------------

	- Experimental support for :ref:`C++ for OpenCL <openclcpp>` has been
	added.


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

	- The ``__VERSION__`` macro has been updated.
	Previously this macro contained the string '4.2.1 Compatible' to achieve
	compatibility with GCC 4.2.1, but that should no longer be necessary.
	However, to retrieve Clang's version, please favor the one of the macro
	defined in :ref:`clang namespaced version macros <languageextensions-builtin-macros>`.


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

	- ``-ftime-trace`` and ``ftime-trace-granularity=N``
	Emits flame chart style compilation time report in chrome://tracing and
	speedscope.app compatible format. A trace .json file is written next to the
	compiled object file, containing hierarchical time information about frontend
	activities (file parsing, template instantiation) and backend activities
	(modules and functions being optimized, optimization passes).


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

	- ``clang -dumpversion`` now returns the version of Clang itself.


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

	- clang-cl now treats non-existent files as possible typos for flags,
	``clang-cl /diagnostic:caret /c test.cc`` for example now produces
	``clang: error: no such file or directory: '/diagnostic:caret'; did you mean '/diagnostics:caret'?``

	- clang now parses the ``__declspec(allocator)`` specifier and generates debug
	information, so that memory usage can be tracked in Visual Studio.

	- The ``-print-search-dirs`` option now separates elements with semicolons,
	as is the norm for path lists on Windows

	- Improved handling of dllexport in conjunction with explicit template
	instantiations for MinGW, to allow building a shared libc++ for MinGW
	without ``--export-all-symbols`` to override the dllexport attributes


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

	- The ``__FILE_NAME__`` macro has been added as a Clang specific extension supported
	in all C-family languages. This macro is similar to ``__FILE__`` except it
	will always provide the last path component when possible.

	- Initial support for ``asm goto`` statements (a GNU C extension) has been
	added for control flow from inline assembly to labels. The main consumers of
	this construct are the Linux kernel (CONFIG_JUMP_LABEL=y) and glib. There are
	still a few unsupported corner cases in Clang's integrated assembler and
	IfConverter. Please file bugs for any issues you run into.


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

	- Support for the address space attribute in various C++ features was improved,
	refer to :ref:`C++ for OpenCL <openclcpp>` for more details. The following
	features deviated from OpenCL:

	(1) Address spaces as method qualifiers are not accepted yet;

	(2) There is no address space deduction.


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

	- Fixed encoding of ObjC pointer types that are pointers to typedefs.

	.. code-block:: objc

	typedef NSArray<NSObject *> MyArray;

	// clang used to encode this as "^{NSArray=#}" instead of "@".
	const char s0 = @encode(MyArray );

	OpenCL Kernel Language Changes in Clang
	---------------------------------------

	OpenCL C
	^^^^^^^^

	- Enabled use of variadic macro as a Clang extension.

	- Added initial support for implicitly including OpenCL builtin
	fuctions using efficient trie lookup generated by TableGen.
	A corresponding frontend-only flag ``-fdeclare-opencl-builtins``
	has been added to enable trie during parsing.

	- Refactored header file to be used for common parts between
	regular header added using ``-finclude-default-header`` and trie
	based declarations added using ``-fdeclare-opencl-builtins``.

	- Improved string formatting diagnostics in printf for vector types.

	- Simplified the internal representation of blocks, including their
	generation in IR. Furthermore, indirect calls to block function
	has been changed to direct function calls.

	- Added diagnostics for conversions of nested pointers with
	different address spaces.

	- Added ``cl_arm_integer_dot_product`` extension.

	- Fixed global samplers in OpenCL v2.0.

	- Improved math builtin functions with parameters of type ``long
	long`` for x86.

	.. _openclcpp:

	C++ for OpenCL
	^^^^^^^^^^^^^^

	Experimental support for C++17 features in OpenCL has been added
	and backwards compatibility with OpenCL C v2.0 was enabled.
	The documentation has been added for supported language features
	into :doc:`LanguageExtensions` and :doc:`UsersManual`.

	Implemented features are:

	- Address space behavior is improved in majority of C++ features:

	- Templates parameters and arguments;

	- Reference types;

	- Type deduction;

	- Objects and member functions, including special member
	functions;

	- Builtin operators;

	- Method qualifiers now include address space;

	- Address space deduction has been extended for C++ use cases;

	- Improved overload ranking rules;

	- All standard cast operators now prevent converting address
	spaces (except for conversions allowed implicitly). They
	can still be cast using C-style cast.

	- Vector types as in OpenCL C, including compound vector
	initialization.

	- OpenCL-specific types: images, samplers, events, pipes, are
	accepted. Note that blocks are not supported yet.

	- OpenCL standard header in Clang can be compiled in C++ mode.

	- Global constructors can be invoked from the host side using
	a specific, compiler-generated kernel.

	- Overloads with generic address space are added to all atomic
	builtin functions, including the ones prior to OpenCL v2.0.


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

	- Added emission of the debug information for NVPTX target devices.

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

	- Added emission of the debug information for the device code.

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

	These are major API changes that have happened since the 8.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 8.0.0
	release of Clang. Users of the build system should adjust accordingly.

	- In 8.0.0 and below, the install-clang-headers target would install clang's
	resource directory headers. This installation is now performed by the
	install-clang-resource-headers target. Users of the old install-clang-headers
	target should switch to the new install-clang-resource-headers target. The
	install-clang-headers target now installs clang's API headers (corresponding
	to its libraries), which is consistent with the install-llvm-headers target.

	- In 9.0.0 and later Clang added a new target on Linux/Unix systems, clang-cpp,
	which generates a shared library comprised of all the clang component
	libraries and exporting the clang C++ APIs. Additionally the build system
	gained the new "CLANG_LINK_CLANG_DYLIB" option, which defaults Off, and when
	set to On, will force clang (and clang-based tools) to link the clang-cpp
	library instead of statically linking clang's components. This option will
	reduce the size of binary distributions at the expense of compiler performance.


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

	- Add language support for clang-formatting C# files.
	- Add Microsoft coding style to encapsulate default C# formatting style.
	- Added new option ``PPDIS_BeforeHash`` (in configuration: ``BeforeHash``) to
	``IndentPPDirectives`` which indents preprocessor directives before the hash.
	- Added new option ``AlignConsecutiveMacros`` to align the C/C++ preprocessor
	macros of consecutive lines.

	libclang
	--------

	- When ``CINDEXTEST_INCLUDE_ATTRIBUTED_TYPES`` is not provided when making a
	CXType, the equivalent type of the AttributedType is returned instead of the
	modified type if the user does not want attribute sugar. The equivalent type
	represents the minimally-desugared type which the AttributedType is
	canonically equivalent to.


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

	- Fixed a bug where an incorrect checker name would be displayed for a bug
	report.

	- New checker: ``security.insecureAPI.DeprecatedOrUnsafeBufferHandling`` to detect
	uses of unsafe/deprecated buffer handling functions for C code using the C11
	standard or newer.

	- New checker: ``osx.MIGChecker`` to find violations of the Mach Interface
	Generator calling convention

	- New checker: ``optin.osx.OSObjectCStyleCast`` to find C-style casts of of XNU
	libkern OSObjects

	- New package: ``apiModeling.llvm`` contains modeling checkers to improve the
	accuracy of reports on LLVM's own codebase.

	- The Static Analyzer received
	:ref:`developer documentation <clang-static-analyzer-docs>`.

	- The UninitializedObject checker is now considered as stable.
	(moved from the ``alpha.cplusplus`` to the ``optin.cplusplus`` package)

	- New frontend flags: The list of available checkers are now split into 3
	different frontend flags:

	- ``-analyzer-checker-help``: The list of user-facing, stable checkers.

	- ``-analyzer-checker-help-alpha``: The list of in-development
	checkers not yet advised to be turned on.

	- ``-analyzer-checker-help-developer``: Checkers never meant to be
	enabled/disabled by hand + development checkers.

	- New frontend flags: While they have always been around, for the first time,
	checker and package options are listable:

	- ``-analyzer-checker-option-help``: The list of user-facing, stable checker
	and package options.

	- ``-analyzer-checker-option-help-alpha``: The list of in-development checker
	options not yet advised to be used.

	- ``-analyzer-checker-option-help-developer``: Options never meant to be
	enabled/disabled by hand + development options.

	- New frontend flag: ``-analyzer-werror`` to turn analyzer warnings into errors.

	- Numerous fixes to increase the stability of the experimental cross translation
	unit analysis (CTU).

	- CTU now handles virtual functions as well.


	Linux Kernel
	============

	With support for asm goto, the mainline Linux kernel for x86_64 is now buildable
	(and bootable) with Clang 9. Other architectures that don't require
	CONFIG_JUMP_LABEL=y such as arm, aarch64, ppc32, ppc64le, (and possibly mips)
	have been supported with older releases of Clang (Clang 4 was first used with
	aarch64).

	The Android and ChromeOS Linux distributions have moved to building their Linux
	kernels with Clang, and Google is currently testing Clang built kernels for
	their production Linux kernels.

	Further, LLD, llvm-objcopy, llvm-ar, llvm-nm, llvm-objdump can all be used to
	build a working Linux kernel.

	More information about building Linux kernels with Clang can be found:

	- `ClangBuiltLinux web page <https://clangbuiltlinux.github.io/>`_.
	- `Issue Tracker <https://github.com/ClangBuiltLinux/linux/issues>`_.
	- `Wiki <https://github.com/ClangBuiltLinux/linux/wiki>`_.
	- `Mailing List <clang-built-linux@googlegroups.com>`_.
	- `Bi-weekly Meeting <https://calendar.google.com/calendar/embed?src=google.com_bbf8m6m4n8nq5p2bfjpele0n5s%40group.calendar.google.com>`_.
	- #clangbuiltlinux on Freenode.
	- `Clang Meta bug <https://bugs.llvm.org/show_bug.cgi?id=4068>`_.
	- `Continuous Integration <https://travis-ci.com/ClangBuiltLinux/continuous-integration>`_.

	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 Subversion version of
	the source code. You can access versions of these documents specific to
	this release by going into the "``clang/docs/``" directory in the Clang
	tree.

	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>`_.