1========================================= 2Libc++ 14.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++ 14 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 14.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++ 14.0.0? 36============================ 37 38New Features 39------------ 40 41- There's initial support for the C++20 header ``<format>``. The implementation 42 is incomplete. Some functions are known to be inefficient; both in memory 43 usage and performance. The implementation is considered experimental and isn't 44 considered ABI stable. 45 46- There's a new CMake option ``LIBCXX_ENABLE_UNICODE`` to disable Unicode 47 support in the ``<format>`` header. This only affects the estimation of the 48 output width of the format functions. 49 50- Support for building libc++ on top of a C Standard Library that does not support ``wchar_t`` was 51 added. This is useful for building libc++ in an embedded setting, and it adds itself to the various 52 freestanding-friendly options provided by libc++. 53 54- ``_LIBCPP_DEBUG`` equals to ``1`` enables the randomization of unspecified 55 behavior of standard algorithms (e.g. equal elements in ``std::sort`` or 56 randomization of both sides of partition for ``std::nth_element``) 57 58- Floating-point support for ``std::to_chars`` support has been added. 59 Thanks to Stephan T. Lavavej and Microsoft for providing their implementation 60 to libc++. 61 62API Changes 63----------- 64 65- The functions ``std::atomic<T*>::fetch_(add|sub)`` and 66 ``std::atomic_fetch_(add|sub)`` no longer accept a function pointer. While 67 this is technically an API break, the invalid syntax isn't supported by 68 libstdc++ and MSVC STL. See https://godbolt.org/z/49fvzz98d. 69 70- The call of the functions ``std::atomic_(add|sub)(std::atomic<T*>*, ...)`` 71 with the explicit template argument ``T`` are now ill-formed. While this is 72 technically an API break, the invalid syntax isn't supported by libstdc++ and 73 MSVC STL. See https://godbolt.org/z/v9959re3v. 74 75 Due to this change it's now possible to call these functions with the 76 explicit template argument ``T*``. This allows using the same syntax on the 77 major Standard library implementations. 78 See https://godbolt.org/z/oEfzPhTTb. 79 80 Calls to these functions where the template argument was deduced by the 81 compiler are unaffected by this change. 82 83- The functions ``std::allocator<T>::allocate`` and 84 ``std::experimental::pmr::polymorphic_allocator<T>::allocate`` now throw 85 an exception of type ``std::bad_array_new_length`` when the requested size 86 exceeds the maximum supported size, as required by the C++ standard. 87 Previously the type ``std::length_error`` was used. 88 89- Removed the nonstandard methods ``std::chrono::file_clock::to_time_t`` and 90 ``std::chrono::file_clock::from_time_t``; neither libstdc++ nor MSVC STL 91 had such methods. Instead, in C++20, you can use ``std::chrono::file_clock::from_sys`` 92 and ``std::chrono::file_clock::to_sys``, which are specified in the Standard. 93 If you are not using C++20, you should move to it. 94 95- The declarations of functions ``declare_reachable``, ``undeclare_reachable``, ``declare_no_pointers``, 96 ``undeclare_no_pointers``, and ``get_pointer_safety`` have been removed not only from C++2b but 97 from all modes. Their symbols are still provided by the dynamic library for the benefit of 98 existing compiled code. All of these functions have always behaved as no-ops. 99 100- ``std::filesystem::path::iterator``, which (in our implementation) stashes 101 a ``path`` value inside itself similar to ``istream_iterator``, now sets its 102 ``reference`` type to ``path`` and its ``iterator_category`` to ``input_iterator_tag``, 103 so that it is a conforming input iterator in C++17 and a conforming 104 ``std::bidirectional_iterator`` in C++20. Before this release, it had set its 105 ``reference`` type to ``const path&`` and its ``iterator_category`` to 106 ``bidirectional_iterator_tag``, making it a non-conforming bidirectional iterator. 107 After this change, ``for`` loops of the form ``for (auto& c : path)`` must be rewritten 108 as either ``for (auto&& c : path)`` or ``for (const auto& c : path)``. 109 ``std::reverse_iterator<path::iterator>`` is no longer rejected. 110 111- Removed the nonstandard default constructor from ``std::chrono::month_weekday``. 112 You must now explicitly initialize with a ``chrono::month`` and 113 ``chrono::weekday_indexed`` instead of "meh, whenever". 114 115ABI Changes 116----------- 117 118- The C++17 variable templates ``is_error_code_enum_v`` and 119 ``is_error_condition_enum_v`` are now of type ``bool`` instead of ``size_t``. 120 121- The C++03 emulation type for ``std::nullptr_t`` has been removed in favor of 122 using ``decltype(nullptr)`` in all standard modes. This is an ABI break for 123 anyone compiling in C++03 mode and who has ``std::nullptr_t`` as part of their 124 ABI. However, previously, these users' ABI would be incompatible with any other 125 binary or static archive compiled with C++11 or later. If you start seeing linker 126 errors involving ``std::nullptr_t`` against previously compiled binaries, this may 127 be the cause. You can define the ``_LIBCPP_ABI_USE_CXX03_NULLPTR_EMULATION`` macro 128 to return to the previous behavior. That macro will be removed in LLVM 15. Please 129 comment `on D109459 <https://reviews.llvm.org/D109459>`_ if you are broken by this change 130 and need to define the macro. 131 132- On Apple platforms, ``std::random_device`` is now implemented on top of ``arc4random()`` 133 instead of reading from ``/dev/urandom``. Any implementation-defined token used when 134 constructing a ``std::random_device`` will now be ignored instead of interpreted as a 135 file to read entropy from. 136 137- ``std::lognormal_distribution::param_type`` used to store a data member of type 138 ``std::normal_distribution``; now this member is stored in the ``lognormal_distribution`` 139 class itself, and the ``param_type`` stores only the mean and standard deviation, 140 as required by the Standard. This changes ``sizeof(std::lognormal_distribution::param_type)``. 141 You can define the ``_LIBCPP_ABI_OLD_LOGNORMAL_DISTRIBUTION`` macro to return to the 142 previous behavior. That macro will be removed in LLVM 15. Please comment 143 `on PR52906 <https://llvm.org/PR52906>`_ if you are broken by this change and need to 144 define the macro. 145 146Build System Changes 147-------------------- 148 149- Building the libc++ shared or static library requires a C++ 20 capable compiler. 150 Consider using a Bootstrapping build to build libc++ with a fresh Clang if you 151 can't use the system compiler to build libc++ anymore. 152 153- Historically, there has been numerous ways of building libc++ and libc++abi. This has 154 culminated in over 5 different ways to build the runtimes, which made it impossible to 155 maintain with a good level of support. Starting with this release, the runtimes support 156 exactly two ways of being built, which should cater to all use-cases. Furthermore, 157 these builds are as lightweight as possible and will work consistently even when targeting 158 embedded platforms, which used not to be the case. Please see the documentation on building 159 libc++ to see those two ways of building and migrate over to the appropriate build instructions 160 as soon as possible. 161 162 All other ways to build are deprecated and will not be supported in the next release. 163 We understand that making these changes can be daunting. For that reason, here's a 164 summary of how to migrate from the two most common ways to build: 165 166 - If you were rooting your CMake invocation at ``<monorepo>/llvm`` and passing ``-DLLVM_ENABLE_PROJECTS=<...>`` 167 (which was the previously advertised way to build the runtimes), please simply root your CMake invocation at 168 ``<monorepo>/runtimes`` and pass ``-DLLVM_ENABLE_RUNTIMES=<...>``. 169 170 - If you were doing two CMake invocations, one rooted at ``<monorepo>/libcxx`` and one rooted at 171 ``<monorepo>/libcxxabi`` (this used to be called a "Standalone build"), please move them to a 172 single invocation like so: 173 174 .. code-block:: bash 175 176 $ cmake -S <monorepo>/libcxx -B libcxx-build <LIBCXX-OPTIONS> 177 $ cmake -S <monorepo>/libcxxabi -B libcxxabi-build <LIBCXXABI-OPTIONS> 178 179 should become 180 181 .. code-block:: bash 182 183 $ cmake -S <monorepo>/runtimes -B build -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi" <LIBCXX-OPTIONS> <LIBCXXABI-OPTIONS> 184 185- Support for building the runtimes using the GCC 32 bit multilib flag (``-m32``) has been removed. Support 186 for this had been flaky for a while, and we didn't know of anyone depending on this. Instead, please perform 187 a normal cross-compilation of the runtimes using the appropriate target, such as passing the following to 188 your bootstrapping build: 189 190 .. code-block:: bash 191 192 -DLLVM_RUNTIME_TARGETS=i386-unknown-linux 193 194- Libc++, libc++abi and libunwind will not be built with ``-fPIC`` by default anymore. 195 If you want to build those runtimes with position independent code, please specify 196 ``-DCMAKE_POSITION_INDEPENDENT_CODE=ON`` explicitly when configuring the build, or 197 ``-DRUNTIMES_<target-name>_CMAKE_POSITION_INDEPENDENT_CODE=ON`` if using the 198 bootstrapping build. 199