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 112ABI Changes 113----------- 114 115- The C++17 variable templates ``is_error_code_enum_v`` and 116 ``is_error_condition_enum_v`` are now of type ``bool`` instead of ``size_t``. 117 118- The C++03 emulation type for ``std::nullptr_t`` has been removed in favor of 119 using ``decltype(nullptr)`` in all standard modes. This is an ABI break for 120 anyone compiling in C++03 mode and who has ``std::nullptr_t`` as part of their 121 ABI. However, previously, these users' ABI would be incompatible with any other 122 binary or static archive compiled with C++11 or later. If you start seeing linker 123 errors involving ``std::nullptr_t`` against previously compiled binaries, this may 124 be the cause. You can define the ``_LIBCPP_ABI_USE_CXX03_NULLPTR_EMULATION`` macro 125 to return to the previous behavior. That macro will be removed in LLVM 15. Please 126 comment `on D109459 <https://reviews.llvm.org/D109459>`_ if you are broken by this change 127 and need to define the macro. 128 129- On Apple platforms, ``std::random_device`` is now implemented on top of ``arc4random()`` 130 instead of reading from ``/dev/urandom``. Any implementation-defined token used when 131 constructing a ``std::random_device`` will now be ignored instead of interpreted as a 132 file to read entropy from. 133 134- ``std::lognormal_distribution::param_type`` used to store a data member of type 135 ``std::normal_distribution``; now this member is stored in the ``lognormal_distribution`` 136 class itself, and the ``param_type`` stores only the mean and standard deviation, 137 as required by the Standard. This changes ``sizeof(std::lognormal_distribution::param_type)``. 138 You can define the ``_LIBCPP_ABI_OLD_LOGNORMAL_DISTRIBUTION`` macro to return to the 139 previous behavior. That macro will be removed in LLVM 15. Please comment 140 `on PR52906 <https://llvm.org/PR52906>`_ if you are broken by this change and need to 141 define the macro. 142 143Build System Changes 144-------------------- 145 146- Building the libc++ shared or static library requires a C++ 20 capable compiler. 147 Consider using a Bootstrapping build to build libc++ with a fresh Clang if you 148 can't use the system compiler to build libc++ anymore. 149 150- Historically, there has been numerous ways of building libc++ and libc++abi. This has 151 culminated in over 5 different ways to build the runtimes, which made it impossible to 152 maintain with a good level of support. Starting with this release, the runtimes support 153 exactly two ways of being built, which should cater to all use-cases. Furthermore, 154 these builds are as lightweight as possible and will work consistently even when targeting 155 embedded platforms, which used not to be the case. Please see the documentation on building 156 libc++ to see those two ways of building and migrate over to the appropriate build instructions 157 as soon as possible. 158 159 All other ways to build are deprecated and will not be supported in the next release. 160 We understand that making these changes can be daunting. For that reason, here's a 161 summary of how to migrate from the two most common ways to build: 162 163 - If you were rooting your CMake invocation at ``<monorepo>/llvm`` and passing ``-DLLVM_ENABLE_PROJECTS=<...>`` 164 (which was the previously advertised way to build the runtimes), please simply root your CMake invocation at 165 ``<monorepo>/runtimes`` and pass ``-DLLVM_ENABLE_RUNTIMES=<...>``. 166 167 - If you were doing two CMake invocations, one rooted at ``<monorepo>/libcxx`` and one rooted at 168 ``<monorepo>/libcxxabi`` (this used to be called a "Standalone build"), please move them to a 169 single invocation like so: 170 171 .. code-block:: bash 172 173 $ cmake -S <monorepo>/libcxx -B libcxx-build <LIBCXX-OPTIONS> 174 $ cmake -S <monorepo>/libcxxabi -B libcxxabi-build <LIBCXXABI-OPTIONS> 175 176 should become 177 178 .. code-block:: bash 179 180 $ cmake -S <monorepo>/runtimes -B build -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi" <LIBCXX-OPTIONS> <LIBCXXABI-OPTIONS> 181 182- Support for building the runtimes using the GCC 32 bit multilib flag (``-m32``) has been removed. Support 183 for this had been flaky for a while, and we didn't know of anyone depending on this. Instead, please perform 184 a normal cross-compilation of the runtimes using the appropriate target, such as passing the following to 185 your bootstrapping build: 186 187 .. code-block:: bash 188 189 -DLLVM_RUNTIME_TARGETS=i386-unknown-linux 190 191- Libc++, libc++abi and libunwind will not be built with ``-fPIC`` by default anymore. 192 If you want to build those runtimes with position independent code, please specify 193 ``-DCMAKE_POSITION_INDEPENDENT_CODE=ON`` explicitly when configuring the build, or 194 ``-DRUNTIMES_<target-name>_CMAKE_POSITION_INDEPENDENT_CODE=ON`` if using the 195 bootstrapping build. 196