1=========================================
2Libc++ 15.0.0 (In-Progress) Release Notes
3=========================================
4
5.. contents::
6   :local:
7   :depth: 2
8
9Written by the `Libc++ Team <https://libcxx.llvm.org>`_
10
11.. warning::
12
13   These are in-progress notes for the upcoming libc++ 15 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 libc++ C++ Standard Library,
21part of the LLVM Compiler Infrastructure, release 15.0.0. Here we describe the
22status 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
24documentation <https://llvm.org/docs/ReleaseNotes.html>`_. All LLVM releases may
25be downloaded from the `LLVM releases web site <https://llvm.org/releases/>`_.
26
27For more information about libc++, please see the `Libc++ Web Site
28<https://libcxx.llvm.org>`_ or the `LLVM Web Site <https://llvm.org>`_.
29
30Note that if you are reading this file from a Git checkout or the
31main Libc++ web page, this document applies to the *next* release, not
32the current one. To see the release notes for a specific release, please
33see the `releases page <https://llvm.org/releases/>`_.
34
35What's New in Libc++ 15.0.0?
36============================
37
38New Features
39------------
40
41- Implemented P0627R6 (Function to mark unreachable code)
42
43- Implemented P1165R1 (Make stateful allocator propagation more consistent for ``operator+(basic_string)``)
44
45- Implemented P0674R1 (Support arrays in ``make_shared`` and ``allocate_shared``)
46
47- Implemented P0980R1 (Making ``std::string`` constexpr)
48
49- 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
62- `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`.
65
66- 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.
71
72- The implementation of the function ``std::to_chars`` for integral types has
73  moved from the dylib to the header. This means the function no longer has a
74  minimum deployment target.
75
76- Implemented P2216R3 (std::format improvements). The format functions
77  (``std::format``, ``std::format_to``, ``std::format_to_n``, and
78  ``std::formatted_size``) now validate the format string at compile time.
79  When the format string is invalid this will make the code ill-formed instead
80  of throwing an exception at run-time.  (This does not affect the ``v``
81  functions.)
82
83
84API Changes
85-----------
86
87- The ``_LIBCPP_ABI_UNSTABLE`` macro has been removed in favour of setting
88  ``_LIBCPP_ABI_VERSION=2``. This should not have any impact on users because
89  they were not supposed to set ``_LIBCPP_ABI_UNSTABLE`` manually, however we
90  still feel that it is worth mentioning in the release notes in case some users
91  had been doing it.
92
93- The header ``<experimental/filesystem>`` has been removed. Instead, use
94  ``<filesystem>`` header. The associated macro
95  ``_LIBCPP_DEPRECATED_EXPERIMENTAL_FILESYSTEM`` has also been removed.
96
97- Some libc++ headers no longer transitively include all of:
98    - ``<algorithm>``
99    - ``<chrono>``
100    - ``<exception>``
101    - ``<functional>``
102    - ``<new>``
103    - ``<typeinfo>``
104    - ``<utility>``
105
106  If, after updating libc++, you see compiler errors related to missing declarations
107  in namespace ``std``, it might be because one of your source files now needs to
108  include one or more of the headers listed above.
109
110- The integer distributions ``binomial_distribution``, ``discrete_distribution``,
111  ``geometric_distribution``, ``negative_binomial_distribution``, ``poisson_distribution``,
112  and ``uniform_int_distribution`` now conform to the Standard by rejecting
113  template parameter types other than ``short``, ``int``, ``long``, ``long long``,
114  (as an extension) ``__int128_t``, and the unsigned versions thereof.
115  In particular, ``uniform_int_distribution<int8_t>`` is no longer supported.
116
117- The C++14 function ``std::quoted(const char*)`` is no longer supported in
118  C++03 or C++11 modes.
119
120- Setting a custom debug handler with ``std::__libcpp_debug_function`` is not
121  supported anymore. Please migrate to using the new support for
122  :ref:`assertions <assertions-mode>` instead.
123
124- ``vector<bool>::const_reference``, ``vector<bool>::const_iterator::reference``
125  and ``bitset::const_reference`` are now aliases for `bool` in the unstable ABI.
126
127- The ``_LIBCPP_DEBUG`` macro is not supported anymore. It will be honoured until
128  LLVM 16, and then it will be an error to define that macro. To enable basic
129  assertions (previously ``_LIBCPP_DEBUG=0``), please use ``_LIBCPP_ENABLE_ASSERTIONS=1``.
130  To enable the debug mode (previously ``_LIBCPP_DEBUG=1|2``), please ensure that
131  the library has been built with support for the debug mode, and it will be
132  enabled automatically (no need to define ``_LIBCPP_DEBUG``).
133
134- The ``_LIBCPP_DISABLE_EXTERN_TEMPLATE`` macro is not honored anymore when defined by
135  users of libc++. Instead, users not wishing to take a dependency on libc++ should link
136  against the static version of libc++, which will result in no dependency being
137  taken against the shared library.
138
139ABI Changes
140-----------
141
142- The ``_LIBCPP_ABI_USE_CXX03_NULLPTR_EMULATION`` macro controlling whether we use an
143  emulation for ``std::nullptr_t`` in C++03 mode has been removed. After this change,
144  ``_LIBCPP_ABI_USE_CXX03_NULLPTR_EMULATION`` will not be honoured anymore and there
145  will be no way to opt back into the C++03 emulation of ``std::nullptr_t``.
146
147- On FreeBSD, NetBSD, DragonFlyBSD and Solaris, ``std::random_device`` is now implemented on
148  top of ``arc4random()`` instead of reading from ``/dev/urandom``. Any implementation-defined
149  token used when constructing a ``std::random_device`` will now be ignored instead of
150  interpreted as a file to read entropy from.
151
152- ``std::valarray``'s unary operators ``!``, ``+``, ``~`` and ``-`` now return an expression
153  object instead of a ``valarray``. This was done to fix an issue where any expression involving
154  other ``valarray`` operators and one of these unary operators would end up with a dangling
155  reference. This is a potential ABI break for code that exposes ``std::valarray`` on an ABI
156  boundary, specifically if the return type of an ABI-boundary function is ``auto``-deduced
157  from an expression involving unary operators on ``valarray``. If you are concerned by this,
158  you can audit whether your executable or library exports any function that returns a
159  ``valarray``, and if so ensure that any such function uses ``std::valarray`` directly
160  as a return type instead of relying on the type of ``valarray``-expressions, which is
161  not guaranteed by the Standard anyway.
162
163Build System Changes
164--------------------
165
166- Support for standalone builds have been entirely removed from libc++, libc++abi and
167  libunwind. Please use :ref:`these instructions <build instructions>` for building
168  libc++, libc++abi and/or libunwind.
169
170- The ``{LIBCXX,LIBCXXABI,LIBUNWIND}_TARGET_TRIPLE``, ``{LIBCXX,LIBCXXABI,LIBUNWIND}_SYSROOT`` and
171  ``{LIBCXX,LIBCXXABI,LIBUNWIND}_GCC_TOOLCHAIN`` CMake variables have been removed. Instead, please
172  use the ``CMAKE_CXX_COMPILER_TARGET``, ``CMAKE_SYSROOT`` and ``CMAKE_CXX_COMPILER_EXTERNAL_TOOLCHAIN``
173  variables provided by CMake.
174
175- When building for Windows, vendors who want to avoid dll-exporting symbols from the static libc++abi
176  library should set ``LIBCXXABI_HERMETIC_STATIC_LIBRARY=ON`` when configuring CMake. The current
177  behavior, which tries to guess the correct dll-export semantics based on whether we're building
178  the libc++ shared library, will be removed in LLVM 16.
179
180- Previously, the C++ ABI library headers would be installed inside ``<prefix>/include/c++/v1``
181  alongside the libc++ headers as part of building libc++. This is not the case anymore -- the
182  ABI library is expected to install its headers where it wants them as part of its own build.
183  Note that no action is required for most users, who build libc++ against libc++abi, since
184  libc++abi already installs its headers in the right location. However, vendors building
185  libc++ against alternate ABI libraries should make sure that their ABI library installs
186  its own headers.
187
188- The legacy testing configuration is now deprecated and will be removed in the next release. For
189  most users, this should not have any impact. However, if you are testing libc++, libc++abi or
190  libunwind in a configuration or on a platform that used to be supported by the legacy testing
191  configuration and isn't supported by one of the configurations in ``libcxx/test/configs``,
192  ``libcxxabi/test/configs`` or ``libunwind/test/configs``, please move to one of those
193  configurations or define your own.
194
195- The ``LIBCXX_ENABLE_DEBUG_MODE_SUPPORT`` CMake configuration is not supported anymore. If you
196  were disabling support for the debug mode with that flag, please use ``LIBCXX_ENABLE_BACKWARDS_COMPATIBILITY_DEBUG_MODE_SYMBOLS=OFF``
197  instead.
198
199- MinGW DLL builds of libc++ no longer use dllimport in their headers, which
200  means that the same set of installed headers works for both DLL and static
201  linkage. This means that distributors finally can build both library
202  versions with a single CMake invocation.
203