blob: c2a43a6873ecbb8c5daf0f2776bc90bb50a998ef [file] [log] [blame]
Hans Wennborg003a9982019-07-18 11:51:05 +00001=========================================
Tom Stellard688b1e22022-02-01 23:29:29 -08002Libc++ 15.0.0 (In-Progress) Release Notes
Hans Wennborg003a9982019-07-18 11:51:05 +00003=========================================
Louis Dionne42222072018-09-06 14:46:22 +00004
5.. contents::
6 :local:
7 :depth: 2
8
Hans Wennborg3329a842018-09-10 08:57:12 +00009Written by the `Libc++ Team <https://libcxx.llvm.org>`_
Louis Dionne42222072018-09-06 14:46:22 +000010
11.. warning::
12
Tom Stellard688b1e22022-02-01 23:29:29 -080013 These are in-progress notes for the upcoming libc++ 15 release.
Louis Dionne42222072018-09-06 14:46:22 +000014 Release notes for previous releases can be found on
Hans Wennborg3329a842018-09-10 08:57:12 +000015 `the Download Page <https://releases.llvm.org/download.html>`_.
Louis Dionne42222072018-09-06 14:46:22 +000016
17Introduction
18============
19
20This document contains the release notes for the libc++ C++ Standard Library,
Tom Stellard688b1e22022-02-01 23:29:29 -080021part of the LLVM Compiler Infrastructure, release 15.0.0. Here we describe the
Louis Dionne42222072018-09-06 14:46:22 +000022status of libc++ in some detail, including major improvements from the previous
23release and new feature work. For the general LLVM release notes, see `the LLVM
Hans Wennborg3329a842018-09-10 08:57:12 +000024documentation <https://llvm.org/docs/ReleaseNotes.html>`_. All LLVM releases may
25be downloaded from the `LLVM releases web site <https://llvm.org/releases/>`_.
Louis Dionne42222072018-09-06 14:46:22 +000026
27For more information about libc++, please see the `Libc++ Web Site
Hans Wennborg3329a842018-09-10 08:57:12 +000028<https://libcxx.llvm.org>`_ or the `LLVM Web Site <https://llvm.org>`_.
Louis Dionne42222072018-09-06 14:46:22 +000029
Hans Wennborgfc14f4e2020-01-15 10:02:56 +010030Note that if you are reading this file from a Git checkout or the
Louis Dionne42222072018-09-06 14:46:22 +000031main Libc++ web page, this document applies to the *next* release, not
32the current one. To see the release notes for a specific release, please
Hans Wennborg3329a842018-09-10 08:57:12 +000033see the `releases page <https://llvm.org/releases/>`_.
Louis Dionne42222072018-09-06 14:46:22 +000034
Tom Stellard688b1e22022-02-01 23:29:29 -080035What's New in Libc++ 15.0.0?
Hans Wennborg003a9982019-07-18 11:51:05 +000036============================
Louis Dionne42222072018-09-06 14:46:22 +000037
38New Features
39------------
40
Louis Dionne09b35772022-03-16 17:26:26 -040041- Implemented P0627R6 (Function to mark unreachable code)
Arthur O'Dwyer6266d872021-12-29 14:11:46 -050042
Louis Dionne09b35772022-03-16 17:26:26 -040043- Implemented P1165R1 (Make stateful allocator propagation more consistent for ``operator+(basic_string)``)
Nikolas Klausercfe21472022-02-14 18:26:02 +010044
Louis Dionnee9520982022-05-06 11:18:01 -040045- Implemented P0674R1 (Support arrays in ``make_shared`` and ``allocate_shared``)
46
47- Implemented P0980R1 (Making ``std::string`` constexpr)
Louis Dionne29464972021-10-26 13:12:12 -040048
varconstae56eea2022-05-14 13:07:08 -070049- Marked the following papers as "Complete" (note that some of those might have
50 been implemented in a previous release but not marked as such):
51
52 - P1207R4 (Movability of Single-pass Iterators);
53 - P1474R1 (Helpful pointers for ``ContiguousIterator``);
54 - P1522R1 (Iterator Difference Type and Integer Overflow);
55 - P1523R1 (Views and Size Types);
56 - P1456R1 (Move-only views);
57 - P1870R1 (``forwarding-range`` is too subtle);
58 - P1878R1 (Constraining Readable Types);
59 - P1970R2 (Consistency for ``size()`` functions: Add ``ranges::ssize``);
60 - P1983R0 (Wording for GB301, US296, US292, US291, and US283).
61
Louis Dionne09b35772022-03-16 17:26:26 -040062- `pop_heap` now uses an algorithm known as "bottom-up heapsort" or
63 "heapsort with bounce" to reduce the number of comparisons, and rearranges
64 elements using move-assignment instead of `swap`.
Arthur O'Dwyer6266d872021-12-29 14:11:46 -050065
Mark de Weverc0574b52022-06-02 08:02:19 +020066- Libc++ now supports a variety of assertions that can be turned on to help catch
67 undefined behavior in user code. This new support is now separate from the old
68 (and incomplete) Debug Mode. Vendors can select whether the library they ship
69 should include assertions or not by default. For details, see
70 :ref:`the documentation <assertions-mode>` about this new feature.
Louis Dionne6e8eb552022-03-03 17:37:03 -050071
Louis Dionne14918c82021-10-18 13:58:31 -040072API Changes
73-----------
Mark de Wever494905b2021-06-09 20:26:34 +020074
Louis Dionne15b1cdf2022-02-07 14:52:17 -050075- The ``_LIBCPP_ABI_UNSTABLE`` macro has been removed in favour of setting
76 ``_LIBCPP_ABI_VERSION=2``. This should not have any impact on users because
77 they were not supposed to set ``_LIBCPP_ABI_UNSTABLE`` manually, however we
78 still feel that it is worth mentioning in the release notes in case some users
79 had been doing it.
Louis Dionne12507ef2022-03-07 09:00:17 -050080
Joe Loser12572992022-02-11 18:45:44 -050081- The header ``<experimental/filesystem>`` has been removed. Instead, use
82 ``<filesystem>`` header. The associated macro
83 ``_LIBCPP_DEPRECATED_EXPERIMENTAL_FILESYSTEM`` has also been removed.
Louis Dionne15b1cdf2022-02-07 14:52:17 -050084
Nikolas Klauser16d31952022-04-23 10:07:24 +020085- Some libc++ headers no longer transitively include all of:
86 - ``<algorithm>``
87 - ``<chrono>``
88 - ``<functional>``
89 - ``<utility>``
90
91 If, after updating libc++, you see compiler errors related to missing declarations
92 in namespace ``std``, it might be because one of your source files now needs to
93 include one or more of the headers listed above.
Nikolas Klauser93205712022-02-24 00:09:18 +010094
Arthur O'Dwyer681dcb82021-12-01 19:55:26 -050095- The integer distributions ``binomial_distribution``, ``discrete_distribution``,
96 ``geometric_distribution``, ``negative_binomial_distribution``, ``poisson_distribution``,
97 and ``uniform_int_distribution`` now conform to the Standard by rejecting
98 template parameter types other than ``short``, ``int``, ``long``, ``long long``,
99 (as an extension) ``__int128_t``, and the unsigned versions thereof.
100 In particular, ``uniform_int_distribution<int8_t>`` is no longer supported.
101
Arthur O'Dwyer53972c52022-03-04 18:24:18 -0500102- The C++14 function ``std::quoted(const char*)`` is no longer supported in
103 C++03 or C++11 modes.
104
Louis Dionne6e8eb552022-03-03 17:37:03 -0500105- Setting a custom debug handler with ``std::__libcpp_debug_function`` is not
106 supported anymore. Please migrate to using the new support for
107 :ref:`assertions <assertions-mode>` instead.
108
Nikolas Klauser86dff6d2022-04-22 20:56:58 +0200109- ``vector<bool>::const_reference``, ``vector<bool>::const_iterator::reference``
110 and ``bitset::const_reference`` are now aliases for `bool` in the unstable ABI.
111
Joe Loser8fcb1d92021-10-28 15:38:02 -0400112ABI Changes
113-----------
114
Louis Dionne9bb7cf42021-09-08 12:57:58 -0400115- The ``_LIBCPP_ABI_USE_CXX03_NULLPTR_EMULATION`` macro controlling whether we use an
116 emulation for ``std::nullptr_t`` in C++03 mode has been removed. After this change,
117 ``_LIBCPP_ABI_USE_CXX03_NULLPTR_EMULATION`` will not be honoured anymore and there
118 will be no way to opt back into the C++03 emulation of ``std::nullptr_t``.
119
Brad Smith20c76062022-05-07 00:57:41 -0400120- On FreeBSD, NetBSD, DragonFlyBSD and Solaris, ``std::random_device`` is now implemented on
121 top of ``arc4random()`` instead of reading from ``/dev/urandom``. Any implementation-defined
Brad Smithca9a5262022-04-24 21:45:49 -0400122 token used when constructing a ``std::random_device`` will now be ignored instead of
123 interpreted as a file to read entropy from.
124
Louis Dionne12a2e572022-05-05 12:24:43 -0400125- ``std::valarray``'s unary operators ``!``, ``+``, ``~`` and ``-`` now return an expression
126 object instead of a ``valarray``. This was done to fix an issue where any expression involving
127 other ``valarray`` operators and one of these unary operators would end up with a dangling
128 reference. This is a potential ABI break for code that exposes ``std::valarray`` on an ABI
129 boundary, specifically if the return type of an ABI-boundary function is ``auto``-deduced
130 from an expression involving unary operators on ``valarray``. If you are concerned by this,
131 you can audit whether your executable or library exports any function that returns a
132 ``valarray``, and if so ensure that any such function uses ``std::valarray`` directly
133 as a return type instead of relying on the type of ``valarray``-expressions, which is
134 not guaranteed by the Standard anyway.
135
Louis Dionne14918c82021-10-18 13:58:31 -0400136Build System Changes
137--------------------
Louis Dionne6e1a6532022-02-08 11:38:29 -0500138
139- Support for standalone builds have been entirely removed from libc++, libc++abi and
140 libunwind. Please use :ref:`these instructions <build instructions>` for building
141 libc++, libc++abi and/or libunwind.
Louis Dionnedd0baa62021-10-12 15:59:08 -0400142
143- The ``{LIBCXX,LIBCXXABI,LIBUNWIND}_TARGET_TRIPLE``, ``{LIBCXX,LIBCXXABI,LIBUNWIND}_SYSROOT`` and
144 ``{LIBCXX,LIBCXXABI,LIBUNWIND}_GCC_TOOLCHAIN`` CMake variables have been removed. Instead, please
145 use the ``CMAKE_CXX_COMPILER_TARGET``, ``CMAKE_SYSROOT`` and ``CMAKE_CXX_COMPILER_EXTERNAL_TOOLCHAIN``
146 variables provided by CMake.
Martin Storsjö2352e812022-03-07 13:32:52 -0500147
148- When building for Windows, vendors who want to avoid dll-exporting symbols from the static libc++abi
149 library should set ``LIBCXXABI_HERMETIC_STATIC_LIBRARY=ON`` when configuring CMake. The current
150 behavior, which tries to guess the correct dll-export semantics based on whether we're building
151 the libc++ shared library, will be removed in LLVM 16.
Louis Dionne3ce7af42022-03-15 11:17:08 -0400152
153- Previously, the C++ ABI library headers would be installed inside ``<prefix>/include/c++/v1``
154 alongside the libc++ headers as part of building libc++. This is not the case anymore -- the
155 ABI library is expected to install its headers where it wants them as part of its own build.
156 Note that no action is required for most users, who build libc++ against libc++abi, since
157 libc++abi already installs its headers in the right location. However, vendors building
158 libc++ against alternate ABI libraries should make sure that their ABI library installs
159 its own headers.
Louis Dionne5a30e352022-03-14 14:23:38 -0400160
161- The legacy testing configuration is now deprecated and will be removed in the next release. For
Louis Dionnea05a01a2022-05-26 11:12:45 -0400162 most users, this should not have any impact. However, if you are testing libc++, libc++abi or
163 libunwind in a configuration or on a platform that used to be supported by the legacy testing
164 configuration and isn't supported by one of the configurations in ``libcxx/test/configs``,
165 ``libcxxabi/test/configs`` or ``libunwind/test/configs``, please move to one of those
166 configurations or define your own.