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