shylie/llvm-project
1
0
Fork 0
Code Issues Pull Requests Actions 6 Packages Projects Releases Wiki Activity

[libc++] Stabilize transitive includes for C++23 (#134143)

Browse Source 
Our mechanism to retain transitive includes for backwards compatibility
was previously not taking into account C++23: this means that users on
C++23 would not get any protection against the removal of transitive
includes. This was fine when C++23 was still not used widely and it
allowed us to make build time improvements for such "bleeding edge"
users.

It also didn't take into account the larger topic of providing a
backwards compatible set of declarations, which is the real goal
of this mechanism.

However, now that C++23 is used pretty widely, we should start providing
transitive includes backwards compatibility for users of that language mode
too. This patch documents that requirement and mentions backwards compatibility
of the set of declarations as well, meaning we may also add internal headers in
the `_LIBCPP_REMOVE_TRANSITIVE_INCLUDES` blocks going forward.

There are no actual changes to the code since we haven't removed
transitive includes since the last release. However, starting now,
we should guard any removal of transitive includes behind

    #if !defined(_LIBCPP_REMOVE_TRANSITIVE_INCLUDES) && _LIBCPP_STD_VER <= 23

instead of

    #if !defined(_LIBCPP_REMOVE_TRANSITIVE_INCLUDES) && _LIBCPP_STD_VER <= 20
This commit is contained in:
Louis Dionne 2025-08-28 18:11:13 -04:00 committed by GitHub
parent 810f06ec3e
commit 1213d4ece0
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 24 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
libcxx/docs/DesignDocs/HeaderRemovalPolicy.rst
View File

@ -22,9 +22,10 @@ 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).
version of libc++ by reducing the set of declarations provided by a header.
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
@ -33,21 +34,34 @@ 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:
However, libc++ intends not to gratuitously break users on stable versions of
the Standard. Hence, we intend to maintain backwards compatibility of the
declarations we provide in a header, within reason. We reserve the right to
break such backwards compatibility in the future, however we will strive to
do it in a user-friendly way, again within reason. For libc++ developers, this
means that any transitive include removal of a public header must be guarded by
something of the form:
.. code-block:: cpp
#if !defined(_LIBCPP_REMOVE_TRANSITIVE_INCLUDES) && _LIBCPP_STD_VER <= 20
#if !defined(_LIBCPP_REMOVE_TRANSITIVE_INCLUDES) && _LIBCPP_STD_VER <= 23
# 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.
Occasionally, private headers may also be included transitively for backwards
compatibility in the same manner. We currently strive to provide backwards
compatibility on the set of declarations provided by a header in all Standard
modes starting with **C++23**. Note that this is very difficult to actually
enforce, so this is done only on a best effort basis.
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. However, note that defining this
macro means that the set of declarations and transitive includes provided by the library
may change from release to release, which can break your code.
Rationale