[libc++] Reduces the number of transitive includes.
This defines a new policy for removal of transitive includes.
The goal of the policy it to make it relatively easy to remove
headers when needed, but avoid breaking developers using and
vendors shipping libc++.
The method used is to guard transitive includes based on the
C++ language version. For the upcoming C++23 we can remove
headers when we want, but for other language versions we try
to keep it to a minimum.
In this code the transitive include of `<chrono>` is removed
since D128577 introduces a header cycle between `<format>`
and `<chrono>`. This cycle is indirectly required by the
Standard. Our cycle dependency tool basically is a grep based
tool, so it needs some hints to ignore cycles. With the input
of our transitive include tests we can create a better tool.
However that's out of the scope of this patch.
Note the flag `_LIBCPP_REMOVE_TRANSITIVE_INCLUDES` remains
unchanged. So users can still opt-out of transitives includes
entirely.
Reviewed By: #libc, ldionne, philnik
Differential Revision: https://reviews.llvm.org/D132284
NOKEYCHECK=True
GitOrigin-RevId: 8ff2d6af6906261567d8c10be62711ce899fb485
diff --git a/docs/DesignDocs/HeaderRemovalPolicy.rst b/docs/DesignDocs/HeaderRemovalPolicy.rst
new file mode 100644
index 0000000..7694708
--- /dev/null
+++ b/docs/DesignDocs/HeaderRemovalPolicy.rst
@@ -0,0 +1,74 @@
+=====================
+Header Removal Policy
+=====================
+
+Policy
+------
+
+Libc++ is in the process of splitting larger headers into smaller modular
+headers. This makes it possible to remove these large headers from other
+headers. For example, instead of including ``<algorithm>`` entirely it is
+possible to only include the headers for the algorithms used. When the
+Standard indirectly adds additional header includes, using the smaller headers
+aids reducing the growth of top-level headers. For example ``<atomic>`` uses
+``std::chrono::nanoseconds`` and included ``<chrono>``. In C++20 ``<chrono>``
+requires ``<format>`` which adds several other headers (like ``<string>``,
+``<optional>``, ``<tuple>``) which are not needed in ``<atomic>``.
+
+The benefit of using minimal headers is that the size of libc++'s top-level
+headers becomes smaller. This improves the compilation time when users include
+a top-level header. It also avoids header inclusion cycles and makes it easier
+to port headers to platforms with reduced functionality.
+
+A disadvantage is that users unknowingly depend on these transitive includes.
+Thus removing an include might break their build after upgrading a newer
+version of libc++. For example, ``<algorithm>`` is often forgotten but using
+algorithms will still work through those transitive includes. This problem is
+solved by modules, however in practice most people do not use modules (yet).
+
+To ease the removal of transitive includes in libc++, libc++ will remove
+unnecessary transitive includes in newly supported C++ versions. This means
+that users will have to fix their missing includes in order to upgrade to a
+newer version of the Standard. Libc++ also reserves the right to remove
+transitive includes at any other time, however new language versions will be
+used as a convenient way to perform bulk removals of transitive includes.
+
+For libc++ developers, this means that any transitive include removal must be
+guarded by something of the form:
+
+.. code-block:: cpp
+
+ #if !defined(_LIBCPP_REMOVE_TRANSITIVE_INCLUDES) && _LIBCPP_STD_VER <= 20
+ # include <algorithm>
+ # include <iterator>
+ # include <utility>
+ #endif
+
+When users define ``_LIBCPP_REMOVE_TRANSITIVE_INCLUDES``, libc++ will not
+include transitive headers, regardless of the language version. This can be
+useful for users to aid the transition to a newer language version, or by users
+who simply want to make sure they include what they use in their code.
+
+One of the issues for libc++ with transitive includes is that these includes
+may create dependency cycles and cause the validation script
+``libcxx/utils/graph_header_deps.py`` to have false positives. To ignore an
+include from the validation script, add a comment containing ``IGNORE-CYCLE``.
+This should only be used when there is a cycle and it has been verified it is a
+false positive.
+
+.. code-block:: cpp
+
+ #if !defined(_LIBCPP_REMOVE_TRANSITIVE_INCLUDES) && _LIBCPP_STD_VER <= 17
+ # include <chrono> // IGNORE-CYCLE due to <format>
+ #endif
+
+
+Rationale
+---------
+
+Removing headers is not only an issue for software developers, but also for
+vendors. When a vendor updates libc++ several of their upstream packages might
+fail to compile, forcing them to fix these packages or file a bug with their
+upstream packages. Usually upgrading software to a new language standard is
+done explicitly by software developers. This means they most likely will
+discover and fix the missing includes, lessening the burden for the vendors.
diff --git a/docs/ReleaseNotes.rst b/docs/ReleaseNotes.rst
index a89d4cd..fda4b69 100644
--- a/docs/ReleaseNotes.rst
+++ b/docs/ReleaseNotes.rst
@@ -45,6 +45,24 @@
Deprecations and Removals
-------------------------
+- Several incidental transitive includes have been removed from libc++. Those
+ includes are removed based on the language version used. Incidental transitive
+ inclusions of the following headers have been removed:
+
+ - C++20: ``chrono``
+ - C++2b: ``algorithm``, ``array``, ``atomic``, ``bit``, ``chrono``,
+ ``climits``, ``cmath``, ``compare``, ``concepts``, ``cstdlib``,
+ ``cstring``, ``ctime``, ``exception``, ``functional``,
+ ``initializer_list``, ``iosfwd``, ``iterator``, ``memory``, ``new``,
+ ``optional``, ``ratio``, ``stdexcept``, ``tuple``, ``typeinfo``,
+ ``unordered_map``, ``utility``, ``variant``, ``vector``.
+
+ Users can also remove all incidental transitive includes by defining
+ ``_LIBCPP_REMOVE_TRANSITIVE_INCLUDES`` regardless of the language version
+ in use. Note that in the future, libc++ reserves the right to remove
+ incidental transitive includes more aggressively, in particular regardless
+ of the language version in use.
+
Upcoming Deprecations and Removals
----------------------------------
diff --git a/docs/index.rst b/docs/index.rst
index 71674e7..4964d13 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -175,6 +175,7 @@
DesignDocs/ExtendedCXX03Support
DesignDocs/FeatureTestMacros
DesignDocs/FileTimeType
+ DesignDocs/HeaderRemovalPolicy
DesignDocs/NoexceptPolicy
DesignDocs/ThreadingSupportAPI
DesignDocs/UniquePtrTrivialAbi