========================================= Libc++ 15.0.0 (In-Progress) Release Notes ========================================= .. contents:: :local: :depth: 2 Written by the `Libc++ Team `_ .. warning:: These are in-progress notes for the upcoming libc++ 15 release. Release notes for previous releases can be found on `the Download Page `_. Introduction ============ This document contains the release notes for the libc++ C++ Standard Library, part of the LLVM Compiler Infrastructure, release 15.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 `_. All LLVM releases may be downloaded from the `LLVM releases web site `_. For more information about libc++, please see the `Libc++ Web Site `_ or the `LLVM Web Site `_. 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 `_. What's New in Libc++ 15.0.0? ============================ Implemented Papers ------------------ - P0627R6 (Function to mark unreachable code) - P1165R1 (Make stateful allocator propagation more consistent for ``operator+(basic_string)``) - P0674R1 (Support arrays in ``make_shared`` and ``allocate_shared``) - P0980R1 (Making ``std::string`` constexpr) - P2216R3 (std::format improvements) - P0174R2 (Deprecating Vestigial Library Parts in C++17) - N4190 (Removing auto_ptr, random_shuffle(), And Old Stuff) - P0154R1 (Hardware inference size) - P0618R0 (Deprecating ) - Marked the following papers as "Complete" (note that some of those might have been implemented in a previous release but not marked as such): - P1207R4 (Movability of Single-pass Iterators); - P1474R1 (Helpful pointers for ``ContiguousIterator``); - P1522R1 (Iterator Difference Type and Integer Overflow); - P1523R1 (Views and Size Types); - P1456R1 (Move-only views); - P1870R1 (``forwarding-range`` is too subtle); - P1878R1 (Constraining Readable Types); - P1970R2 (Consistency for ``size()`` functions: Add ``ranges::ssize``); - P1983R0 (Wording for GB301, US296, US292, US291, and US283). New Features ------------ - `pop_heap` now uses an algorithm known as "bottom-up heapsort" or "heapsort with bounce" to reduce the number of comparisons, and rearranges elements using move-assignment instead of `swap`. - Libc++ now supports a variety of assertions that can be turned on to help catch undefined behavior in user code. This new support is now separate from the old (and incomplete) Debug Mode. Vendors can select whether the library they ship should include assertions or not by default. For details, see :ref:`the documentation ` about this new feature. - The implementation of the function ``std::to_chars`` for integral types has moved from the dylib to the header. This means the function no longer has a minimum deployment target. - The format functions (``std::format``, ``std::format_to``, ``std::format_to_n``, and ``std::formatted_size``) now validate the format string at compile time. When the format string is invalid this will make the code ill-formed instead of throwing an exception at run-time. (This does not affect the ``v`` functions.) API Changes ----------- - The ``_LIBCPP_ABI_UNSTABLE`` macro has been removed in favour of setting ``_LIBCPP_ABI_VERSION=2``. This should not have any impact on users because they were not supposed to set ``_LIBCPP_ABI_UNSTABLE`` manually, however we still feel that it is worth mentioning in the release notes in case some users had been doing it. - The header ```` has been removed. Instead, use ```` header. The associated macro ``_LIBCPP_DEPRECATED_EXPERIMENTAL_FILESYSTEM`` has also been removed. - Libc++ is getting ready to remove unnecessary transitive inclusions. This may break your code in the future. To future-proof your code to these removals, please compile your code with ``_LIBCPP_REMOVE_TRANSITIVE_INCLUDES`` defined and fix any compilation error resulting from missing includes. - The ````, ````, ````, ```` and ```` headers no longer transitively include the ```` header. If you see compiler errors related to missing declarations in namespace ``std``, make sure you have the necessary includes. - The integer distributions ``binomial_distribution``, ``discrete_distribution``, ``geometric_distribution``, ``negative_binomial_distribution``, ``poisson_distribution``, and ``uniform_int_distribution`` now conform to the Standard by rejecting template parameter types other than ``short``, ``int``, ``long``, ``long long``, (as an extension) ``__int128_t``, and the unsigned versions thereof. In particular, ``uniform_int_distribution`` is no longer supported. - The C++14 function ``std::quoted(const char*)`` is no longer supported in C++03 or C++11 modes. - Setting a custom debug handler with ``std::__libcpp_debug_function`` is not supported anymore. Please migrate to using the new support for :ref:`assertions ` instead. - ``vector::const_reference``, ``vector::const_iterator::reference`` and ``bitset::const_reference`` are now aliases for `bool` in the unstable ABI. - The ``_LIBCPP_DEBUG`` macro is not supported anymore. It will be honoured until LLVM 16, and then it will be an error to define that macro. To enable basic assertions (previously ``_LIBCPP_DEBUG=0``), please use ``_LIBCPP_ENABLE_ASSERTIONS=1``. To enable the debug mode (previously ``_LIBCPP_DEBUG=1|2``), please ensure that the library has been built with support for the debug mode, and it will be enabled automatically (no need to define ``_LIBCPP_DEBUG``). - The ``_LIBCPP_DISABLE_EXTERN_TEMPLATE`` macro is not honored anymore when defined by users of libc++. Instead, users not wishing to take a dependency on libc++ should link against the static version of libc++, which will result in no dependency being taken against the shared library. - The ``_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_VOID_SPECIALIZATION`` macro has been added to allow re-enabling the ``allocator`` specialization. When used in conjuction with ``_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS``, this ensures that the members of ``allocator`` removed in C++20 can be accessed. - The experimental versions of ``boyer_moore_searcher`` and ``boyer_moore_horspool_searcher`` will be removed in LLVM 17. You can disable the deprecation warnings by defining ``_LIBCPP_NO_EXPERIMENTAL_DEPRECATION_WARNING_SEARCHERS``. - ``std::function`` has been removed in C++03. If you are using it, please remove usages or upgrade to C++11 or later. It is possible to re-enable ``std::function`` in C++03 by defining ``_LIBCPP_ENABLE_CXX03_FUNCTION``. This option will be removed in LLVM 16. - ``unary_function`` and ``binary_function`` are no longer available in C++17 and C++20. They can be re-enabled by defining ``_LIBCPP_ENABLE_CXX17_REMOVED_UNARY_BINARY_FUNCTION``. They are also marked as ``[[deprecated]]`` in C++11 and later. To disable deprecation warnings you have to define ``_LIBCPP_DISABLE_DEPRECATION_WARNINGS``. Note that this disables all deprecation warnings. - The contents of ````, ``wstring_convert`` and ``wbuffer_convert`` have been marked as deprecated. To disable deprecation warnings you have to define ``_LIBCPP_DISABLE_DEPRECATION_WARNINGS``. Note that this disables all deprecation warnings. ABI Changes ----------- - The ``_LIBCPP_ABI_USE_CXX03_NULLPTR_EMULATION`` macro controlling whether we use an emulation for ``std::nullptr_t`` in C++03 mode has been removed. After this change, ``_LIBCPP_ABI_USE_CXX03_NULLPTR_EMULATION`` will not be honoured anymore and there will be no way to opt back into the C++03 emulation of ``std::nullptr_t``. - On FreeBSD, NetBSD, DragonFlyBSD and Solaris, ``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::valarray``'s unary operators ``!``, ``+``, ``~`` and ``-`` now return an expression object instead of a ``valarray``. This was done to fix an issue where any expression involving other ``valarray`` operators and one of these unary operators would end up with a dangling reference. This is a potential ABI break for code that exposes ``std::valarray`` on an ABI boundary, specifically if the return type of an ABI-boundary function is ``auto``-deduced from an expression involving unary operators on ``valarray``. If you are concerned by this, you can audit whether your executable or library exports any function that returns a ``valarray``, and if so ensure that any such function uses ``std::valarray`` directly as a return type instead of relying on the type of ``valarray``-expressions, which is not guaranteed by the Standard anyway. Build System Changes -------------------- - Support for standalone builds have been entirely removed from libc++, libc++abi and libunwind. Please use :ref:`these instructions ` for building libc++, libc++abi and/or libunwind. - The ``{LIBCXX,LIBCXXABI,LIBUNWIND}_TARGET_TRIPLE``, ``{LIBCXX,LIBCXXABI,LIBUNWIND}_SYSROOT`` and ``{LIBCXX,LIBCXXABI,LIBUNWIND}_GCC_TOOLCHAIN`` CMake variables have been removed. Instead, please use the ``CMAKE_CXX_COMPILER_TARGET``, ``CMAKE_SYSROOT`` and ``CMAKE_CXX_COMPILER_EXTERNAL_TOOLCHAIN`` variables provided by CMake. - When building for Windows, vendors who want to avoid dll-exporting symbols from the static libc++abi library should set ``LIBCXXABI_HERMETIC_STATIC_LIBRARY=ON`` when configuring CMake. The current behavior, which tries to guess the correct dll-export semantics based on whether we're building the libc++ shared library, will be removed in LLVM 16. - Previously, the C++ ABI library headers would be installed inside ``/include/c++/v1`` alongside the libc++ headers as part of building libc++. This is not the case anymore -- the ABI library is expected to install its headers where it wants them as part of its own build. Note that no action is required for most users, who build libc++ against libc++abi, since libc++abi already installs its headers in the right location. However, vendors building libc++ against alternate ABI libraries should make sure that their ABI library installs its own headers. - The legacy testing configuration is now deprecated and will be removed in the next release. For most users, this should not have any impact. However, if you are testing libc++, libc++abi or libunwind in a configuration or on a platform that used to be supported by the legacy testing configuration and isn't supported by one of the configurations in ``libcxx/test/configs``, ``libcxxabi/test/configs`` or ``libunwind/test/configs``, please move to one of those configurations or define your own. - The ``LIBCXX_ENABLE_DEBUG_MODE_SUPPORT`` CMake configuration is not supported anymore. If you were disabling support for the debug mode with that flag, please use ``LIBCXX_ENABLE_BACKWARDS_COMPATIBILITY_DEBUG_MODE_SYMBOLS=OFF`` instead. - MinGW DLL builds of libc++ no longer use dllimport in their headers, which means that the same set of installed headers works for both DLL and static linkage. This means that distributors finally can build both library versions with a single CMake invocation.