1========================================
2Clang 11.0.0 (In-Progress) Release Notes
3========================================
4
5.. contents::
6   :local:
7   :depth: 2
8
9Written by the `LLVM Team <https://llvm.org/>`_
10
11.. warning::
12
13   These are in-progress notes for the upcoming Clang 11 release.
14   Release notes for previous releases can be found on
15   `the Download Page <https://releases.llvm.org/download.html>`_.
16
17Introduction
18============
19
20This document contains the release notes for the Clang C/C++/Objective-C
21frontend, part of the LLVM Compiler Infrastructure, release 11.0.0. Here we
22describe the status of Clang in some detail, including major
23improvements from the previous release and new feature work. For the
24general LLVM release notes, see `the LLVM
25documentation <https://llvm.org/docs/ReleaseNotes.html>`_. All LLVM
26releases may be downloaded from the `LLVM releases web
27site <https://llvm.org/releases/>`_.
28
29For more information about Clang or LLVM, including information about the
30latest release, please see the `Clang Web Site <https://clang.llvm.org>`_ or the
31`LLVM Web Site <https://llvm.org>`_.
32
33Note that if you are reading this file from a Git checkout or the
34main Clang web page, this document applies to the *next* release, not
35the current one. To see the release notes for a specific release, please
36see the `releases page <https://llvm.org/releases/>`_.
37
38What's New in Clang 11.0.0?
39===========================
40
41Some of the major new features and improvements to Clang are listed
42here. Generic improvements to Clang as a whole or to its underlying
43infrastructure are described first, followed by language-specific
44sections with improvements to Clang's support for those languages.
45
46Major New Features
47------------------
48
49- ...
50
51Improvements to Clang's diagnostics
52^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
53
54- -Wpointer-to-int-cast is a new warning group. This group warns about C-style
55  casts of pointers to a integer type too small to hold all possible values.
56
57- -Wuninitialized-const-reference is a new warning controlled by
58  -Wuninitialized. It warns on cases where uninitialized variables are passed
59  as const reference arguments to a function.
60
61Non-comprehensive list of changes in this release
62-------------------------------------------------
63
64- For the ARM target, C-language intrinsics are now provided for the full Arm
65  v8.1-M MVE instruction set. ``<arm_mve.h>`` supports the complete API defined
66  in the Arm C Language Extensions.
67
68- For the ARM target, C-language intrinsics ``<arm_cde.h>`` for the CDE
69  instruction set are now provided.
70
71- clang adds support for a set of  extended integer types (``_ExtInt(N)``) that
72  permit non-power of 2 integers, exposing the LLVM integer types. Since a major
73  motivating use case for these types is to limit 'bit' usage, these types don't
74  automatically promote to 'int' when operations are done between two
75  ``ExtInt(N)`` types, instead math occurs at the size of the largest
76  ``ExtInt(N)`` type.
77
78- Users of UBSan, PGO, and coverage on Windows will now need to add clang's
79  library resource directory to their library search path. These features all
80  use runtime libraries, and Clang provides these libraries in its resource
81  directory. For example, if LLVM is installed in ``C:\Program Files\LLVM``,
82  then the profile runtime library will appear at
83  ``C:\Program Files\LLVM\lib\clang\11.0.0\lib\windows\clang_rt.profile-x86_64.lib``.
84  To ensure that the linker can find the appropriate library, users should pass
85  ``/LIBPATH:C:\Program Files\LLVM\lib\clang\11.0.0\lib\windows`` to the
86  linker. If the user links the program with the ``clang`` or ``clang-cl``
87  drivers, the driver will pass this flag for them.
88
89- Clang's profile files generated through ``-fprofile-instr-generate`` are using
90  a fixed hashing algorithm that prevents some collision when loading
91  out-of-date profile informations. Clang can still read old profile files.
92
93New Compiler Flags
94------------------
95
96- -fstack-clash-protection will provide a protection against the stack clash
97  attack for x86, s390x and ppc64 architectures through automatic probing of
98  each page of allocated stack.
99
100- -ffp-exception-behavior={ignore,maytrap,strict} allows the user to specify
101  the floating-point exception behavior. The default setting is ``ignore``.
102
103- -ffp-model={precise,strict,fast} provides the user an umbrella option to
104  simplify access to the many single purpose floating point options. The default
105  setting is ``precise``.
106
107- The default module cache has moved from /tmp to a per-user cache directory.
108  By default, this is ~/.cache but on some platforms or installations, this
109  might be elsewhere. The -fmodules-cache-path=... flag continues to work.
110
111- -fpch-instantiate-templates tries to instantiate templates already while
112  generating a precompiled header. Such templates do not need to be
113  instantiated every time the precompiled header is used, which saves compile
114  time. This may result in an error during the precompiled header generation
115  if the source header file is not self-contained. This option is enabled
116  by default for clang-cl.
117
118Deprecated Compiler Flags
119-------------------------
120
121The following options are deprecated and ignored. They will be removed in
122future versions of Clang.
123
124- ...
125
126Modified Compiler Flags
127-----------------------
128
129- -fno-common has been enabled as the default for all targets.  Therefore, C
130  code that uses tentative definitions as definitions of a variable in multiple
131  translation units will trigger multiple-definition linker errors. Generally,
132  this occurs when the use of the ``extern`` keyword is neglected in the
133  declaration of a variable in a header file. In some cases, no specific
134  translation unit provides a definition of the variable. The previous
135  behavior can be restored by specifying ``-fcommon``.
136- -Wasm-ignored-qualifier (ex. `asm const ("")`) has been removed and replaced
137  with an error (this matches a recent change in GCC-9).
138- -Wasm-file-asm-volatile (ex. `asm volatile ("")` at global scope) has been
139  removed and replaced with an error (this matches GCC's behavior).
140- Duplicate qualifiers on asm statements (ex. `asm volatile volatile ("")`) no
141  longer produces a warning via -Wduplicate-decl-specifier, but now an error
142  (this matches GCC's behavior).
143- The deprecated argument ``-f[no-]sanitize-recover`` has changed to mean
144  ``-f[no-]sanitize-recover=all`` instead of
145  ``-f[no-]sanitize-recover=undefined,integer`` and is no longer deprecated.
146- The argument to ``-f[no-]sanitize-trap=...`` is now optional and defaults to
147  ``all``.
148- ``-fno-char8_t`` now disables the ``char8_t`` keyword, not just the use of
149  ``char8_t`` as the character type of ``u8`` literals. This restores the
150  Clang 8 behavior that regressed in Clang 9 and 10.
151- -print-targets has been added to print the registered targets.
152
153New Pragmas in Clang
154--------------------
155
156- ...
157
158Attribute Changes in Clang
159--------------------------
160
161- Attributes can now be specified by clang plugins. See the
162  `Clang Plugins <ClangPlugins.html#defining-attributes>`_ documentation for
163  details.
164
165Windows Support
166---------------
167
168C Language Changes in Clang
169---------------------------
170
171- The default C language standard used when `-std=` is not specified has been
172  upgraded from gnu11 to gnu17.
173
174- Clang now supports the GNU C extension `asm inline`; it won't do anything
175  *yet*, but it will be parsed.
176
177- ...
178
179C++ Language Changes in Clang
180-----------------------------
181
182- Clang now implements a restriction on giving non-C-compatible anonymous
183  structs a typedef name for linkage purposes, as described in C++ committee
184  paper `P1766R1 <http://wg21.link/p1766r1>`. This paper was adopted by the
185  C++ committee as a Defect Report resolution, so it is applied retroactively
186  to all C++ standard versions. This affects code such as:
187
188  .. code-block:: c++
189
190    typedef struct {
191      int f() { return 0; }
192    } S;
193
194  Previous versions of Clang rejected some constructs of this form
195  (specifically, where the linkage of the type happened to be computed
196  before the parser reached the typedef name); those cases are still rejected
197  in Clang 11. In addition, cases that previous versions of Clang did not
198  reject now produce an extension warning. This warning can be disabled with
199  the warning flag ``-Wno-non-c-typedef-for-linkage``.
200
201  Affected code should be updated to provide a tag name for the anonymous
202  struct:
203
204  .. code-block:: c++
205
206    struct S {
207      int f() { return 0; }
208    };
209
210  If the code is shared with a C compilation (for example, if the parts that
211  are not C-compatible are guarded with ``#ifdef __cplusplus``), the typedef
212  declaration should be retained, but a tag name should still be provided:
213
214  .. code-block:: c++
215
216    typedef struct S {
217      int f() { return 0; }
218    } S;
219
220C++1z Feature Support
221^^^^^^^^^^^^^^^^^^^^^
222
223...
224
225Objective-C Language Changes in Clang
226-------------------------------------
227
228OpenCL C Language Changes in Clang
229----------------------------------
230
231...
232
233ABI Changes in Clang
234--------------------
235
236OpenMP Support in Clang
237-----------------------
238
239- ...
240
241CUDA Support in Clang
242---------------------
243
244- ...
245
246Internal API Changes
247--------------------
248
249These are major API changes that have happened since the 10.0.0 release of
250Clang. If upgrading an external codebase that uses Clang as a library,
251this section should help get you past the largest hurdles of upgrading.
252
253- ``RecursiveASTVisitor`` no longer calls separate methods to visit specific
254  operator kinds. Previously, ``RecursiveASTVisitor`` treated unary, binary,
255  and compound assignment operators as if they were subclasses of the
256  corresponding AST node. For example, the binary operator plus was treated as
257  if it was a ``BinAdd`` subclass of the ``BinaryOperator`` class: during AST
258  traversal of a ``BinaryOperator`` AST node that had a ``BO_Add`` opcode,
259  ``RecursiveASTVisitor`` was calling the ``TraverseBinAdd`` method instead of
260  ``TraverseBinaryOperator``. This feature was contributing a non-trivial
261  amount of complexity to the implementation of ``RecursiveASTVisitor``, it was
262  used only in a minor way in Clang, was not tested, and as a result it was
263  buggy. Furthermore, this feature was creating a non-uniformity in the API.
264  Since this feature was not documented, it was quite difficult to figure out
265  how to use ``RecursiveASTVisitor`` to visit operators.
266
267  To update your code to the new uniform API, move the code from separate
268  visitation methods into methods that correspond to the actual AST node and
269  perform case analysis based on the operator opcode as needed:
270
271  * ``TraverseUnary*() => TraverseUnaryOperator()``
272  * ``WalkUpFromUnary*() => WalkUpFromUnaryOperator()``
273  * ``VisitUnary*() => VisiUnaryOperator()``
274  * ``TraverseBin*() => TraverseBinaryOperator()``
275  * ``WalkUpFromBin*() => WalkUpFromBinaryOperator()``
276  * ``VisitBin*() => VisiBinaryOperator()``
277  * ``TraverseBin*Assign() => TraverseCompoundAssignOperator()``
278  * ``WalkUpFromBin*Assign() => WalkUpFromCompoundAssignOperator()``
279  * ``VisitBin*Assign() => VisiCompoundAssignOperator()``
280
281Build System Changes
282--------------------
283
284These are major changes to the build system that have happened since the 10.0.0
285release of Clang. Users of the build system should adjust accordingly.
286
287- clang-tidy and clang-include-fixer are no longer compiled into libclang by
288  default. You can set ``LIBCLANG_INCLUDE_CLANG_TOOLS_EXTRA=ON`` to undo that,
289  but it's expected that that setting will go away eventually. If this is
290  something you need, please reach out to the mailing list to discuss possible
291  ways forward.
292
293AST Matchers
294------------
295
296- ...
297
298clang-format
299------------
300
301- Option ``IndentExternBlock`` has been added to optionally apply indenting inside ``extern "C"`` and ``extern "C++"`` blocks.
302
303- ``IndentExternBlock`` option accepts ``AfterExternBlock`` to use the old behavior, as well as Indent and NoIndent options, which map to true and false, respectively.
304
305  .. code-block:: c++
306
307    Indent:                       NoIndent:
308     #ifdef __cplusplus          #ifdef __cplusplus
309     extern "C" {                extern "C++" {
310     #endif                      #endif
311
312          void f(void);          void f(void);
313
314     #ifdef __cplusplus          #ifdef __cplusplus
315     }                           }
316     #endif                      #endif
317
318- Option ``IndentCaseBlocks`` has been added to support treating the block
319  following a switch case label as a scope block which gets indented itself.
320  It helps avoid having the closing bracket align with the switch statement's
321  closing bracket (when ``IndentCaseLabels`` is ``false``).
322
323  .. code-block:: c++
324
325    switch (fool) {                vs.     switch (fool) {
326    case 1:                                case 1: {
327      {                                      bar();
328         bar();                            } break;
329      }                                    default: {
330      break;                                 plop();
331    default:                               }
332      {                                    }
333        plop();
334      }
335    }
336
337- Option ``ObjCBreakBeforeNestedBlockParam`` has been added to optionally apply
338  linebreaks for function arguments declarations before nested blocks.
339
340- Option ``InsertTrailingCommas`` can be set to ``TCS_Wrapped`` to insert
341  trailing commas in container literals (arrays and objects) that wrap across
342  multiple lines. It is currently only available for JavaScript and disabled by
343  default (``TCS_None``).
344
345- Option ``BraceWrapping.BeforeLambdaBody`` has been added to manage lambda
346  line break inside function parameter call in Allman style.
347
348  .. code-block:: c++
349
350      true:
351      connect(
352        []()
353        {
354          foo();
355          bar();
356        });
357
358      false:
359      connect([]() {
360          foo();
361          bar();
362        });
363
364- Option ``AlignConsecutiveBitFields`` has been added to align bit field
365  declarations across multiple adjacent lines
366
367  .. code-block:: c++
368
369      true:
370        bool aaa  : 1;
371        bool a    : 1;
372        bool bb   : 1;
373
374      false:
375        bool aaa : 1;
376        bool a : 1;
377        bool bb : 1;
378
379- Option ``BraceWrapping.BeforeWhile`` has been added to allow wrapping
380  before the ```while`` in a do..while loop. By default the value is (``false``)
381
382  In previous releases ``IndentBraces`` implied ``BraceWrapping.BeforeWhile``.
383  If using a Custom BraceWrapping style you may need to now set
384  ``BraceWrapping.BeforeWhile`` to (``true``) to be explicit.
385
386  .. code-block:: c++
387
388      true:
389      do {
390        foo();
391      }
392      while(1);
393
394      false:
395      do {
396        foo();
397      } while(1);
398
399libclang
400--------
401
402- ...
403
404Static Analyzer
405---------------
406
407- ...
408
409.. _release-notes-ubsan:
410
411Undefined Behavior Sanitizer (UBSan)
412------------------------------------
413
414Core Analysis Improvements
415==========================
416
417- ...
418
419New Issues Found
420================
421
422- ...
423
424Python Binding Changes
425----------------------
426
427The following methods have been added:
428
429-  ...
430
431Significant Known Problems
432==========================
433
434Additional Information
435======================
436
437A wide variety of additional information is available on the `Clang web
438page <https://clang.llvm.org/>`_. The web page contains versions of the
439API documentation which are up-to-date with the Git version of
440the source code. You can access versions of these documents specific to
441this release by going into the "``clang/docs/``" directory in the Clang
442tree.
443
444If you have any questions or comments about Clang, please feel free to
445contact us via the `mailing
446list <https://lists.llvm.org/mailman/listinfo/cfe-dev>`_.
447