e131e4f127803a3b11a2f0f73a8882bd5c9ec1b4
[lldb.git] / clang / docs / ReleaseNotes.rst
1 ========================================
2 Clang 10.0.0 (In-Progress) Release Notes
3 ========================================
4
5 .. contents::
6    :local:
7    :depth: 2
8
9 Written by the `LLVM Team <https://llvm.org/>`_
10
11 .. warning::
12
13    These are in-progress notes for the upcoming Clang 10 release.
14    Release notes for previous releases can be found on
15    `the Download Page <https://releases.llvm.org/download.html>`_.
16
17 Introduction
18 ============
19
20 This document contains the release notes for the Clang C/C++/Objective-C
21 frontend, part of the LLVM Compiler Infrastructure, release 10.0.0. Here we
22 describe the status of Clang in some detail, including major
23 improvements from the previous release and new feature work. For the
24 general LLVM release notes, see `the LLVM
25 documentation <https://llvm.org/docs/ReleaseNotes.html>`_. All LLVM
26 releases may be downloaded from the `LLVM releases web
27 site <https://llvm.org/releases/>`_.
28
29 For more information about Clang or LLVM, including information about the
30 latest release, please see the `Clang Web Site <https://clang.llvm.org>`_ or the
31 `LLVM Web Site <https://llvm.org>`_.
32
33 Note that if you are reading this file from a Subversion checkout or the
34 main Clang web page, this document applies to the *next* release, not
35 the current one. To see the release notes for a specific release, please
36 see the `releases page <https://llvm.org/releases/>`_.
37
38 What's New in Clang 10.0.0?
39 ===========================
40
41 Some of the major new features and improvements to Clang are listed
42 here. Generic improvements to Clang as a whole or to its underlying
43 infrastructure are described first, followed by language-specific
44 sections with improvements to Clang's support for those languages.
45
46 Major New Features
47 ------------------
48
49 - ...
50
51 Improvements to Clang's diagnostics
52 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
53
54 - -Wtautological-overlap-compare will warn on negative numbers and non-int
55   types.
56 - -Wtautological-compare for self comparisons and
57   -Wtautological-overlap-compare will now look through member and array
58   access to determine if two operand expressions are the same.
59 - -Wtautological-bitwise-compare is a new warning group.  This group has the
60   current warning which diagnoses the tautological comparison of a bitwise
61   operation and a constant. The group also has the new warning which diagnoses
62   when a bitwise-or with a non-negative value is converted to a bool, since
63   that bool will always be true.
64 - -Wbitwise-conditional-parentheses will warn on operator precedence issues
65   when mixing bitwise-and (&) and bitwise-or (|) operator with the
66   conditional operator (?:).
67 - -Wrange-loop-analysis got several improvements. It no longer warns about a
68   copy being made when the result is bound to an rvalue reference. It no longer
69   warns when an object of a small, trivially copyable type is copied. The
70   warning now offers fixits. It is now part of -Wall.
71
72 Non-comprehensive list of changes in this release
73 -------------------------------------------------
74
75 * In both C and C++ (C17 ``6.5.6p8``, C++ ``[expr.add]``), pointer arithmetic is
76   only permitted within arrays. In particular, the behavior of a program is not
77   defined if it adds a non-zero offset (or in C, any offset) to a null pointer,
78   or if it forms a null pointer by subtracting an integer from a non-null
79   pointer, and the LLVM optimizer now uses those guarantees for transformations.
80   This may lead to unintended behavior in code that performs these operations.
81   The Undefined Behavior Sanitizer ``-fsanitize=pointer-overflow`` check has
82   been extended to detect these cases, so that code relying on them can be
83   detected and fixed.
84
85 * The Implicit Conversion Sanitizer (``-fsanitize=implicit-conversion``) has
86   learned to sanitize pre/post increment/decrement of types with bit width
87   smaller than ``int``.
88
89 - For X86 target, -march=skylake-avx512, -march=icelake-client,
90   -march=icelake-server, -march=cascadelake, -march=cooperlake will default to
91   not using 512-bit zmm registers in vectorized code unless 512-bit intrinsics
92   are used in the source code. 512-bit operations are known to cause the CPUs
93   to run at a lower frequency which can impact performance. This behavior can be
94   changed by passing -mprefer-vector-width=512 on the command line.
95
96 * clang now defaults to ``.init_array`` on Linux. It used to use ``.ctors`` if
97   the found gcc installation is older than 4.7.0. Add ``-fno-use-init-array`` to
98   get the old behavior (``.ctors``).
99
100 New Compiler Flags
101 ------------------
102
103 - The -fgnuc-version= flag now controls the value of ``__GNUC__`` and related
104   macros. This flag does not enable or disable any GCC extensions implemented in
105   Clang. Setting the version to zero causes Clang to leave ``__GNUC__`` and
106   other GNU-namespaced macros, such as ``__GXX_WEAK__``, undefined.
107
108 - vzeroupper insertion on X86 targets can now be disabled with -mno-vzeroupper.
109   You can also force vzeroupper insertion to be used on CPUs that normally
110   wouldn't with -mvzeroupper.
111
112 Deprecated Compiler Flags
113 -------------------------
114
115 The following options are deprecated and ignored. They will be removed in
116 future versions of Clang.
117
118 - -mmpx used to enable the __MPX__ preprocessor define for the Intel MPX
119   instructions. There were no MPX intrinsics.
120 - -mno-mpx used to disable -mmpx and is the default behavior.
121
122 - ...
123
124 Modified Compiler Flags
125 -----------------------
126
127 - RISC-V now sets the architecture (riscv32/riscv64) based on the value provided
128   to the ``-march`` flag, overriding the target provided by ``-triple``.
129
130 New Pragmas in Clang
131 --------------------
132
133 - ...
134
135 Attribute Changes in Clang
136 --------------------------
137
138 - ...
139
140 Windows Support
141 ---------------
142
143 - Previous Clang versions contained a work-around to avoid an issue with the
144   standard library headers in Visual Studio 2019 versions prior to 16.3. This
145   work-around has now been removed, and users of Visual Studio 2019 are
146   encouraged to upgrade to 16.3 or later, otherwise they may see link errors as
147   below:
148
149   .. code-block:: console
150
151     error LNK2005: "bool const std::_Is_integral<int>" (??$_Is_integral@H@std@@3_NB) already defined
152
153 C Language Changes in Clang
154 ---------------------------
155
156 - ...
157
158 C11 Feature Support
159 ^^^^^^^^^^^^^^^^^^^
160
161 ...
162
163 C++ Language Changes in Clang
164 -----------------------------
165
166 - The behaviour of the `gnu_inline` attribute now matches GCC, for cases
167   where used without the `extern` keyword. As this is a change compared to
168   how it behaved in previous Clang versions, a warning is emitted for this
169   combination.
170
171 C++1z Feature Support
172 ^^^^^^^^^^^^^^^^^^^^^
173
174 ...
175
176 Objective-C Language Changes in Clang
177 -------------------------------------
178
179 - In both Objective-C and
180   Objective-C++, ``-Wcompare-distinct-pointer-types`` will now warn when
181   comparing ObjC ``Class`` with an ObjC instance type pointer.
182
183   .. code-block:: objc
184
185     Class clz = ...;
186     MyType *instance = ...;
187     bool eq = (clz == instance); // Previously undiagnosed, now warns.
188
189 - Objective-C++ now diagnoses conversions between ``Class`` and ObjC
190   instance type pointers. Such conversions already emitted an
191   on-by-default ``-Wincompatible-pointer-types`` warning in Objective-C
192   mode, but had inadvertently been missed entirely in
193   Objective-C++. This has been fixed, and they are now diagnosed as
194   errors, consistent with the usual C++ treatment for conversions
195   between unrelated pointer types.
196
197   .. code-block:: objc
198
199     Class clz = ...;
200     MyType *instance = ...;
201     clz = instance; // Previously undiagnosed, now an error.
202     instance = clz; // Previously undiagnosed, now an error.
203
204   One particular issue you may run into is attempting to use a class
205   as a key in a dictionary literal. This will now result in an error,
206   because ``Class`` is not convertable to ``id<NSCopying>``. (Note that
207   this was already a warning in Objective-C mode.) While an arbitrary
208   ``Class`` object is not guaranteed to implement ``NSCopying``, the
209   default metaclass implementation does. Therefore, the recommended
210   solution is to insert an explicit cast to ``id``, which disables the
211   type-checking here.
212
213  .. code-block:: objc
214
215     Class cls = ...;
216
217     // Error: cannot convert from Class to id<NSCoding>.
218     NSDictionary* d = @{cls : @"Hello"};
219
220     // Fix: add an explicit cast to 'id'.
221     NSDictionary* d = @{(id)cls : @"Hello"};
222
223 OpenCL C Language Changes in Clang
224 ----------------------------------
225
226 ...
227
228 ABI Changes in Clang
229 --------------------
230
231 - gcc passes vectors of __int128 in memory on X86-64. Clang historically
232   broke the vectors into multiple scalars using two 64-bit values for each
233   element. Clang now matches the gcc behavior on Linux and NetBSD. You can
234   switch back to old API behavior with flag: -fclang-abi-compat=9.0.
235
236 - RISC-V now chooses a default ``-march=`` and ``-mabi=`` to match (in almost
237   all cases) the GCC defaults. On baremetal targets, where neither ``-march=``
238   nor ``-mabi=`` are specified, Clang now differs from GCC by defaulting to
239   ``-march=rv32imac -mabi=ilp32`` or ``-march=rv64imac -mabi=lp64`` depending on
240   the architecture in the target triple. These do not always match the defaults
241   in Clang 9. We strongly suggest that you explicitly pass `-march=` and
242   `-mabi=` when compiling for RISC-V, due to how extensible this architecture
243   is.
244
245 OpenMP Support in Clang
246 -----------------------
247
248 - ...
249
250 CUDA Support in Clang
251 ---------------------
252
253 - ...
254
255 Internal API Changes
256 --------------------
257
258 These are major API changes that have happened since the 9.0.0 release of
259 Clang. If upgrading an external codebase that uses Clang as a library,
260 this section should help get you past the largest hurdles of upgrading.
261
262 - libTooling APIs that transfer ownership of `FrontendAction` objects now pass
263   them by `unique_ptr`, making the ownership transfer obvious in the type
264   system. `FrontendActionFactory::create()` now returns a
265   `unique_ptr<FrontendAction>`. `runToolOnCode`, `runToolOnCodeWithArgs`,
266   `ToolInvocation::ToolInvocation()` now take a `unique_ptr<FrontendAction>`.
267
268 Build System Changes
269 --------------------
270
271 These are major changes to the build system that have happened since the 9.0.0
272 release of Clang. Users of the build system should adjust accordingly.
273
274 - In 8.0.0 and below, the install-clang-headers target would install clang's
275   resource directory headers. This installation is now performed by the
276   install-clang-resource-headers target. Users of the old install-clang-headers
277   target should switch to the new install-clang-resource-headers target. The
278   install-clang-headers target now installs clang's API headers (corresponding
279   to its libraries), which is consistent with the install-llvm-headers target.
280
281 - In 9.0.0 and later Clang added a new target, clang-cpp, which generates a
282   shared library comprised of all the clang component libraries and exporting
283   the clang C++ APIs. Additionally the build system gained the new
284   "CLANG_LINK_CLANG_DYLIB" option, which defaults Off, and when set to On, will
285   force clang (and clang-based tools) to link the clang-cpp library instead of
286   statically linking clang's components. This option will reduce the size of
287   binary distributions at the expense of compiler performance.
288
289 - ...
290
291 AST Matchers
292 ------------
293
294 - ...
295
296 clang-format
297 ------------
298
299 - The ``Standard`` style option specifies which version of C++ should be used
300   when parsing and formatting C++ code. The set of allowed values has changed:
301
302   - ``Latest`` will always enable new C++ language features.
303   - ``c++03``, ``c++11``, ``c++14``, ``c++17``, ``c++20`` will pin to exactly
304     that language version.
305   - ``Auto`` is the default and detects style from the code (this is unchanged).
306
307   The previous values of ``Cpp03`` and ``Cpp11`` are deprecated. Note that
308   ``Cpp11`` is treated as ``Latest``, as this was always clang-format's
309   behavior. (One motivation for this change is the new name describes the
310   behavior better).
311
312 - Clang-format has a new option called ``--dry-run`` or ``-n`` to emit a
313   warning for clang-format violations. This can be used together
314   with --ferror-limit=N to limit the number of warnings per file and --Werror
315   to make warnings into errors.
316
317 - Option *IncludeIsMainSourceRegex* has been added to allow for additional
318   suffixes and file extensions to be considered as a source file
319   for execution of logic that looks for "main *include* file" to put
320   it on top.
321
322   By default, clang-format considers *source* files as "main" only when
323   they end with: ``.c``, ``.cc``, ``.cpp``, ``.c++``, ``.cxx``,
324   ``.m`` or ``.mm`` extensions. This config option allows to
325   extend this set of source files considered as "main".
326
327   For example, if this option is configured to ``(Impl\.hpp)$``,
328   then a file ``ClassImpl.hpp`` is considered "main" (in addition to
329   ``Class.c``, ``Class.cc``, ``Class.cpp`` and so on) and "main
330   include file" logic will be executed (with *IncludeIsMainRegex* setting
331   also being respected in later phase). Without this option set,
332   ``ClassImpl.hpp`` would not have the main include file put on top
333   before any other include.
334
335 - Options ``DeriveLineEnding`` and  ``UseCRLF`` have been added to allow
336   clang-format to control the newlines. ``DeriveLineEnding`` is by default
337   ``true`` and reflects is the existing mechanism, which based is on majority
338   rule. The new options allows this to be turned off and ``UseCRLF`` to control
339   the decision as to which sort of line ending to use.
340
341 - Option ``SpaceBeforeSquareBrackets`` has been added to insert a space before
342   array declarations.
343
344   .. code-block:: c++
345
346     int a [5];    vs    int a[5];
347
348 - Clang-format now supports JavaScript null operators.
349
350   .. code-block:: c++
351
352     const x = foo ?? default;
353     const z = foo?.bar?.baz;
354
355 libclang
356 --------
357
358 - ...
359
360 Static Analyzer
361 ---------------
362
363 - The Clang analyzer checker ``DeadStores`` gets a new option called
364   ``WarnForDeadNestedAssignments`` to detect nested dead assignments
365   (enabled by default).
366 - ...
367
368 .. _release-notes-ubsan:
369
370 Undefined Behavior Sanitizer (UBSan)
371 ------------------------------------
372
373 - * The ``pointer-overflow`` check was extended added to catch the cases where
374     a non-zero offset is applied to a null pointer, or the result of
375     applying the offset is a null pointer.
376
377     .. code-block:: c++
378
379       #include <cstdint> // for intptr_t
380
381       static char *getelementpointer_inbounds(char *base, unsigned long offset) {
382         // Potentially UB.
383         return base + offset;
384       }
385
386       char *getelementpointer_unsafe(char *base, unsigned long offset) {
387         // Always apply offset. UB if base is ``nullptr`` and ``offset`` is not
388         // zero, or if ``base`` is non-``nullptr`` and ``offset`` is
389         // ``-reinterpret_cast<intptr_t>(base)``.
390         return getelementpointer_inbounds(base, offset);
391       }
392
393       char *getelementpointer_safe(char *base, unsigned long offset) {
394         // Cast pointer to integer, perform usual arithmetic addition,
395         // and cast to pointer. This is legal.
396         char *computed =
397             reinterpret_cast<char *>(reinterpret_cast<intptr_t>(base) + offset);
398         // If either the pointer becomes non-``nullptr``, or becomes
399         // ``nullptr``, we must use ``computed`` result.
400         if (((base == nullptr) && (computed != nullptr)) ||
401             ((base != nullptr) && (computed == nullptr)))
402           return computed;
403         // Else we can use ``getelementpointer_inbounds()``.
404         return getelementpointer_inbounds(base, offset);
405       }
406
407 Core Analysis Improvements
408 ==========================
409
410 - ...
411
412 New Issues Found
413 ================
414
415 - ...
416
417 Python Binding Changes
418 ----------------------
419
420 The following methods have been added:
421
422 -  ...
423
424 Significant Known Problems
425 ==========================
426
427 Additional Information
428 ======================
429
430 A wide variety of additional information is available on the `Clang web
431 page <https://clang.llvm.org/>`_. The web page contains versions of the
432 API documentation which are up-to-date with the Subversion version of
433 the source code. You can access versions of these documents specific to
434 this release by going into the "``clang/docs/``" directory in the Clang
435 tree.
436
437 If you have any questions or comments about Clang, please feel free to
438 contact us via the `mailing
439 list <https://lists.llvm.org/mailman/listinfo/cfe-dev>`_.