[libcxx-commits] [libcxx] [libc++] Documentation for _LIBCPP_REMOVE_TRANSITIVE_INCLUDES (PR #130560)

[Louis Dionne via libcxx-commits]

https://github.com/ldionne updated https://github.com/llvm/llvm-project/pull/130560

>From a705cfc897ae392e1d754e29d782914b2c04c592 Mon Sep 17 00:00:00 2001
From: Martin Licht <37779541+martinlicht at users.noreply.github.com>
Date: Mon, 10 Mar 2025 09:04:31 +0100
Subject: [PATCH 1/2] Update UserDocumentation.rst

Add _LIBCPP_REMOVE_TRANSITIVE_INCLUDES to the list of configuration macros
---
 libcxx/docs/UserDocumentation.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/libcxx/docs/UserDocumentation.rst b/libcxx/docs/UserDocumentation.rst
index 2c1bc1373659c..b55651a62ec5e 100644
--- a/libcxx/docs/UserDocumentation.rst
+++ b/libcxx/docs/UserDocumentation.rst
@@ -128,6 +128,24 @@ 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
+  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 any existing
+  codebase that implicitly relies on standard headers providing any definitions
+  not explicitly required by the standard.
+
+  The primary motivation for this configuration macro is to improve compilation
+  times. In most standard library implementations, header files include more
+  definitions than officially required because the implementation details give rise
+  to internal dependencies. The common practice is to have the standard headers
+  internally include other standard headers, but this generally results in
+  increased compilation overhead. This configuration option attempts to mitigate
+  this problem by avoiding such unnecessary inclusions. In addition, compiling
+  a codebase with this macro may improve maintainability by identifying
+  missing standard header inclusions.
+
 **_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

>From 2c9f0a9b9c8cbad805884c14fe4cc2a58ced3790 Mon Sep 17 00:00:00 2001
From: Louis Dionne <ldionne.2 at gmail.com>
Date: Wed, 19 Mar 2025 09:33:44 -0400
Subject: [PATCH 2/2] Minor rewording

---
 libcxx/docs/UserDocumentation.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/libcxx/docs/UserDocumentation.rst b/libcxx/docs/UserDocumentation.rst
index b55651a62ec5e..469a26b90bee8 100644
--- a/libcxx/docs/UserDocumentation.rst
+++ b/libcxx/docs/UserDocumentation.rst
@@ -132,9 +132,9 @@ 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 any existing
-  codebase that implicitly relies on standard headers providing any definitions
-  not explicitly required by the standard.
+  the standard. Please notice that defining this macro might break existing codebases
+  that implicitly rely on standard headers providing definitions not explicitly
+  required by the standard.
 
   The primary motivation for this configuration macro is to improve compilation
   times. In most standard library implementations, header files include more