1=========================================== 2Libc++ 18.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++ 18.0.0 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 18.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++ 18.0.0? 36============================== 37 38The main focus of the libc++ team has been to implement new C++20, C++23, 39and C++26 features. 40 41New hardened modes for the library have been added, replacing the legacy debug mode that was 42removed in the LLVM 17 release. Unlike the legacy debug mode, some of these hardening modes are 43also intended to be used in production. See :ref:`hardening-modes` for more details. 44 45Work on the ranges support has progressed. See 46:ref:`ranges-status` for the current status. 47 48Work on the experimental C++23 module support has progressed. The ``std.compat`` 49module is available and the feature is retroactively available in C++20. See 50:ref:`ModulesInLibcxx` for more information. 51 52Work on the experimental C++17 Parallel STL has progressed. See 53:ref:`pstl-status` for the current status. 54 55Work on the experimental C++17 SIMD support has progressed. See 56:ref:`parallelism-status` for the current status. 57 58 59Implemented 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 83 84 85Improvements and New Features 86----------------------------- 87 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. 91 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. 94 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. 103 104- The ``_LIBCPP_ENABLE_CXX26_REMOVED_CODECVT`` macro has been added to make 105 the declarations in ``<codecvt>`` available. 106 107- The ``_LIBCPP_ENABLE_CXX26_REMOVED_STRING_RESERVE`` macro has been added to make 108 the function ``std::basic_string<...>::reserve()`` available. 109 110- The ``_LIBCPP_ENABLE_CXX26_REMOVED_ALLOCATOR_MEMBERS`` macro has been added to make 111 the function ``allocator<T>::is_always_equal`` available. 112 113- The ``_LIBCPP_ENABLE_CXX20_REMOVED_SHARED_PTR_UNIQUE`` macro has been added to make 114 the function ``std::shared_ptr<...>::unique()`` available. 115 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). 119 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``. 126 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. 130 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. 134 135Deprecations and Removals 136------------------------- 137 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. 142 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. 145 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. 151 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. 157 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. 160 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. 164 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. 170 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. 176 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. 182 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. 186 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. 189 190 191Upcoming Deprecations and Removals 192---------------------------------- 193 194- The ability to override ``__libcpp_verbose_abort`` will be removed in an upcoming release. 195 196LLVM 19 197~~~~~~~ 198 199- The ``LIBCXX_EXECUTOR`` CMake variable has been deprecated. LLVM 19 will 200 completely remove support for the ``*_EXECUTOR`` variables. 201 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. 207 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. 215 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. 218 219- The ``_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS`` macro has been deprecated in LLVM 18 and will be removed 220 entirely in LLVM 19. 221 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. 225 226- The macro ``_LIBCPP_INLINE_VISIBILITY`` has been deprecated in LLVM 18 and 227 will be removed entirely in LLVM 19. 228 229- The macro ``_VSTD`` has been deprecated in LLVM 18 and will be removed 230 entirely in LLVM 19. 231 232LLVM 20 233~~~~~~~ 234 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. 237 238 239ABI Affecting Changes 240--------------------- 241 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. 247 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. 252 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. 259 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``. 264 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. 267 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. 275 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. 279 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``). 285 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. 297 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: 301 302 - library version (This was part of the ABI tag prior to LLVM 18.) 303 - exceptions vs no-exceptions 304 - hardening mode 305 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. 309 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: 314 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): 318 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 323 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>`_. 330 331 332Build System Changes 333-------------------- 334 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. 339 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. 346