Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Polishing documentation of libc++ #132962

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 22 commits into from
May 12, 2025
Merged

Polishing documentation of libc++ #132962

merged 22 commits into from
May 12, 2025

Conversation

martinlicht
Copy link
Contributor

  • Some lists re-ordered alphabetically
  • numerous instances of spelling, grammar, language

@martinlicht martinlicht requested a review from a team as a code owner March 25, 2025 17:35
@llvmbot llvmbot added the libc++ libc++ C++ Standard Library. Not GNU libstdc++. Not libc++abi. label Mar 25, 2025
@llvmbot
Copy link
Member

llvmbot commented Mar 25, 2025

@llvm/pr-subscribers-libcxx

Author: Martin Licht (martinlicht)

Changes
  • Some lists re-ordered alphabetically
  • numerous instances of spelling, grammar, language

Patch is 22.59 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/132962.diff

5 Files Affected:

  • (modified) libcxx/docs/CodingGuidelines.rst (+6-6)
  • (modified) libcxx/docs/Hardening.rst (+8-8)
  • (modified) libcxx/docs/ImplementationDefinedBehavior.rst (+6-6)
  • (modified) libcxx/docs/Modules.rst (+1-1)
  • (modified) libcxx/docs/UserDocumentation.rst (+67-66)
diff --git a/libcxx/docs/CodingGuidelines.rst b/libcxx/docs/CodingGuidelines.rst
index c783a4f2e4e72..21c5dd78ae298 100644
--- a/libcxx/docs/CodingGuidelines.rst
+++ b/libcxx/docs/CodingGuidelines.rst
@@ -79,9 +79,9 @@ and then check for ``#if _LIBCPP_SOMETHING_ENABLED`` instead of
 
 and then checking for ``#ifdef _LIBCPP_SOMETHING_ENABLED``.
 
-This makes it significantly easier to catch missing includes, since Clang and GCC will warn when using and undefined
-marco inside an ``#if`` statement when using ``-Wundef``. Some macros in libc++ don't use this style yet, so this only
-applies when introducing a new macro.
+This makes it significantly easier to catch missing includes: Clang and GCC with ``-Wundef`` enabled will warn
+when using an undefined macro inside an ``#if`` statement. Some macros in libc++ don't use this style yet,
+so this guidelines only applies when introducing a new macro.
 
 This is partially enforced by the clang-tidy check ``libcpp-internal-ftms``.
 
@@ -107,9 +107,9 @@ This is enforced by the clang-tidy check ``libcpp-uglify-attributes``.
 Use C++11 extensions in C++03 code if they simplify the code
 ============================================================
 
-libc++ only supports Clang in C++98/03 mode. Clang provides many C++11 features in C++03, making it possible to write a
-lot of code in a simpler way than if we were restricted to C++03 features. Some use of extensions is even mandatory,
-since libc++ supports move semantics in C++03.
+libc++ supports the C++98/03 mode only with the Clang compiler. Clang provides many C++11 features
+in C++03, making it possible to write a lot of code in a simpler way than if we were restricted to C++03 features.
+Some use of extensions is even mandatory, since libc++ supports move semantics in C++03.
 
 Use ``using`` aliases instead of ``typedef``
 ============================================
diff --git a/libcxx/docs/Hardening.rst b/libcxx/docs/Hardening.rst
index 097ad4b73b126..dc0322556023d 100644
--- a/libcxx/docs/Hardening.rst
+++ b/libcxx/docs/Hardening.rst
@@ -32,8 +32,8 @@ modes are:
   including heuristic checks that might have significant performance overhead as
   well as internal library assertions. This mode should be used in
   non-production environments (such as test suites, CI, or local development).
-  We don’t commit to a particular level of performance in this mode and it’s
-  *not* intended to be used in production.
+  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::
 
@@ -155,13 +155,13 @@ easier to reason about the high-level semantics of a hardening mode.
   in the library -- whatever the consequences are, they will happen in the user
   code.
 
-- ``pedantic`` -- checks preconditions that are imposed by the Standard, but
-  violating which happens to be benign in libc++.
+- ``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 requirements imposed by the 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.
+  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
   assertions don't depend on user input.
@@ -239,7 +239,7 @@ Mapping between the hardening modes and the assertion categories
 
 .. note::
 
