[libc++][doc] Update the release notes for LLVM 18

[mordante]

This is a preparation for the upcoming LLVM 18 release.

[llvmbot]

@llvm/pr-subscribers-libcxx

Author: Mark de Wever (mordante)

Changes

This is a preparation for the upcoming LLVM 18 release.

---

Full diff: https://github.com/llvm/llvm-project/pull/78324.diff

4 Files Affected:

• (modified) libcxx/docs/Hardening.rst (+2)
• (modified) libcxx/docs/ReleaseNotes/18.rst (+63-17)
• (modified) libcxx/docs/Status/Parallelism.rst (+1-1)
• (modified) libcxx/docs/Status/Ranges.rst (+1-1)

diff --git a/libcxx/docs/Hardening.rst b/libcxx/docs/Hardening.rst
index 33a168d6e16837..0761f42368e921 100644
--- a/libcxx/docs/Hardening.rst
+++ b/libcxx/docs/Hardening.rst
@@ -1,3 +1,5 @@
+.. _hardening-modes:
+
 ===============
 Hardening Modes
 ===============
diff --git a/libcxx/docs/ReleaseNotes/18.rst b/libcxx/docs/ReleaseNotes/18.rst
index 6a68514723bf2c..0e1b9c52f7f7ff 100644
--- a/libcxx/docs/ReleaseNotes/18.rst
+++ b/libcxx/docs/ReleaseNotes/18.rst
@@ -35,9 +35,25 @@ see the `releases page <https://llvm.org/releases/>`_.
 What's New in Libc++ 18.0.0?
 ==============================
 
-- 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.
+The main focus of the libc++ team has been to implement new C++20, C++23,
+and C++26 features.
+
+A new debug mode has been added, replacing the legacy debug mode that was
+removed in the LLVM 17 release. See :ref:`hardening-modes` for more details.
+
+Work on the ranges support has progressed. See
+:ref:`ranges-status` for the current status.
+
+Work on the experimental C++23 module support has progressed. The ``std.compat``
+module is available and the feature is retroactively available in C++20. See
+:ref:`ModulesInLibcxx` for more information.
+
+Work on the experimental C++17 Parallel STL has progressed. See
+:ref:`pstl-status` for the current status.
+
+Work on the experimental C++17 SIMD support has progressed. See
+:ref:`parallelism-status` for the current status.
+
 
 Implemented Papers
 ------------------
@@ -65,7 +81,7 @@ Implemented Papers
 Improvements and New Features
 -----------------------------
 
-- ``std::ranges::count`` is now optimized for ``vector<bool>::iterator``, which
+- ``std::ranges::count`` is now optimized for ``std::vector<bool>::iterator``, which
   can lead up to 350x performance improvements.
 
 - ``std::for_each`` has been optimized for segmented iterators like ``std::deque::iterator`` in C++23 and
@@ -89,6 +105,11 @@ Improvements and New Features
 - The ``_LIBCPP_ENABLE_CXX20_REMOVED_SHARED_PTR_UNIQUE`` macro has been added to make
   the function ``std::shared_ptr<...>::unique()`` available.
 
+- Asan annotations have been added to ``std::basic_string``.
+
+- The libc++ source code has been formatted with ``clang-format``. This 
+  `discourse thread <https://discourse.llvm.org/t/rfc-clang-formatting-all-of-libc-once-and-for-all>`_
+   contains information how to rebase downstream patches.
 
 Deprecations and Removals
 -------------------------
@@ -101,7 +122,7 @@ Deprecations and Removals
 - The non-conforming constructor ``std::future_error(std::error_code)`` has been removed. Please use the
   ``std::future_error(std::future_errc)`` constructor provided in C++17 instead.
 
