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
57Non-comprehensive list of changes in this release
58-------------------------------------------------
59
60- For the ARM target, C-language intrinsics are now provided for the full Arm
61  v8.1-M MVE instruction set. ``<arm_mve.h>`` supports the complete API defined
62  in the Arm C Language Extensions.
63
64- For the ARM target, C-language intrinsics ``<arm_cde.h>`` for the CDE
65  instruction set are now provided.
66
67- clang adds support for a set of  extended integer types (``_ExtInt(N)``) that
68  permit non-power of 2 integers, exposing the LLVM integer types. Since a major
69  motivating use case for these types is to limit 'bit' usage, these types don't
70  automatically promote to 'int' when operations are done between two
71  ``ExtInt(N)`` types, instead math occurs at the size of the largest
72  ``ExtInt(N)`` type.
73
74- Users of UBSan, PGO, and coverage on Windows will now need to add clang's
75  library resource directory to their library search path. These features all
76  use runtime libraries, and Clang provides these libraries in its resource
77  directory. For example, if LLVM is installed in ``C:\Program Files\LLVM``,
78  then the profile runtime library will appear at
79  ``C:\Program Files\LLVM\lib\clang\11.0.0\lib\windows\clang_rt.profile-x86_64.lib``.
80  To ensure that the linker can find the appropriate library, users should pass
81  ``/LIBPATH:C:\Program Files\LLVM\lib\clang\11.0.0\lib\windows`` to the
82  linker. If the user links the program with the ``clang`` or ``clang-cl``
83  drivers, the driver will pass this flag for them.
84
85- Clang's profile files generated through ``-fprofile-instr-generate`` are using
86  a fixed hashing algorithm that prevents some collision when loading
87  out-of-date profile informations. Clang can still read old profile files.
88
89New Compiler Flags
90------------------
91
92- -fstack-clash-protection will provide a protection against the stack clash
93  attack for x86 architecture through automatic probing of each page of
94  allocated stack.
95
96- -ffp-exception-behavior={ignore,maytrap,strict} allows the user to specify
97  the floating-point exception behavior. The default setting is ``ignore``.
98
99- -ffp-model={precise,strict,fast} provides the user an umbrella option to
100  simplify access to the many single purpose floating point options. The default
101  setting is ``precise``.
102
103Deprecated Compiler Flags
104-------------------------
105
106The following options are deprecated and ignored. They will be removed in
107future versions of Clang.
108
109- ...
110
111Modified Compiler Flags
112-----------------------
113
114- -fno-common has been enabled as the default for all targets.  Therefore, C
115  code that uses tentative definitions as definitions of a variable in multiple
116  translation units will trigger multiple-definition linker errors. Generally,
117  this occurs when the use of the ``extern`` keyword is neglected in the
118  declaration of a variable in a header file. In some cases, no specific
119  translation unit provides a definition of the variable. The previous
120  behavior can be restored by specifying ``-fcommon``.
121- -Wasm-ignored-qualifier (ex. `asm const ("")`) has been removed and replaced
122  with an error (this matches a recent change in GCC-9).
123- -Wasm-file-asm-volatile (ex. `asm volatile ("")` at global scope) has been
124  removed and replaced with an error (this matches GCC's behavior).
125- Duplicate qualifiers on asm statements (ex. `asm volatile volatile ("")`) no
126  longer produces a warning via -Wduplicate-decl-specifier, but now an error
127  (this matches GCC's behavior).
128- The deprecated argument ``-f[no-]sanitize-recover`` has changed to mean
129  ``-f[no-]sanitize-recover=all`` instead of
130  ``-f[no-]sanitize-recover=undefined,integer`` and is no longer deprecated.
131- The argument to ``-f[no-]sanitize-trap=...`` is now optional and defaults to
132  ``all``.
133- ``-fno-char8_t`` now disables the ``char8_t`` keyword, not just the use of
134  ``char8_t`` as the character type of ``u8`` literals. This restores the
135  Clang 8 behavior that regressed in Clang 9 and 10.
136- -print-targets has been added to print the registered targets.
137
138New Pragmas in Clang
139--------------------
140
141- ...
142
143Attribute Changes in Clang
144--------------------------
145
146- Attributes can now be specified by clang plugins. See the
147  `Clang Plugins <ClangPlugins.html#defining-attributes>`_ documentation for
148  details.
149
150Windows Support
151---------------
152
153C Language Changes in Clang
154---------------------------
155
156- The default C language standard used when `-std=` is not specified has been
157  upgraded from gnu11 to gnu17.
158
159- Clang now supports the GNU C extension `asm inline`; it won't do anything
160  *yet*, but it will be parsed.
161
162- ...
163
164C++ Language Changes in Clang
165-----------------------------
166
167- Clang now implements a restriction on giving non-C-compatible anonymous
168  structs a typedef name for linkage purposes, as described in C++ committee
169  paper `P1766R1 <http://wg21.link/p1766r1>`. This paper was adopted by the
170  C++ committee as a Defect Report resolution, so it is applied retroactively
171  to all C++ standard versions. This affects code such as:
172
173  .. code-block:: c++
174
175    typedef struct {
176      int f() { return 0; }
177    } S;
178
179  Previous versions of Clang rejected some constructs of this form
180  (specifically, where the linkage of the type happened to be computed
181  before the parser reached the typedef name); those cases are still rejected
182  in Clang 11. In addition, cases that previous versions of Clang did not
183  reject now produce an extension warning. This warning can be disabled with
184  the warning flag ``-Wno-non-c-typedef-for-linkage``.
185
186  Affected code should be updated to provide a tag name for the anonymous
187  struct:
188
189  .. code-block:: c++
190
191    struct S {
192      int f() { return 0; }
193    };
194
195  If the code is shared with a C compilation (for example, if the parts that
196  are not C-compatible are guarded with ``#ifdef __cplusplus``), the typedef
197  declaration should be retained, but a tag name should still be provided:
198
199  .. code-block:: c++
200
201    typedef struct S {
202      int f() { return 0; }
203    } S;
204
205C++1z Feature Support
206^^^^^^^^^^^^^^^^^^^^^
207
208...
209
210Objective-C Language Changes in Clang
211-------------------------------------
212
213OpenCL C Language Changes in Clang
214----------------------------------
215
216...
217
218ABI Changes in Clang
219--------------------
220
221OpenMP Support in Clang
222-----------------------
223
224- ...
225
226CUDA Support in Clang
227---------------------
228
229- ...
230
231Internal API Changes
232--------------------
233
234These are major API changes that have happened since the 10.0.0 release of
235Clang. If upgrading an external codebase that uses Clang as a library,
236this section should help get you past the largest hurdles of upgrading.
237
238Build System Changes
239--------------------
240
241These are major changes to the build system that have happened since the 10.0.0
242release of Clang. Users of the build system should adjust accordingly.
243
244- clang-tidy and clang-include-fixer are no longer compiled into libclang by
245  default. You can set ``LIBCLANG_INCLUDE_CLANG_TOOLS_EXTRA=ON`` to undo that,
246  but it's expected that that setting will go away eventually. If this is
247  something you need, please reach out to the mailing list to discuss possible
248  ways forward.
249
250AST Matchers
251------------
252
253- Traversal in AST Matchers was simplified to use the
254  ``TK_IgnoreUnlessSpelledInSource`` mode by default, instead of ``TK_AsIs``.
255  This means that many uses of the ``ignoringImplicit()`` and similar matchers
256  is no longer necessary.  Clients of AST Matchers which wish to match on
257  implicit AST nodes can wrap their matcher in ``traverse(TK_AsIs, ...)`` or
258  use ``TraversalKindScope`` if appropriate.  The ``clang-query`` tool also
259  uses ``IgnoreUnlessSpelledInSource`` by default.  The mode can be changed
260  using ``set traversal AsIs`` in the ``clang-query`` environment.
261
262clang-format
263------------
264
265- Option ``IndentExternBlock`` has been added to optionally apply indenting inside ``extern "C"`` and ``extern "C++"`` blocks.
266
267- ``IndentExternBlock`` option accepts ``AfterExternBlock`` to use the old behavior, as well as Indent and NoIndent options, which map to true and false, respectively.
268
269  .. code-block:: c++
270
271    Indent:                       NoIndent:
272     #ifdef __cplusplus          #ifdef __cplusplus
273     extern "C" {                extern "C++" {
274     #endif                      #endif
275
276          void f(void);          void f(void);
277
278     #ifdef __cplusplus          #ifdef __cplusplus
279     }                           }
280     #endif                      #endif
281
282- Option ``IndentCaseBlocks`` has been added to support treating the block
283  following a switch case label as a scope block which gets indented itself.
284  It helps avoid having the closing bracket align with the switch statement's
285  closing bracket (when ``IndentCaseLabels`` is ``false``).
286
287  .. code-block:: c++
288
289    switch (fool) {                vs.     switch (fool) {
290    case 1:                                case 1: {
291      {                                      bar();
292         bar();                            } break;
293      }                                    default: {
294      break;                                 plop();
295    default:                               }
296      {                                    }
297        plop();
298      }
299    }
300
301- Option ``ObjCBreakBeforeNestedBlockParam`` has been added to optionally apply
302  linebreaks for function arguments declarations before nested blocks.
303
304- Option ``InsertTrailingCommas`` can be set to ``TCS_Wrapped`` to insert
305  trailing commas in container literals (arrays and objects) that wrap across
306  multiple lines. It is currently only available for JavaScript and disabled by
307  default (``TCS_None``).
308
309- Option ``BraceWrapping.BeforeLambdaBody`` has been added to manage lambda
310  line break inside function parameter call in Allman style.
311
312  .. code-block:: c++
313
314      true:
315      connect(
316        []()
317        {
318          foo();
319          bar();
320        });
321
322      false:
323      connect([]() {
324          foo();
325          bar();
326        });
327
328- Option ``AlignConsecutiveBitFields`` has been added to align bit field
329  declarations across multiple adjacent lines
330
331  .. code-block:: c++
332
333      true:
334        bool aaa  : 1;
335        bool a    : 1;
336        bool bb   : 1;
337
338      false:
339        bool aaa : 1;
340        bool a : 1;
341        bool bb : 1;
342
343- Option ``BraceWrapping.BeforeWhile`` has been added to allow wrapping
344  before the ```while`` in a do..while loop. By default the value is (``false``)
345
346  In previous releases ``IndentBraces`` implied ``BraceWrapping.BeforeWhile``.
347  If using a Custom BraceWrapping style you may need to now set
348  ``BraceWrapping.BeforeWhile`` to (``true``) to be explicit.
349
350  .. code-block:: c++
351
352      true:
353      do {
354        foo();
355      }
356      while(1);
357
358      false:
359      do {
360        foo();
361      } while(1);
362
363libclang
364--------
365
366- ...
367
368Static Analyzer
369---------------
370
371- ...
372
373.. _release-notes-ubsan:
374
375Undefined Behavior Sanitizer (UBSan)
376------------------------------------
377
378Core Analysis Improvements
379==========================
380
381- ...
382
383New Issues Found
384================
385
386- ...
387
388Python Binding Changes
389----------------------
390
391The following methods have been added:
392
393-  ...
394
395Significant Known Problems
396==========================
397
398Additional Information
399======================
400
401A wide variety of additional information is available on the `Clang web
402page <https://clang.llvm.org/>`_. The web page contains versions of the
403API documentation which are up-to-date with the Git version of
404the source code. You can access versions of these documents specific to
405this release by going into the "``clang/docs/``" directory in the Clang
406tree.
407
408If you have any questions or comments about Clang, please feel free to
409contact us via the `mailing
410list <https://lists.llvm.org/mailman/listinfo/cfe-dev>`_.
411