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