Libc++ 18.0.0 (In-Progress) Release Notes

Written by the Libc++ Team

Warning

These are in-progress notes for the upcoming libc++ 18.0.0 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 18.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++ 18.0.0?

  • The “safe” mode is replaced by the hardened mode in this release. The LIBCXX_ENABLE_ASSERTIONS CMake variable is deprecated and setting it will trigger an error; use LIBCXX_HARDENING_MODE instead. Similarly, the _LIBCPP_ENABLE_ASSERTIONS macro is deprecated and setting it to 1 now enables the hardened mode. See libcxx/docs/Hardening.rst for more details.

  • A new debug mode has been added, replacing the legacy debug mode that was removed in the LLVM 17 release. See libcxx/docs/Hardening.rst for more details.

Implemented Papers

  • P2497R0 - Testing for success or failure of <charconv> functions

  • P2697R1 - Interfacing bitset with string_view

  • P2443R1 - views::chunk_by

  • P2538R1 - ADL-proof std::projected

Improvements and New Features

  • The library now provides a hardened mode under which common cases of library undefined behavior will be turned into a reliable program termination. Vendors can configure whether the hardened mode is enabled by default with the LIBCXX_HARDENING_MODE variable at CMake configuration time. Users can control whether the hardened mode is enabled on a per translation unit basis using the -D_LIBCPP_ENABLE_HARDENED_MODE=1 macro. See the hardening documentation for more details.

  • The safe mode is now a part of hardening modes. Vendors can configure whether the safe mode is enabled by default with the LIBCXX_HARDENING_MODE variable at CMake configuration time. Users can control whether the safe mode is enabled on a per translation unit basis using the -D_LIBCPP_ENABLE_SAFE_MODE=1 macro. The _LIBCPP_ENABLE_ASSERTIONS macro that was previously used to enable the safe mode is now deprecated. See the hardening documentation for more details.

  • The library now provides a debug mode which is a superset of the safe mode, additionally enabling more expensive checks that are not suitable to be used in production. This replaces the legacy debug mode that was removed in this release. Unlike the legacy debug mode, this doesn’t affect the ABI and doesn’t require locking. Vendors can configure whether the debug mode is enabled by default with the LIBCXX_HARDENING_MODE variable at CMake configuration time. Users can control whether the debug mode is enabled on a per translation unit basis using the -D_LIBCPP_ENABLE_DEBUG_MODE=1 macro. See the hardening documentation for more details.

Deprecations and Removals

  • The “safe” mode is now controlled via the new generalized support for hardening. The LIBCXX_ENABLE_ASSERTIONS CMake variable that was used to enable the safe mode is now deprecated and setting it will trigger an error; use the LIBCXX_HARDENING_MODE variable with the value safe instead. Similarly, the _LIBCPP_ENABLE_ASSERTIONS macro is deprecated (setting it to 1 still enables the safe mode in this release while also issuing a deprecation warning). _LIBCPP_ENABLE_ASSERTIONS will be removed entirely in the next release and setting it will become an error. See the hardening documentation for more details.

Upcoming Deprecations and Removals

LLVM 18

  • The _LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED macro will not be honored anymore in LLVM 18. Please see the updated documentation about the safe libc++ mode and in particular the _LIBCPP_VERBOSE_ABORT macro for details.

  • The headers <experimental/deque>, <experimental/forward_list>, <experimental/list>, <experimental/map>, <experimental/memory_resource>, <experimental/regex>, <experimental/set>, <experimental/string>, <experimental/unordered_map>, <experimental/unordered_set>, and <experimental/vector> will be removed in LLVM 18, as all their contents will have been implemented in namespace std for at least two releases.

LLVM 19

  • The base template for std::char_traits has been marked as deprecated and will be removed in LLVM 19. If you are using std::char_traits with types other than char, wchar_t, char8_t, char16_t, char32_t or a custom character type for which you specialized std::char_traits, your code will stop working when we remove the base template. The Standard does not mandate that a base template is provided, and such a base template is bound to be incorrect for some types, which could currently cause unexpected behavior while going undetected. Note that the _LIBCPP_CHAR_TRAITS_REMOVE_BASE_SPECIALIZATION macro can be defined in LLVM 18 to eagerly remove the specialization and prepare code bases for the unconditional removal in LLVM 19.

ABI Affecting Changes

  • The symbol of a non-visible function part of std::system_error was removed. This is not a breaking change as the private function __init was never referenced internally outside of the dylib

  • This release of libc++ added missing visibility annotations on some types in the library. Users compiling with -fvisbility=hidden may notice that additional type infos from libc++ are being exported from their ABI. This is the correct behavior in almost all cases since exporting the RTTI is required for these types to work properly with dynamic_cast, exceptions and other mechanisms across binaries. However, if you intend to use libc++ purely as an internal implementation detail (i.e. you use libc++ as a static archive and never export libc++ symbols from your ABI) and you notice changes to your exported symbols list, then this means that you were not properly preventing libc++ symbols from being part of your ABI.

  • The name mangling for intantiations of std::projected has changed in order to implement P2538R1. This technically results in an ABI break, however in practice we expect uses of std::projected in ABI-sensitive places to be extremely rare. Any error resulting from this change should result in a link-time error.

Build System Changes

  • The LIBCXX_EXECUTOR CMake variable has been deprecated. If you are relying on this, the new replacement is passing -Dexecutor=... to llvm-lit. Alternatively, this flag can be made persistent in the generated test configuration file by passing -DLIBCXX_TEST_PARAMS=executor=.... This also applies to the LIBUWIND_EXECTOR and LIBCXXABI_EXECUTOR CMake variables. LLVM 19 will completely remove support for the *_EXECUTOR variables.