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 54API Changes 55----------- 56 57- The functions ``std::atomic<T*>::fetch_(add|sub)`` and 58 ``std::atomic_fetch_(add|sub)`` no longer accept a function pointer. While 59 this is technically an API break, the invalid syntax isn't supported by 60 libstc++ and MSVC STL. See https://godbolt.org/z/49fvzz98d. 61 62- The call of the functions ``std::atomic_(add|sub)(std::atomic<T*>*, ...)`` 63 with the explicit template argument ``T`` are now ill-formed. While this is 64 technically an API break, the invalid syntax isn't supported by libstc++ and 65 MSVC STL. See https://godbolt.org/z/v9959re3v. 66 67 Due to this change it's now possible to call these functions with the 68 explicit template argument ``T*``. This allows using the same syntax on the 69 major Standard library implementations. 70 See https://godbolt.org/z/oEfzPhTTb. 71 72 Calls to these functions where the template argument was deduced by the 73 compiler are unaffected by this change. 74 75- The functions ``std::allocator<T>::allocate`` and 76 ``std::experimental::pmr::polymorphic_allocator<T>::allocate`` now throw 77 an exception of type ``std::bad_array_new_length`` when the requested size 78 exceeds the maximum supported size, as required by the C++ standard. 79 Previously the type ``std::length_error`` was used. 80 81Build System Changes 82-------------------- 83 84- Building the libc++ shared or static library requires a C++ 20 capable compiler. 85 Consider using a Bootstrapping build to build libc++ with a fresh Clang if you 86 can't use the system compiler to build libc++ anymore. 87 88- Historically, there has been numerous ways of building libc++ and libc++abi. This has 89 culminated in over 5 different ways to build the runtimes, which made it impossible to 90 maintain with a good level of support. Starting with this release, the runtimes support 91 exactly two ways of being built, which should cater to all use-cases. Furthermore, 92 these builds are as lightweight as possible and will work consistently even when targetting 93 embedded platforms, which used not to be the case. Please see the documentation on building 94 libc++ to see those two ways of building and migrate over to the appropriate build instructions 95 as soon as possible. 96 97 All other ways to build are deprecated and will not be supported in the next release. 98 We understand that making these changes can be daunting. For that reason, here's a 99 summary of how to migrate from the two most common ways to build: 100 101 - If you were rooting your CMake invocation at ``<monorepo>/llvm`` and passing ``-DLLVM_ENABLE_PROJECTS=<...>`` 102 (which was the previously advertised way to build the runtimes), please simply root your CMake invocation at 103 ``<monorepo>/runtimes`` and pass ``-DLLVM_ENABLE_RUNTIMES=<...>``. 104 105 - If you were doing two CMake invocations, one rooted at ``<monorepo>/libcxx`` and one rooted at 106 ``<monorepo>/libcxxabi`` (this used to be called a "Standalone build"), please move them to a 107 single invocation like so: 108 109 .. code-block:: bash 110 111 $ cmake -S <monorepo>/libcxx -B libcxx-build <LIBCXX-OPTIONS> 112 $ cmake -S <monorepo>/libcxxabi -B libcxxabi-build <LIBCXXABI-OPTIONS> 113 114 should become 115 116 .. code-block:: bash 117 118 $ cmake -S <monorepo>/runtimes -B build -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi" <LIBCXX-OPTIONS> <LIBCXXABI-OPTIONS> 119