-- `P1957 <https://wg21.link/P1957>` has been implemented in Clang and libc++ removed a code path that led to
+- `P1957 <https://wg21.link/P1957>`_ has been implemented in Clang and libc++ removed a code path that led to
   narrowing conversions in ``std::variant`` behaving in a non-standard way. This may change how some uses of
   ``std::variant``'s constructor behave in user code. The ``_LIBCPP_ENABLE_NARROWING_CONVERSIONS_IN_VARIANT``
   macro is provided to restore the previous behavior, and it will be supported in the LLVM 18 release only.
@@ -129,12 +150,23 @@ Deprecations and Removals
   that were removed in the C++17 and C++20 standards. Instead of using these
   macros, please use the macros to re-enable individual features.
 
+- The macro ``_LIBCPP_INLINE_VISIBILITY`` has been deprecated in LLVM 18 and
+  will be removed entirely in LLVM 19. The macro ``_LIBCPP_HIDE_FROM_ABI`` is
+  the drop-in replacement.
+
+- The macro ``_VSTD`` has been deprecated in LLVM 18 and will be removed
+  entirely in LLVM 19. The code ``std`` is the drop-in replacement.
+
+
 Upcoming Deprecations and Removals
 ----------------------------------
 
 LLVM 19
 ~~~~~~~
 
