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 79Improvements and New Features 80----------------------------- 81 82- ``std::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 ``std::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- Clang now implements the ``-fexperimental-library`` flag. This flag can be used to 93 enable experimental library features such as TSes and other in-progress work like 94 ``<ranges>`` and ``<format>``. Using this flag makes it unnecessary to manually link 95 against ``libc++experimental.a`` -- just use ``-fexperimental-library`` and the 96 compiler will do what's needed to make experimental features work. However, be 97 aware that experimental features are not stable! 98 99- The implementation of the function ``std::to_chars`` for integral types using 100 base 10 has moved from the dylib to the header. This means the function no 101 longer has a minimum deployment target. 102 103- The performance for ``std::to_chars``, for integral types using base 2, 8, 104 10, or 16 has been improved. 105 106- The functions ``std::from_chars`` and ``std::to_chars`` now have 128-bit integral 107 support. 108 109- The format functions (``std::format``, ``std::format_to``, ``std::format_to_n``, and 110 ``std::formatted_size``) now validate the format string at compile time. 111 When the format string is invalid this will make the code ill-formed instead 112 of throwing an exception at run-time. (This does not affect the ``v`` 113 functions.) 114 115- All format functions in ``<format>`` allow the usage of non-copyable types as 116 argument for the formatting functions. This change causes bit fields to become 117 invalid arguments for the formatting functions. 118 119- The ``_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_VOID_SPECIALIZATION`` macro has been added to allow 120 re-enabling the ``allocator<void>`` specialization. When used in conjunction with 121 ``_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS``, this ensures that the members of 122 ``allocator<void>`` removed in C++20 can be accessed. 123 124- ``boyer_moore_searcher`` and ``boyer_moore_horspool_searcher`` have been implemented. 125 126- ``vector<bool>::const_reference``, ``vector<bool>::const_iterator::reference`` 127 and ``bitset::const_reference`` are now aliases for `bool` in the unstable ABI, 128 which improves libc++'s conformance to the Standard. 129 130Deprecations and Removals 131------------------------- 132 133- The header ``<experimental/filesystem>`` has been removed. Instead, use 134 ``<filesystem>`` header. The associated macro 135 ``_LIBCPP_DEPRECATED_EXPERIMENTAL_FILESYSTEM`` has been removed too. 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- ``std::function`` has been removed in C++03. If you are using it, please remove usages 145 or upgrade to C++11 or later. It is possible to re-enable ``std::function`` in C++03 by defining 146 ``_LIBCPP_ENABLE_CXX03_FUNCTION``. This option will be removed in LLVM 16. 147 148- ``unary_function`` and ``binary_function`` are no longer available in C++17 and C++20. 149 They can be re-enabled by defining ``_LIBCPP_ENABLE_CXX17_REMOVED_UNARY_BINARY_FUNCTION``. 150 They are also marked as ``[[deprecated]]`` in C++11 and later. To disable deprecation warnings 151 you have to define ``_LIBCPP_DISABLE_DEPRECATION_WARNINGS``. Note that this disables 152 all deprecation warnings. 153 154- The contents of ``<codecvt>``, ``wstring_convert`` and ``wbuffer_convert`` have been marked as deprecated. 155 To disable deprecation warnings you have to define ``_LIBCPP_DISABLE_DEPRECATION_WARNINGS``. Note that this 156 disables all deprecation warnings. 157 158- The ``_LIBCPP_DISABLE_EXTERN_TEMPLATE`` macro is not honored anymore when defined by 159 users of libc++. Instead, users not wishing to take a dependency on libc++ should link 160 against the static version of libc++, which will result in no dependency being 161 taken against the shared library. 162 163- The ``_LIBCPP_ABI_UNSTABLE`` macro has been removed in favour of setting 164 ``_LIBCPP_ABI_VERSION=2``. This should not have any impact on users because 165 they were not supposed to set ``_LIBCPP_ABI_UNSTABLE`` manually, however we 166 still feel that it is worth mentioning in the release notes in case some users 167 had been doing it. 168 169- The integer distributions ``binomial_distribution``, ``discrete_distribution``, 170 ``geometric_distribution``, ``negative_binomial_distribution``, ``poisson_distribution``, 171 and ``uniform_int_distribution`` now conform to the Standard by rejecting 172 template parameter types other than ``short``, ``int``, ``long``, ``long long``, 173 and the unsigned versions thereof. As an extension, ``int8_t``, ``__int128_t`` and 174 their unsigned versions are supported too. In particular, instantiating these 175 distributions with non-integer types like ``bool`` and ``char`` will not compile 176 anymore. 177 178Upcoming Deprecations and Removals 179---------------------------------- 180 181- The ``_LIBCPP_DEBUG`` macro is not supported anymore. It will be honoured until 182 LLVM 16, and then it will be an error to define that macro. To enable basic 183 assertions (previously ``_LIBCPP_DEBUG=0``), please use ``_LIBCPP_ENABLE_ASSERTIONS=1``. 184 To enable the debug mode (previously ``_LIBCPP_DEBUG=1|2``), please ensure that 185 the library has been built with support for the debug mode, and it will be 186 enabled automatically (no need to define ``_LIBCPP_DEBUG``). 187 188- The experimental versions of ``boyer_moore_searcher`` and ``boyer_moore_horspool_searcher`` 189 will be removed in LLVM 17. You can disable the deprecation warnings by defining 190 ``_LIBCPP_NO_EXPERIMENTAL_DEPRECATION_WARNING_SEARCHERS``. 191 192- The implementation of the Coroutines TS in ``std::experimental`` will be removed in LLVM 16. 193 194- Libc++ is getting ready to remove unnecessary transitive inclusions. This may 195 break your code in the future. To future-proof your code to these removals, 196 please compile your code with ``_LIBCPP_REMOVE_TRANSITIVE_INCLUDES`` defined 197 and fix any compilation error resulting from missing includes. 198 199ABI Affecting Changes 200--------------------- 201 202- The ``_LIBCPP_ABI_USE_CXX03_NULLPTR_EMULATION`` macro controlling whether we use an 203 emulation for ``std::nullptr_t`` in C++03 mode has been removed. After this change, 204 ``_LIBCPP_ABI_USE_CXX03_NULLPTR_EMULATION`` will not be honoured anymore and there 205 will be no way to opt back into the C++03 emulation of ``std::nullptr_t``. 206 207- On FreeBSD, NetBSD, DragonFlyBSD and Solaris, ``std::random_device`` is now implemented on 208 top of ``arc4random()`` instead of reading from ``/dev/urandom``. Any implementation-defined 209 token used when constructing a ``std::random_device`` will now be ignored instead of 210 interpreted as a file to read entropy from. 211 212- ``std::valarray``'s unary operators ``!``, ``+``, ``~`` and ``-`` now return an expression 213 object instead of a ``valarray``. This was done to fix an issue where any expression involving 214 other ``valarray`` operators and one of these unary operators would end up with a dangling 215 reference. This is a potential ABI break for code that exposes ``std::valarray`` on an ABI 216 boundary, specifically if the return type of an ABI-boundary function is ``auto``-deduced 217 from an expression involving unary operators on ``valarray``. If you are concerned by this, 218 you can audit whether your executable or library exports any function that returns a 219 ``valarray``, and if so ensure that any such function uses ``std::valarray`` directly 220 as a return type instead of relying on the type of ``valarray``-expressions, which is 221 not guaranteed by the Standard anyway. 222 223- By default, the legacy debug mode symbols are not provided with the library anymore. If 224 you are a vendor and need to re-enable them, please use the ``LIBCXX_ENABLE_BACKWARDS_COMPATIBILITY_DEBUG_MODE_SYMBOLS`` 225 CMake flag, and contact the libc++ developers as this will be removed in LLVM 16. 226 Furthermore, please note that ``LIBCXX_ENABLE_DEBUG_MODE_SUPPORT`` is not honored anymore. 227 228Build System Changes 229-------------------- 230 231- Support for standalone builds have been entirely removed from libc++, libc++abi and 232 libunwind. Please use :ref:`these instructions <build instructions>` for building 233 libc++, libc++abi and/or libunwind. 234 235- The ``{LIBCXX,LIBCXXABI,LIBUNWIND}_TARGET_TRIPLE``, ``{LIBCXX,LIBCXXABI,LIBUNWIND}_SYSROOT`` and 236 ``{LIBCXX,LIBCXXABI,LIBUNWIND}_GCC_TOOLCHAIN`` CMake variables have been removed. Instead, please 237 use the ``CMAKE_CXX_COMPILER_TARGET``, ``CMAKE_SYSROOT`` and ``CMAKE_CXX_COMPILER_EXTERNAL_TOOLCHAIN`` 238 variables provided by CMake. 239 240- When building for Windows, vendors who want to avoid dll-exporting symbols from the static libc++abi 241 library should set ``LIBCXXABI_HERMETIC_STATIC_LIBRARY=ON`` when configuring CMake. The current 242 behavior, which tries to guess the correct dll-export semantics based on whether we're building 243 the libc++ shared library, will be removed in LLVM 16. 244 245- Previously, the C++ ABI library headers would be installed inside ``<prefix>/include/c++/v1`` 246 alongside the libc++ headers as part of building libc++. This is not the case anymore -- the 247 ABI library is expected to install its headers where it wants them as part of its own build. 248 Note that no action is required for most users, who build libc++ against libc++abi, since 249 libc++abi already installs its headers in the right location. However, vendors building 250 libc++ against alternate ABI libraries should make sure that their ABI library installs 251 its own headers. 252 253- The legacy testing configuration is now deprecated and will be removed in LLVM 16. For 254 most users, this should not have any impact. However, if you are testing libc++, libc++abi, or 255 libunwind in a configuration or on a platform that used to be supported by the legacy testing 256 configuration and isn't supported by one of the configurations in ``libcxx/test/configs``, 257 ``libcxxabi/test/configs``, or ``libunwind/test/configs``, please move to one of those 258 configurations or define your own. 259 260- MinGW DLL builds of libc++ no longer use dllimport in their headers, which 261 means that the same set of installed headers works for both DLL and static 262 linkage. This means that distributors finally can build both library 263 versions with a single CMake invocation. 264 265- The ``LIBCXX_HIDE_FROM_ABI_PER_TU_BY_DEFAULT`` configuration option has been removed. Indeed, 266 the risk of ODR violations from mixing different versions of libc++ in the same program has 267 been mitigated with a different technique that is simpler and does not have the drawbacks of 268 using internal linkage. 269