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
100ABI 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
117Build 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
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 targeting
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>
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
164
165- Libc++, libc++abi and libunwind will not be built with ``-fPIC`` by default anymore.
166  If you want to build those runtimes with position independent code, please specify
167  ``-DCMAKE_POSITION_INDEPENDENT_CODE=ON`` explicitly when configuring the build, or
168  ``-DRUNTIMES_<target-name>_CMAKE_POSITION_INDEPENDENT_CODE=ON`` if using the
169  bootstrapping build.
170