[llvm-branch-commits] [libcxx] [libc++][docs] Convert doc files from reST to Markdown (PR #221513)
via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Mon Sep 7 14:14:54 PDT 2026
llvmorg-github-actions[bot] wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-libcxx
Author: Reid Kleckner (rnk)
<details>
<summary>Changes</summary>
I have more confidence in the conversion process now, so I decided to try to migrate all 41 libc++ docs in one batch. Let me know if I should split it up.
I made a longest-common-subsequence pixel diff tool, and I reviewed the diffs and they all seem like fixes, in the following categories:
- dashed bullet lists were previously not rendered, but now they are
- extra indentation interpreted as blockquotes has been removed
- single backticks are now codefont spans, not italic spans
Tracking issue: #<!-- -->201242
See the [migration guide] for more information.
[migration guide]: https://llvm.org/docs/SphinxQuickstartTemplate.html#markdown-migration-guidelines
This is a stacked PR based on #<!-- -->221512, which will be a standalone commit that
renames *.rst -> *.md before this PR lands for history preservation purposes.
-----
The [rendered preview index](https://llvmdocs.staging.reidkleckner.dev/) lists the available before/after pages.
Before/after validation links:
The two files under `libcxx/docs/Helpers/` are intentionally excluded from standalone Sphinx output. They were validated through their consumer pages and, for the release-notes template, an isolated render, so they are omitted from this page-link table.
| Source file | Before HTML | After HTML |
| --- | --- | --- |
| `libcxx/docs/ABIGuarantees.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/ABIGuarantees.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/ABIGuarantees.html) |
| `libcxx/docs/AddingNewCIJobs.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/AddingNewCIJobs.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/AddingNewCIJobs.html) |
| `libcxx/docs/CodingGuidelines.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/CodingGuidelines.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/CodingGuidelines.html) |
| `libcxx/docs/Contributing/NewStandardProcedure.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/Contributing/NewStandardProcedure.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/Contributing/NewStandardProcedure.html) |
| `libcxx/docs/Contributing/PostMeetingProcedure.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/Contributing/PostMeetingProcedure.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/Contributing/PostMeetingProcedure.html) |
| `libcxx/docs/Contributing/ReleaseProcedure.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/Contributing/ReleaseProcedure.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/Contributing/ReleaseProcedure.html) |
| `libcxx/docs/Contributing.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/Contributing.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/Contributing.html) |
| `libcxx/docs/DesignDocs/ABIVersioning.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/ABIVersioning.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/ABIVersioning.html) |
| `libcxx/docs/DesignDocs/AtomicDesign.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/AtomicDesign.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/AtomicDesign.html) |
| `libcxx/docs/DesignDocs/CapturingConfigInfo.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/CapturingConfigInfo.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/CapturingConfigInfo.html) |
| `libcxx/docs/DesignDocs/ExperimentalFeatures.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/ExperimentalFeatures.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/ExperimentalFeatures.html) |
| `libcxx/docs/DesignDocs/ExtendedCXX03Support.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/ExtendedCXX03Support.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/ExtendedCXX03Support.html) |
| `libcxx/docs/DesignDocs/FeatureTestMacros.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/FeatureTestMacros.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/FeatureTestMacros.html) |
| `libcxx/docs/DesignDocs/FileTimeType.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/FileTimeType.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/FileTimeType.html) |
| `libcxx/docs/DesignDocs/HeaderRemovalPolicy.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/HeaderRemovalPolicy.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/HeaderRemovalPolicy.html) |
| `libcxx/docs/DesignDocs/NoexceptPolicy.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/NoexceptPolicy.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/NoexceptPolicy.html) |
| `libcxx/docs/DesignDocs/PSTLIntegration.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/PSTLIntegration.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/PSTLIntegration.html) |
| `libcxx/docs/DesignDocs/ThreadingSupportAPI.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/ThreadingSupportAPI.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/ThreadingSupportAPI.html) |
| `libcxx/docs/DesignDocs/TimeZone.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/TimeZone.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/TimeZone.html) |
| `libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/UniquePtrTrivialAbi.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/UniquePtrTrivialAbi.html) |
| `libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.html) |
| `libcxx/docs/DesignDocs/VisibilityMacros.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/VisibilityMacros.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/VisibilityMacros.html) |
| `libcxx/docs/DesignDocs/WindowsSupport.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/DesignDocs/WindowsSupport.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/DesignDocs/WindowsSupport.html) |
| `libcxx/docs/FeatureTestMacroTable.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/FeatureTestMacroTable.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/FeatureTestMacroTable.html) |
| `libcxx/docs/Hardening.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/Hardening.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/Hardening.html) |
| `libcxx/docs/ImplementationDefinedBehavior.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/ImplementationDefinedBehavior.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/ImplementationDefinedBehavior.html) |
| `libcxx/docs/Modules.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/Modules.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/Modules.html) |
| `libcxx/docs/ReleaseNotes/20.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/ReleaseNotes/20.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/ReleaseNotes/20.html) |
| `libcxx/docs/ReleaseNotes/21.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/ReleaseNotes/21.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/ReleaseNotes/21.html) |
| `libcxx/docs/ReleaseNotes/22.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/ReleaseNotes/22.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/ReleaseNotes/22.html) |
| `libcxx/docs/ReleaseNotes/23.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/ReleaseNotes/23.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/ReleaseNotes/23.html) |
| `libcxx/docs/ReleaseNotes/24.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/ReleaseNotes/24.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/ReleaseNotes/24.html) |
| `libcxx/docs/ReleaseNotes.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/ReleaseNotes.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/ReleaseNotes.html) |
| `libcxx/docs/Status/Cxx17.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/Status/Cxx17.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/Status/Cxx17.html) |
| `libcxx/docs/Status/Cxx20.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/Status/Cxx20.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/Status/Cxx20.html) |
| `libcxx/docs/Status/Cxx23.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/Status/Cxx23.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/Status/Cxx23.html) |
| `libcxx/docs/Status/Cxx26.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/Status/Cxx26.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/Status/Cxx26.html) |
| `libcxx/docs/Status/Cxx29.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/Status/Cxx29.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/Status/Cxx29.html) |
| `libcxx/docs/TestingLibcxx.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/TestingLibcxx.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/TestingLibcxx.html) |
| `libcxx/docs/UserDocumentation.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/UserDocumentation.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/UserDocumentation.html) |
| `libcxx/docs/VendorDocumentation.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/VendorDocumentation.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/VendorDocumentation.html) |
| `libcxx/docs/index.md` | [before](https://llvmdocs.staging.reidkleckner.dev/before/libcxx/docs/index.html) | [after](https://llvmdocs.staging.reidkleckner.dev/after/libcxx/docs/index.html) |
---
Patch is 1.29 MiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/221513.diff
57 Files Affected:
- (modified) libcxx/docs/ABIGuarantees.md (+139-147)
- (modified) libcxx/docs/AddingNewCIJobs.md (+28-32)
- (modified) libcxx/docs/CMakeLists.txt (+3)
- (modified) libcxx/docs/CodingGuidelines.md (+101-116)
- (modified) libcxx/docs/Contributing.md (+152-163)
- (modified) libcxx/docs/Contributing/NewStandardProcedure.md (+21-18)
- (modified) libcxx/docs/Contributing/PostMeetingProcedure.md (+42-41)
- (modified) libcxx/docs/Contributing/ReleaseProcedure.md (+22-26)
- (modified) libcxx/docs/DesignDocs/ABIVersioning.md (+11-15)
- (modified) libcxx/docs/DesignDocs/AtomicDesign.md (+672-679)
- (modified) libcxx/docs/DesignDocs/CapturingConfigInfo.md (+29-36)
- (modified) libcxx/docs/DesignDocs/ExperimentalFeatures.md (+120-140)
- (modified) libcxx/docs/DesignDocs/ExtendedCXX03Support.md (+24-28)
- (modified) libcxx/docs/DesignDocs/FeatureTestMacros.md (+15-20)
- (modified) libcxx/docs/DesignDocs/FileTimeType.md (+283-304)
- (modified) libcxx/docs/DesignDocs/HeaderRemovalPolicy.md (+18-22)
- (modified) libcxx/docs/DesignDocs/NoexceptPolicy.md (+4-6)
- (modified) libcxx/docs/DesignDocs/PSTLIntegration.md (+11-12)
- (modified) libcxx/docs/DesignDocs/ThreadingSupportAPI.md (+32-31)
- (modified) libcxx/docs/DesignDocs/TimeZone.md (+41-49)
- (modified) libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md (+85-103)
- (modified) libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.md (+31-41)
- (modified) libcxx/docs/DesignDocs/VisibilityMacros.md (+46-43)
- (modified) libcxx/docs/DesignDocs/WindowsSupport.md (+8-12)
- (modified) libcxx/docs/FeatureTestMacroTable.md (+10-11)
- (modified) libcxx/docs/Hardening.md (+311-324)
- (modified) libcxx/docs/Helpers/ReleaseNotesTemplate.md (+24-40)
- (modified) libcxx/docs/Helpers/Styles.md (+20-37)
- (modified) libcxx/docs/ImplementationDefinedBehavior.md (+28-43)
- (modified) libcxx/docs/Modules.md (+218-217)
- (modified) libcxx/docs/ReleaseNotes.md (+14-10)
- (modified) libcxx/docs/ReleaseNotes/20.md (+106-126)
- (modified) libcxx/docs/ReleaseNotes/21.md (+83-113)
- (modified) libcxx/docs/ReleaseNotes/22.md (+95-108)
- (modified) libcxx/docs/ReleaseNotes/23.md (+78-97)
- (modified) libcxx/docs/ReleaseNotes/24.md (+58-71)
- (modified) libcxx/docs/Status/Cxx17.md (+41-32)
- (modified) libcxx/docs/Status/Cxx17Issues.csv (+307-307)
- (modified) libcxx/docs/Status/Cxx17Papers.csv (+105-105)
- (modified) libcxx/docs/Status/Cxx20.md (+41-32)
- (modified) libcxx/docs/Status/Cxx20Issues.csv (+292-292)
- (modified) libcxx/docs/Status/Cxx20Papers.csv (+193-193)
- (modified) libcxx/docs/Status/Cxx23.md (+41-32)
- (modified) libcxx/docs/Status/Cxx23Issues.csv (+300-300)
- (modified) libcxx/docs/Status/Cxx23Papers.csv (+114-114)
- (modified) libcxx/docs/Status/Cxx26.md (+44-33)
- (modified) libcxx/docs/Status/Cxx26Issues.csv (+337-337)
- (modified) libcxx/docs/Status/Cxx26Papers.csv (+208-208)
- (modified) libcxx/docs/Status/Cxx29.md (+44-33)
- (modified) libcxx/docs/Status/Cxx29Issues.csv (+19-19)
- (modified) libcxx/docs/Status/Cxx29Papers.csv (+21-21)
- (modified) libcxx/docs/TestingLibcxx.md (+263-287)
- (modified) libcxx/docs/UserDocumentation.md (+238-239)
- (modified) libcxx/docs/VendorDocumentation.md (+389-411)
- (modified) libcxx/docs/conf.py (+24-1)
- (modified) libcxx/docs/index.md (+141-159)
- (modified) libcxx/utils/generate_feature_test_macro_components.py (+80-56)
``````````diff
diff --git a/libcxx/docs/ABIGuarantees.md b/libcxx/docs/ABIGuarantees.md
index ee9d1296757c4..6fa1fa0513979 100644
--- a/libcxx/docs/ABIGuarantees.md
+++ b/libcxx/docs/ABIGuarantees.md
@@ -1,8 +1,6 @@
-.. _ABIGuarantees:
+(abiguarantees)=
-=======================
-libc++'s ABI Guarantees
-=======================
+# libc++'s ABI Guarantees
libc++ provides multiple types of ABI guarantees. These include stability of the layout of structs, the linking of TUs
built against different versions and configurations of the library, and more. This document describes what guarantees
@@ -12,254 +10,248 @@ Note that all of the guarantees listed below come with an asterisk that there ma
worth it to break that guarantee. These breaks are communicated to vendors by CCing #libcxx-vendors on GitHub. If you
are a vendor, please ask to be added to that group to be notified about changes that potentially affect you.
-ABI flags
-=========
-All the ABI flags listed below can be added to the ``__config_site`` header by the vendor to opt in to an ABI breaking
+## ABI flags
+
+All the ABI flags listed below can be added to the `__config_site` header by the vendor to opt in to an ABI breaking
change. These flags should never be set by the user. When porting libc++ to a new platform, vendord should consider
which flags to enable, assuming that ABI stability is relevant to them. Please contact the libc++ team on Discord or
through other means to be able to make an informed decision on which flags make sense to enable, and to avoid enabling
-flags which may not be stable. Flags can be enabled via the ``LIBCXX_ABI_DEFINES`` CMake option.
-
+flags which may not be stable. Flags can be enabled via the `LIBCXX_ABI_DEFINES` CMake option.
-Stability of the Layout of Structs
-==================================
+## Stability of the Layout of Structs
The layout of any user-observable struct is kept stable across versions of the library and any user-facing options
-documented :ref:`here <libcxx-configuration-macros>`. There are a lot of structs that have internal names, but are none
+documented {ref}`here <libcxx-configuration-macros>`. There are a lot of structs that have internal names, but are none
the less observable by users; for example through public aliases to these types or because they affect the layout of
other types.
There are multiple ABI flags which affect the layout of certain structs:
-``_LIBCPP_ABI_ALTERNATE_STRING_LAYOUT``
----------------------------------------
-This changes the internal layout of ``basic_string`` to move the section that is used for the internal buffer to the
+### `_LIBCPP_ABI_ALTERNATE_STRING_LAYOUT`
+
+This changes the internal layout of `basic_string` to move the section that is used for the internal buffer to the
front, making it eight byte aligned instead of being unaligned, improving the performance of some operations
significantly.
-``_LIBCPP_ABI_NO_ITERATOR_BASES``
----------------------------------
-This removes the ``iterator`` base class from ``back_insert_iterator``, ``front_insert_iterator``, ``insert_iterator``,
-``istream_iterator``, ``ostream_iterator``, ``ostreambuf_iterator``, ``reverse_iterator``, and ``raw_storage_iterator``.
+### `_LIBCPP_ABI_NO_ITERATOR_BASES`
+
+This removes the `iterator` base class from `back_insert_iterator`, `front_insert_iterator`, `insert_iterator`,
+`istream_iterator`, `ostream_iterator`, `ostreambuf_iterator`, `reverse_iterator`, and `raw_storage_iterator`.
This doesn't directly affect the layout of these types in most cases, but may result in more padding being used when
-they are used in combination, for example ``reverse_iterator<reverse_iterator<T>>``.
+they are used in combination, for example `reverse_iterator<reverse_iterator<T>>`.
-``_LIBCPP_ABI_NO_REVERSE_ITERATOR_SECOND_MEMBER``
--------------------------------------------------
-This removes a second member in ``reverse_iterator`` that is unused after LWG2360.
+### `_LIBCPP_ABI_NO_REVERSE_ITERATOR_SECOND_MEMBER`
-``_LIBCPP_ABI_VARIANT_INDEX_TYPE_OPTIMIZATION``
--------------------------------------------------
-This changes the index type used inside ``variant`` to the smallest required type to reduce the datasize of variants in
+This removes a second member in `reverse_iterator` that is unused after LWG2360.
+
+### `_LIBCPP_ABI_VARIANT_INDEX_TYPE_OPTIMIZATION`
+
+This changes the index type used inside `variant` to the smallest required type to reduce the datasize of variants in
most cases.
-``_LIBCPP_ABI_OPTIMIZED_FUNCTION``
-----------------------------------
-This significantly restructures how ``function`` is written to provide better performance, but is currently not ABI
+### `_LIBCPP_ABI_OPTIMIZED_FUNCTION`
+
+This significantly restructures how `function` is written to provide better performance, but is currently not ABI
stable.
-``_LIBCPP_ABI_VECTOR_LAYOUT_SIZE_BASED``
-----------------------------------------
-Changes the layout of :cpp:type:`std::vector` from pointer-based to size-based.
+### `_LIBCPP_ABI_VECTOR_LAYOUT_SIZE_BASED`
-libc++ supports two different data layouts for :cpp:type:`std::vector`:
+Changes the layout of {cpp:type}`std::vector` from pointer-based to size-based.
-.. list-table::
- :header-rows: 1
+libc++ supports two different data layouts for {cpp:type}`std::vector`:
- * - **Layout**
- - ABI
- - Description
- * - Pointer-based layout
- - Stable ABI (default)
- - :cpp:type:`std::vector` uses three pointers to manage its state:
+:::{list-table}
+:header-rows: 1
- * A pointer to the beginning of the buffer (:cpp:expr:`begin_`);
- * A pointer to where the next element should be inserted (:cpp:expr:`end_`); and
- * A pointer to the end of the buffer (:cpp:expr:`cap_`).
+* - **Layout**
+ - ABI
+ - Description
+* - Pointer-based layout
+ - Stable ABI (default)
+ - {cpp:type}`std::vector` uses three pointers to manage its state:
- This layout causes :cpp:type:`vector`'s implementation details to be pointer-oriented.
- The following methods are of particular interest:
+ * A pointer to the beginning of the buffer ({cpp:expr}`begin_`);
+ * A pointer to where the next element should be inserted ({cpp:expr}`end_`); and
+ * A pointer to the end of the buffer ({cpp:expr}`cap_`).
- * :cpp:expr:`vector::size()` returns :cpp:expr:`end_ - begin_`;
- * :cpp:expr:`vector::capacity()` returns :cpp:expr:`cap_ - begin_`; and
- * :cpp:expr:`vector::end()` returns :cpp:expr:`end_`.
+ This layout causes {cpp:type}`vector`'s implementation details to be pointer-oriented.
+ The following methods are of particular interest:
- This is the original layout for libc++'s :cpp:type:`std::vector` implementation, and
- is the default layout as a result.
+ * {cpp:expr}`vector::size()` returns {cpp:expr}`end_ - begin_`;
+ * {cpp:expr}`vector::capacity()` returns {cpp:expr}`cap_ - begin_`; and
+ * {cpp:expr}`vector::end()` returns {cpp:expr}`end_`.
- * - Size-based layout
- - Unstable ABI (opt-in)
- - :cpp:type:`std::vector` uses a pointer and two integers to manage its state:
+ This is the original layout for libc++'s {cpp:type}`std::vector` implementation, and
+ is the default layout as a result.
- * A pointer to the beginning of the buffer (:cpp:expr:`begin_`);
- * An integer storing how many elements are in the vector (:cpp:expr:`size_`); and
- * An integer storing how many elements the vector can potentially hold before needing
- to reallocate (:cpp:expr:`capacity_`).
+* - Size-based layout
+ - Unstable ABI (opt-in)
+ - {cpp:type}`std::vector` uses a pointer and two integers to manage its state:
- This layout causes :cpp:type:`vector`'s implementation details to be integer-oriented.
- The following methods are of particular interest:
+ * A pointer to the beginning of the buffer ({cpp:expr}`begin_`);
+ * An integer storing how many elements are in the vector ({cpp:expr}`size_`); and
+ * An integer storing how many elements the vector can potentially hold before needing
+ to reallocate ({cpp:expr}`capacity_`).
- * :cpp:expr:`vector::size()` returns :cpp:expr:`size_`;
- * :cpp:expr:`vector::capacity()` returns :cpp:expr:`cap_`; and
- * :cpp:expr:`vector::end()` returns :cpp:expr:`begin_ + size_`.
+ This layout causes {cpp:type}`vector`'s implementation details to be integer-oriented.
+ The following methods are of particular interest:
- This layout is opt-in, and is incompatible with the pointer-based layout. It has the
- potential for significant performance improvements, especially when combined with
- :ref:`hardening`.
+ * {cpp:expr}`vector::size()` returns {cpp:expr}`size_`;
+ * {cpp:expr}`vector::capacity()` returns {cpp:expr}`cap_`; and
+ * {cpp:expr}`vector::end()` returns {cpp:expr}`begin_ + size_`.
-``_LIBCPP_ABI_NO_RANDOM_DEVICE_COMPATIBILITY_LAYOUT``
------------------------------------------------------
-This changes the layout of ``random_device`` to only holds state with an implementation that gets entropy from a file
-(see ``_LIBCPP_USING_DEV_RANDOM``). When switching from this implementation to another one on a platform that has
-already shipped ``random_device``, one needs to retain the same object layout to remain ABI compatible. This flag
+ This layout is opt-in, and is incompatible with the pointer-based layout. It has the
+ potential for significant performance improvements, especially when combined with
+ {ref}`hardening`.
+:::
+
+### `_LIBCPP_ABI_NO_RANDOM_DEVICE_COMPATIBILITY_LAYOUT`
+
+This changes the layout of `random_device` to only holds state with an implementation that gets entropy from a file
+(see `_LIBCPP_USING_DEV_RANDOM`). When switching from this implementation to another one on a platform that has
+already shipped `random_device`, one needs to retain the same object layout to remain ABI compatible. This flag
removes these workarounds for platforms that don't care about ABI compatibility.
-``_LIBCPP_ABI_NO_COMPRESSED_PAIR_PADDING``
-------------------------------------------
-This removes artificial padding from ``_LIBCPP_COMPRESSED_PAIR``.
+### `_LIBCPP_ABI_NO_COMPRESSED_PAIR_PADDING`
+
+This removes artificial padding from `_LIBCPP_COMPRESSED_PAIR`.
-These macros are used inside the associative and unordered containers, ``deque``, ``forward_list``, ``future``,
-``list``, ``basic_string``, ``function``, ``shared_ptr``, ``unique_ptr``, and ``vector`` to stay ABI compatible with the
-legacy ``__compressed_pair`` type. ``__compressed_pair`` had historically been used to reduce storage requirements in
-the case of empty types, but has been replaced by ``[[no_unique_address]]``. ``[[no_unique_address]]`` is significantly
+These macros are used inside the associative and unordered containers, `deque`, `forward_list`, `future`,
+`list`, `basic_string`, `function`, `shared_ptr`, `unique_ptr`, and `vector` to stay ABI compatible with the
+legacy `__compressed_pair` type. `__compressed_pair` had historically been used to reduce storage requirements in
+the case of empty types, but has been replaced by `[[no_unique_address]]`. `[[no_unique_address]]` is significantly
lighter in terms of compile time and debug information, and also improves the layout of structs further. However, to
keep ABI stability, the additional improvements in layout had to be reverted by introducing artificial padding. This
flag removes that artificial padding.
-``_LIBCPP_ABI_IOS_ALLOW_ARBITRARY_FILL_VALUE``
-----------------------------------------------
-``basic_ios`` uses ``WEOF`` to indicate that the fill value is uninitialized. However, on platforms where the size of
-``char_type`` is equal to or greater than the size of ``int_type`` and ``char_type`` is unsigned,
-``char_traits<char_type>::eq_int_type()`` cannot distinguish between ``WEOF`` and ``WCHAR_MAX``. This flag changes
-``basic_ios`` to instead track whether the fill value has been initialized using a separate boolean.
+### `_LIBCPP_ABI_IOS_ALLOW_ARBITRARY_FILL_VALUE`
+`basic_ios` uses `WEOF` to indicate that the fill value is uninitialized. However, on platforms where the size of
+`char_type` is equal to or greater than the size of `int_type` and `char_type` is unsigned,
+`char_traits<char_type>::eq_int_type()` cannot distinguish between `WEOF` and `WCHAR_MAX`. This flag changes
+`basic_ios` to instead track whether the fill value has been initialized using a separate boolean.
+
+## Linking TUs which have been compiled against different releases of libc++
-Linking TUs which have been compiled against different releases of libc++
-=========================================================================
libc++ supports linking TUs which have been compiled against different releases of libc++ by marking symbols with
hidden visibility and changing the mangling of header-only functions in every release.
+## Linking TUs which have been compiled with different flags affecting code gen
-Linking TUs which have been compiled with different flags affecting code gen
-============================================================================
There are a lot of compiler (and library) flags which change the code generated for functions. This includes flags like
-``-O1``, which are guaranteed by the compiler to not change the observable behaviour of a correct program, as well as
-flags like ``-fexceptions``, which **do** change the observable behaviour. libc++ allows linking of TUs which have been
+`-O1`, which are guaranteed by the compiler to not change the observable behaviour of a correct program, as well as
+flags like `-fexceptions`, which **do** change the observable behaviour. libc++ allows linking of TUs which have been
compiled with specific flags only and makes no guarantees for any of the flags not listed below.
The flags allowed (in any combination) are:
-- ``-f[no-]exceptions``
-- ``-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE{_FAST,_EXTENSIVE,_DEBUG,_NONE}``
+- `-f[no-]exceptions`
+- `-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE{_FAST,_EXTENSIVE,_DEBUG,_NONE}`
Note that this does not provide any guarantees about user-defined functions, but only that the libc++ functions linked
behave as the flags say.
+## Availability of symbols in the built library (both static and shared)
-Availability of symbols in the built library (both static and shared)
-=====================================================================
In general, libc++ does not make any guarantees about forwards-compatibility. That is, a TU compiled against new headers
may not work with an older library. Vendors who require such support can leverage availability markup. On the other
hand, backwards compatibility is generally guaranteed.
There are multiple ABI flags that change the symbols exported from the built library:
-``_LIBCPP_ABI_STRING_OPTIMIZED_EXTERNAL_INSTANTIATION``
--------------------------------------------------------
-This replaces the symbols that are exported for ``basic_string`` to avoid exporting functions which are likely to be
+### `_LIBCPP_ABI_STRING_OPTIMIZED_EXTERNAL_INSTANTIATION`
+
+This replaces the symbols that are exported for `basic_string` to avoid exporting functions which are likely to be
inlined as well as explicitly moving paths to the built library which are slow, improving fast-path inlining of multiple
functions. This flag is currently unstable.
+## Stability of the traits of a type
-Stability of the traits of a type
-=================================
Whether a particular trait of a type is kept stable depends heavily on the type in question and the trait. The most
important trait of a type to keep stable is the triviality for the purpose of calls, since that directly affects the
function call ABI. Which types are considered non-trivial for the purpose of calls is defined in the
-`Itanium ABI <https://itanium-cxx-abi.github.io/cxx-abi/abi.html#definitions>`_.
-``is_trivially_copyable`` should also be kept stable usually, since many programs depend on this trait for their own
+[Itanium ABI](https://itanium-cxx-abi.github.io/cxx-abi/abi.html#definitions).
+`is_trivially_copyable` should also be kept stable usually, since many programs depend on this trait for their own
layouting. This isn't as rigid as the previous requirement though.
There are multiple ABI flags that change traits of a struct:
-``_LIBCPP_ABI_ENABLE_UNIQUE_PTR_TRIVIAL_ABI``
----------------------------------------------
-This flag adds ``[[clang::trivial_abi]]`` to ``unique_ptr``, which makes it trivial for the purpose of calls.
+### `_LIBCPP_ABI_ENABLE_UNIQUE_PTR_TRIVIAL_ABI`
+
+This flag adds `[[clang::trivial_abi]]` to `unique_ptr`, which makes it trivial for the purpose of calls.
-``_LIBCPP_ABI_ENABLE_SHARED_PTR_TRIVIAL_ABI``
----------------------------------------------
-This flag adds ``[[clang::trivial_abi]]`` to ``shared_ptr``, which makes it trivial for the purpose of calls.
+### `_LIBCPP_ABI_ENABLE_SHARED_PTR_TRIVIAL_ABI`
-``_LIBCPP_ABI_TRIVIALLY_COPYABLE_BIT_ITERATOR``
------------------------------------------------
-This flag makes ``__bit_iterator`` (a.k.a. ``vector<bool>::iterator``) trivially copyable as well as trivial for the
+This flag adds `[[clang::trivial_abi]]` to `shared_ptr`, which makes it trivial for the purpose of calls.
+
+### `_LIBCPP_ABI_TRIVIALLY_COPYABLE_BIT_ITERATOR`
+
+This flag makes `__bit_iterator` (a.k.a. `vector<bool>::iterator`) trivially copyable as well as trivial for the
purpose of calls, since the copy constructor is made trivial.
-``_LIBCPP_ABI_USE_SMALL_DEQUE_BLOCK_SIZE``
-------------------------------------------
-This flag sets the default block size of ``deque`` to 512 bytes and the minimum number of elements per block to 4.
+### `_LIBCPP_ABI_USE_SMALL_DEQUE_BLOCK_SIZE`
+
+This flag sets the default block size of `deque` to 512 bytes and the minimum number of elements per block to 4.
+
+## Types that public aliases reference
-Types that public aliases reference
-===================================
There are a lot of aliases that reference types with library internal names. For example, containers contain an
-``iterator`` alias to a type with a library internal name. These have to always reference the same type, since the
+`iterator` alias to a type with a library internal name. These have to always reference the same type, since the
mangling of user-defined function overloads would change otherwise. A notable exception to this are the alias templates
to type traits. There doesn't seem to be anybody who relies on these names staying the same, so it is OK to change what
these aliases actually reference.
There are multiple ABI flags which change which type an alias references:
-``_LIBCPP_ABI_INCOMPLETE_TYPES_IN_DEQUE``
------------------------------------------
-This changes ``deque::iterator`` to avoid requiring complete types for ``deque``.
+### `_LIBCPP_ABI_INCOMPLETE_TYPES_IN_DEQUE`
+
+This changes `deque::iterator` to avoid requiring complete types for `deque`.
+
+### `_LIBCPP_ABI_FIX_UNORDERED_CONTAINER_SIZE_TYPE`
-``_LIBCPP_ABI_FIX_UNORDERED_CONTAINER_SIZE_TYPE``
--------------------------------------------------
-This changes the unordered container's ``size_types`` aliases.
+This changes the unordered container's `size_types` aliases.
-``_LIBCPP_ABI_USE_WRAP_ITER_IN_STD_ARRAY`` and ``_LIBCPP_ABI_USE_WRAP_ITER_IN_STD_STRING_VIEW``
------------------------------------------------------------------------------------------------
-This changes the ``iterator`` and ``const_iterator`` of ``array`` and ``string_view`` respectively to reference
-``__wrap_iter`` instead, which makes it less likely for users to depend on non-portable implementation details. This is
+### `_LIBCPP_ABI_USE_WRAP_ITER_IN_STD_ARRAY` and `_LIBCPP_ABI_USE_WRAP_ITER_IN_STD_STRING_VIEW`
+
+This changes the `iterator` and `const_iterator` of `array` and `string_view` respectively to reference
+`__wrap_iter` instead, which makes it less likely for users to depend on non-portable implementation details. This is
especially useful because enabling bounded iterators hardening requires code not to make these assumptions.
-``_LIBCPP_ABI_BOUNDED_ITERATORS``, ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_STRING``, ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_VECTOR``, ``_LIBCPP_ABI...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/221513
More information about the llvm-branch-commits
mailing list