-  The categories enabled by each mode are subject to change and users should not
+  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.
diff --git a/libcxx/docs/ImplementationDefinedBehavior.rst b/libcxx/docs/ImplementationDefinedBehavior.rst
index 1f95de77db0eb..153823fa0067e 100644
--- a/libcxx/docs/ImplementationDefinedBehavior.rst
+++ b/libcxx/docs/ImplementationDefinedBehavior.rst
@@ -4,8 +4,8 @@
 Implementation-defined behavior
 ===============================
 
-Contains the implementation details of the implementation-defined behavior in
-libc++. Implementation-defined is mandated to be documented by the Standard.
+This page contains the implementation details of the implementation-defined behavior in libc++.
+The C++ standard mandates that implementation-defined behavior be documented.
 
 .. note:
    This page is far from complete.
@@ -17,7 +17,7 @@ Implementation-defined behavior
 Updating the Time Zone Database
 -------------------------------
 
-The Standard allows implementations to automatically update the
+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
@@ -32,7 +32,7 @@ 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
 --------------------------------------------------------------------------------------------------------------------------
 
-The Standard specifies that the manner in which a stream is determined to refer
+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.
 
@@ -55,9 +55,9 @@ Libc++ determines that a stream is Unicode-capable terminal by:
 ----------------------------------------------------------------------------------------
 
 Most functions within the Mathematical Special Functions section contain integral indices.
-The Standard specifies the result for larger indices as implementation-defined.
+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.
+E.g.,
 
 - ``std::hermite(unsigned n, T x)`` for ``n >= 128``
 
diff --git a/libcxx/docs/Modules.rst b/libcxx/docs/Modules.rst
index 352a198f3774d..ebd851fed95fc 100644
--- a/libcxx/docs/Modules.rst
+++ b/libcxx/docs/Modules.rst
@@ -24,7 +24,7 @@ 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
-on the compiler used and its compilation flags. Therefore there needs to be a
+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
 systems in the future. To aid early adaptor and build system vendors libc++
diff --git a/libcxx/docs/UserDocumentation.rst b/libcxx/docs/UserDocumentation.rst
index 4a11a10224ae9..6c71511aa60df 100644
--- a/libcxx/docs/UserDocumentation.rst
+++ b/libcxx/docs/UserDocumentation.rst
@@ -7,29 +7,29 @@ User documentation
 .. contents::
   :local:
 
-This page contains information about configuration knobs that can be used by
-users when they know libc++ is used by their toolchain, and how to use libc++
-when it is not the default library used by their toolchain. It is aimed at
-users of libc++: a separate page contains documentation aimed at vendors who
-build and ship libc++ as part of their toolchain.
+This page contains information about 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 if libc++ is used by the toolchain.
+This page is aimed at users of libc++, whereas a 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
 =============================================
 
-Libc++ implements the various versions of the C++ Standard. Changing the version of
+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
-automatically detect what Standard is being used and will provide functionality that
-matches that Standard in the library.
+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
 
-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 Standard that hasn't been ratified yet. Use
-these versions of the Standard at your own risk.
+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
@@ -39,16 +39,16 @@ Usually, libc++ is packaged and shipped by a vendor through some delivery vehicl
 (operating system distribution, SDK, toolchain, etc) and users don't need to do
 anything special in order to use the library.
 
-On systems where libc++ is provided but is not the default, Clang provides a flag
-called ``-stdlib=`` that can be used to decide which standard library is used.
+However, on systems where libc++ is provided but is not the default, we can envoke
+Clang with the flag ``-stdlib=`` to decide which standard library is used.
 Using ``-stdlib=libc++`` will select libc++:
 
 .. code-block:: bash
 
   $ clang++ -stdlib=libc++ test.cpp
 
-On systems where libc++ is the library in use by default such as macOS and FreeBSD,
-this flag is not required.
+This flag is not required on systems where libc++ is the library in use by default,
+such as macOS and FreeBSD.
 
 
 Enabling experimental C++ Library features
@@ -56,9 +56,9 @@ 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 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, the
-``-fexperimental-library`` compiler flag can be defined to turn those features on.
+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 define 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
@@ -75,7 +75,7 @@ when ``-fexperimental-library`` is passed:
 .. note::
   Experimental libraries are experimental.
     * The contents of the ``<experimental/...>`` headers and the associated static
