[llvm-branch-commits] [libcxx] [libc++][docs] Convert documentation from reST to Markdown (batch 2) (PR #222064)
Reid Kleckner via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Sun Sep 27 09:37:13 PDT 2026
https://github.com/rnk updated https://github.com/llvm/llvm-project/pull/222064
>From c237f0f7aade131c5766f3ae01bb6e21808bb5b0 Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Sat, 5 Sep 2026 04:09:00 +0000
Subject: [PATCH 1/4] [libc++][docs] Convert documentation with rst2myst (batch
2)
---
libcxx/docs/DesignDocs/NoexceptPolicy.md | 10 +-
libcxx/docs/DesignDocs/PSTLIntegration.md | 23 +-
libcxx/docs/DesignDocs/ThreadingSupportAPI.md | 63 +-
libcxx/docs/DesignDocs/TimeZone.md | 90 +-
libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md | 187 ++--
.../UnspecifiedBehaviorRandomization.md | 71 +-
libcxx/docs/DesignDocs/VisibilityMacros.md | 64 +-
libcxx/docs/DesignDocs/WindowsSupport.md | 20 +-
libcxx/docs/Hardening.md | 357 ++++----
libcxx/docs/ImplementationDefinedBehavior.md | 71 +-
libcxx/docs/Modules.md | 468 +++++-----
libcxx/docs/TestingLibcxx.md | 547 ++++++------
libcxx/docs/UserDocumentation.md | 441 +++++-----
libcxx/docs/VendorDocumentation.md | 801 +++++++++---------
libcxx/docs/index.md | 297 +++----
15 files changed, 1692 insertions(+), 1818 deletions(-)
diff --git a/libcxx/docs/DesignDocs/NoexceptPolicy.md b/libcxx/docs/DesignDocs/NoexceptPolicy.md
index 74c8ca406ed847..bfefb48d868970 100644
--- a/libcxx/docs/DesignDocs/NoexceptPolicy.md
+++ b/libcxx/docs/DesignDocs/NoexceptPolicy.md
@@ -1,13 +1,11 @@
-===================
-``noexcept`` Policy
-===================
+# `noexcept` Policy
-Extended applications of ``noexcept``
--------------------------------------
+## Extended applications of `noexcept`
As of version 13 libc++ may mark functions that do not throw (i.e.,
-"Throws: Nothing") as ``noexcept``. This has two primary consequences:
+"Throws: Nothing") as `noexcept`. This has two primary consequences:
first, functions might not report precondition violations by throwing.
Second, user-provided functions, such as custom predicates or custom
traits, which throw might not be propagated up to the caller (unless
specified otherwise by the Standard).
+
diff --git a/libcxx/docs/DesignDocs/PSTLIntegration.md b/libcxx/docs/DesignDocs/PSTLIntegration.md
index e2b9e89f050eb2..111e5e94953a1a 100644
--- a/libcxx/docs/DesignDocs/PSTLIntegration.md
+++ b/libcxx/docs/DesignDocs/PSTLIntegration.md
@@ -1,22 +1,21 @@
-================
-PSTL integration
-================
+# PSTL integration
The PSTL (or Parallel STL) project is quite complex in its current form and does not provide everything that libc++
-requires, for example ``_LIBCPP_HIDE_FROM_ABI`` or similar annotations and including granularized headers. Furthermore,
+requires, for example `_LIBCPP_HIDE_FROM_ABI` or similar annotations and including granularized headers. Furthermore,
the PSTL provides various layers of indirection that make sense in a generic implementation of the parallel algorithms,
but are unnecessarily complex in the context of a single standard library implementation. Because of these drawbacks, we
decided to adopt a modified PSTL in libc++. Specifically, the goals of the modified PSTL are
-- No ``<__pstl_algorithm>`` and similar glue headers -- instead, the implementation files are included directly in
- ``<algorithm>`` and friends.
-- No ``<pstl/internal/algorithm_impl.h>`` and ``<pstl/internal/algorithm_fwd.h>`` headers and friends -- these contain
+- No `<__pstl_algorithm>` and similar glue headers -- instead, the implementation files are included directly in
+ `<algorithm>` and friends.
+- No `<pstl/internal/algorithm_impl.h>` and `<pstl/internal/algorithm_fwd.h>` headers and friends -- these contain
the implementation and forward declarations for internal functions respectively. The implementation lives inside
- ``<__algorithm/pstl_any_of.h>`` and friends, and the forward declarations are not needed inside libc++.
-- No ``<pstl/internal/glue_algorithm_defs.h>`` and ``<pstl/internal/glue_algorithm_impl.h>`` headers and friends --
- these contain the public API. It lives inside ``<__algorithm/pstl_any_of.h>`` and friends instead.
+ `<__algorithm/pstl_any_of.h>` and friends, and the forward declarations are not needed inside libc++.
+- No `<pstl/internal/glue_algorithm_defs.h>` and `<pstl/internal/glue_algorithm_impl.h>` headers and friends --
+ these contain the public API. It lives inside `<__algorithm/pstl_any_of.h>` and friends instead.
- The headers implementing backends are kept with as few changes as possible to make it easier to keep the backends in
sync with the backends from the original PSTL.
-- The configuration headers ``__pstl_config_site.in`` and ``pstl_config.h`` are removed, and any required configuration
- is done inside ``__config_site.in`` and ``__config`` respectively.
+- The configuration headers `__pstl_config_site.in` and `pstl_config.h` are removed, and any required configuration
+ is done inside `__config_site.in` and `__config` respectively.
- libc++-style tests for the public PSTL API
+
diff --git a/libcxx/docs/DesignDocs/ThreadingSupportAPI.md b/libcxx/docs/DesignDocs/ThreadingSupportAPI.md
index d103c49e25952f..88894cb8d1416a 100644
--- a/libcxx/docs/DesignDocs/ThreadingSupportAPI.md
+++ b/libcxx/docs/DesignDocs/ThreadingSupportAPI.md
@@ -1,37 +1,33 @@
-=====================
-Threading Support API
-=====================
+# Threading Support API
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-Overview
-========
+## Overview
Libc++ supports using multiple different threading models and configurations
-to implement the threading parts of libc++, including ``<thread>`` and ``<mutex>``.
+to implement the threading parts of libc++, including `<thread>` and `<mutex>`.
These different models provide entirely different interfaces from each
other. To address this libc++ wraps the underlying threading API in a new and
consistent API, which it uses internally to implement threading primitives.
-The ``<__thread/support.h>`` header is where libc++ defines its internal
+The `<__thread/support.h>` header is where libc++ defines its internal
threading interface. It documents the functions and declarations required
to fullfil the internal threading interface.
-External Threading API and the ``<__external_threading>`` header
-================================================================
+## External Threading API and the `<__external_threading>` header
In order to support vendors with custom threading API's libc++ allows the
entire internal threading interface to be provided by an external,
vendor provided, header.
-When ``_LIBCPP_HAS_THREAD_API_EXTERNAL`` is defined the ``<__thread/support.h>``
-header simply forwards to the ``<__external_threading>`` header (which must exist).
-It is expected that the ``<__external_threading>`` header provide the exact
-interface normally provided by ``<__thread/support.h>``.
+When `_LIBCPP_HAS_THREAD_API_EXTERNAL` is defined the `<__thread/support.h>`
+header simply forwards to the `<__external_threading>` header (which must exist).
+It is expected that the `<__external_threading>` header provide the exact
+interface normally provided by `<__thread/support.h>`.
-External Threading Library
-==========================
+## External Threading Library
libc++ can be compiled with its internal threading API delegating to an external
library. Such a configuration is useful for library vendors who wish to
@@ -39,29 +35,34 @@ distribute a thread-agnostic libc++ library, where the users of the library are
expected to provide the implementation of the libc++ internal threading API.
On a production setting, this would be achieved through a custom
-``<__external_threading>`` header, which declares the libc++ internal threading
+`<__external_threading>` header, which declares the libc++ internal threading
API but leaves out the implementation.
-Threading Configuration Macros
-==============================
+## Threading Configuration Macros
-**_LIBCPP_HAS_THREADS**
- This macro is set to 1 when libc++ is built with threading support. Otherwise
+**\_LIBCPP_HAS_THREADS**
+
+: This macro is set to 1 when libc++ is built with threading support. Otherwise
it is set to 0. It should not be manually defined by the user.
-**_LIBCPP_HAS_THREAD_API_EXTERNAL**
- This macro is defined when libc++ should use the ``<__external_threading>``
+**\_LIBCPP_HAS_THREAD_API_EXTERNAL**
+
+: This macro is defined when libc++ should use the `<__external_threading>`
header to provide the internal threading API. This macro overrides
- ``_LIBCPP_HAS_THREAD_API_PTHREAD``.
+ `_LIBCPP_HAS_THREAD_API_PTHREAD`.
+
+**\_LIBCPP_HAS_THREAD_API_PTHREAD**
-**_LIBCPP_HAS_THREAD_API_PTHREAD**
- This macro is defined when libc++ should use POSIX threads to implement the
+: This macro is defined when libc++ should use POSIX threads to implement the
internal threading API.
-**_LIBCPP_HAS_THREAD_API_C11**
- This macro is defined when libc++ should use C11 threads to implement the
+**\_LIBCPP_HAS_THREAD_API_C11**
+
+: This macro is defined when libc++ should use C11 threads to implement the
internal threading API.
-**_LIBCPP_HAS_THREAD_API_WIN32**
- This macro is defined when libc++ should use Win32 threads to implement the
+**\_LIBCPP_HAS_THREAD_API_WIN32**
+
+: This macro is defined when libc++ should use Win32 threads to implement the
internal threading API.
+
diff --git a/libcxx/docs/DesignDocs/TimeZone.md b/libcxx/docs/DesignDocs/TimeZone.md
index 60adaa45412489..37f47054a96152 100644
--- a/libcxx/docs/DesignDocs/TimeZone.md
+++ b/libcxx/docs/DesignDocs/TimeZone.md
@@ -1,101 +1,92 @@
-=================
-Time Zone Support
-=================
+# Time Zone Support
-Introduction
-============
+## Introduction
-Starting with C++20 the ``<chrono>`` library has support for time zones.
+Starting with C++20 the `<chrono>` library has support for time zones.
These are available in the
-`IANA Time Zone Database <https://data.iana.org/time-zones/tz-link.html>`_.
+[IANA Time Zone Database](https://data.iana.org/time-zones/tz-link.html).
This page describes the design decisions and trade-offs made to implement this
feature. This page contains several links with more information regarding the
contents of the IANA database, this page assumes the reader is familiar with
this information.
-Which version of the Time Zone Database to use
-==============================================
+## Which version of the Time Zone Database to use
The data of the database is available on several platforms in different forms:
- Typically Unix systems ship the database as
- `TZif files <https://www.rfc-editor.org/rfc/rfc8536.html>`_. This format has
- 3 versions and the ``time_zone_link`` information is not always available.
+ [TZif files](https://www.rfc-editor.org/rfc/rfc8536.html). This format has
+ 3 versions and the `time_zone_link` information is not always available.
If available, they are symlinks in the file system.
These files don't provide the database version information. This information
- is needed for the functions ``std::chrono:: remote_version()`` and
- ``std::chrono::reload_tzdb()``.
-
+ is needed for the functions `std::chrono:: remote_version()` and
+ `std::chrono::reload_tzdb()`.
- On several Unix systems the time zone source files are available. These files
are stored in several regions, mainly the continents. This file contains a
large amount of comment with historical information regarding time zones.
The format is documented in the
- `IANA documentation <https://data.iana.org/time-zones/tz-how-to.html>`_
- and in the `man page <https://man7.org/linux/man-pages/man8/zic.8.html>`_ of zic.
+ [IANA documentation](https://data.iana.org/time-zones/tz-how-to.html)
+ and in the [man page](https://man7.org/linux/man-pages/man8/zic.8.html) of zic.
The disadvantage of this version is that at least Linux versions don't have
the database version information. This information is needed for the functions
- ``std::chrono:: remote_version()`` and ``std::chrono::reload_tzdb()``.
-
-- On Linux systems ``tzdata.zi`` is available. This contains the same
+ `std::chrono:: remote_version()` and `std::chrono::reload_tzdb()`.
+- On Linux systems `tzdata.zi` is available. This contains the same
information as the source files but in one file without the comments. This
file uses the same format as the sources, but shortens the names. For example
- ``Rule`` is abbreviated to ``R``. This file contains the database version
+ `Rule` is abbreviated to `R`. This file contains the database version
information.
-The disadvantage of the ``TZif`` format (which is a binary format) is that it's
-not possible to get the proper ``time_zone_link`` information on all platforms.
-The time zone database version number is also missing from ``TZif`` files.
+The disadvantage of the `TZif` format (which is a binary format) is that it's
+not possible to get the proper `time_zone_link` information on all platforms.
+The time zone database version number is also missing from `TZif` files.
Since the time zone database is supposed to contain both these informations,
-``TZif`` files can't be used to create a conforming implementation.
+`TZif` files can't be used to create a conforming implementation.
Since it's easier to parse one file than a set of files we decided
-to use the ``tzdata.zi``. The other benefit is that the ``tzdata.zi`` file
+to use the `tzdata.zi`. The other benefit is that the `tzdata.zi` file
contains the database version information needed for a conforming
implementation.
-The ``tzdata.zi`` file is not available on all platforms as of August 2023, so
+The `tzdata.zi` file is not available on all platforms as of August 2023, so
some vendors will need to make changes to their platform. Most vendors already
ship the database, so they only need to adjust the packaging of their time zone
package to include the files we require. One notable exception is Windows,
where no IANA time zone database is provided at all. However it's possible for
Windows packagers to add these files to their libc++ packages. The IANA
databases can be
-`downloaded <https://data.iana.org/time-zones/releases/>`_.
+[downloaded](https://data.iana.org/time-zones/releases/).
An alternative would be to ship the database with libc++, either as a file or
compiled in the dylib. The text file is about 112 KB. For now libc++ will not
ship this file. If it's hard to get vendors to ship these files we can
reconsider based on that information.
-Leap seconds
-------------
+### Leap seconds
-For the leap seconds libc++ will use the source file ``leap-seconds.list``.
-This file is easier to parse than the ``leapseconds`` file. Both files are
+For the leap seconds libc++ will use the source file `leap-seconds.list`.
+This file is easier to parse than the `leapseconds` file. Both files are
present on Linux, but not always on other platforms. Since these platforms need
-to change their packaging for ``tzdata.zi``, adding two instead of one files
+to change their packaging for `tzdata.zi`, adding two instead of one files
seems a small change.
+## Updating the Time Zone Database
-Updating the Time Zone Database
-===============================
-
-Per `[time.zone.db.remote]/1 <http://eel.is/c++draft/time.zone#db.remote-1>`_
+Per [[time.zone.db.remote]/1](http://eel.is/c++draft/time.zone#db.remote-1)
-.. code-block:: text
-
- The local time zone database is that supplied by the implementation when the
- program first accesses the database, for example via current_zone(). While the
- program is running, the implementation may choose to update the time zone
- database. This update shall not impact the program in any way unless the
- program calls the functions in this subclause. This potentially updated time
- zone database is referred to as the remote time zone database.
+```text
+The local time zone database is that supplied by the implementation when the
+program first accesses the database, for example via current_zone(). While the
+program is running, the implementation may choose to update the time zone
+database. This update shall not impact the program in any way unless the
+program calls the functions in this subclause. This potentially updated time
+zone database is referred to as the remote time zone database.
+```
There is an update mechanism in libc++, however this is not done automatically.
-Invoking the function ``std::chrono::remote_version()`` will parse the version
-information of the ``tzdata.zi`` file and return that information. Similarly,
-``std::chrono::reload_tzdb()`` will parse the ``tzdata.zi`` and
-``leap-seconds.list`` again. This makes it possible to update the database if
+Invoking the function `std::chrono::remote_version()` will parse the version
+information of the `tzdata.zi` file and return that information. Similarly,
+`std::chrono::reload_tzdb()` will parse the `tzdata.zi` and
+`leap-seconds.list` again. This makes it possible to update the database if
needed by the application and gives the user full power over the update policy.
This approach has several advantages:
@@ -107,7 +98,7 @@ This approach has several advantages:
from that task.
- If there is no threading available this polling
becomes more involved. For example, query the file every *x* calls to
- ``std::chrono::get_tzdb()``. This mean calls to ``std::chrono::get_tzdb()``
+ `std::chrono::get_tzdb()`. This mean calls to `std::chrono::get_tzdb()`
would have different performance characteristics.
The small drawback is:
@@ -120,3 +111,4 @@ Another issue with the automatic update is that it may not be considered
Standard compliant, since the Standard uses the wording "This update shall not
impact the program in any way". Using resources could be considered as
impacting the program.
+
diff --git a/libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md b/libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md
index 1af0b34263662c..92df3ba1abe0b2 100644
--- a/libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md
+++ b/libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md
@@ -1,69 +1,55 @@
-=============================================
-Enable std::unique_ptr [[clang::trivial_abi]]
-=============================================
+# Enable std::unique_ptr \[[clang::trivial_abi]\]
-Background
-==========
+## Background
Consider the follow snippets
+```cpp
+void raw_func(Foo* raw_arg) { ... }
+void smart_func(std::unique_ptr<Foo> smart_arg) { ... }
-.. code-block:: cpp
+Foo* raw_ptr_retval() { ... }
+std::unique_ptr<Foo*> smart_ptr_retval() { ... }
+```
- void raw_func(Foo* raw_arg) { ... }
- void smart_func(std::unique_ptr<Foo> smart_arg) { ... }
-
- Foo* raw_ptr_retval() { ... }
- std::unique_ptr<Foo*> smart_ptr_retval() { ... }
-
-
-
-The argument ``raw_arg`` could be passed in a register but ``smart_arg`` could not, due to current
+The argument `raw_arg` could be passed in a register but `smart_arg` could not, due to current
implementation.
-Specifically, in the ``smart_arg`` case, the caller secretly constructs a temporary ``std::unique_ptr``
+Specifically, in the `smart_arg` case, the caller secretly constructs a temporary `std::unique_ptr`
in its stack-frame, and then passes a pointer to it to the callee in a hidden parameter.
-Similarly, the return value from ``smart_ptr_retval`` is secretly allocated in the caller and
+Similarly, the return value from `smart_ptr_retval` is secretly allocated in the caller and
passed as a secret reference to the callee.
+## Goal
-Goal
-===================
+`std::unique_ptr` is passed directly in a register.
-``std::unique_ptr`` is passed directly in a register.
-
-Design
-======
-
-* Annotate the two definitions of ``std::unique_ptr`` with ``clang::trivial_abi`` attribute.
-* Put the attribute behind a flag because this change has potential compilation and runtime breakages.
+## Design
+- Annotate the two definitions of `std::unique_ptr` with `clang::trivial_abi` attribute.
+- Put the attribute behind a flag because this change has potential compilation and runtime breakages.
This comes with some side effects:
-* ``std::unique_ptr`` parameters will now be destroyed by callees, rather than callers.
+- `std::unique_ptr` parameters will now be destroyed by callees, rather than callers.
It is worth noting that destruction by callee is not unique to the use of trivial_abi attribute.
In most Microsoft's ABIs, arguments are always destroyed by the callee.
Consequently, this may change the destruction order for function parameters to an order that is non-conforming to the standard.
For example:
+ ```cpp
+ struct A { ~A(); };
+ struct B { ~B(); };
+ struct C { C(A, unique_ptr<B>, A) {} };
+ C c{{}, make_unique<B>, {}};
+ ```
- .. code-block:: cpp
-
- struct A { ~A(); };
- struct B { ~B(); };
- struct C { C(A, unique_ptr<B>, A) {} };
- C c{{}, make_unique<B>, {}};
+ In a conforming implementation, the destruction order for C::C's parameters is required to be `~A(), ~B(), ~A()` but with this mode enabled, we'll instead see `~B(), ~A(), ~A()`.
+- Reduced code-size.
- In a conforming implementation, the destruction order for C::C's parameters is required to be ``~A(), ~B(), ~A()`` but with this mode enabled, we'll instead see ``~B(), ~A(), ~A()``.
-
-* Reduced code-size.
-
-
-Performance impact
-------------------
+### Performance impact
Google has measured performance improvements of up to 1.6% on some large server macrobenchmarks, and a small reduction in binary sizes.
@@ -72,78 +58,75 @@ This also affects null pointer optimization
Clang's optimizer can now figure out when a `std::unique_ptr` is known to contain *non*-null.
(Actually, this has been a *missed* optimization all along.)
+```cpp
+struct Foo {
+ ~Foo();
+};
+std::unique_ptr<Foo> make_foo();
+void do_nothing(const Foo&)
-.. code-block:: cpp
-
- struct Foo {
- ~Foo();
- };
- std::unique_ptr<Foo> make_foo();
- void do_nothing(const Foo&)
-
- void bar() {
- auto x = make_foo();
- do_nothing(*x);
- }
-
+void bar() {
+ auto x = make_foo();
+ do_nothing(*x);
+}
+```
-With this change, ``~Foo()`` will be called even if ``make_foo`` returns ``unique_ptr<Foo>(nullptr)``.
-The compiler can now assume that ``x.get()`` cannot be null by the end of ``bar()``, because
-the deference of ``x`` would be UB if it were ``nullptr``. (This dereference would not have caused
-a segfault, because no load is generated for dereferencing a pointer to a reference. This can be detected with ``-fsanitize=null``).
+With this change, `~Foo()` will be called even if `make_foo` returns `unique_ptr<Foo>(nullptr)`.
+The compiler can now assume that `x.get()` cannot be null by the end of `bar()`, because
+the deference of `x` would be UB if it were `nullptr`. (This dereference would not have caused
+a segfault, because no load is generated for dereferencing a pointer to a reference. This can be detected with `-fsanitize=null`).
-
-Potential breakages
--------------------
+### Potential breakages
The following breakages were discovered by enabling this change and fixing the resulting issues in a large code base.
- Compilation failures
- - Function definitions now require complete type ``T`` for parameters with type ``std::unique_ptr<T>``. The following code will no longer compile.
-
- .. code-block:: cpp
-
- class Foo;
- void func(std::unique_ptr<Foo> arg) { /* never use `arg` directly */ }
-
- - Fix: Remove forward-declaration of ``Foo`` and include its proper header.
+> - Function definitions now require complete type `T` for parameters with type `std::unique_ptr<T>`. The following code will no longer compile.
+>
+> ```cpp
+> class Foo;
+> void func(std::unique_ptr<Foo> arg) { /* never use `arg` directly */ }
+> ```
+>
+> - Fix: Remove forward-declaration of `Foo` and include its proper header.
- Runtime Failures
- - Lifetime of ``std::unique_ptr<>`` arguments end earlier (at the end of the callee's body, rather than at the end of the full expression containing the call).
-
- .. code-block:: cpp
-
- util::Status run_worker(std::unique_ptr<Foo>);
- void func() {
- std::unique_ptr<Foo> smart_foo = ...;
- Foo* owned_foo = smart_foo.get();
- // Currently, the following would "work" because the argument to run_worker() is deleted at the end of func()
- // With the new calling convention, it will be deleted at the end of run_worker(),
- // making this an access to freed memory.
- owned_foo->Bar(run_worker(std::move(smart_foo)));
- ^
- // <<<Crash expected here
- }
-
- - Lifetime of local *returned* ``std::unique_ptr<>`` ends earlier.
-
- Spot the bug:
-
- .. code-block:: cpp
-
- std::unique_ptr<Foo> create_and_subscribe(Bar* subscriber) {
- auto foo = std::make_unique<Foo>();
- subscriber->sub([&foo] { foo->do_thing();} );
- return foo;
- }
-
- One could point out this is an obvious stack-use-after return bug.
- With the current calling convention, running this code with ASAN enabled, however, would not yield any "issue".
- So is this a bug in ASAN? (Spoiler: No)
-
- This currently would "work" only because the storage for ``foo`` is in the caller's stackframe.
- In other words, ``&foo`` in callee and ``&foo`` in the caller are the same address.
+> - Lifetime of `std::unique_ptr<>` arguments end earlier (at the end of the callee's body, rather than at the end of the full expression containing the call).
+>
+> ```cpp
+> util::Status run_worker(std::unique_ptr<Foo>);
+> void func() {
+> std::unique_ptr<Foo> smart_foo = ...;
+> Foo* owned_foo = smart_foo.get();
+> // Currently, the following would "work" because the argument to run_worker() is deleted at the end of func()
+> // With the new calling convention, it will be deleted at the end of run_worker(),
+> // making this an access to freed memory.
+> owned_foo->Bar(run_worker(std::move(smart_foo)));
+> ^
+> // <<<Crash expected here
+> }
+> ```
+>
+> - Lifetime of local *returned* `std::unique_ptr<>` ends earlier.
+>
+> Spot the bug:
+>
+> > ```cpp
+> > std::unique_ptr<Foo> create_and_subscribe(Bar* subscriber) {
+> > auto foo = std::make_unique<Foo>();
+> > subscriber->sub([&foo] { foo->do_thing();} );
+> > return foo;
+> > }
+> > ```
+>
+> One could point out this is an obvious stack-use-after return bug.
+> With the current calling convention, running this code with ASAN enabled, however, would not yield any "issue".
+> So is this a bug in ASAN? (Spoiler: No)
+>
+> This currently would "work" only because the storage for `foo` is in the caller's stackframe.
+> In other words, `&foo` in callee and `&foo` in the caller are the same address.
ASAN can be used to detect both of these.
+
diff --git a/libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.md b/libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.md
index 70278798ecf630..9a82c8b3c8239f 100644
--- a/libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.md
+++ b/libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.md
@@ -1,65 +1,57 @@
-==================================
-Unspecified Behavior Randomization
-==================================
+# Unspecified Behavior Randomization
-Background
-==========
+## Background
Consider the follow snippet which steadily happens in tests:
-
-.. code-block:: cpp
-
- std::vector<std::pair<int, int>> v(SomeData());
- std::sort(v.begin(), v.end(), [](const auto& lhs, const auto& rhs) {
- return lhs.first < rhs.first;
- });
+```cpp
+std::vector<std::pair<int, int>> v(SomeData());
+std::sort(v.begin(), v.end(), [](const auto& lhs, const auto& rhs) {
+ return lhs.first < rhs.first;
+});
+```
Under this assumption all elements in the vector whose first elements are equal
do not guarantee any order. Unfortunately, this prevents libcxx introducing
other implementations because tests might silently fail and the users might
heavily depend on the stability of implementations.
-Goal
-===================
+## Goal
Provide functionality for randomizing the unspecified behavior so that the users
can test and migrate their components and libcxx can introduce new sorting
algorithms and optimizations to the containers.
For example, as of LLVM version 13, libcxx sorting algorithm takes
-`O(n^2) worst case <https://llvm.org/PR20837>`_ but according
+[O(n^2) worst case](https://llvm.org/PR20837) but according
to the standard its worst case should be `O(n log n)`. This effort helps users
to gradually fix their tests while updating to new faster algorithms.
-Design
-======
+## Design
-* Introduce new macro ``_LIBCPP_DEBUG_RANDOMIZE_UNSPECIFIED_STABILITY`` which should
+- Introduce new macro `_LIBCPP_DEBUG_RANDOMIZE_UNSPECIFIED_STABILITY` which should
be a part of the libcxx config.
-* This macro randomizes the unspecified behavior of algorithms and containers.
+- This macro randomizes the unspecified behavior of algorithms and containers.
For example, for sorting algorithm the input range is shuffled and then
sorted.
-* This macro is off by default because users should enable it only for testing
+- This macro is off by default because users should enable it only for testing
purposes and/or migrations if they happen to libcxx.
-* This feature is only available for C++11 and further because of
- ``std::shuffle`` availability.
-* We may use `ASLR <https://en.wikipedia.org/wiki/Address_space_layout_randomization>`_ or
- static ``std::random_device`` for seeding the random number generator. This
+- This feature is only available for C++11 and further because of
+ `std::shuffle` availability.
+- We may use [ASLR](https://en.wikipedia.org/wiki/Address_space_layout_randomization) or
+ static `std::random_device` for seeding the random number generator. This
guarantees the same stability guarantee within a run but not through different
runs, for example, for tests become flaky and eventually be seen as broken.
For platforms which do not support ASLR, the seed is fixed during build.
-* The users can fix the seed of the random number generator by providing
- ``_LIBCPP_RANDOMIZE_UNSPECIFIED_STABILITY_SEED=seed`` definition.
+- The users can fix the seed of the random number generator by providing
+ `_LIBCPP_RANDOMIZE_UNSPECIFIED_STABILITY_SEED=seed` definition.
This comes with some side effects if any of the flags is on:
-* Computation penalty, we think users are OK with that if they use this feature.
-* Non reproducible results if they don't use the fixed seed.
+- Computation penalty, we think users are OK with that if they use this feature.
+- Non reproducible results if they don't use the fixed seed.
-
-Impact
-------------------
+### Impact
Google has measured couple of thousands of tests to be dependent on the
stability of sorting and selection algorithms. As we also plan on updating
@@ -68,19 +60,18 @@ doing it gradually and sustainably. This is also bad for users to depend on the
unspecified behavior in their tests, this effort helps to turn this flag in
debug mode.
-Potential breakages
--------------------
+### Potential breakages
None if the flag is off. If the flag is on, it may lead to some non-reproducible
results, for example, for caching.
-Currently supported randomization
----------------------------------
+### Currently supported randomization
-* ``std::sort``, there is no guarantee on the order of equal elements
-* ``std::partial_sort``, there is no guarantee on the order of equal elements and
- on the order of the remaining part
-* ``std::nth_element``, there is no guarantee on the order from both sides of the
- partition
+- `std::sort`, there is no guarantee on the order of equal elements
+- `std::partial_sort`, there is no guarantee on the order of equal elements and
+ : on the order of the remaining part
+- `std::nth_element`, there is no guarantee on the order from both sides of the
+ : partition
Patches welcome.
+
diff --git a/libcxx/docs/DesignDocs/VisibilityMacros.md b/libcxx/docs/DesignDocs/VisibilityMacros.md
index db54b35386b19f..8e41ca9d002770 100644
--- a/libcxx/docs/DesignDocs/VisibilityMacros.md
+++ b/libcxx/docs/DesignDocs/VisibilityMacros.md
@@ -1,14 +1,12 @@
-========================
-Symbol Visibility Macros
-========================
+# Symbol Visibility Macros
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-.. _visibility-macros:
+(visibility-macros)=
-Overview
-========
+## Overview
Libc++ uses various "visibility" macros in order to provide a stable ABI in
both the library and the headers. These macros work by changing the
@@ -21,22 +19,24 @@ type_visibility is only supported by Clang, so this doesn't replace
type-specific attributes. The only exception are enums, which GCC always gives
default visibility, thus removing the need for any annotations.
-Visibility Macros
-=================
+## Visibility Macros
-**_LIBCPP_HIDDEN**
- Mark a symbol as hidden so it will not be exported from shared libraries.
+**\_LIBCPP_HIDDEN**
-**_LIBCPP_EXPORTED_FROM_ABI**
- Mark a symbol as being part of our ABI. This includes functions that are part
+: Mark a symbol as hidden so it will not be exported from shared libraries.
+
+**\_LIBCPP_EXPORTED_FROM_ABI**
+
+: Mark a symbol as being part of our ABI. This includes functions that are part
of the libc++ library, type information and other symbols. On Windows,
this macro applies `dllimport`/`dllexport` to the symbol, and on other
platforms it gives the symbol default visibility. This macro should never be
used on class templates. On classes it should only be used if the vtable
lives in the built library.
-**_LIBCPP_OVERRIDABLE_FUNC_VIS**
- Mark a symbol as being exported by the libc++ library, but allow it to be
+**\_LIBCPP_OVERRIDABLE_FUNC_VIS**
+
+: Mark a symbol as being exported by the libc++ library, but allow it to be
overridden locally. On non-Windows, this is equivalent to `_LIBCPP_FUNC_VIS`.
This macro is applied to all `operator new` and `operator delete` overloads.
@@ -47,12 +47,14 @@ Visibility Macros
this macro therefore expands to `__declspec(dllexport)` when building the
library and has an empty definition otherwise.
-**_LIBCPP_HIDE_FROM_ABI**
- Mark a function as not being part of the ABI of any final linked image that
+**\_LIBCPP_HIDE_FROM_ABI**
+
+: Mark a function as not being part of the ABI of any final linked image that
uses it.
-**_LIBCPP_HIDE_FROM_ABI_AFTER_V1**
- Mark a function as being hidden from the ABI (per `_LIBCPP_HIDE_FROM_ABI`)
+**\_LIBCPP_HIDE_FROM_ABI_AFTER_V1**
+
+: Mark a function as being hidden from the ABI (per `_LIBCPP_HIDE_FROM_ABI`)
when libc++ is built with an ABI version after ABI v1. This macro is used to
maintain ABI compatibility for symbols that have been historically exported
by libc++ in v1 of the ABI, but that we don't want to export in the future.
@@ -63,11 +65,12 @@ Visibility Macros
building libc++), the macro always marks symbols as internal so that programs
built using new libc++ headers stop relying on symbols that are removed from
the ABI in a future version. Each time we release a new stable version of the
- ABI, we should create a new _LIBCPP_HIDE_FROM_ABI_AFTER_XXX macro, and we can
+ ABI, we should create a new \_LIBCPP_HIDE_FROM_ABI_AFTER_XXX macro, and we can
use it to start removing symbols from the ABI after that stable version.
-**_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS**
- Mark the member functions, typeinfo, and vtable of the type named in
+**\_LIBCPP_EXTERN_TEMPLATE_TYPE_VIS**
+
+: Mark the member functions, typeinfo, and vtable of the type named in
an extern template declaration as being exported by the libc++ library.
This attribute must be specified on all extern class template declarations.
@@ -86,8 +89,9 @@ Visibility Macros
extern template declaration (i.e. using `_LIBCPP_FUNC_VIS`) is the correct
thing to do for them.
-**_LIBCPP_CLASS_TEMPLATE_INSTANTIATION_VIS**
- Mark the member functions, typeinfo, and vtable of an explicit instantiation
+**\_LIBCPP_CLASS_TEMPLATE_INSTANTIATION_VIS**
+
+: Mark the member functions, typeinfo, and vtable of an explicit instantiation
of a class template as being exported by the libc++ library. This attribute
must be specified on all class template explicit instantiations.
@@ -95,9 +99,9 @@ Visibility Macros
the extern template declaration) as exported on Windows, as discussed above.
On all other platforms, this macro has an empty definition.
-Links
-=====
+## Links
+
+- [[cfe-dev] Visibility in libc++ - 1](http://lists.llvm.org/pipermail/cfe-dev/2013-July/030610.html)
+- [[cfe-dev] Visibility in libc++ - 2](http://lists.llvm.org/pipermail/cfe-dev/2013-August/031195.html)
+- [[libcxx] Visibility fixes for Windows](http://lists.llvm.org/pipermail/cfe-commits/Week-of-Mon-20130805/085461.html)
-* `[cfe-dev] Visibility in libc++ - 1 <http://lists.llvm.org/pipermail/cfe-dev/2013-July/030610.html>`_
-* `[cfe-dev] Visibility in libc++ - 2 <http://lists.llvm.org/pipermail/cfe-dev/2013-August/031195.html>`_
-* `[libcxx] Visibility fixes for Windows <http://lists.llvm.org/pipermail/cfe-commits/Week-of-Mon-20130805/085461.html>`_
diff --git a/libcxx/docs/DesignDocs/WindowsSupport.md b/libcxx/docs/DesignDocs/WindowsSupport.md
index bf79c0e8271312..2ba0ba55c48f40 100644
--- a/libcxx/docs/DesignDocs/WindowsSupport.md
+++ b/libcxx/docs/DesignDocs/WindowsSupport.md
@@ -1,20 +1,16 @@
-===============
-Windows support
-===============
+# Windows support
**This document only applies to the MSVC Mode.**
-Motivation:
------------
+## Motivation:
-Currently libc++ needs to link to the MSVC STL ``msvcprt`` library to implement part of the functionality on Windows. This dependency is counterintuitive since one standard library is depending on another standard library. Our goal is to remove this dependency by implementing the required functionality in libc++ itself.
+Currently libc++ needs to link to the MSVC STL `msvcprt` library to implement part of the functionality on Windows. This dependency is counterintuitive since one standard library is depending on another standard library. Our goal is to remove this dependency by implementing the required functionality in libc++ itself.
-Goals:
-------
+## Goals:
-- ``VCRuntime`` is the underlying ABI layer that libc++ will be using to implement the required functionality for Windows support.
+- `VCRuntime` is the underlying ABI layer that libc++ will be using to implement the required functionality for Windows support.
-Non-Goals:
-----------
+## Non-Goals:
+
+- Interoperability with the MSVC STL in the case where both libraries are linked in the same binary is not a goal. For example if you link both libc++ and the MSVC STL in the same binary, a call to a function that needs to maintain internal state like `std::set_new_handler` from the libc++ side should not be expected to also change the MSVC STL internal state (since they are separate). We will be maintaining our own internal state for such functions, therefore any such functions should only be expected to have an effect on the libc++ side.
-- Interoperability with the MSVC STL in the case where both libraries are linked in the same binary is not a goal. For example if you link both libc++ and the MSVC STL in the same binary, a call to a function that needs to maintain internal state like ``std::set_new_handler`` from the libc++ side should not be expected to also change the MSVC STL internal state (since they are separate). We will be maintaining our own internal state for such functions, therefore any such functions should only be expected to have an effect on the libc++ side.
diff --git a/libcxx/docs/Hardening.md b/libcxx/docs/Hardening.md
index 8178a25e826489..4e50a1240ba09d 100644
--- a/libcxx/docs/Hardening.md
+++ b/libcxx/docs/Hardening.md
@@ -1,16 +1,14 @@
-.. _hardening:
+(hardening)=
-===============
-Hardening Modes
-===============
+# Hardening Modes
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-.. _using-hardening-modes:
+(using-hardening-modes)=
-Using hardening modes
-=====================
+## Using hardening modes
libc++ provides several hardening modes, where each mode enables a set of
assertions that prevent undefined behavior caused by violating preconditions of
@@ -35,14 +33,13 @@ modes are:
We do not commit to a particular level of performance in this mode.
In particular, this mode is *not* intended to be used in production.
-.. note::
+:::{note}
+Enabling hardening has no impact on the ABI.
+:::
- Enabling hardening has no impact on the ABI.
+(notes-for-users)=
-.. _notes-for-users:
-
-Notes for users
----------------
+### Notes for users
As a libc++ user, consult with your vendor to determine the level of hardening
enabled by default.
@@ -50,98 +47,94 @@ enabled by default.
Users wishing for a different hardening level to their vendor default are able
to control the level by passing **one** of the following options to the compiler:
-- ``-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_NONE``
-- ``-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_FAST``
-- ``-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_EXTENSIVE``
-- ``-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_DEBUG``
-
-.. warning::
-
- The exact numeric values of these macros are unspecified and users should not
- rely on them (e.g. expect the values to be sorted in any way).
-
-.. warning::
+- `-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_NONE`
+- `-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_FAST`
+- `-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_EXTENSIVE`
+- `-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_DEBUG`
- If you would prefer to override the hardening level on a per-translation-unit
- basis, you must do so **before** including any headers to avoid `ODR issues`_.
+:::{warning}
+The exact numeric values of these macros are unspecified and users should not
+rely on them (e.g. expect the values to be sorted in any way).
+:::
-.. _`ODR issues`: https://en.cppreference.com/w/cpp/language/definition#:~:text=is%20ill%2Dformed.-,One%20Definition%20Rule,-Only%20one%20definition
+:::{warning}
+If you would prefer to override the hardening level on a per-translation-unit
+basis, you must do so **before** including any headers to avoid [ODR issues][odr issues].
+:::
-.. note::
-
- Since the static and shared library components of libc++ are built by the
- vendor, setting this macro will have no impact on the hardening mode for the
- pre-built components. Most libc++ code is header-based, so a user-provided
- value for ``_LIBCPP_HARDENING_MODE`` will be mostly respected.
+:::{note}
+Since the static and shared library components of libc++ are built by the
+vendor, setting this macro will have no impact on the hardening mode for the
+pre-built components. Most libc++ code is header-based, so a user-provided
+value for `_LIBCPP_HARDENING_MODE` will be mostly respected.
+:::
In some cases, users might want to override the assertion semantic used by the
library. This can be done similarly to setting the hardening mode; please refer
-to the :ref:`relevant section <assertion-semantics>`.
+to the {ref}`relevant section <assertion-semantics>`.
-Notes for vendors
------------------
+### Notes for vendors
Vendors can set the default hardening mode by providing
-``LIBCXX_HARDENING_MODE`` as a configuration option, with the possible values of
-``none``, ``fast``, ``extensive`` and ``debug``. The default value is ``none``
+`LIBCXX_HARDENING_MODE` as a configuration option, with the possible values of
+`none`, `fast`, `extensive` and `debug`. The default value is `none`
which doesn't enable any hardening checks (this mode is sometimes called the
-``unchecked`` mode).
+`unchecked` mode).
This option controls both the hardening mode that the precompiled library is
built with and the default hardening mode that users will build with. If set to
-``none``, the precompiled library will not contain any assertions, and user code
+`none`, the precompiled library will not contain any assertions, and user code
will default to building without assertions.
Vendors can also override the way the program is terminated when an assertion
-fails by :ref:`providing a custom header <override-assertion-handler>`.
+fails by {ref}`providing a custom header <override-assertion-handler>`.
-Assertion categories
-====================
+## Assertion categories
Inside the library, individual assertions are grouped into different
*categories*. Each hardening mode enables a different set of assertion
categories; categories provide an additional layer of abstraction that makes it
easier to reason about the high-level semantics of a hardening mode.
-.. note::
-
- Users are not intended to interact with these categories directly -- the
- categories are considered internal to the library and subject to change.
+:::{note}
+Users are not intended to interact with these categories directly -- the
+categories are considered internal to the library and subject to change.
+:::
-- ``valid-element-access`` -- checks that any attempts to access a container
+- `valid-element-access` -- checks that any attempts to access a container
element, whether through the container object or through an iterator, are
valid and do not attempt to go out of bounds or otherwise access
a non-existent element. This also includes operations that set up an imminent
invalid access (e.g. incrementing an end iterator). For iterator checks to
work, bounded iterators must be enabled in the ABI. Types like
- ``std::optional`` and ``std::function`` are considered containers (with at
+ `std::optional` and `std::function` are considered containers (with at
most one element) for the purposes of this check.
-- ``valid-input-range`` -- checks that ranges (whether expressed as an iterator
+- `valid-input-range` -- checks that ranges (whether expressed as an iterator
pair, an iterator and a sentinel, an iterator and a count, or
- a ``std::range``) given as input to library functions are valid:
- - the sentinel is reachable from the begin iterator;
- - TODO(hardening): both iterators refer to the same container.
+ a `std::range`) given as input to library functions are valid:
+ \- the sentinel is reachable from the begin iterator;
+ \- TODO(hardening): both iterators refer to the same container.
("input" here refers to "an input given to an algorithm", not to an iterator
category)
Violating assertions in this category leads to an out-of-bounds access.
-- ``non-null`` -- checks that the pointer being dereferenced is not null. On
+- `non-null` -- checks that the pointer being dereferenced is not null. On
most modern platforms, the zero address does not refer to an actual location
in memory, so a null pointer dereference would not compromise the memory
security of a program (however, it is still undefined behavior that can result
in strange errors due to compiler optimizations).
-- ``non-overlapping-ranges`` -- for functions that take several ranges as
+- `non-overlapping-ranges` -- for functions that take several ranges as
arguments, checks that those ranges do not overlap.
-- ``valid-deallocation`` -- checks that an attempt to deallocate memory is valid
+- `valid-deallocation` -- checks that an attempt to deallocate memory is valid
(e.g. the given object was allocated by the given allocator). Violating this
category typically results in a memory leak.
-- ``valid-external-api-call`` -- checks that a call to an external API doesn't
+- `valid-external-api-call` -- checks that a call to an external API doesn't
fail in an unexpected manner. This includes triggering documented cases of
undefined behavior in an external library (like attempting to unlock an
unlocked mutex in pthreads). Any API external to the library falls under this
@@ -149,36 +142,36 @@ easier to reason about the high-level semantics of a hardening mode.
these failures to compromise memory safety or otherwise create an immediate
security issue.
-- ``compatible-allocator`` -- checks any operations that exchange nodes between
+- `compatible-allocator` -- checks any operations that exchange nodes between
containers to make sure the containers have compatible allocators.
-- ``argument-within-domain`` -- checks that the given argument is within the
+- `argument-within-domain` -- checks that the given argument is within the
domain of valid arguments for the function. Violating this typically produces
- an incorrect result (e.g. ``std::clamp`` returns the original value without
+ an incorrect result (e.g. `std::clamp` returns the original value without
clamping it due to incorrect functors) or puts an object into an invalid state
(e.g. a string view where only a subset of elements is accessible). This
category is for assertions violating which doesn't cause any immediate issues
in the library -- whatever the consequences are, they will happen in the user
code.
-- ``pedantic`` -- checks preconditions that are imposed by the C++ standard,
+- `pedantic` -- checks preconditions that are imposed by the C++ standard,
but violating which happens to be benign in libc++.
-- ``semantic-requirement`` -- checks that the given argument satisfies the
+- `semantic-requirement` -- checks that the given argument satisfies the
semantic requirements imposed by the C++ standard. Typically, there is no
simple way to completely prove that a semantic requirement is satisfied;
thus, this would often be a heuristic check and it might be quite expensive.
-- ``internal`` -- checks that internal invariants of the library hold. These
+- `internal` -- checks that internal invariants of the library hold. These
assertions don't depend on user input.
-- ``uncategorized`` -- for assertions that haven't been properly classified yet.
+- `uncategorized` -- for assertions that haven't been properly classified yet.
This category is an escape hatch used for some existing assertions in the
library; all new code should have its assertions properly classified.
-Mapping between the hardening modes and the assertion categories
-================================================================
+## Mapping between the hardening modes and the assertion categories
+```{eval-rst}
.. list-table::
:header-rows: 1
:widths: auto
@@ -235,128 +228,125 @@ Mapping between the hardening modes and the assertion categories
- ❌
- ✅
- ✅
+```
-.. note::
-
- At the moment, each subsequent hardening mode is a strict superset of the
- previous one (in other words, each subsequent mode only enables additional
- assertion categories without disabling any), but this won't necessarily be
- true for any hardening modes that might be added in the future.
+:::{note}
+At the moment, each subsequent hardening mode is a strict superset of the
+previous one (in other words, each subsequent mode only enables additional
+assertion categories without disabling any), but this won't necessarily be
+true for any hardening modes that might be added in the future.
+:::
-.. note::
+:::{note}
+The categories enabled by each mode are subject to change. Users should not
+rely on the precise assertions enabled by a mode at a given point in time.
+However, the library does guarantee to keep the hardening modes stable and
+to fulfill the semantics documented here.
+:::
- The categories enabled by each mode are subject to change. Users should not
- rely on the precise assertions enabled by a mode at a given point in time.
- However, the library does guarantee to keep the hardening modes stable and
- to fulfill the semantics documented here.
+## Hardening assertion failure
-Hardening assertion failure
-===========================
-
-In production modes (``fast`` and ``extensive``), a hardening assertion failure
-immediately ``_traps <https://clang.llvm.org/docs/LanguageExtensions.html#builtin-verbose-trap>``
+In production modes (`fast` and `extensive`), a hardening assertion failure
+immediately `_traps <https://clang.llvm.org/docs/LanguageExtensions.html#builtin-verbose-trap>`
the program. This is the safest approach that also minimizes the code size
penalty as the failure handler maps to a single instruction. The downside is
that the failure provides no additional details other than the stack trace
(which might also be affected by optimizations).
-In the ``debug`` mode, an assertion failure terminates the program in an
+In the `debug` mode, an assertion failure terminates the program in an
unspecified manner and also outputs the associated error message to the error
output. This is less secure and increases the size of the binary (among other
things, it has to store the error message strings) but makes the failure easier
to debug. It also allows testing the error messages in our test suite.
-This default behavior can be customized by users via :ref:`assertion semantics
+This default behavior can be customized by users via {ref}`assertion semantics
<assertion-semantics>`; it can also be completely overridden by vendors by
-providing a :ref:`custom assertion failure handler
+providing a {ref}`custom assertion failure handler
<override-assertion-handler>`.
-.. _assertion-semantics:
-
-Assertion semantics
--------------------
-
-.. warning::
+(assertion-semantics)=
- Assertion semantics are currently an experimental feature.
+### Assertion semantics
-.. note::
+:::{warning}
+Assertion semantics are currently an experimental feature.
+:::
- Assertion semantics are not available in the C++03 mode.
+:::{note}
+Assertion semantics are not available in the C++03 mode.
+:::
What happens when an assertion fails depends on the assertion semantic being
used. Four assertion semantics are available, based on C++26 Contracts
evaluation semantics:
-- ``ignore`` evaluates the assertion but has no effect if it fails (note that it
- differs from the Contracts ``ignore`` semantic which would not evaluate
+- `ignore` evaluates the assertion but has no effect if it fails (note that it
+ differs from the Contracts `ignore` semantic which would not evaluate
the assertion at all);
-- ``observe`` logs an error (indicating, if possible on the platform, that the
+- `observe` logs an error (indicating, if possible on the platform, that the
error is fatal) but continues execution;
-- ``quick-enforce`` terminates the program as fast as possible via a trap
- instruction. It is the default semantic for the production modes (``fast`` and
- ``extensive``);
-- ``enforce`` logs an error and then terminates the program. It is the default
- semantic for the ``debug`` mode.
+- `quick-enforce` terminates the program as fast as possible via a trap
+ instruction. It is the default semantic for the production modes (`fast` and
+ `extensive`);
+- `enforce` logs an error and then terminates the program. It is the default
+ semantic for the `debug` mode.
Notes:
- Continuing execution after a hardening check fails results in undefined
- behavior; the ``observe`` semantic is meant to make adopting hardening easier
+ behavior; the `observe` semantic is meant to make adopting hardening easier
but should not be used outside of the adoption period;
- C++26 wording for Library Hardening precludes a conforming Hardened
- implementation from using the Contracts ``ignore`` semantic when evaluating
+ implementation from using the Contracts `ignore` semantic when evaluating
hardened preconditions in the Library. Libc++ allows using this semantic for
- hardened preconditions, but please be aware that using ``ignore`` does not
+ hardened preconditions, but please be aware that using `ignore` does not
produce a conforming "Hardened" implementation, unlike the other semantics
above.
The default assertion semantics are as follows:
-- ``fast``: ``quick-enforce``;
-- ``extensive``: ``quick-enforce``;
-- ``debug``: ``enforce``.
+- `fast`: `quick-enforce`;
+- `extensive`: `quick-enforce`;
+- `debug`: `enforce`.
The default assertion semantics can be overridden by passing **one** of the
following options to the compiler:
-- ``-D_LIBCPP_ASSERTION_SEMANTIC=_LIBCPP_ASSERTION_SEMANTIC_IGNORE``
-- ``-D_LIBCPP_ASSERTION_SEMANTIC=_LIBCPP_ASSERTION_SEMANTIC_OBSERVE``
-- ``-D_LIBCPP_ASSERTION_SEMANTIC=_LIBCPP_ASSERTION_SEMANTIC_QUICK_ENFORCE``
-- ``-D_LIBCPP_ASSERTION_SEMANTIC=_LIBCPP_ASSERTION_SEMANTIC_ENFORCE``
+- `-D_LIBCPP_ASSERTION_SEMANTIC=_LIBCPP_ASSERTION_SEMANTIC_IGNORE`
+- `-D_LIBCPP_ASSERTION_SEMANTIC=_LIBCPP_ASSERTION_SEMANTIC_OBSERVE`
+- `-D_LIBCPP_ASSERTION_SEMANTIC=_LIBCPP_ASSERTION_SEMANTIC_QUICK_ENFORCE`
+- `-D_LIBCPP_ASSERTION_SEMANTIC=_LIBCPP_ASSERTION_SEMANTIC_ENFORCE`
-All the :ref:`same notes <notes-for-users>` apply to setting this macro as for
-setting ``_LIBCPP_HARDENING_MODE``.
+All the {ref}`same notes <notes-for-users>` apply to setting this macro as for
+setting `_LIBCPP_HARDENING_MODE`.
-Notes for vendors
------------------
+### Notes for vendors
Similarly to hardening modes, vendors can set the default assertion semantic by
-providing ``LIBCXX_ASSERTION_SEMANTIC`` as a configuration option, with the
-possible values of ``hardening_dependent``, ``ignore``, ``observe``,
-``quick_enforce`` and ``enforce``. The default value is ``hardening_dependent``
+providing `LIBCXX_ASSERTION_SEMANTIC` as a configuration option, with the
+possible values of `hardening_dependent`, `ignore`, `observe`,
+`quick_enforce` and `enforce`. The default value is `hardening_dependent`
which is a special value that instructs the library to select the semantic based
on the hardening mode in effect (the mapping is described in
-:ref:`the main section on assertion semantics <assertion-semantics>`).
+{ref}`the main section on assertion semantics <assertion-semantics>`).
This option controls both the assertion semantic that the precompiled library is
built with and the default assertion semantic that users will build with.
-.. _override-assertion-handler:
+(override-assertion-handler)=
-Overriding the assertion failure handler
-----------------------------------------
+### Overriding the assertion failure handler
Vendors can override the default assertion handler mechanism by following these
steps:
- create a header file that provides a definition of a macro called
- ``_LIBCPP_ASSERTION_HANDLER``. The macro will be invoked when a hardening
+ `_LIBCPP_ASSERTION_HANDLER`. The macro will be invoked when a hardening
assertion fails, with a single parameter containing a null-terminated string
with the error message.
- when configuring the library, provide the path to custom header (relative to
the root of the repository) via the CMake variable
- ``LIBCXX_ASSERTION_HANDLER_FILE``.
+ `LIBCXX_ASSERTION_HANDLER_FILE`.
Note that almost all libc++ headers include the assertion handler header which
means it should not include anything non-trivial from the standard library to
@@ -370,8 +360,7 @@ what's right on their platform for their users -- a vendor who wishes to provide
this capability is free to do so, e.g. by declaring the assertion handler as an
overridable function.
-ABI
-===
+## ABI
Setting a hardening mode does **not** affect the ABI. Each mode uses the subset
of checks available in the current ABI configuration which is determined by the
@@ -382,21 +371,20 @@ the combination of the selected hardening mode and the hardening-related ABI
options. Some checks require changing the ABI from the "default" to store
additional information in the library classes -- e.g. checking whether an
iterator is valid upon dereference generally requires storing data about bounds
-inside the iterator object. Using ``std::span`` as an example, setting the
-hardening mode to ``fast`` will always enable the ``valid-element-access``
-checks when accessing elements via a ``std::span`` object, but whether
-dereferencing a ``std::span`` iterator does the equivalent check depends on the
+inside the iterator object. Using `std::span` as an example, setting the
+hardening mode to `fast` will always enable the `valid-element-access`
+checks when accessing elements via a `std::span` object, but whether
+dereferencing a `std::span` iterator does the equivalent check depends on the
ABI configuration.
-ABI options
------------
+### ABI options
Vendors can use some ABI options at CMake configuration time (when building libc++
itself) to enable additional hardening checks. This is done by passing these
-macros as ``-DLIBCXX_ABI_DEFINES="_LIBCPP_ABI_FOO;_LIBCPP_ABI_BAR;etc"`` at
+macros as `-DLIBCXX_ABI_DEFINES="_LIBCPP_ABI_FOO;_LIBCPP_ABI_BAR;etc"` at
CMake configuration time. The available options are:
-- ``_LIBCPP_ABI_BOUNDED_ITERATORS`` -- changes the iterator type of select
+- `_LIBCPP_ABI_BOUNDED_ITERATORS` -- changes the iterator type of select
containers (see below) to a bounded iterator that keeps track of whether it's
within the bounds of the original container and asserts valid bounds on every
dereference.
@@ -405,78 +393,79 @@ CMake configuration time. The available options are:
Supported containers:
- - ``span``;
- - ``string_view``.
+ - `span`;
+ - `string_view`.
-- ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_STRING`` -- changes the iterator type of
- ``basic_string`` to a bounded iterator that keeps track of whether it's within
+- `_LIBCPP_ABI_BOUNDED_ITERATORS_IN_STRING` -- changes the iterator type of
+ `basic_string` to a bounded iterator that keeps track of whether it's within
the bounds of the original container and asserts it on every dereference and
when performing iterator arithmetics.
- ABI impact: changes the iterator type of ``basic_string`` and its
- specializations, such as ``string`` and ``wstring``.
+ ABI impact: changes the iterator type of `basic_string` and its
+ specializations, such as `string` and `wstring`.
-- ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_VECTOR`` -- changes the iterator type of
- ``vector`` to a bounded iterator that keeps track of whether it's within the
+- `_LIBCPP_ABI_BOUNDED_ITERATORS_IN_VECTOR` -- changes the iterator type of
+ `vector` to a bounded iterator that keeps track of whether it's within the
bounds of the original container and asserts it on every dereference and when
performing iterator arithmetics. Note: this doesn't yet affect
- ``vector<bool>``.
+ `vector<bool>`.
- ABI impact: changes the iterator type of ``vector`` (except ``vector<bool>``).
+ ABI impact: changes the iterator type of `vector` (except `vector<bool>`).
-- ``_LIBCPP_ABI_BOUNDED_UNIQUE_PTR`` -- tracks the bounds of the array stored inside
- a ``std::unique_ptr<T[]>``, allowing it to trap when accessed out-of-bounds. This
- requires the ``std::unique_ptr`` to be created using an API like ``std::make_unique``
- or ``std::make_unique_for_overwrite``, otherwise the bounds information is not available
+- `_LIBCPP_ABI_BOUNDED_UNIQUE_PTR` -- tracks the bounds of the array stored inside
+ a `std::unique_ptr<T[]>`, allowing it to trap when accessed out-of-bounds. This
+ requires the `std::unique_ptr` to be created using an API like `std::make_unique`
+ or `std::make_unique_for_overwrite`, otherwise the bounds information is not available
to the library.
- ABI impact: changes the layout of ``std::unique_ptr<T[]>``, and the representation
- of a few library types that use ``std::unique_ptr`` internally, such as
- the unordered containers.
+ ABI impact: changes the layout of `std::unique_ptr<T[]>`, and the representation
-- ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_STD_ARRAY`` -- changes the iterator type of ``std::array`` to a
+ : of a few library types that use `std::unique_ptr` internally, such as
+ the unordered containers.
+
+- `_LIBCPP_ABI_BOUNDED_ITERATORS_IN_STD_ARRAY` -- changes the iterator type of `std::array` to a
bounded iterator that keeps track of whether it's within the bounds of the container and asserts it
on every dereference and when performing iterator arithmetic.
- ABI impact: changes the iterator type of ``std::array``, its size and its layout.
+ ABI impact: changes the iterator type of `std::array`, its size and its layout.
-- ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_OPTIONAL`` -- changes the iterator type of ``std::optional`` to a
+- `_LIBCPP_ABI_BOUNDED_ITERATORS_IN_OPTIONAL` -- changes the iterator type of `std::optional` to a
bounded iterator that keeps track of whether it's within the bounds of its container and asserts it
on every dereference and when performing iterator arithmetic.
- ABI impact: changes the iterator type of ``std::optional``.
+ ABI impact: changes the iterator type of `std::optional`.
-ABI tags
---------
+### ABI tags
We use ABI tags to allow translation units built with different hardening modes
to interact with each other without causing ODR violations. Knowing how
hardening modes are encoded into the ABI tags might be useful to examine
a binary and determine whether it was built with hardening enabled.
-.. warning::
- We don't commit to the encoding scheme used by the ABI tags being stable
- between different releases of libc++. The tags themselves are never stable, by
- design -- new releases increase the version number. The following describes
- the state of the latest release and is for informational purposes only.
+:::{warning}
+We don't commit to the encoding scheme used by the ABI tags being stable
+between different releases of libc++. The tags themselves are never stable, by
+design -- new releases increase the version number. The following describes
+the state of the latest release and is for informational purposes only.
+:::
The first character of an ABI tag encodes the hardening mode:
-- ``f`` -- [f]ast mode;
-- ``s`` -- extensive ("[s]afe") mode;
-- ``d`` -- [d]ebug mode;
-- ``n`` -- [n]one mode.
+- `f` -- [f]ast mode;
+- `s` -- extensive ("[s]afe") mode;
+- `d` -- [d]ebug mode;
+- `n` -- [n]one mode.
The second character of an ABI tag encodes the assertion semantic:
-- ``i`` -- [i]gnore semantic;
-- ``o`` -- [o]bserve semantic;
-- ``q`` -- [q]uick-enforce semantic;
-- ``e`` -- [e]nforce semantic.
+- `i` -- [i]gnore semantic;
+- `o` -- [o]bserve semantic;
+- `q` -- [q]uick-enforce semantic;
+- `e` -- [e]nforce semantic.
-Hardened containers status
-==========================
+## Hardened containers status
+```{eval-rst}
.. list-table::
:header-rows: 1
:widths: auto
@@ -556,20 +545,22 @@ Hardened containers status
* - ``bitset``
- ✅
- N/A
+```
-Note: for ``vector`` and ``string``, the iterator does not check for
+Note: for `vector` and `string`, the iterator does not check for
invalidation (accesses made via an invalidated iterator still lead to undefined
behavior)
-Note: ``vector<bool>`` iterator is not currently hardened.
+Note: `vector<bool>` iterator is not currently hardened.
-Testing
-=======
+## Testing
-Please see :ref:`Testing documentation <testing-hardening-assertions>`.
+Please see {ref}`Testing documentation <testing-hardening-assertions>`.
-Further reading
-===============
+## Further reading
-- `Hardening RFC <https://discourse.llvm.org/t/rfc-hardening-in-libc/73925>`_:
+- [Hardening RFC](https://discourse.llvm.org/t/rfc-hardening-in-libc/73925):
contains some of the design rationale.
+
+[odr issues]: https://en.cppreference.com/w/cpp/language/definition#:~:text=is%20ill%2Dformed.-,One%20Definition%20Rule,-Only%20one%20definition
+
diff --git a/libcxx/docs/ImplementationDefinedBehavior.md b/libcxx/docs/ImplementationDefinedBehavior.md
index 97ea96a5063631..355b978a393130 100644
--- a/libcxx/docs/ImplementationDefinedBehavior.md
+++ b/libcxx/docs/ImplementationDefinedBehavior.md
@@ -1,84 +1,69 @@
-.. _implementation-defined-behavior:
+(implementation-defined-behavior)=
-===============================
-Implementation-defined behavior
-===============================
+# Implementation-defined behavior
This document contains the implementation details of the implementation-defined behavior in libc++.
The C++ standard mandates that implementation-defined behavior is documented.
-.. note:
- This page is far from complete.
+% note:
+% This page is far from complete.
+## Implementation-defined behavior
-Implementation-defined behavior
-===============================
-
-Updating the Time Zone Database
--------------------------------
+### Updating the Time Zone Database
The C++ standard allows implementations to automatically update the
*remote time zone database*. Libc++ opts not to do that. Instead calling
- - ``std::chrono::remote_version()`` will update the version information of the
- *remote time zone database*,
- - ``std::chrono::reload_tzdb()``, if needed, will update the entire
- *remote time zone database*.
+> - `std::chrono::remote_version()` will update the version information of the
+> *remote time zone database*,
+> - `std::chrono::reload_tzdb()`, if needed, will update the entire
+> *remote time zone database*.
This offers a way for users to update the *remote time zone database* and
give them full control over the process.
-
-`[ostream.formatted.print]/3 <http://eel.is/c++draft/ostream.formatted.print#3>`_ A terminal capable of displaying Unicode
---------------------------------------------------------------------------------------------------------------------------
+### [[ostream.formatted.print]/3](http://eel.is/c++draft/ostream.formatted.print#3) A terminal capable of displaying Unicode
The C++ standard specifies that the manner in which a stream is determined to refer
to a terminal capable of displaying Unicode is implementation-defined. This is
-used for ``std::print`` and similar functions taking an ``ostream&`` argument.
+used for `std::print` and similar functions taking an `ostream&` argument.
Libc++ determines that a stream is Unicode-capable terminal by:
-* First it determines whether the stream's ``rdbuf()`` has an underlying
- ``FILE*``. This is ``true`` in the following cases:
+- First it determines whether the stream's `rdbuf()` has an underlying
+ `FILE*`. This is `true` in the following cases:
- * The stream is ``std::cout``, ``std::cerr``, or ``std::clog``.
+ - The stream is `std::cout`, `std::cerr`, or `std::clog`.
+ - A `std::basic_filebuf<CharT, Traits>` derived from `std::filebuf`.
- * A ``std::basic_filebuf<CharT, Traits>`` derived from ``std::filebuf``.
+- The way to determine whether this `FILE*` refers to a terminal capable of
+ displaying Unicode is the same as specified for [void vprint_unicode(FILE\*
+ stream, string_view fmt, format_args args);](http://eel.is/c++draft/print.fun#7). This function is used for other
+ `std::print` overloads that don't take an `ostream&` argument.
-* The way to determine whether this ``FILE*`` refers to a terminal capable of
- displaying Unicode is the same as specified for `void vprint_unicode(FILE*
- stream, string_view fmt, format_args args);
- <http://eel.is/c++draft/print.fun#7>`_. This function is used for other
- ``std::print`` overloads that don't take an ``ostream&`` argument.
-
-`[sf.cmath] <https://wg21.link/sf.cmath>`_ Mathematical Special Functions: Large indices
-----------------------------------------------------------------------------------------
+### [[sf.cmath]](https://wg21.link/sf.cmath) Mathematical Special Functions: Large indices
Most functions within the Mathematical Special Functions section contain integral indices.
The C++ standard specifies the result for larger indices as implementation-defined.
Libc++ pursuits reasonable results by choosing the same formulas as for indices below that threshold.
E.g.,
-- ``std::hermite(unsigned n, T x)`` for ``n >= 128``
-
+- `std::hermite(unsigned n, T x)` for `n >= 128`
-`[filebuf.virtuals] <https://eel.is/c++draft/filebuf.virtual>`_ Effect of calling ``basic_filebuf::setbuf`` with nonzero arguments
-----------------------------------------------------------------------------------------------------------------------------------
+### [[filebuf.virtuals]](https://eel.is/c++draft/filebuf.virtual) Effect of calling `basic_filebuf::setbuf` with nonzero arguments
Libc++ uses the provided buffer as the underlying buffer for input and output, and
does not discard that buffer even when the stream is closed.
-
-`[stringbuf.cons] <http://eel.is/c++draft/stringbuf.cons>`_ Whether sequence pointers are initialized to null pointers
-----------------------------------------------------------------------------------------------------------------------
+### [[stringbuf.cons]](http://eel.is/c++draft/stringbuf.cons) Whether sequence pointers are initialized to null pointers
Libc++ does not initialize the pointers to null pointers. It resizes the buffer
to its capacity and uses that size. This means the SSO buffer of
-``std::string`` is used as initial output buffer.
-
+`std::string` is used as initial output buffer.
-Listed in the index of implementation-defined behavior
-======================================================
+## Listed in the index of implementation-defined behavior
The order of the entries matches the entries in the
-`draft of the Standard <http://eel.is/c++draft/impldefindex>`_.
+[draft of the Standard](http://eel.is/c++draft/impldefindex).
+
diff --git a/libcxx/docs/Modules.md b/libcxx/docs/Modules.md
index c8f3e6194fd84d..38ddd34be8611b 100644
--- a/libcxx/docs/Modules.md
+++ b/libcxx/docs/Modules.md
@@ -1,226 +1,226 @@
-.. _ModulesInLibcxx:
+(modulesinlibcxx)=
-=================
-Modules in libc++
-=================
+# Modules in libc++
-.. warning:: Modules are an experimental feature. It has additional build
- requirements and not all libc++ configurations are supported yet.
+:::{warning}
+Modules are an experimental feature. It has additional build
+requirements and not all libc++ configurations are supported yet.
- The work is still in an early development state and not
- considered stable nor complete
+The work is still in an early development state and not
+considered stable nor complete
+:::
This page contains information regarding C++23 module support in libc++.
There are two kinds of modules available in Clang
- * `Clang specific modules <https://clang.llvm.org/docs/Modules.html>`_
- * `C++ modules <https://clang.llvm.org/docs/StandardCPlusPlusModules.html>`_
+> - [Clang specific modules](https://clang.llvm.org/docs/Modules.html)
+> - [C++ modules](https://clang.llvm.org/docs/StandardCPlusPlusModules.html)
This page mainly discusses the C++ modules. In C++20 there are also header units,
these are not part of this document.
-Overview
-========
+## Overview
-The module sources are stored in ``.cppm`` files. Modules need to be available
-as BMIs, which are ``.pcm`` files for Clang. BMIs are not portable, they depend
+The module sources are stored in `.cppm` files. Modules need to be available
+as BMIs, which are `.pcm` files for Clang. BMIs are not portable, they depend
on the compiler and the compilation flags used. Therefore there needs to be a
-way to distribute the ``.cppm`` files to the user and offer a way for them to
-build and use the ``.pcm`` files. It is expected this will be done by build
+way to distribute the `.cppm` files to the user and offer a way for them to
+build and use the `.pcm` files. It is expected this will be done by build
systems in the future. To aid early adaptor and build system vendors libc++
currently ships a CMake project to aid building modules.
-.. note:: This CMake file is intended to be a temporary solution and will
- be removed in the future. The timeline for the removal depends
- on the availability of build systems with proper module support.
-
-What works
-~~~~~~~~~~
-
- * Building BMIs
- * Running tests using the ``std`` and ``std.compat`` module
- * Using the ``std`` and ``std.compat`` module in external projects
- * The following "parts disabled" configuration options are supported
-
- * ``LIBCXX_ENABLE_LOCALIZATION``
- * ``LIBCXX_ENABLE_WIDE_CHARACTERS``
- * ``LIBCXX_ENABLE_THREADS``
- * ``LIBCXX_ENABLE_FILESYSTEM``
- * ``LIBCXX_ENABLE_RANDOM_DEVICE``
- * ``LIBCXX_ENABLE_UNICODE``
- * ``LIBCXX_ENABLE_EXCEPTIONS`` [#note-no-windows]_
-
- * A C++20 based extension
-
-.. note::
-
- .. [#note-no-windows] This configuration will probably not work on Windows
- due to hard-coded compilation flags.
-
-Some of the current limitations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- * There is no official build system support, libc++ has experimental CMake support
- * Requires CMake 3.26 for C++20 support
- * Requires CMake 3.26 for C++23 support
- * Requires CMake 3.27 for C++26 support
- * Requires Ninja 1.11
- * Requires Clang 17
- * The path to the compiler may not be a symlink, ``clang-scan-deps`` does
- not handle that case properly
- * Libc++ is not tested with modules instead of headers
- * Clang:
- * Including headers after importing the ``std`` module may fail. This is
- hard to solve and there is a work-around by first including all headers
- `bug report <https://llvm.org/PR61465>`__.
-
-Blockers
-~~~~~~~~
-
- * libc++
-
- * Currently the tests only test with modules enabled, but do not import
- modules instead of headers. When converting tests to using modules there
- are still failures. These are under investigation.
-
- * It has not been determined how to fully test libc++ with modules instead
- of headers.
-
- * Clang
-
- * Some concepts do not work properly `bug report <https://llvm.org/PR61465>`__.
-
-
-Using in external projects
-==========================
+:::{note}
+This CMake file is intended to be a temporary solution and will
+be removed in the future. The timeline for the removal depends
+on the availability of build systems with proper module support.
+:::
+
+### What works
+
+> - Building BMIs
+>
+> - Running tests using the `std` and `std.compat` module
+>
+> - Using the `std` and `std.compat` module in external projects
+>
+> - The following "parts disabled" configuration options are supported
+>
+> - `LIBCXX_ENABLE_LOCALIZATION`
+> - `LIBCXX_ENABLE_WIDE_CHARACTERS`
+> - `LIBCXX_ENABLE_THREADS`
+> - `LIBCXX_ENABLE_FILESYSTEM`
+> - `LIBCXX_ENABLE_RANDOM_DEVICE`
+> - `LIBCXX_ENABLE_UNICODE`
+> - `LIBCXX_ENABLE_EXCEPTIONS` [^note-no-windows]
+>
+> - A C++20 based extension
+
+:::{note}
+[^note-no-windows]: This configuration will probably not work on Windows
+ due to hard-coded compilation flags.
+:::
+
+### Some of the current limitations
+
+> - There is no official build system support, libc++ has experimental CMake support
+> - Requires CMake 3.26 for C++20 support
+> - Requires CMake 3.26 for C++23 support
+> - Requires CMake 3.27 for C++26 support
+> - Requires Ninja 1.11
+> - Requires Clang 17
+> - The path to the compiler may not be a symlink, `clang-scan-deps` does
+> not handle that case properly
+> - Libc++ is not tested with modules instead of headers
+> - Clang:
+> : - Including headers after importing the `std` module may fail. This is
+> hard to solve and there is a work-around by first including all headers
+> [bug report](https://llvm.org/PR61465).
+
+### Blockers
+
+> - libc++
+>
+> - Currently the tests only test with modules enabled, but do not import
+> modules instead of headers. When converting tests to using modules there
+> are still failures. These are under investigation.
+> - It has not been determined how to fully test libc++ with modules instead
+> of headers.
+>
+> - Clang
+>
+> - Some concepts do not work properly [bug report](https://llvm.org/PR61465).
+
+## Using in external projects
Users need to be able to build their own BMI files.
-.. note:: The requirements for users to build their own BMI files will remain
- true for the foreseeable future. For now this needs to be done manually.
- Once libc++'s implementation is more mature we will reach out to build
- system vendors, with the goal that building the BMI files is done by
- the build system.
+:::{note}
+The requirements for users to build their own BMI files will remain
+true for the foreseeable future. For now this needs to be done manually.
+Once libc++'s implementation is more mature we will reach out to build
+system vendors, with the goal that building the BMI files is done by
+the build system.
+:::
Currently there are two ways to build modules
- * Use a local build of modules from the build directory. This requires
- Clang 17 or later and CMake 3.26 or later.
-
- * Use the installed modules. This requires Clang 18.1.2 or later and
- a recent build of CMake. The CMake changes will be part of CMake 3.30. This
- method requires you or your distribution to enable module installation.
-
-Using the local build
-~~~~~~~~~~~~~~~~~~~~~
+> - Use a local build of modules from the build directory. This requires
+> Clang 17 or later and CMake 3.26 or later.
+> - Use the installed modules. This requires Clang 18.1.2 or later and
+> a recent build of CMake. The CMake changes will be part of CMake 3.30. This
+> method requires you or your distribution to enable module installation.
-.. code-block:: bash
+### Using the local build
- $ git clone https://github.com/llvm/llvm-project.git
- $ cd llvm-project
- $ mkdir build
- $ cmake -G Ninja -S runtimes -B build -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind"
- $ ninja -C build
+```bash
+$ git clone https://github.com/llvm/llvm-project.git
+$ cd llvm-project
+$ mkdir build
+$ cmake -G Ninja -S runtimes -B build -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind"
+$ ninja -C build
+```
-The above ``build`` directory will be referred to as ``<build>`` in the
+The above `build` directory will be referred to as `<build>` in the
rest of these instructions.
-This is a small sample program that uses the module ``std``. It consists of a
-``CMakeLists.txt`` and a ``main.cpp`` file.
-
-.. code-block:: cpp
-
- import std; // When importing std.compat it's not needed to import std.
- import std.compat;
-
- int main() {
- std::cout << "Hello modular world\n";
- ::printf("Hello compat modular world\n");
- }
-
-.. code-block:: cmake
-
- cmake_minimum_required(VERSION 3.26.0 FATAL_ERROR)
- project("example"
- LANGUAGES CXX
- )
-
- #
- # Set language version used
- #
-
- set(CMAKE_CXX_STANDARD 23)
- set(CMAKE_CXX_STANDARD_REQUIRED YES)
- set(CMAKE_CXX_EXTENSIONS OFF)
-
- #
- # Enable modules in CMake
- #
-
- # This is required to write your own modules in your project.
- if(CMAKE_VERSION VERSION_LESS "3.28.0")
- if(CMAKE_VERSION VERSION_LESS "3.27.0")
- set(CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API "2182bf5c-ef0d-489a-91da-49dbc3090d2a")
- else()
- set(CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API "aa1f7df0-828a-4fcd-9afc-2dc80491aca7")
- endif()
- set(CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP 1)
+This is a small sample program that uses the module `std`. It consists of a
+`CMakeLists.txt` and a `main.cpp` file.
+
+```cpp
+import std; // When importing std.compat it's not needed to import std.
+import std.compat;
+
+int main() {
+ std::cout << "Hello modular world\n";
+ ::printf("Hello compat modular world\n");
+}
+```
+
+```cmake
+cmake_minimum_required(VERSION 3.26.0 FATAL_ERROR)
+project("example"
+ LANGUAGES CXX
+)
+
+#
+# Set language version used
+#
+
+set(CMAKE_CXX_STANDARD 23)
+set(CMAKE_CXX_STANDARD_REQUIRED YES)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+#
+# Enable modules in CMake
+#
+
+# This is required to write your own modules in your project.
+if(CMAKE_VERSION VERSION_LESS "3.28.0")
+ if(CMAKE_VERSION VERSION_LESS "3.27.0")
+ set(CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API "2182bf5c-ef0d-489a-91da-49dbc3090d2a")
else()
- cmake_policy(VERSION 3.28)
+ set(CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API "aa1f7df0-828a-4fcd-9afc-2dc80491aca7")
endif()
-
- #
- # Import the modules from libc++
- #
-
- include(FetchContent)
- FetchContent_Declare(
- std
- URL "file://${LIBCXX_BUILD}/modules/c++/v1/"
- DOWNLOAD_EXTRACT_TIMESTAMP TRUE
- SYSTEM
- )
- FetchContent_MakeAvailable(std)
-
- #
- # Add the project
- #
-
- add_executable(main)
- add_dependencies(main std.compat)
- target_link_libraries(main std.compat)
- target_sources(main
- PRIVATE
- main.cpp
- )
+ set(CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP 1)
+else()
+ cmake_policy(VERSION 3.28)
+endif()
+
+#
+# Import the modules from libc++
+#
+
+include(FetchContent)
+FetchContent_Declare(
+ std
+ URL "file://${LIBCXX_BUILD}/modules/c++/v1/"
+ DOWNLOAD_EXTRACT_TIMESTAMP TRUE
+ SYSTEM
+)
+FetchContent_MakeAvailable(std)
+
+#
+# Add the project
+#
+
+add_executable(main)
+add_dependencies(main std.compat)
+target_link_libraries(main std.compat)
+target_sources(main
+ PRIVATE
+ main.cpp
+)
+```
Building this project is done with the following steps, assuming the files
-``main.cpp`` and ``CMakeLists.txt`` are copied in the current directory.
-
-.. code-block:: bash
-
- $ mkdir build
- $ cmake -G Ninja -S . -B build -DCMAKE_CXX_COMPILER=<path-to-compiler> -DLIBCXX_BUILD=<build>
- $ ninja -C build
- $ build/main
+`main.cpp` and `CMakeLists.txt` are copied in the current directory.
-.. warning:: ``<path-to-compiler>`` should point point to the real binary and
- not to a symlink.
+```bash
+$ mkdir build
+$ cmake -G Ninja -S . -B build -DCMAKE_CXX_COMPILER=<path-to-compiler> -DLIBCXX_BUILD=<build>
+$ ninja -C build
+$ build/main
+```
-.. warning:: When using these examples in your own projects make sure the
- compilation flags are the same for the ``std`` module and your
- project. Some flags will affect the generated code, when these
- are different the module cannot be used. For example using
- ``-pthread`` in your project and not in the module will give
- errors like
+:::{warning}
+`<path-to-compiler>` should point point to the real binary and
+not to a symlink.
+:::
- ``error: POSIX thread support was disabled in PCH file but is currently enabled``
+:::{warning}
+When using these examples in your own projects make sure the
+compilation flags are the same for the `std` module and your
+project. Some flags will affect the generated code, when these
+are different the module cannot be used. For example using
+`-pthread` in your project and not in the module will give
+errors like
- ``error: module file _deps/std-build/CMakeFiles/std.dir/std.pcm cannot be loaded due to a configuration mismatch with the current compilation [-Wmodule-file-config-mismatch]``
+`error: POSIX thread support was disabled in PCH file but is currently enabled`
+`error: module file _deps/std-build/CMakeFiles/std.dir/std.pcm cannot be loaded due to a configuration mismatch with the current compilation [-Wmodule-file-config-mismatch]`
+:::
-Using the installed modules
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### Using the installed modules
CMake has added experimental support for importing the Standard modules. This
is available in the current nightly builds and will be part of the 3.30
@@ -228,57 +228,59 @@ release. Currently CMake only supports importing the Standard modules in C++23
and later. Enabling this for C++20 is on the TODO list of the CMake
developers.
-The example uses the same ``main.cpp`` as above. It uses the following
-``CMakeLists.txt``:
-
-.. code-block:: cmake
-
- # This requires a recent nightly build.
- # This will be part of CMake 3.30.0.
- cmake_minimum_required(VERSION 3.29.0 FATAL_ERROR)
-
- # Enables the Standard module support. This needs to be done
- # before selecting the languages.
- set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD "0e5b6991-d74f-4b3d-a41c-cf096e0b2508")
- set(CMAKE_CXX_MODULE_STD ON)
-
- project("example"
- LANGUAGES CXX
- )
-
- #
- # Set language version used
- #
-
- set(CMAKE_CXX_STANDARD 23)
- set(CMAKE_CXX_STANDARD_REQUIRED YES)
- # Currently CMake requires extensions enabled when using import std.
- # https://gitlab.kitware.com/cmake/cmake/-/issues/25916
- # https://gitlab.kitware.com/cmake/cmake/-/issues/25539
- set(CMAKE_CXX_EXTENSIONS ON)
-
- add_executable(main)
- target_sources(main
- PRIVATE
- main.cpp
- )
+The example uses the same `main.cpp` as above. It uses the following
+`CMakeLists.txt`:
+
+```cmake
+# This requires a recent nightly build.
+# This will be part of CMake 3.30.0.
+cmake_minimum_required(VERSION 3.29.0 FATAL_ERROR)
+
+# Enables the Standard module support. This needs to be done
+# before selecting the languages.
+set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD "0e5b6991-d74f-4b3d-a41c-cf096e0b2508")
+set(CMAKE_CXX_MODULE_STD ON)
+
+project("example"
+ LANGUAGES CXX
+)
+
+#
+# Set language version used
+#
+
+set(CMAKE_CXX_STANDARD 23)
+set(CMAKE_CXX_STANDARD_REQUIRED YES)
+# Currently CMake requires extensions enabled when using import std.
+# https://gitlab.kitware.com/cmake/cmake/-/issues/25916
+# https://gitlab.kitware.com/cmake/cmake/-/issues/25539
+set(CMAKE_CXX_EXTENSIONS ON)
+
+add_executable(main)
+target_sources(main
+ PRIVATE
+ main.cpp
+)
+```
Building this project is done with the following steps, assuming the files
-``main.cpp`` and ``CMakeLists.txt`` are copied in the current directory.
+`main.cpp` and `CMakeLists.txt` are copied in the current directory.
-.. code-block:: bash
+```bash
+$ mkdir build
+$ cmake -G Ninja -S . -B build -DCMAKE_CXX_COMPILER=<path-to-compiler> -DCMAKE_CXX_FLAGS=-stdlib=libc++
+$ ninja -C build
+$ build/main
+```
- $ mkdir build
- $ cmake -G Ninja -S . -B build -DCMAKE_CXX_COMPILER=<path-to-compiler> -DCMAKE_CXX_FLAGS=-stdlib=libc++
- $ ninja -C build
- $ build/main
+:::{warning}
+`<path-to-compiler>` should point point to the real binary and
+not to a symlink.
+:::
-.. warning:: ``<path-to-compiler>`` should point point to the real binary and
- not to a symlink.
+If you have questions about modules feel free to ask them in the `#libcxx`
+channel on [LLVM's Discord server](https://discord.gg/jzUbyP26tQ).
-If you have questions about modules feel free to ask them in the ``#libcxx``
-channel on `LLVM's Discord server <https://discord.gg/jzUbyP26tQ>`__.
-
-If you think you've found a bug please it using the `LLVM bug tracker
-<https://github.com/llvm/llvm-project/issues>`_. Please make sure the issue
+If you think you've found a bug please it using the [LLVM bug tracker](https://github.com/llvm/llvm-project/issues). Please make sure the issue
you found is not one of the known bugs or limitations on this page.
+
diff --git a/libcxx/docs/TestingLibcxx.md b/libcxx/docs/TestingLibcxx.md
index 8b902518a204b4..8267726c1059b5 100644
--- a/libcxx/docs/TestingLibcxx.md
+++ b/libcxx/docs/TestingLibcxx.md
@@ -1,88 +1,83 @@
-.. _testing:
+(testing)=
-==============
-Testing libc++
-==============
+# Testing libc++
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-Getting Started
-===============
+## Getting Started
libc++ uses LIT to configure and run its tests.
-The primary way to run the libc++ tests is by using ``make check-cxx``.
+The primary way to run the libc++ tests is by using `make check-cxx`.
However since libc++ can be used in any number of possible
configurations it is important to customize the way LIT builds and runs
the tests. This guide provides information on how to use LIT directly to
test libc++.
-Please see the `Lit Command Guide`_ for more information about LIT.
+Please see the [Lit Command Guide][lit command guide] for more information about LIT.
-.. _LIT Command Guide: https://llvm.org/docs/CommandGuide/lit.html
-
-Dependencies
-------------
+### Dependencies
The libc++ test suite has a few optional dependencies. These can be installed
-with ``pip install -r libcxx/test/requirements.txt``. Installing these dependencies
+with `pip install -r libcxx/test/requirements.txt`. Installing these dependencies
will ensure that the maximum number of tests can be run.
-Usage
------
+### Usage
-After :ref:`building libc++ <VendorDocumentation>`, you can run parts of the libc++ test suite by simply
-running ``llvm-lit`` on a specified test or directory. If you're unsure
+After {ref}`building libc++ <VendorDocumentation>`, you can run parts of the libc++ test suite by simply
+running `llvm-lit` on a specified test or directory. If you're unsure
whether the required libraries have been built, you can use the
-``cxx-test-depends`` target. For example:
-
-.. code-block:: bash
+`cxx-test-depends` target. For example:
- $ cd <monorepo-root>
- $ make -C <build> cxx-test-depends # If you want to make sure the targets get rebuilt
- $ <build>/bin/llvm-lit -sv libcxx/test/std/re # Run all of the std::regex tests
- $ <build>/bin/llvm-lit -sv libcxx/test/std/depr/depr.c.headers/stdlib_h.pass.cpp # Run a single test
- $ <build>/bin/llvm-lit -sv libcxx/test/std/atomics libcxx/test/std/threads # Test std::thread and std::atomic
+```bash
+$ cd <monorepo-root>
+$ make -C <build> cxx-test-depends # If you want to make sure the targets get rebuilt
+$ <build>/bin/llvm-lit -sv libcxx/test/std/re # Run all of the std::regex tests
+$ <build>/bin/llvm-lit -sv libcxx/test/std/depr/depr.c.headers/stdlib_h.pass.cpp # Run a single test
+$ <build>/bin/llvm-lit -sv libcxx/test/std/atomics libcxx/test/std/threads # Test std::thread and std::atomic
+```
-If you used **ninja** as your build system, running ``ninja -C <build> check-cxx`` will run
+If you used **ninja** as your build system, running `ninja -C <build> check-cxx` will run
all the tests in the libc++ testsuite.
-.. note::
- If you used the Bootstrapping build instead of the default runtimes build, the
- ``cxx-test-depends`` target is instead named ``runtimes-test-depends``, and
- you will need to prefix ``<build>/runtimes/runtimes-<target>-bins/`` to the
- paths of all tests. For example, to run all the libcxx tests you can do
- ``<build>/bin/llvm-lit -sv <build>/runtimes/runtimes-bins/libcxx/test``.
+:::{note}
+If you used the Bootstrapping build instead of the default runtimes build, the
+`cxx-test-depends` target is instead named `runtimes-test-depends`, and
+you will need to prefix `<build>/runtimes/runtimes-<target>-bins/` to the
+paths of all tests. For example, to run all the libcxx tests you can do
+`<build>/bin/llvm-lit -sv <build>/runtimes/runtimes-bins/libcxx/test`.
+:::
In the default configuration, the tests are built against headers that form a
fake installation root of libc++. This installation root has to be updated when
-changes are made to the headers, so you should re-run the ``cxx-test-depends``
-target before running the tests manually with ``lit`` when you make any sort of
-change, including to the headers. We recommend using the provided ``libcxx/utils/libcxx-lit``
+changes are made to the headers, so you should re-run the `cxx-test-depends`
+target before running the tests manually with `lit` when you make any sort of
+change, including to the headers. We recommend using the provided `libcxx/utils/libcxx-lit`
script to automate this so you don't have to think about building test dependencies
every time:
-.. code-block:: bash
-
- $ cd <monorepo-root>
- $ libcxx/utils/libcxx-lit <build> -sv libcxx/test/std/re # Build testing dependencies and run all of the std::regex tests
+```bash
+$ cd <monorepo-root>
+$ libcxx/utils/libcxx-lit <build> -sv libcxx/test/std/re # Build testing dependencies and run all of the std::regex tests
+```
Sometimes you'll want to change the way LIT is running the tests. Custom options
-can be specified using the ``--param <name>=<val>`` flag. The most common option
-you'll want to change is the standard dialect (ie ``-std=c++XX``). By default the
+can be specified using the `--param <name>=<val>` flag. The most common option
+you'll want to change is the standard dialect (ie `-std=c++XX`). By default the
test suite will select the newest C++ dialect supported by the compiler and use
that. However, you can manually specify the option like so if you want:
-.. code-block:: bash
+```bash
+$ libcxx/utils/libcxx-lit <build> -sv libcxx/test/std/containers # Run the tests with the newest -std
+$ libcxx/utils/libcxx-lit <build> -sv libcxx/test/std/containers --param std=c++03 # Run the tests in C++03
+```
- $ libcxx/utils/libcxx-lit <build> -sv libcxx/test/std/containers # Run the tests with the newest -std
- $ libcxx/utils/libcxx-lit <build> -sv libcxx/test/std/containers --param std=c++03 # Run the tests in C++03
-
-Other parameters are supported by the test suite. Those are defined in ``libcxx/utils/libcxx/test/params.py``.
+Other parameters are supported by the test suite. Those are defined in `libcxx/utils/libcxx/test/params.py`.
If you want to customize how to run the libc++ test suite beyond what is available
-in ``params.py``, you most likely want to use a custom site configuration instead.
+in `params.py`, you most likely want to use a custom site configuration instead.
The libc++ test suite works by loading a site configuration that defines various
"base" parameters (via Lit substitutions). These base parameters represent things
@@ -91,34 +86,33 @@ flags to use, and how to run an executable. This system is meant to be easily
extended for custom needs, in particular when porting the libc++ test suite to
new platforms.
-.. note::
- If you run the test suite on Apple platforms, we recommend adding the terminal application
- used to run the test suite to the list of "Developer Tools". This prevents the system from
- trying to scan each individual test binary for malware and dramatically speeds up the test
- suite.
+:::{note}
+If you run the test suite on Apple platforms, we recommend adding the terminal application
+used to run the test suite to the list of "Developer Tools". This prevents the system from
+trying to scan each individual test binary for malware and dramatically speeds up the test
+suite.
+:::
-Using a Custom Site Configuration
----------------------------------
+### Using a Custom Site Configuration
By default, the libc++ test suite will use a site configuration that matches
-the current CMake configuration. It does so by generating a ``lit.site.cfg``
+the current CMake configuration. It does so by generating a `lit.site.cfg`
file in the build directory from one of the configuration file templates in
-``libcxx/test/configs/``, and pointing ``llvm-lit`` (which is a wrapper around
-``llvm/utils/lit/lit.py``) to that file. So when you're running
-``<build>/bin/llvm-lit`` either directly or indirectly, the generated ``lit.site.cfg``
-file is always loaded instead of ``libcxx/test/lit.cfg.py``. If you want to use a
+`libcxx/test/configs/`, and pointing `llvm-lit` (which is a wrapper around
+`llvm/utils/lit/lit.py`) to that file. So when you're running
+`<build>/bin/llvm-lit` either directly or indirectly, the generated `lit.site.cfg`
+file is always loaded instead of `libcxx/test/lit.cfg.py`. If you want to use a
custom site configuration, simply point the CMake build to it using
-``-DLIBCXX_TEST_CONFIG=<path-to-site-config>``, and that site configuration
+`-DLIBCXX_TEST_CONFIG=<path-to-site-config>`, and that site configuration
will be used instead. That file can use CMake variables inside it to make
configuration easier.
- .. code-block:: bash
-
- $ cmake <options> -DLIBCXX_TEST_CONFIG=<path-to-site-config>
- $ libcxx/utils/libcxx-lit <build> -sv libcxx/test # will use your custom config file
+> ```bash
+> $ cmake <options> -DLIBCXX_TEST_CONFIG=<path-to-site-config>
+> $ libcxx/utils/libcxx-lit <build> -sv libcxx/test # will use your custom config file
+> ```
-Additional tools
-----------------
+### Additional tools
The libc++ test suite uses a few optional tools to improve the code quality.
@@ -126,18 +120,17 @@ These tools are:
- clang-tidy (you might need additional dev packages to compile libc++-specific clang-tidy checks)
-Reproducing CI issues locally
------------------------------
+### Reproducing CI issues locally
Libc++ has extensive CI that tests various configurations of the library. The testing for
-all these configurations is located in ``libcxx/utils/ci/run-buildbot``. Most of our
+all these configurations is located in `libcxx/utils/ci/run-buildbot`. Most of our
CI jobs are being run on a Docker image for reproducibility. The definition of this Docker
-image is located in ``libcxx/utils/ci/Dockerfile``. If you are looking to reproduce the
+image is located in `libcxx/utils/ci/Dockerfile`. If you are looking to reproduce the
failure of a specific CI job locally, you should first drop into a Docker container that
-matches our CI images by running ``libcxx/utils/ci/run-buildbot-container``, and then run
-the specific CI job that you're interested in (from within the container) using the ``run-buildbot``
-script above. If you want to control which compiler is used, you can set the ``CC`` and the
-``CXX`` environment variables before calling ``run-buildbot`` to select the right compiler.
+matches our CI images by running `libcxx/utils/ci/run-buildbot-container`, and then run
+the specific CI job that you're interested in (from within the container) using the `run-buildbot`
+script above. If you want to control which compiler is used, you can set the `CC` and the
+`CXX` environment variables before calling `run-buildbot` to select the right compiler.
Take note that some CI jobs are testing the library on specific platforms and are *not* run
in our Docker image. In the general case, it is not possible to reproduce these failures
locally, unless they aren't specific to the platform.
@@ -146,8 +139,7 @@ Also note that the Docker container shares the same filesystem as your local mac
modifying files on your local machine will also modify what the Docker container sees.
This is useful for editing source files as you're testing your code in the Docker container.
-Writing Tests
-=============
+## Writing Tests
When writing tests for the libc++ test suite, you should follow a few guidelines.
This will ensure that your tests can run on a wide variety of hardware and under
@@ -159,7 +151,7 @@ few requirements to the test suite. Here's some stuff you should know:
cleaned up after the test is done.
- When a test needs data files as inputs, these data files can be saved in the
repository (when reasonable) and referenced by the test as
- ``// FILE_DEPENDENCIES: <path-to-dependencies>``. Copies of these files or
+ `// FILE_DEPENDENCIES: <path-to-dependencies>`. Copies of these files or
directories will be made available to the test in the temporary directory
where it is run.
- You should never hardcode a path from the build-host in a test, because that
@@ -169,190 +161,173 @@ few requirements to the test suite. Here's some stuff you should know:
necessarily available on all devices we may want to run the tests on (even
though supporting Python is probably trivial for the build-host).
-Structure of the testing related directories
---------------------------------------------
+### Structure of the testing related directories
The tests of libc++ are stored in libc++'s testing related subdirectories:
-- ``libcxx/test/support`` This directory contains several helper headers with
- generic parts for the tests. The most important header is ``test_macros.h``.
+- `libcxx/test/support` This directory contains several helper headers with
+ generic parts for the tests. The most important header is `test_macros.h`.
This file contains configuration information regarding the platform used.
- This is similar to the ``__config`` file in libc++'s ``include`` directory.
+ This is similar to the `__config` file in libc++'s `include` directory.
Since libc++'s tests are used by other Standard libraries, tests should use
- the ``TEST_FOO`` macros instead of the ``_LIBCPP_FOO`` macros, which are
+ the `TEST_FOO` macros instead of the `_LIBCPP_FOO` macros, which are
specific to libc++.
-- ``libcxx/test/std`` This directory contains the tests that validate the library under
+- `libcxx/test/std` This directory contains the tests that validate the library under
test conforms to the C++ Standard. The paths and the names of the test match
the section names in the C++ Standard. Note that the C++ Standard sometimes
reorganises its structure, therefore some tests are at a location based on
where they appeared historically in the standard. We try to strike a balance
between keeping things at up-to-date locations and unnecessary churn.
-- ``libcxx/test/libcxx`` This directory contains the tests that validate libc++
+- `libcxx/test/libcxx` This directory contains the tests that validate libc++
specific behavior and implementation details. For example, libc++ has
"wrapped iterators" that perform bounds checks. Since those are specific to
libc++ and not mandated by the Standard, tests for those are located under
- ``libcxx/test/libcxx``. The structure of this directories follows the
- structure of ``libcxx/test/std``.
+ `libcxx/test/libcxx`. The structure of this directories follows the
+ structure of `libcxx/test/std`.
-Structure of a test
--------------------
+### Structure of a test
Some platforms where libc++ is tested have requirement on the signature of
-``main`` and require ``main`` to explicitly return a value. Therefore the
-typical ``main`` function should look like:
-
-.. code-block:: cpp
-
- int main(int, char**) {
- ...
- return 0;
- }
-
-
-The C++ Standard has ``constexpr`` requirements. The typical way to test that,
-is to create a helper ``test`` function that returns a ``bool`` and use the
-following ``main`` function:
-
-.. code-block:: cpp
-
- constexpr bool test() {
- ...
- return true;
- }
-
- int main(int, char**) {
- test()
- static_assert(test());
-
- return 0;
- }
-
-Tests in libc++ mainly use ``assert`` and ``static_assert`` for testing. There
+`main` and require `main` to explicitly return a value. Therefore the
+typical `main` function should look like:
+
+```cpp
+int main(int, char**) {
+ ...
+ return 0;
+}
+```
+
+The C++ Standard has `constexpr` requirements. The typical way to test that,
+is to create a helper `test` function that returns a `bool` and use the
+following `main` function:
+
+```cpp
+constexpr bool test() {
+ ...
+ return true;
+}
+
+int main(int, char**) {
+ test()
+ static_assert(test());
+
+ return 0;
+}
+```
+
+Tests in libc++ mainly use `assert` and `static_assert` for testing. There
are a few helper macros and function that can be used to make it easier to
write common tests.
-libcxx/test/support/assert_macros.h
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### libcxx/test/support/assert_macros.h
The header contains several macros with user specified log messages. This is
useful when a normal assertion failure lacks the information to easily
understand why the test has failed. This usually happens when the test is in a
-helper function. For example the ``std::format`` tests use a helper function
+helper function. For example the `std::format` tests use a helper function
for its validation. When the test fails it will give the line in the helper
-function with the condition ``out == expected`` failed. Without knowing what
-the value of ``format string``, ``out`` and ``expected`` are it is not easy to
+function with the condition `out == expected` failed. Without knowing what
+the value of `format string`, `out` and `expected` are it is not easy to
understand why the test has failed. By logging these three values the point of
failure can be found without resorting to a debugger.
-Several of these macros are documented to take an ``ARG``. This ``ARG``:
+Several of these macros are documented to take an `ARG`. This `ARG`:
- - if it is a ``const char*`` or ``std::string`` its contents are written to
- the ``stderr``,
- - otherwise it must be a callable that is invoked without any additional
- arguments and is expected to produce useful output to e.g. ``stderr``.
+> - if it is a `const char*` or `std::string` its contents are written to
+> the `stderr`,
+> - otherwise it must be a callable that is invoked without any additional
+> arguments and is expected to produce useful output to e.g. `stderr`.
This makes it possible to write additional information when a test fails,
either by supplying a hard-coded string or generate it at runtime.
-TEST_FAIL(ARG)
-^^^^^^^^^^^^^^
+##### TEST_FAIL(ARG)
-This macro is an unconditional failure with a log message ``ARG``. The main
+This macro is an unconditional failure with a log message `ARG`. The main
use-case is to fail when code is reached that should be unreachable.
+##### TEST_REQUIRE(CONDITION, ARG)
-TEST_REQUIRE(CONDITION, ARG)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This macro requires its ``CONDITION`` to evaluate to ``true``. If that fails it
-will fail the test with a log message ``ARG``.
+This macro requires its `CONDITION` to evaluate to `true`. If that fails it
+will fail the test with a log message `ARG`.
+##### TEST_LIBCPP_REQUIRE((CONDITION, ARG)
-TEST_LIBCPP_REQUIRE((CONDITION, ARG)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If the library under test is libc++ it behaves like ``TEST_REQUIRE``, else it
+If the library under test is libc++ it behaves like `TEST_REQUIRE`, else it
is a no-op. This makes it possible to test libc++ specific behaviour. For
-example testing whether the ``what()`` of an exception thrown matches libc++'s
+example testing whether the `what()` of an exception thrown matches libc++'s
expectations. (Usually the Standard requires certain exceptions to be thrown,
-but not the contents of its ``what()`` message.)
-
-
-TEST_DOES_NOT_THROW(EXPR)
-^^^^^^^^^^^^^^^^^^^^^^^^^
+but not the contents of its `what()` message.)
-Validates execution of ``EXPR`` does not throw an exception.
+##### TEST_DOES_NOT_THROW(EXPR)
-TEST_THROWS_TYPE(TYPE, EXPR)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Validates execution of `EXPR` does not throw an exception.
-Validates the execution of ``EXPR`` throws an exception of the type ``TYPE``.
+##### TEST_THROWS_TYPE(TYPE, EXPR)
+Validates the execution of `EXPR` throws an exception of the type `TYPE`.
-TEST_VALIDATE_EXCEPTION(TYPE, PRED, EXPR)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+##### TEST_VALIDATE_EXCEPTION(TYPE, PRED, EXPR)
-Validates the execution of ``EXPR`` throws an exception of the type ``TYPE``
-which passes validation of ``PRED``. Using this macro makes it easier to write
+Validates the execution of `EXPR` throws an exception of the type `TYPE`
+which passes validation of `PRED`. Using this macro makes it easier to write
tests using exceptions. The code to write a test manually would be:
-
-.. code-block:: cpp
-
- void test_exception([[maybe_unused]] int arg) {
- #ifndef TEST_HAS_NO_EXCEPTIONS // do nothing when tests are disabled
- try {
- foo(arg);
- assert(false); // validates foo really throws
- } catch ([[maybe_unused]] const bar& e) {
- LIBCPP_ASSERT(e.what() == what);
- return;
- }
- assert(false); // validates bar was thrown
- #endif
- }
+```cpp
+void test_exception([[maybe_unused]] int arg) {
+#ifndef TEST_HAS_NO_EXCEPTIONS // do nothing when tests are disabled
+ try {
+ foo(arg);
+ assert(false); // validates foo really throws
+ } catch ([[maybe_unused]] const bar& e) {
+ LIBCPP_ASSERT(e.what() == what);
+ return;
+ }
+ assert(false); // validates bar was thrown
+#endif
+ }
+```
The same test using a macro:
-.. code-block:: cpp
-
- void test_exception([[maybe_unused]] int arg) {
- TEST_VALIDATE_EXCEPTION(bar,
- [](const bar& e) {
- LIBCPP_ASSERT(e.what() == what);
- },
- foo(arg));
- }
-
+```cpp
+void test_exception([[maybe_unused]] int arg) {
+ TEST_VALIDATE_EXCEPTION(bar,
+ [](const bar& e) {
+ LIBCPP_ASSERT(e.what() == what);
+ },
+ foo(arg));
+ }
+```
-libcxx/test/support/concat_macros.h
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### libcxx/test/support/concat_macros.h
-This file contains a helper macro ``TEST_WRITE_CONCATENATED`` to lazily
-concatenate its arguments to a ``std::string`` and write it to ``stderr``. When
+This file contains a helper macro `TEST_WRITE_CONCATENATED` to lazily
+concatenate its arguments to a `std::string` and write it to `stderr`. When
the output can't be concatenated a default message will be written to
-``stderr``. This is useful for tests where the arguments use different
-character types like ``char`` and ``wchar_t``, the latter can't simply be
-written to ``stderr``.
+`stderr`. This is useful for tests where the arguments use different
+character types like `char` and `wchar_t`, the latter can't simply be
+written to `stderr`.
-This macro is in a different header as ``assert_macros.h`` since it pulls in
+This macro is in a different header as `assert_macros.h` since it pulls in
additional headers.
- .. note: This macro can only be used in test using C++20 or newer. The macro
- was added at a time where most of libc++'s C++17 support was complete.
- Since it is not expected to add this to existing tests no effort was
- taken to make it work in earlier language versions.
-
+> % note: This macro can only be used in test using C++20 or newer. The macro
+> % was added at a time where most of libc++'s C++17 support was complete.
+> % Since it is not expected to add this to existing tests no effort was
+> % taken to make it work in earlier language versions.
-Test names
-----------
+### Test names
The names of test files have meaning for the libc++-specific configuration of
Lit. Based on the pattern that matches the name of a test file, Lit will test
-the code contained therein in different ways. Refer to the `Lit Meaning of libc++
-Test Filenames`_ when determining the names for new test files.
+the code contained therein in different ways. Refer to the [Lit Meaning of libc++
+Test Filenames][lit meaning of libc++ test filenames] when determining the names for new test files.
+
+(lit-meaning-of-libc-test-filenames)=
-.. _Lit Meaning of libc++ Test Filenames:
+```{eval-rst}
.. list-table:: Lit Meaning of libc++ Test Filenames
:widths: 25 75
:header-rows: 1
@@ -404,17 +379,18 @@ Test Filenames`_ when determining the names for new test files.
- A benchmark test. These tests are linked against the GoogleBenchmark library and generally consist of micro-benchmarks of individual
components of the library.
+```
-libc++-Specific Lit Features
-----------------------------
+### libc++-Specific Lit Features
-Custom Directives
-~~~~~~~~~~~~~~~~~
+#### Custom Directives
-Lit has many directives built in (e.g., ``DEFINE``, ``UNSUPPORTED``). In addition to those directives, libc++ adds two additional libc++-specific directives that makes
-writing tests easier. See `libc++-specific Lit Directives`_ for more information about the ``FILE_DEPENDENCIES``, ``ADDITIONAL_COMPILE_FLAGS``, and ``MODULE_DEPENDENCIES`` libc++-specific directives.
+Lit has many directives built in (e.g., `DEFINE`, `UNSUPPORTED`). In addition to those directives, libc++ adds two additional libc++-specific directives that makes
+writing tests easier. See [libc++-specific Lit Directives] for more information about the `FILE_DEPENDENCIES`, `ADDITIONAL_COMPILE_FLAGS`, and `MODULE_DEPENDENCIES` libc++-specific directives.
-.. _libc++-specific Lit Directives:
+(libc-specific-lit-directives)=
+
+```{eval-rst}
.. list-table:: libc++-specific Lit Directives
:widths: 20 35 45
:header-rows: 1
@@ -442,150 +418,149 @@ writing tests easier. See `libc++-specific Lit Directives`_ for more information
%{compile_flags}. (Libc++ offers these modules in C++20 as an
extension.)
+```
-C++ Standard version tests
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### C++ Standard version tests
Historically libc++ tests used to filter the tests for C++ Standard versions
with lit directives like:
-.. code-block:: cpp
-
- // UNSUPPORTED: c++03, c++11, c++14, c++17, c++20, c++23
+```cpp
+// UNSUPPORTED: c++03, c++11, c++14, c++17, c++20, c++23
+```
With C++ Standards released every 3 years, this solution is not scalable.
Instead use:
-.. code-block:: cpp
-
- // REQUIRES: std-at-least-c++26
+```cpp
+// REQUIRES: std-at-least-c++26
+```
-There is no corresponding ``std-at-most-c++23``. This could be useful when
+There is no corresponding `std-at-most-c++23`. This could be useful when
tests are only valid for a small set of standard versions. For example, a
deprecation test is only valid when the feature is deprecated until it is
removed from the Standard. These tests should be written like:
-.. code-block:: cpp
-
- // REQUIRES: c++17 || c++20 || c++23
-
-.. note::
-
- There are a lot of tests with the first style, these can remain as they are.
- The new style is only intended to be used for new tests.
+```cpp
+// REQUIRES: c++17 || c++20 || c++23
+```
+:::{note}
+There are a lot of tests with the first style, these can remain as they are.
+The new style is only intended to be used for new tests.
+:::
-Benchmarks
-==========
+## Benchmarks
-Libc++'s test suite also contains benchmarks. Many benchmarks are written using the `Google Benchmark`_
+Libc++'s test suite also contains benchmarks. Many benchmarks are written using the [Google Benchmark][google benchmark]
library, a copy of which is stored in the LLVM monorepo. For more information about using the Google
-Benchmark library, see the `official documentation <https://github.com/google/benchmark>`_.
+Benchmark library, see the [official documentation](https://github.com/google/benchmark).
-The benchmarks are located under ``libcxx/test/benchmarks``. Running a benchmark
+The benchmarks are located under `libcxx/test/benchmarks`. Running a benchmark
works in the same way as running a test. Both the benchmarks and the tests share
the same configuration, so make sure to enable the relevant optimization level
when running the benchmarks. For example,
-.. code-block:: bash
+```bash
+$ libcxx/utils/libcxx-lit <build> libcxx/test/benchmarks/containers/string.bench.cpp --show-all --param optimization=speed
+```
- $ libcxx/utils/libcxx-lit <build> libcxx/test/benchmarks/containers/string.bench.cpp --show-all --param optimization=speed
-
-Note that benchmarks are only dry-run when run via the ``check-cxx`` target since
+Note that benchmarks are only dry-run when run via the `check-cxx` target since
we only want to make sure they don't rot. Do not rely on the results of benchmarks
-run through ``check-cxx`` for anything, instead run the benchmarks manually using
+run through `check-cxx` for anything, instead run the benchmarks manually using
the instructions for running individual tests.
If you want to compare the results of different benchmark runs, we recommend using the
-``compare-benchmarks`` helper tool. Note that the script has some dependencies, which can
+`compare-benchmarks` helper tool. Note that the script has some dependencies, which can
be installed with:
-.. code-block:: bash
-
- $ python -m venv .venv && source .venv/bin/activate # Optional but recommended
- $ pip install -r libcxx/utils/requirements.txt
+```bash
+$ python -m venv .venv && source .venv/bin/activate # Optional but recommended
+$ pip install -r libcxx/utils/requirements.txt
+```
Once that's done, start by configuring CMake in a build directory and running one or
more benchmarks, as usual:
-.. code-block:: bash
-
- $ cmake -S runtimes -B <build> [...]
- $ libcxx/utils/libcxx-lit <build> libcxx/test/benchmarks/containers/string.bench.cpp --param optimization=speed
+```bash
+$ cmake -S runtimes -B <build> [...]
+$ libcxx/utils/libcxx-lit <build> libcxx/test/benchmarks/containers/string.bench.cpp --param optimization=speed
+```
-Then, get the consolidated benchmark output for that run using ``consolidate-benchmarks``:
+Then, get the consolidated benchmark output for that run using `consolidate-benchmarks`:
-.. code-block:: bash
+```bash
+$ libcxx/utils/consolidate-benchmarks <build> > baseline.lnt
+```
- $ libcxx/utils/consolidate-benchmarks <build> > baseline.lnt
-
-The ``baseline.lnt`` file will contain a consolidation of all the benchmark results present in the build
+The `baseline.lnt` file will contain a consolidation of all the benchmark results present in the build
directory. You can then make the desired modifications to the code, run the benchmark(s) again, and then run:
-.. code-block:: bash
-
- $ libcxx/utils/consolidate-benchmarks <build> > candidate.lnt
-
-Finally, use ``compare-benchmarks`` to compare both:
+```bash
+$ libcxx/utils/consolidate-benchmarks <build> > candidate.lnt
+```
-.. code-block:: bash
+Finally, use `compare-benchmarks` to compare both:
- $ libcxx/utils/compare-benchmarks baseline.lnt candidate.lnt
+```bash
+$ libcxx/utils/compare-benchmarks baseline.lnt candidate.lnt
- # Useful one-liner when iterating locally:
- $ libcxx/utils/compare-benchmarks baseline.lnt <(libcxx/utils/consolidate-benchmarks <build>)
+# Useful one-liner when iterating locally:
+$ libcxx/utils/compare-benchmarks baseline.lnt <(libcxx/utils/consolidate-benchmarks <build>)
+```
-The ``compare-benchmarks`` script provides some useful options like creating a chart to easily visualize
-differences in a browser window. Use ``compare-benchmarks --help`` for details.
+The `compare-benchmarks` script provides some useful options like creating a chart to easily visualize
+differences in a browser window. Use `compare-benchmarks --help` for details.
Additionally, adding a comment of the following form to a libc++ PR will cause the specified benchmarks to be run
on our pre-commit CI infrastructure and the results to be reported in the PR by our CI system:
-.. code-block::
-
- /libcxx-bot benchmark <path/to/benchmark1.bench.cpp> <path/to/benchmark2.bench.cpp> ...
+```
+/libcxx-bot benchmark <path/to/benchmark1.bench.cpp> <path/to/benchmark2.bench.cpp> ...
+```
Note that this is currently experimental and the results should not be relied upon too strongly, since
we do not have dedicated hardware to run the benchmarks on.
-.. _`Google Benchmark`: https://github.com/google/benchmark
-
-.. _testing-hardening-assertions:
+(testing-hardening-assertions)=
-Testing hardening assertions
-============================
+## Testing hardening assertions
Each hardening assertion should be tested using death tests (via the
-``TEST_LIBCPP_ASSERT_FAILURE`` macro). The convention is to use ``assert.`` in
+`TEST_LIBCPP_ASSERT_FAILURE` macro). The convention is to use `assert.` in
the name of the test file to make it easier to identify as a hardening test, e.g.
-``assert.my_func.pass.cpp``.
+`assert.my_func.pass.cpp`.
These tests only make sense in configurations where the death test machinery in
-``check_assertion.h`` is usable, where a failing assertion is observable, and
+`check_assertion.h` is usable, where a failing assertion is observable, and
where the assertion being tested is enabled in the first place. Use the various
-``can-test-hardening-assertions-<mode>`` Lit features to guard the tests accordingly.
-The bare ``can-test-hardening-assertions`` Lit feature only encodes whether the death
+`can-test-hardening-assertions-<mode>` Lit features to guard the tests accordingly.
+The bare `can-test-hardening-assertions` Lit feature only encodes whether the death
test machinery is usable; it is meant for tests that select a hardening mode or an
-assertion semantic themselves (see the tests under ``libcxx/test/libcxx/assertions/``).
+assertion semantic themselves (see the tests under `libcxx/test/libcxx/assertions/`).
A toy example:
-.. code-block:: cpp
-
- // Example: `std::foo(...)` uses `_LIBCPP_ASSERT_NON_NULL`, which is
- // enabled in the `extensive` and `debug` modes.
- // REQUIRES: can-test-hardening-assertions-extensive
+```cpp
+// Example: `std::foo(...)` uses `_LIBCPP_ASSERT_NON_NULL`, which is
+// enabled in the `extensive` and `debug` modes.
+// REQUIRES: can-test-hardening-assertions-extensive
- #include <stdfoo>
+#include <stdfoo>
- #include "check_assertion.h" // Contains the `TEST_LIBCPP_ASSERT_FAILURE` macro
+#include "check_assertion.h" // Contains the `TEST_LIBCPP_ASSERT_FAILURE` macro
- int main(int, char**) {
- int bad_input = -1;
- TEST_LIBCPP_ASSERT_FAILURE(std::foo(bad_input), "The expected assertion message");
+int main(int, char**) {
+ int bad_input = -1;
+ TEST_LIBCPP_ASSERT_FAILURE(std::foo(bad_input), "The expected assertion message");
- return 0;
- }
+ return 0;
+}
+```
Note that error messages are only tested (matched) when the assertion semantic in
-effect logs one, i.e. ``enforce`` or ``observe``.
+effect logs one, i.e. `enforce` or `observe`.
+
+[google benchmark]: https://github.com/google/benchmark
+[lit command guide]: https://llvm.org/docs/CommandGuide/lit.html
+
diff --git a/libcxx/docs/UserDocumentation.md b/libcxx/docs/UserDocumentation.md
index 415a599168374f..2f8a5a7fcb2e8e 100644
--- a/libcxx/docs/UserDocumentation.md
+++ b/libcxx/docs/UserDocumentation.md
@@ -1,11 +1,10 @@
-.. _user-documentation:
+(user-documentation)=
-==================
-User documentation
-==================
+# User documentation
-.. contents::
- :local:
+```{contents}
+:local: true
+```
This page contains information for users of libc++: how to use libc++ if it is not
the default library used by the toolchain, and what configuration knobs are available
@@ -13,117 +12,116 @@ if libc++ is used by the toolchain. This page is aimed at users of libc++, where
separate page contains documentation aimed at vendors who build and ship libc++
as part of their toolchain.
-
-Using a different version of the C++ Standard
-=============================================
+## Using a different version of the C++ Standard
Libc++ implements the various versions of the C++ standard. Changing the version of
-the standard can be done by passing ``-std=c++XY`` to the compiler. Libc++ will
+the standard can be done by passing `-std=c++XY` to the compiler. Libc++ will
automatically detect what standard is being used and will provide functionality that
matches that standard in the library.
-.. code-block:: bash
-
- $ clang++ -std=c++17 test.cpp
+```bash
+$ clang++ -std=c++17 test.cpp
+```
-Note that using ``-std=c++XY`` with a version of the standard that has not been ratified
+Note that using `-std=c++XY` with a version of the standard that has not been ratified
yet is considered unstable. While we strive to maintain stability, libc++ may be forced to
make breaking changes to features shipped in a C++ standard that has not been ratified yet.
Use these versions of the standard at your own risk.
-
-Using libc++ when it is not the system default
-==============================================
+## Using libc++ when it is not the system default
Usually, libc++ is packaged and shipped by a vendor through some delivery vehicle
(operating system distribution, SDK, toolchain, etc) and users don't need to do
anything special in order to use the library.
However, on systems where libc++ is provided but is not the default, Clang can be invoked
-with the ``-stdlib=`` flag to select which standard library is used.
-Using ``-stdlib=libc++`` will select libc++:
+with the `-stdlib=` flag to select which standard library is used.
+Using `-stdlib=libc++` will select libc++:
-.. code-block:: bash
-
- $ clang++ -stdlib=libc++ test.cpp
+```bash
+$ clang++ -stdlib=libc++ test.cpp
+```
This flag is not required on systems where libc++ is the default standard library,
such as macOS and FreeBSD.
-
-Enabling experimental C++ Library features
-==========================================
+## Enabling experimental C++ Library features
Libc++ provides implementations of some experimental features. Experimental features
are either Technical Specifications (TSes) or official features that were voted to
the C++ standard but whose implementation is not complete or stable yet in libc++.
Those are disabled by default because they are neither API nor ABI stable. However,
-users can enable the ``-fexperimental-library`` compiler flag to turn those features on.
+users can enable the `-fexperimental-library` compiler flag to turn those features on.
-On compilers that do not support the ``-fexperimental-library`` flag (such as GCC),
-users can define the ``_LIBCPP_ENABLE_EXPERIMENTAL`` macro and manually link against
-the appropriate static library (usually shipped as ``libc++experimental.a``) to get
+On compilers that do not support the `-fexperimental-library` flag (such as GCC),
+users can define the `_LIBCPP_ENABLE_EXPERIMENTAL` macro and manually link against
+the appropriate static library (usually shipped as `libc++experimental.a`) to get
access to experimental library features.
The following features are currently considered experimental and are only provided
-when ``-fexperimental-library`` is passed:
+when `-fexperimental-library` is passed:
-* The parallel algorithms library (``<execution>`` and the associated algorithms)
-* ``std::chrono::tzdb`` and related time zone functionality
-* ``<syncstream>``
+- The parallel algorithms library (`<execution>` and the associated algorithms)
+- `std::chrono::tzdb` and related time zone functionality
+- `<syncstream>`
Additionally, assertion semantics are an experimental feature that can be used
-to customize the behavior of Hardening (see :ref:`here <assertion-semantics>`).
+to customize the behavior of Hardening (see {ref}`here <assertion-semantics>`).
Assertion semantics mirror the evaluation semantics of C++26 Contracts but are
not a standard feature.
-.. note::
- Experimental libraries are experimental.
- * The contents of the ``<experimental/...>`` headers and the associated static
- library may not remain compatible between versions.
- * No guarantees of API or ABI stability are provided.
- * When the standardized version of an experimental feature is implemented,
- the experimental feature is removed two releases after the non-experimental
- version has shipped. The full policy is explained :ref:`here <experimental features>`.
+:::{note}
+Experimental libraries are experimental.
+: - The contents of the `<experimental/...>` headers and the associated static
+ library may not remain compatible between versions.
+ - No guarantees of API or ABI stability are provided.
+ - When the standardized version of an experimental feature is implemented,
+ the experimental feature is removed two releases after the non-experimental
+ version has shipped. The full policy is explained {ref}`here <experimental features>`.
+:::
+(libcxx-configuration-macros)=
-.. _libcxx-configuration-macros:
-
-Libc++ Configuration Macros
-===========================
+## Libc++ Configuration Macros
Libc++ provides a number of configuration macros that can be used by developers to
enable or disable extended libc++ behavior.
-.. warning::
- Configuration macros that are not documented here are not intended to be customized
- by developers and should not be used. In particular, some configuration macros are
- only intended to be used by vendors and changing their value from the one provided
- in your toolchain can lead to unexpected behavior.
+:::{warning}
+Configuration macros that are not documented here are not intended to be customized
+by developers and should not be used. In particular, some configuration macros are
+only intended to be used by vendors and changing their value from the one provided
+in your toolchain can lead to unexpected behavior.
+:::
+
+**\_LIBCPP_DISABLE_DEPRECATION_WARNINGS**:
-**_LIBCPP_DISABLE_DEPRECATION_WARNINGS**:
- This macro disables warnings when using deprecated components. For example,
+: This macro disables warnings when using deprecated components. For example,
using `std::auto_ptr` when compiling in C++11 mode will normally trigger a
warning saying that `std::auto_ptr` is deprecated. If the macro is defined,
no warning will be emitted. By default, this macro is not defined.
-**_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS**:
- This macro is used to disable all visibility annotations inside libc++.
+**\_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS**:
+
+: This macro is used to disable all visibility annotations inside libc++.
Defining this macro and then building libc++ with hidden visibility gives a
build of libc++ which does not export any symbols, which can be useful when
building statically for inclusion into another library.
-**_LIBCPP_ENABLE_EXPERIMENTAL**:
- This macro enables experimental features. This can be used on compilers that do
- not support the ``-fexperimental-library`` flag. When used, users also need to
- ensure that the appropriate experimental library (usually ``libc++experimental.a``)
+**\_LIBCPP_ENABLE_EXPERIMENTAL**:
+
+: This macro enables experimental features. This can be used on compilers that do
+ not support the `-fexperimental-library` flag. When used, users also need to
+ ensure that the appropriate experimental library (usually `libc++experimental.a`)
is linked into their program.
-**_LIBCPP_HARDENING_MODE**:
- This macro is used to choose the :ref:`hardening mode <using-hardening-modes>`.
+**\_LIBCPP_HARDENING_MODE**:
+
+: This macro is used to choose the {ref}`hardening mode <using-hardening-modes>`.
-**_LIBCPP_NO_VCRUNTIME**:
- Microsoft's C and C++ headers are fairly entangled, and some of their C++
+**\_LIBCPP_NO_VCRUNTIME**:
+
+: Microsoft's C and C++ headers are fairly entangled, and some of their C++
headers are fairly hard to avoid. In particular, `vcruntime_new.h` gets pulled
in from a lot of other headers and provides definitions which clash with
libc++ headers, such as `nothrow_t` (note that `nothrow_t` is a struct, so
@@ -142,8 +140,9 @@ enable or disable extended libc++ behavior.
replacement scenarios from working, e.g. replacing `operator new` and
expecting a non-replaced `operator new[]` to call the replaced `operator new`.
-**_LIBCPP_REMOVE_TRANSITIVE_INCLUDES**:
- When this macro is defined, the standard library headers will adhere to a
+**\_LIBCPP_REMOVE_TRANSITIVE_INCLUDES**:
+
+: When this macro is defined, the standard library headers will adhere to a
stricter policy regarding the (transitive) inclusion of other standard library
headers, only guaranteeing to provide those definitions explicitly mandated by
the standard. Please notice that defining this macro might break existing codebases
@@ -164,189 +163,196 @@ enable or disable extended libc++ behavior.
when updating to a newer version of the library, since transitive includes
that your code was previously relying on may have been removed.
-C++17 Specific Configuration Macros
------------------------------------
-**_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**:
- This macro is used to re-enable `auto_ptr`.
+### C++17 Specific Configuration Macros
+
+**\_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**:
+
+: This macro is used to re-enable `auto_ptr`.
+
+**\_LIBCPP_ENABLE_CXX17_REMOVED_BINDERS**:
-**_LIBCPP_ENABLE_CXX17_REMOVED_BINDERS**:
- This macro is used to re-enable the `binder1st`, `binder2nd`,
+: This macro is used to re-enable the `binder1st`, `binder2nd`,
`pointer_to_unary_function`, `pointer_to_binary_function`, `mem_fun_t`,
`mem_fun1_t`, `mem_fun_ref_t`, `mem_fun1_ref_t`, `const_mem_fun_t`,
`const_mem_fun1_t`, `const_mem_fun_ref_t`, and `const_mem_fun1_ref_t`
class templates, and the `bind1st`, `bind2nd`, `mem_fun`, `mem_fun_ref`,
and `ptr_fun` functions.
-**_LIBCPP_ENABLE_CXX17_REMOVED_RANDOM_SHUFFLE**:
- This macro is used to re-enable the `random_shuffle` algorithm.
+**\_LIBCPP_ENABLE_CXX17_REMOVED_RANDOM_SHUFFLE**:
-**_LIBCPP_ENABLE_CXX17_REMOVED_UNARY_BINARY_FUNCTION**:
- This macro is used to re-enable `unary_function` and `binary_function`.
+: This macro is used to re-enable the `random_shuffle` algorithm.
-**_LIBCPP_ENABLE_CXX17_REMOVED_UNEXPECTED_FUNCTIONS**:
- This macro is used to re-enable `set_unexpected`, `get_unexpected`, and
+**\_LIBCPP_ENABLE_CXX17_REMOVED_UNARY_BINARY_FUNCTION**:
+
+: This macro is used to re-enable `unary_function` and `binary_function`.
+
+**\_LIBCPP_ENABLE_CXX17_REMOVED_UNEXPECTED_FUNCTIONS**:
+
+: This macro is used to re-enable `set_unexpected`, `get_unexpected`, and
`unexpected`.
-C++20 Specific Configuration Macros
------------------------------------
-**_LIBCPP_ENABLE_CXX20_REMOVED_BINDER_TYPEDEFS**:
- This macro is used to re-enable the `argument_type`, `result_type`,
+### C++20 Specific Configuration Macros
+
+**\_LIBCPP_ENABLE_CXX20_REMOVED_BINDER_TYPEDEFS**:
+
+: This macro is used to re-enable the `argument_type`, `result_type`,
`first_argument_type`, and `second_argument_type` members of class
templates such as `plus`, `logical_not`, `hash`, and `owner_less`.
-**_LIBCPP_ENABLE_CXX20_REMOVED_NEGATORS**:
- This macro is used to re-enable `not1`, `not2`, `unary_negate`,
+**\_LIBCPP_ENABLE_CXX20_REMOVED_NEGATORS**:
+
+: This macro is used to re-enable `not1`, `not2`, `unary_negate`,
and `binary_negate`.
-**_LIBCPP_ENABLE_CXX20_REMOVED_RAW_STORAGE_ITERATOR**:
- This macro is used to re-enable `raw_storage_iterator`.
+**\_LIBCPP_ENABLE_CXX20_REMOVED_RAW_STORAGE_ITERATOR**:
+
+: This macro is used to re-enable `raw_storage_iterator`.
+
+**\_LIBCPP_ENABLE_CXX20_REMOVED_SHARED_PTR_UNIQUE**:
+
+: This macro is used to re-enable the function
+ `std::shared_ptr<...>::unique()`.
-**_LIBCPP_ENABLE_CXX20_REMOVED_SHARED_PTR_UNIQUE**:
- This macro is used to re-enable the function
- ``std::shared_ptr<...>::unique()``.
+**\_LIBCPP_ENABLE_CXX20_REMOVED_TEMPORARY_BUFFER**:
-**_LIBCPP_ENABLE_CXX20_REMOVED_TEMPORARY_BUFFER**:
- This macro is used to re-enable `get_temporary_buffer` and `return_temporary_buffer`.
+: This macro is used to re-enable `get_temporary_buffer` and `return_temporary_buffer`.
-**_LIBCPP_ENABLE_CXX20_REMOVED_TYPE_TRAITS**:
- This macro is used to re-enable `is_literal_type`, `is_literal_type_v`,
+**\_LIBCPP_ENABLE_CXX20_REMOVED_TYPE_TRAITS**:
+
+: This macro is used to re-enable `is_literal_type`, `is_literal_type_v`,
`result_of` and `result_of_t`.
-**_LIBCPP_ENABLE_CXX20_REMOVED_UNCAUGHT_EXCEPTION**:
- This macro is used to re-enable `uncaught_exception`.
+**\_LIBCPP_ENABLE_CXX20_REMOVED_UNCAUGHT_EXCEPTION**:
+
+: This macro is used to re-enable `uncaught_exception`.
+
+### C++26 Specific Configuration Macros
+
+**\_LIBCPP_ENABLE_CXX26_REMOVED_ALLOCATOR_MEMBERS**:
-C++26 Specific Configuration Macros
------------------------------------
+: This macro is used to re-enable redundant member of `allocator<T>::is_always_equal`.
-**_LIBCPP_ENABLE_CXX26_REMOVED_ALLOCATOR_MEMBERS**:
- This macro is used to re-enable redundant member of ``allocator<T>::is_always_equal``.
+**\_LIBCPP_ENABLE_CXX26_REMOVED_CODECVT**:
-**_LIBCPP_ENABLE_CXX26_REMOVED_CODECVT**:
- This macro is used to re-enable all named declarations in ``<codecvt>``.
+: This macro is used to re-enable all named declarations in `<codecvt>`.
-**_LIBCPP_ENABLE_CXX26_REMOVED_STRING_RESERVE**:
- This macro is used to re-enable the function
- ``std::basic_string<...>::reserve()``.
+**\_LIBCPP_ENABLE_CXX26_REMOVED_STRING_RESERVE**:
-**_LIBCPP_ENABLE_CXX26_REMOVED_STRSTREAM**:
- This macro is used to re-enable all named declarations in ``<strstream>``.
+: This macro is used to re-enable the function
+ `std::basic_string<...>::reserve()`.
-**_LIBCPP_ENABLE_CXX26_REMOVED_WSTRING_CONVERT**:
- This macro is used to re-enable the ``wstring_convert`` and ``wbuffer_convert``
- in ``<locale>``.
+**\_LIBCPP_ENABLE_CXX26_REMOVED_STRSTREAM**:
-Libc++ Extensions
-=================
+: This macro is used to re-enable all named declarations in `<strstream>`.
+
+**\_LIBCPP_ENABLE_CXX26_REMOVED_WSTRING_CONVERT**:
+
+: This macro is used to re-enable the `wstring_convert` and `wbuffer_convert`
+ in `<locale>`.
+
+## Libc++ Extensions
This section documents various extensions provided by libc++
and any information regarding how to use them.
-Extended integral type support
-------------------------------
+### Extended integral type support
Several platforms support types that are not specified in the C++ standard,
-such as the 128-bit integral types ``__int128_t`` and ``__uint128_t``.
+such as the 128-bit integral types `__int128_t` and `__uint128_t`.
As an extension, libc++ does a best-effort attempt to support these types like
other integral types, by supporting them notably in:
-* ``<bits>``
-* ``<charconv>``
-* ``<functional>``
-* ``<format>``
-* ``<random>``
-* ``<type_traits>``
+- `<bits>`
+- `<charconv>`
+- `<functional>`
+- `<format>`
+- `<random>`
+- `<type_traits>`
-Additional types supported in random distributions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Additional types supported in random distributions
-The `C++ Standard <http://eel.is/c++draft/rand#req.genl-1.5>`_ mentions that instantiating several random number
-distributions with types other than ``short``, ``int``, ``long``, ``long long``, and their unsigned versions is
-undefined. As an extension, libc++ supports instantiating ``binomial_distribution``, ``discrete_distribution``,
-``geometric_distribution``, ``negative_binomial_distribution``, ``poisson_distribution``, and ``uniform_int_distribution``
-with ``int8_t``, ``__int128_t`` and their unsigned versions.
+The [C++ Standard](http://eel.is/c++draft/rand#req.genl-1.5) mentions that instantiating several random number
+distributions with types other than `short`, `int`, `long`, `long long`, and their unsigned versions is
+undefined. As an extension, libc++ supports instantiating `binomial_distribution`, `discrete_distribution`,
+`geometric_distribution`, `negative_binomial_distribution`, `poisson_distribution`, and `uniform_int_distribution`
+with `int8_t`, `__int128_t` and their unsigned versions.
-Extensions to ``<format>``
---------------------------
+### Extensions to `<format>`
-The exposition only type ``basic-format-string`` and its typedefs
-``format-string`` and ``wformat-string`` became ``basic_format_string``,
-``format_string``, and ``wformat_string`` in C++23. Libc++ makes these types
+The exposition only type `basic-format-string` and its typedefs
+`format-string` and `wformat-string` became `basic_format_string`,
+`format_string`, and `wformat_string` in C++23. Libc++ makes these types
available in C++20 as an extension.
-For padding Unicode strings the ``format`` library relies on the Unicode standard.
+For padding Unicode strings the `format` library relies on the Unicode standard.
Libc++ retroactively updates the Unicode standard in older C++ versions.
This allows the library to have better estimates for newly introduced Unicode code points,
without requiring the user to use the latest C++ version in their code base.
-In C++26 formatting pointers gained a type ``P`` and allows to use
+In C++26 formatting pointers gained a type `P` and allows to use
zero-padding. These options have been retroactively applied to C++20.
-Extensions to the C++23 modules ``std`` and ``std.compat``
-----------------------------------------------------------
+### Extensions to the C++23 modules `std` and `std.compat`
-Like other major implementations, libc++ provides C++23 modules ``std`` and
-``std.compat`` in C++20 as an extension.
+Like other major implementations, libc++ provides C++23 modules `std` and
+`std.compat` in C++20 as an extension.
-Constant-initialized std::string
---------------------------------
+### Constant-initialized std::string
-As an implementation-specific optimization, ``std::basic_string`` (``std::string``,
-``std::wstring``, etc.) may either store the string data directly in the object, or else store a
+As an implementation-specific optimization, `std::basic_string` (`std::string`,
+`std::wstring`, etc.) may either store the string data directly in the object, or else store a
pointer to heap-allocated memory, depending on the length of the string.
-As of C++20, the constructors are now declared ``constexpr``, which permits strings to be used
+As of C++20, the constructors are now declared `constexpr`, which permits strings to be used
during constant-evaluation time. In libc++, as in other common implementations, it is also possible
-to constant-initialize a string object (e.g. via declaring a variable with ``constinit`` or
-``constexpr``), but only if the string is short enough to not require a heap allocation.
+to constant-initialize a string object (e.g. via declaring a variable with `constinit` or
+`constexpr`), but only if the string is short enough to not require a heap allocation.
Reliance upon this is discouraged in portable code, as the allowed length differs based on the
standard-library implementation and also based on whether the platform uses 32-bit or 64-bit
pointers.
-.. code-block:: cpp
+```cpp
+// Non-portable: 11-char string works on 64-bit libc++, but not on 32-bit.
+constinit std::string x = "hello world";
- // Non-portable: 11-char string works on 64-bit libc++, but not on 32-bit.
- constinit std::string x = "hello world";
+// Prefer to use string_view, or remove constinit/constexpr from the variable definition:
+constinit std::string_view x = "hello world";
+std::string_view y = "hello world";
+```
- // Prefer to use string_view, or remove constinit/constexpr from the variable definition:
- constinit std::string_view x = "hello world";
- std::string_view y = "hello world";
+(turning-off-asan)=
-.. _turning-off-asan:
+### Turning off ASan annotation in containers
-Turning off ASan annotation in containers
------------------------------------------
-
-``__asan_annotate_container_with_allocator`` is a customization point to allow users to disable
-`Address Sanitizer annotations for containers <https://github.com/google/sanitizers/wiki/AddressSanitizerContainerOverflow>`_ for specific allocators.
+`__asan_annotate_container_with_allocator` is a customization point to allow users to disable
+[Address Sanitizer annotations for containers](https://github.com/google/sanitizers/wiki/AddressSanitizerContainerOverflow) for specific allocators.
This may be necessary for allocators that access allocated memory.
-This customization point exists only when ``_LIBCPP_HAS_ASAN_CONTAINER_ANNOTATIONS_FOR_ALL_ALLOCATORS`` Feature Test Macro is defined.
+This customization point exists only when `_LIBCPP_HAS_ASAN_CONTAINER_ANNOTATIONS_FOR_ALL_ALLOCATORS` Feature Test Macro is defined.
-For allocators not running destructors, it is also possible to `bulk-unpoison memory <https://github.com/google/sanitizers/wiki/AddressSanitizerManualPoisoning>`_
+For allocators not running destructors, it is also possible to [bulk-unpoison memory](https://github.com/google/sanitizers/wiki/AddressSanitizerManualPoisoning)
instead of disabling annotations altogether.
-The struct may be specialized for user-defined allocators. It is a `Cpp17UnaryTypeTrait <http://eel.is/c++draft/type.traits#meta.rqmts>`_
-with a base characteristic of ``true_type`` if the container is allowed to use annotations and ``false_type`` otherwise.
-
-The annotations for a ``user_allocator`` can be disabled like this:
+The struct may be specialized for user-defined allocators. It is a [Cpp17UnaryTypeTrait](http://eel.is/c++draft/type.traits#meta.rqmts)
+with a base characteristic of `true_type` if the container is allowed to use annotations and `false_type` otherwise.
-.. code-block:: cpp
+The annotations for a `user_allocator` can be disabled like this:
- #ifdef _LIBCPP_HAS_ASAN_CONTAINER_ANNOTATIONS_FOR_ALL_ALLOCATORS
- template <class T>
- struct std::__asan_annotate_container_with_allocator<user_allocator<T>> : std::false_type {};
- #endif
+```cpp
+#ifdef _LIBCPP_HAS_ASAN_CONTAINER_ANNOTATIONS_FOR_ALL_ALLOCATORS
+template <class T>
+struct std::__asan_annotate_container_with_allocator<user_allocator<T>> : std::false_type {};
+#endif
+```
-Why may I want to turn it off?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Why may I want to turn it off?
There are a few reasons why you may want to turn off annotations for an allocator.
Unpoisoning may not be an option, if (for example) you are not maintaining the allocator.
-* You are using allocator, which does not call destructor during deallocation.
-* You are aware that memory allocated with an allocator may be accessed, even when unused by container.
+- You are using allocator, which does not call destructor during deallocation.
+- You are aware that memory allocated with an allocator may be accessed, even when unused by container.
-Support for compiler extensions
--------------------------------
+### Support for compiler extensions
Clang, GCC and other compilers all provide their own set of language extensions. These extensions
have often been developed without particular consideration for their interaction with the library,
@@ -354,89 +360,82 @@ and as such, libc++ does not go out of its way to support them. The library may
compiler extensions which would then be documented explicitly, but the basic expectation should be
that no special support is provided for arbitrary compiler extensions.
-Platform specific behavior
-==========================
+## Platform specific behavior
-Windows
--------
+### Windows
-The ``stdout``, ``stderr``, and ``stdin`` file streams can be placed in
-Unicode mode by a suitable call to ``_setmode()``. When in this mode,
+The `stdout`, `stderr`, and `stdin` file streams can be placed in
+Unicode mode by a suitable call to `_setmode()`. When in this mode,
the sequence of bytes read from, or written to, these streams is interpreted
-as a sequence of little-endian ``wchar_t`` elements. Thus, use of
-``std::cout``, ``std::cerr``, or ``std::cin`` with streams in Unicode mode
+as a sequence of little-endian `wchar_t` elements. Thus, use of
+`std::cout`, `std::cerr`, or `std::cin` with streams in Unicode mode
will not behave as they usually do since bytes read or written won't be
-interpreted as individual ``char`` elements. However, ``std::wcout``,
-``std::wcerr``, and ``std::wcin`` will behave as expected.
+interpreted as individual `char` elements. However, `std::wcout`,
+`std::wcerr`, and `std::wcin` will behave as expected.
-Wide character stream such as ``std::wcin`` or ``std::wcout`` imbued with a
+Wide character stream such as `std::wcin` or `std::wcout` imbued with a
locale behave differently than they otherwise do. By default, wide character
streams don't convert wide characters but input/output them as is. If a
specific locale is imbued, the IO with the underlying stream happens with
-regular ``char`` elements, which are converted to/from wide characters
+regular `char` elements, which are converted to/from wide characters
according to the locale. Note that this will not behave as expected if the
stream has been set in Unicode mode.
-
-Third-party Integrations
-========================
+## Third-party Integrations
Libc++ provides integration with a few third-party tools.
-Debugging libc++ internals in LLDB
-----------------------------------
+### Debugging libc++ internals in LLDB
LLDB hides the implementation details of libc++ by default.
-E.g., when setting a breakpoint in a comparator passed to ``std::sort``, the
+E.g., when setting a breakpoint in a comparator passed to `std::sort`, the
backtrace will read as
-.. code-block::
-
- (lldb) thread backtrace
- * thread #1, name = 'a.out', stop reason = breakpoint 3.1
- * frame #0: 0x000055555555520e a.out`my_comparator(a=1, b=8) at test-std-sort.cpp:6:3
- frame #7: 0x0000555555555615 a.out`void std::__1::sort[abi:ne200000]<std::__1::__wrap_iter<int*>, bool (*)(int, int)>(__first=(item = 8), __last=(item = 0), __comp=(a.out`my_less(int, int) at test-std-sort.cpp:5)) at sort.h:1003:3
- frame #8: 0x000055555555531a a.out`main at test-std-sort.cpp:24:3
+```
+(lldb) thread backtrace
+* thread #1, name = 'a.out', stop reason = breakpoint 3.1
+ * frame #0: 0x000055555555520e a.out`my_comparator(a=1, b=8) at test-std-sort.cpp:6:3
+ frame #7: 0x0000555555555615 a.out`void std::__1::sort[abi:ne200000]<std::__1::__wrap_iter<int*>, bool (*)(int, int)>(__first=(item = 8), __last=(item = 0), __comp=(a.out`my_less(int, int) at test-std-sort.cpp:5)) at sort.h:1003:3
+ frame #8: 0x000055555555531a a.out`main at test-std-sort.cpp:24:3
+```
-Note how the caller of ``my_comparator`` is shown as ``std::sort``. Looking at
+Note how the caller of `my_comparator` is shown as `std::sort`. Looking at
the frame numbers, we can see that frames #1 until #6 were hidden. Those frames
-represent internal implementation details such as ``__sort4`` and similar
+represent internal implementation details such as `__sort4` and similar
utility functions.
-To also show those implementation details, use ``thread backtrace -u``.
-Alternatively, to disable those compact backtraces, use ``frame recognizer list``
-and ``frame recognizer disable`` on the "libc++ frame recognizer".
+To also show those implementation details, use `thread backtrace -u`.
+Alternatively, to disable those compact backtraces, use `frame recognizer list`
+and `frame recognizer disable` on the "libc++ frame recognizer".
Futhermore, stepping into libc++ functions is disabled by default. This is controlled via the
-setting ``target.process.thread.step-avoid-regexp`` which defaults to ``^std::`` and can be
-disabled using ``settings set target.process.thread.step-avoid-regexp ""``.
+setting `target.process.thread.step-avoid-regexp` which defaults to `^std::` and can be
+disabled using `settings set target.process.thread.step-avoid-regexp ""`.
-GDB Pretty printers for libc++
-------------------------------
+### GDB Pretty printers for libc++
GDB does not support pretty-printing of libc++ symbols by default. However, libc++ does
provide pretty-printers itself. Those can be used as:
-.. code-block:: bash
-
- $ gdb -ex "source <libcxx>/utils/gdb/libcxx/printers.py" \
- -ex "python register_libcxx_printer_loader()" \
- <args>
-
+```bash
+$ gdb -ex "source <libcxx>/utils/gdb/libcxx/printers.py" \
+ -ex "python register_libcxx_printer_loader()" \
+ <args>
+```
-.. _include-what-you-use:
+(include-what-you-use)=
-include-what-you-use (IWYU)
----------------------------
+### include-what-you-use (IWYU)
-libc++ provides an IWYU `mapping file <https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/IWYUMappings.md>`_,
+libc++ provides an IWYU [mapping file](https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/IWYUMappings.md),
which drastically improves the accuracy of the tool when using libc++. To use the mapping file with
IWYU, you should run the tool like so:
-.. code-block:: bash
+```bash
+$ include-what-you-use -Xiwyu --mapping_file=/path/to/libcxx/include/libcxx.imp file.cpp
+```
- $ include-what-you-use -Xiwyu --mapping_file=/path/to/libcxx/include/libcxx.imp file.cpp
+If you would prefer to not use that flag, then you can replace `/path/to/include-what-you-use/share/libcxx.imp`
+file with the libc++-provided `libcxx.imp` file.
-If you would prefer to not use that flag, then you can replace ``/path/to/include-what-you-use/share/libcxx.imp``
-file with the libc++-provided ``libcxx.imp`` file.
diff --git a/libcxx/docs/VendorDocumentation.md b/libcxx/docs/VendorDocumentation.md
index 38fd5ac73e2229..4ff5472ca5ea36 100644
--- a/libcxx/docs/VendorDocumentation.md
+++ b/libcxx/docs/VendorDocumentation.md
@@ -1,50 +1,49 @@
-.. _VendorDocumentation:
+(vendordocumentation)=
-====================
-Vendor Documentation
-====================
+# Vendor Documentation
-.. contents::
- :local:
+```{contents}
+:local: true
+```
The instructions on this page are aimed at vendors who ship libc++ as part of an
operating system distribution, a toolchain or similar shipping vehicles. If you
are a user merely trying to use libc++ in your program, you most likely want to
refer to your vendor's documentation, or to the general user documentation
-:ref:`here <user-documentation>`.
+{ref}`here <user-documentation>`.
-.. warning::
- If your operating system already provides libc++, it is important to be careful
- not to replace it. Replacing your system's libc++ installation could render it
- non-functional. Use the CMake option ``CMAKE_INSTALL_PREFIX`` to select a safe
- place to install libc++.
+:::{warning}
+If your operating system already provides libc++, it is important to be careful
+not to replace it. Replacing your system's libc++ installation could render it
+non-functional. Use the CMake option `CMAKE_INSTALL_PREFIX` to select a safe
+place to install libc++.
+:::
-
-The default build
-=================
+## The default build
The default way of building libc++, libc++abi and libunwind is to root the CMake
-invocation at ``<monorepo>/runtimes``. While those projects are under the LLVM
+invocation at `<monorepo>/runtimes`. While those projects are under the LLVM
umbrella, they are different in nature from other build tools, so it makes sense
to treat them as a separate set of entities. The default build can be achieved
with the following CMake invocation:
-.. code-block:: bash
-
- $ git clone https://github.com/llvm/llvm-project.git
- $ cd llvm-project
- $ mkdir build
- $ cmake -G Ninja -S runtimes -B build -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind" # Configure
- $ ninja -C build cxx cxxabi unwind # Build
- $ ninja -C build check-cxx check-cxxabi check-unwind # Test
- $ ninja -C build install-cxx install-cxxabi install-unwind # Install
-
-.. note::
- See :ref:`Vendor Configuration Options` below for more configuration options.
-
-After building the various ``install-XXX`` targets, shared libraries for libc++, libc++abi and
-libunwind should now be present in ``<CMAKE_INSTALL_PREFIX>/lib``, and headers in
-``<CMAKE_INSTALL_PREFIX>/include/c++/v1``. See the instructions below for information on how
+```bash
+$ git clone https://github.com/llvm/llvm-project.git
+$ cd llvm-project
+$ mkdir build
+$ cmake -G Ninja -S runtimes -B build -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind" # Configure
+$ ninja -C build cxx cxxabi unwind # Build
+$ ninja -C build check-cxx check-cxxabi check-unwind # Test
+$ ninja -C build install-cxx install-cxxabi install-unwind # Install
+```
+
+:::{note}
+See {ref}`Vendor Configuration Options` below for more configuration options.
+:::
+
+After building the various `install-XXX` targets, shared libraries for libc++, libc++abi and
+libunwind should now be present in `<CMAKE_INSTALL_PREFIX>/lib`, and headers in
+`<CMAKE_INSTALL_PREFIX>/include/c++/v1`. See the instructions below for information on how
to use this libc++ over the default one.
In the default configuration, the runtimes will be built using the compiler available by default
@@ -52,377 +51,369 @@ on your system. Of course, you can change what compiler is being used with the u
variables. If you wish to build the runtimes from a just-built Clang, the bootstrapping build
explained below makes this task easy.
-Using the just-built libc++
----------------------------
+### Using the just-built libc++
Most compilers provide a way to disable the default behavior for finding the standard library and
to override it with custom paths. With Clang, this can be done with:
-.. code-block:: bash
-
- $ clang++ -nostdinc++ -isystem <install>/include/c++/v1 \
- -nostdlib++ -L <install>/lib -lc++ \
- -Wl,-rpath,<install>/lib \
- test.cpp
+```bash
+$ clang++ -nostdinc++ -isystem <install>/include/c++/v1 \
+ -nostdlib++ -L <install>/lib -lc++ \
+ -Wl,-rpath,<install>/lib \
+ test.cpp
+```
-The option ``-Wl,-rpath,<install>/lib`` adds a runtime library search path, which causes the system's
-dynamic linker to look for libc++ in ``<install>/lib`` whenever the program is loaded.
+The option `-Wl,-rpath,<install>/lib` adds a runtime library search path, which causes the system's
+dynamic linker to look for libc++ in `<install>/lib` whenever the program is loaded.
-.. note::
- If the runtimes were built using the "per-target runtime directory" layout,
- they will be in ``<install>/lib/<target-triple>`` instead of ``<install>/lib``.
- In this case, use the former path for all library paths in the command above
- (the path to include files does not change).
+:::{note}
+If the runtimes were built using the "per-target runtime directory" layout,
+they will be in `<install>/lib/<target-triple>` instead of `<install>/lib`.
+In this case, use the former path for all library paths in the command above
+(the path to include files does not change).
+:::
-The Bootstrapping build
-=======================
+## The Bootstrapping build
It is possible to build Clang and then build the runtimes using that just-built compiler in a
single CMake invocation. This is usually the correct way to build the runtimes when putting together
a toolchain, or when the system compiler is not adequate to build them (too old, unsupported, etc.).
To do this, use the following CMake invocation, and in particular notice how we're now rooting the
-CMake invocation at ``<monorepo>/llvm``:
-
-.. code-block:: bash
-
- $ mkdir build
- $ # Configure
- $ cmake -G Ninja -S llvm -B build \
- -DCMAKE_BUILD_TYPE=RelWithDebInfo \
- -DLLVM_ENABLE_PROJECTS="clang" \
- -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind;compiler-rt" \
- -DLLVM_RUNTIME_TARGETS="<target-triple>"
- $ ninja -C build runtimes # Build
- $ ninja -C build check-runtimes # Test
- $ ninja -C build install-runtimes # Install
-
-.. note::
- - This type of build is also commonly called a "Runtimes build", but we would like to move
- away from that terminology, which is too confusing.
-
- - Adding the `--fresh` flag to the top-level cmake invocation in a bootstrapping build *will not*
- freshen the cmake cache of any of the enabled runtimes.
-
-
-.. _Vendor Configuration Options:
-
-Vendor Configuration Options
-============================
+CMake invocation at `<monorepo>/llvm`:
+
+```bash
+$ mkdir build
+$ # Configure
+$ cmake -G Ninja -S llvm -B build \
+ -DCMAKE_BUILD_TYPE=RelWithDebInfo \
+ -DLLVM_ENABLE_PROJECTS="clang" \
+ -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind;compiler-rt" \
+ -DLLVM_RUNTIME_TARGETS="<target-triple>"
+$ ninja -C build runtimes # Build
+$ ninja -C build check-runtimes # Test
+$ ninja -C build install-runtimes # Install
+```
+
+:::{note}
+- This type of build is also commonly called a "Runtimes build", but we would like to move
+ away from that terminology, which is too confusing.
+- Adding the `--fresh` flag to the top-level cmake invocation in a bootstrapping build *will not*
+ freshen the cmake cache of any of the enabled runtimes.
+:::
+
+(vendor-configuration-options)=
+
+## Vendor Configuration Options
This section documents configuration options that can be used by vendors when building the library.
These options provide a great deal of flexibility to customize libc++, such as selecting the ABI in
use, whether some features are provided, etc.
-.. warning::
- Many of these CMake options are tied to configuration macros with a corresponding name in the source
- code. However, these configuration macros are not intended to be customized by users directly, since
- many of them require the library to be built with a matching configuration. If you don't build libc++
- yourself, you should not use the options documented here.
-
-General purpose options
------------------------
-
-.. option:: LIBCXX_INSTALL_LIBRARY:BOOL
-
- **Default**: ``ON``
-
- Toggle the installation of the library portion of libc++.
-
-.. option:: LIBCXX_INSTALL_HEADERS:BOOL
-
- **Default**: ``ON``
-
- Toggle the installation of the libc++ headers.
-
-.. option:: LIBCXX_INSTALL_MODULES:BOOL
-
- **Default**: ``ON``
-
- Toggle the installation of the experimental libc++ module sources.
-
-.. option:: LIBCXX_ENABLE_SHARED:BOOL
-
- **Default**: ``ON``
-
- Build libc++ as a shared library. Either `LIBCXX_ENABLE_SHARED` or
- `LIBCXX_ENABLE_STATIC` has to be enabled.
-
-.. option:: LIBCXX_ENABLE_STATIC:BOOL
-
- **Default**: ``ON``
-
- Build libc++ as a static library. Either `LIBCXX_ENABLE_SHARED` or
- `LIBCXX_ENABLE_STATIC` has to be enabled.
-
-.. option:: LIBCXX_LIBDIR_SUFFIX:STRING
-
- Extra suffix to append to the directory where libraries are to be installed.
- This option overrides `LLVM_LIBDIR_SUFFIX`.
-
-.. option:: LIBCXX_HERMETIC_STATIC_LIBRARY:BOOL
-
- **Default**: ``OFF``
-
- Do not export any symbols from the static libc++ library.
- This is useful when the static libc++ library is being linked into shared
- libraries that may be used in with other shared libraries that use different
- C++ library. We want to avoid exporting any libc++ symbols in that case.
+:::{warning}
+Many of these CMake options are tied to configuration macros with a corresponding name in the source
+code. However, these configuration macros are not intended to be customized by users directly, since
+many of them require the library to be built with a matching configuration. If you don't build libc++
+yourself, you should not use the options documented here.
+:::
-.. option:: LIBCXX_ENABLE_FILESYSTEM:BOOL
+### General purpose options
- **Default**: ``ON``
+:::{option} LIBCXX_INSTALL_LIBRARY:BOOL
+**Default**: `ON`
- This option can be used to enable or disable the filesystem components on
- platforms that may not support them.
+Toggle the installation of the library portion of libc++.
+:::
-.. option:: LIBCXX_ENABLE_WIDE_CHARACTERS:BOOL
+:::{option} LIBCXX_INSTALL_HEADERS:BOOL
+**Default**: `ON`
- **Default**: ``ON``
+Toggle the installation of the libc++ headers.
+:::
- This option can be used to disable support for ``wchar_t`` in the library. It also
- allows the library to work on top of a C Standard Library that does not provide
- support for ``wchar_t``. This is especially useful in embedded settings where
- C Standard Libraries don't always provide all the usual bells and whistles.
+:::{option} LIBCXX_INSTALL_MODULES:BOOL
+**Default**: `ON`
-.. option:: LIBCXX_ENABLE_TIME_ZONE_DATABASE:BOOL
+Toggle the installation of the experimental libc++ module sources.
+:::
- **Default**: ``ON``
+:::{option} LIBCXX_ENABLE_SHARED:BOOL
+**Default**: `ON`
- Whether to include support for time zones in the library. Disabling
- time zone support can be useful when porting to platforms that don't
- ship the IANA time zone database. When time zones are not supported,
- time zone support in <chrono> will be disabled.
+Build libc++ as a shared library. Either `LIBCXX_ENABLE_SHARED` or
+`LIBCXX_ENABLE_STATIC` has to be enabled.
+:::
-.. option:: LIBCXX_INSTALL_LIBRARY_DIR:PATH
+:::{option} LIBCXX_ENABLE_STATIC:BOOL
+**Default**: `ON`
- **Default**: ``lib${LIBCXX_LIBDIR_SUFFIX}``
+Build libc++ as a static library. Either `LIBCXX_ENABLE_SHARED` or
+`LIBCXX_ENABLE_STATIC` has to be enabled.
+:::
- Path where built libc++ libraries should be installed. If a relative path,
- relative to ``CMAKE_INSTALL_PREFIX``.
+:::{option} LIBCXX_LIBDIR_SUFFIX:STRING
+Extra suffix to append to the directory where libraries are to be installed.
+This option overrides `LLVM_LIBDIR_SUFFIX`.
+:::
-.. option:: LIBCXX_INSTALL_INCLUDE_DIR:PATH
+:::{option} LIBCXX_HERMETIC_STATIC_LIBRARY:BOOL
+**Default**: `OFF`
- **Default**: ``include/c++/v1``
+Do not export any symbols from the static libc++ library.
+This is useful when the static libc++ library is being linked into shared
+libraries that may be used in with other shared libraries that use different
+C++ library. We want to avoid exporting any libc++ symbols in that case.
+:::
- Path where target-agnostic libc++ headers should be installed. If a relative
- path, relative to ``CMAKE_INSTALL_PREFIX``.
+:::{option} LIBCXX_ENABLE_FILESYSTEM:BOOL
+**Default**: `ON`
-.. option:: LIBCXX_INSTALL_INCLUDE_TARGET_DIR:PATH
+This option can be used to enable or disable the filesystem components on
+platforms that may not support them.
+:::
- **Default**: ``include/c++/v1`` or
- ``include/${LLVM_DEFAULT_TARGET_TRIPLE}/c++/v1``
+:::{option} LIBCXX_ENABLE_WIDE_CHARACTERS:BOOL
+**Default**: `ON`
- Path where target-specific libc++ headers should be installed. If a relative
- path, relative to ``CMAKE_INSTALL_PREFIX``.
+This option can be used to disable support for `wchar_t` in the library. It also
+allows the library to work on top of a C Standard Library that does not provide
+support for `wchar_t`. This is especially useful in embedded settings where
+C Standard Libraries don't always provide all the usual bells and whistles.
+:::
-.. option:: LIBCXX_SHARED_OUTPUT_NAME:STRING
+:::{option} LIBCXX_ENABLE_TIME_ZONE_DATABASE:BOOL
+**Default**: `ON`
- **Default**: ``c++``
+Whether to include support for time zones in the library. Disabling
+time zone support can be useful when porting to platforms that don't
+ship the IANA time zone database. When time zones are not supported,
+time zone support in \<chrono> will be disabled.
+:::
- Output name for the shared libc++ runtime library.
+:::{option} LIBCXX_INSTALL_LIBRARY_DIR:PATH
+**Default**: `lib${LIBCXX_LIBDIR_SUFFIX}`
-.. option:: {LIBCXX,LIBCXXABI,LIBUNWIND}_ADDITIONAL_COMPILE_FLAGS:STRING
+Path where built libc++ libraries should be installed. If a relative path,
+relative to `CMAKE_INSTALL_PREFIX`.
+:::
- **Default**: ``""``
+:::{option} LIBCXX_INSTALL_INCLUDE_DIR:PATH
+**Default**: `include/c++/v1`
- Additional compile flags to use when building the runtimes. This should be a CMake ``;``-delimited list of individual
- compiler options to use. For options that must be passed as-is to the compiler without deduplication (e.g.
- ``-Xclang -foo`` option groups), consider using ``SHELL:`` as `documented here <https://cmake.org/cmake/help/latest/command/add_compile_options.html#option-de-duplication>`_.
+Path where target-agnostic libc++ headers should be installed. If a relative
+path, relative to `CMAKE_INSTALL_PREFIX`.
+:::
-.. option:: LIBCXX_ADDITIONAL_LIBRARIES:STRING
+:::{option} LIBCXX_INSTALL_INCLUDE_TARGET_DIR:PATH
+**Default**: `include/c++/v1` or
+`include/${LLVM_DEFAULT_TARGET_TRIPLE}/c++/v1`
- **Default**: ``""``
+Path where target-specific libc++ headers should be installed. If a relative
+path, relative to `CMAKE_INSTALL_PREFIX`.
+:::
- Additional libraries libc++ is linked to which can be provided in cache.
+:::{option} LIBCXX_SHARED_OUTPUT_NAME:STRING
+**Default**: `c++`
-.. option:: LIBCXX_ENABLE_EXCEPTIONS:BOOL
+Output name for the shared libc++ runtime library.
+:::
- **Default**: ``ON``
+:::{option} {LIBCXX,LIBCXXABI,LIBUNWIND}_ADDITIONAL_COMPILE_FLAGS:STRING
+**Default**: `""`
- Build libc++ with exception support.
+Additional compile flags to use when building the runtimes. This should be a CMake `;`-delimited list of individual
+compiler options to use. For options that must be passed as-is to the compiler without deduplication (e.g.
+`-Xclang -foo` option groups), consider using `SHELL:` as [documented here](https://cmake.org/cmake/help/latest/command/add_compile_options.html#option-de-duplication).
+:::
-.. option:: LIBCXX_ENABLE_RTTI:BOOL
+:::{option} LIBCXX_ADDITIONAL_LIBRARIES:STRING
+**Default**: `""`
- **Default**: ``ON``
+Additional libraries libc++ is linked to which can be provided in cache.
+:::
- Build libc++ with run time type information.
- This option may only be set to OFF when LIBCXX_ENABLE_EXCEPTIONS=OFF.
+:::{option} LIBCXX_ENABLE_EXCEPTIONS:BOOL
+**Default**: `ON`
-.. option:: LIBCXX_INCLUDE_TESTS:BOOL
+Build libc++ with exception support.
+:::
- **Default**: ``ON`` (or value of ``LLVM_INCLUDE_TESTS``)
+:::{option} LIBCXX_ENABLE_RTTI:BOOL
+**Default**: `ON`
- Build the libc++ test suite, which includes various types of tests like conformance
- tests, vendor-specific tests and benchmarks.
+Build libc++ with run time type information.
+This option may only be set to OFF when LIBCXX_ENABLE_EXCEPTIONS=OFF.
+:::
-.. option:: LIBCXX_INCLUDE_BENCHMARKS:BOOL
+:::{option} LIBCXX_INCLUDE_TESTS:BOOL
+**Default**: `ON` (or value of `LLVM_INCLUDE_TESTS`)
- **Default**: ``ON``
+Build the libc++ test suite, which includes various types of tests like conformance
+tests, vendor-specific tests and benchmarks.
+:::
- Build the libc++ benchmark tests and the Google Benchmark library needed
- to support them.
+:::{option} LIBCXX_INCLUDE_BENCHMARKS:BOOL
+**Default**: `ON`
-.. option:: LIBCXX_ASSERTION_HANDLER_FILE:PATH
+Build the libc++ benchmark tests and the Google Benchmark library needed
+to support them.
+:::
- **Default**:: ``"${CMAKE_CURRENT_SOURCE_DIR}/vendor/llvm/default_assertion_handler.in"``
+:::{option} LIBCXX_ASSERTION_HANDLER_FILE:PATH
+**Default**:: `"${CMAKE_CURRENT_SOURCE_DIR}/vendor/llvm/default_assertion_handler.in"`
- Specify the path to a header that contains a custom implementation of the
- assertion handler that gets invoked when a hardening assertion fails. If
- provided, this header will be included by the library, replacing the
- default assertion handler. If this is specified as a relative path, it
- is assumed to be relative to ``<monorepo>/libcxx``.
+Specify the path to a header that contains a custom implementation of the
+assertion handler that gets invoked when a hardening assertion fails. If
+provided, this header will be included by the library, replacing the
+default assertion handler. If this is specified as a relative path, it
+is assumed to be relative to `<monorepo>/libcxx`.
+:::
-ABI Specific Options
---------------------
+### ABI Specific Options
The following options allow building libc++ for a different ABI version.
-.. option:: LIBCXX_ABI_VERSION:STRING
+:::{option} LIBCXX_ABI_VERSION:STRING
+**Default**: `1`
- **Default**: ``1``
+Defines the target ABI version of libc++.
+:::
- Defines the target ABI version of libc++.
+:::{option} LIBCXX_ABI_UNSTABLE:BOOL
+**Default**: `OFF`
-.. option:: LIBCXX_ABI_UNSTABLE:BOOL
+Build the "unstable" ABI version of libc++. Includes all ABI changing features
+on top of the current stable version.
+:::
- **Default**: ``OFF``
+::::{option} LIBCXX_ABI_NAMESPACE:STRING
+**Default**: `__n` where `n` is the current ABI version.
- Build the "unstable" ABI version of libc++. Includes all ABI changing features
- on top of the current stable version.
+This option defines the name of the inline ABI versioning namespace. It can be used for building
+custom versions of libc++ with unique symbol names in order to prevent conflicts or ODR issues
+with other libc++ versions.
-.. option:: LIBCXX_ABI_NAMESPACE:STRING
+:::{warning}
+When providing a custom namespace, it's the vendor's responsibility to ensure the name won't cause
+conflicts with other names defined by libc++, both now and in the future. In particular, inline
+namespaces of the form `__[0-9]+` could cause conflicts with future versions of the library,
+and so should be avoided.
+:::
+::::
- **Default**: ``__n`` where ``n`` is the current ABI version.
+:::{option} LIBCXX_ABI_DEFINES:STRING
+**Default**: `""`
- This option defines the name of the inline ABI versioning namespace. It can be used for building
- custom versions of libc++ with unique symbol names in order to prevent conflicts or ODR issues
- with other libc++ versions.
+A semicolon-separated list of ABI macros to persist in the site config header.
+See `include/__config` for the list of ABI macros.
+:::
- .. warning::
- When providing a custom namespace, it's the vendor's responsibility to ensure the name won't cause
- conflicts with other names defined by libc++, both now and in the future. In particular, inline
- namespaces of the form ``__[0-9]+`` could cause conflicts with future versions of the library,
- and so should be avoided.
+:::{option} LIBCXX_CXX_ABI:STRING
+**Values**: `none`, `libcxxabi`, `system-libcxxabi`, `libcxxrt`, `libstdc++`, `libsupc++`, `vcruntime`.
-.. option:: LIBCXX_ABI_DEFINES:STRING
+Select the ABI library to build libc++ against.
+:::
- **Default**: ``""``
+:::{option} LIBCXX_CXX_ABI_INCLUDE_PATHS:PATHS
+Provide additional search paths for the ABI library headers.
+:::
- A semicolon-separated list of ABI macros to persist in the site config header.
- See ``include/__config`` for the list of ABI macros.
+:::{option} LIBCXX_CXX_ABI_LIBRARY_PATH:PATH
+Provide the path to the ABI library that libc++ should link against. This is only
+useful when linking against an out-of-tree ABI library.
+:::
-.. option:: LIBCXX_CXX_ABI:STRING
+:::{option} LIBCXX_ENABLE_STATIC_ABI_LIBRARY:BOOL
+**Default**: `OFF`
- **Values**: ``none``, ``libcxxabi``, ``system-libcxxabi``, ``libcxxrt``, ``libstdc++``, ``libsupc++``, ``vcruntime``.
+If this option is enabled, libc++ will try and link the selected ABI library
+statically.
+:::
- Select the ABI library to build libc++ against.
+:::{option} LIBCXX_ENABLE_ABI_LINKER_SCRIPT:BOOL
+**Default**: `ON` by default on UNIX platforms other than Apple unless
+'LIBCXX_ENABLE_STATIC_ABI_LIBRARY' is ON. Otherwise the default value is `OFF`.
-.. option:: LIBCXX_CXX_ABI_INCLUDE_PATHS:PATHS
+This option generate and installs a linker script as `libc++.so` which
+links the correct ABI library.
+:::
- Provide additional search paths for the ABI library headers.
+:::{option} LIBCXX_AVAILABILITY_MINIMUM_HEADER_VERSION:STRING
+**Default**: `2`
-.. option:: LIBCXX_CXX_ABI_LIBRARY_PATH:PATH
+This option configures the oldest version of the libc++ headers that the built
+library has to be compatible with. See the
+{ref}`minimum header version documentation<MinimumHeaderVersion>` for details.
+:::
- Provide the path to the ABI library that libc++ should link against. This is only
- useful when linking against an out-of-tree ABI library.
+:::{option} LIBCXXABI_AVAILABILITY_MINIMUM_HEADER_VERSION:STRING
+**Default**: `2`
-.. option:: LIBCXX_ENABLE_STATIC_ABI_LIBRARY:BOOL
+This is the same as `LIBCXX_AVAILABILITY_MINIMUM_HEADER_VERSION` documented
+above, but for libc++abi. The two options should be set to the same value if
+libc++abi is used.
+:::
- **Default**: ``OFF``
+:::{option} LIBCXXABI_USE_LLVM_UNWINDER:BOOL
+**Default**: `ON`
- If this option is enabled, libc++ will try and link the selected ABI library
- statically.
+Build and use the LLVM unwinder. Note: This option can only be used when
+libc++abi is the C++ ABI library used.
+:::
-.. option:: LIBCXX_ENABLE_ABI_LINKER_SCRIPT:BOOL
+:::{option} LIBCXXABI_ADDITIONAL_LIBRARIES:STRING
+**Default**: `""`
- **Default**: ``ON`` by default on UNIX platforms other than Apple unless
- 'LIBCXX_ENABLE_STATIC_ABI_LIBRARY' is ON. Otherwise the default value is ``OFF``.
+Additional libraries libc++abi is linked to which can be provided in cache.
+:::
- This option generate and installs a linker script as ``libc++.so`` which
- links the correct ABI library.
+### LLVM-specific options
-.. option:: LIBCXX_AVAILABILITY_MINIMUM_HEADER_VERSION:STRING
+:::{option} LLVM_LIBDIR_SUFFIX:STRING
+Extra suffix to append to the directory where libraries are to be
+installed. On a 64-bit architecture, one could use `-DLLVM_LIBDIR_SUFFIX=64`
+to install libraries to `/usr/lib64`.
+:::
- **Default**: ``2``
+:::{option} LLVM_BUILD_32_BITS:BOOL
+Build 32-bits executables and libraries on 64-bits systems. This option is
+available only on some 64-bits Unix systems. Defaults to OFF.
+:::
- This option configures the oldest version of the libc++ headers that the built
- library has to be compatible with. See the
- :ref:`minimum header version documentation<MinimumHeaderVersion>` for details.
+:::{option} LLVM_LIT_ARGS:STRING
+Arguments given to lit. `make check` and `make clang-test` are affected.
+By default, `'-sv --no-progress-bar'` on Visual C++ and Xcode, `'-sv'` on
+others.
+:::
-.. option:: LIBCXXABI_AVAILABILITY_MINIMUM_HEADER_VERSION:STRING
-
- **Default**: ``2``
-
- This is the same as ``LIBCXX_AVAILABILITY_MINIMUM_HEADER_VERSION`` documented
- above, but for libc++abi. The two options should be set to the same value if
- libc++abi is used.
-
-.. option:: LIBCXXABI_USE_LLVM_UNWINDER:BOOL
-
- **Default**: ``ON``
-
- Build and use the LLVM unwinder. Note: This option can only be used when
- libc++abi is the C++ ABI library used.
-
-.. option:: LIBCXXABI_ADDITIONAL_LIBRARIES:STRING
-
- **Default**: ``""``
-
- Additional libraries libc++abi is linked to which can be provided in cache.
-
-LLVM-specific options
----------------------
-
-.. option:: LLVM_LIBDIR_SUFFIX:STRING
-
- Extra suffix to append to the directory where libraries are to be
- installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
- to install libraries to ``/usr/lib64``.
-
-.. option:: LLVM_BUILD_32_BITS:BOOL
-
- Build 32-bits executables and libraries on 64-bits systems. This option is
- available only on some 64-bits Unix systems. Defaults to OFF.
-
-.. option:: LLVM_LIT_ARGS:STRING
-
- Arguments given to lit. ``make check`` and ``make clang-test`` are affected.
- By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on
- others.
-
-
-Support for Windows
-===================
+## Support for Windows
Libc++ supports being built with clang-cl, but not with MSVC's cl.exe, as
-cl doesn't support the ``#include_next`` extension. Furthermore, VS 2017 or
+cl doesn't support the `#include_next` extension. Furthermore, VS 2017 or
newer (19.14) is required.
Libc++ also supports being built with clang targeting MinGW environments.
Libc++ supports Windows 7 or newer. However, the minimum runtime version
-of the build is determined by the ``_WIN32_WINNT`` define, which in many
+of the build is determined by the `_WIN32_WINNT` define, which in many
SDKs defaults to the latest version. To build a version that runs on an
-older version, define e.g. ``_WIN32_WINNT=0x601`` while building libc++,
+older version, define e.g. `_WIN32_WINNT=0x601` while building libc++,
to target Windows 7.
-CMake + Visual Studio
----------------------
+### CMake + Visual Studio
Building with Visual Studio currently does not permit running tests. However,
it is the simplest way to build.
-.. code-block:: batch
-
- > cmake -G "Visual Studio 16 2019" -S runtimes -B build ^
- -T "ClangCL" ^
- -DLLVM_ENABLE_RUNTIMES=libcxx ^
- -DLIBCXX_ENABLE_SHARED=YES ^
- -DLIBCXX_ENABLE_STATIC=NO
- > cmake --build build
+```batch
+> cmake -G "Visual Studio 16 2019" -S runtimes -B build ^
+ -T "ClangCL" ^
+ -DLLVM_ENABLE_RUNTIMES=libcxx ^
+ -DLIBCXX_ENABLE_SHARED=YES ^
+ -DLIBCXX_ENABLE_STATIC=NO
+> cmake --build build
+```
-CMake + ninja (MSVC)
---------------------
+### CMake + ninja (MSVC)
Building with ninja is required for development to enable tests.
A couple of tests require Bash to be available, and a couple dozens
@@ -432,76 +423,71 @@ can still be ran successfully.
If Git for Windows is available, that can be used to provide the bash
shell by adding the right bin directory to the path, e.g.
-``set PATH=%PATH%;C:\Program Files\Git\usr\bin``.
+`set PATH=%PATH%;C:\Program Files\Git\usr\bin`.
Alternatively, one can also choose to run the whole build in a MSYS2
shell. That can be set up e.g. by starting a Visual Studio Tools Command
Prompt (for getting the environment variables pointing to the headers and
import libraries), and making sure that clang-cl is available in the
path. From there, launch an MSYS2 shell via e.g.
-``C:\msys64\msys2_shell.cmd -full-path -mingw64`` (preserving the earlier
+`C:\msys64\msys2_shell.cmd -full-path -mingw64` (preserving the earlier
environment, allowing the MSVC headers/libraries and clang-cl to be found).
In either case, then run:
-.. code-block:: batch
-
- > cmake -G Ninja -S runtimes -B build ^
- -DCMAKE_C_COMPILER=clang-cl ^
- -DCMAKE_CXX_COMPILER=clang-cl ^
- -DLLVM_ENABLE_RUNTIMES=libcxx
- > ninja -C build cxx
- > ninja -C build check-cxx
+```batch
+> cmake -G Ninja -S runtimes -B build ^
+ -DCMAKE_C_COMPILER=clang-cl ^
+ -DCMAKE_CXX_COMPILER=clang-cl ^
+ -DLLVM_ENABLE_RUNTIMES=libcxx
+> ninja -C build cxx
+> ninja -C build check-cxx
+```
If you are running in an MSYS2 shell and you have installed the
MSYS2-provided clang package (which defaults to a non-MSVC target), you
-should add e.g. ``-DCMAKE_CXX_COMPILER_TARGET=x86_64-windows-msvc`` (replacing
-``x86_64`` with the architecture you're targeting) to the ``cmake`` command
-line above. This will instruct ``check-cxx`` to use the right target triple
-when invoking ``clang++``.
+should add e.g. `-DCMAKE_CXX_COMPILER_TARGET=x86_64-windows-msvc` (replacing
+`x86_64` with the architecture you're targeting) to the `cmake` command
+line above. This will instruct `check-cxx` to use the right target triple
+when invoking `clang++`.
-CMake + ninja (MinGW)
----------------------
+### CMake + ninja (MinGW)
libcxx can also be built in MinGW environments, e.g. with the MinGW
compilers in MSYS2. This requires clang to be available (installed with
-e.g. the ``mingw-w64-x86_64-clang`` package), together with CMake and ninja.
-
-.. code-block:: bash
+e.g. the `mingw-w64-x86_64-clang` package), together with CMake and ninja.
- > cmake -G Ninja -S runtimes -B build \
- -DCMAKE_C_COMPILER=clang \
- -DCMAKE_CXX_COMPILER=clang++ \
- -DLLVM_ENABLE_LLD=ON \
- -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind" \
- -DLIBCXXABI_ENABLE_SHARED=OFF \
- -DLIBCXX_ENABLE_STATIC_ABI_LIBRARY=ON
- > ninja -C build cxx
- > ninja -C build check-cxx
+```bash
+> cmake -G Ninja -S runtimes -B build \
+ -DCMAKE_C_COMPILER=clang \
+ -DCMAKE_CXX_COMPILER=clang++ \
+ -DLLVM_ENABLE_LLD=ON \
+ -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind" \
+ -DLIBCXXABI_ENABLE_SHARED=OFF \
+ -DLIBCXX_ENABLE_STATIC_ABI_LIBRARY=ON
+> ninja -C build cxx
+> ninja -C build check-cxx
+```
-.. _`libc++abi`: http://libcxxabi.llvm.org/
+(assertion-handler)=
-
-.. _assertion-handler:
-
-Overriding the default assertion handler
-========================================
+## Overriding the default assertion handler
When the library wants to terminate due to a hardening assertion failure, the
program is aborted by invoking a trap instruction (or in debug mode, by
a special verbose termination function that prints an error message and calls
-``std::abort()``). This is done to minimize the code size impact of enabling
+`std::abort()`). This is done to minimize the code size impact of enabling
hardening in the library. However, vendors can also override that mechanism at
CMake configuration time.
Under the hood, a hardening assertion will invoke the
-``_LIBCPP_ASSERTION_HANDLER`` macro upon failure. A vendor may provide a header
+`_LIBCPP_ASSERTION_HANDLER` macro upon failure. A vendor may provide a header
that contains a custom definition of this macro and specify the path to the
-header via the ``LIBCXX_ASSERTION_HANDLER_FILE`` CMake variable. If provided,
+header via the `LIBCXX_ASSERTION_HANDLER_FILE` CMake variable. If provided,
this header will be included by the library and replace the default
implementation. The header must not include any standard library headers
(directly or transitively) because doing so will almost always create a circular
-dependency. The ``_LIBCPP_ASSERTION_HANDLER(message)`` macro takes a single
+dependency. The `_LIBCPP_ASSERTION_HANDLER(message)` macro takes a single
parameter that contains an error message explaining the hardening failure and
some details about the source location that triggered it.
@@ -512,118 +498,109 @@ decides to avoid doing so (e.g. it chooses to log and continue instead), it does
so at its own risk -- this approach should only be used in non-production builds
and with an understanding of potential consequences. Furthermore, the custom
assertion handler should not throw any exceptions as it may be invoked from
-standard library functions that are marked ``noexcept`` (so throwing will result
-in ``std::terminate`` being called).
+standard library functions that are marked `noexcept` (so throwing will result
+in `std::terminate` being called).
+## Using Alternate ABI libraries
-Using Alternate ABI libraries
-=============================
-
-In order to implement various features like exceptions, RTTI, ``dynamic_cast`` and
+In order to implement various features like exceptions, RTTI, `dynamic_cast` and
more, libc++ requires what we refer to as an ABI library. Typically, that library
-implements the `Itanium C++ ABI <https://itanium-cxx-abi.github.io/cxx-abi/abi.html>`_.
+implements the [Itanium C++ ABI](https://itanium-cxx-abi.github.io/cxx-abi/abi.html).
By default, libc++ uses libc++abi as an ABI library. However, it is possible to use
other ABI libraries too.
-Using libsupc++ on Linux
-------------------------
+### Using libsupc++ on Linux
You will need libstdc++ in order to provide libsupc++.
Figure out where the libsupc++ headers are on your system. On Ubuntu this
-is ``/usr/include/c++/<version>`` and ``/usr/include/c++/<version>/<target-triple>``
+is `/usr/include/c++/<version>` and `/usr/include/c++/<version>/<target-triple>`
You can also figure this out by running
-.. code-block:: bash
-
- $ echo | g++ -Wp,-v -x c++ - -fsyntax-only
- ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu"
- ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include"
- #include "..." search starts here:
- #include <...> search starts here:
- /usr/include/c++/4.7
- /usr/include/c++/4.7/x86_64-linux-gnu
- /usr/include/c++/4.7/backward
- /usr/lib/gcc/x86_64-linux-gnu/4.7/include
- /usr/local/include
- /usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed
- /usr/include/x86_64-linux-gnu
- /usr/include
- End of search list.
+```bash
+$ echo | g++ -Wp,-v -x c++ - -fsyntax-only
+ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu"
+ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include"
+#include "..." search starts here:
+#include <...> search starts here:
+/usr/include/c++/4.7
+/usr/include/c++/4.7/x86_64-linux-gnu
+/usr/include/c++/4.7/backward
+/usr/lib/gcc/x86_64-linux-gnu/4.7/include
+/usr/local/include
+/usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed
+/usr/include/x86_64-linux-gnu
+/usr/include
+End of search list.
+```
Note that the first two entries happen to be what we are looking for. This
may not be correct on all platforms.
We can now run CMake:
-.. code-block:: bash
-
- $ cmake -G Ninja -S runtimes -B build \
- -DLLVM_ENABLE_RUNTIMES="libcxx" \
- -DLIBCXX_CXX_ABI=libstdc++ \
- -DLIBCXXABI_USE_LLVM_UNWINDER=OFF \
- -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/"
- $ ninja -C build install-cxx
+```bash
+$ cmake -G Ninja -S runtimes -B build \
+ -DLLVM_ENABLE_RUNTIMES="libcxx" \
+ -DLIBCXX_CXX_ABI=libstdc++ \
+ -DLIBCXXABI_USE_LLVM_UNWINDER=OFF \
+ -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/"
+$ ninja -C build install-cxx
+```
-
-You can also substitute ``-DLIBCXX_CXX_ABI=libsupc++``
+You can also substitute `-DLIBCXX_CXX_ABI=libsupc++`
above, which will cause the library to be linked to libsupc++ instead
of libstdc++, but this is only recommended if you know that you will
never need to link against libstdc++ in the same executable as libc++.
-GCC ships libsupc++ separately but only as a static library. If a
+GCC ships libsupc++ separately but only as a static library. If a
program also needs to link against libstdc++, it will provide its
own copy of libsupc++ and this can lead to subtle problems.
-Using libcxxrt on Linux
-------------------------
+### Using libcxxrt on Linux
-You will need to keep the source tree of `libcxxrt`_ available
+You will need to keep the source tree of [libcxxrt][libcxxrt] available
on your build machine and your copy of the libcxxrt shared library must
be placed where your linker will find it.
We can now run CMake like:
-.. code-block:: bash
-
- $ cmake -G Ninja -S runtimes -B build \
- -DLLVM_ENABLE_RUNTIMES="libcxx" \
- -DLIBCXX_CXX_ABI=libcxxrt \
- -DLIBCXX_ENABLE_NEW_DELETE_DEFINITIONS=ON \
- -DLIBCXXABI_USE_LLVM_UNWINDER=OFF \
- -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src
- $ ninja -C build install-cxx
+```bash
+$ cmake -G Ninja -S runtimes -B build \
+ -DLLVM_ENABLE_RUNTIMES="libcxx" \
+ -DLIBCXX_CXX_ABI=libcxxrt \
+ -DLIBCXX_ENABLE_NEW_DELETE_DEFINITIONS=ON \
+ -DLIBCXXABI_USE_LLVM_UNWINDER=OFF \
+ -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src
+$ ninja -C build install-cxx
+```
Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as
-clang is set up to link for libc++ linked to libsupc++. To get around this
-you'll have to set up your linker yourself (or patch clang). For example,
+clang is set up to link for libc++ linked to libsupc++. To get around this
+you'll have to set up your linker yourself (or patch clang). For example,
-.. code-block:: bash
-
- $ clang++ -stdlib=libc++ helloworld.cpp \
- -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc
+```bash
+$ clang++ -stdlib=libc++ helloworld.cpp \
+ -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc
+```
Alternately, you could just add libcxxrt to your libraries list, which in most
situations will give the same result:
-.. code-block:: bash
-
- $ clang++ -stdlib=libc++ helloworld.cpp -lcxxrt
+```bash
+$ clang++ -stdlib=libc++ helloworld.cpp -lcxxrt
+```
-.. _`libcxxrt`: https://github.com/libcxxrt/libcxxrt
+## libc++'s ABI guarantees
-libc++'s ABI guarantees
-=======================
+Libc++ provides several ABI guarantees, which are documented {ref}`here <ABIGuarantees>`.
-Libc++ provides several ABI guarantees, which are documented :ref:`here <ABIGuarantees>`.
-
-Availability Markup
-===================
+## Availability Markup
Libc++ is shipped by various vendors. In particular, it is used as a system library on macOS, iOS and other Apple
platforms. In order for users to be able to compile a binary that is intended to be deployed to an older version of a
-platform, Clang provides `availability attributes <https://clang.llvm.org/docs/AttributeReference.html#availability>`_.
+platform, Clang provides [availability attributes](https://clang.llvm.org/docs/AttributeReference.html#availability).
These attributes can be placed on declarations and are used to describe the life cycle of a symbol in the library.
The main goal is to ensure a compile-time error if a symbol that hasn't been introduced in a previously released library
@@ -641,36 +618,38 @@ This mechanism is general in nature, and any vendor can add their markup to the
feature is added that requires support in the shared library, two macros are added below to allow marking the feature as
unavailable:
-1. A macro named ``_LIBCPP_AVAILABILITY_HAS_<feature>`` which must be defined to ``_LIBCPP_INTRODUCED_IN_<version>`` for
+1. A macro named `_LIBCPP_AVAILABILITY_HAS_<feature>` which must be defined to `_LIBCPP_INTRODUCED_IN_<version>` for
the appropriate LLVM version.
-
-2. A macro named ``_LIBCPP_AVAILABILITY_<feature>``, which must be defined to ``_LIBCPP_INTRODUCED_IN_<version>_MARKUP``
+2. A macro named `_LIBCPP_AVAILABILITY_<feature>`, which must be defined to `_LIBCPP_INTRODUCED_IN_<version>_MARKUP`
for the appropriate LLVM version.
When vendors decide to ship the feature as part of their shared library, they can update the
-``_LIBCPP_INTRODUCED_IN_<version>`` macro (and the markup counterpart) based on the platform version they shipped that
+`_LIBCPP_INTRODUCED_IN_<version>` macro (and the markup counterpart) based on the platform version they shipped that
version of LLVM in. The library will then use this markup to provide an optimal user experience on these platforms.
Furthermore, many features in the standard library have corresponding feature-test macros. The
-``_LIBCPP_AVAILABILITY_HAS_<feature>`` macros are checked by the corresponding feature-test macros generated by
-``generate_feature_test_macro_components.py`` to ensure that the library doesn't announce a feature as being implemented
+`_LIBCPP_AVAILABILITY_HAS_<feature>` macros are checked by the corresponding feature-test macros generated by
+`generate_feature_test_macro_components.py` to ensure that the library doesn't announce a feature as being implemented
if it is unavailable on the deployment target.
Note that this mechanism is disabled by default in the "upstream" libc++. Availability annotations are only meaningful
when shipping libc++ inside a platform (i.e. as a system library), and so vendors that want them should turn those
annotations on at CMake configuration time.
-.. _MinimumHeaderVersion:
+(minimumheaderversion)=
-Minimum Header Version
-======================
+## Minimum Header Version
In libc++ we add new functions and remove the use of other functions in the built library on a regular basis. To avoid
breaking programs, we keep old functions in the built library as documented in our
-:ref:`header support policy<HeaderSupportPolicy>`. However, there are platforms where some of these functions could
+{ref}`header support policy<HeaderSupportPolicy>`. However, there are platforms where some of these functions could
never be referenced, because that platform never provided headers which referenced these functions. To reduce the size
of the built library on these platforms, libc++ provides the notion of a minimum header version. The minimum header
version describes the earliest version of the libc++ headers that can be used in a program linking against the library
currently being built. Functions which have never been referenced in headers since the minimum header version are
removed from the library. The minimum header version can be set with the CMake variables
-``LIBCXX_AVAILABILITY_MINIMUM_HEADER_VERSION`` and ``LIBCXXABI_AVAILABILITY_MINIMUM_HEADER_VERSION``.
+`LIBCXX_AVAILABILITY_MINIMUM_HEADER_VERSION` and `LIBCXXABI_AVAILABILITY_MINIMUM_HEADER_VERSION`.
+
+[libc++abi]: http://libcxxabi.llvm.org/
+[libcxxrt]: https://github.com/libcxxrt/libcxxrt
+
diff --git a/libcxx/docs/index.md b/libcxx/docs/index.md
index e4f337270231ef..9a74d39a6c4400 100644
--- a/libcxx/docs/index.md
+++ b/libcxx/docs/index.md
@@ -1,68 +1,62 @@
-.. _index:
+(index)=
-=============================
-"libc++" C++ Standard Library
-=============================
+# "libc++" C++ Standard Library
-Overview
-========
+## Overview
libc++ is a new implementation of the C++ standard library, targeting C++11 and
above.
-* Features and Goals
+- Features and Goals
- * Correctness as defined by the C++11 standard.
- * Fast execution.
- * Minimal memory use.
- * Fast compile times.
- * ABI compatibility with gcc's libstdc++ for some low-level features
+ - Correctness as defined by the C++11 standard.
+ - Fast execution.
+ - Minimal memory use.
+ - Fast compile times.
+ - ABI compatibility with gcc's libstdc++ for some low-level features
such as exception objects, rtti and memory allocation.
- * Extensive unit tests.
-
-* Design and Implementation:
-
- * Extensive unit tests
- * Internal linker model can be dumped/read to textual format
- * Additional linking features can be plugged in as "passes"
- * OS specific and CPU specific code factored out
-
-
-Getting Started with libc++
-===========================
-
-.. toctree::
- :maxdepth: 1
-
- ReleaseNotes
- UserDocumentation
- VendorDocumentation
- ABIGuarantees
- Contributing
- CodingGuidelines
- TestingLibcxx
- ImplementationDefinedBehavior
- Modules
- Hardening
- Status/Cxx17
- Status/Cxx20
- Status/Cxx23
- Status/Cxx26
- Status/Cxx29
-
-
-.. toctree::
- :hidden:
-
- AddingNewCIJobs
- Contributing/ReleaseProcedure
- Contributing/PostMeetingProcedure
- Contributing/NewStandardProcedure
- FeatureTestMacroTable
-
-
-Current Status
-==============
+ - Extensive unit tests.
+
+- Design and Implementation:
+
+ - Extensive unit tests
+ - Internal linker model can be dumped/read to textual format
+ - Additional linking features can be plugged in as "passes"
+ - OS specific and CPU specific code factored out
+
+## Getting Started with libc++
+
+```{toctree}
+:maxdepth: 1
+
+ReleaseNotes
+UserDocumentation
+VendorDocumentation
+ABIGuarantees
+Contributing
+CodingGuidelines
+TestingLibcxx
+ImplementationDefinedBehavior
+Modules
+Hardening
+Status/Cxx17
+Status/Cxx20
+Status/Cxx23
+Status/Cxx26
+Status/Cxx29
+```
+
+```{toctree}
+:hidden: true
+
+AddingNewCIJobs
+Contributing/ReleaseProcedure
+Contributing/PostMeetingProcedure
+Contributing/NewStandardProcedure
+FeatureTestMacroTable
+```
+
+## Current Status
libc++ has become the default C++ Standard Library implementation for many major platforms, including Apple's macOS,
iOS, watchOS, and tvOS, Google Search, the Android operating system, and FreeBSD. As a result, libc++ has an estimated
@@ -80,35 +74,32 @@ As an open-source project, libc++ benefits from a vibrant community of contribut
library and add new features. This ongoing development and support ensure that libc++ remains at the forefront of
C++ standardization efforts and continues to meet the evolving needs of C++ developers worldwide.
+### History
-History
--------
After its initial introduction, many people have asked "why start a new
library instead of contributing to an existing library?" (like Apache's
-libstdcxx, GNU's libstdc++, STLport, etc). There are many contributing
+libstdcxx, GNU's libstdc++, STLport, etc). There are many contributing
reasons, but some of the major ones are:
-* From years of experience (including having implemented the standard
+- From years of experience (including having implemented the standard
library before), we've learned many things about implementing
the standard containers which require ABI breakage and fundamental changes
- to how they are implemented. For example, it is generally accepted that
+ to how they are implemented. For example, it is generally accepted that
building std::string using the "short string optimization" instead of
using Copy On Write (COW) is a superior approach for multicore
- machines (particularly in C++11, which has rvalue references). Breaking
+ machines (particularly in C++11, which has rvalue references). Breaking
ABI compatibility with old versions of the library was
determined to be critical to achieving the performance goals of
libc++.
-
-* Mainline libstdc++ has switched to GPL3, a license which the developers
- of libc++ cannot use. libstdc++ 4.2 (the last GPL2 version) could be
+- Mainline libstdc++ has switched to GPL3, a license which the developers
+ of libc++ cannot use. libstdc++ 4.2 (the last GPL2 version) could be
independently extended to support C++11, but this would be a fork of the
codebase (which is often seen as worse for a project than starting a new
- independent one). Another problem with libstdc++ is that it is tightly
+ independent one). Another problem with libstdc++ is that it is tightly
integrated with G++ development, tending to be tied fairly closely to the
matching version of G++.
-
-* STLport and the Apache libstdcxx library are two other popular
- candidates, but both lack C++11 support. Our experience (and the
+- STLport and the Apache libstdcxx library are two other popular
+ candidates, but both lack C++11 support. Our experience (and the
experience of libstdc++ developers) is that adding support for C++11 (in
particular rvalue references and move-only types) requires changes to
almost every class and function, essentially amounting to a rewrite.
@@ -117,40 +108,34 @@ reasons, but some of the major ones are:
Further, both projects are apparently abandoned: STLport 5.2.1 was
released in Oct'08, and STDCXX 4.2.1 in May'08.
-..
- LLVM RELEASE bump version
+% LLVM RELEASE bump version
-.. _SupportedPlatforms:
+(supportedplatforms)=
-Platform and Compiler Support
-=============================
+## Platform and Compiler Support
Libc++ aims to support common compilers that implement the C++11 Standard. In order to strike a
good balance between stability for users and maintenance cost, testing coverage and development
velocity, libc++ drops support for older compilers as newer ones are released.
-============ =================== ========================== =====================
-Compiler Versions Restrictions Support policy
-============ =================== ========================== =====================
-Clang 21, 22, 23-git latest two stable releases per `LLVM's release page <https://releases.llvm.org>`_ and the development version
-AppleClang 26.4 latest stable release per `Xcode's release page <https://developer.apple.com/documentation/xcode-release-notes>`_
-Open XL 17.1.4 (AIX) latest stable release per `Open XL's documentation page <https://www.ibm.com/docs/en/openxl-c-and-cpp-aix>`_
-GCC 16 In C++11 or later only latest stable release per `GCC's release page <https://gcc.gnu.org/releases.html>`_
-============ =================== ========================== =====================
+| Compiler | Versions | Restrictions | Support policy |
+| ---------- | -------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Clang | 21, 22, 23-git | | latest two stable releases per [LLVM's release page](https://releases.llvm.org) and the development version |
+| AppleClang | 26.4 | | latest stable release per [Xcode's release page](https://developer.apple.com/documentation/xcode-release-notes) |
+| Open XL | 17.1.4 (AIX) | | latest stable release per [Open XL's documentation page](https://www.ibm.com/docs/en/openxl-c-and-cpp-aix) |
+| GCC | 16 | In C++11 or later only | latest stable release per [GCC's release page](https://gcc.gnu.org/releases.html) |
Libc++ also supports common platforms and architectures:
-===================== ========================= ============================
-Target platform Target architecture Notes
-===================== ========================= ============================
-macOS 11.0+ i386, x86_64, arm64 Deployment target lower bound is the minimum between what Chrome resp. the last stable `Xcode release <https://developer.apple.com/support/xcode>`_ support
-FreeBSD 12+ i386, x86_64, arm
-Linux i386, x86_64, arm, arm64 Only glibc-2.24 and later and no other libc is officially supported
-Android 5.0+ i386, x86_64, arm, arm64
-Windows 7+ i386, x86_64, arm64 Both MSVC and MinGW style environments, ABI in MSVC environments is :doc:`unstable <DesignDocs/ABIVersioning>`
-AIX 7.2TL5+ powerpc, powerpc64
-Embedded (picolibc) arm
-===================== ========================= ============================
+| Target platform | Target architecture | Notes |
+| ------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| macOS 11.0+ | i386, x86_64, arm64 | Deployment target lower bound is the minimum between what Chrome resp. the last stable [Xcode release](https://developer.apple.com/support/xcode) support |
+| FreeBSD 12+ | i386, x86_64, arm | |
+| Linux | i386, x86_64, arm, arm64 | Only glibc-2.24 and later and no other libc is officially supported |
+| Android 5.0+ | i386, x86_64, arm, arm64 | |
+| Windows 7+ | i386, x86_64, arm64 | Both MSVC and MinGW style environments, ABI in MSVC environments is {doc}`unstable <DesignDocs/ABIVersioning>` |
+| AIX 7.2TL5+ | powerpc, powerpc64 | |
+| Embedded (picolibc) | arm | |
Generally speaking, libc++ should work on any platform that provides a fairly complete
C Standard Library. It is also possible to turn off parts of the library for use on
@@ -165,90 +150,84 @@ we don't make any guarantees. If you would like your compiler and/or platform
to be formally supported and listed here, please work with the libc++ team to set
up testing for your configuration.
-.. _HeaderSupportPolicy:
+(headersupportpolicy)=
Libc++ maintains backwards compatibility with programs compiled against older
versions of the headers. The library can currently be configured by vendors to
support headers from LLVM 2.8 or any later major release.
-C++ Standards Conformance
-=========================
+## C++ Standards Conformance
Libc++ provides full support for C++11 and C++14, and provides most of newer standards
with a few omissions. The conformance status of the library's tip is tracked in real-time
-using `this page <https://github.com/orgs/llvm/projects/31>`_. The conformance status of
+using [this page](https://github.com/orgs/llvm/projects/31). The conformance status of
this release is described in the pages below:
-* C++11 - Complete
-* C++14 - Complete
-* :ref:`C++17 - In Progress <cxx17-status>`
-* :ref:`C++20 - In Progress <cxx20-status>`
-* :ref:`C++23 - In Progress <cxx23-status>`
-* :ref:`C++26 - In Progress <cxx26-status>`
-* :ref:`C++29 - In Progress <cxx29-status>`
-* :ref:`C++ Feature Test Macro Status <feature-status>`
-
+- C++11 - Complete
+- C++14 - Complete
+- {ref}`C++17 - In Progress <cxx17-status>`
+- {ref}`C++20 - In Progress <cxx20-status>`
+- {ref}`C++23 - In Progress <cxx23-status>`
+- {ref}`C++26 - In Progress <cxx26-status>`
+- {ref}`C++29 - In Progress <cxx29-status>`
+- {ref}`C++ Feature Test Macro Status <feature-status>`
-Getting Involved
-================
+## Getting Involved
-First please review our `Developer's Policy <https://llvm.org/docs/DeveloperPolicy.html>`__
-and `Getting started with LLVM <https://llvm.org/docs/GettingStarted.html>`__.
+First please review our [Developer's Policy](https://llvm.org/docs/DeveloperPolicy.html)
+and [Getting started with LLVM](https://llvm.org/docs/GettingStarted.html).
**Bug Reports**
-If you think you've found a bug in libc++, please report it using the `LLVM bug tracker`_.
-If you're not sure, you can ask for support on the `libc++ forum`_ or in the `libc++ chat`_.
+If you think you've found a bug in libc++, please report it using the [LLVM bug tracker].
+If you're not sure, you can ask for support on the [libc++ forum] or in the [libc++ chat].
**Patches**
If you want to contribute a patch to libc++, please start by reviewing our
-:ref:`documentation about contributing <ContributingToLibcxx>`.
+{ref}`documentation about contributing <ContributingToLibcxx>`.
**Discussion and Questions**
-Send discussions and questions to the `libc++ forum`_.
-
-
-Design Documents
-================
-
-.. toctree::
- :maxdepth: 1
-
- DesignDocs/ABIVersioning
- DesignDocs/AtomicDesign
- DesignDocs/CapturingConfigInfo
- DesignDocs/ExperimentalFeatures
- DesignDocs/ExtendedCXX03Support
- DesignDocs/FeatureTestMacros
- DesignDocs/FileTimeType
- DesignDocs/HeaderRemovalPolicy
- DesignDocs/NoexceptPolicy
- DesignDocs/PSTLIntegration
- DesignDocs/ThreadingSupportAPI
- DesignDocs/UniquePtrTrivialAbi
- DesignDocs/UnspecifiedBehaviorRandomization
- DesignDocs/VisibilityMacros
- DesignDocs/TimeZone
- DesignDocs/WindowsSupport
-
-
-Build Bots and Test Coverage
-============================
-
-* `Github Actions CI pipeline <https://github.com/llvm/llvm-project/actions/workflows/libcxx-pr-conformance-tests.yaml>`_
-* `Buildkite CI pipeline <https://buildkite.com/llvm-project/libcxx-ci>`_
-* `LLVM Buildbot Builders <https://lab.llvm.org/buildbot>`_
-* :ref:`Adding New CI Jobs <AddingNewCIJobs>`
-
-
-Quick Links
-===========
-* `LLVM Homepage <https://llvm.org/>`_
-* `libc++abi Homepage <http://libcxxabi.llvm.org/>`_
-* `LLVM Bug Tracker <https://github.com/llvm/llvm-project/labels/libc++/>`_
-* `libcxx-commits Mailing List <http://lists.llvm.org/mailman/listinfo/libcxx-commits>`_
-* `libc++ forum <https://discourse.llvm.org/c/runtimes/libcxx/>`_
-* `libc++ chat <https://discord.com/channels/636084430946959380/636732894974312448>`_ (`invite link <https://discord.gg/xS7Z362>`_)
-* `Browse libc++ Sources <https://github.com/llvm/llvm-project/tree/main/libcxx/>`_
+Send discussions and questions to the [libc++ forum].
+
+## Design Documents
+
+```{toctree}
+:maxdepth: 1
+
+DesignDocs/ABIVersioning
+DesignDocs/AtomicDesign
+DesignDocs/CapturingConfigInfo
+DesignDocs/ExperimentalFeatures
+DesignDocs/ExtendedCXX03Support
+DesignDocs/FeatureTestMacros
+DesignDocs/FileTimeType
+DesignDocs/HeaderRemovalPolicy
+DesignDocs/NoexceptPolicy
+DesignDocs/PSTLIntegration
+DesignDocs/ThreadingSupportAPI
+DesignDocs/UniquePtrTrivialAbi
+DesignDocs/UnspecifiedBehaviorRandomization
+DesignDocs/VisibilityMacros
+DesignDocs/TimeZone
+DesignDocs/WindowsSupport
+```
+
+## Build Bots and Test Coverage
+
+- [Github Actions CI pipeline](https://github.com/llvm/llvm-project/actions/workflows/libcxx-pr-conformance-tests.yaml)
+- [Buildkite CI pipeline](https://buildkite.com/llvm-project/libcxx-ci)
+- [LLVM Buildbot Builders](https://lab.llvm.org/buildbot)
+- {ref}`Adding New CI Jobs <AddingNewCIJobs>`
+
+## Quick Links
+
+- [LLVM Homepage](https://llvm.org/)
+- [libc++abi Homepage](http://libcxxabi.llvm.org/)
+- [LLVM Bug Tracker](https://github.com/llvm/llvm-project/labels/libc++/)
+- [libcxx-commits Mailing List](http://lists.llvm.org/mailman/listinfo/libcxx-commits)
+- [libc++ forum](https://discourse.llvm.org/c/runtimes/libcxx/)
+- [libc++ chat](https://discord.com/channels/636084430946959380/636732894974312448) ([invite link](https://discord.gg/xS7Z362))
+- [Browse libc++ Sources](https://github.com/llvm/llvm-project/tree/main/libcxx/)
+
>From e1f80254c170171892d87e9b07e2feaefd8aa413 Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Sat, 5 Sep 2026 04:10:05 +0000
Subject: [PATCH 2/4] [libc++][docs] Finish MyST migration (batch 2)
---
libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md | 3 +-
.../UnspecifiedBehaviorRandomization.md | 3 +-
libcxx/docs/DesignDocs/VisibilityMacros.md | 31 +-
libcxx/docs/Hardening.md | 290 +++++++++---------
libcxx/docs/Modules.md | 103 +++----
libcxx/docs/TestingLibcxx.md | 184 ++++++-----
libcxx/docs/UserDocumentation.md | 124 ++++----
libcxx/docs/VendorDocumentation.md | 5 +-
libcxx/docs/index.md | 9 +-
9 files changed, 369 insertions(+), 383 deletions(-)
diff --git a/libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md b/libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md
index 92df3ba1abe0b2..af65c7bd6e32fd 100644
--- a/libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md
+++ b/libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md
@@ -55,7 +55,7 @@ Google has measured performance improvements of up to 1.6% on some large server
This also affects null pointer optimization
-Clang's optimizer can now figure out when a `std::unique_ptr` is known to contain *non*-null.
+Clang's optimizer can now figure out when a {title-reference}`std::unique_ptr` is known to contain *non*-null.
(Actually, this has been a *missed* optimization all along.)
```cpp
@@ -129,4 +129,3 @@ The following breakages were discovered by enabling this change and fixing the r
> In other words, `&foo` in callee and `&foo` in the caller are the same address.
ASAN can be used to detect both of these.
-
diff --git a/libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.md b/libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.md
index 9a82c8b3c8239f..4d608cc1dabd24 100644
--- a/libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.md
+++ b/libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.md
@@ -24,7 +24,7 @@ algorithms and optimizations to the containers.
For example, as of LLVM version 13, libcxx sorting algorithm takes
[O(n^2) worst case](https://llvm.org/PR20837) but according
-to the standard its worst case should be `O(n log n)`. This effort helps users
+to the standard its worst case should be {title-reference}`O(n log n)`. This effort helps users
to gradually fix their tests while updating to new faster algorithms.
## Design
@@ -74,4 +74,3 @@ results, for example, for caching.
: partition
Patches welcome.
-
diff --git a/libcxx/docs/DesignDocs/VisibilityMacros.md b/libcxx/docs/DesignDocs/VisibilityMacros.md
index 8e41ca9d002770..9ea35d82b2b701 100644
--- a/libcxx/docs/DesignDocs/VisibilityMacros.md
+++ b/libcxx/docs/DesignDocs/VisibilityMacros.md
@@ -29,7 +29,7 @@ default visibility, thus removing the need for any annotations.
: Mark a symbol as being part of our ABI. This includes functions that are part
of the libc++ library, type information and other symbols. On Windows,
- this macro applies `dllimport`/`dllexport` to the symbol, and on other
+ this macro applies {title-reference}`dllimport`/{title-reference}`dllexport` to the symbol, and on other
platforms it gives the symbol default visibility. This macro should never be
used on class templates. On classes it should only be used if the vtable
lives in the built library.
@@ -37,14 +37,14 @@ default visibility, thus removing the need for any annotations.
**\_LIBCPP_OVERRIDABLE_FUNC_VIS**
: Mark a symbol as being exported by the libc++ library, but allow it to be
- overridden locally. On non-Windows, this is equivalent to `_LIBCPP_FUNC_VIS`.
- This macro is applied to all `operator new` and `operator delete` overloads.
-
- **Windows Behavior**: Any symbol marked `dllimport` cannot be overridden
- locally, since `dllimport` indicates the symbol should be bound to a separate
- DLL. All `operator new` and `operator delete` overloads are required to be
- locally overridable, and therefore must not be marked `dllimport`. On Windows,
- this macro therefore expands to `__declspec(dllexport)` when building the
+ overridden locally. On non-Windows, this is equivalent to {title-reference}`_LIBCPP_FUNC_VIS`.
+ This macro is applied to all {title-reference}`operator new` and {title-reference}`operator delete` overloads.
+
+ **Windows Behavior**: Any symbol marked {title-reference}`dllimport` cannot be overridden
+ locally, since {title-reference}`dllimport` indicates the symbol should be bound to a separate
+ DLL. All {title-reference}`operator new` and {title-reference}`operator delete` overloads are required to be
+ locally overridable, and therefore must not be marked {title-reference}`dllimport`. On Windows,
+ this macro therefore expands to {title-reference}`__declspec(dllexport)` when building the
library and has an empty definition otherwise.
**\_LIBCPP_HIDE_FROM_ABI**
@@ -54,7 +54,7 @@ default visibility, thus removing the need for any annotations.
**\_LIBCPP_HIDE_FROM_ABI_AFTER_V1**
-: Mark a function as being hidden from the ABI (per `_LIBCPP_HIDE_FROM_ABI`)
+: Mark a function as being hidden from the ABI (per {title-reference}`_LIBCPP_HIDE_FROM_ABI`)
when libc++ is built with an ABI version after ABI v1. This macro is used to
maintain ABI compatibility for symbols that have been historically exported
by libc++ in v1 of the ABI, but that we don't want to export in the future.
@@ -77,16 +77,16 @@ default visibility, thus removing the need for any annotations.
This macro is used to export the member functions produced by the explicit
instantiation in the dylib.
- **Windows Behavior**: `extern template` and `dllexport` are fundamentally
+ **Windows Behavior**: {title-reference}`extern template` and {title-reference}`dllexport` are fundamentally
incompatible *on a class template* on Windows; the former suppresses
instantiation, while the latter forces it. Specifying both on the same
declaration makes the class template be instantiated, which is not desirable
- inside headers. This macro therefore expands to `dllimport` outside of libc++
- but nothing inside of it (rather than expanding to `dllexport`); instead, the
+ inside headers. This macro therefore expands to {title-reference}`dllimport` outside of libc++
+ but nothing inside of it (rather than expanding to {title-reference}`dllexport`); instead, the
explicit instantiations themselves are marked as exported. Note that this
applies *only* to extern *class* templates. Extern *function* templates obey
- regular import/export semantics, and applying `dllexport` directly to the
- extern template declaration (i.e. using `_LIBCPP_FUNC_VIS`) is the correct
+ regular import/export semantics, and applying {title-reference}`dllexport` directly to the
+ extern template declaration (i.e. using {title-reference}`_LIBCPP_FUNC_VIS`) is the correct
thing to do for them.
**\_LIBCPP_CLASS_TEMPLATE_INSTANTIATION_VIS**
@@ -104,4 +104,3 @@ default visibility, thus removing the need for any annotations.
- [[cfe-dev] Visibility in libc++ - 1](http://lists.llvm.org/pipermail/cfe-dev/2013-July/030610.html)
- [[cfe-dev] Visibility in libc++ - 2](http://lists.llvm.org/pipermail/cfe-dev/2013-August/031195.html)
- [[libcxx] Visibility fixes for Windows](http://lists.llvm.org/pipermail/cfe-commits/Week-of-Mon-20130805/085461.html)
-
diff --git a/libcxx/docs/Hardening.md b/libcxx/docs/Hardening.md
index 4e50a1240ba09d..caf9bfb3f6355e 100644
--- a/libcxx/docs/Hardening.md
+++ b/libcxx/docs/Hardening.md
@@ -2,9 +2,9 @@
# Hardening Modes
-```{contents}
+:::{contents}
:local: true
-```
+:::
(using-hardening-modes)=
@@ -113,8 +113,8 @@ categories are considered internal to the library and subject to change.
- `valid-input-range` -- checks that ranges (whether expressed as an iterator
pair, an iterator and a sentinel, an iterator and a count, or
a `std::range`) given as input to library functions are valid:
- \- the sentinel is reachable from the begin iterator;
- \- TODO(hardening): both iterators refer to the same container.
+ - the sentinel is reachable from the begin iterator;
+ - TODO(hardening): both iterators refer to the same container.
("input" here refers to "an input given to an algorithm", not to an iterator
category)
@@ -171,64 +171,63 @@ categories are considered internal to the library and subject to change.
## Mapping between the hardening modes and the assertion categories
-```{eval-rst}
-.. list-table::
- :header-rows: 1
- :widths: auto
-
- * - Category name
- - ``fast``
- - ``extensive``
- - ``debug``
- * - ``valid-element-access``
- - ✅
- - ✅
- - ✅
- * - ``valid-input-range``
- - ✅
- - ✅
- - ✅
- * - ``non-null``
- - ❌
- - ✅
- - ✅
- * - ``non-overlapping-ranges``
- - ❌
- - ✅
- - ✅
- * - ``valid-deallocation``
- - ❌
- - ✅
- - ✅
- * - ``valid-external-api-call``
- - ❌
- - ✅
- - ✅
- * - ``compatible-allocator``
- - ❌
- - ✅
- - ✅
- * - ``argument-within-domain``
- - ❌
- - ✅
- - ✅
- * - ``pedantic``
- - ❌
- - ✅
- - ✅
- * - ``semantic-requirement``
- - ❌
- - ❌
- - ✅
- * - ``internal``
- - ❌
- - ❌
- - ✅
- * - ``uncategorized``
- - ❌
- - ✅
- - ✅
-```
+:::{list-table}
+:header-rows: 1
+:widths: auto
+
+* - Category name
+ - `fast`
+ - `extensive`
+ - `debug`
+* - `valid-element-access`
+ - ✅
+ - ✅
+ - ✅
+* - `valid-input-range`
+ - ✅
+ - ✅
+ - ✅
+* - `non-null`
+ - ❌
+ - ✅
+ - ✅
+* - `non-overlapping-ranges`
+ - ❌
+ - ✅
+ - ✅
+* - `valid-deallocation`
+ - ❌
+ - ✅
+ - ✅
+* - `valid-external-api-call`
+ - ❌
+ - ✅
+ - ✅
+* - `compatible-allocator`
+ - ❌
+ - ✅
+ - ✅
+* - `argument-within-domain`
+ - ❌
+ - ✅
+ - ✅
+* - `pedantic`
+ - ❌
+ - ✅
+ - ✅
+* - `semantic-requirement`
+ - ❌
+ - ❌
+ - ✅
+* - `internal`
+ - ❌
+ - ❌
+ - ✅
+* - `uncategorized`
+ - ❌
+ - ✅
+ - ✅
+:::
:::{note}
At the moment, each subsequent hardening mode is a strict superset of the
@@ -419,9 +418,8 @@ CMake configuration time. The available options are:
to the library.
ABI impact: changes the layout of `std::unique_ptr<T[]>`, and the representation
-
- : of a few library types that use `std::unique_ptr` internally, such as
- the unordered containers.
+ of a few library types that use `std::unique_ptr` internally, such as
+ the unordered containers.
- `_LIBCPP_ABI_BOUNDED_ITERATORS_IN_STD_ARRAY` -- changes the iterator type of `std::array` to a
bounded iterator that keeps track of whether it's within the bounds of the container and asserts it
@@ -465,87 +463,86 @@ The second character of an ABI tag encodes the assertion semantic:
## Hardened containers status
-```{eval-rst}
-.. list-table::
- :header-rows: 1
- :widths: auto
-
- * - Name
- - Member functions
- - Iterators (ABI-dependent)
- * - ``span``
- - ✅
- - ✅
- * - ``string_view``
- - ✅
- - ✅
- * - ``array``
- - ✅
- - ❌
- * - ``vector``
- - ✅
- - ✅ (see note)
- * - ``string``
- - ✅
- - ✅ (see note)
- * - ``list``
- - ✅
- - ❌
- * - ``forward_list``
- - ✅
- - ❌
- * - ``deque``
- - ✅
- - ❌
- * - ``map``
- - ❌
- - ❌
- * - ``set``
- - ❌
- - ❌
- * - ``multimap``
- - ❌
- - ❌
- * - ``multiset``
- - ❌
- - ❌
- * - ``unordered_map``
- - Partial
- - Partial
- * - ``unordered_set``
- - Partial
- - Partial
- * - ``unordered_multimap``
- - Partial
- - Partial
- * - ``unordered_multiset``
- - Partial
- - Partial
- * - ``mdspan``
- - ✅
- - ❌
- * - ``optional``
- - ✅
- - ✅
- * - ``function``
- - ❌
- - N/A
- * - ``variant``
- - N/A
- - N/A
- * - ``any``
- - N/A
- - N/A
- * - ``expected``
- - ✅
- - N/A
- * - ``valarray``
- - Partial
- - N/A
- * - ``bitset``
- - ✅
- - N/A
-```
+:::{list-table}
+:header-rows: 1
+:widths: auto
+
+* - Name
+ - Member functions
+ - Iterators (ABI-dependent)
+* - `span`
+ - ✅
+ - ✅
+* - `string_view`
+ - ✅
+ - ✅
+* - `array`
+ - ✅
+ - ❌
+* - `vector`
+ - ✅
+ - ✅ (see note)
+* - `string`
+ - ✅
+ - ✅ (see note)
+* - `list`
+ - ✅
+ - ❌
+* - `forward_list`
+ - ✅
+ - ❌
+* - `deque`
+ - ✅
+ - ❌
+* - `map`
+ - ❌
+ - ❌
+* - `set`
+ - ❌
+ - ❌
+* - `multimap`
+ - ❌
+ - ❌
+* - `multiset`
+ - ❌
+ - ❌
+* - `unordered_map`
+ - Partial
+ - Partial
+* - `unordered_set`
+ - Partial
+ - Partial
+* - `unordered_multimap`
+ - Partial
+ - Partial
+* - `unordered_multiset`
+ - Partial
+ - Partial
+* - `mdspan`
+ - ✅
+ - ❌
+* - `optional`
+ - ✅
+ - ✅
+* - `function`
+ - ❌
+ - N/A
+* - `variant`
+ - N/A
+ - N/A
+* - `any`
+ - N/A
+ - N/A
+* - `expected`
+ - ✅
+ - N/A
+* - `valarray`
+ - Partial
+ - N/A
+* - `bitset`
+ - ✅
+ - N/A
+:::
Note: for `vector` and `string`, the iterator does not check for
invalidation (accesses made via an invalidated iterator still lead to undefined
@@ -563,4 +560,3 @@ Please see {ref}`Testing documentation <testing-hardening-assertions>`.
contains some of the design rationale.
[odr issues]: https://en.cppreference.com/w/cpp/language/definition#:~:text=is%20ill%2Dformed.-,One%20Definition%20Rule,-Only%20one%20definition
-
diff --git a/libcxx/docs/Modules.md b/libcxx/docs/Modules.md
index 38ddd34be8611b..85612b74482bfe 100644
--- a/libcxx/docs/Modules.md
+++ b/libcxx/docs/Modules.md
@@ -13,8 +13,8 @@ considered stable nor complete
This page contains information regarding C++23 module support in libc++.
There are two kinds of modules available in Clang
-> - [Clang specific modules](https://clang.llvm.org/docs/Modules.html)
-> - [C++ modules](https://clang.llvm.org/docs/StandardCPlusPlusModules.html)
+- [Clang specific modules](https://clang.llvm.org/docs/Modules.html)
+- [C++ modules](https://clang.llvm.org/docs/StandardCPlusPlusModules.html)
This page mainly discusses the C++ modules. In C++20 there are also header units,
these are not part of this document.
@@ -37,58 +37,58 @@ on the availability of build systems with proper module support.
### What works
-> - Building BMIs
->
-> - Running tests using the `std` and `std.compat` module
->
-> - Using the `std` and `std.compat` module in external projects
->
-> - The following "parts disabled" configuration options are supported
->
-> - `LIBCXX_ENABLE_LOCALIZATION`
-> - `LIBCXX_ENABLE_WIDE_CHARACTERS`
-> - `LIBCXX_ENABLE_THREADS`
-> - `LIBCXX_ENABLE_FILESYSTEM`
-> - `LIBCXX_ENABLE_RANDOM_DEVICE`
-> - `LIBCXX_ENABLE_UNICODE`
-> - `LIBCXX_ENABLE_EXCEPTIONS` [^note-no-windows]
->
-> - A C++20 based extension
+- Building BMIs
-:::{note}
-[^note-no-windows]: This configuration will probably not work on Windows
+- Running tests using the `std` and `std.compat` module
+
+- Using the `std` and `std.compat` module in external projects
+
+- The following "parts disabled" configuration options are supported
+
+ - `LIBCXX_ENABLE_LOCALIZATION`
+ - `LIBCXX_ENABLE_WIDE_CHARACTERS`
+ - `LIBCXX_ENABLE_THREADS`
+ - `LIBCXX_ENABLE_FILESYSTEM`
+ - `LIBCXX_ENABLE_RANDOM_DEVICE`
+ - `LIBCXX_ENABLE_UNICODE`
+ - `LIBCXX_ENABLE_EXCEPTIONS` [^note-no-windows]
+
+- A C++20 based extension
+
+[^note-no-windows]:
+ This configuration will probably not work on Windows
due to hard-coded compilation flags.
-:::
### Some of the current limitations
-> - There is no official build system support, libc++ has experimental CMake support
-> - Requires CMake 3.26 for C++20 support
-> - Requires CMake 3.26 for C++23 support
-> - Requires CMake 3.27 for C++26 support
-> - Requires Ninja 1.11
-> - Requires Clang 17
-> - The path to the compiler may not be a symlink, `clang-scan-deps` does
-> not handle that case properly
-> - Libc++ is not tested with modules instead of headers
-> - Clang:
-> : - Including headers after importing the `std` module may fail. This is
-> hard to solve and there is a work-around by first including all headers
-> [bug report](https://llvm.org/PR61465).
+- There is no official build system support, libc++ has experimental CMake support
+- Requires CMake 3.26 for C++20 support
+- Requires CMake 3.26 for C++23 support
+- Requires CMake 3.27 for C++26 support
+- Requires Ninja 1.11
+- Requires Clang 17
+- The path to the compiler may not be a symlink, `clang-scan-deps` does
+ not handle that case properly
+- Libc++ is not tested with modules instead of headers
+- Clang:
+
+ - Including headers after importing the `std` module may fail. This is
+ hard to solve and there is a work-around by first including all headers
+ [bug report](https://llvm.org/PR61465).
### Blockers
-> - libc++
->
-> - Currently the tests only test with modules enabled, but do not import
-> modules instead of headers. When converting tests to using modules there
-> are still failures. These are under investigation.
-> - It has not been determined how to fully test libc++ with modules instead
-> of headers.
->
-> - Clang
->
-> - Some concepts do not work properly [bug report](https://llvm.org/PR61465).
+- libc++
+
+ - Currently the tests only test with modules enabled, but do not import
+ modules instead of headers. When converting tests to using modules there
+ are still failures. These are under investigation.
+ - It has not been determined how to fully test libc++ with modules instead
+ of headers.
+
+- Clang
+
+ - Some concepts do not work properly [bug report](https://llvm.org/PR61465).
## Using in external projects
@@ -104,11 +104,11 @@ the build system.
Currently there are two ways to build modules
-> - Use a local build of modules from the build directory. This requires
-> Clang 17 or later and CMake 3.26 or later.
-> - Use the installed modules. This requires Clang 18.1.2 or later and
-> a recent build of CMake. The CMake changes will be part of CMake 3.30. This
-> method requires you or your distribution to enable module installation.
+- Use a local build of modules from the build directory. This requires
+ Clang 17 or later and CMake 3.26 or later.
+- Use the installed modules. This requires Clang 18.1.2 or later and
+ a recent build of CMake. The CMake changes will be part of CMake 3.30. This
+ method requires you or your distribution to enable module installation.
### Using the local build
@@ -283,4 +283,3 @@ channel on [LLVM's Discord server](https://discord.gg/jzUbyP26tQ).
If you think you've found a bug please it using the [LLVM bug tracker](https://github.com/llvm/llvm-project/issues). Please make sure the issue
you found is not one of the known bugs or limitations on this page.
-
diff --git a/libcxx/docs/TestingLibcxx.md b/libcxx/docs/TestingLibcxx.md
index 8267726c1059b5..bb0c40d3042054 100644
--- a/libcxx/docs/TestingLibcxx.md
+++ b/libcxx/docs/TestingLibcxx.md
@@ -2,9 +2,9 @@
# Testing libc++
-```{contents}
+:::{contents}
:local: true
-```
+:::
## Getting Started
@@ -107,10 +107,10 @@ custom site configuration, simply point the CMake build to it using
will be used instead. That file can use CMake variables inside it to make
configuration easier.
-> ```bash
-> $ cmake <options> -DLIBCXX_TEST_CONFIG=<path-to-site-config>
-> $ libcxx/utils/libcxx-lit <build> -sv libcxx/test # will use your custom config file
-> ```
+```bash
+$ cmake <options> -DLIBCXX_TEST_CONFIG=<path-to-site-config>
+$ libcxx/utils/libcxx-lit <build> -sv libcxx/test # will use your custom config file
+```
### Additional tools
@@ -313,112 +313,105 @@ written to `stderr`.
This macro is in a different header as `assert_macros.h` since it pulls in
additional headers.
-> % note: This macro can only be used in test using C++20 or newer. The macro
-> % was added at a time where most of libc++'s C++17 support was complete.
-> % Since it is not expected to add this to existing tests no effort was
-> % taken to make it work in earlier language versions.
+:::{note}
+This macro can only be used in test using C++20 or newer. The macro
+was added at a time where most of libc++'s C++17 support was complete.
+Since it is not expected to add this to existing tests no effort was
+taken to make it work in earlier language versions.
+:::
### Test names
The names of test files have meaning for the libc++-specific configuration of
Lit. Based on the pattern that matches the name of a test file, Lit will test
-the code contained therein in different ways. Refer to the [Lit Meaning of libc++
-Test Filenames][lit meaning of libc++ test filenames] when determining the names for new test files.
+the code contained therein in different ways. Refer to the {ref}`Lit Meaning of libc++
+Test Filenames <lit-meaning-of-libc-test-filenames>` when determining the names for new test files.
(lit-meaning-of-libc-test-filenames)=
-```{eval-rst}
-.. list-table:: Lit Meaning of libc++ Test Filenames
- :widths: 25 75
- :header-rows: 1
-
- * - Name Pattern
- - Meaning
- * - ``FOO.pass.cpp``
- - Checks whether the C++ code in the file compiles, links and runs successfully.
- * - ``FOO.pass.mm``
- - Same as ``FOO.pass.cpp``, but for Objective-C++.
-
- * - ``FOO.compile.pass.cpp``
- - Checks whether the C++ code in the file compiles successfully. In general, prefer ``compile`` tests over ``verify`` tests,
- subject to the specific recommendations, below, for when to write ``verify`` tests.
- * - ``FOO.compile.pass.mm``
- - Same as ``FOO.compile.pass.cpp``, but for Objective-C++.
- * - ``FOO.compile.fail.cpp``
- - Checks that the code in the file does *not* compile successfully.
-
- * - ``FOO.verify.cpp``
- - Compiles with clang-verify. This type of test is automatically marked as UNSUPPORTED if the compiler does not support clang-verify.
- For additional information about how to write ``verify`` tests, see the `Internals Manual <https://clang.llvm.org/docs/InternalsManual.html#verifying-diagnostics>`_.
- Prefer `verify` tests over ``compile`` tests to test that compilation fails for a particular reason. For example, use a ``verify`` test
- to ensure that
-
- * an expected ``static_assert`` is triggered;
- * the use of deprecated functions generates the proper warning;
- * removed functions are no longer usable; or
- * return values from functions marked ``[[nodiscard]]`` are stored.
-
- * - ``FOO.link.pass.cpp``
- - Checks that the C++ code in the file compiles and links successfully -- no run attempted.
- * - ``FOO.link.pass.mm``
- - Same as ``FOO.link.pass.cpp``, but for Objective-C++.
- * - ``FOO.link.fail.cpp``
- - Checks whether the C++ code in the file fails to link after successful compilation.
- * - ``FOO.link.fail.mm``
- - Same as ``FOO.link.fail.cpp``, but for Objective-C++.
-
- * - ``FOO.sh.<anything>``
- - A *builtin Lit Shell* test.
- * - ``FOO.gen.<anything>``
- - A variant of a *Lit Shell* test that generates one or more Lit tests on the fly. Executing this test must generate one or more files as expected
- by LLVM split-file. Each generated file will drive an invocation of a separate Lit test. The format of the generated file will determine the type
- of Lit test to be executed. This can be used to generate multiple Lit tests from a single source file, which is useful for testing repetitive properties
- in the library. Be careful not to abuse this since this is not a replacement for usual code reuse techniques.
-
- * - ``FOO.bench.cpp``
- - A benchmark test. These tests are linked against the GoogleBenchmark library and generally consist of micro-benchmarks of individual
- components of the library.
-
-```
+:::{list-table} Lit Meaning of libc++ Test Filenames
+:widths: 25 75
+:header-rows: 1
+
+* - Name Pattern
+ - Meaning
+* - `FOO.pass.cpp`
+ - Checks whether the C++ code in the file compiles, links and runs successfully.
+* - `FOO.pass.mm`
+ - Same as `FOO.pass.cpp`, but for Objective-C++.
+* - `FOO.compile.pass.cpp`
+ - Checks whether the C++ code in the file compiles successfully. In general, prefer `compile` tests over `verify` tests,
+ subject to the specific recommendations, below, for when to write `verify` tests.
+* - `FOO.compile.pass.mm`
+ - Same as `FOO.compile.pass.cpp`, but for Objective-C++.
+* - `FOO.compile.fail.cpp`
+ - Checks that the code in the file does *not* compile successfully.
+* - `FOO.verify.cpp`
+ - Compiles with clang-verify. This type of test is automatically marked as UNSUPPORTED if the compiler does not support clang-verify.
+ For additional information about how to write `verify` tests, see the [Internals Manual](https://clang.llvm.org/docs/InternalsManual.html#verifying-diagnostics).
+ Prefer `verify` tests over `compile` tests to test that compilation fails for a particular reason. For example, use a `verify` test
+ to ensure that
+
+ - an expected `static_assert` is triggered;
+ - the use of deprecated functions generates the proper warning;
+ - removed functions are no longer usable; or
+ - return values from functions marked `[[nodiscard]]` are stored.
+* - `FOO.link.pass.cpp`
+ - Checks that the C++ code in the file compiles and links successfully -- no run attempted.
+* - `FOO.link.pass.mm`
+ - Same as `FOO.link.pass.cpp`, but for Objective-C++.
+* - `FOO.link.fail.cpp`
+ - Checks whether the C++ code in the file fails to link after successful compilation.
+* - `FOO.link.fail.mm`
+ - Same as `FOO.link.fail.cpp`, but for Objective-C++.
+* - `FOO.sh.<anything>`
+ - A *builtin Lit Shell* test.
+* - `FOO.gen.<anything>`
+ - A variant of a *Lit Shell* test that generates one or more Lit tests on the fly. Executing this test must generate one or more files as expected
+ by LLVM split-file. Each generated file will drive an invocation of a separate Lit test. The format of the generated file will determine the type
+ of Lit test to be executed. This can be used to generate multiple Lit tests from a single source file, which is useful for testing repetitive properties
+ in the library. Be careful not to abuse this since this is not a replacement for usual code reuse techniques.
+* - `FOO.bench.cpp`
+ - A benchmark test. These tests are linked against the GoogleBenchmark library and generally consist of micro-benchmarks of individual
+ components of the library.
+:::
### libc++-Specific Lit Features
#### Custom Directives
Lit has many directives built in (e.g., `DEFINE`, `UNSUPPORTED`). In addition to those directives, libc++ adds two additional libc++-specific directives that makes
-writing tests easier. See [libc++-specific Lit Directives] for more information about the `FILE_DEPENDENCIES`, `ADDITIONAL_COMPILE_FLAGS`, and `MODULE_DEPENDENCIES` libc++-specific directives.
+writing tests easier. See {ref}`libc++-specific Lit Directives <libc-specific-lit-directives>` for more information about the `FILE_DEPENDENCIES`, `ADDITIONAL_COMPILE_FLAGS`, and `MODULE_DEPENDENCIES` libc++-specific directives.
(libc-specific-lit-directives)=
-```{eval-rst}
-.. list-table:: libc++-specific Lit Directives
- :widths: 20 35 45
- :header-rows: 1
-
- * - Directive
- - Parameters
- - Usage
- * - ``FILE_DEPENDENCIES``
- - ``// FILE_DEPENDENCIES: file, directory, /path/to/file, ...``
- - The paths given to the ``FILE_DEPENDENCIES`` directive can specify directories or specific files upon which a given test depend. For example, a test that requires some test
- input stored in a data file would use this libc++-specific Lit directive. When a test file contains the ``FILE_DEPENDENCIES`` directive, Lit will collect the named files and copy
- them to the directory represented by the ``%{temp}`` substitution before the test executes. The copy is performed from the directory represented by the ``%S`` substitution
- (i.e. the source directory of the test being executed) which makes it possible to use relative paths to specify the location of dependency files. After Lit copies
- all the dependent files to the directory specified by the ``%{temp}`` substitution, that directory should contain *all* the necessary inputs to run. In other words,
- it should be possible to copy the contents of the directory specified by the ``%{temp}`` substitution to a remote host where the execution of the test will actually occur.
- * - ``ADDITIONAL_COMPILE_FLAGS``
- - ``// ADDITIONAL_COMPILE_FLAGS: flag1 flag2 ...``
- - The additional compiler flags specified by a space-separated list to the ``ADDITIONAL_COMPILE_FLAGS`` libc++-specific Lit directive will be added to the end of the ``%{compile_flags}``
- substitution for the test that contains it. This libc++-specific Lit directive makes it possible to add special compilation flags without having to resort to writing a ``.sh.cpp`` test (see
- `Lit Meaning of libc++ Test Filenames`_), more powerful but perhaps overkill.
- * - ``MODULE_DEPENDENCIES``
- - ``// MODULE_DEPENDENCIES: std std.compat``
- - This directive will build the required C++23 standard library
- modules and add the additional compiler flags in
- %{compile_flags}. (Libc++ offers these modules in C++20 as an
- extension.)
-
-```
+:::{list-table} libc++-specific Lit Directives
+:widths: 20 35 45
+:header-rows: 1
+
+* - Directive
+ - Parameters
+ - Usage
+* - `FILE_DEPENDENCIES`
+ - `// FILE_DEPENDENCIES: file, directory, /path/to/file, ...`
+ - The paths given to the `FILE_DEPENDENCIES` directive can specify directories or specific files upon which a given test depend. For example, a test that requires some test
+ input stored in a data file would use this libc++-specific Lit directive. When a test file contains the `FILE_DEPENDENCIES` directive, Lit will collect the named files and copy
+ them to the directory represented by the `%{temp}` substitution before the test executes. The copy is performed from the directory represented by the `%S` substitution
+ (i.e. the source directory of the test being executed) which makes it possible to use relative paths to specify the location of dependency files. After Lit copies
+ all the dependent files to the directory specified by the `%{temp}` substitution, that directory should contain *all* the necessary inputs to run. In other words,
+ it should be possible to copy the contents of the directory specified by the `%{temp}` substitution to a remote host where the execution of the test will actually occur.
+* - `ADDITIONAL_COMPILE_FLAGS`
+ - `// ADDITIONAL_COMPILE_FLAGS: flag1 flag2 ...`
+ - The additional compiler flags specified by a space-separated list to the `ADDITIONAL_COMPILE_FLAGS` libc++-specific Lit directive will be added to the end of the `%{compile_flags}`
+ substitution for the test that contains it. This libc++-specific Lit directive makes it possible to add special compilation flags without having to resort to writing a `.sh.cpp` test (see
+ {ref}`Lit Meaning of libc++ Test Filenames <lit-meaning-of-libc-test-filenames>`), more powerful but perhaps overkill.
+* - `MODULE_DEPENDENCIES`
+ - `// MODULE_DEPENDENCIES: std std.compat`
+ - This directive will build the required C++23 standard library
+ modules and add the additional compiler flags in
+ `%{compile_flags}`. (Libc++ offers these modules in C++20 as an
+ extension.)
+:::
#### C++ Standard version tests
@@ -563,4 +556,3 @@ effect logs one, i.e. `enforce` or `observe`.
[google benchmark]: https://github.com/google/benchmark
[lit command guide]: https://llvm.org/docs/CommandGuide/lit.html
-
diff --git a/libcxx/docs/UserDocumentation.md b/libcxx/docs/UserDocumentation.md
index 2f8a5a7fcb2e8e..58e28abcceec7f 100644
--- a/libcxx/docs/UserDocumentation.md
+++ b/libcxx/docs/UserDocumentation.md
@@ -2,9 +2,9 @@
# User documentation
-```{contents}
+:::{contents}
:local: true
-```
+:::
This page contains information for users of libc++: how to use libc++ if it is not
the default library used by the toolchain, and what configuration knobs are available
@@ -71,13 +71,14 @@ Assertion semantics mirror the evaluation semantics of C++26 Contracts but are
not a standard feature.
:::{note}
-Experimental libraries are experimental.
-: - The contents of the `<experimental/...>` headers and the associated static
- library may not remain compatible between versions.
- - No guarantees of API or ABI stability are provided.
- - When the standardized version of an experimental feature is implemented,
- the experimental feature is removed two releases after the non-experimental
- version has shipped. The full policy is explained {ref}`here <experimental features>`.
+**Experimental libraries are experimental.**
+
+- The contents of the `<experimental/...>` headers and the associated static
+ library may not remain compatible between versions.
+- No guarantees of API or ABI stability are provided.
+- When the standardized version of an experimental feature is implemented,
+ the experimental feature is removed two releases after the non-experimental
+ version has shipped. The full policy is explained {ref}`here <experimental features>`.
:::
(libcxx-configuration-macros)=
@@ -94,53 +95,53 @@ only intended to be used by vendors and changing their value from the one provid
in your toolchain can lead to unexpected behavior.
:::
-**\_LIBCPP_DISABLE_DEPRECATION_WARNINGS**:
+**\_LIBCPP_DISABLE_DEPRECATION_WARNINGS**\:
: This macro disables warnings when using deprecated components. For example,
- using `std::auto_ptr` when compiling in C++11 mode will normally trigger a
- warning saying that `std::auto_ptr` is deprecated. If the macro is defined,
+ using {title-reference}`std::auto_ptr` when compiling in C++11 mode will normally trigger a
+ warning saying that {title-reference}`std::auto_ptr` is deprecated. If the macro is defined,
no warning will be emitted. By default, this macro is not defined.
-**\_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS**:
+**\_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS**\:
: This macro is used to disable all visibility annotations inside libc++.
Defining this macro and then building libc++ with hidden visibility gives a
build of libc++ which does not export any symbols, which can be useful when
building statically for inclusion into another library.
-**\_LIBCPP_ENABLE_EXPERIMENTAL**:
+**\_LIBCPP_ENABLE_EXPERIMENTAL**\:
: This macro enables experimental features. This can be used on compilers that do
not support the `-fexperimental-library` flag. When used, users also need to
ensure that the appropriate experimental library (usually `libc++experimental.a`)
is linked into their program.
-**\_LIBCPP_HARDENING_MODE**:
+**\_LIBCPP_HARDENING_MODE**\:
: This macro is used to choose the {ref}`hardening mode <using-hardening-modes>`.
-**\_LIBCPP_NO_VCRUNTIME**:
+**\_LIBCPP_NO_VCRUNTIME**\:
: Microsoft's C and C++ headers are fairly entangled, and some of their C++
- headers are fairly hard to avoid. In particular, `vcruntime_new.h` gets pulled
+ headers are fairly hard to avoid. In particular, {title-reference}`vcruntime_new.h` gets pulled
in from a lot of other headers and provides definitions which clash with
- libc++ headers, such as `nothrow_t` (note that `nothrow_t` is a struct, so
+ libc++ headers, such as {title-reference}`nothrow_t` (note that {title-reference}`nothrow_t` is a struct, so
there's no way for libc++ to provide a compatible definition, since you can't
have multiple definitions).
By default, libc++ solves this problem by deferring to Microsoft's vcruntime
headers where needed. However, it may be undesirable to depend on vcruntime
headers, since they may not always be available in cross-compilation setups,
- or they may clash with other headers. The `_LIBCPP_NO_VCRUNTIME` macro
+ or they may clash with other headers. The {title-reference}`_LIBCPP_NO_VCRUNTIME` macro
prevents libc++ from depending on vcruntime headers. Consequently, it also
prevents libc++ headers from being interoperable with vcruntime headers (from
the aforementioned clashes), so users of this macro are promising to not
attempt to combine libc++ headers with the problematic vcruntime headers. This
- macro also currently prevents certain `operator new`/`operator delete`
- replacement scenarios from working, e.g. replacing `operator new` and
- expecting a non-replaced `operator new[]` to call the replaced `operator new`.
+ macro also currently prevents certain {title-reference}`operator new`/{title-reference}`operator delete`
+ replacement scenarios from working, e.g. replacing {title-reference}`operator new` and
+ expecting a non-replaced {title-reference}`operator new[]` to call the replaced {title-reference}`operator new`.
-**\_LIBCPP_REMOVE_TRANSITIVE_INCLUDES**:
+**\_LIBCPP_REMOVE_TRANSITIVE_INCLUDES**\:
: When this macro is defined, the standard library headers will adhere to a
stricter policy regarding the (transitive) inclusion of other standard library
@@ -165,87 +166,87 @@ in your toolchain can lead to unexpected behavior.
### C++17 Specific Configuration Macros
-**\_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**:
+**\_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**\:
-: This macro is used to re-enable `auto_ptr`.
+: This macro is used to re-enable {title-reference}`auto_ptr`.
-**\_LIBCPP_ENABLE_CXX17_REMOVED_BINDERS**:
+**\_LIBCPP_ENABLE_CXX17_REMOVED_BINDERS**\:
-: This macro is used to re-enable the `binder1st`, `binder2nd`,
- `pointer_to_unary_function`, `pointer_to_binary_function`, `mem_fun_t`,
- `mem_fun1_t`, `mem_fun_ref_t`, `mem_fun1_ref_t`, `const_mem_fun_t`,
- `const_mem_fun1_t`, `const_mem_fun_ref_t`, and `const_mem_fun1_ref_t`
- class templates, and the `bind1st`, `bind2nd`, `mem_fun`, `mem_fun_ref`,
- and `ptr_fun` functions.
+: This macro is used to re-enable the {title-reference}`binder1st`, {title-reference}`binder2nd`,
+ {title-reference}`pointer_to_unary_function`, {title-reference}`pointer_to_binary_function`, {title-reference}`mem_fun_t`,
+ {title-reference}`mem_fun1_t`, {title-reference}`mem_fun_ref_t`, {title-reference}`mem_fun1_ref_t`, {title-reference}`const_mem_fun_t`,
+ {title-reference}`const_mem_fun1_t`, {title-reference}`const_mem_fun_ref_t`, and {title-reference}`const_mem_fun1_ref_t`
+ class templates, and the {title-reference}`bind1st`, {title-reference}`bind2nd`, {title-reference}`mem_fun`, {title-reference}`mem_fun_ref`,
+ and {title-reference}`ptr_fun` functions.
-**\_LIBCPP_ENABLE_CXX17_REMOVED_RANDOM_SHUFFLE**:
+**\_LIBCPP_ENABLE_CXX17_REMOVED_RANDOM_SHUFFLE**\:
-: This macro is used to re-enable the `random_shuffle` algorithm.
+: This macro is used to re-enable the {title-reference}`random_shuffle` algorithm.
-**\_LIBCPP_ENABLE_CXX17_REMOVED_UNARY_BINARY_FUNCTION**:
+**\_LIBCPP_ENABLE_CXX17_REMOVED_UNARY_BINARY_FUNCTION**\:
-: This macro is used to re-enable `unary_function` and `binary_function`.
+: This macro is used to re-enable {title-reference}`unary_function` and {title-reference}`binary_function`.
-**\_LIBCPP_ENABLE_CXX17_REMOVED_UNEXPECTED_FUNCTIONS**:
+**\_LIBCPP_ENABLE_CXX17_REMOVED_UNEXPECTED_FUNCTIONS**\:
-: This macro is used to re-enable `set_unexpected`, `get_unexpected`, and
- `unexpected`.
+: This macro is used to re-enable {title-reference}`set_unexpected`, {title-reference}`get_unexpected`, and
+ {title-reference}`unexpected`.
### C++20 Specific Configuration Macros
-**\_LIBCPP_ENABLE_CXX20_REMOVED_BINDER_TYPEDEFS**:
+**\_LIBCPP_ENABLE_CXX20_REMOVED_BINDER_TYPEDEFS**\:
-: This macro is used to re-enable the `argument_type`, `result_type`,
- `first_argument_type`, and `second_argument_type` members of class
- templates such as `plus`, `logical_not`, `hash`, and `owner_less`.
+: This macro is used to re-enable the {title-reference}`argument_type`, {title-reference}`result_type`,
+ {title-reference}`first_argument_type`, and {title-reference}`second_argument_type` members of class
+ templates such as {title-reference}`plus`, {title-reference}`logical_not`, {title-reference}`hash`, and {title-reference}`owner_less`.
-**\_LIBCPP_ENABLE_CXX20_REMOVED_NEGATORS**:
+**\_LIBCPP_ENABLE_CXX20_REMOVED_NEGATORS**\:
-: This macro is used to re-enable `not1`, `not2`, `unary_negate`,
- and `binary_negate`.
+: This macro is used to re-enable {title-reference}`not1`, {title-reference}`not2`, {title-reference}`unary_negate`,
+ and {title-reference}`binary_negate`.
-**\_LIBCPP_ENABLE_CXX20_REMOVED_RAW_STORAGE_ITERATOR**:
+**\_LIBCPP_ENABLE_CXX20_REMOVED_RAW_STORAGE_ITERATOR**\:
-: This macro is used to re-enable `raw_storage_iterator`.
+: This macro is used to re-enable {title-reference}`raw_storage_iterator`.
-**\_LIBCPP_ENABLE_CXX20_REMOVED_SHARED_PTR_UNIQUE**:
+**\_LIBCPP_ENABLE_CXX20_REMOVED_SHARED_PTR_UNIQUE**\:
: This macro is used to re-enable the function
`std::shared_ptr<...>::unique()`.
-**\_LIBCPP_ENABLE_CXX20_REMOVED_TEMPORARY_BUFFER**:
+**\_LIBCPP_ENABLE_CXX20_REMOVED_TEMPORARY_BUFFER**\:
-: This macro is used to re-enable `get_temporary_buffer` and `return_temporary_buffer`.
+: This macro is used to re-enable {title-reference}`get_temporary_buffer` and {title-reference}`return_temporary_buffer`.
-**\_LIBCPP_ENABLE_CXX20_REMOVED_TYPE_TRAITS**:
+**\_LIBCPP_ENABLE_CXX20_REMOVED_TYPE_TRAITS**\:
-: This macro is used to re-enable `is_literal_type`, `is_literal_type_v`,
- `result_of` and `result_of_t`.
+: This macro is used to re-enable {title-reference}`is_literal_type`, {title-reference}`is_literal_type_v`,
+ {title-reference}`result_of` and {title-reference}`result_of_t`.
-**\_LIBCPP_ENABLE_CXX20_REMOVED_UNCAUGHT_EXCEPTION**:
+**\_LIBCPP_ENABLE_CXX20_REMOVED_UNCAUGHT_EXCEPTION**\:
-: This macro is used to re-enable `uncaught_exception`.
+: This macro is used to re-enable {title-reference}`uncaught_exception`.
### C++26 Specific Configuration Macros
-**\_LIBCPP_ENABLE_CXX26_REMOVED_ALLOCATOR_MEMBERS**:
+**\_LIBCPP_ENABLE_CXX26_REMOVED_ALLOCATOR_MEMBERS**\:
: This macro is used to re-enable redundant member of `allocator<T>::is_always_equal`.
-**\_LIBCPP_ENABLE_CXX26_REMOVED_CODECVT**:
+**\_LIBCPP_ENABLE_CXX26_REMOVED_CODECVT**\:
: This macro is used to re-enable all named declarations in `<codecvt>`.
-**\_LIBCPP_ENABLE_CXX26_REMOVED_STRING_RESERVE**:
+**\_LIBCPP_ENABLE_CXX26_REMOVED_STRING_RESERVE**\:
: This macro is used to re-enable the function
`std::basic_string<...>::reserve()`.
-**\_LIBCPP_ENABLE_CXX26_REMOVED_STRSTREAM**:
+**\_LIBCPP_ENABLE_CXX26_REMOVED_STRSTREAM**\:
: This macro is used to re-enable all named declarations in `<strstream>`.
-**\_LIBCPP_ENABLE_CXX26_REMOVED_WSTRING_CONVERT**:
+**\_LIBCPP_ENABLE_CXX26_REMOVED_WSTRING_CONVERT**\:
: This macro is used to re-enable the `wstring_convert` and `wbuffer_convert`
in `<locale>`.
@@ -438,4 +439,3 @@ $ include-what-you-use -Xiwyu --mapping_file=/path/to/libcxx/include/libcxx.imp
If you would prefer to not use that flag, then you can replace `/path/to/include-what-you-use/share/libcxx.imp`
file with the libc++-provided `libcxx.imp` file.
-
diff --git a/libcxx/docs/VendorDocumentation.md b/libcxx/docs/VendorDocumentation.md
index 4ff5472ca5ea36..424eb5d58d868c 100644
--- a/libcxx/docs/VendorDocumentation.md
+++ b/libcxx/docs/VendorDocumentation.md
@@ -38,7 +38,7 @@ $ ninja -C build install-cxx install-cxxabi install-unwind
```
:::{note}
-See {ref}`Vendor Configuration Options` below for more configuration options.
+See [Vendor Configuration Options](#vendor-configuration-options) below for more configuration options.
:::
After building the various `install-XXX` targets, shared libraries for libc++, libc++abi and
@@ -186,7 +186,7 @@ C Standard Libraries don't always provide all the usual bells and whistles.
Whether to include support for time zones in the library. Disabling
time zone support can be useful when porting to platforms that don't
ship the IANA time zone database. When time zones are not supported,
-time zone support in \<chrono> will be disabled.
+time zone support in `<chrono>` will be disabled.
:::
:::{option} LIBCXX_INSTALL_LIBRARY_DIR:PATH
@@ -652,4 +652,3 @@ removed from the library. The minimum header version can be set with the CMake v
[libc++abi]: http://libcxxabi.llvm.org/
[libcxxrt]: https://github.com/libcxxrt/libcxxrt
-
diff --git a/libcxx/docs/index.md b/libcxx/docs/index.md
index 9a74d39a6c4400..2f7de426897581 100644
--- a/libcxx/docs/index.md
+++ b/libcxx/docs/index.md
@@ -225,9 +225,12 @@ DesignDocs/WindowsSupport
- [LLVM Homepage](https://llvm.org/)
- [libc++abi Homepage](http://libcxxabi.llvm.org/)
-- [LLVM Bug Tracker](https://github.com/llvm/llvm-project/labels/libc++/)
+- [LLVM Bug Tracker]
- [libcxx-commits Mailing List](http://lists.llvm.org/mailman/listinfo/libcxx-commits)
-- [libc++ forum](https://discourse.llvm.org/c/runtimes/libcxx/)
-- [libc++ chat](https://discord.com/channels/636084430946959380/636732894974312448) ([invite link](https://discord.gg/xS7Z362))
+- [libc++ forum]
+- [libc++ chat] ([invite link](https://discord.gg/xS7Z362))
- [Browse libc++ Sources](https://github.com/llvm/llvm-project/tree/main/libcxx/)
+[LLVM Bug Tracker]: https://github.com/llvm/llvm-project/labels/libc++/
+[libc++ forum]: https://discourse.llvm.org/c/runtimes/libcxx/
+[libc++ chat]: https://discord.com/channels/636084430946959380/636732894974312448
>From 70df14c4cfa37cbd8ce68de37391ce5847693eae Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Sun, 27 Sep 2026 16:06:35 +0000
Subject: [PATCH 3/4] [libc++][docs] Continue batch 2 rewrite after dependency
update
>From a02e6b09a9848fd3e211df03ce8996448f7dd94c Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Sun, 27 Sep 2026 16:28:03 +0000
Subject: [PATCH 4/4] [libc++][docs] Clean up Markdown conversion artifacts
---
libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md | 86 +++++++++----------
.../UnspecifiedBehaviorRandomization.md | 2 +-
libcxx/docs/DesignDocs/VisibilityMacros.md | 30 +++----
libcxx/docs/ImplementationDefinedBehavior.md | 9 +-
libcxx/docs/TestingLibcxx.md | 8 +-
libcxx/docs/UserDocumentation.md | 58 ++++++-------
6 files changed, 96 insertions(+), 97 deletions(-)
diff --git a/libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md b/libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md
index af65c7bd6e32fd..26631ba34b2ae1 100644
--- a/libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md
+++ b/libcxx/docs/DesignDocs/UniquePtrTrivialAbi.md
@@ -55,7 +55,7 @@ Google has measured performance improvements of up to 1.6% on some large server
This also affects null pointer optimization
-Clang's optimizer can now figure out when a {title-reference}`std::unique_ptr` is known to contain *non*-null.
+Clang's optimizer can now figure out when a `std::unique_ptr` is known to contain *non*-null.
(Actually, this has been a *missed* optimization all along.)
```cpp
@@ -82,50 +82,50 @@ The following breakages were discovered by enabling this change and fixing the r
- Compilation failures
-> - Function definitions now require complete type `T` for parameters with type `std::unique_ptr<T>`. The following code will no longer compile.
->
-> ```cpp
-> class Foo;
-> void func(std::unique_ptr<Foo> arg) { /* never use `arg` directly */ }
-> ```
->
-> - Fix: Remove forward-declaration of `Foo` and include its proper header.
+ - Function definitions now require complete type `T` for parameters with type `std::unique_ptr<T>`. The following code will no longer compile.
+
+ ```cpp
+ class Foo;
+ void func(std::unique_ptr<Foo> arg) { /* never use `arg` directly */ }
+ ```
+
+ - Fix: Remove forward-declaration of `Foo` and include its proper header.
- Runtime Failures
-> - Lifetime of `std::unique_ptr<>` arguments end earlier (at the end of the callee's body, rather than at the end of the full expression containing the call).
->
-> ```cpp
-> util::Status run_worker(std::unique_ptr<Foo>);
-> void func() {
-> std::unique_ptr<Foo> smart_foo = ...;
-> Foo* owned_foo = smart_foo.get();
-> // Currently, the following would "work" because the argument to run_worker() is deleted at the end of func()
-> // With the new calling convention, it will be deleted at the end of run_worker(),
-> // making this an access to freed memory.
-> owned_foo->Bar(run_worker(std::move(smart_foo)));
-> ^
-> // <<<Crash expected here
-> }
-> ```
->
-> - Lifetime of local *returned* `std::unique_ptr<>` ends earlier.
->
-> Spot the bug:
->
-> > ```cpp
-> > std::unique_ptr<Foo> create_and_subscribe(Bar* subscriber) {
-> > auto foo = std::make_unique<Foo>();
-> > subscriber->sub([&foo] { foo->do_thing();} );
-> > return foo;
-> > }
-> > ```
->
-> One could point out this is an obvious stack-use-after return bug.
-> With the current calling convention, running this code with ASAN enabled, however, would not yield any "issue".
-> So is this a bug in ASAN? (Spoiler: No)
->
-> This currently would "work" only because the storage for `foo` is in the caller's stackframe.
-> In other words, `&foo` in callee and `&foo` in the caller are the same address.
+ - Lifetime of `std::unique_ptr<>` arguments end earlier (at the end of the callee's body, rather than at the end of the full expression containing the call).
+
+ ```cpp
+ util::Status run_worker(std::unique_ptr<Foo>);
+ void func() {
+ std::unique_ptr<Foo> smart_foo = ...;
+ Foo* owned_foo = smart_foo.get();
+ // Currently, the following would "work" because the argument to run_worker() is deleted at the end of func()
+ // With the new calling convention, it will be deleted at the end of run_worker(),
+ // making this an access to freed memory.
+ owned_foo->Bar(run_worker(std::move(smart_foo)));
+ ^
+ // <<<Crash expected here
+ }
+ ```
+
+ - Lifetime of local *returned* `std::unique_ptr<>` ends earlier.
+
+ Spot the bug:
+
+ ```cpp
+ std::unique_ptr<Foo> create_and_subscribe(Bar* subscriber) {
+ auto foo = std::make_unique<Foo>();
+ subscriber->sub([&foo] { foo->do_thing();} );
+ return foo;
+ }
+ ```
+
+ One could point out this is an obvious stack-use-after return bug.
+ With the current calling convention, running this code with ASAN enabled, however, would not yield any "issue".
+ So is this a bug in ASAN? (Spoiler: No)
+
+ This currently would "work" only because the storage for `foo` is in the caller's stackframe.
+ In other words, `&foo` in callee and `&foo` in the caller are the same address.
ASAN can be used to detect both of these.
diff --git a/libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.md b/libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.md
index 4d608cc1dabd24..eb03f8daa514e6 100644
--- a/libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.md
+++ b/libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.md
@@ -24,7 +24,7 @@ algorithms and optimizations to the containers.
For example, as of LLVM version 13, libcxx sorting algorithm takes
[O(n^2) worst case](https://llvm.org/PR20837) but according
-to the standard its worst case should be {title-reference}`O(n log n)`. This effort helps users
+to the standard its worst case should be `O(n log n)`. This effort helps users
to gradually fix their tests while updating to new faster algorithms.
## Design
diff --git a/libcxx/docs/DesignDocs/VisibilityMacros.md b/libcxx/docs/DesignDocs/VisibilityMacros.md
index 9ea35d82b2b701..bea6092c79aab5 100644
--- a/libcxx/docs/DesignDocs/VisibilityMacros.md
+++ b/libcxx/docs/DesignDocs/VisibilityMacros.md
@@ -29,7 +29,7 @@ default visibility, thus removing the need for any annotations.
: Mark a symbol as being part of our ABI. This includes functions that are part
of the libc++ library, type information and other symbols. On Windows,
- this macro applies {title-reference}`dllimport`/{title-reference}`dllexport` to the symbol, and on other
+ this macro applies `dllimport`/`dllexport` to the symbol, and on other
platforms it gives the symbol default visibility. This macro should never be
used on class templates. On classes it should only be used if the vtable
lives in the built library.
@@ -37,14 +37,14 @@ default visibility, thus removing the need for any annotations.
**\_LIBCPP_OVERRIDABLE_FUNC_VIS**
: Mark a symbol as being exported by the libc++ library, but allow it to be
- overridden locally. On non-Windows, this is equivalent to {title-reference}`_LIBCPP_FUNC_VIS`.
- This macro is applied to all {title-reference}`operator new` and {title-reference}`operator delete` overloads.
-
- **Windows Behavior**: Any symbol marked {title-reference}`dllimport` cannot be overridden
- locally, since {title-reference}`dllimport` indicates the symbol should be bound to a separate
- DLL. All {title-reference}`operator new` and {title-reference}`operator delete` overloads are required to be
- locally overridable, and therefore must not be marked {title-reference}`dllimport`. On Windows,
- this macro therefore expands to {title-reference}`__declspec(dllexport)` when building the
+ overridden locally. On non-Windows, this is equivalent to `_LIBCPP_FUNC_VIS`.
+ This macro is applied to all `operator new` and `operator delete` overloads.
+
+ **Windows Behavior**: Any symbol marked `dllimport` cannot be overridden
+ locally, since `dllimport` indicates the symbol should be bound to a separate
+ DLL. All `operator new` and `operator delete` overloads are required to be
+ locally overridable, and therefore must not be marked `dllimport`. On Windows,
+ this macro therefore expands to `__declspec(dllexport)` when building the
library and has an empty definition otherwise.
**\_LIBCPP_HIDE_FROM_ABI**
@@ -54,7 +54,7 @@ default visibility, thus removing the need for any annotations.
**\_LIBCPP_HIDE_FROM_ABI_AFTER_V1**
-: Mark a function as being hidden from the ABI (per {title-reference}`_LIBCPP_HIDE_FROM_ABI`)
+: Mark a function as being hidden from the ABI (per `_LIBCPP_HIDE_FROM_ABI`)
when libc++ is built with an ABI version after ABI v1. This macro is used to
maintain ABI compatibility for symbols that have been historically exported
by libc++ in v1 of the ABI, but that we don't want to export in the future.
@@ -77,16 +77,16 @@ default visibility, thus removing the need for any annotations.
This macro is used to export the member functions produced by the explicit
instantiation in the dylib.
- **Windows Behavior**: {title-reference}`extern template` and {title-reference}`dllexport` are fundamentally
+ **Windows Behavior**: `extern template` and `dllexport` are fundamentally
incompatible *on a class template* on Windows; the former suppresses
instantiation, while the latter forces it. Specifying both on the same
declaration makes the class template be instantiated, which is not desirable
- inside headers. This macro therefore expands to {title-reference}`dllimport` outside of libc++
- but nothing inside of it (rather than expanding to {title-reference}`dllexport`); instead, the
+ inside headers. This macro therefore expands to `dllimport` outside of libc++
+ but nothing inside of it (rather than expanding to `dllexport`); instead, the
explicit instantiations themselves are marked as exported. Note that this
applies *only* to extern *class* templates. Extern *function* templates obey
- regular import/export semantics, and applying {title-reference}`dllexport` directly to the
- extern template declaration (i.e. using {title-reference}`_LIBCPP_FUNC_VIS`) is the correct
+ regular import/export semantics, and applying `dllexport` directly to the
+ extern template declaration (i.e. using `_LIBCPP_FUNC_VIS`) is the correct
thing to do for them.
**\_LIBCPP_CLASS_TEMPLATE_INSTANTIATION_VIS**
diff --git a/libcxx/docs/ImplementationDefinedBehavior.md b/libcxx/docs/ImplementationDefinedBehavior.md
index 355b978a393130..233033662482ed 100644
--- a/libcxx/docs/ImplementationDefinedBehavior.md
+++ b/libcxx/docs/ImplementationDefinedBehavior.md
@@ -15,10 +15,10 @@ The C++ standard mandates that implementation-defined behavior is documented.
The C++ standard allows implementations to automatically update the
*remote time zone database*. Libc++ opts not to do that. Instead calling
-> - `std::chrono::remote_version()` will update the version information of the
-> *remote time zone database*,
-> - `std::chrono::reload_tzdb()`, if needed, will update the entire
-> *remote time zone database*.
+- `std::chrono::remote_version()` will update the version information of the
+ *remote time zone database*,
+- `std::chrono::reload_tzdb()`, if needed, will update the entire
+ *remote time zone database*.
This offers a way for users to update the *remote time zone database* and
give them full control over the process.
@@ -66,4 +66,3 @@ to its capacity and uses that size. This means the SSO buffer of
The order of the entries matches the entries in the
[draft of the Standard](http://eel.is/c++draft/impldefindex).
-
diff --git a/libcxx/docs/TestingLibcxx.md b/libcxx/docs/TestingLibcxx.md
index 158784f0980df1..644f58794b80d7 100644
--- a/libcxx/docs/TestingLibcxx.md
+++ b/libcxx/docs/TestingLibcxx.md
@@ -234,10 +234,10 @@ failure can be found without resorting to a debugger.
Several of these macros are documented to take an `ARG`. This `ARG`:
-> - if it is a `const char*` or `std::string` its contents are written to
-> the `stderr`,
-> - otherwise it must be a callable that is invoked without any additional
-> arguments and is expected to produce useful output to e.g. `stderr`.
+- if it is a `const char*` or `std::string` its contents are written to
+ the `stderr`,
+- otherwise it must be a callable that is invoked without any additional
+ arguments and is expected to produce useful output to e.g. `stderr`.
This makes it possible to write additional information when a test fails,
either by supplying a hard-coded string or generate it at runtime.
diff --git a/libcxx/docs/UserDocumentation.md b/libcxx/docs/UserDocumentation.md
index 58e28abcceec7f..51a6d6955a34bb 100644
--- a/libcxx/docs/UserDocumentation.md
+++ b/libcxx/docs/UserDocumentation.md
@@ -98,8 +98,8 @@ in your toolchain can lead to unexpected behavior.
**\_LIBCPP_DISABLE_DEPRECATION_WARNINGS**\:
: This macro disables warnings when using deprecated components. For example,
- using {title-reference}`std::auto_ptr` when compiling in C++11 mode will normally trigger a
- warning saying that {title-reference}`std::auto_ptr` is deprecated. If the macro is defined,
+ using `std::auto_ptr` when compiling in C++11 mode will normally trigger a
+ warning saying that `std::auto_ptr` is deprecated. If the macro is defined,
no warning will be emitted. By default, this macro is not defined.
**\_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS**\:
@@ -123,23 +123,23 @@ in your toolchain can lead to unexpected behavior.
**\_LIBCPP_NO_VCRUNTIME**\:
: Microsoft's C and C++ headers are fairly entangled, and some of their C++
- headers are fairly hard to avoid. In particular, {title-reference}`vcruntime_new.h` gets pulled
+ headers are fairly hard to avoid. In particular, `vcruntime_new.h` gets pulled
in from a lot of other headers and provides definitions which clash with
- libc++ headers, such as {title-reference}`nothrow_t` (note that {title-reference}`nothrow_t` is a struct, so
+ libc++ headers, such as `nothrow_t` (note that `nothrow_t` is a struct, so
there's no way for libc++ to provide a compatible definition, since you can't
have multiple definitions).
By default, libc++ solves this problem by deferring to Microsoft's vcruntime
headers where needed. However, it may be undesirable to depend on vcruntime
headers, since they may not always be available in cross-compilation setups,
- or they may clash with other headers. The {title-reference}`_LIBCPP_NO_VCRUNTIME` macro
+ or they may clash with other headers. The `_LIBCPP_NO_VCRUNTIME` macro
prevents libc++ from depending on vcruntime headers. Consequently, it also
prevents libc++ headers from being interoperable with vcruntime headers (from
the aforementioned clashes), so users of this macro are promising to not
attempt to combine libc++ headers with the problematic vcruntime headers. This
- macro also currently prevents certain {title-reference}`operator new`/{title-reference}`operator delete`
- replacement scenarios from working, e.g. replacing {title-reference}`operator new` and
- expecting a non-replaced {title-reference}`operator new[]` to call the replaced {title-reference}`operator new`.
+ macro also currently prevents certain `operator new`/`operator delete`
+ replacement scenarios from working, e.g. replacing `operator new` and
+ expecting a non-replaced `operator new[]` to call the replaced `operator new`.
**\_LIBCPP_REMOVE_TRANSITIVE_INCLUDES**\:
@@ -168,46 +168,46 @@ in your toolchain can lead to unexpected behavior.
**\_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**\:
-: This macro is used to re-enable {title-reference}`auto_ptr`.
+: This macro is used to re-enable `auto_ptr`.
**\_LIBCPP_ENABLE_CXX17_REMOVED_BINDERS**\:
-: This macro is used to re-enable the {title-reference}`binder1st`, {title-reference}`binder2nd`,
- {title-reference}`pointer_to_unary_function`, {title-reference}`pointer_to_binary_function`, {title-reference}`mem_fun_t`,
- {title-reference}`mem_fun1_t`, {title-reference}`mem_fun_ref_t`, {title-reference}`mem_fun1_ref_t`, {title-reference}`const_mem_fun_t`,
- {title-reference}`const_mem_fun1_t`, {title-reference}`const_mem_fun_ref_t`, and {title-reference}`const_mem_fun1_ref_t`
- class templates, and the {title-reference}`bind1st`, {title-reference}`bind2nd`, {title-reference}`mem_fun`, {title-reference}`mem_fun_ref`,
- and {title-reference}`ptr_fun` functions.
+: This macro is used to re-enable the `binder1st`, `binder2nd`,
+ `pointer_to_unary_function`, `pointer_to_binary_function`, `mem_fun_t`,
+ `mem_fun1_t`, `mem_fun_ref_t`, `mem_fun1_ref_t`, `const_mem_fun_t`,
+ `const_mem_fun1_t`, `const_mem_fun_ref_t`, and `const_mem_fun1_ref_t`
+ class templates, and the `bind1st`, `bind2nd`, `mem_fun`, `mem_fun_ref`,
+ and `ptr_fun` functions.
**\_LIBCPP_ENABLE_CXX17_REMOVED_RANDOM_SHUFFLE**\:
-: This macro is used to re-enable the {title-reference}`random_shuffle` algorithm.
+: This macro is used to re-enable the `random_shuffle` algorithm.
**\_LIBCPP_ENABLE_CXX17_REMOVED_UNARY_BINARY_FUNCTION**\:
-: This macro is used to re-enable {title-reference}`unary_function` and {title-reference}`binary_function`.
+: This macro is used to re-enable `unary_function` and `binary_function`.
**\_LIBCPP_ENABLE_CXX17_REMOVED_UNEXPECTED_FUNCTIONS**\:
-: This macro is used to re-enable {title-reference}`set_unexpected`, {title-reference}`get_unexpected`, and
- {title-reference}`unexpected`.
+: This macro is used to re-enable `set_unexpected`, `get_unexpected`, and
+ `unexpected`.
### C++20 Specific Configuration Macros
**\_LIBCPP_ENABLE_CXX20_REMOVED_BINDER_TYPEDEFS**\:
-: This macro is used to re-enable the {title-reference}`argument_type`, {title-reference}`result_type`,
- {title-reference}`first_argument_type`, and {title-reference}`second_argument_type` members of class
- templates such as {title-reference}`plus`, {title-reference}`logical_not`, {title-reference}`hash`, and {title-reference}`owner_less`.
+: This macro is used to re-enable the `argument_type`, `result_type`,
+ `first_argument_type`, and `second_argument_type` members of class
+ templates such as `plus`, `logical_not`, `hash`, and `owner_less`.
**\_LIBCPP_ENABLE_CXX20_REMOVED_NEGATORS**\:
-: This macro is used to re-enable {title-reference}`not1`, {title-reference}`not2`, {title-reference}`unary_negate`,
- and {title-reference}`binary_negate`.
+: This macro is used to re-enable `not1`, `not2`, `unary_negate`,
+ and `binary_negate`.
**\_LIBCPP_ENABLE_CXX20_REMOVED_RAW_STORAGE_ITERATOR**\:
-: This macro is used to re-enable {title-reference}`raw_storage_iterator`.
+: This macro is used to re-enable `raw_storage_iterator`.
**\_LIBCPP_ENABLE_CXX20_REMOVED_SHARED_PTR_UNIQUE**\:
@@ -216,16 +216,16 @@ in your toolchain can lead to unexpected behavior.
**\_LIBCPP_ENABLE_CXX20_REMOVED_TEMPORARY_BUFFER**\:
-: This macro is used to re-enable {title-reference}`get_temporary_buffer` and {title-reference}`return_temporary_buffer`.
+: This macro is used to re-enable `get_temporary_buffer` and `return_temporary_buffer`.
**\_LIBCPP_ENABLE_CXX20_REMOVED_TYPE_TRAITS**\:
-: This macro is used to re-enable {title-reference}`is_literal_type`, {title-reference}`is_literal_type_v`,
- {title-reference}`result_of` and {title-reference}`result_of_t`.
+: This macro is used to re-enable `is_literal_type`, `is_literal_type_v`,
+ `result_of` and `result_of_t`.
**\_LIBCPP_ENABLE_CXX20_REMOVED_UNCAUGHT_EXCEPTION**\:
-: This macro is used to re-enable {title-reference}`uncaught_exception`.
+: This macro is used to re-enable `uncaught_exception`.
### C++26 Specific Configuration Macros
More information about the llvm-branch-commits
mailing list