libcxx/docs/ReleaseNotes.rst

   1 =========================================
   2 Libc++ 14.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++ 14 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 14.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++ 14.0.0?
  36 ============================
  37
  38 New 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
  62 API 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 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
 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
 117 - On Apple platforms, ``std::random_device`` is now implemented on top of ``arc4random()``
 118   instead of reading from ``/dev/urandom``. Any implementation-defined token used when
 119   constructing a ``std::random_device`` will now be ignored instead of interpreted as a
 120   file to read entropy from.
 121
 122 Build System Changes
 123 --------------------
 124
 125 - Building the libc++ shared or static library requires a C++ 20 capable compiler.
 126   Consider using a Bootstrapping build to build libc++ with a fresh Clang if you
 127   can't use the system compiler to build libc++ anymore.
 128
 129 - Historically, there has been numerous ways of building libc++ and libc++abi. This has
 130   culminated in over 5 different ways to build the runtimes, which made it impossible to
 131   maintain with a good level of support. Starting with this release, the runtimes support
 132   exactly two ways of being built, which should cater to all use-cases. Furthermore,
 133   these builds are as lightweight as possible and will work consistently even when targeting
 134   embedded platforms, which used not to be the case. Please see the documentation on building
 135   libc++ to see those two ways of building and migrate over to the appropriate build instructions
 136   as soon as possible.
 137
 138   All other ways to build are deprecated and will not be supported in the next release.
 139   We understand that making these changes can be daunting. For that reason, here's a
 140   summary of how to migrate from the two most common ways to build:
 141
 142   - If you were rooting your CMake invocation at ``<monorepo>/llvm`` and passing ``-DLLVM_ENABLE_PROJECTS=<...>``
 143     (which was the previously advertised way to build the runtimes), please simply root your CMake invocation at
 144     ``<monorepo>/runtimes`` and pass ``-DLLVM_ENABLE_RUNTIMES=<...>``.
 145
 146   - If you were doing two CMake invocations, one rooted at ``<monorepo>/libcxx`` and one rooted at
 147     ``<monorepo>/libcxxabi`` (this used to be called a "Standalone build"), please move them to a
 148     single invocation like so:
 149
 150     .. code-block:: bash
 151
 152         $ cmake -S <monorepo>/libcxx -B libcxx-build <LIBCXX-OPTIONS>
 153         $ cmake -S <monorepo>/libcxxabi -B libcxxabi-build <LIBCXXABI-OPTIONS>
 154
 155     should become
 156
 157     .. code-block:: bash
 158
 159         $ cmake -S <monorepo>/runtimes -B build -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi" <LIBCXX-OPTIONS> <LIBCXXABI-OPTIONS>
 160
 161 - Support for building the runtimes using the GCC 32 bit multilib flag (``-m32``) has been removed. Support
 162   for this had been flaky for a while, and we didn't know of anyone depending on this. Instead, please perform
 163   a normal cross-compilation of the runtimes using the appropriate target, such as passing the following to
 164   your bootstrapping build:
 165
 166   .. code-block:: bash
 167
 168       -DLLVM_RUNTIME_TARGETS=i386-unknown-linux
 169
 170 - Libc++, libc++abi and libunwind will not be built with ``-fPIC`` by default anymore.
 171   If you want to build those runtimes with position independent code, please specify
 172   ``-DCMAKE_POSITION_INDEPENDENT_CODE=ON`` explicitly when configuring the build, or
 173   ``-DRUNTIMES_<target-name>_CMAKE_POSITION_INDEPENDENT_CODE=ON`` if using the
 174   bootstrapping build.