-      library will not remain compatible between versions.
+      library will generally 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
@@ -94,6 +94,24 @@ enable or disable extended libc++ behavior.
   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**:
+  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++.
+  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``)
+  is linked into their program.
+
 **_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS**:
   This macro is used to enable -Wthread-safety annotations on libc++'s
   ``std::mutex`` and ``std::lock_guard``. By default, these annotations are
@@ -102,12 +120,6 @@ enable or disable extended libc++ behavior.
 **_LIBCPP_HARDENING_MODE**:
   This macro is used to choose the :ref:`hardening mode <using-hardening-modes>`.
 
-**_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_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
@@ -132,7 +144,7 @@ enable or disable extended libc++ behavior.
   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
+  the standard. Please notice that defining this macro might break existing codebasesgit
   that implicitly rely on standard headers providing definitions not explicitly
   required by the standard.
 
@@ -150,18 +162,6 @@ 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.
 
-**_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,
-  no warning will be emitted. By default, this macro is not defined.
-
-**_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.
-
 C++17 Specific Configuration Macros
 -----------------------------------
 **_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**:
@@ -187,13 +187,6 @@ C++17 Specific Configuration Macros
 
 C++20 Specific Configuration Macros
 -----------------------------------
-**_LIBCPP_ENABLE_CXX20_REMOVED_UNCAUGHT_EXCEPTION**:
-  This macro is used to re-enable `uncaught_exception`.
-
-**_LIBCPP_ENABLE_CXX20_REMOVED_SHARED_PTR_UNIQUE**:
-  This macro is used to re-enable the function
-  ``std::shared_ptr<...>::unique()``.
-
 **_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
@@ -206,6 +199,10 @@ C++20 Specific Configuration Macros
 **_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_TEMPORARY_BUFFER**:
   This macro is used to re-enable `get_temporary_buffer` and `return_temporary_buffer`.
 