+- The ``LIBCXX_EXECUTOR`` CMake variable has been deprecated.  LLVM 19 will
+  completely remove support for the ``*_EXECUTOR`` variables.
+
 - The ``LIBCXX_ENABLE_ASSERTIONS`` CMake variable that was used to enable the safe mode will be deprecated and setting
   it will trigger an error; use the ``LIBCXX_HARDENING_MODE`` variable with the value ``extensive`` instead. Similarly,
   the ``_LIBCPP_ENABLE_ASSERTIONS`` macro will be deprecated (setting it to ``1`` still enables the extensive mode the
@@ -159,6 +191,12 @@ LLVM 19
   ``_LIBCPP_ENABLE_CXX20_REMOVED_FEATURES`` macros have been deprecated
   in LLVM 18 and will be removed entirely in LLVM 19.
 
+- The macro ``_LIBCPP_INLINE_VISIBILITY`` has been deprecated in LLVM 18 and
+  will be removed entirely in LLVM 19.
+
+- The macro ``_VSTD`` has been deprecated in LLVM 18 and will be removed
+  entirely in LLVM 19.
+
 LLVM 20
 ~~~~~~~
 
@@ -175,12 +213,12 @@ ABI Affecting Changes
 - 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
+  ``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
+- The name mangling for instantiations 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.
 
@@ -191,18 +229,26 @@ ABI Affecting Changes
   to throw a different exception when attempting allocations that are too large
   (``std::bad_alloc`` vs ``std::length_error``).
 
-- The layout of some views inside ``std::ranges`` that use the ``movable-box`` exposition-only type as an implementation 
-  detail has changed in order to fix a bug which could result in overwriting user data following the ``movable-box``
-  <https://github.com/llvm/llvm-project/issues/70506>. 
-  This was caused by incorrect usage of the ``[[no_unique_address]]`` attribute inside the implementation of ``movable-box``. 
-  This only affects the layout of the following views: ``take_while_view``, ``filter_view``, ``single_view``, ``drop_while_view``, 
-  ``repeat_view``, ``transform_view``, ``chunk_by_view``. In order to avoid silent breakage, an ABI tag has been added to 
-  these views such that their mangled name will be different starting in this version of libc++. 
-  As a result, attempting to call a function that expects one of these views will fail to link until the code has been rebuilt 
-  against a matching version of libc++. In practice, we believe it is unusual for these views to appear at ABI boundaries so this 
-  should not be a major problem for most users. However it is probably worth auditing ranges-heavy code for ABI boundaries that 
+- The layout of some views inside ``std::ranges`` that use the ``movable-box`` exposition-only type as an implementation
+  detail has changed in order to fix a `bug <https://github.com/llvm/llvm-project/issues/70506>`_ which could result in
+  overwriting user data following the ``movable-box``.
+  This was caused by incorrect usage of the ``[[no_unique_address]]`` attribute inside the implementation of ``movable-box``.
+  This affects the layout of the following views: ``take_while_view``, ``filter_view``, ``single_view``, ``drop_while_view``,
+  ``repeat_view``, ``transform_view``, ``chunk_by_view``. In order to avoid silent breakage, an ABI tag has been added to
+  these views such that their mangled name will be different starting in this version of libc++.
+  As a result, attempting to call a function that expects one of these views will fail to link until the code has been rebuilt
+  against a matching version of libc++. In practice, we believe it is unusual for these views to appear at ABI boundaries so this
+  should not be a major problem for most users. However it is probably worth auditing ranges-heavy code for ABI boundaries that
   would contain these views, or for types that contain these views as members and which are passed across ABI boundaries.
 
+- Some properties of libc++ may cause ODR-violations when mixing multiple libc++
+  instances. To avoid these, often benign, ODR-violations the ODR-affecting
+  properties are now part of the ABI tag. The ODR-affecting properties are:
+
+    - library version
+    - exceptions vs no-exceptions
+    - hardening mode
+
 Build System Changes
 --------------------
 
diff --git a/libcxx/docs/Status/Parallelism.rst b/libcxx/docs/Status/Parallelism.rst
index 4fce429bbe6cee..9f8a326867f1ca 100644
--- a/libcxx/docs/Status/Parallelism.rst
+++ b/libcxx/docs/Status/Parallelism.rst
@@ -1,4 +1,4 @@
-.. parallelism-status:
+.. _parallelism-status:
 
 ====================================
 libc++ Parallelism TS Status (N4808)
diff --git a/libcxx/docs/Status/Ranges.rst b/libcxx/docs/Status/Ranges.rst
index 7d36700d6545f0..cdbf68393b739d 100644
--- a/libcxx/docs/Status/Ranges.rst
+++ b/libcxx/docs/Status/Ranges.rst
@@ -1,4 +1,4 @@
-.. ranges-status:
+.. _ranges-status:
 
 ================================
 libc++ Ranges Status

[hawkinsw]

Looks great. I hope that my suggestions are useful. Feel free to ignore if they aren't!

[ldionne]

Let's add:

This should not be ABI-affecting except that libc++ will be more robust against different configurations of it being used in different translation units.

Also, the library version was already part of the ABI tag, so that property wasn't added in LLVM 18.

[mordante]

I added a comment regarding the version too.

[cjdb]

LGTM overall, thanks for working on this.

[cjdb]

Suggested change

	A new debug mode has been added, replacing the legacy debug mode that was
	removed in the LLVM 17 release. See :ref:`hardening-modes` for more details.
	A new debug mode replaced the legacy debug mode. See :ref:`hardening-modes` for more details.

[mordante]

Louis suggested a larger rewording, I've used that version.

[cjdb]

Suggested change

	- The layout of some views inside ``std::ranges`` that use the ``movable-box`` exposition-only type as an implementation
	- The layout of some range adaptors that use the *``movable-box``* exposition-only type as an implementation

[H-G-Hristov]

I am not sure that the combination

     *``movable-box``* 

works as intended. Maybe remove the back ticks.

[mordante]

it indeed does not work. I prefer to remove the * instead. We typically use the double backtracks. That the type is exposition only from formatting seems less important.

[cjdb]

Suggested change

	overwriting user data following the ``movable-box``.
	overwriting user data following the *``movable-box``*.

[mordante]

I've omitted this one too.

[cjdb]

Suggested change

	This was caused by incorrect usage of the ``[[no_unique_address]]`` attribute inside the implementation of ``movable-box``.
	This was caused by incorrect usage of the ``[[no_unique_address]]`` attribute inside the implementation of *``movable-box``*.

[philnik777]

Thanks!

[var-const]

Can you please also include the additions to the release notes from #78561 ?

[mordante]

Do you mean adding the committed changes or separate changes?

[mordante]

Thanks for all feedback. I'll land this patch later today. If there are comments after landing it we can create a new PR.