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