@@ -213,10 +210,15 @@ C++20 Specific Configuration Macros
   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`.
 
 C++26 Specific Configuration Macros
 -----------------------------------
 
+**_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**:
   This macro is used to re-enable all named declarations in ``<codecvt>``.
 
@@ -224,9 +226,6 @@ C++26 Specific Configuration Macros
   This macro is used to re-enable the function
   ``std::basic_string<...>::reserve()``.
 
-**_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_STRSTREAM**:
   This macro is used to re-enable all named declarations in ``<strstream>``.
 
@@ -237,22 +236,22 @@ C++26 Specific Configuration Macros
 Libc++ Extensions
 =================
 
-This section documents various extensions provided by libc++, how they're
-provided, and any information regarding how to use them.
+This section documents various extensions to the C++ standard library
+provided by libc++ and any information regarding how to use them.
 
 Extended integral type support
 ------------------------------
 
-Several platforms support types that are not specified in the Standard, 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:
+Several platforms support types that are not specified in the C++ standard,
+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>``
-* ``<type_traits>``
 * ``<format>``
+* ``<type_traits>``
 * ``<random>``
 
 Additional types supported in random distributions
@@ -272,11 +271,10 @@ The exposition only type ``basic-format-string`` and its typedefs
 ``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. 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.
+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
 zero-padding. These options have been retroactively applied to C++20.
@@ -297,8 +295,8 @@ 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
 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. Reliance
-upon this should be discouraged in port...
[truncated]

Copy link
Member

@ldionne ldionne left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the patch. Overall, I believe this makes some things clearer, but I have some comments about a few places where IMO it doesn't.

Reflowing lines to a specific number of columns in our documentation has pretty low value IMO. I don't object to it in this patch since I've already reviewed the diff, but in the future please try to avoid mixing too many content changes with purely stylistic edits like line length, since that makes diffs harder to review.

Thanks!

libcxx/docs/CodingGuidelines.rst Outdated Show resolved Hide resolved
Comment on lines 10 to 14
This page contains information about 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 if libc++ is used by the toolchain.
This page is aimed at users of libc++, whereas a separate page contains documentation
aimed at vendors who build and ship libc++ as part of their toolchain.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this rewording isn't much clearer. Perhaps this can be re-evaluated once the first sentence has been fixed?

libcxx/docs/UserDocumentation.rst Outdated Show resolved Hide resolved
libcxx/docs/UserDocumentation.rst Outdated Show resolved Hide resolved
libcxx/docs/UserDocumentation.rst Show resolved Hide resolved
libcxx/docs/UserDocumentation.rst Outdated Show resolved Hide resolved
Comment on lines 239 to 240
This section documents various extensions to the C++ standard library
provided by libc++ and any information regarding how to use them.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The old formulation was clearer. The new formulation reads as-if libc++ was "providing a C++ standard library".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand why you marked this comment as resolved but didn't make any changes.

martinlicht and others added 4 commits March 25, 2025 23:30
Co-authored-by: Louis Dionne <ldionne.2@gmail.com>
Co-authored-by: Louis Dionne <ldionne.2@gmail.com>
Co-authored-by: Louis Dionne <ldionne.2@gmail.com>
Co-authored-by: Louis Dionne <ldionne.2@gmail.com>
libcxx/docs/Hardening.rst Outdated Show resolved Hide resolved
libcxx/docs/ImplementationDefinedBehavior.rst Outdated Show resolved Hide resolved
libcxx/docs/ImplementationDefinedBehavior.rst Outdated Show resolved Hide resolved
libcxx/docs/Hardening.rst Show resolved Hide resolved
libcxx/docs/UserDocumentation.rst Outdated Show resolved Hide resolved
libcxx/docs/UserDocumentation.rst Outdated Show resolved Hide resolved
libcxx/docs/UserDocumentation.rst Outdated Show resolved Hide resolved
libcxx/docs/UserDocumentation.rst Outdated Show resolved Hide resolved
martinlicht and others added 9 commits March 26, 2025 11:22
Co-authored-by: Nikolas Klauser <nikolasklauser@berlin.de>
Co-authored-by: Nikolas Klauser <nikolasklauser@berlin.de>
Co-authored-by: Nikolas Klauser <nikolasklauser@berlin.de>
Co-authored-by: Nikolas Klauser <nikolasklauser@berlin.de>
Co-authored-by: Nikolas Klauser <nikolasklauser@berlin.de>
Co-authored-by: Nikolas Klauser <nikolasklauser@berlin.de>
Co-authored-by: Nikolas Klauser <nikolasklauser@berlin.de>
Copy link
Member

@ldionne ldionne left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM w/ minor changes.

libcxx/docs/UserDocumentation.rst Outdated Show resolved Hide resolved
Comment on lines 239 to 240
This section documents various extensions to the C++ standard library
provided by libc++ and any information regarding how to use them.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand why you marked this comment as resolved but didn't make any changes.

libcxx/docs/UserDocumentation.rst Outdated Show resolved Hide resolved
@ldionne ldionne merged commit 608c85c into llvm:main May 12, 2025
14 of 20 checks passed
@llvm-ci
Copy link
Collaborator

llvm-ci commented May 12, 2025

LLVM Buildbot has detected a new failure on builder sanitizer-aarch64-linux-bootstrap-hwasan running on sanitizer-buildbot12 while building libcxx at step 2 "annotate".

Full details are available at: https://lab.llvm.org/buildbot/#/builders/55/builds/11223

Here is the relevant piece of the build log for the reference
Step 2 (annotate) failure: 'python ../sanitizer_buildbot/sanitizers/zorg/buildbot/builders/sanitizers/buildbot_selector.py' (failure)
...
llvm-lit: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/utils/lit/lit/llvm/config.py:520: note: using lld-link: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/lld-link
llvm-lit: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/utils/lit/lit/llvm/config.py:520: note: using ld64.lld: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/ld64.lld
llvm-lit: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/utils/lit/lit/llvm/config.py:520: note: using wasm-ld: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/wasm-ld
llvm-lit: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/utils/lit/lit/llvm/config.py:520: note: using ld.lld: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/ld.lld
llvm-lit: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/utils/lit/lit/llvm/config.py:520: note: using lld-link: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/lld-link
llvm-lit: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/utils/lit/lit/llvm/config.py:520: note: using ld64.lld: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/ld64.lld
llvm-lit: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/utils/lit/lit/llvm/config.py:520: note: using wasm-ld: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/wasm-ld
llvm-lit: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/utils/lit/lit/main.py:72: note: The test suite configuration requested an individual test timeout of 0 seconds but a timeout of 900 seconds was requested on the command line. Forcing timeout to be 900 seconds.
-- Testing: 87214 tests, 72 workers --
Testing:  0.. 10.. 20.. 30.. 40.. 50.. 
FAIL: LLVM :: ExecutionEngine/JITLink/x86-64/COFF_directive_alternatename_fail.s (52721 of 87214)
******************** TEST 'LLVM :: ExecutionEngine/JITLink/x86-64/COFF_directive_alternatename_fail.s' FAILED ********************
Exit Code: 1

Command Output (stderr):
--
/home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/llvm-mc -filetype=obj -triple=x86_64-windows-msvc /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/test/ExecutionEngine/JITLink/x86-64/COFF_directive_alternatename_fail.s -o /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/test/ExecutionEngine/JITLink/x86-64/Output/COFF_directive_alternatename_fail.s.tmp # RUN: at line 1
+ /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/llvm-mc -filetype=obj -triple=x86_64-windows-msvc /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/test/ExecutionEngine/JITLink/x86-64/COFF_directive_alternatename_fail.s -o /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/test/ExecutionEngine/JITLink/x86-64/Output/COFF_directive_alternatename_fail.s.tmp
not /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/llvm-jitlink -noexec /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/test/ExecutionEngine/JITLink/x86-64/Output/COFF_directive_alternatename_fail.s.tmp 2>&1 | /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/FileCheck /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/test/ExecutionEngine/JITLink/x86-64/COFF_directive_alternatename_fail.s # RUN: at line 2
+ not /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/llvm-jitlink -noexec /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/test/ExecutionEngine/JITLink/x86-64/Output/COFF_directive_alternatename_fail.s.tmp
+ /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/FileCheck /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/test/ExecutionEngine/JITLink/x86-64/COFF_directive_alternatename_fail.s

--

********************
Testing:  0.. 10.. 20.. 30.. 40.. 50.. 60.. 70.. 80.. 90.. 
Slowest Tests:
--------------------------------------------------------------------------
59.99s: Clang :: Driver/fsanitize.c
41.31s: Clang :: Preprocessor/riscv-target-features.c
38.48s: Clang :: Driver/arm-cortex-cpus-2.c
37.68s: Clang :: Driver/arm-cortex-cpus-1.c
35.78s: LLVM :: CodeGen/AMDGPU/sched-group-barrier-pipeline-solver.mir
34.03s: Clang :: OpenMP/target_defaultmap_codegen_01.cpp
32.38s: Clang :: OpenMP/target_update_codegen.cpp
30.27s: Clang :: Preprocessor/arm-target-features.c
30.11s: LLVM :: CodeGen/RISCV/attributes.ll
29.12s: Clang :: Preprocessor/aarch64-target-features.c
25.15s: Clang :: Driver/linux-ld.c
24.70s: Clang :: Preprocessor/predefined-arch-macros.c
24.47s: Clang :: Driver/clang_f_opts.c
24.14s: LLVM :: CodeGen/ARM/build-attributes.ll
23.83s: LLVM :: tools/llvm-reduce/parallel-workitem-kill.ll
23.72s: Clang :: Driver/cl-options.c
21.79s: Clang :: Driver/x86-target-features.c
20.15s: Clang :: CodeGen/AArch64/sve-intrinsics/acle_sve_reinterpret.c
19.25s: Clang :: Analysis/a_flaky_crash.cpp
18.80s: Clang :: Driver/debug-options.c

Step 11 (stage2/hwasan check) failure: stage2/hwasan check (failure)
...
llvm-lit: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/utils/lit/lit/llvm/config.py:520: note: using lld-link: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/lld-link
llvm-lit: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/utils/lit/lit/llvm/config.py:520: note: using ld64.lld: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/ld64.lld
llvm-lit: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/utils/lit/lit/llvm/config.py:520: note: using wasm-ld: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/wasm-ld
llvm-lit: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/utils/lit/lit/llvm/config.py:520: note: using ld.lld: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/ld.lld
llvm-lit: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/utils/lit/lit/llvm/config.py:520: note: using lld-link: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/lld-link
llvm-lit: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/utils/lit/lit/llvm/config.py:520: note: using ld64.lld: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/ld64.lld
llvm-lit: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/utils/lit/lit/llvm/config.py:520: note: using wasm-ld: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/wasm-ld
llvm-lit: /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/utils/lit/lit/main.py:72: note: The test suite configuration requested an individual test timeout of 0 seconds but a timeout of 900 seconds was requested on the command line. Forcing timeout to be 900 seconds.
-- Testing: 87214 tests, 72 workers --
Testing:  0.. 10.. 20.. 30.. 40.. 50.. 
FAIL: LLVM :: ExecutionEngine/JITLink/x86-64/COFF_directive_alternatename_fail.s (52721 of 87214)
******************** TEST 'LLVM :: ExecutionEngine/JITLink/x86-64/COFF_directive_alternatename_fail.s' FAILED ********************
Exit Code: 1

Command Output (stderr):
--
/home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/llvm-mc -filetype=obj -triple=x86_64-windows-msvc /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/test/ExecutionEngine/JITLink/x86-64/COFF_directive_alternatename_fail.s -o /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/test/ExecutionEngine/JITLink/x86-64/Output/COFF_directive_alternatename_fail.s.tmp # RUN: at line 1
+ /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/llvm-mc -filetype=obj -triple=x86_64-windows-msvc /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/test/ExecutionEngine/JITLink/x86-64/COFF_directive_alternatename_fail.s -o /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/test/ExecutionEngine/JITLink/x86-64/Output/COFF_directive_alternatename_fail.s.tmp
not /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/llvm-jitlink -noexec /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/test/ExecutionEngine/JITLink/x86-64/Output/COFF_directive_alternatename_fail.s.tmp 2>&1 | /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/FileCheck /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/test/ExecutionEngine/JITLink/x86-64/COFF_directive_alternatename_fail.s # RUN: at line 2
+ not /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/llvm-jitlink -noexec /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/test/ExecutionEngine/JITLink/x86-64/Output/COFF_directive_alternatename_fail.s.tmp
+ /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm_build_hwasan/bin/FileCheck /home/b/sanitizer-aarch64-linux-bootstrap-hwasan/build/llvm-project/llvm/test/ExecutionEngine/JITLink/x86-64/COFF_directive_alternatename_fail.s

--

********************
Testing:  0.. 10.. 20.. 30.. 40.. 50.. 60.. 70.. 80.. 90.. 
Slowest Tests:
--------------------------------------------------------------------------
59.99s: Clang :: Driver/fsanitize.c
41.31s: Clang :: Preprocessor/riscv-target-features.c
38.48s: Clang :: Driver/arm-cortex-cpus-2.c
37.68s: Clang :: Driver/arm-cortex-cpus-1.c
35.78s: LLVM :: CodeGen/AMDGPU/sched-group-barrier-pipeline-solver.mir
34.03s: Clang :: OpenMP/target_defaultmap_codegen_01.cpp
32.38s: Clang :: OpenMP/target_update_codegen.cpp
30.27s: Clang :: Preprocessor/arm-target-features.c
30.11s: LLVM :: CodeGen/RISCV/attributes.ll
29.12s: Clang :: Preprocessor/aarch64-target-features.c
25.15s: Clang :: Driver/linux-ld.c
24.70s: Clang :: Preprocessor/predefined-arch-macros.c
24.47s: Clang :: Driver/clang_f_opts.c
24.14s: LLVM :: CodeGen/ARM/build-attributes.ll
23.83s: LLVM :: tools/llvm-reduce/parallel-workitem-kill.ll
23.72s: Clang :: Driver/cl-options.c
21.79s: Clang :: Driver/x86-target-features.c
20.15s: Clang :: CodeGen/AArch64/sve-intrinsics/acle_sve_reinterpret.c
19.25s: Clang :: Analysis/a_flaky_crash.cpp
18.80s: Clang :: Driver/debug-options.c


Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
libc++ libc++ C++ Standard Library. Not GNU libstdc++. Not libc++abi.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants
Morty Proxy This is a proxified and sanitized view of the page, visit original site.