forked from OSchip/llvm-project
227 lines
12 KiB
ReStructuredText
227 lines
12 KiB
ReStructuredText
=========================================
|
|
Libc++ 14.0.0 (In-Progress) Release Notes
|
|
=========================================
|
|
|
|
.. contents::
|
|
:local:
|
|
:depth: 2
|
|
|
|
Written by the `Libc++ Team <https://libcxx.llvm.org>`_
|
|
|
|
.. warning::
|
|
|
|
These are in-progress notes for the upcoming libc++ 14 release.
|
|
Release notes for previous releases can be found on
|
|
`the Download Page <https://releases.llvm.org/download.html>`_.
|
|
|
|
Introduction
|
|
============
|
|
|
|
This document contains the release notes for the libc++ C++ Standard Library,
|
|
part of the LLVM Compiler Infrastructure, release 14.0.0. Here we describe the
|
|
status of libc++ in some detail, including major improvements from the previous
|
|
release and new feature work. For the general LLVM release notes, see `the LLVM
|
|
documentation <https://llvm.org/docs/ReleaseNotes.html>`_. All LLVM releases may
|
|
be downloaded from the `LLVM releases web site <https://llvm.org/releases/>`_.
|
|
|
|
For more information about libc++, please see the `Libc++ Web Site
|
|
<https://libcxx.llvm.org>`_ or the `LLVM Web Site <https://llvm.org>`_.
|
|
|
|
Note that if you are reading this file from a Git checkout or the
|
|
main Libc++ web page, this document applies to the *next* release, not
|
|
the current one. To see the release notes for a specific release, please
|
|
see the `releases page <https://llvm.org/releases/>`_.
|
|
|
|
What's New in Libc++ 14.0.0?
|
|
============================
|
|
|
|
New Features
|
|
------------
|
|
|
|
- There's support for the C++20 header ``<format>``. Some parts are still
|
|
missing, most notably the compile-time format string validation. Some
|
|
functions are known to be inefficient, both in memory usage and performance.
|
|
The implementation isn't API- or ABI-stable and therefore considered
|
|
experimental. (Some not-yet-implemented papers require an API-break.)
|
|
Vendors can still disable this header by turning the CMake option
|
|
`LIBCXX_ENABLE_INCOMPLETE_FEATURES` off.
|
|
|
|
- There's a new CMake option ``LIBCXX_ENABLE_UNICODE`` to disable Unicode
|
|
support in the ``<format>`` header. This only affects the estimation of the
|
|
output width of the format functions.
|
|
|
|
- Support for building libc++ on top of a C Standard Library that does not support ``wchar_t`` was
|
|
added. This is useful for building libc++ in an embedded setting, and it adds itself to the various
|
|
freestanding-friendly options provided by libc++.
|
|
|
|
- Defining ``_LIBCPP_DEBUG`` to ``1`` enables the randomization of unspecified
|
|
behavior in standard algorithms (e.g. the ordering of equal elements in ``std::sort``, or
|
|
the ordering of both sides of the partition in ``std::nth_element``).
|
|
|
|
- Floating-point support for ``std::to_chars`` support has been added.
|
|
Thanks to Stephan T. Lavavej and Microsoft for providing their implementation
|
|
to libc++.
|
|
|
|
- The C++20 ``<coroutine>`` implementation has been completed.
|
|
|
|
- More C++20 features have been implemented. :doc:`Status/Cxx20` has the full
|
|
overview of libc++'s C++20 implementation status.
|
|
|
|
- More C++2b features have been implemented. :doc:`Status/Cxx2b` has the full
|
|
overview of libc++'s C++2b implementation status.
|
|
|
|
API Changes
|
|
-----------
|
|
|
|
- The functions ``std::atomic<T*>::fetch_(add|sub)`` and
|
|
``std::atomic_fetch_(add|sub)`` no longer accept a function pointer. While
|
|
this is technically an API break, the invalid syntax isn't supported by
|
|
libstdc++ and MSVC STL. See https://godbolt.org/z/49fvzz98d.
|
|
|
|
- The call of the functions ``std::atomic_(add|sub)(std::atomic<T*>*, ...)``
|
|
with the explicit template argument ``T`` are now ill-formed. While this is
|
|
technically an API break, the invalid syntax isn't supported by libstdc++ and
|
|
MSVC STL. See https://godbolt.org/z/v9959re3v.
|
|
|
|
Due to this change it's now possible to call these functions with the
|
|
explicit template argument ``T*``. This allows using the same syntax on the
|
|
major Standard library implementations.
|
|
See https://godbolt.org/z/oEfzPhTTb.
|
|
|
|
Calls to these functions where the template argument was deduced by the
|
|
compiler are unaffected by this change.
|
|
|
|
- The functions ``std::allocator<T>::allocate`` and
|
|
``std::experimental::pmr::polymorphic_allocator<T>::allocate`` now throw
|
|
an exception of type ``std::bad_array_new_length`` when the requested size
|
|
exceeds the maximum supported size, as required by the C++ standard.
|
|
Previously the type ``std::length_error`` was used.
|
|
|
|
- Removed the nonstandard methods ``std::chrono::file_clock::to_time_t`` and
|
|
``std::chrono::file_clock::from_time_t``; neither libstdc++ nor MSVC STL
|
|
had such methods. Instead, in C++20, you can use ``std::chrono::file_clock::from_sys``
|
|
and ``std::chrono::file_clock::to_sys``, which are specified in the Standard.
|
|
If you are not using C++20, you should move to it.
|
|
|
|
- The declarations of functions ``declare_reachable``, ``undeclare_reachable``, ``declare_no_pointers``,
|
|
``undeclare_no_pointers``, and ``get_pointer_safety`` have been removed not only from C++2b but
|
|
from all modes. Their symbols are still provided by the dynamic library for the benefit of
|
|
existing compiled code. All of these functions have always behaved as no-ops.
|
|
|
|
- ``std::filesystem::path::iterator``, which (in our implementation) stashes
|
|
a ``path`` value inside itself similar to ``istream_iterator``, now sets its
|
|
``reference`` type to ``path`` and its ``iterator_category`` to ``input_iterator_tag``,
|
|
so that it is a conforming input iterator in C++17 and a conforming
|
|
``std::bidirectional_iterator`` in C++20. Before this release, it had set its
|
|
``reference`` type to ``const path&`` and its ``iterator_category`` to
|
|
``bidirectional_iterator_tag``, making it a non-conforming bidirectional iterator.
|
|
After this change, ``for`` loops of the form ``for (auto& c : path)`` must be rewritten
|
|
as either ``for (auto&& c : path)`` or ``for (const auto& c : path)``.
|
|
``std::reverse_iterator<path::iterator>`` is no longer rejected.
|
|
|
|
- Removed the nonstandard default constructor from ``std::chrono::month_weekday``.
|
|
You must now explicitly initialize with a ``chrono::month`` and
|
|
``chrono::weekday_indexed`` instead of "meh, whenever".
|
|
|
|
- C++20 requires that ``std::basic_string::reserve(n)`` never reduce the capacity
|
|
of the string. (For that, use ``shrink_to_fit()``.) Prior to this release, libc++'s
|
|
``std::basic_string::reserve(n)`` could reduce capacity in C++17 and before, but
|
|
not in C++20 and later. This caused ODR violations when mixing code compiled under
|
|
different Standard modes. After this change, libc++'s ``std::basic_string::reserve(n)``
|
|
never reduces capacity, even in C++17 and before.
|
|
C++20 deprecates the zero-argument overload of ``std::basic_string::reserve()``,
|
|
but specifically permits it to reduce capacity. To avoid breaking existing code
|
|
assuming that ``std::basic_string::reserve()`` will shrink, libc++ maintains
|
|
the behavior to shrink, even though that makes ``std::basic_string::reserve()`` not
|
|
a synonym for ``std::basic_string::reserve(0)`` in any Standard mode anymore.
|
|
|
|
- The ``<experimental/coroutine>`` header is deprecated, as is any
|
|
use of coroutines without C++20. Use C++20's ``<coroutine>`` header
|
|
instead. The ``<experimental/coroutine>`` header will be removed
|
|
in LLVM 15.
|
|
|
|
ABI Changes
|
|
-----------
|
|
|
|
- The C++17 variable templates ``is_error_code_enum_v`` and
|
|
``is_error_condition_enum_v`` are now of type ``bool`` instead of ``size_t``.
|
|
|
|
- The C++03 emulation type for ``std::nullptr_t`` has been removed in favor of
|
|
using ``decltype(nullptr)`` in all standard modes. This is an ABI break for
|
|
anyone compiling in C++03 mode and who has ``std::nullptr_t`` as part of their
|
|
ABI. However, previously, these users' ABI would be incompatible with any other
|
|
binary or static archive compiled with C++11 or later. If you start seeing linker
|
|
errors involving ``std::nullptr_t`` against previously compiled binaries, this may
|
|
be the cause. You can define the ``_LIBCPP_ABI_USE_CXX03_NULLPTR_EMULATION`` macro
|
|
to return to the previous behavior. That macro will be removed in LLVM 15. Please
|
|
comment `on D109459 <https://reviews.llvm.org/D109459>`_ if you are broken by this change
|
|
and need to define the macro.
|
|
|
|
- On Apple platforms, ``std::random_device`` is now implemented on top of ``arc4random()``
|
|
instead of reading from ``/dev/urandom``. Any implementation-defined token used when
|
|
constructing a ``std::random_device`` will now be ignored instead of interpreted as a
|
|
file to read entropy from.
|
|
|
|
- ``std::lognormal_distribution::param_type`` used to store a data member of type
|
|
``std::normal_distribution``; now this member is stored in the ``lognormal_distribution``
|
|
class itself, and the ``param_type`` stores only the mean and standard deviation,
|
|
as required by the Standard. This changes ``sizeof(std::lognormal_distribution::param_type)``.
|
|
You can define the ``_LIBCPP_ABI_OLD_LOGNORMAL_DISTRIBUTION`` macro to return to the
|
|
previous behavior. That macro will be removed in LLVM 15. Please comment
|
|
`on PR52906 <https://llvm.org/PR52906>`_ if you are broken by this change and need to
|
|
define the macro.
|
|
|
|
Build System Changes
|
|
--------------------
|
|
|
|
- Building the libc++ shared or static library requires a C++ 20 capable compiler.
|
|
Consider using a Bootstrapping build to build libc++ with a fresh Clang if you
|
|
can't use the system compiler to build libc++ anymore.
|
|
|
|
- Historically, there have been numerous ways of building libc++ and libc++abi. This has
|
|
led to at least 5 different ways to build the runtimes, which was impossible to
|
|
maintain with a good level of support. Starting with this release, libc++ and libc++abi support
|
|
exactly two ways of being built, which should cater to all use-cases. Furthermore,
|
|
these builds are as lightweight as possible and will work consistently even when targeting
|
|
embedded platforms, which used not to be the case. :doc:`BuildingLibcxx` describes
|
|
those two ways of building. Please migrate over to the appropriate build instructions
|
|
as soon as possible.
|
|
|
|
All other ways to build are deprecated and will not be supported in the next release.
|
|
We understand that making these changes can be daunting. For that reason, here's a
|
|
summary of how to migrate from the two most common ways to build:
|
|
|
|
- If you were rooting your CMake invocation at ``<monorepo>/llvm`` and passing ``-DLLVM_ENABLE_PROJECTS=<...>``
|
|
(which was the previously advertised way to build the runtimes), please simply root your CMake invocation at
|
|
``<monorepo>/runtimes`` and pass ``-DLLVM_ENABLE_RUNTIMES=<...>``.
|
|
|
|
- If you were doing two CMake invocations, one rooted at ``<monorepo>/libcxx`` and one rooted at
|
|
``<monorepo>/libcxxabi`` (this used to be called a "Standalone build"), please move them to a
|
|
single invocation like so:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ cmake -S <monorepo>/libcxx -B libcxx-build <LIBCXX-OPTIONS>
|
|
$ cmake -S <monorepo>/libcxxabi -B libcxxabi-build <LIBCXXABI-OPTIONS>
|
|
|
|
should become
|
|
|
|
.. code-block:: bash
|
|
|
|
$ cmake -S <monorepo>/runtimes -B build -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi" <LIBCXX-OPTIONS> <LIBCXXABI-OPTIONS>
|
|
|
|
- Support for building the runtimes using the GCC 32 bit multilib flag (``-m32``) has been removed. Support
|
|
for this had been flaky for a while, and we didn't know of anyone depending on this. Instead, please perform
|
|
a normal cross-compilation of the runtimes using the appropriate target, such as passing the following to
|
|
your bootstrapping build:
|
|
|
|
.. code-block:: bash
|
|
|
|
-DLLVM_RUNTIME_TARGETS=i386-unknown-linux
|
|
|
|
- Libc++, libc++abi, and libunwind will not be built with ``-fPIC`` by default anymore.
|
|
If you want to build those runtimes with position-independent code, please specify
|
|
``-DCMAKE_POSITION_INDEPENDENT_CODE=ON`` explicitly when configuring the build, or
|
|
``-DRUNTIMES_<target-name>_CMAKE_POSITION_INDEPENDENT_CODE=ON`` if using the
|
|
bootstrapping build.
|