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
38The main focus of the libc++ team has been to implement new C++20 and C++23
39features.
40
41The C++20 ``format`` library is feature complete, but not all Standard LWG
42issues have been addressed. Since it is expected that at least one of these
43issues will cause an ABI break the ``format`` library is considered
44experimental.
45
46The C++20 ``ranges`` library has progressed a lot since the last release and is
47almost complete. The ``ranges`` library is considered experimental.
48
49
50Implemented Papers
51------------------
52
53- P0627R6 – Function to mark unreachable code
54- P1165R1 – Make stateful allocator propagation more consistent for ``operator+(basic_string)``
55- P0674R1 – Support arrays in ``make_shared`` and ``allocate_shared``
56- P0980R1 – Making ``std::string`` constexpr
57- P2216R3 – ``std::format`` improvements
58- P0174R2 – Deprecating Vestigial Library Parts in C++17
59- N4190 – Removing ``auto_ptr``, ``random_shuffle()``, And Old ``<functional>`` Stuff
60- P0154R1 – Hardware inference size
61- P0618R0 – Deprecating ``<codecvt>``
62- P2418R2 – Add support for ``std::generator``-like types to ``std::format``
63- LWG3659 – Consider ``ATOMIC_FLAG_INIT`` undeprecation
64- P1423R3 – ``char8_t`` backward compatibility remediation
65
66- Marked the following papers as "Complete" (note that some of those might have
67  been implemented in a previous release but not marked as such):
68
69    - P1207R4 – Movability of Single-pass Iterators
70    - P1474R1 – Helpful pointers for ``ContiguousIterator``
71    - P1522R1 – Iterator Difference Type and Integer Overflow
72    - P1523R1 – Views and Size Types
73    - P1456R1 – Move-only views
74    - P1870R1 – ``forwarding-range`` is too subtle
75    - P1878R1 – Constraining Readable Types
76    - P1970R2 – Consistency for ``size()`` functions: Add ``ranges::ssize``
77    - P1983R0 – Wording for GB301, US296, US292, US291, and US283
78
79New Features
80------------
81
82- `pop_heap` now uses an algorithm known as "bottom-up heapsort" or
83  "heapsort with bounce" to reduce the number of comparisons, and rearranges
84  elements using move-assignment instead of `swap`.
85
86- Libc++ now supports a variety of assertions that can be turned on to help catch
87  undefined behavior in user code. This new support is now separate from the old
88  (and incomplete) Debug Mode. Vendors can select whether the library they ship
89  should include assertions or not by default. For details, see
90  :ref:`the documentation <assertions-mode>` about this new feature.
91
92- The implementation of the function ``std::to_chars`` for integral types using
93  base 10 has moved from the dylib to the header. This means the function no
94  longer has a minimum deployment target.
95
96- The performance for ``std::to_chars``, for integral types using base 2, 8,
97  10, or 16 has been improved.
98
99- The functions ``std::from_chars`` and ``std::to_chars`` now have 128-bit integral
100  support.
101
102- The format functions (``std::format``, ``std::format_to``, ``std::format_to_n``, and
103  ``std::formatted_size``) now validate the format string at compile time.
104  When the format string is invalid this will make the code ill-formed instead
105  of throwing an exception at run-time.  (This does not affect the ``v``
106  functions.)
107
108- All format functions in ``<format>`` allow the usage of non-copyable types as
109  argument for the formatting functions. This change causes bit fields to become
110  invalid arguments for the formatting functions.
111
112API Changes
113-----------
114
115- The ``_LIBCPP_ABI_UNSTABLE`` macro has been removed in favour of setting
116  ``_LIBCPP_ABI_VERSION=2``. This should not have any impact on users because
117  they were not supposed to set ``_LIBCPP_ABI_UNSTABLE`` manually, however we
118  still feel that it is worth mentioning in the release notes in case some users
119  had been doing it.
120
121- The header ``<experimental/filesystem>`` has been removed. Instead, use
122  ``<filesystem>`` header. The associated macro
123  ``_LIBCPP_DEPRECATED_EXPERIMENTAL_FILESYSTEM`` has been removed too.
124
125- Libc++ is getting ready to remove unnecessary transitive inclusions. This may
126  break your code in the future. To future-proof your code to these removals,
127  please compile your code with ``_LIBCPP_REMOVE_TRANSITIVE_INCLUDES`` defined
128  and fix any compilation error resulting from missing includes.
129
130- The integer distributions ``binomial_distribution``, ``discrete_distribution``,
131  ``geometric_distribution``, ``negative_binomial_distribution``, ``poisson_distribution``,
132  and ``uniform_int_distribution`` now conform to the Standard by rejecting
133  template parameter types other than ``short``, ``int``, ``long``, ``long long``,
134  (as an extension) ``__int128_t``, and the unsigned versions thereof.
135  In particular, ``uniform_int_distribution<int8_t>`` is no longer supported.
136
137- The C++14 function ``std::quoted(const char*)`` is no longer supported in
138  C++03 or C++11 modes.
139
140- Setting a custom debug handler with ``std::__libcpp_debug_function`` is not
141  supported anymore. Please migrate to using the new support for
142  :ref:`assertions <assertions-mode>` instead.
143
144- ``vector<bool>::const_reference``, ``vector<bool>::const_iterator::reference``
145  and ``bitset::const_reference`` are now aliases for `bool` in the unstable ABI.
146
147- The ``_LIBCPP_DEBUG`` macro is not supported anymore. It will be honoured until
148  LLVM 16, and then it will be an error to define that macro. To enable basic
149  assertions (previously ``_LIBCPP_DEBUG=0``), please use ``_LIBCPP_ENABLE_ASSERTIONS=1``.
150  To enable the debug mode (previously ``_LIBCPP_DEBUG=1|2``), please ensure that
151  the library has been built with support for the debug mode, and it will be
152  enabled automatically (no need to define ``_LIBCPP_DEBUG``).
153
154- The ``_LIBCPP_DISABLE_EXTERN_TEMPLATE`` macro is not honored anymore when defined by
155  users of libc++. Instead, users not wishing to take a dependency on libc++ should link
156  against the static version of libc++, which will result in no dependency being
157  taken against the shared library.
158
159- The ``_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_VOID_SPECIALIZATION`` macro has been added to allow
160  re-enabling the ``allocator<void>`` specialization. When used in conjunction with
161  ``_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS``, this ensures that the members of
162  ``allocator<void>`` removed in C++20 can be accessed.
163
164- The experimental versions of ``boyer_moore_searcher`` and ``boyer_moore_horspool_searcher``
165  will be removed in LLVM 17. You can disable the deprecation warnings by defining
166  ``_LIBCPP_NO_EXPERIMENTAL_DEPRECATION_WARNING_SEARCHERS``.
167
168- ``std::function`` has been removed in C++03. If you are using it, please remove usages
169  or upgrade to C++11 or later. It is possible to re-enable ``std::function`` in C++03 by defining
170  ``_LIBCPP_ENABLE_CXX03_FUNCTION``. This option will be removed in LLVM 16.
171
172- ``unary_function`` and ``binary_function`` are no longer available in C++17 and C++20.
173  They can be re-enabled by defining ``_LIBCPP_ENABLE_CXX17_REMOVED_UNARY_BINARY_FUNCTION``.
174  They are also marked as ``[[deprecated]]`` in C++11 and later. To disable deprecation warnings
175  you have to define ``_LIBCPP_DISABLE_DEPRECATION_WARNINGS``. Note that this disables
176  all deprecation warnings.
177
178- The contents of ``<codecvt>``, ``wstring_convert`` and ``wbuffer_convert`` have been marked as deprecated.
179  To disable deprecation warnings you have to define ``_LIBCPP_DISABLE_DEPRECATION_WARNINGS``. Note that this
180  disables all deprecation warnings.
181
182- ``boyer_moore_searcher`` and ``boyer_moore_horspool_searcher`` have been implemented.
183
184ABI Changes
185-----------
186
187- The ``_LIBCPP_ABI_USE_CXX03_NULLPTR_EMULATION`` macro controlling whether we use an
188  emulation for ``std::nullptr_t`` in C++03 mode has been removed. After this change,
189  ``_LIBCPP_ABI_USE_CXX03_NULLPTR_EMULATION`` will not be honoured anymore and there
190  will be no way to opt back into the C++03 emulation of ``std::nullptr_t``.
191
192- On FreeBSD, NetBSD, DragonFlyBSD and Solaris, ``std::random_device`` is now implemented on
193  top of ``arc4random()`` instead of reading from ``/dev/urandom``. Any implementation-defined
194  token used when constructing a ``std::random_device`` will now be ignored instead of
195  interpreted as a file to read entropy from.
196
197- ``std::valarray``'s unary operators ``!``, ``+``, ``~`` and ``-`` now return an expression
198  object instead of a ``valarray``. This was done to fix an issue where any expression involving
199  other ``valarray`` operators and one of these unary operators would end up with a dangling
200  reference. This is a potential ABI break for code that exposes ``std::valarray`` on an ABI
201  boundary, specifically if the return type of an ABI-boundary function is ``auto``-deduced
202  from an expression involving unary operators on ``valarray``. If you are concerned by this,
203  you can audit whether your executable or library exports any function that returns a
204  ``valarray``, and if so ensure that any such function uses ``std::valarray`` directly
205  as a return type instead of relying on the type of ``valarray``-expressions, which is
206  not guaranteed by the Standard anyway.
207
208- By default, the legacy debug mode symbols are not provided with the library anymore. If
209  you are a vendor and need to re-enable them, please use the ``LIBCXX_ENABLE_BACKWARDS_COMPATIBILITY_DEBUG_MODE_SYMBOLS``
210  CMake flag, and contact the libc++ developers as this will be removed in LLVM 16.
211  Furthermore, please note that ``LIBCXX_ENABLE_DEBUG_MODE_SUPPORT`` is not honored anymore.
212
213Build System Changes
214--------------------
215
216- Support for standalone builds have been entirely removed from libc++, libc++abi and
217  libunwind. Please use :ref:`these instructions <build instructions>` for building
218  libc++, libc++abi and/or libunwind.
219
220- The ``{LIBCXX,LIBCXXABI,LIBUNWIND}_TARGET_TRIPLE``, ``{LIBCXX,LIBCXXABI,LIBUNWIND}_SYSROOT`` and
221  ``{LIBCXX,LIBCXXABI,LIBUNWIND}_GCC_TOOLCHAIN`` CMake variables have been removed. Instead, please
222  use the ``CMAKE_CXX_COMPILER_TARGET``, ``CMAKE_SYSROOT`` and ``CMAKE_CXX_COMPILER_EXTERNAL_TOOLCHAIN``
223  variables provided by CMake.
224
225- When building for Windows, vendors who want to avoid dll-exporting symbols from the static libc++abi
226  library should set ``LIBCXXABI_HERMETIC_STATIC_LIBRARY=ON`` when configuring CMake. The current
227  behavior, which tries to guess the correct dll-export semantics based on whether we're building
228  the libc++ shared library, will be removed in LLVM 16.
229
230- Previously, the C++ ABI library headers would be installed inside ``<prefix>/include/c++/v1``
231  alongside the libc++ headers as part of building libc++. This is not the case anymore -- the
232  ABI library is expected to install its headers where it wants them as part of its own build.
233  Note that no action is required for most users, who build libc++ against libc++abi, since
234  libc++abi already installs its headers in the right location. However, vendors building
235  libc++ against alternate ABI libraries should make sure that their ABI library installs
236  its own headers.
237
238- The legacy testing configuration is now deprecated and will be removed in LLVM 16. For
239  most users, this should not have any impact. However, if you are testing libc++, libc++abi, or
240  libunwind in a configuration or on a platform that used to be supported by the legacy testing
241  configuration and isn't supported by one of the configurations in ``libcxx/test/configs``,
242  ``libcxxabi/test/configs``, or ``libunwind/test/configs``, please move to one of those
243  configurations or define your own.
244
245- MinGW DLL builds of libc++ no longer use dllimport in their headers, which
246  means that the same set of installed headers works for both DLL and static
247  linkage. This means that distributors finally can build both library
248  versions with a single CMake invocation.
249
250- The ``LIBCXX_HIDE_FROM_ABI_PER_TU_BY_DEFAULT`` configuration option has been removed. Indeed,
251  the risk of ODR violations from mixing different versions of libc++ in the same program has
252  been mitigated with a different technique that is simpler and does not have the drawbacks of
253  using internal linkage.
254