Hans Wennborg | 003a998 | 2019-07-18 11:51:05 +0000 | [diff] [blame] | 1 | ========================================= |
Tom Stellard | ce41e66 | 2021-07-27 21:51:07 -0700 | [diff] [blame] | 2 | Libc++ 14.0.0 (In-Progress) Release Notes |
Hans Wennborg | 003a998 | 2019-07-18 11:51:05 +0000 | [diff] [blame] | 3 | ========================================= |
Louis Dionne | 4222207 | 2018-09-06 14:46:22 +0000 | [diff] [blame] | 4 | |
| 5 | .. contents:: |
| 6 | :local: |
| 7 | :depth: 2 |
| 8 | |
Hans Wennborg | 3329a84 | 2018-09-10 08:57:12 +0000 | [diff] [blame] | 9 | Written by the `Libc++ Team <https://libcxx.llvm.org>`_ |
Louis Dionne | 4222207 | 2018-09-06 14:46:22 +0000 | [diff] [blame] | 10 | |
| 11 | .. warning:: |
| 12 | |
Tom Stellard | ce41e66 | 2021-07-27 21:51:07 -0700 | [diff] [blame] | 13 | These are in-progress notes for the upcoming libc++ 14 release. |
Louis Dionne | 4222207 | 2018-09-06 14:46:22 +0000 | [diff] [blame] | 14 | Release notes for previous releases can be found on |
Hans Wennborg | 3329a84 | 2018-09-10 08:57:12 +0000 | [diff] [blame] | 15 | `the Download Page <https://releases.llvm.org/download.html>`_. |
Louis Dionne | 4222207 | 2018-09-06 14:46:22 +0000 | [diff] [blame] | 16 | |
| 17 | Introduction |
| 18 | ============ |
| 19 | |
| 20 | This document contains the release notes for the libc++ C++ Standard Library, |
Tom Stellard | ce41e66 | 2021-07-27 21:51:07 -0700 | [diff] [blame] | 21 | part of the LLVM Compiler Infrastructure, release 14.0.0. Here we describe the |
Louis Dionne | 4222207 | 2018-09-06 14:46:22 +0000 | [diff] [blame] | 22 | status of libc++ in some detail, including major improvements from the previous |
| 23 | release and new feature work. For the general LLVM release notes, see `the LLVM |
Hans Wennborg | 3329a84 | 2018-09-10 08:57:12 +0000 | [diff] [blame] | 24 | documentation <https://llvm.org/docs/ReleaseNotes.html>`_. All LLVM releases may |
| 25 | be downloaded from the `LLVM releases web site <https://llvm.org/releases/>`_. |
Louis Dionne | 4222207 | 2018-09-06 14:46:22 +0000 | [diff] [blame] | 26 | |
| 27 | For more information about libc++, please see the `Libc++ Web Site |
Hans Wennborg | 3329a84 | 2018-09-10 08:57:12 +0000 | [diff] [blame] | 28 | <https://libcxx.llvm.org>`_ or the `LLVM Web Site <https://llvm.org>`_. |
Louis Dionne | 4222207 | 2018-09-06 14:46:22 +0000 | [diff] [blame] | 29 | |
Hans Wennborg | fc14f4e | 2020-01-15 10:02:56 +0100 | [diff] [blame] | 30 | Note that if you are reading this file from a Git checkout or the |
Louis Dionne | 4222207 | 2018-09-06 14:46:22 +0000 | [diff] [blame] | 31 | main Libc++ web page, this document applies to the *next* release, not |
| 32 | the current one. To see the release notes for a specific release, please |
Hans Wennborg | 3329a84 | 2018-09-10 08:57:12 +0000 | [diff] [blame] | 33 | see the `releases page <https://llvm.org/releases/>`_. |
Louis Dionne | 4222207 | 2018-09-06 14:46:22 +0000 | [diff] [blame] | 34 | |
Tom Stellard | ce41e66 | 2021-07-27 21:51:07 -0700 | [diff] [blame] | 35 | What's New in Libc++ 14.0.0? |
Hans Wennborg | 003a998 | 2019-07-18 11:51:05 +0000 | [diff] [blame] | 36 | ============================ |
Louis Dionne | 4222207 | 2018-09-06 14:46:22 +0000 | [diff] [blame] | 37 | |
| 38 | New Features |
| 39 | ------------ |
| 40 | |
Mark de Wever | cb50a05 | 2020-12-19 13:52:07 +0100 | [diff] [blame] | 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. |
Louis Dionne | 14918c8 | 2021-10-18 13:58:31 -0400 | [diff] [blame] | 45 | |
Mark de Wever | ebbd3b6 | 2021-05-25 20:11:08 +0200 | [diff] [blame] | 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. |
Raul Tambre | afcedea | 2020-06-19 12:43:33 +0530 | [diff] [blame] | 49 | |
Louis Dionne | 8925814 | 2021-08-23 15:32:36 -0400 | [diff] [blame] | 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++. |
Sylvestre Ledru | b6e1b31 | 2021-10-04 11:06:45 +0200 | [diff] [blame] | 53 | |
Danila Kutenin | a9cbea1 | 2021-11-16 15:48:59 -0500 | [diff] [blame] | 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 | |
Mark de Wever | 82dfd33 | 2021-02-09 17:52:41 +0100 | [diff] [blame] | 58 | - Floating-point support for ``std::to_chars`` support has been added. |
| 59 | Thanks to Stephan T. Lavavej and Microsoft for providing their implemention |
| 60 | to libc++. |
| 61 | |
Louis Dionne | 14918c8 | 2021-10-18 13:58:31 -0400 | [diff] [blame] | 62 | API Changes |
| 63 | ----------- |
Mark de Wever | 494905b | 2021-06-09 20:26:34 +0200 | [diff] [blame] | 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 | libstc++ 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 libstc++ 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. |
Louis Dionne | 076fd0c | 2021-10-07 16:19:11 -0400 | [diff] [blame] | 82 | |
Mikhail Maltsev | d93a877 | 2021-10-18 19:12:42 +0100 | [diff] [blame] | 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 | |
Martin Storsjö | 5e511f2 | 2021-11-02 16:32:09 +0000 | [diff] [blame] | 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 |
Louis Dionne | b35fab8 | 2021-11-08 15:30:32 -0500 | [diff] [blame] | 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. |
Martin Storsjö | 5e511f2 | 2021-11-02 16:32:09 +0000 | [diff] [blame] | 94 | |
Nikolas Klauser | 883bf17 | 2021-11-11 18:57:25 +0100 | [diff] [blame] | 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 | |
Joe Loser | 8fcb1d9 | 2021-10-28 15:38:02 -0400 | [diff] [blame] | 100 | ABI Changes |
| 101 | ----------- |
| 102 | |
| 103 | - The C++17 variable templates ``is_error_code_enum_v`` and |
| 104 | ``is_error_condition_enum_v`` are now of type ``bool`` instead of ``size_t``. |
| 105 | |
Louis Dionne | 495e9ad | 2021-11-29 16:20:48 -0500 | [diff] [blame] | 106 | - The C++03 emulation type for ``std::nullptr_t`` has been removed in favor of |
| 107 | using ``decltype(nullptr)`` in all standard modes. This is an ABI break for |
| 108 | anyone compiling in C++03 mode and who has ``std::nullptr_t`` as part of their |
| 109 | ABI. However, previously, these users' ABI would be incompatible with any other |
| 110 | binary or static archive compiled with C++11 or later. If you start seeing linker |
| 111 | errors involving ``std::nullptr_t`` against previously compiled binaries, this may |
| 112 | be the cause. You can define the ``_LIBCPP_ABI_USE_CXX03_NULLPTR_EMULATION`` macro |
| 113 | to return to the previous behavior. That macro will be removed in LLVM 15. Please |
| 114 | comment `here <https://reviews.llvm.org/D109459>`_ if you are broken by this change |
| 115 | and need to define the macro. |
| 116 | |
Louis Dionne | 14918c8 | 2021-10-18 13:58:31 -0400 | [diff] [blame] | 117 | Build System Changes |
| 118 | -------------------- |
| 119 | |
| 120 | - Building the libc++ shared or static library requires a C++ 20 capable compiler. |
| 121 | Consider using a Bootstrapping build to build libc++ with a fresh Clang if you |
| 122 | can't use the system compiler to build libc++ anymore. |
| 123 | |
Louis Dionne | 076fd0c | 2021-10-07 16:19:11 -0400 | [diff] [blame] | 124 | - Historically, there has been numerous ways of building libc++ and libc++abi. This has |
| 125 | culminated in over 5 different ways to build the runtimes, which made it impossible to |
| 126 | maintain with a good level of support. Starting with this release, the runtimes support |
| 127 | exactly two ways of being built, which should cater to all use-cases. Furthermore, |
| 128 | these builds are as lightweight as possible and will work consistently even when targetting |
| 129 | embedded platforms, which used not to be the case. Please see the documentation on building |
| 130 | libc++ to see those two ways of building and migrate over to the appropriate build instructions |
| 131 | as soon as possible. |
| 132 | |
| 133 | All other ways to build are deprecated and will not be supported in the next release. |
| 134 | We understand that making these changes can be daunting. For that reason, here's a |
| 135 | summary of how to migrate from the two most common ways to build: |
| 136 | |
| 137 | - If you were rooting your CMake invocation at ``<monorepo>/llvm`` and passing ``-DLLVM_ENABLE_PROJECTS=<...>`` |
| 138 | (which was the previously advertised way to build the runtimes), please simply root your CMake invocation at |
| 139 | ``<monorepo>/runtimes`` and pass ``-DLLVM_ENABLE_RUNTIMES=<...>``. |
| 140 | |
| 141 | - If you were doing two CMake invocations, one rooted at ``<monorepo>/libcxx`` and one rooted at |
| 142 | ``<monorepo>/libcxxabi`` (this used to be called a "Standalone build"), please move them to a |
| 143 | single invocation like so: |
| 144 | |
| 145 | .. code-block:: bash |
| 146 | |
| 147 | $ cmake -S <monorepo>/libcxx -B libcxx-build <LIBCXX-OPTIONS> |
| 148 | $ cmake -S <monorepo>/libcxxabi -B libcxxabi-build <LIBCXXABI-OPTIONS> |
| 149 | |
| 150 | should become |
| 151 | |
| 152 | .. code-block:: bash |
| 153 | |
| 154 | $ cmake -S <monorepo>/runtimes -B build -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi" <LIBCXX-OPTIONS> <LIBCXXABI-OPTIONS> |
Louis Dionne | dcd1105 | 2021-11-23 16:34:09 -0500 | [diff] [blame] | 155 | |
| 156 | - Support for building the runtimes using the GCC 32 bit multilib flag (``-m32``) has been removed. Support |
| 157 | for this had been flaky for a while, and we didn't know of anyone depending on this. Instead, please perform |
| 158 | a normal cross-compilation of the runtimes using the appropriate target, such as passing the following to |
| 159 | your bootstrapping build: |
| 160 | |
| 161 | .. code-block:: bash |
| 162 | |
| 163 | -DLLVM_RUNTIME_TARGETS=i386-unknown-linux |