| blob | 4f7b9b362e5e66a33b1c73b577161e7bcd902521 |
1 ===========================================
2 Libc++ 18.0.0 (In-Progress) Release Notes
3 ===========================================
5 .. contents::
6 :local:
7 :depth: 2
9 Written by the `Libc++ Team <https://libcxx.llvm.org>`_
11 .. warning::
13 These are in-progress notes for the upcoming libc++ 18.0.0 release.
14 Release notes for previous releases can be found on
15 `the Download Page <https://releases.llvm.org/download.html>`_.
17 Introduction
18 ============
20 This document contains the release notes for the libc++ C++ Standard Library,
21 part of the LLVM Compiler Infrastructure, release 18.0.0. Here we describe the
22 status of libc++ in some detail, including major improvements from the previous
23 release and new feature work. For the general LLVM release notes, see `the LLVM
24 documentation <https://llvm.org/docs/ReleaseNotes.html>`_. All LLVM releases may
25 be downloaded from the `LLVM releases web site <https://llvm.org/releases/>`_.
27 For more information about libc++, please see the `Libc++ Web Site
28 <https://libcxx.llvm.org>`_ or the `LLVM Web Site <https://llvm.org>`_.
30 Note that if you are reading this file from a Git checkout or the
31 main Libc++ web page, this document applies to the *next* release, not
32 the current one. To see the release notes for a specific release, please
33 see the `releases page <https://llvm.org/releases/>`_.
35 What's New in Libc++ 18.0.0?
36 ==============================
38 The main focus of the libc++ team has been to implement new C++20, C++23,
39 and C++26 features.
41 New hardened modes for the library have been added, replacing the legacy debug mode that was
42 removed in the LLVM 17 release. Unlike the legacy debug mode, some of these hardening modes are
43 also intended to be used in production. See :ref:`hardening` for more details.
45 Work on the ranges support has progressed. See
46 :ref:`ranges-status` for the current status.
48 Work on the experimental C++23 module support has progressed. The ``std.compat``
49 module is available and the feature is retroactively available in C++20. See
50 :ref:`ModulesInLibcxx` for more information.
52 Work on the experimental C++17 Parallel STL has progressed. See
53 :ref:`pstl-status` for the current status.
55 Work on the experimental C++17 SIMD support has progressed. See
56 :ref:`parallelism-status` for the current status.
59 Implemented Papers
60 ------------------
61 - P2093R14 - Formatted output
62 - P2539R4 - Should the output of ``std::print`` to a terminal be synchronized with the underlying stream?
63 - P2497R0 - Testing for success or failure of ``<charconv>`` functions
64 - P2697R1 - Interfacing ``bitset`` with ``string_view``
65 - P2443R1 - ``views::chunk_by``
66 - P2538R1 - ADL-proof ``std::projected``
67 - P2614R2 - Deprecate ``numeric_limits::has_denorm``
68 - P0053R7 - C++ Synchronized Buffered Ostream (in the experimental library)
69 - P2467R1 - Support exclusive mode for fstreams
70 - P0020R6 - Floating Point Atomic
71 - P2905R2 - Runtime format strings
72 - P2918R2 - Runtime format strings II
73 - P2871R3 - Remove Deprecated Unicode Conversion Facets from C++26
74 - P2870R3 - Remove ``basic_string::reserve()``
75 - P2909R4 - Fix formatting of code units as integers (Dude, where’s my ``char``?)
76 - P2821R5 - ``span.at()``
77 - P0521R0 - Proposed Resolution for CA 14 (``shared_ptr`` ``use_count/unique``)
78 - P0543R3 - Saturation arithmetic
79 - P1759R6 - Native handles and file streams
80 - P2868R3 - Remove Deprecated ``std::allocator`` Typedef From C++26
81 - P2517R1 - Add a conditional ``noexcept`` specification to ``std::apply``
82 - P2447R6 - ``span`` over initializer list
85 Improvements and New Features
86 -----------------------------
88 - ``std::ranges::count`` and ``std::ranges::find`` are now optimized for
89 ``std::vector<bool>::iterator``, which can lead up to 350x performance
90 improvements.
92 - ``std::for_each`` has been optimized for segmented iterators like ``std::deque::iterator`` in C++23 and
93 later, which can lead up to 40x performance improvements.
95 - The library now provides several hardening modes under which common cases of library undefined behavior will be turned
96 into a reliable program termination. The ``fast`` hardening mode enables a set of security-critical checks with
97 minimal runtime overhead; the ``extensive`` hardening mode additionally enables relatively cheap checks that catch
98 common logic errors but aren't necessarily security-critical; and the ``debug`` hardening mode enables all available
99 checks, some of which might be very expensive. Vendors can configure which hardening mode is enabled by default with
100 the ``LIBCXX_HARDENING_MODE`` variable at CMake configuration time. Users can control which hardening mode is enabled
101 on a per translation unit basis using the ``_LIBCPP_HARDENING_MODE`` macro. See :ref:`the hardening documentation
102 <using-hardening-modes>` for more details.
104 - The ``_LIBCPP_ENABLE_CXX26_REMOVED_CODECVT`` macro has been added to make
105 the declarations in ``<codecvt>`` available.
107 - The ``_LIBCPP_ENABLE_CXX26_REMOVED_STRING_RESERVE`` macro has been added to make
108 the function ``std::basic_string<...>::reserve()`` available.
110 - The ``_LIBCPP_ENABLE_CXX26_REMOVED_ALLOCATOR_MEMBERS`` macro has been added to make
111 the function ``allocator<T>::is_always_equal`` available.
113 - The ``_LIBCPP_ENABLE_CXX20_REMOVED_SHARED_PTR_UNIQUE`` macro has been added to make
114 the function ``std::shared_ptr<...>::unique()`` available.
116 - The cmake option ``LIBCXX_ENABLE_STD_MODULES`` has been removed. The test
117 infrastructure no longer depends on a modern CMake, it works with the minimal
118 required LLVM version (3.20.0).
120 - The ``.cppm`` files of experimental standard library modules can now be
121 installed. By default, they are not installed. This can be enabled by
122 configuring CMake with ``-DLIBCXX_INSTALL_MODULES=ON``. The installation
123 directory can be configured with the CMake option
124 ``-DLIBCXX_INSTALL_MODULE_DIR=<path>``. The default location is
125 ``${PREFIX}/share/libc++/v1``.
127 - AddressSanitizer annotations have been added to ``std::basic_string``.
128 These annotations are enabled for all allocators by default.
129 It's only enabled for long strings, strings using the small buffer optimization are not annotated.
131 - The libc++ source code has been formatted with ``clang-format``. This
132 `discourse thread <https://discourse.llvm.org/t/rfc-clang-formatting-all-of-libc-once-and-for-all>`_
133 contains information how to rebase downstream patches.
135 Deprecations and Removals
136 -------------------------
138 - Availability macros which will never trigger an error have been removed. This includes anything that has been
139 introduced before macOS 10.13, iOS 12, tvOS 12 and watchOS 4. This shouldn't affect anybody, since AppleClang 15
140 doesn't support any older OSes. If you are a vendor and make use of these macros, please inform the libc++ team so we
141 can re-introduce them and consider upstreaming support for your platform.
143 - The non-conforming constructor ``std::future_error(std::error_code)`` has been removed. Please use the
144 ``std::future_error(std::future_errc)`` constructor provided in C++17 instead.
146 - `P1957 <https://wg21.link/P1957>`_ has been implemented in Clang and libc++ removed a code path that led to
147 narrowing conversions in ``std::variant`` behaving in a non-standard way. This may change how some uses of
148 ``std::variant``'s constructor behave in user code. The ``_LIBCPP_ENABLE_NARROWING_CONVERSIONS_IN_VARIANT``
149 macro is provided to restore the previous behavior, and it will be supported in the LLVM 18 release only.
150 In LLVM 19 and beyond, ``_LIBCPP_ENABLE_NARROWING_CONVERSIONS_IN_VARIANT`` will not be honored anymore.
152 - Overriding ``__libcpp_verbose_abort`` no longer has any effect on library assertions. The only supported way
153 to customize the assertion handler that gets invoked when a hardening assertion fails is now by setting the
154 ``LIBCXX_ASSERTION_HANDLER_FILE`` CMake variable and providing a custom header. See the documentation on
155 overriding the default assertion handler for details. The ability to override ``__libcpp_verbose_abort``
156 will be removed in an upcoming release in favor of the new overriding mechanism.
158 - In safe mode (which is now equivalent to the ``extensive`` hardening mode), a failed assertion will now
159 generate a trap rather than a call to verbose abort.
161 - The ``_LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED`` macro is not honored anymore in LLVM 18.
162 Please see the updated documentation about the hardening modes in libc++ and in particular on
163 overriding the default assertion handler.
165 - The headers ``<experimental/deque>``, ``<experimental/forward_list>``, ``<experimental/list>``,
166 ``<experimental/map>``, ``<experimental/memory_resource>``, ``<experimental/regex>``, ``<experimental/set>``,
167 ``<experimental/string>``, ``<experimental/unordered_map>``, ``<experimental/unordered_set>``,
168 and ``<experimental/vector>`` have been removed in LLVM 18, as all their contents will have been
169 implemented in namespace ``std`` for at least two releases.
171 - The macro ``_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS`` has been deprecated and will be removed
172 in LLVM 19. This macro used to re-enable redundant members of ``std::allocator<T>`` like ``pointer``,
173 ``reference``, ``rebind``, ``address``, ``max_size``, ``construct``, ``destroy``, and the two-argument
174 overload of ``allocate``. However, this led to the library being non-conforming due to incorrect
175 constexpr-ness.
177 - The macros ``_LIBCPP_ENABLE_CXX17_REMOVED_FEATURES`` and
178 ``_LIBCPP_ENABLE_CXX20_REMOVED_FEATURES`` have been deprecated and
179 will be removed in LLVM 19. These macros used to re-enable all features
180 that were removed in the C++17 and C++20 standards. Instead of using these
181 macros, please use the macros to re-enable individual features.
183 - The macro ``_LIBCPP_INLINE_VISIBILITY`` has been deprecated in LLVM 18 and
184 will be removed entirely in LLVM 19. The macro ``_LIBCPP_HIDE_FROM_ABI`` is
185 the drop-in replacement.
187 - The macro ``_VSTD`` has been deprecated in LLVM 18 and will be removed
188 entirely in LLVM 19. The code ``std`` is the drop-in replacement.
191 Upcoming Deprecations and Removals
192 ----------------------------------
194 - The ability to override ``__libcpp_verbose_abort`` will be removed in an upcoming release.
196 LLVM 19
197 ~~~~~~~
199 - The ``LIBCXX_EXECUTOR`` CMake variable has been deprecated. LLVM 19 will
200 completely remove support for the ``*_EXECUTOR`` variables.
202 - The ``LIBCXX_ENABLE_ASSERTIONS`` CMake variable that was used to enable the safe mode will be deprecated and setting
203 it will trigger an error; use the ``LIBCXX_HARDENING_MODE`` variable with the value ``extensive`` instead. Similarly,
204 the ``_LIBCPP_ENABLE_ASSERTIONS`` macro will be deprecated (setting it to ``1`` still enables the extensive mode in
205 the LLVM 19 release while also issuing a deprecation warning). See :ref:`the hardening documentation
206 <using-hardening-modes>` for more details.
208 - The base template for ``std::char_traits`` has been marked as deprecated and will be removed in LLVM 19. If you
209 are using ``std::char_traits`` with types other than ``char``, ``wchar_t``, ``char8_t``, ``char16_t``, ``char32_t``
210 or a custom character type for which you specialized ``std::char_traits``, your code will stop working when we
211 remove the base template. The Standard does not mandate that a base template is provided, and such a base template
212 is bound to be incorrect for some types, which could currently cause unexpected behavior while going undetected.
213 Note that the ``_LIBCPP_CHAR_TRAITS_REMOVE_BASE_SPECIALIZATION`` macro can be defined in LLVM 18 to eagerly remove
214 the specialization and prepare code bases for the unconditional removal in LLVM 19.
216 - The ``_LIBCPP_ENABLE_NARROWING_CONVERSIONS_IN_VARIANT`` macro that changed the behavior for narrowing conversions
217 in ``std::variant`` will be removed in LLVM 19.
219 - The ``_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS`` macro has been deprecated in LLVM 18 and will be removed
220 entirely in LLVM 19.
222 - The ``_LIBCPP_ENABLE_CXX17_REMOVED_FEATURES`` and
223 ``_LIBCPP_ENABLE_CXX20_REMOVED_FEATURES`` macros have been deprecated
224 in LLVM 18 and will be removed entirely in LLVM 19.
226 - The macro ``_LIBCPP_INLINE_VISIBILITY`` has been deprecated in LLVM 18 and
227 will be removed entirely in LLVM 19.
229 - The macro ``_VSTD`` has been deprecated in LLVM 18 and will be removed
230 entirely in LLVM 19.
232 LLVM 20
233 ~~~~~~~
235 - The ``LIBCXX_ENABLE_ASSERTIONS`` CMake variable and the ``_LIBCPP_ENABLE_ASSERTIONS`` macro that were used to enable
236 the safe mode will be removed.
239 ABI Affecting Changes
240 ---------------------
242 - When the shared/static library is built with ``-fno-exceptions``, the behavior of ``operator new`` was changed
243 to make it standards-conforming. In LLVM 17 and before, the throwing versions of ``operator new`` would return
244 ``nullptr`` upon failure to allocate, when the shared/static library was built with exceptions disabled. This
245 was non-conforming, since the throwing versions of ``operator new`` are never expected to return ``nullptr``, and
246 this non-conformance could actually lead to miscompiles in subtle cases.
248 Starting in LLVM 18, the throwing versions of ``operator new`` will abort the program when they fail to allocate
249 if the shared/static library has been built with ``-fno-exceptions``. This is consistent with the behavior of all
250 other potentially-throwing functions in the library, which abort the program instead of throwing when ``-fno-exceptions``
251 is used.
253 Furthermore, when the shared/static library is built with ``-fno-exceptions``, users who override the throwing
254 version of ``operator new`` will now need to also override the ``std::nothrow_t`` version of ``operator new`` if
255 they want to use it. Indeed, this is because there is no way to implement a conforming ``operator new(nothrow)``
256 from a conforming potentially-throwing ``operator new`` when compiled with ``-fno-exceptions``. In that case, using
257 ``operator new(nothrow)`` without overriding it explicitly but after overriding the throwing ``operator new`` will
258 result in an error.
260 Note that this change only impacts vendors/users that build the shared/static library themselves and pass
261 ``-DLIBCXX_ENABLE_EXCEPTIONS=OFF``, which is not the default configuration. If you are using the default
262 configuration of the library, the libc++ shared/static library will be built with exceptions enabled, and
263 there is no change between LLVM 17 and LLVM 18, even for users who build their own code using ``-fno-exceptions``.
265 - The symbol of a non-visible function part of ``std::system_error`` was removed.
266 This is not a breaking change as the private function ``__init`` was never referenced internally outside of the dylib.
268 - This release of libc++ added missing visibility annotations on some types in the library. Users compiling with
269 ``-fvisbility=hidden`` may notice that additional type infos from libc++ are being exported from their ABI. This is
270 the correct behavior in almost all cases since exporting the RTTI is required for these types to work properly with
271 ``dynamic_cast``, exceptions and other mechanisms across binaries. However, if you intend to use libc++ purely as an
272 internal implementation detail (i.e. you use libc++ as a static archive and never export libc++ symbols from your ABI)
273 and you notice changes to your exported symbols list, then this means that you were not properly preventing libc++
274 symbols from being part of your ABI.
276 - The name mangling for instantiations of ``std::projected`` has changed in order to implement P2538R1. This technically
277 results in an ABI break, however in practice we expect uses of ``std::projected`` in ABI-sensitive places to be
278 extremely rare. Any error resulting from this change should result in a link-time error.
280 - The internal alignment requirements for heap allocations inside ``std::string`` has decreased from 16 to 8. This
281 saves memory since string requests fewer additional bytes than it did previously. However, this also changes the
282 return value of ``std::string::max_size`` and can cause code compiled against older libc++ versions but linked at
283 runtime to a new version to throw a different exception when attempting allocations that are too large
284 (``std::bad_alloc`` vs ``std::length_error``).
286 - The layout of some range adaptors that use the ``movable-box`` exposition-only type as an implementation
287 detail has changed in order to fix a `bug <https://github.com/llvm/llvm-project/issues/70506>`_ which could result in
288 overwriting user data following the ``movable-box``.
289 This bug was caused by incorrect usage of the ``[[no_unique_address]]`` attribute inside the implementation of ``movable-box``.
290 This fix affects the layout of the following views: ``take_while_view``, ``filter_view``, ``single_view``, ``drop_while_view``,
291 ``repeat_view``, ``transform_view``, ``chunk_by_view``. In order to avoid silent breakage as a result of this fix, an ABI tag has been added to
292 these views such that their mangled name will be different starting in this version of libc++.
293 As a result, attempting to call a function that expects one of these views will fail to link until the code has been rebuilt
294 against a matching version of libc++. In practice, we believe it is unusual for these views to appear at ABI boundaries so this
295 should not be a major problem for most users. However it is probably worth auditing ranges-heavy code for ABI boundaries that
296 would contain these views, or for types that contain these views as members and which are passed across ABI boundaries.
298 - Some properties of libc++ may cause ODR-violations when mixing multiple libc++
299 instances. To avoid these, often benign, ODR-violations the ODR-affecting
300 properties are now part of the ABI tag. The ODR-affecting properties are:
302 - library version (This was part of the ABI tag prior to LLVM 18.)
303 - exceptions vs no-exceptions
304 - hardening mode
306 This should not be ABI-affecting except that libc++ will be more robust
307 against different configurations of it being used in different translation
308 units.
310 - The amount of padding bytes available for use at the end of certain ``std::expected`` instantiations has changed in this
311 release. This is an ABI break for any code that held a ``std::expected`` member with ``[[no_unique_address]]`` in an
312 ABI-facing type. In those cases, the layout of the enclosing type will change, breaking the ABI. However, the
313 ``std::expected<T, E>`` member requires a few characteristics in order to be affected by this change:
315 - A type equivalent to ``union {T ; E}`` needs to have more than one byte of padding available.
316 - The ``std::expected<T, E>`` member must have been in a situation where its padding bytes were previously reused by
317 another object, which can happen in a few cases (this is probably not exhaustive):
319 - It is a member with ``[[no_unique_address]]`` applied to it, and it is followed by another data member, or
320 - It is a member with ``[[no_unique_address]]`` applied to it, and it is the last member of the user-defined type,
321 and that user-defined type is used in ways that its padding bytes can be reused, or
322 - It is inherited from
324 We expect that this will not be a very frequent occurrence. However, there is unfortunately no technique we can use
325 in the library to catch such misuse. Indeed, even applying an ABI tag to ``std::expected`` would not help since ABI
326 tags are not propagated to containing types. As a result, if you notice very difficult to explain bugs around the
327 usage of a ``std::expected``, you should consider checking whether you are hitting this ABI break. This change was
328 done to fix `#70494 <https://github.com/llvm/llvm-project/issues/70494>`_ and the vendor communication is handled
329 in `#70820 <https://github.com/llvm/llvm-project/issues/70820>`_.
332 Build System Changes
333 --------------------
335 - The ``LIBCXX_EXECUTOR`` CMake variable has been deprecated. If you are relying on this, the new replacement is
336 passing ``-Dexecutor=...`` to ``llvm-lit``. Alternatively, this flag can be made persistent in the generated test
337 configuration file by passing ``-DLIBCXX_TEST_PARAMS=executor=...``. This also applies to the ``LIBUWIND_EXECTOR``
338 and ``LIBCXXABI_EXECUTOR`` CMake variables. LLVM 19 will completely remove support for the ``*_EXECUTOR`` variables.
340 - ``LIBCXXABI_USE_LLVM_UNWINDER`` and ``COMPILER_RT_USE_LLVM_UNWINDER`` switched defaults from ``OFF`` to ``ON``.
341 This means that by default, libc++abi and compiler-rt will link against the LLVM provided ``libunwind`` library
342 instead of the system-provided unwinding library. If you are building the LLVM runtimes with the goal of shipping
343 them so that they can interoperate with other system-provided libraries that might be using a different unwinding
344 library (such as ``libgcc_s``), you should pass ``LIBCXXABI_USE_LLVM_UNWINDER=OFF`` and ``COMPILER_RT_USE_LLVM_UNWINDER=OFF``
345 to make sure the system-provided unwinding library is used by the LLVM runtimes.