libcxx/docs/ReleaseNotes/18.rst

   1 ===========================================
   2 Libc++ 18.0.0 (In-Progress) Release Notes
   3 ===========================================
   4
   5 .. contents::
   6    :local:
   7    :depth: 2
   8
   9 Written by the `Libc++ Team <https://libcxx.llvm.org>`_
  10
  11 .. warning::
  12
  13    These are in-progress notes for the upcoming libc++ 18.0.0 release.
  14    Release notes for previous releases can be found on
  15    `the Download Page <https://releases.llvm.org/download.html>`_.
  16
  17 Introduction
  18 ============
  19
  20 This document contains the release notes for the libc++ C++ Standard Library,
  21 part of the LLVM Compiler Infrastructure, release 18.0.0. Here we describe the
  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
  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/>`_.
  26
  27 For more information about libc++, please see the `Libc++ Web Site
  28 <https://libcxx.llvm.org>`_ or the `LLVM Web Site <https://llvm.org>`_.
  29
  30 Note that if you are reading this file from a Git checkout or the
  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
  33 see the `releases page <https://llvm.org/releases/>`_.
  34
  35 What's New in Libc++ 18.0.0?
  36 ==============================
  37
  38 - A new debug mode has been added, replacing the legacy debug mode that was
  39   removed in the LLVM 17 release. See ``libcxx/docs/Hardening.rst`` for more
  40   details.
  41
  42 Implemented Papers
  43 ------------------
  44
  45 - P2497R0 - Testing for success or failure of ``<charconv>`` functions
  46 - P2697R1 - Interfacing ``bitset`` with ``string_view``
  47 - P2443R1 - ``views::chunk_by``
  48 - P2538R1 - ADL-proof ``std::projected``
  49 - P2614R2 - Deprecate ``numeric_limits::has_denorm``
  50
  51
  52 Improvements and New Features
  53 -----------------------------
  54
  55 - ``std::ranges::count`` is now optimized for ``vector<bool>::iterator``, which
  56   can lead up to 350x performance improvements.
  57
  58 - The library now provides a hardened mode under which common cases of library undefined behavior will be turned into
  59   a reliable program termination. Vendors can configure whether the hardened mode is enabled by default with the
  60   ``LIBCXX_HARDENING_MODE`` variable at CMake configuration time. Users can control whether the hardened mode is
  61   enabled on a per translation unit basis using the ``-D_LIBCPP_ENABLE_HARDENED_MODE=1`` macro. See
  62   :ref:`the hardening documentation <using-hardening-modes>` for more details.
  63
  64 - The library now provides a debug mode which is a superset of the safe mode, additionally enabling more expensive
  65   checks that are not suitable to be used in production. This replaces the legacy debug mode that was removed in this
  66   release. Unlike the legacy debug mode, this doesn't affect the ABI and doesn't require locking. Vendors can configure
  67   whether the debug mode is enabled by default with the ``LIBCXX_HARDENING_MODE`` variable at CMake configuration time.
  68   Users can control whether the debug mode is enabled on a per translation unit basis using the
  69   ``-D_LIBCPP_ENABLE_DEBUG_MODE=1`` macro. See :ref:`the hardening documentation <using-hardening-modes>` for more
  70   details.
  71
  72 Deprecations and Removals
  73 -------------------------
  74
  75 - The non-conforming constructor ``std::future_error(std::error_code)`` has been removed. Please use the
  76   ``std::future_error(std::future_errc)`` constructor provided in C++17 instead.
  77
  78 Upcoming Deprecations and Removals
  79 ----------------------------------
  80
  81 LLVM 18
  82 ~~~~~~~
  83
  84 - The ``_LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED`` macro will not be honored anymore in LLVM 18.
  85   Please see the updated documentation about the safe libc++ mode and in particular the ``_LIBCPP_VERBOSE_ABORT``
  86   macro for details.
  87
  88 - The headers ``<experimental/deque>``, ``<experimental/forward_list>``, ``<experimental/list>``,
  89   ``<experimental/map>``, ``<experimental/memory_resource>``, ``<experimental/regex>``, ``<experimental/set>``,
  90   ``<experimental/string>``, ``<experimental/unordered_map>``, ``<experimental/unordered_set>``,
  91   and ``<experimental/vector>`` will be removed in LLVM 18, as all their contents will have been implemented in
  92   namespace ``std`` for at least two releases.
  93
  94 LLVM 19
  95 ~~~~~~~
  96
  97 - The ``LIBCXX_ENABLE_ASSERTIONS`` CMake variable that was used to enable the safe mode will be deprecated and setting
  98   it will trigger an error; use the ``LIBCXX_HARDENING_MODE`` variable with the value ``safe`` instead. Similarly, the
  99   ``_LIBCPP_ENABLE_ASSERTIONS`` macro will be deprecated (setting it to ``1`` still enables the safe mode the LLVM 19
 100   release while also issuing a deprecation warning). See :ref:`the hardening documentation <using-hardening-modes>` for
 101   more details.
 102
 103 - The base template for ``std::char_traits`` has been marked as deprecated and will be removed in LLVM 19. If you
 104   are using ``std::char_traits`` with types other than ``char``, ``wchar_t``, ``char8_t``, ``char16_t``, ``char32_t``
 105   or a custom character type for which you specialized ``std::char_traits``, your code will stop working when we
 106   remove the base template. The Standard does not mandate that a base template is provided, and such a base template
 107   is bound to be incorrect for some types, which could currently cause unexpected behavior while going undetected.
 108   Note that the ``_LIBCPP_CHAR_TRAITS_REMOVE_BASE_SPECIALIZATION`` macro can be defined in LLVM 18 to eagerly remove
 109   the specialization and prepare code bases for the unconditional removal in LLVM 19.
 110
 111 LLVM 20
 112 ~~~~~~~
 113
 114 - The ``LIBCXX_ENABLE_ASSERTIONS`` CMake variable and the ``_LIBCPP_ENABLE_ASSERTIONS`` macro that were used to enable
 115   the safe mode will be removed.
 116
 117
 118 ABI Affecting Changes
 119 ---------------------
 120
 121 - The symbol of a non-visible function part of ``std::system_error`` was removed.
 122   This is not a breaking change as the private function ``__init`` was never referenced internally outside of the dylib
 123
 124 - This release of libc++ added missing visibility annotations on some types in the library. Users compiling with
 125   ``-fvisbility=hidden`` may notice that additional type infos from libc++ are being exported from their ABI. This is
 126   the correct behavior in almost all cases since exporting the RTTI is required for these types to work properly with
 127   dynamic_cast, exceptions and other mechanisms across binaries. However, if you intend to use libc++ purely as an
 128   internal implementation detail (i.e. you use libc++ as a static archive and never export libc++ symbols from your ABI)
 129   and you notice changes to your exported symbols list, then this means that you were not properly preventing libc++
 130   symbols from being part of your ABI.
 131
 132 - The name mangling for intantiations of ``std::projected`` has changed in order to implement P2538R1. This technically
 133   results in an ABI break, however in practice we expect uses of ``std::projected`` in ABI-sensitive places to be
 134   extremely rare. Any error resulting from this change should result in a link-time error.
 135
 136 - Under the unstable ABI, the internal alignment requirements for heap allocations
 137   inside ``std::string`` has decreased from 16 to 8 This save memory since string requests fewer additional
 138   bytes than it did previously. However, this also changes the return value of ``std::string::max_size``
 139   and can cause code compiled against older libc++ versions but linked at runtime to a new version
 140   to throw a different exception when attempting allocations that are too large
 141   (``std::bad_alloc`` vs ``std::length_error``).
 142
 143 Build System Changes
 144 --------------------
 145
 146 - The ``LIBCXX_EXECUTOR`` CMake variable has been deprecated. If you are relying on this, the new replacement is
 147   passing ``-Dexecutor=...`` to ``llvm-lit``. Alternatively, this flag can be made persistent in the generated test
 148   configuration file by passing ``-DLIBCXX_TEST_PARAMS=executor=...``. This also applies to the ``LIBUWIND_EXECTOR``
 149   and ``LIBCXXABI_EXECUTOR`` CMake variables. LLVM 19 will completely remove support for the ``*_EXECUTOR`` variables.